From 623de2e585faccbeebcfdfe5c0b0a71c01907c9b Mon Sep 17 00:00:00 2001 From: Jan Petykiewicz Date: Thu, 19 Nov 2026 10:21:56 -0800 Subject: [PATCH] Clarify comparison and report controls --- docs/cli.md | 25 ++++++++++++++----------- docs/comparison.md | 11 ++++++----- docs/diff-reports.md | 11 ++++++----- 3 files changed, 26 insertions(+), 21 deletions(-) diff --git a/docs/cli.md b/docs/cli.md index bee1df3..fb56827 100644 --- a/docs/cli.md +++ b/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 diff --git a/docs/comparison.md b/docs/comparison.md index a596f54..739fab3 100644 --- a/docs/comparison.md +++ b/docs/comparison.md @@ -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 diff --git a/docs/diff-reports.md b/docs/diff-reports.md index c88cdfd..b71b0ab 100644 --- a/docs/diff-reports.md +++ b/docs/diff-reports.md @@ -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