126 lines
6.7 KiB
Markdown
126 lines
6.7 KiB
Markdown
# JSON diff reports
|
|
|
|
Use JSON reports to automate layout review while retaining the evidence behind
|
|
a result. The [comparison rules](comparison.md) define equality; the
|
|
[version 1 JSON Schema](diff-report-v1.schema.json) defines every field.
|
|
A [complete example](../tests/golden/report-geometry.json) shows geometry changes.
|
|
|
|
```sh
|
|
pheon diff before.gds after.gds --format json > report.json
|
|
pheon diff before.gds after.gds --format json --hierarchy graph
|
|
pheon diff before.gds after.gds --format json --top CHIP --layer 1/0
|
|
```
|
|
|
|
`diff` writes one UTF-8 JSON document and a newline to stdout, including comparison
|
|
diagnostics. Output write failures go to stderr and return 2; interrupted output
|
|
is invalid. Other CLI commands retain text output.
|
|
|
|
## Check the result first
|
|
|
|
| `status` | `result` | Exit code | Meaning |
|
|
| --- | --- | --- | --- |
|
|
| `complete` | `equal` | 0 | Equal under the recorded profile and scope. |
|
|
| `complete` | `different` | 1 | Differences found. |
|
|
| `incomplete` | `different` | 2 | Definite differences, with comparison limitations. |
|
|
| `incomplete` | `unknown` | 2 | Equality cannot be established. |
|
|
| `failed` | `unknown` | 2 | No comparison result. |
|
|
|
|
A code of 1 is an expected result, including when saving a report. Unsupported
|
|
records, future metadata, unresolved references, and cycles make a comparison
|
|
incomplete. Malformed input, I/O errors, invalid scopes, and command errors fail.
|
|
|
|
`summary` covers the whole scoped comparison before display filters. Counts are
|
|
`exact` for complete results and `observed` for incomplete ones. Failed reports
|
|
have a null summary and empty change arrays. Replacement suggestions and affected
|
|
ancestors do not add to change counts.
|
|
|
|
## Scope and evidence selection
|
|
|
|
`scope` records `top`, `cell`, and numeric `layer` selectors; null means
|
|
unrestricted. The full input is parsed before scope selection.
|
|
|
|
`report_selection` records display-only cell/layer filters and `max_objects`.
|
|
JSON is unbounded by default. Explicit `--max-changes N` limits total emitted
|
|
removals plus additions, with removals first within each cell. Selection counters
|
|
`filtered_cells`, `filtered_objects`, `limited_objects`, and `emitted_objects`
|
|
explain omissions. `truncated` is true when filtering or limits omit evidence.
|
|
Library changes, layer-name changes, diagnostics, summaries, and the optional
|
|
graph remain. Replacement links appear only if both objects are emitted.
|
|
|
|
## Read values safely
|
|
|
|
Aggregate counts, limits, and byte offsets are unsigned decimal **strings** to
|
|
avoid JSON number precision loss. Coordinates, numeric tags, layer/type pairs,
|
|
widths, and array dimensions are bounded JSON numbers. Null means absent or
|
|
unavailable; zero and empty arrays remain meaningful values.
|
|
|
|
`inputs.old` and `inputs.new` record paths, presence, and UNITS. An absent revision
|
|
is distinct from an empty library. The Rust API supports absent Git revisions
|
|
with `Document::empty_like`. Failed reports may lack presence, units, or argument
|
|
context. Non-UTF-8 paths use null `path` and `path_encoded_hex`: `0x`-prefixed
|
|
platform-native Rust path bytes, not a portable filename encoding.
|
|
|
|
## Interpret changes
|
|
|
|
| Section | Evidence |
|
|
| --- | --- |
|
|
| `library_changes` | Typed before/after header fields, including unscaled UNITS. Presence changes use a null tag and boolean values. |
|
|
| `layer_name_changes` | Before/after names for numeric pairs `{ "number": 1, "purpose": 0 }`. |
|
|
| `layer_legend` | Unchanged names available in scope. Annotation labels do not also appear as object changes. |
|
|
| `cell_changes` | Name, nullable before/after cell records, attributes, removed/added objects, and replacement suggestions. A null side means absent; an existing empty cell still has a byte offset. |
|
|
|
|
Objects retain kind, numeric tag, layer, target, bounds, source side and half-open
|
|
byte range, typed fields, and a sorted property multiset including duplicates.
|
|
Convenience fields include origin, width, and reference dimensions. SREF counts
|
|
are `[1, 1]`; kind and retained fields still distinguish a one-element AREF.
|
|
|
|
Coordinates are cell-local database units. Bounds are stored-coordinate
|
|
envelopes, excluding stroke width, rendered text, and recursive target geometry.
|
|
Consider UNITS before deriving physical dimensions.
|
|
|
|
Fields contain `tag`, display `name`, `encoding`, decoded `value`, and
|
|
`payload_hex`. Numeric tags are authoritative. XY values are lists of points;
|
|
other numeric values are arrays. Unsupported encodings have null values and
|
|
preserved bytes. Invalid UTF-8 strings/properties have null decoded values;
|
|
hex preserves their bytes.
|
|
|
|
Evidence follows the comparison profile: boundary/box rings are canonicalized,
|
|
string padding is removed, and fields/properties are sorted. REAL8 encodings and
|
|
explicit defaults remain significant. Source offsets locate original records.
|
|
|
|
Replacements link report-local removed/added IDs with `match_rule`,
|
|
`field_changes`, and `properties_changed`. Rules are `unique_kind_layer_bounds`,
|
|
`unique_kind_layer`, or `unique_kind_target`. IDs are not persistent identities;
|
|
ambiguous candidates stay separate. Explanation text is for display only.
|
|
|
|
## Diagnostics and hierarchy
|
|
|
|
Diagnostics provide `code`, `severity`, `message`, input side, byte offset, cell,
|
|
layer, and target; unknown context is null. Use codes and context for automation.
|
|
Fatal parser locations currently appear only in the human message, with null
|
|
structured offsets. Do not parse message wording.
|
|
|
|
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`.
|
|
|
|
`--hierarchy graph` includes the full scoped union graph; otherwise `hierarchy`
|
|
is null. Nodes are keyed by name, with per-side states `included`, `outside_scope`,
|
|
`unresolved`, or `absent`, and change states `direct`, `affected`, or `unchanged`.
|
|
Edges record parent, target, before/after direct placement counts, and changed
|
|
reference records. Array multiplicities are symbolic, not expanded or recursively
|
|
accumulated. Shared cells occur once and removed edges remain. Display filters,
|
|
object limits, and text depth do not trim the graph.
|
|
|
|
## Versions
|
|
|
|
`schema_version` is 1, `comparison_profile` is `klamath-object-v2`, and
|
|
`producer.name` is `pheon`. Structure, equality rules, and producer version evolve
|
|
independently. Understand the profile before interpreting equality. Consumers
|
|
should tolerate additional optional fields and unknown codes/rules without
|
|
assuming equality. Removed fields or changed meanings require a schema change.
|
|
|
|
Serialization is deterministic for identical inputs, paths, options, and producer
|
|
version. Sorted evidence retains duplicates. Reports have no generation timestamp
|
|
or required content fingerprint. See [development](development.md) for contract
|
|
tests and golden updates.
|