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
comparison, totals, or exit status. A layer display filter hides references
without a numeric layer. `--max-changes N` limits displayed object occurrences
after filtering. Text defaults to 100 occurrences and shows a replacement only
when both objects fit within the limit. Grouped rows count each object toward
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
changes hidden by filters or the limit. JSON has no default object limit and reports
omissions from both display filters and any explicit limit in `report_selection`.
See the [JSON reference](diff-reports.md) for the selection counters.
comparison, totals, or exit status. In text reports, `--show-layer` filters
object changes within modified cells and hides references without a numeric
layer. Added and removed cells appear as name-only entries outside the object
budget. Use `--show-cell` to filter those entries.
`--max-changes N` limits displayed object occurrences after filtering. Text
defaults to 100 occurrences and shows a replacement only when both objects fit
within the limit. Grouped rows count each object toward the limit. When a
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
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,
retained fields, and properties. Both sides count toward `--max-changes`.
For added and removed cells, the report lists the cell name.
retained fields, and properties.
The diff hierarchy shows directly changed cells, affected ancestors, and targets
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
Unmatched objects can be paired to explain a replacement when the pairing is
unique by kind, layer, and bounds, then by kind and layer. References also use
their target cell. Ambiguous candidates remain independent removals and
additions. Pairing helps explain the report; it does not establish persistent
object identity or change the underlying counts.
Pheon first pairs unmatched polygons, boxes, and paths that differ only in
layer or type, with exactly one candidate in each revision. It then checks the
remaining objects for unique matches by kind, layer, and bounds, followed by
kind and layer. Reference matching uses the target cell. Ambiguous candidates
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
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
`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`.
`--hierarchy graph` includes the full scoped union graph. By default, `hierarchy`
is null. JSON output rejects `--depth` with exit code 2. 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.
accumulated. Shared cells occur once and removed edges remain. The graph covers
the full comparison scope regardless of display filters and object limits.
## Versions