diff --git a/README.md b/README.md index 2f368b1..2eb673a 100644 --- a/README.md +++ b/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. diff --git a/contrib/git/attributes b/contrib/git/attributes new file mode 100644 index 0000000..051952d --- /dev/null +++ b/contrib/git/attributes @@ -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 diff --git a/contrib/git/config b/contrib/git/config new file mode 100644 index 0000000..2852e9a --- /dev/null +++ b/contrib/git/config @@ -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 diff --git a/src/bin/klamath.rs b/src/bin/klamath.rs index 11e791f..5dc0c21 100644 --- a/src/bin/klamath.rs +++ b/src/bin/klamath.rs @@ -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 { 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 { 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 { 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 { diff --git a/src/review.rs b/src/review.rs index a677210..4ee01fd 100644 --- a/src/review.rs +++ b/src/review.rs @@ -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, } impl Object<'_> { @@ -71,6 +76,7 @@ pub struct Cell<'a> { pub end_offset: usize, pub objects: Vec>, attributes: Vec<(u16, &'a [u8])>, + issues: Vec, } #[derive(Debug)] @@ -81,6 +87,10 @@ pub struct Document<'a> { /// Unsupported features or invalid reference graphs prevent an equality claim. pub issues: Vec, header: Vec<(u16, &'a [u8])>, + global_issues: Vec, + known_cells: BTreeSet, + 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) -> Result 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, pub bounds: Option, pub target: Option, + pub origin: Option<[i32; 2]>, + pub width: Option, + 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, pub added: Vec, + pub replacements: Vec, } #[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, pub library_fields: Vec, pub layer_names: Vec, pub cells: Vec, @@ -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)) diff --git a/src/review/changes.rs b/src/review/changes.rs new file mode 100644 index 0000000..c962766 --- /dev/null +++ b/src/review/changes.rs @@ -0,0 +1,117 @@ +use super::*; + +#[derive(Debug)] +pub struct Replacement { + pub removed: usize, + pub added: usize, + pub explanation: String, +} + +type Group = (u16, Option, Option, Option); + +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 { + 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::>::new(), + BTreeMap::>::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| { + 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("; ") +} diff --git a/src/review/selection.rs b/src/review/selection.rs new file mode 100644 index 0000000..42e09f2 --- /dev/null +++ b/src/review/selection.rs @@ -0,0 +1,221 @@ +use super::*; + +#[derive(Clone, Debug, Default, Eq, PartialEq)] +pub struct Scope { + pub top: Option, + pub cell: Option, + pub layer: Option, +} + +/// Presentation filters never modify comparison status, totals, or hierarchy. +#[derive(Clone, Debug, Default)] +pub struct DisplayFilter { + pub cell: Option, + pub layer: Option, +} + +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 { + 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 { + 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::>::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) + } +} diff --git a/tests/golden/review-canonical.txt b/tests/golden/review-canonical.txt index 3cd359a..3cdc7ea 100644 --- a/tests/golden/review-canonical.txt +++ b/tests/golden/review-canonical.txt @@ -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" diff --git a/tests/golden/review-diff.txt b/tests/golden/review-diff.txt new file mode 100644 index 0000000..57e6c09 --- /dev/null +++ b/tests/golden/review-diff.txt @@ -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 diff --git a/tests/golden/review-hierarchy.mmd b/tests/golden/review-hierarchy.mmd index 86cffd6..dcc963b 100644 --- a/tests/golden/review-hierarchy.mmd +++ b/tests/golden/review-hierarchy.mmd @@ -1,4 +1,5 @@ flowchart TD + %% scope top=all cell=all layer=all n0["CHIP [affected]"] n1["leaf [cell changed]"] n2["left [affected]"] diff --git a/tests/golden/review-hierarchy.txt b/tests/golden/review-hierarchy.txt index b6a0f97..fa40d79 100644 --- a/tests/golden/review-hierarchy.txt +++ b/tests/golden/review-hierarchy.txt @@ -1,3 +1,4 @@ +scope top=all cell=all layer=all "CHIP" x1 [affected] "left" x1 [affected] "leaf" x2 [cell changed] diff --git a/tests/review.rs b/tests/review.rs index be34f07..829eeb5 100644 --- a/tests/review.rs +++ b/tests/review.rs @@ -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::>(), + ["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| { + 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| { + 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::>() + }; + 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); +}