feat(review): add versioned JSON comparison reports
This commit is contained in:
parent
d8f764c7fe
commit
248f6bcff7
2 changed files with 2312 additions and 43 deletions
206
docs/diff-report-v1.schema.json
Normal file
206
docs/diff-report-v1.schema.json
Normal file
|
|
@ -0,0 +1,206 @@
|
|||
{
|
||||
"$schema": "https://json-schema.org/draft/2020-12/schema",
|
||||
"title": "Klamath diff report version 1",
|
||||
"description": "Object-profile comparison evidence, not a layout serialization. Unknown additional fields are permitted for compatible extensions.",
|
||||
"type": "object",
|
||||
"required": ["schema_version", "kind", "producer", "comparison_profile", "inputs", "scope", "coordinates", "status", "result", "exit_code", "summary", "report_selection", "layer_legend", "library_changes", "layer_name_changes", "cell_changes", "hierarchy", "diagnostics"],
|
||||
"properties": {
|
||||
"schema_version": {"const": 1},
|
||||
"kind": {"const": "diff"},
|
||||
"producer": {
|
||||
"type": "object", "required": ["name", "version"],
|
||||
"properties": {"name": {"const": "klamath"}, "version": {"type": "string"}}
|
||||
},
|
||||
"comparison_profile": {"type": "string"},
|
||||
"inputs": {
|
||||
"type": "object", "required": ["old", "new"],
|
||||
"properties": {"old": {"$ref": "#/$defs/input"}, "new": {"$ref": "#/$defs/input"}}
|
||||
},
|
||||
"scope": {
|
||||
"type": "object", "required": ["top", "cell", "layer"],
|
||||
"properties": {"top": {"type": ["string", "null"]}, "cell": {"type": ["string", "null"]}, "layer": {"$ref": "#/$defs/nullableLayer"}}
|
||||
},
|
||||
"coordinates": {
|
||||
"type": "object", "required": ["unit", "frame", "bounds"],
|
||||
"properties": {"unit": {"const": "database_unit"}, "frame": {"const": "cell_local"}, "bounds": {"const": "coordinate_envelope"}}
|
||||
},
|
||||
"status": {"enum": ["complete", "incomplete", "failed"]},
|
||||
"result": {"enum": ["equal", "different", "unknown"]},
|
||||
"exit_code": {"enum": [0, 1, 2]},
|
||||
"summary": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/summary"}]},
|
||||
"report_selection": {"$ref": "#/$defs/selection"},
|
||||
"layer_legend": {
|
||||
"type": "array", "items": {
|
||||
"type": "object", "required": ["layer", "name"],
|
||||
"properties": {"layer": {"$ref": "#/$defs/layer"}, "name": {"type": "string"}}
|
||||
}
|
||||
},
|
||||
"library_changes": {"type": "array", "items": {"$ref": "#/$defs/libraryChange"}},
|
||||
"layer_name_changes": {
|
||||
"type": "array", "items": {
|
||||
"type": "object", "required": ["layer", "before", "after"],
|
||||
"properties": {"layer": {"$ref": "#/$defs/layer"}, "before": {"type": ["string", "null"]}, "after": {"type": ["string", "null"]}}
|
||||
}
|
||||
},
|
||||
"cell_changes": {"type": "array", "items": {"$ref": "#/$defs/cellChange"}},
|
||||
"hierarchy": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/graph"}]},
|
||||
"diagnostics": {"type": "array", "items": {"$ref": "#/$defs/diagnostic"}}
|
||||
},
|
||||
"allOf": [
|
||||
{
|
||||
"if": {"properties": {"status": {"const": "complete"}}},
|
||||
"then": {
|
||||
"properties": {"result": {"enum": ["equal", "different"]}, "summary": {"$ref": "#/$defs/summary", "properties": {"counts": {"const": "exact"}}}, "diagnostics": {"maxItems": 0}},
|
||||
"if": {"properties": {"result": {"const": "equal"}}},
|
||||
"then": {"properties": {"exit_code": {"const": 0}}},
|
||||
"else": {"properties": {"exit_code": {"const": 1}}}
|
||||
},
|
||||
"else": {"properties": {"exit_code": {"const": 2}, "diagnostics": {"minItems": 1}}}
|
||||
},
|
||||
{
|
||||
"if": {"properties": {"status": {"const": "incomplete"}}},
|
||||
"then": {"properties": {"result": {"enum": ["different", "unknown"]}, "summary": {"$ref": "#/$defs/summary", "properties": {"counts": {"const": "observed"}}}}}
|
||||
},
|
||||
{
|
||||
"if": {"properties": {"status": {"const": "failed"}}},
|
||||
"then": {"properties": {"result": {"const": "unknown"}, "summary": {"type": "null"}, "library_changes": {"maxItems": 0}, "layer_name_changes": {"maxItems": 0}, "cell_changes": {"maxItems": 0}, "hierarchy": {"type": "null"}}}
|
||||
}
|
||||
],
|
||||
"$defs": {
|
||||
"decimal": {"type": "string", "pattern": "^(0|[1-9][0-9]*)$"},
|
||||
"hex": {"type": "string", "pattern": "^0x([0-9a-f]{2})*$"},
|
||||
"uint16": {"type": "integer", "minimum": 0, "maximum": 65535},
|
||||
"int32": {"type": "integer", "minimum": -2147483648, "maximum": 2147483647},
|
||||
"layer": {
|
||||
"type": "object", "required": ["number", "purpose"],
|
||||
"properties": {"number": {"$ref": "#/$defs/uint16"}, "purpose": {"$ref": "#/$defs/uint16"}}
|
||||
},
|
||||
"nullableLayer": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/layer"}]},
|
||||
"point": {"type": "array", "minItems": 2, "maxItems": 2, "items": {"$ref": "#/$defs/int32"}},
|
||||
"fields": {"type": "array", "items": {"$ref": "#/$defs/field"}},
|
||||
"field": {
|
||||
"type": "object", "required": ["tag", "name", "encoding", "value", "payload_hex"],
|
||||
"properties": {
|
||||
"tag": {"$ref": "#/$defs/uint16"}, "name": {"type": "string"},
|
||||
"encoding": {"enum": ["xy", "uint16", "int16", "int32", "bits", "real8", "ascii", "none", "bytes"]},
|
||||
"payload_hex": {"$ref": "#/$defs/hex"},
|
||||
"value": {"type": ["array", "string", "null"]}
|
||||
},
|
||||
"allOf": [
|
||||
{"if": {"properties": {"encoding": {"const": "xy"}}}, "then": {"properties": {"value": {"type": "array", "items": {"$ref": "#/$defs/point"}}}}},
|
||||
{"if": {"properties": {"encoding": {"enum": ["uint16", "bits"]}}}, "then": {"properties": {"value": {"type": "array", "items": {"$ref": "#/$defs/uint16"}}}}},
|
||||
{"if": {"properties": {"encoding": {"const": "int16"}}}, "then": {"properties": {"value": {"type": "array", "items": {"type": "integer", "minimum": -32768, "maximum": 32767}}}}},
|
||||
{"if": {"properties": {"encoding": {"const": "int32"}}}, "then": {"properties": {"value": {"type": "array", "items": {"$ref": "#/$defs/int32"}}}}},
|
||||
{"if": {"properties": {"encoding": {"const": "real8"}}}, "then": {"properties": {"value": {"type": "array", "items": {"type": ["number", "null"]}}}}},
|
||||
{"if": {"properties": {"encoding": {"const": "ascii"}}}, "then": {"properties": {"value": {"type": ["string", "null"]}}}},
|
||||
{"if": {"properties": {"encoding": {"enum": ["none", "bytes"]}}}, "then": {"properties": {"value": {"type": "null"}}}}
|
||||
]
|
||||
},
|
||||
"input": {
|
||||
"type": "object", "required": ["path", "path_encoded_hex", "present", "units"],
|
||||
"properties": {
|
||||
"path": {"type": ["string", "null"]},
|
||||
"path_encoded_hex": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/hex"}]},
|
||||
"present": {"type": ["boolean", "null"]},
|
||||
"units": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/field"}]}
|
||||
}
|
||||
},
|
||||
"summary": {
|
||||
"type": "object", "required": ["counts", "changed_cells", "removed_objects", "added_objects", "layer_name_changes", "library_field_changes"],
|
||||
"properties": {
|
||||
"counts": {"enum": ["exact", "observed"]},
|
||||
"changed_cells": {"$ref": "#/$defs/decimal"}, "removed_objects": {"$ref": "#/$defs/decimal"}, "added_objects": {"$ref": "#/$defs/decimal"},
|
||||
"layer_name_changes": {"$ref": "#/$defs/decimal"}, "library_field_changes": {"$ref": "#/$defs/decimal"}
|
||||
}
|
||||
},
|
||||
"selection": {
|
||||
"type": "object", "required": ["cell", "layer", "max_objects", "truncated", "filtered_cells", "filtered_objects", "limited_objects", "emitted_objects"],
|
||||
"properties": {
|
||||
"cell": {"type": ["string", "null"]}, "layer": {"$ref": "#/$defs/nullableLayer"},
|
||||
"max_objects": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/decimal"}]}, "truncated": {"type": "boolean"},
|
||||
"filtered_cells": {"$ref": "#/$defs/decimal"}, "filtered_objects": {"$ref": "#/$defs/decimal"},
|
||||
"limited_objects": {"$ref": "#/$defs/decimal"}, "emitted_objects": {"$ref": "#/$defs/decimal"}
|
||||
}
|
||||
},
|
||||
"libraryChange": {
|
||||
"oneOf": [
|
||||
{
|
||||
"type": "object", "required": ["field", "tag", "before", "after"],
|
||||
"properties": {"field": {"const": "presence"}, "tag": {"type": "null"}, "before": {"type": "boolean"}, "after": {"type": "boolean"}}
|
||||
},
|
||||
{
|
||||
"type": "object", "required": ["field", "tag", "before", "after"],
|
||||
"properties": {"field": {"type": "string"}, "tag": {"$ref": "#/$defs/uint16"}, "before": {"$ref": "#/$defs/fields"}, "after": {"$ref": "#/$defs/fields"}}
|
||||
}
|
||||
]
|
||||
},
|
||||
"source": {
|
||||
"type": "object", "required": ["side", "byte_offset", "end_offset"],
|
||||
"properties": {"side": {"enum": ["old", "new"]}, "byte_offset": {"$ref": "#/$defs/decimal"}, "end_offset": {"$ref": "#/$defs/decimal"}}
|
||||
},
|
||||
"property": {
|
||||
"type": "object", "required": ["attribute", "value", "payload_hex"],
|
||||
"properties": {"attribute": {"$ref": "#/$defs/uint16"}, "value": {"type": ["string", "null"]}, "payload_hex": {"$ref": "#/$defs/hex"}}
|
||||
},
|
||||
"object": {
|
||||
"type": "object", "required": ["id", "kind", "tag", "source", "layer", "bounds", "target", "origin", "width", "counts", "fields", "properties"],
|
||||
"properties": {
|
||||
"id": {"type": "string"}, "kind": {"type": "string"}, "tag": {"$ref": "#/$defs/uint16"}, "source": {"$ref": "#/$defs/source"},
|
||||
"layer": {"$ref": "#/$defs/nullableLayer"},
|
||||
"bounds": {"oneOf": [{"type": "null"}, {"type": "array", "minItems": 4, "maxItems": 4, "items": {"$ref": "#/$defs/int32"}}]},
|
||||
"target": {"type": ["string", "null"]}, "origin": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/point"}]},
|
||||
"width": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/int32"}]},
|
||||
"counts": {"oneOf": [{"type": "null"}, {"type": "array", "minItems": 2, "maxItems": 2, "items": {"type": "integer", "minimum": 1, "maximum": 32767}}]},
|
||||
"fields": {"$ref": "#/$defs/fields"}, "properties": {"type": "array", "items": {"$ref": "#/$defs/property"}}
|
||||
}
|
||||
},
|
||||
"replacement": {
|
||||
"type": "object", "required": ["removed", "added", "match_rule", "explanation", "field_changes", "properties_changed"],
|
||||
"properties": {
|
||||
"removed": {"type": "string"}, "added": {"type": "string"}, "match_rule": {"type": "string"}, "explanation": {"type": "string"}, "properties_changed": {"type": "boolean"},
|
||||
"field_changes": {"type": "array", "items": {
|
||||
"type": "object", "required": ["tag", "before", "after"],
|
||||
"properties": {"tag": {"$ref": "#/$defs/uint16"}, "before": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/field"}]}, "after": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/field"}]}}
|
||||
}}
|
||||
}
|
||||
},
|
||||
"cellSide": {
|
||||
"oneOf": [{"type": "null"}, {
|
||||
"type": "object", "required": ["byte_offset", "attributes"],
|
||||
"properties": {"byte_offset": {"$ref": "#/$defs/decimal"}, "attributes": {"$ref": "#/$defs/fields"}}
|
||||
}]
|
||||
},
|
||||
"cellChange": {
|
||||
"type": "object", "required": ["name", "before", "after", "attributes_changed", "removed", "added", "replacements"],
|
||||
"properties": {
|
||||
"name": {"type": "string"}, "before": {"$ref": "#/$defs/cellSide"}, "after": {"$ref": "#/$defs/cellSide"}, "attributes_changed": {"type": "boolean"},
|
||||
"removed": {"type": "array", "items": {"$ref": "#/$defs/object"}}, "added": {"type": "array", "items": {"$ref": "#/$defs/object"}},
|
||||
"replacements": {"type": "array", "items": {"$ref": "#/$defs/replacement"}}
|
||||
}
|
||||
},
|
||||
"diagnostic": {
|
||||
"type": "object", "required": ["code", "severity", "message", "side", "byte_offset", "cell", "layer", "target"],
|
||||
"properties": {
|
||||
"code": {"type": "string"}, "severity": {"const": "error"}, "message": {"type": "string"}, "side": {"enum": ["old", "new", null]},
|
||||
"byte_offset": {"oneOf": [{"type": "null"}, {"$ref": "#/$defs/decimal"}]}, "cell": {"type": ["string", "null"]},
|
||||
"layer": {"$ref": "#/$defs/nullableLayer"}, "target": {"type": ["string", "null"]}
|
||||
}
|
||||
},
|
||||
"graph": {
|
||||
"type": "object", "required": ["nodes", "edges"],
|
||||
"properties": {
|
||||
"nodes": {"type": "array", "items": {
|
||||
"type": "object", "required": ["cell", "before", "after", "change"],
|
||||
"properties": {
|
||||
"cell": {"type": "string"}, "before": {"enum": ["included", "outside_scope", "unresolved", "absent"]}, "after": {"enum": ["included", "outside_scope", "unresolved", "absent"]},
|
||||
"change": {"enum": ["direct", "affected", "unchanged"]}
|
||||
}
|
||||
}},
|
||||
"edges": {"type": "array", "items": {
|
||||
"type": "object", "required": ["parent", "target", "before_count", "after_count", "reference_changed"],
|
||||
"properties": {"parent": {"type": "string"}, "target": {"type": "string"}, "before_count": {"$ref": "#/$defs/decimal"}, "after_count": {"$ref": "#/$defs/decimal"}, "reference_changed": {"type": "boolean"}}
|
||||
}}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
185
docs/diff-reports.md
Normal file
185
docs/diff-reports.md
Normal file
|
|
@ -0,0 +1,185 @@
|
|||
# Machine-readable diff reports
|
||||
|
||||
```sh
|
||||
klamath diff before.gds after.gds --format json > report.json
|
||||
klamath diff before.gds after.gds --format json --hierarchy graph
|
||||
klamath diff before.gds after.gds --format json --top CHIP --layer 1/0
|
||||
```
|
||||
|
||||
The command writes one UTF-8 JSON document followed by a newline to stdout.
|
||||
Comparison diagnostics belong to that document. Output write failures are
|
||||
reported on stderr and return 2; interrupted output is not a valid report.
|
||||
JSON output currently belongs to `diff`; `dump`, `hierarchy`, and the Git
|
||||
external driver retain their existing text interfaces. No external process is
|
||||
used to produce a report.
|
||||
|
||||
The [version 1 JSON Schema](diff-report-v1.schema.json) defines the structure.
|
||||
[Golden reports](../tests/golden/report-geometry.json) illustrate complete
|
||||
evidence; other `report-*.json` goldens cover equality, metadata, incomplete
|
||||
comparison, and failure. Their producer version is replaced with `test` so
|
||||
package version changes do not alter the fixtures.
|
||||
|
||||
## Versions and determinism
|
||||
|
||||
`schema_version` describes the report structure. `comparison_profile` names the
|
||||
equality rules, currently `klamath-object-v2`. `producer.version` identifies the
|
||||
implementation. These versions are independent. Consumers interpreting equality
|
||||
must understand the comparison profile as well as the schema.
|
||||
|
||||
Compatible additions may introduce optional fields. Consumers should ignore
|
||||
unfamiliar additional fields and handle unfamiliar diagnostic codes and matching
|
||||
rules without treating them as equality. Removed fields or changed meanings
|
||||
require a new schema version. The schema intentionally permits additional fields.
|
||||
|
||||
For the same inputs, paths, options, and producer version, serialization is
|
||||
deterministic. Cells, layer pairs, fields, properties, and graph edges are sorted.
|
||||
Duplicate objects and properties remain separate occurrences. Reports contain
|
||||
no generation timestamp or required content fingerprint.
|
||||
|
||||
## Result and exit status
|
||||
|
||||
| `status` | `result` | Exit code | Interpretation |
|
||||
| --- | --- | --- | --- |
|
||||
| `complete` | `equal` | 0 | Equal under the recorded profile and scope. |
|
||||
| `complete` | `different` | 1 | Differences found. |
|
||||
| `incomplete` | `different` | 2 | Definite differences found, with comparison limitations. |
|
||||
| `incomplete` | `unknown` | 2 | Equality cannot be established. |
|
||||
| `failed` | `unknown` | 2 | No comparison result is available. |
|
||||
|
||||
Unsupported records, future metadata versions, unresolved references, and
|
||||
hierarchy cycles make the comparison incomplete. Malformed input, read errors,
|
||||
invalid scopes, and invalid command arguments produce failed reports. CI must
|
||||
check completeness as well as differences. An exit code of 1 is a normal
|
||||
comparison outcome, including when stdout is redirected to a report file.
|
||||
|
||||
Library and cell timestamps are excluded from the comparison profile. A valid,
|
||||
complete timestamp-only comparison returns 0. Raw record dumps remain available
|
||||
for examining those timestamps.
|
||||
|
||||
`summary` counts the entire scoped comparison, before display selection. Its
|
||||
`counts` is `exact` for a complete comparison and `observed` for an incomplete
|
||||
one. Failed reports have a null summary and empty change arrays. Replacement
|
||||
suggestions and affected ancestors never add to change counts.
|
||||
|
||||
## Scope, selection, and numbers
|
||||
|
||||
`scope` records the actual `top`, `cell`, and numeric `layer` selectors. Null
|
||||
means unrestricted. The complete file is parsed before applying scope, so an
|
||||
invalid record outside the selected subtree still fails the command.
|
||||
|
||||
`report_selection` records display-only `cell`, `layer`, and `max_objects`.
|
||||
JSON has no default object limit. Explicit `--max-changes N` limits the total
|
||||
number of emitted object occurrences across both sides. Removals precede
|
||||
additions within each cell. `filtered_cells`, `filtered_objects`,
|
||||
`limited_objects`, and `emitted_objects` explain evidence selection. `truncated`
|
||||
is true if filtering or a limit omits any changed cell or object. Library and
|
||||
layer-name changes, diagnostics, summaries, and the optional graph are retained.
|
||||
A replacement is emitted only when both linked objects are included.
|
||||
|
||||
All aggregate counts, limits, and byte offsets are unsigned decimal **strings**.
|
||||
This avoids loss of precision in JSON consumers using binary64 numbers.
|
||||
Coordinates, numeric tags, layer/type pairs, widths, and array dimensions are
|
||||
bounded integers represented as JSON numbers. Null means absent or unavailable;
|
||||
zero and empty arrays do not imply absence.
|
||||
|
||||
`inputs.old` and `inputs.new` contain input paths, presence, and UNITS fields.
|
||||
Presence is distinct from an empty library. The Rust API also supports absent
|
||||
Git revisions using `Document::empty_like`; no units are invented for absent
|
||||
inputs. Failed reports may have null presence and units. Argument failures can
|
||||
lack input/selection context because the command could not be parsed.
|
||||
|
||||
Paths are UTF-8 when representable. Otherwise `path` is null and
|
||||
`path_encoded_hex` preserves Rust's platform-native encoded path bytes, prefixed
|
||||
with `0x`. This is platform-dependent evidence rather than a portable path name.
|
||||
|
||||
## Change evidence
|
||||
|
||||
`library_changes` records changed header fields as typed before/after arrays.
|
||||
Library presence changes use the special field `presence`, a null tag, and
|
||||
boolean before/after values. Units are not rescaled to a common grid.
|
||||
|
||||
`layer_name_changes` records numeric pairs with before/after names. A layer
|
||||
pair is `{ "number": 1, "purpose": 0 }`, where purpose is DATATYPE, TEXTTYPE,
|
||||
BOXTYPE, or NODETYPE according to the object kind. `layer_legend` contains
|
||||
unchanged names available in the scope. Embedded annotation labels are excluded
|
||||
from ordinary object changes. A metadata rename appears once.
|
||||
|
||||
Each `cell_changes` entry has its name, nullable before/after cell records,
|
||||
attribute evidence, removed and added objects, and replacement suggestions.
|
||||
A null cell side means the cell is absent in that scope. An existing empty
|
||||
cell has a byte offset and an empty attribute array.
|
||||
|
||||
Each object retains:
|
||||
|
||||
- Its kind and numeric tag, numeric layer pair, target cell, and coordinate envelope.
|
||||
- Its original source side and byte range `[byte_offset, end_offset)`.
|
||||
- Typed field records and the sorted property multiset, including duplicates.
|
||||
- Convenience fields for text/reference origin, path/text width, and reference
|
||||
array dimensions. SREF dimensions are `[1, 1]`; the kind and retained fields
|
||||
distinguish an SREF from a one-element AREF and explicit fields from omission.
|
||||
|
||||
Coordinates are cell-local integer database units. `bounds` contains
|
||||
`[xmin, ymin, xmax, ymax]` of stored coordinates. It excludes path stroke width,
|
||||
rendered text dimensions, and recursively transformed target geometry.
|
||||
Equal envelopes do not establish geometric equality. Unit changes must be
|
||||
considered before deriving physical movements or dimensions.
|
||||
|
||||
A retained field has a numeric `tag`, convenience `name`, `encoding`, decoded
|
||||
`value`, and `payload_hex`. The numeric tag is authoritative; names are display
|
||||
aids. XY values are arrays of `[x, y]` pairs. Other numeric fields are arrays
|
||||
of their declared type. Unsupported encodings retain bytes with a null value.
|
||||
String and property values are null if their bytes are not valid UTF-8;
|
||||
`payload_hex` always preserves them without replacement characters.
|
||||
|
||||
Payloads follow the comparison profile: boundary/box rings use canonical start
|
||||
and winding, string padding is removed, and fields/properties are sorted. They
|
||||
are comparison evidence, not a verbatim serialization of the source records.
|
||||
REAL8 payload encodings are retained exactly alongside their decoded values.
|
||||
Explicit defaults and omitted fields remain distinct. Source ranges allow raw
|
||||
record inspection when original encoding or order is needed.
|
||||
|
||||
Replacement suggestions link report-local removed/added IDs, with a `match_rule`,
|
||||
typed `field_changes`, and `properties_changed`. Their explanation is optional
|
||||
for consumers to display and must not be parsed. Current matching rules are
|
||||
`unique_kind_layer_bounds`, `unique_kind_layer`, and `unique_kind_target`.
|
||||
These are explanatory matches, not persistent identity or shape equivalence.
|
||||
Ambiguous candidates stay independent removals and additions. IDs are unique
|
||||
within a report and have no meaning across reports.
|
||||
|
||||
## Diagnostics and hierarchy
|
||||
|
||||
Diagnostics have `code`, `severity`, `message`, input `side`, original byte
|
||||
offset, cell, layer, and target context. Unknown context is null. Messages are
|
||||
for display; codes and context support automation. Current limitation codes are
|
||||
`unsupported_record`, `unsupported_metadata_version`, `unresolved_reference`,
|
||||
`hierarchy_cycle`, and `scope_mismatch`. Failure codes are `invalid_input`,
|
||||
`io_error`, `invalid_scope`, and `command_error`. Fatal parser errors currently
|
||||
retain their location in the human message; their structured byte offset is
|
||||
null. Consumers must not depend on message wording.
|
||||
|
||||
`--hierarchy graph` includes the full scoped union graph of both revisions.
|
||||
Otherwise `hierarchy` is null. Nodes are keyed by cell name, with per-side
|
||||
states `included`, `outside_scope`, `unresolved`, or `absent`. Their `change`
|
||||
is `direct`, `affected` through a descendant, or `unchanged`.
|
||||
|
||||
Edges record parent, target, before/after direct placement counts, and whether
|
||||
the underlying reference records changed. AREF columns times rows contribute
|
||||
symbolically; arrays are never expanded. Counts are direct edge multiplicities,
|
||||
not recursively accumulated placements. Shared cells occur once. Removed edges
|
||||
remain visible, and ancestors are computed over the union of both revisions.
|
||||
Graph content is independent of display filters and object limits. Text depth
|
||||
limits and ASCII/Mermaid choices do not apply to JSON graphs.
|
||||
|
||||
## Development
|
||||
|
||||
`cargo test --test review` checks report semantics, CLI behavior, and versioned
|
||||
goldens. To intentionally regenerate report goldens after reviewing a contract
|
||||
change, run:
|
||||
|
||||
```sh
|
||||
KLAMATH_UPDATE_REPORT_GOLDENS=1 cargo test --test review machine_reports_match_versioned_goldens
|
||||
```
|
||||
|
||||
Schema validators can validate the goldens or actual CLI output against
|
||||
`diff-report-v1.schema.json`. Schema validation does not replace semantic checks
|
||||
such as replacement links, summary totals, or status/exit-code agreement.
|
||||
Loading…
Reference in a new issue