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:
Jan Petykiewicz 2026-11-14 17:48:49 -08:00
commit d8f764c7fe
12 changed files with 1191 additions and 97 deletions

102
README.md
View file

@ -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.

5
contrib/git/attributes Normal file
View file

@ -0,0 +1,5 @@
# Add these lines to the layout repository's .gitattributes.
*.gds diff=klamath
# For canonical textconv instead, replace the line above with:
# *.gds diff=klamath-text

10
contrib/git/config Normal file
View file

@ -0,0 +1,10 @@
# Include this file from Git config after installing klamath on PATH.
[diff "klamath"]
command = klamath git-diff --hierarchy ascii --
binary = true
trustExitCode = false
[diff "klamath-text"]
textconv = klamath dump
binary = true
cachetextconv = true

View file

@ -1,5 +1,6 @@
use klamath_rs_ext::review::{
Comparison, Document, dump_records, hierarchy, parse_layer, parse_layer_name, write_layer_names,
Comparison, DisplayFilter, Document, Scope, dump_records, hierarchy, parse_layer,
parse_layer_name, write_layer_names,
};
use std::{
collections::BTreeMap,
@ -11,8 +12,8 @@ use std::{
const HELP: &str = "Usage:
klamath dump FILE [--records]
klamath diff OLD NEW [--hierarchy ascii|mermaid|none] [--max-changes N] [--depth N]
klamath hierarchy FILE [--format ascii|mermaid] [--depth N]
klamath diff OLD NEW [--top NAME] [--cell NAME] [--layer L/T]\n [--show-cell NAME] [--show-layer L/T] [--hierarchy ascii|mermaid|none]\n [--max-changes N] [--depth N]
klamath hierarchy FILE [--format ascii|mermaid] [--depth N] [--top NAME]\n klamath git-diff [OPTIONS] -- PATH OLD OLD_OID OLD_MODE NEW NEW_OID NEW_MODE
klamath name-layers INPUT OUTPUT --cell NAME --carrier L/T --name L:T:NAME ...
Object profile: ignore timestamps and element order, normalize polygon start/winding,
@ -77,39 +78,66 @@ fn name_layers(args: &[OsString]) -> Result<u8, String> {
Ok(0)
}
fn stdout(output: &str) -> Result<(), String> {
io::stdout()
.lock()
.write_all(output.as_bytes())
.map_err(|e| e.to_string())
}
fn run() -> Result<u8, String> {
let args: Vec<_> = std::env::args_os().skip(1).collect();
if args.is_empty() || args[0] == "--help" || args[0] == "-h" {
print!("{HELP}");
stdout(HELP)?;
return Ok(0);
}
let command = args[0].to_str().ok_or("invalid command")?;
if command == "name-layers" {
return name_layers(&args[1..]);
}
let paths = match command {
let expected = match command {
"dump" | "hierarchy" => 1,
"diff" => 2,
"git-diff" => 7,
_ => return Err(HELP.to_string()),
};
if args.len() <= paths {
return Err(HELP.to_string());
}
let compare = command == "diff" || command == "git-diff";
let mut scope = Scope::default();
let mut show = DisplayFilter::default();
let mut raw = false;
let mut format = if command == "diff" {
let mut format = if compare {
"none".to_string()
} else {
"ascii".to_string()
};
let mut max_changes = 100;
let mut depth = 8;
let mut i = paths + 1;
let mut paths = Vec::new();
let mut literal = false;
let mut i = 1;
while i < args.len() {
if literal {
paths.push(args[i].clone());
i += 1;
continue;
}
match args[i].to_str() {
Some("--") => literal = true,
Some("--help" | "-h") => {
stdout(HELP)?;
return Ok(0);
}
Some("--records") if command == "dump" => raw = true,
Some("--hierarchy") if command == "diff" => format = value(&args, &mut i)?,
Some("--top") => scope.top = Some(value(&args, &mut i)?),
Some("--cell") => scope.cell = Some(value(&args, &mut i)?),
Some("--layer") => scope.layer = Some(parse_layer(&value(&args, &mut i)?)?),
Some("--show-cell") if compare => show.cell = Some(value(&args, &mut i)?),
Some("--show-layer") if compare => {
show.layer = Some(parse_layer(&value(&args, &mut i)?)?)
}
Some("--hierarchy") if compare => format = value(&args, &mut i)?,
Some("--format") if command == "hierarchy" => format = value(&args, &mut i)?,
Some("--max-changes") if command == "diff" => {
Some("--max-changes") if compare => {
max_changes = value(&args, &mut i)?
.parse()
.map_err(|_| "invalid change limit")?
@ -117,71 +145,107 @@ fn run() -> Result<u8, String> {
Some("--depth") if command != "dump" => {
depth = value(&args, &mut i)?.parse().map_err(|_| "invalid depth")?
}
_ => return Err(format!("unknown option {:?}\n{HELP}", args[i])),
Some(s) if s.starts_with('-') => return Err(format!("unknown option {s:?}")),
_ => paths.push(args[i].clone()),
}
i += 1;
}
if paths.len() != expected && !(command == "git-diff" && paths.len() == 9) {
return Err(HELP.to_string());
}
if !matches!(format.as_str(), "ascii" | "mermaid" | "none")
|| (command == "hierarchy" && format == "none")
{
return Err("format must be ascii or mermaid (diff also accepts none)".to_string());
}
let old_bytes = fs::read(&args[1]).map_err(|e| format!("{:?}: {e}", args[1]))?;
let read = |path: &OsString| fs::read(path).map_err(|e| format!("{path:?}: {e}"));
if raw {
io::stdout()
.lock()
.write_all(dump_records(&old_bytes)?.as_bytes())
.map_err(|e| e.to_string())?;
if scope != Scope::default() {
return Err("record dumps do not accept object scope selectors".to_string());
}
stdout(&dump_records(&read(&paths[0])?)?)?;
return Ok(0);
}
let old = Document::parse(&old_bytes)?;
let (output, status) = match command {
"dump" => (
old.canonical_dump(),
if old.issues.is_empty() { 0 } else { 2 },
),
"hierarchy" => {
let mut output = hierarchy(&old, &old, None, format == "mermaid", depth);
if format != "mermaid" {
for issue in &old.issues {
output.push_str(&format!("INCOMPLETE: {issue}\n"));
}
} else {
for issue in &old.issues {
eprintln!("INCOMPLETE: {issue}");
}
if !compare {
let bytes = read(&paths[0])?;
let doc = Document::parse(&bytes)?.selected(&scope, false)?;
let output = if command == "dump" {
doc.canonical_dump()
} else {
hierarchy(&doc, &doc, None, format == "mermaid", depth)
};
stdout(&output)?;
if command == "hierarchy" {
for issue in &doc.issues {
eprintln!("INCOMPLETE: {issue}");
}
(output, if old.issues.is_empty() { 0 } else { 2 })
}
"diff" => {
let new_bytes = fs::read(&args[2]).map_err(|e| format!("{:?}: {e}", args[2]))?;
let new = Document::parse(&new_bytes)?;
let diff = Comparison::between(&old, &new);
let mut output = diff.text(max_changes);
if format != "none" {
if format == "mermaid" {
output.push_str("```mermaid\n");
}
output.push_str(&hierarchy(
&old,
&new,
Some(&diff),
format == "mermaid",
depth,
));
if format == "mermaid" {
output.push_str("```\n");
}
}
(output, diff.exit_code())
}
_ => unreachable!(),
return Ok(if doc.issues.is_empty() { 0 } else { 2 });
}
let git = command == "git-diff";
let old_missing = git && (paths[3] == "000000" || paths[3] == ".");
let new_missing = git && (paths[6] == "000000" || paths[6] == ".");
if old_missing && new_missing {
return Err("both Git revisions are absent".to_string());
}
let old_bytes = if old_missing {
None
} else {
Some(read(&paths[if git { 1 } else { 0 }])?)
};
io::stdout()
.lock()
.write_all(output.as_bytes())
.map_err(|e| e.to_string())?;
Ok(status)
let new_bytes = if new_missing {
None
} else {
Some(read(&paths[if git { 4 } else { 1 }])?)
};
let old = old_bytes.as_ref().map(|b| Document::parse(b)).transpose()?;
let new = new_bytes.as_ref().map(|b| Document::parse(b)).transpose()?;
let old = old.unwrap_or_else(|| new.as_ref().unwrap().empty_like());
let new = new.unwrap_or_else(|| old.empty_like());
scope.validate_pair(&old, &new)?;
let old = old.selected(&scope, true)?;
let new = new.selected(&scope, true)?;
let diff = Comparison::between(&old, &new);
let mut output = String::new();
if git {
if paths.len() == 9 {
output.push_str(&format!("layout {:?} -> {:?}\n", paths[0], paths[7]));
} else {
output.push_str(&format!("layout {:?}\n", paths[0]));
}
if old_missing {
output.push_str("layout added\n");
} else if new_missing {
output.push_str("layout deleted\n");
}
if paths[3] != paths[6] {
output.push_str(&format!("mode {:?} -> {:?}\n", paths[3], paths[6]));
}
}
output.push_str(&diff.text_filtered(max_changes, &show));
if format != "none" {
if format == "mermaid" {
output.push_str("```mermaid\n");
}
output.push_str(&hierarchy(
&old,
&new,
Some(&diff),
format == "mermaid",
depth,
));
if format == "mermaid" {
output.push_str("```\n");
}
}
stdout(&output)?;
// Git's external driver expects successful rendering for either equality
// or differences. Actual comparison/input failures remain nonzero.
Ok(if git && diff.exit_code() == 1 {
0
} else {
diff.exit_code()
})
}
fn main() -> ExitCode {

View file

@ -10,8 +10,12 @@ use std::{
mod names;
pub use names::{parse_layer, parse_layer_name, write_layer_names};
mod selection;
pub use selection::{DisplayFilter, Scope};
mod changes;
pub use changes::Replacement;
pub const PROFILE: &str = "klamath-object-v1";
pub const PROFILE: &str = "klamath-object-v2";
pub const LAYER_SENTINEL: &str = "KLAMATH_LAYER_NAMES_V1";
pub type Layer = (u16, u16);
pub type Bounds = [i32; 4];
@ -41,6 +45,7 @@ pub struct Object<'a> {
pub multiplicity: u64,
key: Key<'a>,
metadata: bool,
issues: Vec<String>,
}
impl Object<'_> {
@ -71,6 +76,7 @@ pub struct Cell<'a> {
pub end_offset: usize,
pub objects: Vec<Object<'a>>,
attributes: Vec<(u16, &'a [u8])>,
issues: Vec<String>,
}
#[derive(Debug)]
@ -81,6 +87,10 @@ pub struct Document<'a> {
/// Unsupported features or invalid reference graphs prevent an equality claim.
pub issues: Vec<String>,
header: Vec<(u16, &'a [u8])>,
global_issues: Vec<String>,
known_cells: BTreeSet<String>,
pub scope: Scope,
present: bool,
}
fn error(offset: usize, message: impl std::fmt::Display) -> String {
@ -299,6 +309,7 @@ fn object<'a>(records: &[Record<'a>], issues: &mut Vec<String>) -> Result<Object
properties,
},
metadata: false,
issues: Vec::new(),
};
let xy = object
.field(RTAG_XY)
@ -414,6 +425,10 @@ impl<'a> Document<'a> {
layer_names: BTreeMap::new(),
issues: Vec::new(),
header: Vec::new(),
global_issues: Vec::new(),
known_cells: BTreeSet::new(),
scope: Scope::default(),
present: true,
};
let mut i = 2;
let mut global_seen = BTreeSet::new();
@ -446,7 +461,7 @@ impl<'a> Document<'a> {
| RTAG_SRFNAME
| RTAG_LIBSECUR
) {
doc.issues.push(error(
doc.global_issues.push(error(
record.offset,
format!("unsupported library record 0x{:04x}", record.tag),
));
@ -483,6 +498,7 @@ impl<'a> Document<'a> {
end_offset: 0,
objects: Vec::new(),
attributes: Vec::new(),
issues: Vec::new(),
};
loop {
let record = doc
@ -508,15 +524,17 @@ impl<'a> Document<'a> {
if i == doc.records.len() {
return Err(error(offset, "missing ENDEL"));
}
cell.objects
.push(object(&doc.records[start..=i], &mut doc.issues)?);
let mut issues = Vec::new();
let mut parsed = object(&doc.records[start..=i], &mut issues)?;
parsed.issues = issues;
cell.objects.push(parsed);
i += 1;
} else {
if matches!(record.tag, RTAG_ENDLIB | RTAG_BGNSTR) {
return Err(error(record.offset, "missing ENDSTR"));
}
if record.tag != RTAG_STRCLASS {
doc.issues.push(error(
cell.issues.push(error(
record.offset,
format!("unsupported cell record 0x{:04x}", record.tag),
));
@ -543,16 +561,17 @@ impl<'a> Document<'a> {
}
doc.header.sort();
doc.read_metadata()?;
doc.check_graph();
doc.known_cells = doc.cells.keys().cloned().collect();
doc.refresh_issues();
Ok(doc)
}
fn read_metadata(&mut self) -> Result<(), String> {
for cell in self.cells.values_mut() {
for object in cell.objects.iter().filter(|o| o.kind == RTAG_TEXT) {
for object in cell.objects.iter_mut().filter(|o| o.kind == RTAG_TEXT) {
let text = object.field(RTAG_STRING).unwrap();
if text.starts_with(b"KLAMATH_LAYER_NAMES_") && text != LAYER_SENTINEL.as_bytes() {
self.issues.push(error(
object.issues.push(error(
object.offset,
"unsupported layer-name metadata version",
));
@ -595,8 +614,8 @@ impl<'a> Document<'a> {
fn check_graph(&mut self) {
let edges = self.edges();
for ((parent, target), _) in &edges {
if !self.cells.contains_key(target) {
for (parent, target) in edges.keys() {
if !self.known_cells.contains(target) {
self.issues
.push(format!("cell {parent:?}: unresolved reference {target:?}"));
}
@ -646,7 +665,8 @@ impl<'a> Document<'a> {
pub fn canonical_dump(&self) -> String {
let mut out = format!(
"profile {PROFILE}\ncoordinates: integer database units; bounds: coordinate envelopes\n"
"profile {PROFILE}\n{}\ncoordinates: integer database units; bounds: coordinate envelopes\n",
self.scope.description()
);
for (tag, data) in &self.header {
writeln!(out, "{}={}", tag_name(*tag), format_data(*tag, data)).unwrap();
@ -706,8 +726,13 @@ fn format_records(records: &[Record<'_>]) -> String {
#[derive(Debug)]
pub struct ObjectChange {
pub offset: usize,
pub kind: u16,
pub layer: Option<Layer>,
pub bounds: Option<Bounds>,
pub target: Option<String>,
pub origin: Option<[i32; 2]>,
pub width: Option<i32>,
pub counts: Option<[u16; 2]>,
pub description: String,
}
@ -715,8 +740,25 @@ impl From<&Object<'_>> for ObjectChange {
fn from(object: &Object<'_>) -> Self {
Self {
offset: object.offset,
kind: object.kind,
layer: object.layer,
bounds: object.bounds,
target: object.target.clone(),
origin: object.field(RTAG_XY).map(|data| {
[
i32::from_be_bytes(data[..4].try_into().unwrap()),
i32::from_be_bytes(data[4..8].try_into().unwrap()),
]
}),
width: object
.field(RTAG_WIDTH)
.map(|data| i32::from_be_bytes(data.try_into().unwrap())),
counts: object.target.as_ref().map(|_| {
object
.field(RTAG_COLROW)
.map(|data| [integer(&data[..2]), integer(&data[2..])])
.unwrap_or([1, 1])
}),
description: object.description(),
}
}
@ -730,6 +772,7 @@ pub struct CellChange {
pub attributes_changed: bool,
pub removed: Vec<ObjectChange>,
pub added: Vec<ObjectChange>,
pub replacements: Vec<Replacement>,
}
#[derive(Debug)]
@ -748,6 +791,9 @@ pub struct LibraryFieldChange {
#[derive(Debug)]
pub struct Comparison {
pub scope: Scope,
/// Unchanged names are displayed once when objects on that layer change.
pub layer_legend: BTreeMap<Layer, String>,
pub library_fields: Vec<LibraryFieldChange>,
pub layer_names: Vec<LayerNameChange>,
pub cells: Vec<CellChange>,
@ -757,11 +803,28 @@ pub struct Comparison {
impl Comparison {
pub fn between(old: &Document<'_>, new: &Document<'_>) -> Self {
let mut result = Self {
scope: old.scope.clone(),
layer_legend: old
.layer_names
.iter()
.filter(|(pair, name)| new.layer_names.get(pair) == Some(*name))
.map(|(pair, name)| (*pair, name.clone()))
.collect(),
library_fields: Vec::new(),
layer_names: Vec::new(),
cells: Vec::new(),
issues: Vec::new(),
};
if old.scope != new.scope {
result.issues.push("comparison scopes differ".to_string());
}
if old.present != new.present {
result.library_fields.push(LibraryFieldChange {
field: "presence".to_string(),
old: vec![if old.present { "present" } else { "absent" }.to_string()],
new: vec![if new.present { "present" } else { "absent" }.to_string()],
});
}
for (side, doc) in [("old", old), ("new", new)] {
result
.issues
@ -820,6 +883,7 @@ impl Comparison {
attributes_changed: a.map(|c| &c.attributes) != b.map(|c| &c.attributes),
removed: Vec::new(),
added: Vec::new(),
replacements: Vec::new(),
};
let a: Vec<_> = a
.into_iter()
@ -859,6 +923,7 @@ impl Comparison {
|| !change.removed.is_empty()
|| !change.added.is_empty()
{
change.replacements = changes::replacements(&change.removed, &change.added);
result.cells.push(change);
}
}
@ -884,7 +949,14 @@ impl Comparison {
/// Limit presentation only: the complete comparison has already been made.
pub fn text(&self, max_objects: usize) -> String {
let mut out = format!("profile {PROFILE}\n");
self.text_filtered(max_objects, &DisplayFilter::default())
}
pub fn text_filtered(&self, max_objects: usize, show: &DisplayFilter) -> String {
let mut out = format!("profile {PROFILE}\n{}\n", self.scope.description());
if show.cell.is_some() || show.layer.is_some() {
writeln!(out, "display-only filter cell={:?} layer={:?}; status, totals and hierarchy are unfiltered", show.cell, show.layer).unwrap();
}
for change in &self.library_fields {
writeln!(
out,
@ -904,13 +976,29 @@ impl Comparison {
)
.unwrap();
}
let changed_layers: BTreeSet<_> = self
.cells
.iter()
.filter(|cell| show.cell.as_ref().is_none_or(|name| name == &cell.name))
.flat_map(|cell| cell.removed.iter().chain(&cell.added))
.filter_map(|object| object.layer)
.filter(|layer| show.layer.is_none_or(|selected| selected == *layer))
.collect();
for layer in changed_layers {
if let Some(name) = self.layer_legend.get(&layer) {
writeln!(out, "layer {}/{} name={name:?}", layer.0, layer.1).unwrap();
}
}
let total: usize = self
.cells
.iter()
.map(|c| c.removed.len() + c.added.len())
.sum();
let mut shown = 0;
let mut shown: usize = 0;
for cell in &self.cells {
if show.cell.as_ref().is_some_and(|name| name != &cell.name) {
continue;
}
writeln!(
out,
"cell {:?} old@{:?} new@{:?}{}",
@ -924,8 +1012,45 @@ impl Comparison {
}
)
.unwrap();
for (sign, objects) in [("-", &cell.removed), ("+", &cell.added)] {
for object in objects {
let mut paired_old = BTreeSet::new();
let mut paired_new = BTreeSet::new();
for replacement in &cell.replacements {
let a = &cell.removed[replacement.removed];
let b = &cell.added[replacement.added];
if shown.saturating_add(2) <= max_objects
&& show
.layer
.is_none_or(|layer| a.layer == Some(layer) && b.layer == Some(layer))
{
writeln!(out, " ~ {}", replacement.explanation).unwrap();
writeln!(
out,
" - @{} bbox={:?} {}",
a.offset, a.bounds, a.description
)
.unwrap();
writeln!(
out,
" + @{} bbox={:?} {}",
b.offset, b.bounds, b.description
)
.unwrap();
paired_old.insert(replacement.removed);
paired_new.insert(replacement.added);
shown += 2;
}
}
for (sign, objects, paired) in [
("-", &cell.removed, &paired_old),
("+", &cell.added, &paired_new),
] {
for (index, object) in objects.iter().enumerate() {
if paired.contains(&index) {
continue;
}
if show.layer.is_some_and(|layer| object.layer != Some(layer)) {
continue;
}
if shown < max_objects {
writeln!(
out,
@ -1054,7 +1179,13 @@ pub fn hierarchy(
rows.push((name.clone(), 0, None, false, true));
}
let status = |name: &String| {
if direct.contains(name) {
if !old.cells.contains_key(name) && !new.cells.contains_key(name) {
if old.known_cells.contains(name) || new.known_cells.contains(name) {
" [outside scope]"
} else {
" [unresolved]"
}
} else if direct.contains(name) {
" [cell changed]"
} else if affected.contains(name) {
" [affected]"
@ -1091,7 +1222,7 @@ pub fn hierarchy(
.enumerate()
.map(|(i, n)| (n, i))
.collect();
let mut out = "flowchart TD\n".to_string();
let mut out = format!("flowchart TD\n %% {}\n", new.scope.description());
for (name, id) in &ids {
let label = format!("{name}{}", status(name));
let label = label
@ -1112,7 +1243,7 @@ pub fn hierarchy(
}
out
} else {
let mut out = String::new();
let mut out = format!("{}\n", new.scope.description());
for (name, depth, parent, seen, limited) in rows {
let count = parent
.map(|p| edge_label(&p, &name))

117
src/review/changes.rs Normal file
View file

@ -0,0 +1,117 @@
use super::*;
#[derive(Debug)]
pub struct Replacement {
pub removed: usize,
pub added: usize,
pub explanation: String,
}
type Group = (u16, Option<Layer>, Option<String>, Option<Bounds>);
fn group(object: &ObjectChange, bounds: bool) -> Group {
(
object.kind,
object.layer,
object.target.clone(),
if bounds && object.target.is_none() {
object.bounds
} else {
None
},
)
}
/// Pair only unique candidates in the remaining multisets. Ambiguous groups
/// remain additions/removals; no identity or geometric equivalence is inferred.
pub(super) fn replacements(old: &[ObjectChange], new: &[ObjectChange]) -> Vec<Replacement> {
let (mut used_old, mut used_new) = (BTreeSet::new(), BTreeSet::new());
let mut result = Vec::new();
for bounds in [true, false] {
let (mut a, mut b) = (
BTreeMap::<Group, Vec<usize>>::new(),
BTreeMap::<Group, Vec<usize>>::new(),
);
for (i, object) in old
.iter()
.enumerate()
.filter(|(i, _)| !used_old.contains(i))
{
a.entry(group(object, bounds)).or_default().push(i);
}
for (i, object) in new
.iter()
.enumerate()
.filter(|(i, _)| !used_new.contains(i))
{
b.entry(group(object, bounds)).or_default().push(i);
}
for (key, indices) in a {
if let (1, Some(others)) = (indices.len(), b.get(&key)) {
if others.len() == 1 {
let (i, j) = (indices[0], others[0]);
result.push(Replacement {
removed: i,
added: j,
explanation: explain(&old[i], &new[j]),
});
used_old.insert(i);
used_new.insert(j);
}
}
}
}
result.sort_by_key(|r| (r.removed, r.added));
result
}
fn explain(old: &ObjectChange, new: &ObjectChange) -> String {
let mut parts = vec![format!(
"{} modified{}",
kind_name(old.kind),
old.target
.as_ref()
.map(|t| format!(" target={t:?}"))
.unwrap_or_default()
)];
if old.target.is_some() && old.origin != new.origin {
if let (Some(a), Some(b)) = (old.origin, new.origin) {
parts.push(format!(
"origin {a:?} -> {b:?}, delta=({}, {}) dbu",
i64::from(b[0]) - i64::from(a[0]),
i64::from(b[1]) - i64::from(a[1])
));
}
}
if old.counts != new.counts {
let counts = |c: Option<[u16; 2]>| {
c.map(|[a, b]| format!("{a} x {b}"))
.unwrap_or_else(|| "absent".to_string())
};
parts.push(format!(
"columns/rows {} -> {}",
counts(old.counts),
counts(new.counts)
));
}
if old.width != new.width {
let width = |n: Option<i32>| {
n.map(|n| n.to_string())
.unwrap_or_else(|| "absent".to_string())
};
parts.push(format!(
"width {} -> {} dbu",
width(old.width),
width(new.width)
));
}
if old.bounds == new.bounds {
parts.push("coordinate bounds unchanged".to_string());
} else {
parts.push(format!(
"coordinate bounds {:?} -> {:?}",
old.bounds, new.bounds
));
}
parts.join("; ")
}

221
src/review/selection.rs Normal file
View file

@ -0,0 +1,221 @@
use super::*;
#[derive(Clone, Debug, Default, Eq, PartialEq)]
pub struct Scope {
pub top: Option<String>,
pub cell: Option<String>,
pub layer: Option<Layer>,
}
/// Presentation filters never modify comparison status, totals, or hierarchy.
#[derive(Clone, Debug, Default)]
pub struct DisplayFilter {
pub cell: Option<String>,
pub layer: Option<Layer>,
}
impl Scope {
pub fn description(&self) -> String {
let top = self
.top
.as_ref()
.map(|s| format!("{s:?}"))
.unwrap_or_else(|| "all".to_string());
let cell = self
.cell
.as_ref()
.map(|s| format!("{s:?}"))
.unwrap_or_else(|| "all".to_string());
let layer = self
.layer
.map(|(a, b)| format!("{a}/{b}"))
.unwrap_or_else(|| "all".to_string());
format!("scope top={top} cell={cell} layer={layer}")
}
pub fn validate_pair(&self, old: &Document<'_>, new: &Document<'_>) -> Result<(), String> {
for (kind, name) in [("top", &self.top), ("cell", &self.cell)] {
if let Some(name) = name {
if !old.cells.contains_key(name) && !new.cells.contains_key(name) {
return Err(format!(
"selected {kind} {name:?} exists in neither revision"
));
}
}
}
if let (Some(top), Some(cell)) = (&self.top, &self.cell) {
if !old.reachable(top).contains(cell) && !new.reachable(top).contains(cell) {
return Err(format!(
"selected cell {cell:?} is not reachable from {top:?}"
));
}
}
Ok(())
}
}
impl<'a> Document<'a> {
/// A missing Git revision has no cells or declarations. Retain the other
/// revision's library header to avoid inventing a unit/name change.
pub fn empty_like(&self) -> Self {
Self {
records: Vec::new(),
cells: BTreeMap::new(),
layer_names: BTreeMap::new(),
issues: Vec::new(),
header: self.header.clone(),
global_issues: Vec::new(),
known_cells: BTreeSet::new(),
scope: self.scope.clone(),
present: false,
}
}
fn reachable(&self, root: &str) -> BTreeSet<String> {
let mut found = BTreeSet::new();
let mut pending = vec![root.to_string()];
while let Some(name) = pending.pop() {
if let Some(cell) = self.cells.get(&name) {
if found.insert(name) {
pending.extend(cell.objects.iter().filter_map(|o| o.target.clone()));
}
}
}
found
}
pub(super) fn refresh_issues(&mut self) {
self.issues = self.global_issues.clone();
for (name, cell) in &self.cells {
for issue in cell
.issues
.iter()
.chain(cell.objects.iter().flat_map(|o| &o.issues))
{
self.issues.push(format!("cell {name:?}: {issue}"));
}
}
self.check_graph();
}
/// Project a parsed document. Missing selectors are allowed only for one
/// side of a comparison, after Scope::validate_pair has checked both sides.
pub fn selected(mut self, scope: &Scope, allow_missing: bool) -> Result<Self, String> {
if self.scope != Scope::default() {
return Err("document is already scoped; combine selectors in one Scope".to_string());
}
if !allow_missing {
scope.validate_pair(&self, &self)?;
}
let mut wanted = scope
.top
.as_ref()
.map(|t| self.reachable(t))
.unwrap_or_else(|| self.cells.keys().cloned().collect());
if let Some(cell) = &scope.cell {
wanted.retain(|n| n == cell);
}
// Determine layer coverage before projecting cells: exact-cell scopes
// still need to know whether a referenced definition uses this layer.
let relevant = scope.layer.map(|layer| {
let mut relevant: BTreeSet<_> = self
.cells
.iter()
.filter(|(_, c)| {
!c.issues.is_empty()
|| c.objects.iter().any(|o| {
!o.metadata
&& (o.layer == Some(layer)
|| (!o.issues.is_empty() && o.layer.is_none()))
})
})
.map(|(n, _)| n.clone())
.collect();
let mut parents = BTreeMap::<String, Vec<String>>::new();
for (parent, cell) in &self.cells {
for o in &cell.objects {
if let Some(target) = &o.target {
parents
.entry(target.clone())
.or_default()
.push(parent.clone());
if !self.known_cells.contains(target) {
relevant.insert(parent.clone());
}
}
}
}
let mut pending: Vec<_> = relevant.iter().cloned().collect();
// A cycle cannot be proven to have no effect on a layer. Preserve
// cycles (and their descendants) so graph validation remains visible.
let mut indegree: BTreeMap<_, usize> =
self.cells.keys().map(|n| (n.clone(), 0)).collect();
for cell in self.cells.values() {
for target in cell.objects.iter().filter_map(|o| o.target.as_ref()) {
if let Some(n) = indegree.get_mut(target) {
*n += 1;
}
}
}
let mut ready: Vec<_> = indegree
.iter()
.filter(|(_, n)| **n == 0)
.map(|(n, _)| n.clone())
.collect();
while let Some(name) = ready.pop() {
for target in self.cells[&name]
.objects
.iter()
.filter_map(|o| o.target.as_ref())
{
if let Some(n) = indegree.get_mut(target) {
*n -= 1;
if *n == 0 {
ready.push(target.clone());
}
}
}
}
for (name, _) in indegree.iter().filter(|(_, n)| **n != 0) {
if relevant.insert(name.clone()) {
pending.push(name.clone());
}
}
while let Some(child) = pending.pop() {
for parent in parents.get(&child).into_iter().flatten() {
if relevant.insert(parent.clone()) {
pending.push(parent.clone());
}
}
}
relevant
});
self.cells.retain(|name, _| {
wanted.contains(name) && relevant.as_ref().is_none_or(|r| r.contains(name))
});
if let (Some(layer), Some(relevant)) = (scope.layer, relevant) {
for cell in self.cells.values_mut() {
cell.objects.retain(|o| {
o.metadata
|| o.layer == Some(layer)
|| o.target
.as_ref()
.is_some_and(|t| relevant.contains(t) || !self.known_cells.contains(t))
|| (!o.issues.is_empty() && o.layer.is_none())
});
}
self.layer_names.retain(|pair, _| *pair == layer);
} else if scope.top.is_some() || scope.cell.is_some() {
let layers: BTreeSet<_> = self
.cells
.values()
.flat_map(|c| &c.objects)
.filter(|o| !o.metadata)
.filter_map(|o| o.layer)
.collect();
self.layer_names.retain(|pair, _| layers.contains(pair));
}
self.scope = scope.clone();
self.refresh_issues();
Ok(self)
}
}

View file

@ -1,4 +1,5 @@
profile klamath-object-v1
profile klamath-object-v2
scope top=all cell=all layer=all
coordinates: integer database units; bounds: coordinate envelopes
HEADER=[600]
LIBNAME="test"

View file

@ -0,0 +1,7 @@
profile klamath-object-v2
scope top=all cell=all layer=all
cell "CHIP" old@Some(62) new@Some(62)
~ BOUNDARY modified; coordinate bounds unchanged
- @98 bbox=Some([0, 0, 10, 10]) BOUNDARY layer=1 datatype=0 xy=[0, 0, 0, 10, 10, 10, 10, 0, 0, 0]
+ @98 bbox=Some([0, 0, 10, 10]) BOUNDARY layer=1 datatype=0 xy=[0, 0, 0, 10, 10, 0, 0, 0]
1 changed cells; 2 of 2 object changes shown; 0 layer-name changes

View file

@ -1,4 +1,5 @@
flowchart TD
%% scope top=all cell=all layer=all
n0["CHIP [affected]"]
n1["leaf [cell changed]"]
n2["left [affected]"]

View file

@ -1,3 +1,4 @@
scope top=all cell=all layer=all
"CHIP" x1 [affected]
"left" x1 [affected]
"leaf" x2 [cell changed]

View file

@ -421,6 +421,7 @@ fn shared_hierarchy_reports_ancestors_and_marks_repeated_definitions() {
assert_eq!(
hierarchy(&a, &b, Some(&diff), false, 8),
concat!(
"scope top=all cell=all layer=all\n",
"\"CHIP\" x1 [affected]\n",
" \"left\" x1 [affected]\n",
" \"leaf\" x2 [cell changed]\n",
@ -782,3 +783,464 @@ fn metadata_cli_creates_a_separate_file_and_refuses_existing_output() {
assert_eq!(fs::read(&output).unwrap(), generated);
fs::remove_dir_all(directory).unwrap();
}
#[test]
fn scope_selection_distinguishes_reachable_subtrees_from_exact_cells() {
use klamath_rs_ext::review::Scope;
let a = layout(&[
("CHIP", vec![reference("leaf", 0, 1)]),
("leaf", vec![square()]),
("unused", vec![square()]),
]);
let b = layout(&[
("CHIP", vec![reference("leaf", 0, 1)]),
("leaf", vec![triangle()]),
("unused", vec![triangle()]),
]);
let top = Scope {
top: Some("CHIP".to_string()),
..Scope::default()
};
let old = Document::parse(&a).unwrap().selected(&top, false).unwrap();
let new = Document::parse(&b).unwrap().selected(&top, false).unwrap();
assert_eq!(
old.cells.keys().map(String::as_str).collect::<Vec<_>>(),
["CHIP", "leaf"]
);
assert_eq!(Comparison::between(&old, &new).cells.len(), 1);
assert!(old.canonical_dump().contains("scope top=\"CHIP\""));
let cell = Scope {
cell: Some("CHIP".to_string()),
..Scope::default()
};
let old = Document::parse(&a).unwrap().selected(&cell, false).unwrap();
let new = Document::parse(&b).unwrap().selected(&cell, false).unwrap();
assert!(old.issues.is_empty());
assert!(Comparison::between(&old, &new).is_equal());
let missing = Scope {
top: Some("missing".to_string()),
..Scope::default()
};
assert!(
Document::parse(&a)
.unwrap()
.selected(&missing, false)
.is_err()
);
let wrong = Scope {
top: Some("CHIP".to_string()),
cell: Some("unused".to_string()),
layer: None,
};
assert!(
wrong
.validate_pair(&Document::parse(&a).unwrap(), &Document::parse(&b).unwrap())
.is_err()
);
}
#[test]
fn layer_scope_filters_geometry_and_references_by_descendant_coverage() {
use klamath_rs_ext::review::Scope;
let mut other_layer = square();
other_layer[8..10].copy_from_slice(&2_u16.to_be_bytes());
let a = layout(&[
(
"CHIP",
vec![reference("wg", 0, 1), reference("heater", 0, 1)],
),
("wg", vec![square()]),
("heater", vec![other_layer.clone()]),
]);
let b = layout(&[
(
"CHIP",
vec![reference("wg", 0, 1), reference("heater", 5, 1)],
),
("wg", vec![square()]),
("heater", vec![other_layer]),
]);
for (layer, expected) in [((1, 0), 0), ((2, 0), 1)] {
let scope = Scope {
layer: Some(layer),
..Scope::default()
};
let old = Document::parse(&a)
.unwrap()
.selected(&scope, false)
.unwrap();
let new = Document::parse(&b)
.unwrap()
.selected(&scope, false)
.unwrap();
assert_eq!(Comparison::between(&old, &new).exit_code(), expected);
assert!(old.issues.is_empty());
}
}
#[test]
fn scoped_issues_do_not_hide_relevant_unsupported_objects_or_cycles() {
use klamath_rs_ext::review::Scope;
let mut unknown = square();
unknown.truncate(unknown.len() - 4);
record(&mut unknown, 0x7f00, &[]);
record(&mut unknown, RTAG_ENDEL, &[]);
let bytes = layout(&[("CHIP", vec![square()]), ("unused", vec![unknown])]);
let scope = Scope {
cell: Some("CHIP".to_string()),
..Scope::default()
};
assert!(
Document::parse(&bytes)
.unwrap()
.selected(&scope, false)
.unwrap()
.issues
.is_empty()
);
let scope = Scope {
cell: Some("unused".to_string()),
..Scope::default()
};
assert!(
!Document::parse(&bytes)
.unwrap()
.selected(&scope, false)
.unwrap()
.issues
.is_empty()
);
let bytes = layout(&[
("a", vec![reference("b", 0, 1)]),
("b", vec![reference("a", 0, 1)]),
]);
let scope = Scope {
layer: Some((999, 0)),
..Scope::default()
};
assert!(
Document::parse(&bytes)
.unwrap()
.selected(&scope, false)
.unwrap()
.issues
.iter()
.any(|s| s.contains("cyclic"))
);
}
#[test]
fn display_filters_never_change_equality_or_totals() {
use klamath_rs_ext::review::DisplayFilter;
let a = layout(&[("CHIP", vec![square()])]);
let b = layout(&[("CHIP", vec![triangle()])]);
let diff = Comparison::between(&Document::parse(&a).unwrap(), &Document::parse(&b).unwrap());
let text = diff.text_filtered(
100,
&DisplayFilter {
cell: None,
layer: Some((42, 0)),
},
);
assert!(text.contains("display-only"));
assert!(text.contains("0 of 2 object changes shown"));
assert_eq!(diff.exit_code(), 1);
}
#[test]
fn git_external_driver_handles_changes_additions_deletions_and_errors() {
let directory = std::env::temp_dir().join(format!(
"klamath-git-review-{}-{}",
std::process::id(),
std::time::SystemTime::now()
.duration_since(std::time::UNIX_EPOCH)
.unwrap()
.as_nanos()
));
fs::create_dir_all(&directory).unwrap();
let inherited_path = std::env::var_os("PATH").unwrap_or_default();
let git_path = std::env::join_paths(
std::iter::once(
PathBuf::from(env!("CARGO_BIN_EXE_klamath"))
.parent()
.unwrap()
.to_path_buf(),
)
.chain(std::env::split_paths(&inherited_path)),
)
.unwrap();
let git = |args: &[&str]| {
let result = Command::new("git")
.env("PATH", &git_path)
.arg("-C")
.arg(&directory)
.args(args)
.output()
.unwrap();
assert!(
result.status.success(),
"git {args:?}: {}",
String::from_utf8_lossy(&result.stderr)
);
result
};
git(&["init", "-q"]);
git(&["config", "user.name", "Review Fixture"]);
git(&["config", "user.email", "fixture@example.invalid"]);
git(&["config", "commit.gpgsign", "false"]);
git(&["config", "core.hooksPath", "/dev/null"]);
git(&[
"config",
"include.path",
concat!(env!("CARGO_MANIFEST_DIR"), "/contrib/git/config"),
]);
assert_eq!(
String::from_utf8(git(&["config", "--get", "diff.klamath.trustExitCode"]).stdout)
.unwrap()
.trim(),
"false"
);
fs::write(
directory.join(".gitattributes"),
include_str!("../contrib/git/attributes"),
)
.unwrap();
let path = directory.join("chip layout.gds");
fs::write(&path, layout(&[("CHIP", vec![square()])])).unwrap();
git(&["add", "."]);
git(&["commit", "-qm", "baseline"]);
fs::write(&path, layout(&[("CHIP", vec![triangle()])])).unwrap();
let changed = git(&["diff", "--", "chip layout.gds"]);
assert!(
String::from_utf8(changed.stdout)
.unwrap()
.contains("2 of 2 object changes shown")
);
fs::write(&path, b"invalid").unwrap();
let invalid = Command::new("git")
.env("PATH", &git_path)
.arg("-C")
.arg(&directory)
.args(["diff", "--", "chip layout.gds"])
.output()
.unwrap();
assert!(!invalid.status.success());
assert!(String::from_utf8_lossy(&invalid.stderr).contains("klamath:"));
fs::write(&path, layout(&[("CHIP", vec![square()])])).unwrap();
let added = directory.join("added layout.gds");
fs::write(&added, shared(square())).unwrap();
git(&["add", "added layout.gds"]);
let result = git(&["diff", "--cached", "--", "added layout.gds"]);
assert!(
String::from_utf8(result.stdout)
.unwrap()
.contains("layout added")
);
fs::remove_file(&path).unwrap();
git(&["add", "-u"]);
let result = git(&["diff", "--cached", "--", "chip layout.gds"]);
assert!(
String::from_utf8(result.stdout)
.unwrap()
.contains("layout deleted")
);
// Textconv is an alternative to the external driver, with a separate cache.
git(&["commit", "-qm", "replace fixture"]);
git(&["mv", "added layout.gds", "renamed layout.gds"]);
let renamed = directory.join("renamed layout.gds");
fs::write(&renamed, shared(triangle())).unwrap();
git(&["add", "renamed layout.gds"]);
let result = git(&["diff", "--cached", "--find-renames"]);
let text = String::from_utf8(result.stdout).unwrap();
assert!(text.contains("renamed layout.gds"), "{text}");
assert!(text.contains("2 of 2 object changes shown"), "{text}");
git(&["commit", "-qm", "rename fixture"]);
fs::write(
directory.join(".gitattributes"),
"*.gds diff=klamath-text\n",
)
.unwrap();
fs::write(&renamed, shared(square())).unwrap();
let result = git(&["diff", "--", "renamed layout.gds"]);
assert!(
String::from_utf8(result.stdout)
.unwrap()
.contains("- BOUNDARY")
);
fs::remove_dir_all(directory).unwrap();
}
#[test]
fn replacement_explanations_are_unique_and_keep_full_evidence() {
for pair in corpus().into_iter().filter(|p| {
[
"same bounds different geometry",
"moved reference",
"array count",
]
.contains(&p.name)
}) {
let old = Document::parse(&pair.old).unwrap();
let new = Document::parse(&pair.new).unwrap();
let diff = Comparison::between(&old, &new);
assert_eq!(diff.cells[0].replacements.len(), 1);
let text = diff.text(100);
assert!(text.contains(" ~ "));
assert!(text.contains(" - @"));
assert!(text.contains(" + @"));
match pair.name {
"moved reference" => assert!(text.contains("delta=(5, 0) dbu")),
"array count" => assert!(text.contains("columns/rows 2 x 1 -> 3 x 1")),
_ => assert_eq!(text, include_str!("golden/review-diff.txt")),
}
assert!(!diff.text(0).contains(" ~ "));
assert!(diff.text(1).contains("1 of 2 object changes shown"));
}
let a = layout(&[("CHIP", vec![square(), square()])]);
let b = layout(&[("CHIP", vec![triangle(), triangle()])]);
let diff = Comparison::between(&Document::parse(&a).unwrap(), &Document::parse(&b).unwrap());
assert!(diff.cells[0].replacements.is_empty());
}
#[test]
fn path_width_explanation_preserves_absent_and_zero() {
let path = |width: Option<i32>| {
let mut bytes = Vec::new();
record(&mut bytes, RTAG_PATH, &[]);
record(&mut bytes, RTAG_LAYER, &[0, 1]);
record(&mut bytes, RTAG_DATATYPE, &[0, 0]);
if let Some(n) = width {
record(&mut bytes, RTAG_WIDTH, &n.to_be_bytes());
}
xy(&mut bytes, &[[0, 0], [10, 10]]);
record(&mut bytes, RTAG_ENDEL, &[]);
layout(&[("CHIP", vec![bytes])])
};
let a = path(None);
let b = path(Some(0));
let diff = Comparison::between(&Document::parse(&a).unwrap(), &Document::parse(&b).unwrap());
assert!(diff.text(100).contains("width absent -> 0 dbu"));
}
#[test]
fn unchanged_layer_names_explain_geometry_changes_once() {
let named = |geometry| {
layout(&[(
"CHIP",
vec![
geometry,
label((900, 7), LAYER_SENTINEL),
label((900, 7), "1:0:WG"),
],
)])
};
let a = named(square());
let b = named(triangle());
let diff = Comparison::between(&Document::parse(&a).unwrap(), &Document::parse(&b).unwrap());
let text = diff.text(100);
assert_eq!(text.matches("name=\"WG\"").count(), 1);
assert!(diff.layer_names.is_empty());
}
#[test]
fn an_added_empty_document_is_still_a_presence_change() {
let bytes = layout(&[]);
let doc = Document::parse(&bytes).unwrap();
let diff = Comparison::between(&doc.empty_like(), &doc);
assert_eq!(diff.exit_code(), 1);
assert!(diff.text(0).contains("library presence:"));
assert!(!diff.text(0).contains("equal under"));
}
#[test]
fn cli_scope_and_display_filters_have_distinct_exit_behavior() {
let directory = std::env::temp_dir().join(format!("klamath-scope-{}", std::process::id()));
fs::create_dir_all(&directory).unwrap();
let old = directory.join("old.gds");
let new = directory.join("new.gds");
fs::write(&old, shared(square())).unwrap();
fs::write(&new, shared(triangle())).unwrap();
for (options, expected) in [
(vec!["--cell", "CHIP"], 0),
(vec!["--top", "CHIP"], 1),
(vec!["--layer", "99/0"], 0),
(vec!["--show-cell", "missing"], 1),
(vec!["--show-layer", "99/0"], 1),
(vec!["--top", "missing"], 2),
] {
let output = Command::new(env!("CARGO_BIN_EXE_klamath"))
.arg("diff")
.args(&options)
.arg(&old)
.arg(&new)
.output()
.unwrap();
assert_eq!(
output.status.code(),
Some(expected),
"{options:?}: {}",
String::from_utf8_lossy(&output.stderr)
);
}
fs::write(&old, layout(&[])).unwrap();
let output = Command::new(env!("CARGO_BIN_EXE_klamath"))
.args(["diff", "--top", "CHIP"])
.arg(&old)
.arg(&new)
.output()
.unwrap();
assert_eq!(output.status.code(), Some(1));
fs::remove_dir_all(directory).unwrap();
}
#[test]
fn large_polygons_and_billion_instance_arrays_stay_compact() {
let mut points = vec![[0, 0], [0, 1]];
points.extend((1..8187).map(|x| [x, 1]));
points.extend([[8186, 0], [0, 0]]);
let mut array = Vec::new();
record(&mut array, RTAG_AREF, &[]);
ascii(&mut array, RTAG_SNAME, "leaf");
record(&mut array, RTAG_COLROW, &[0x7f, 0xff, 0x7f, 0xff]);
xy(&mut array, &[[0, 0], [32767, 0], [0, 32767]]);
record(&mut array, RTAG_ENDEL, &[]);
let bytes = layout(&[("CHIP", vec![array]), ("leaf", vec![polygon(&points)])]);
let doc = Document::parse(&bytes).unwrap();
assert_eq!(
doc.edges()[&("CHIP".to_string(), "leaf".to_string())],
32767 * 32767
);
assert_eq!(doc.cells["CHIP"].objects.len(), 1);
assert!(hierarchy(&doc, &doc, None, false, 8).len() < 200);
assert!(Comparison::between(&doc, &doc).is_equal());
}
#[test]
fn deep_hierarchy_comparison_and_rendering_are_iterative() {
let names: Vec<_> = (0..2048).map(|i| format!("cell_{i}")).collect();
let cells = |leaf: Vec<u8>| {
names
.iter()
.enumerate()
.map(|(i, name)| {
(
name.as_str(),
if i + 1 == names.len() {
vec![leaf.clone()]
} else {
vec![reference(&names[i + 1], 0, 1)]
},
)
})
.collect::<Vec<_>>()
};
let a = layout(&cells(square()));
let b = layout(&cells(triangle()));
let a = Document::parse(&a).unwrap();
let b = Document::parse(&b).unwrap();
let diff = Comparison::between(&a, &b);
let tree = hierarchy(&a, &b, Some(&diff), false, 5);
assert_eq!(diff.cells.len(), 1);
assert!(tree.contains("children omitted"));
assert!(tree.len() < 500);
}