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
|
`--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
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
|
||||||
|
|
@ -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
|
||||||
|
|
||||||
|
|
|
||||||
Loading…
Reference in a new issue