feat(review): add scoped reports and native Git integration
Separate top, exact-cell and layer comparison scopes from display filters. Explain unique replacements and preserve full evidence, duplicate counts and incomplete-result handling. Version the dump profile and freeze canonical, hierarchy and diff goldens. Package native Git and textconv drivers with integration coverage for edits, additions, deletions, renames, quoted paths and errors. Document embedded metadata writing and validate deep hierarchies, large polygons and symbolic arrays.
This commit is contained in:
parent
e56026c3a6
commit
d8f764c7fe
1 changed files with 1191 additions and 97 deletions
102
README.md
102
README.md
|
|
@ -56,7 +56,7 @@ schema, offset definitions, and ID assignment.
|
|||
|
||||
## Layout review CLI
|
||||
|
||||
The first review milestone provides a Rust CLI using the existing dependencies:
|
||||
The review CLI uses the existing Rust dependencies:
|
||||
|
||||
```sh
|
||||
cargo build --bin klamath
|
||||
|
|
@ -65,6 +65,9 @@ target/debug/klamath dump chip.gds --records
|
|||
target/debug/klamath diff old.gds new.gds --hierarchy ascii
|
||||
target/debug/klamath diff old.gds new.gds --hierarchy mermaid --max-changes 20
|
||||
target/debug/klamath hierarchy chip.gds --format mermaid --depth 4
|
||||
target/debug/klamath diff old.gds new.gds --top CHIP --layer 1/0
|
||||
target/debug/klamath diff old.gds new.gds --show-layer 1/0
|
||||
target/debug/klamath name-layers chip.gds named.gds --cell CHIP --carrier 900/7 --name 1:0:WG
|
||||
```
|
||||
|
||||
The object dump is deterministic and omits source offsets. Record dumps preserve
|
||||
|
|
@ -72,9 +75,10 @@ record order and show offsets, tags, sizes, and values, including records the
|
|||
object reviewer does not support. They can inspect an invalid metadata declaration
|
||||
without invoking object-level validation. Zero padding after ENDLIB is accepted.
|
||||
|
||||
The fixed `klamath-object-v1` comparison profile:
|
||||
The fixed `klamath-object-v2` comparison profile:
|
||||
|
||||
- Compares the entire library, matching cells by name and layers by numeric pair.
|
||||
- Matches cells by name and layers by numeric pair. The default scope is the
|
||||
entire library; explicit selectors are recorded in each report.
|
||||
- Ignores library/cell timestamps, cell order, element order, and property order.
|
||||
- Normalizes boundary/box starting vertex and winding, retaining other vertices.
|
||||
- Preserves duplicate objects and duplicate properties as multisets.
|
||||
|
|
@ -94,6 +98,37 @@ and **2** for invalid input or incomplete comparison. `--max-changes` limits the
|
|||
number of object details displayed, not the comparison. Source offsets are
|
||||
included in changed-object reports for tracing changes back to record dumps.
|
||||
|
||||
Unmatched objects are paired for explanation only when candidates are unique by
|
||||
type/layer/bounding box, then by type/layer among the remaining objects.
|
||||
References additionally match by target. Ambiguous groups stay additions and
|
||||
removals. Reports explain reference movement, array-count changes, path widths,
|
||||
and polygons changed within the same bounds. Full before/after records remain
|
||||
visible, and duplicate counts remain significant. Unchanged layer names appear
|
||||
once as a legend for changed objects on those layers.
|
||||
|
||||
### Comparison scope and display filters
|
||||
|
||||
`--top NAME` compares that cell and its reachable subtree independently in each
|
||||
revision. `--cell NAME` compares the exact cell, including its reference records,
|
||||
without comparing descendant contents. Combine the two to select a cell within
|
||||
a subtree. A selector absent from both revisions is an error; absence on one
|
||||
side is an addition/deletion.
|
||||
|
||||
`--layer L/T` selects objects on a numeric layer/type pair, plus references whose
|
||||
targets use that layer transitively. Cells with no relevant content are omitted.
|
||||
Unresolved references, cycles, and unsupported records with unknown layer effect
|
||||
remain incomplete results. Unsupported objects on another known layer can be
|
||||
excluded. Library fields, including units, remain compared. Scoped dumps and
|
||||
hierarchy views accept the same selectors. Scope selection parses the complete
|
||||
input: malformed record grammar and conflicting metadata are still errors.
|
||||
|
||||
`--show-cell NAME` and `--show-layer L/T` filter object details in a diff report
|
||||
without changing comparison status, totals, metadata changes, or hierarchy.
|
||||
References have no numeric layer and are hidden by `--show-layer`. The comparison
|
||||
scope and any display-only filter are printed explicitly. The Rust API accepts
|
||||
one combined `Scope`; applying another scope to an already scoped document is
|
||||
rejected rather than losing reference coverage information.
|
||||
|
||||
Hierarchy output distinguishes directly changed cells, affected ancestors, and
|
||||
unchanged targets of modified references. It includes edges from both revisions,
|
||||
so removed branches remain visible. Counts are direct edge multiplicities,
|
||||
|
|
@ -113,24 +148,59 @@ Names are collected across the library. Recognized metadata labels are omitted
|
|||
from object comparison; mappings are compared separately and printed once per
|
||||
numeric pair, so renaming a layer does not rewrite every shape description.
|
||||
|
||||
This milestone reads the sentinel convention. It does not yet write metadata,
|
||||
import LayoutEditor's `LayerNames` extension, remap/extract layouts, or provide
|
||||
top/layer scope filters. The separate review adapter borrows raw record payloads
|
||||
and retains information normalized or omitted by the Arrow geometry reader;
|
||||
the existing Arrow APIs are unchanged. Structured Rust change records feed the
|
||||
text and hierarchy renderers.
|
||||
`name-layers INPUT OUTPUT --cell NAME --carrier L/T --name L:T:NAME ...` writes
|
||||
this convention. It consolidates existing recognized declarations into one legend
|
||||
in the chosen existing cell, retains existing names not explicitly updated, and
|
||||
overrides the named pairs. The chosen carrier must contain no ordinary design
|
||||
objects in that cell. Unrelated records, timestamps, unknown records and trailing
|
||||
padding are copied byte-for-byte. No structures or references are added. Output
|
||||
must be a new file: the CLI refuses to overwrite an existing destination, including
|
||||
the input. Invalid declarations, conflicting arguments, oversized labels and
|
||||
future metadata versions fail before output creation.
|
||||
|
||||
After installing the executable on PATH, the canonical dump can serve as a Git
|
||||
textconv. Add this attribute to the layout repository:
|
||||
The record-preserving review adapter retains information normalized or omitted
|
||||
by the Arrow geometry reader; existing Arrow APIs are unchanged. Structured Rust
|
||||
change records feed the text and hierarchy renderers. LayoutEditor's `LayerNames`
|
||||
extension, layout extraction/remapping, and geometric Boolean comparison remain
|
||||
outside the current CLI.
|
||||
|
||||
### Git integration
|
||||
|
||||
Install the executable on PATH with `cargo install --path . --bin klamath`.
|
||||
The templates in [contrib/git/config](contrib/git/config) and
|
||||
[contrib/git/attributes](contrib/git/attributes) provide two alternative drivers.
|
||||
For structural summaries and affected hierarchy, add this attribute:
|
||||
|
||||
```gitattributes
|
||||
*.gds diff=klamath
|
||||
```
|
||||
|
||||
Configure the driver in Git config:
|
||||
Configure the native external driver in Git config:
|
||||
|
||||
```gitconfig
|
||||
[diff "klamath"]
|
||||
command = klamath git-diff --hierarchy ascii --
|
||||
binary = true
|
||||
trustExitCode = false
|
||||
```
|
||||
|
||||
The adapter consumes Git's old/new temporary files directly, handles additions,
|
||||
deletions and renames, and quotes display paths. It returns success after rendering
|
||||
either equality or differences, as expected by the external-driver protocol.
|
||||
Invalid or incomplete comparisons retain a nonzero exit and diagnostics. Scope
|
||||
and display options can precede the final `--` in the configured command. Existing
|
||||
repositories using `diff=layout` can put the same command under `[diff "layout"]`.
|
||||
|
||||
For ordinary Git line diffs, use canonical textconv instead:
|
||||
|
||||
```gitattributes
|
||||
*.gds diff=klamath-text
|
||||
```
|
||||
|
||||
Configure the driver in Git config:
|
||||
|
||||
```gitconfig
|
||||
[diff "klamath-text"]
|
||||
textconv = klamath dump
|
||||
binary = true
|
||||
cachetextconv = true
|
||||
|
|
@ -140,5 +210,9 @@ This is a human review representation, not an applicable GDS patch. Invalidate
|
|||
Git's textconv cache when changing the dump profile/tool version. For automated
|
||||
equality checks, use `klamath diff` and its exit status directly.
|
||||
|
||||
`tests/review.rs` contains ten generated fixture pairs with explicit expected
|
||||
results, plus record, metadata, malformed-input, hierarchy, and CLI regressions.
|
||||
`tests/review.rs` contains ten initial fixture pairs, checked-in canonical/text/
|
||||
Mermaid goldens, metadata byte-preservation checks, scope and report regressions,
|
||||
and actual Git integration tests. It also checks near-limit polygon records,
|
||||
2048-cell hierarchies and arrays representing over a billion placements without
|
||||
expanding them. Run `cargo test` and `cargo test --release` for debug and optimized
|
||||
validation. No KLayout installation or Python package is required.
|
||||
|
|
|
|||
Loading…
Reference in a new issue