Clarify comparison and report controls

This commit is contained in:
Jan Petykiewicz 2026-11-19 10:21:56 -08:00
commit 623de2e585
3 changed files with 26 additions and 21 deletions

View file

@ -127,21 +127,24 @@ pheon diff before.gds after.gds --hierarchy mermaid --depth 4
``` ```
`--show-cell` and `--show-layer` filter displayed changes without changing the `--show-cell` and `--show-layer` filter displayed changes without changing the
comparison, totals, or exit status. A layer display filter hides references comparison, totals, or exit status. In text reports, `--show-layer` filters
without a numeric layer. `--max-changes N` limits displayed object occurrences object changes within modified cells and hides references without a numeric
after filtering. Text defaults to 100 occurrences and shows a replacement only layer. Added and removed cells appear as name-only entries outside the object
when both objects fit within the limit. Grouped rows count each object toward budget. Use `--show-cell` to filter those entries.
the limit. When a layer filter selects one side of a layer-only replacement,
that side appears as an addition or removal. A single omission line lists `--max-changes N` limits displayed object occurrences after filtering. Text
changes hidden by filters or the limit. JSON has no default object limit and reports defaults to 100 occurrences and shows a replacement only when both objects fit
omissions from both display filters and any explicit limit in `report_selection`. within the limit. Grouped rows count each object toward the limit. When a
See the [JSON reference](diff-reports.md) for the selection counters. layer filter selects one side of a layer-only replacement, that side appears as
an addition or removal. The omission line lists changes hidden by filters or the
limit. JSON has no default object limit and records omissions in
`report_selection`. See the [JSON reference](diff-reports.md) for the selection
counters.
`--details` shows individual object evidence inside modified cells in text `--details` shows individual object evidence inside modified cells in text
reports. Replacement rows include a nested `-` row for the old object and a reports. Replacement rows include a nested `-` row for the old object and a
`+` row for the new object, with cell-local coordinates in database units, `+` row for the new object, with cell-local coordinates in database units,
retained fields, and properties. Both sides count toward `--max-changes`. retained fields, and properties.
For added and removed cells, the report lists the cell name.
The diff hierarchy shows directly changed cells, affected ancestors, and targets The diff hierarchy shows directly changed cells, affected ancestors, and targets
of modified references. It includes references from both revisions so removed of modified references. It includes references from both revisions so removed

View file

@ -27,11 +27,12 @@ operations, XOR, or tolerance-based matching.
## Read change explanations ## Read change explanations
Unmatched objects can be paired to explain a replacement when the pairing is Pheon first pairs unmatched polygons, boxes, and paths that differ only in
unique by kind, layer, and bounds, then by kind and layer. References also use layer or type, with exactly one candidate in each revision. It then checks the
their target cell. Ambiguous candidates remain independent removals and remaining objects for unique matches by kind, layer, and bounds, followed by
additions. Pairing helps explain the report; it does not establish persistent kind and layer. Reference matching uses the target cell. Ambiguous candidates
object identity or change the underlying counts. are reported as separate removals and additions. These explanations apply to
the current report and preserve the underlying addition and removal counts.
Reported bounds are envelopes of stored coordinates in cell-local database Reported bounds are envelopes of stored coordinates in cell-local database
units. They exclude path width, rendered text size, and recursively transformed units. They exclude path width, rendered text size, and recursively transformed

View file

@ -108,13 +108,14 @@ Limitation codes are `unsupported_record`, `unsupported_metadata_version`,
`unresolved_reference`, `hierarchy_cycle`, and `scope_mismatch`. Failure codes are `unresolved_reference`, `hierarchy_cycle`, and `scope_mismatch`. Failure codes are
`invalid_input`, `io_error`, `invalid_scope`, and `command_error`. `invalid_input`, `io_error`, `invalid_scope`, and `command_error`.
`--hierarchy graph` includes the full scoped union graph; otherwise `hierarchy` `--hierarchy graph` includes the full scoped union graph. By default, `hierarchy`
is null. Nodes are keyed by name, with per-side states `included`, `outside_scope`, is null. JSON output rejects `--depth` with exit code 2. Nodes are keyed by name,
`unresolved`, or `absent`, and change states `direct`, `affected`, or `unchanged`. 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 Edges record parent, target, before/after direct placement counts, and changed
reference records. Array multiplicities are symbolic, not expanded or recursively reference records. Array multiplicities are symbolic, not expanded or recursively
accumulated. Shared cells occur once and removed edges remain. Display filters, accumulated. Shared cells occur once and removed edges remain. The graph covers
object limits, and text depth do not trim the graph. the full comparison scope regardless of display filters and object limits.
## Versions ## Versions