Capture revision metadata, cell presence and attributes, and structured diagnostics in owned comparison results. Derive outcomes and render text, JSON, and hierarchy reports without retaining source documents. Keep derived descriptions and graph analysis in their renderers. Use pheon-structural-v1 and PHEON_LAYER_NAMES_V1 consistently, expose helpers through their defining modules, and remove obsolete re-exports. Update user guides and report fixtures without changing schema version 1. Cover dropped inputs, diagnostic ordering, absent and empty cells, offset independence, and CLI failures. All 92 Rust tests pass in debug and release; report and hierarchy goldens retain their behavior.
6.8 KiB
JSON diff reports
Use JSON reports to automate layout review while retaining the evidence behind a result. The comparison rules define equality; the version 1 JSON Schema defines every field. A complete example shows geometry changes.
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 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 for contract tests and golden updates.