Clarify comparison and report controls
This commit is contained in:
parent
4aa36a6d65
commit
623de2e585
3 changed files with 26 additions and 21 deletions
25
docs/cli.md
25
docs/cli.md
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue