feat(review): add versioned JSON comparison reports

This commit is contained in:
Jan Petykiewicz 2026-11-15 10:38:48 -08:00
commit 248f6bcff7

View file

@ -56,7 +56,7 @@ schema, offset definitions, and ID assignment.
## Layout review CLI
The review CLI uses the existing Rust dependencies:
The review CLI is a standalone Rust executable:
```sh
cargo build --bin klamath
@ -67,6 +67,8 @@ target/debug/klamath diff old.gds new.gds --hierarchy mermaid --max-changes 20
target/debug/klamath hierarchy chip.gds --format mermaid --depth 4
target/debug/klamath diff old.gds new.gds --top CHIP --layer 1/0
target/debug/klamath diff old.gds new.gds --show-layer 1/0
target/debug/klamath diff old.gds new.gds --format json
target/debug/klamath diff old.gds new.gds --format json --hierarchy graph
target/debug/klamath name-layers chip.gds named.gds --cell CHIP --carrier 900/7 --name 1:0:WG
```
@ -98,6 +100,16 @@ and **2** for invalid input or incomplete comparison. `--max-changes` limits the
number of object details displayed, not the comparison. Source offsets are
included in changed-object reports for tracing changes back to record dumps.
`diff --format json` emits a versioned report with typed before/after evidence,
structured diagnostics, and independent comparison status and completeness.
JSON includes all changes by default. Explicit display filters and `--max-changes`
record omitted evidence without changing totals or exit status. `--hierarchy graph`
adds the complete scoped reference graph, with symbolic array multiplicities;
`--depth` applies to text output only. Timestamp-only changes still return 0.
Input and argument errors also produce JSON when requested. See the
[report contract](docs/diff-reports.md) and
[version 1 JSON Schema](docs/diff-report-v1.schema.json).
Unmatched objects are paired for explanation only when candidates are unique by
type/layer/bounding box, then by type/layer among the remaining objects.
References additionally match by target. Ambiguous groups stay additions and