pheon/docs/diff-reports.md

127 lines
6.8 KiB
Markdown
Raw Normal View History

# 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](https://mpxd.net/code/jan/pheon/src/branch/master/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. For gzip inputs, source offsets locate
records in the decompressed layout.
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 `pheon-structural-v1`, 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.