feat(review): add deterministic GDS dumps and structural comparisons

Read embedded layer-name labels, retain unsupported records, and report affected hierarchy as ASCII or Mermaid. Preserve duplicate objects, canonicalize polygon rings, and cover the first profile with ten fixture pairs and golden outputs.
This commit is contained in:
Jan Petykiewicz 2026-11-14 17:25:04 -08:00
commit a04a955e90
8 changed files with 2160 additions and 0 deletions

View file

@ -53,3 +53,92 @@ the empty input. Nonempty buffers must be readable for the duration of the call;
range values must be aligned. Exported Arrow data owns its storage independently range values must be aligned. Exported Arrow data owns its storage independently
of the input. See [Arrow Schema Documentation](ARROW_SCHEMA.md) for the scan of the input. See [Arrow Schema Documentation](ARROW_SCHEMA.md) for the scan
schema, offset definitions, and ID assignment. schema, offset definitions, and ID assignment.
## Layout review CLI
The first review milestone provides a Rust CLI using the existing dependencies:
```sh
cargo build --bin klamath
target/debug/klamath dump chip.gds
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
```
The object dump is deterministic and omits source offsets. Record dumps preserve
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:
- Compares the entire library, matching cells by name and layers by numeric pair.
- 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.
- Compares paths, labels, references, array endpoints/counts, properties, and all
retained flags exactly. Explicit defaults and their omission remain distinct;
SREFs and single-element AREFs remain distinct. REAL8 encodings are retained.
- Reports library fields, including UNITS, separately. It does not rescale files
into a shared grid, infer cell renames, or perform geometric Boolean operations.
- Uses bounding boxes as coordinate envelopes, not evidence of equality. Path
envelopes do not include stroke width; text/reference envelopes are coordinates,
not rendered or recursively transformed bounds.
- Returns an incomplete result for unsupported records, future metadata versions,
unresolved references, or cycles. These cannot produce an equality claim.
`diff` exits with **0** for equality under this profile, **1** for differences,
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.
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,
including arrays, rather than expanded placements. Shared definitions are marked
as already shown in text and appear once in Mermaid. `--depth` limits displayed
descendants only. The CLI emits Mermaid source, requiring no diagram renderer.
Layer names are read from labels in an existing cell. A label with the exact
string `KLAMATH_LAYER_NAMES_V1` identifies an annotation carrier `(layer, texttype)`
pair within that cell. All other labels on that same pair in that same cell must
be `layer:datatype:name` declarations, for example `1:0:WG`. The carrier pair is
not fixed; choose a suitable annotation layer in the design's technology.
Declarations split at the first two colons, allowing colons in names. Numeric
fields are unsigned 16-bit decimal integers. Names are nonempty UTF-8 strings.
Repeated identical declarations are accepted; conflicting declarations fail.
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.
After installing the executable on PATH, the canonical dump can serve as a Git
textconv. Add this attribute to the layout repository:
```gitattributes
*.gds diff=klamath
```
Configure the driver in Git config:
```gitconfig
[diff "klamath"]
textconv = klamath dump
binary = true
cachetextconv = true
```
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.

139
src/bin/klamath.rs Normal file
View file

@ -0,0 +1,139 @@
use klamath_rs_ext::review::{Comparison, Document, dump_records, hierarchy};
use std::{
ffi::OsString,
fs,
io::{self, Write},
process::ExitCode,
};
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]
Object profile: ignore timestamps and element order, normalize polygon start/winding,
preserve duplicates, compare all retained fields exactly. No geometric XOR or tolerance.
Exit status: 0 equal/success, 1 different, 2 invalid/unsupported/incomplete.
";
fn value(args: &[OsString], index: &mut usize) -> Result<String, String> {
*index += 1;
args.get(*index)
.and_then(|s| s.to_str())
.map(str::to_owned)
.ok_or_else(|| "missing UTF-8 option value".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}");
return Ok(0);
}
let command = args[0].to_str().ok_or("invalid command")?;
let paths = match command {
"dump" | "hierarchy" => 1,
"diff" => 2,
_ => return Err(HELP.to_string()),
};
if args.len() <= paths {
return Err(HELP.to_string());
}
let mut raw = false;
let mut format = if command == "diff" {
"none".to_string()
} else {
"ascii".to_string()
};
let mut max_changes = 100;
let mut depth = 8;
let mut i = paths + 1;
while i < args.len() {
match args[i].to_str() {
Some("--records") if command == "dump" => raw = true,
Some("--hierarchy") if command == "diff" => format = value(&args, &mut i)?,
Some("--format") if command == "hierarchy" => format = value(&args, &mut i)?,
Some("--max-changes") if command == "diff" => {
max_changes = value(&args, &mut i)?
.parse()
.map_err(|_| "invalid change limit")?
}
Some("--depth") if command != "dump" => {
depth = value(&args, &mut i)?.parse().map_err(|_| "invalid depth")?
}
_ => return Err(format!("unknown option {:?}\n{HELP}", args[i])),
}
i += 1;
}
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]))?;
if raw {
io::stdout()
.lock()
.write_all(dump_records(&old_bytes)?.as_bytes())
.map_err(|e| e.to_string())?;
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}");
}
}
(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!(),
};
io::stdout()
.lock()
.write_all(output.as_bytes())
.map_err(|e| e.to_string())?;
Ok(status)
}
fn main() -> ExitCode {
match run() {
Ok(status) => ExitCode::from(status),
Err(message) => {
eprintln!("klamath: {message}");
ExitCode::from(2)
}
}
}

View file

@ -5,6 +5,7 @@ pub mod record;
pub mod records; pub mod records;
pub mod elements; pub mod elements;
pub mod library; pub mod library;
pub mod review;
use crate::library::{read_library, read_selected_library, scan_library}; use crate::library::{read_library, read_selected_library, scan_library};

1241
src/review.rs Normal file

File diff suppressed because it is too large Load diff

View file

@ -0,0 +1,8 @@
profile klamath-object-v1
coordinates: integer database units; bounds: coordinate envelopes
HEADER=[600]
LIBNAME="test"
UNITS=[0.001, 9.999999999999999e-10] raw=0x3f04189374bc6a7f3a044b82fa09b5a5
layer 1/0 name="WG"
cell "CHIP"
BOUNDARY layer=1 datatype=0 xy=[0, 0, 0, 10, 10, 10, 10, 0, 0, 0]

View file

@ -0,0 +1,9 @@
flowchart TD
n0["CHIP [affected]"]
n1["leaf [cell changed]"]
n2["left [affected]"]
n3["right [affected]"]
n0 -->|"x1"| n2
n0 -->|"x1"| n3
n2 -->|"x2"| n1
n3 -->|"x3"| n1

View file

@ -0,0 +1,5 @@
"CHIP" x1 [affected]
"left" x1 [affected]
"leaf" x2 [cell changed]
"right" x1 [affected]
"leaf" x3 [cell changed] [shown above]

668
tests/review.rs Normal file
View file

@ -0,0 +1,668 @@
mod common;
use common::{library_header, record};
use klamath_rs_ext::{
records::*,
review::{Comparison, Document, LAYER_SENTINEL, hierarchy},
};
use std::{fs, path::PathBuf, process::Command};
fn ascii(bytes: &mut Vec<u8>, tag: u16, value: &str) {
let mut value = value.as_bytes().to_vec();
if value.len() % 2 == 1 {
value.push(0);
}
record(bytes, tag, &value);
}
fn xy(bytes: &mut Vec<u8>, points: &[[i32; 2]]) {
record(
bytes,
RTAG_XY,
&points
.iter()
.flatten()
.flat_map(|v| v.to_be_bytes())
.collect::<Vec<_>>(),
);
}
fn layout(cells: &[(&str, Vec<Vec<u8>>)]) -> Vec<u8> {
let mut bytes = library_header();
for (name, objects) in cells {
record(&mut bytes, RTAG_BGNSTR, &[0; 24]);
ascii(&mut bytes, RTAG_STRNAME, name);
for object in objects {
bytes.extend_from_slice(object);
}
record(&mut bytes, RTAG_ENDSTR, &[]);
}
record(&mut bytes, RTAG_ENDLIB, &[]);
bytes
}
fn polygon(points: &[[i32; 2]]) -> Vec<u8> {
let mut bytes = Vec::new();
record(&mut bytes, RTAG_BOUNDARY, &[]);
record(&mut bytes, RTAG_LAYER, &1_u16.to_be_bytes());
record(&mut bytes, RTAG_DATATYPE, &0_u16.to_be_bytes());
xy(&mut bytes, points);
record(&mut bytes, RTAG_ENDEL, &[]);
bytes
}
fn square() -> Vec<u8> {
polygon(&[[0, 0], [10, 0], [10, 10], [0, 10], [0, 0]])
}
fn triangle() -> Vec<u8> {
polygon(&[[0, 0], [10, 0], [0, 10], [0, 0]])
}
fn reference(target: &str, x: i32, count: i16) -> Vec<u8> {
let mut bytes = Vec::new();
record(
&mut bytes,
if count == 1 { RTAG_SREF } else { RTAG_AREF },
&[],
);
ascii(&mut bytes, RTAG_SNAME, target);
if count == 1 {
xy(&mut bytes, &[[x, 0]]);
} else {
let counts: Vec<_> = [count, 1].into_iter().flat_map(i16::to_be_bytes).collect();
record(&mut bytes, RTAG_COLROW, &counts);
xy(&mut bytes, &[[x, 0], [x + 100, 0], [x, 0]]);
}
record(&mut bytes, RTAG_ENDEL, &[]);
bytes
}
fn label(carrier: (u16, u16), text: &str) -> Vec<u8> {
let mut bytes = Vec::new();
record(&mut bytes, RTAG_TEXT, &[]);
record(&mut bytes, RTAG_LAYER, &carrier.0.to_be_bytes());
record(&mut bytes, RTAG_TEXTTYPE, &carrier.1.to_be_bytes());
xy(&mut bytes, &[[0, 0]]);
ascii(&mut bytes, RTAG_STRING, text);
record(&mut bytes, RTAG_ENDEL, &[]);
bytes
}
fn with_property(mut object: Vec<u8>, value: &str) -> Vec<u8> {
object.truncate(object.len() - 4);
record(&mut object, RTAG_PROPATTR, &17_u16.to_be_bytes());
ascii(&mut object, RTAG_PROPVALUE, value);
record(&mut object, RTAG_ENDEL, &[]);
object
}
fn shared(geometry: Vec<u8>) -> Vec<u8> {
layout(&[
(
"CHIP",
vec![reference("left", 0, 1), reference("right", 20, 1)],
),
("left", vec![reference("leaf", 0, 2)]),
("right", vec![reference("leaf", 0, 3)]),
("leaf", vec![geometry]),
])
}
struct Pair {
name: &'static str,
old: Vec<u8>,
new: Vec<u8>,
changed_cells: usize,
removed: usize,
added: usize,
metadata: usize,
}
// Ten deliberately small fixture pairs specify the first object profile.
fn corpus() -> Vec<Pair> {
let base = layout(&[("CHIP", vec![square(), label((2, 0), "port")])]);
let mut timestamps = base.clone();
timestamps[10] = 1; // BGNLIB payload, ignored by the object profile.
let meta = |name| {
layout(&[(
"CHIP",
vec![
square(),
label((900, 7), LAYER_SENTINEL),
label((900, 7), name),
],
)])
};
vec![
Pair {
name: "record reordering",
old: base.clone(),
new: layout(&[("CHIP", vec![label((2, 0), "port"), square()])]),
changed_cells: 0,
removed: 0,
added: 0,
metadata: 0,
},
Pair {
name: "timestamp edit",
old: base,
new: timestamps,
changed_cells: 0,
removed: 0,
added: 0,
metadata: 0,
},
Pair {
name: "polygon start and winding",
old: layout(&[("CHIP", vec![square()])]),
new: layout(&[(
"CHIP",
vec![polygon(&[[10, 10], [10, 0], [0, 0], [0, 10], [10, 10]])],
)]),
changed_cells: 0,
removed: 0,
added: 0,
metadata: 0,
},
Pair {
name: "duplicate shape",
old: layout(&[("CHIP", vec![square()])]),
new: layout(&[("CHIP", vec![square(), square()])]),
changed_cells: 1,
removed: 0,
added: 1,
metadata: 0,
},
Pair {
name: "same bounds different geometry",
old: layout(&[("CHIP", vec![square()])]),
new: layout(&[("CHIP", vec![triangle()])]),
changed_cells: 1,
removed: 1,
added: 1,
metadata: 0,
},
Pair {
name: "moved reference",
old: layout(&[
("CHIP", vec![reference("leaf", 0, 1)]),
("leaf", vec![square()]),
]),
new: layout(&[
("CHIP", vec![reference("leaf", 5, 1)]),
("leaf", vec![square()]),
]),
changed_cells: 1,
removed: 1,
added: 1,
metadata: 0,
},
Pair {
name: "array count",
old: layout(&[
("CHIP", vec![reference("leaf", 0, 2)]),
("leaf", vec![square()]),
]),
new: layout(&[
("CHIP", vec![reference("leaf", 0, 3)]),
("leaf", vec![square()]),
]),
changed_cells: 1,
removed: 1,
added: 1,
metadata: 0,
},
Pair {
name: "element property",
old: layout(&[("CHIP", vec![with_property(square(), "old")])]),
new: layout(&[("CHIP", vec![with_property(square(), "new")])]),
changed_cells: 1,
removed: 1,
added: 1,
metadata: 0,
},
Pair {
name: "layer name only",
old: meta("1:0:WG"),
new: meta("1:0:CORE:WG"),
changed_cells: 0,
removed: 0,
added: 0,
metadata: 1,
},
Pair {
name: "shared changed descendant",
old: shared(square()),
new: shared(triangle()),
changed_cells: 1,
removed: 1,
added: 1,
metadata: 0,
},
]
}
#[test]
fn ten_fixture_pairs_have_explicit_expected_changes() {
for pair in corpus() {
let old = Document::parse(&pair.old).unwrap();
let new = Document::parse(&pair.new).unwrap();
let diff = Comparison::between(&old, &new);
assert!(diff.issues.is_empty(), "{}: {:?}", pair.name, diff.issues);
assert_eq!(diff.cells.len(), pair.changed_cells, "{}", pair.name);
assert_eq!(
diff.cells.iter().map(|c| c.removed.len()).sum::<usize>(),
pair.removed,
"{}",
pair.name
);
assert_eq!(
diff.cells.iter().map(|c| c.added.len()).sum::<usize>(),
pair.added,
"{}",
pair.name
);
assert_eq!(diff.layer_names.len(), pair.metadata, "{}", pair.name);
let equal = pair.changed_cells + pair.metadata == 0;
assert_eq!(diff.is_equal(), equal, "{}", pair.name);
assert_eq!(
old.canonical_dump() == new.canonical_dump(),
equal,
"{}",
pair.name
);
assert_eq!(diff.exit_code(), if equal { 0 } else { 1 });
}
}
#[test]
fn canonical_polygon_dump_is_readable_and_offsets_are_separate() {
let bytes = layout(&[("CHIP", vec![square()])]);
let doc = Document::parse(&bytes).unwrap();
let dump = doc.canonical_dump();
assert!(
dump.ends_with(
"cell \"CHIP\"\n BOUNDARY layer=1 datatype=0 xy=[0, 0, 0, 10, 10, 10, 10, 0, 0, 0]\n"
),
"{dump}"
);
assert!(!dump.contains("BGNSTR"));
assert!(
doc.record_dump()
.contains("0000000000 0002 HEADER size=6 [600]")
);
assert!(doc.record_dump().contains("BGNSTR"));
}
#[test]
fn canonical_dump_and_hierarchy_match_versioned_goldens() {
let bytes = layout(&[(
"CHIP",
vec![
square(),
label((900, 7), LAYER_SENTINEL),
label((900, 7), "1:0:WG"),
],
)]);
assert_eq!(
Document::parse(&bytes).unwrap().canonical_dump(),
include_str!("golden/review-canonical.txt")
);
let a = shared(square());
let b = shared(triangle());
let a = Document::parse(&a).unwrap();
let b = Document::parse(&b).unwrap();
let diff = Comparison::between(&a, &b);
assert_eq!(
hierarchy(&a, &b, Some(&diff), false, 8),
include_str!("golden/review-hierarchy.txt")
);
assert_eq!(
hierarchy(&a, &b, Some(&diff), true, 8),
include_str!("golden/review-hierarchy.mmd")
);
}
#[test]
fn misplaced_library_fields_and_nul_names_are_rejected() {
let mut late = layout(&[("CHIP", vec![])]);
late.truncate(late.len() - 4);
ascii(&mut late, RTAG_LIBNAME, "late");
record(&mut late, RTAG_ENDLIB, &[]);
assert!(
Document::parse(&late)
.unwrap_err()
.contains("library field outside")
);
assert!(
Document::parse(&layout(&[("CH\0IP", vec![])]))
.unwrap_err()
.contains("NUL")
);
}
#[test]
fn cell_and_property_order_do_not_affect_comparison() {
let a = with_property(with_property(square(), "a"), "b");
let b = with_property(with_property(square(), "b"), "a");
let a = layout(&[("z", vec![a]), ("a", vec![])]);
let b = layout(&[("a", vec![]), ("z", vec![b])]);
let a = Document::parse(&a).unwrap();
let b = Document::parse(&b).unwrap();
assert!(Comparison::between(&a, &b).is_equal());
assert_eq!(a.canonical_dump(), b.canonical_dump());
}
#[test]
fn metadata_requires_a_sentinel_in_the_same_cell_and_carrier_pair() {
let bytes = layout(&[
(
"CHIP",
vec![
label((900, 7), LAYER_SENTINEL),
label((900, 7), "1:0:WG"),
label((900, 8), "2:0:ordinary text"),
],
),
("OTHER", vec![label((900, 7), "3:0:ordinary text")]),
]);
let doc = Document::parse(&bytes).unwrap();
assert_eq!(doc.layer_names.len(), 1);
assert_eq!(doc.layer_names.get(&(1, 0)).unwrap(), "WG");
assert!(doc.canonical_dump().contains("2:0:ordinary text"));
assert!(doc.canonical_dump().contains("3:0:ordinary text"));
assert!(!doc.canonical_dump().contains(LAYER_SENTINEL));
let conflicts = layout(&[(
"CHIP",
vec![
label((9, 0), LAYER_SENTINEL),
label((9, 0), "1:0:A"),
label((9, 0), "1:0:B"),
],
)]);
assert!(
Document::parse(&conflicts)
.unwrap_err()
.contains("conflicting names")
);
assert!(
klamath_rs_ext::review::dump_records(&conflicts)
.unwrap()
.contains("1:0:B")
);
let future = layout(&[("CHIP", vec![label((9, 0), "KLAMATH_LAYER_NAMES_V2")])]);
let future = Document::parse(&future).unwrap();
assert_eq!(Comparison::between(&future, &future).exit_code(), 2);
}
#[test]
fn unknown_records_never_produce_a_successful_equality_claim() {
let mut unknown = square();
unknown.truncate(unknown.len() - 4);
record(&mut unknown, 0x7f00, &[]);
record(&mut unknown, RTAG_ENDEL, &[]);
let bytes = layout(&[("CHIP", vec![unknown])]);
let doc = Document::parse(&bytes).unwrap();
let diff = Comparison::between(&doc, &doc);
assert!(!diff.is_equal());
assert_eq!(diff.exit_code(), 2);
assert!(doc.record_dump().contains("7f00"));
assert!(diff.text(0).contains("INCOMPLETE"));
}
#[test]
fn shared_hierarchy_reports_ancestors_and_marks_repeated_definitions() {
let a = shared(square());
let b = shared(triangle());
let a = Document::parse(&a).unwrap();
let b = Document::parse(&b).unwrap();
let diff = Comparison::between(&a, &b);
assert_eq!(
hierarchy(&a, &b, Some(&diff), false, 8),
concat!(
"\"CHIP\" x1 [affected]\n",
" \"left\" x1 [affected]\n",
" \"leaf\" x2 [cell changed]\n",
" \"right\" x1 [affected]\n",
" \"leaf\" x3 [cell changed] [shown above]\n",
)
);
let graph = hierarchy(&a, &b, Some(&diff), true, 8);
assert_eq!(graph.matches("leaf [cell changed]").count(), 1);
assert!(graph.contains("x2"));
assert!(graph.contains("x3"));
let limited = hierarchy(&a, &b, Some(&diff), false, 1);
assert!(!limited.contains("\"leaf\""));
assert!(limited.contains("children omitted"));
}
#[test]
fn reference_changes_keep_unchanged_targets_and_old_edges_visible() {
for pair in corpus()
.into_iter()
.filter(|p| p.name == "moved reference" || p.name == "array count")
{
let old = Document::parse(&pair.old).unwrap();
let new = Document::parse(&pair.new).unwrap();
let diff = Comparison::between(&old, &new);
let tree = hierarchy(&old, &new, Some(&diff), false, 8);
assert!(tree.contains("[cell unchanged]"), "{tree}");
assert!(tree.contains("[reference changed]"), "{tree}");
if pair.name == "array count" {
assert!(tree.contains("x2 -> x3"), "{tree}");
}
}
let a = layout(&[
("CHIP", vec![reference("leaf", 0, 1)]),
("leaf", vec![square()]),
]);
let b = layout(&[("CHIP", vec![])]);
let a = Document::parse(&a).unwrap();
let b = Document::parse(&b).unwrap();
let tree = hierarchy(&a, &b, Some(&Comparison::between(&a, &b)), false, 8);
assert!(tree.contains("\"leaf\" x1 -> x0"), "{tree}");
}
#[test]
fn same_bounds_changes_and_truncated_reports_remain_differences() {
let a = layout(&[("CHIP", vec![square()])]);
let b = layout(&[("CHIP", vec![triangle()])]);
let a = Document::parse(&a).unwrap();
let b = Document::parse(&b).unwrap();
let diff = Comparison::between(&a, &b);
assert_eq!(
diff.cells[0].removed[0].bounds,
diff.cells[0].added[0].bounds
);
assert!(diff.text(0).contains("0 of 2 object changes shown"));
assert_eq!(diff.exit_code(), 1);
assert!(diff.cells[0].removed[0].offset > 0);
}
#[test]
fn unit_changes_report_values_without_claiming_geometry_equivalence() {
let a = layout(&[("CHIP", vec![square()])]);
let units = Document::parse(&a)
.unwrap()
.records
.iter()
.find(|r| r.tag == RTAG_UNITS)
.unwrap()
.offset;
let mut b = a.clone();
b[units + 12..units + 20].copy_from_slice(
&klamath_rs_ext::basic::encode_real8(2e-9)
.unwrap()
.to_be_bytes(),
);
let a = Document::parse(&a).unwrap();
let b = Document::parse(&b).unwrap();
let diff = Comparison::between(&a, &b);
assert_eq!(diff.exit_code(), 1);
assert_eq!(diff.library_fields.len(), 1);
assert_eq!(diff.library_fields[0].field, "UNITS");
assert!(diff.text(0).contains("UNITS changed"));
assert!(diff.cells.is_empty());
}
#[test]
fn dangling_references_cycles_and_duplicate_cell_names_are_reported() {
let missing = layout(&[("CHIP", vec![reference("missing", 0, 1)])]);
let missing = Document::parse(&missing).unwrap();
assert!(
missing
.issues
.iter()
.any(|s| s.contains("unresolved reference"))
);
let cycle = layout(&[
("a", vec![reference("b", 0, 1)]),
("b", vec![reference("a", 0, 1)]),
]);
let cycle = Document::parse(&cycle).unwrap();
assert!(cycle.issues.iter().any(|s| s.contains("cyclic")));
assert!(hierarchy(&cycle, &cycle, None, false, 8).len() < 200);
let duplicate = layout(&[("a", vec![]), ("a", vec![])]);
assert!(
Document::parse(&duplicate)
.unwrap_err()
.contains("duplicate cell")
);
}
#[test]
fn absolute_transform_flags_are_not_discarded() {
let a = reference("leaf", 0, 1);
let mut b = Vec::new();
record(&mut b, RTAG_SREF, &[]);
ascii(&mut b, RTAG_SNAME, "leaf");
record(&mut b, RTAG_STRANS, &[0, 2]);
xy(&mut b, &[[0, 0]]);
record(&mut b, RTAG_ENDEL, &[]);
let a = layout(&[("CHIP", vec![a]), ("leaf", vec![])]);
let b = layout(&[("CHIP", vec![b]), ("leaf", vec![])]);
assert_eq!(
Comparison::between(&Document::parse(&a).unwrap(), &Document::parse(&b).unwrap())
.exit_code(),
1
);
}
#[test]
fn polygon_normalization_handles_repeated_minimum_vertices() {
let ring = [[0, 0], [4, 0], [4, 4], [0, 0], [-2, 2], [-2, 4], [0, 0]];
let baseline = layout(&[("CHIP", vec![polygon(&ring)])]);
let baseline = Document::parse(&baseline).unwrap();
let mut open = ring[..ring.len() - 1].to_vec();
for _ in 0..2 {
for start in 0..open.len() {
let mut rotated = open[start..]
.iter()
.chain(&open[..start])
.copied()
.collect::<Vec<_>>();
rotated.push(rotated[0]);
let candidate = layout(&[("CHIP", vec![polygon(&rotated)])]);
let candidate = Document::parse(&candidate).unwrap();
assert!(Comparison::between(&baseline, &candidate).is_equal());
}
open.reverse();
}
}
#[test]
fn malformed_lengths_fields_and_units_return_errors_without_panicking() {
let good = layout(&[("CHIP", vec![square()])]);
for length in 0..good.len() {
assert!(
Document::parse(&good[..length]).is_err(),
"accepted truncated length {length}"
);
}
let mut bad = good.clone();
bad[0..2].copy_from_slice(&3_u16.to_be_bytes());
assert!(Document::parse(&bad).is_err());
let mut bad = good.clone();
let units = Document::parse(&good)
.unwrap()
.records
.iter()
.find(|r| r.tag == RTAG_UNITS)
.unwrap()
.offset;
bad[units + 4..units + 20].fill(0);
assert!(Document::parse(&bad).unwrap_err().contains("UNITS"));
let mut polygon = square();
polygon.truncate(polygon.len() - 4);
record(&mut polygon, RTAG_LAYER, &[0, 1]);
record(&mut polygon, RTAG_ENDEL, &[]);
assert!(
Document::parse(&layout(&[("CHIP", vec![polygon])]))
.unwrap_err()
.contains("duplicate element field")
);
}
#[test]
fn cli_uses_documented_exit_codes_and_accepts_paths_with_spaces() {
let directory = std::env::temp_dir().join(format!("klamath review {}", std::process::id()));
fs::create_dir_all(&directory).unwrap();
struct Cleanup(PathBuf);
impl Drop for Cleanup {
fn drop(&mut self) {
let _ = fs::remove_dir_all(&self.0);
}
}
let _cleanup = Cleanup(directory.clone());
let old = directory.join("old file.gds");
let new = directory.join("new file.gds");
fs::write(&old, shared(square())).unwrap();
fs::write(&new, shared(triangle())).unwrap();
let command = || Command::new(env!("CARGO_BIN_EXE_klamath"));
let equal = command().arg("diff").arg(&old).arg(&old).output().unwrap();
assert_eq!(equal.status.code(), Some(0));
let diff = command()
.arg("diff")
.arg(&old)
.arg(&new)
.args(["--hierarchy", "mermaid", "--max-changes", "0"])
.output()
.unwrap();
assert_eq!(diff.status.code(), Some(1));
let text = String::from_utf8(diff.stdout).unwrap();
assert!(text.contains("0 of 2 object changes shown"));
assert!(text.contains("```mermaid\nflowchart TD"));
let dump = command()
.arg("dump")
.arg(&old)
.args(["--records"])
.output()
.unwrap();
assert_eq!(dump.status.code(), Some(0));
assert!(String::from_utf8(dump.stdout).unwrap().contains("BGNSTR"));
let graph = command()
.arg("hierarchy")
.arg(&old)
.args(["--format", "mermaid"])
.output()
.unwrap();
assert_eq!(graph.status.code(), Some(0));
assert!(
String::from_utf8(graph.stdout)
.unwrap()
.starts_with("flowchart TD")
);
fs::write(&new, b"invalid").unwrap();
assert_eq!(
command()
.arg("diff")
.arg(&old)
.arg(&new)
.output()
.unwrap()
.status
.code(),
Some(2)
);
}