From a04a955e9077673c75a0195744816827ee9f6205 Mon Sep 17 00:00:00 2001 From: Jan Petykiewicz Date: Sat, 14 Nov 2026 17:25:04 -0800 Subject: [PATCH] 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. --- README.md | 89 +++ src/bin/klamath.rs | 139 ++++ src/lib.rs | 1 + src/review.rs | 1241 +++++++++++++++++++++++++++++ tests/golden/review-canonical.txt | 8 + tests/golden/review-hierarchy.mmd | 9 + tests/golden/review-hierarchy.txt | 5 + tests/review.rs | 668 ++++++++++++++++ 8 files changed, 2160 insertions(+) create mode 100644 src/bin/klamath.rs create mode 100644 src/review.rs create mode 100644 tests/golden/review-canonical.txt create mode 100644 tests/golden/review-hierarchy.mmd create mode 100644 tests/golden/review-hierarchy.txt create mode 100644 tests/review.rs diff --git a/README.md b/README.md index e5a43a7..2f368b1 100644 --- a/README.md +++ b/README.md @@ -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 of the input. See [Arrow Schema Documentation](ARROW_SCHEMA.md) for the scan 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. diff --git a/src/bin/klamath.rs b/src/bin/klamath.rs new file mode 100644 index 0000000..6cfad4a --- /dev/null +++ b/src/bin/klamath.rs @@ -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 { + *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 { + 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) + } + } +} diff --git a/src/lib.rs b/src/lib.rs index d188a56..0698e3e 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -5,6 +5,7 @@ pub mod record; pub mod records; pub mod elements; pub mod library; +pub mod review; use crate::library::{read_library, read_selected_library, scan_library}; diff --git a/src/review.rs b/src/review.rs new file mode 100644 index 0000000..961d097 --- /dev/null +++ b/src/review.rs @@ -0,0 +1,1241 @@ +//! Deterministic GDS object review without the normalization performed by the +//! Arrow reader. Raw payloads borrow the file; only polygon keys are copied. + +use crate::{basic::decode_real8, record::RecordHeader, records::*}; +use std::{ + borrow::Cow, + collections::{BTreeMap, BTreeSet}, + fmt::Write, +}; + +pub const PROFILE: &str = "klamath-object-v1"; +pub const LAYER_SENTINEL: &str = "KLAMATH_LAYER_NAMES_V1"; +pub type Layer = (u16, u16); +pub type Bounds = [i32; 4]; + +#[derive(Clone, Debug)] +pub struct Record<'a> { + pub offset: usize, + pub tag: u16, + pub data: &'a [u8], +} + +#[derive(Clone, Debug, Eq, PartialEq, Ord, PartialOrd)] +struct Key<'a> { + kind: u16, + fields: Vec<(u16, Cow<'a, [u8]>)>, + properties: Vec<(u16, &'a [u8])>, +} + +#[derive(Debug)] +pub struct Object<'a> { + pub offset: usize, + pub kind: u16, + pub layer: Option, + pub bounds: Option, + pub target: Option, + pub multiplicity: u64, + key: Key<'a>, + metadata: bool, +} + +impl Object<'_> { + fn field(&self, tag: u16) -> Option<&[u8]> { + self.key + .fields + .iter() + .find(|(t, _)| *t == tag) + .map(|(_, v)| v.as_ref()) + } + + pub fn description(&self) -> String { + let mut out = kind_name(self.kind).to_string(); + for (tag, value) in &self.key.fields { + write!(out, " {}={}", tag_name(*tag), format_data(*tag, value)).unwrap(); + } + for (attribute, value) in &self.key.properties { + write!(out, " property[{attribute}]={}", quoted(value)).unwrap(); + } + out + } +} + +#[derive(Debug)] +pub struct Cell<'a> { + pub offset: usize, + pub objects: Vec>, + attributes: Vec<(u16, &'a [u8])>, +} + +#[derive(Debug)] +pub struct Document<'a> { + pub records: Vec>, + pub cells: BTreeMap>, + pub layer_names: BTreeMap, + /// Unsupported features or invalid reference graphs prevent an equality claim. + pub issues: Vec, + header: Vec<(u16, &'a [u8])>, +} + +fn error(offset: usize, message: impl std::fmt::Display) -> String { + format!("at byte {offset}: {message}") +} + +fn string(data: &[u8], offset: usize) -> Result { + decoded_string(unpad(data), offset) +} + +fn decoded_string(data: &[u8], offset: usize) -> Result { + if data.contains(&0) { + return Err(error(offset, "name or metadata contains an embedded NUL")); + } + std::str::from_utf8(data) + .map(str::to_owned) + .map_err(|_| error(offset, "name or metadata is not UTF-8")) +} + +fn unpad(data: &[u8]) -> &[u8] { + if data.last() == Some(&0) { + &data[..data.len() - 1] + } else { + data + } +} + +fn integer(data: &[u8]) -> u16 { + u16::from_be_bytes(data.try_into().unwrap()) +} + +fn points(data: &[u8]) -> Vec<[i32; 2]> { + data.chunks_exact(8) + .map(|p| { + [ + i32::from_be_bytes(p[..4].try_into().unwrap()), + i32::from_be_bytes(p[4..].try_into().unwrap()), + ] + }) + .collect() +} + +// Booth's least-rotation algorithm avoids quadratic work on repeated vertices. +fn least_rotation(points: &[[i32; 2]]) -> Vec<[i32; 2]> { + let n = points.len(); + let (mut i, mut j, mut k) = (0, 1, 0); + while i < n && j < n && k < n { + match points[(i + k) % n].cmp(&points[(j + k) % n]) { + std::cmp::Ordering::Equal => k += 1, + std::cmp::Ordering::Greater => { + i += k + 1; + if i <= j { + i = j + 1; + } + k = 0; + } + std::cmp::Ordering::Less => { + j += k + 1; + if j <= i { + j = i + 1; + } + k = 0; + } + } + } + let start = i.min(j); + (0..n).map(|k| points[(start + k) % n]).collect() +} + +fn canonical_ring(data: &[u8]) -> Vec { + let mut ring = points(data); + ring.pop(); // The caller has checked closure. + let forward = least_rotation(&ring); + ring.reverse(); + let backward = least_rotation(&ring); + let mut ring = forward.min(backward); + ring.push(ring[0]); + ring.into_iter() + .flatten() + .flat_map(i32::to_be_bytes) + .collect() +} + +fn validate_payload(record: &Record<'_>) -> Result<(), String> { + let size = record.data.len(); + let valid = match record.tag { + RTAG_BGNLIB | RTAG_BGNSTR => size == 24, + RTAG_UNITS => size == 16, + RTAG_HEADER | RTAG_LAYER | RTAG_DATATYPE | RTAG_TEXTTYPE | RTAG_NODETYPE | RTAG_BOXTYPE + | RTAG_PROPATTR | RTAG_PATHTYPE | RTAG_STRANS | RTAG_PRESENTATION | RTAG_ELFLAGS + | RTAG_STRCLASS | RTAG_GENERATIONS => size == 2, + RTAG_WIDTH | RTAG_BGNEXTN | RTAG_ENDEXTN | RTAG_PLEX | RTAG_COLROW => size == 4, + RTAG_MAG | RTAG_ANGLE => size == 8, + RTAG_XY => size % 8 == 0, + RTAG_ENDLIB | RTAG_ENDSTR | RTAG_ENDEL | RTAG_BOUNDARY | RTAG_PATH | RTAG_SREF + | RTAG_AREF | RTAG_TEXT | RTAG_NODE | RTAG_BOX | RTAG_ENDMASKS => size == 0, + _ => true, + }; + if !valid { + return Err(error( + record.offset, + format!("invalid payload size {size} for {}", tag_name(record.tag)), + )); + } + if record.tag == RTAG_UNITS + && record.data.chunks_exact(8).any(|bytes| { + let value = decode_real8(u64::from_be_bytes(bytes.try_into().unwrap())); + !value.is_finite() || value <= 0.0 + }) + { + return Err(error(record.offset, "UNITS must be positive finite values")); + } + Ok(()) +} + +fn is_element(tag: u16) -> bool { + matches!( + tag, + RTAG_BOUNDARY | RTAG_PATH | RTAG_SREF | RTAG_AREF | RTAG_TEXT | RTAG_NODE | RTAG_BOX + ) +} + +fn allowed_field(kind: u16, tag: u16) -> bool { + if matches!(tag, RTAG_ELFLAGS | RTAG_PLEX | RTAG_XY) { + return true; + } + match kind { + RTAG_BOUNDARY => matches!(tag, RTAG_LAYER | RTAG_DATATYPE), + RTAG_BOX => matches!(tag, RTAG_LAYER | RTAG_BOXTYPE), + RTAG_NODE => matches!(tag, RTAG_LAYER | RTAG_NODETYPE), + RTAG_PATH => matches!( + tag, + RTAG_LAYER | RTAG_DATATYPE | RTAG_WIDTH | RTAG_PATHTYPE | RTAG_BGNEXTN | RTAG_ENDEXTN + ), + RTAG_SREF => matches!(tag, RTAG_SNAME | RTAG_STRANS | RTAG_MAG | RTAG_ANGLE), + RTAG_AREF => matches!( + tag, + RTAG_SNAME | RTAG_STRANS | RTAG_MAG | RTAG_ANGLE | RTAG_COLROW + ), + RTAG_TEXT => matches!( + tag, + RTAG_LAYER + | RTAG_TEXTTYPE + | RTAG_STRING + | RTAG_STRANS + | RTAG_MAG + | RTAG_ANGLE + | RTAG_PRESENTATION + | RTAG_PATHTYPE + | RTAG_WIDTH + ), + _ => false, + } +} + +fn object<'a>(records: &[Record<'a>], issues: &mut Vec) -> Result, String> { + let first = &records[0]; + let mut fields = Vec::new(); + let mut properties = Vec::new(); + let mut seen = BTreeSet::new(); + let mut i = 1; + while i + 1 < records.len() { + let record = &records[i]; + if record.tag == RTAG_PROPATTR { + let value = records + .get(i + 1) + .filter(|r| r.tag == RTAG_PROPVALUE) + .ok_or_else(|| error(record.offset, "PROPATTR without PROPVALUE"))?; + properties.push((integer(record.data), unpad(value.data))); + i += 2; + continue; + } + if !allowed_field(first.tag, record.tag) { + issues.push(error( + record.offset, + format!( + "unsupported record 0x{:04x} in {}", + record.tag, + kind_name(first.tag) + ), + )); + } + if !seen.insert(record.tag) { + return Err(error(record.offset, "duplicate element field")); + } + let mut data = Cow::Borrowed(record.data); + if record.tag & 0xff == 6 { + data = Cow::Borrowed(unpad(record.data)); + } + if record.tag == RTAG_XY && matches!(first.tag, RTAG_BOUNDARY | RTAG_BOX) { + let p = points(record.data); + if p.len() < 4 || p.first() != p.last() { + return Err(error( + record.offset, + "polygon must have at least three vertices and be closed", + )); + } + data = Cow::Owned(canonical_ring(record.data)); + } + fields.push((record.tag, data)); + i += 1; + } + fields.sort(); + properties.sort(); + let mut object = Object { + offset: first.offset, + kind: first.tag, + layer: None, + bounds: None, + target: None, + multiplicity: 1, + key: Key { + kind: first.tag, + fields, + properties, + }, + metadata: false, + }; + let xy = object + .field(RTAG_XY) + .ok_or_else(|| error(first.offset, "element has no XY record"))?; + let p = points(xy); + let valid_count = match first.tag { + RTAG_TEXT | RTAG_SREF => p.len() == 1, + RTAG_AREF => p.len() == 3, + RTAG_PATH => p.len() >= 2, + RTAG_NODE => !p.is_empty(), + RTAG_BOX => p.len() == 5, + _ => true, + }; + if !valid_count { + return Err(error(first.offset, "invalid coordinate count")); + } + object.bounds = Some([ + p.iter().map(|p| p[0]).min().unwrap(), + p.iter().map(|p| p[1]).min().unwrap(), + p.iter().map(|p| p[0]).max().unwrap(), + p.iter().map(|p| p[1]).max().unwrap(), + ]); + if matches!(first.tag, RTAG_SREF | RTAG_AREF) { + object.target = Some(decoded_string( + object + .field(RTAG_SNAME) + .ok_or_else(|| error(first.offset, "reference has no SNAME"))?, + first.offset, + )?); + if first.tag == RTAG_AREF { + let counts = object + .field(RTAG_COLROW) + .ok_or_else(|| error(first.offset, "array has no COLROW"))?; + let a = i16::from_be_bytes(counts[..2].try_into().unwrap()); + let b = i16::from_be_bytes(counts[2..].try_into().unwrap()); + if a <= 0 || b <= 0 { + return Err(error(first.offset, "array counts must be positive")); + } + object.multiplicity = a as u64 * b as u64; + } + } else { + let dtype = match first.tag { + RTAG_TEXT => RTAG_TEXTTYPE, + RTAG_BOX => RTAG_BOXTYPE, + RTAG_NODE => RTAG_NODETYPE, + _ => RTAG_DATATYPE, + }; + object.layer = Some(( + integer( + object + .field(RTAG_LAYER) + .ok_or_else(|| error(first.offset, "element has no LAYER"))?, + ), + integer( + object + .field(dtype) + .ok_or_else(|| error(first.offset, "element has no datatype/texttype"))?, + ), + )); + if first.tag == RTAG_TEXT && object.field(RTAG_STRING).is_none() { + return Err(error(first.offset, "text has no STRING")); + } + } + Ok(object) +} + +fn read_records(input: &[u8]) -> Result>, String> { + let mut records = Vec::new(); + let mut offset = 0; + while offset < input.len() { + let (payload, header) = RecordHeader::read(&input[offset..]) + .map_err(|(_, e)| error(offset, format!("invalid record header: {e:?}")))?; + let size = header.data_size as usize; + if (size + 4) % 2 != 0 { + return Err(error(offset, "odd record length")); + } + let data = payload + .get(..size) + .ok_or_else(|| error(offset, "truncated record"))?; + let record = Record { + offset, + tag: header.tag, + data, + }; + offset += size + 4; + let ended = record.tag == RTAG_ENDLIB; + records.push(record); + if ended { + if input[offset..].iter().any(|b| *b != 0) { + return Err(error(offset, "nonzero data after ENDLIB")); + } + break; + } + } + Ok(records) +} + +impl<'a> Document<'a> { + pub fn parse(input: &'a [u8]) -> Result { + let records = read_records(input)?; + for record in &records { + validate_payload(record)?; + } + if records.first().map(|r| r.tag) != Some(RTAG_HEADER) + || records.get(1).map(|r| r.tag) != Some(RTAG_BGNLIB) + || records.last().map(|r| r.tag) != Some(RTAG_ENDLIB) + { + return Err("expected HEADER, BGNLIB, and a final ENDLIB".to_string()); + } + let mut doc = Self { + records, + cells: BTreeMap::new(), + layer_names: BTreeMap::new(), + issues: Vec::new(), + header: Vec::new(), + }; + let mut i = 2; + let mut global_seen = BTreeSet::new(); + let mut cells_started = false; + doc.header.push((RTAG_HEADER, doc.records[0].data)); + while i + 1 < doc.records.len() { + let record = &doc.records[i]; + if record.tag != RTAG_BGNSTR { + if cells_started { + return Err(error( + record.offset, + "library field outside the library header", + )); + } + if record.tag != RTAG_MASK && !global_seen.insert(record.tag) { + return Err(error(record.offset, "duplicate library field")); + } + if !matches!( + record.tag, + RTAG_LIBNAME + | RTAG_UNITS + | RTAG_REFLIBS + | RTAG_FONTS + | RTAG_GENERATIONS + | RTAG_ATTRTABLE + | RTAG_FORMAT + | RTAG_MASK + | RTAG_ENDMASKS + | RTAG_LIBDIRSIZE + | RTAG_SRFNAME + | RTAG_LIBSECUR + ) { + doc.issues.push(error( + record.offset, + format!("unsupported library record 0x{:04x}", record.tag), + )); + } + doc.header.push(( + record.tag, + if record.tag & 0xff == 6 { + unpad(record.data) + } else { + record.data + }, + )); + i += 1; + continue; + } + if !global_seen.contains(&RTAG_LIBNAME) || !global_seen.contains(&RTAG_UNITS) { + return Err(error(record.offset, "LIBNAME and UNITS must precede cells")); + } + cells_started = true; + let offset = record.offset; + i += 1; + let name_record = doc + .records + .get(i) + .filter(|r| r.tag == RTAG_STRNAME) + .ok_or_else(|| error(offset, "BGNSTR must be followed by STRNAME"))?; + let name = string(name_record.data, name_record.offset)?; + if name.is_empty() { + return Err(error(name_record.offset, "empty cell name")); + } + i += 1; + let mut cell = Cell { + offset, + objects: Vec::new(), + attributes: Vec::new(), + }; + loop { + let record = doc + .records + .get(i) + .ok_or_else(|| error(offset, "missing ENDSTR"))?; + if record.tag == RTAG_ENDSTR { + i += 1; + break; + } + if is_element(record.tag) { + let start = i; + i += 1; + while doc.records.get(i).is_some_and(|r| r.tag != RTAG_ENDEL) { + if matches!(doc.records[i].tag, RTAG_ENDSTR | RTAG_ENDLIB | RTAG_BGNSTR) + || is_element(doc.records[i].tag) + { + return Err(error(doc.records[i].offset, "missing ENDEL")); + } + i += 1; + } + if i == doc.records.len() { + return Err(error(offset, "missing ENDEL")); + } + cell.objects + .push(object(&doc.records[start..=i], &mut doc.issues)?); + 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( + record.offset, + format!("unsupported cell record 0x{:04x}", record.tag), + )); + } else if !cell.objects.is_empty() + || cell.attributes.iter().any(|(tag, _)| *tag == RTAG_STRCLASS) + { + return Err(error( + record.offset, + "STRCLASS must occur once before elements", + )); + } + cell.attributes.push((record.tag, record.data)); + i += 1; + } + } + cell.attributes.sort(); + cell.objects.sort_by(|a, b| a.key.cmp(&b.key)); + if doc.cells.insert(name.clone(), cell).is_some() { + return Err(error(offset, format!("duplicate cell name {name:?}"))); + } + } + if !global_seen.contains(&RTAG_LIBNAME) || !global_seen.contains(&RTAG_UNITS) { + return Err("library must contain LIBNAME and UNITS".to_string()); + } + doc.header.sort(); + doc.read_metadata()?; + doc.check_graph(); + 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) { + 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.offset, + "unsupported layer-name metadata version", + )); + } + } + let carriers: BTreeSet<_> = cell + .objects + .iter() + .filter(|o| { + o.kind == RTAG_TEXT && o.field(RTAG_STRING) == Some(LAYER_SENTINEL.as_bytes()) + }) + .filter_map(|o| o.layer) + .collect(); + for object in &mut cell.objects { + if object.kind != RTAG_TEXT || !object.layer.is_some_and(|l| carriers.contains(&l)) + { + continue; + } + let text = decoded_string(object.field(RTAG_STRING).unwrap(), object.offset)?; + if text != LAYER_SENTINEL { + let mut parts = text.splitn(3, ':'); + let parsed = parts + .next() + .and_then(|a| a.parse::().ok()) + .zip(parts.next().and_then(|b| b.parse::().ok())) + .zip(parts.next().filter(|name| !name.is_empty())); + let ((layer, dtype), name) = parsed.ok_or_else(|| { + error( + object.offset, + "invalid layer-name declaration; expected layer:datatype:name", + ) + })?; + if self + .layer_names + .get(&(layer, dtype)) + .is_some_and(|old| old != name) + { + return Err(error( + object.offset, + format!("conflicting names for {layer}/{dtype}"), + )); + } + self.layer_names.insert((layer, dtype), name.to_string()); + } + object.metadata = true; + } + } + Ok(()) + } + + fn check_graph(&mut self) { + let edges = self.edges(); + for ((parent, target), _) in &edges { + if !self.cells.contains_key(target) { + self.issues + .push(format!("cell {parent:?}: unresolved reference {target:?}")); + } + } + let mut state = BTreeMap::<&str, u8>::new(); + for root in self.cells.keys() { + let mut stack = vec![(root.as_str(), false)]; + while let Some((name, leaving)) = stack.pop() { + if leaving { + state.insert(name, 2); + continue; + } + match state.get(name) { + Some(2) => continue, + Some(1) => { + self.issues + .push(format!("cyclic hierarchy involving {name:?}")); + continue; + } + _ => (), + } + state.insert(name, 1); + stack.push((name, true)); + if let Some(cell) = self.cells.get(name) { + for object in &cell.objects { + if let Some(target) = &object.target { + stack.push((target, false)); + } + } + } + } + } + } + + pub fn edges(&self) -> BTreeMap<(String, String), u64> { + let mut edges = BTreeMap::new(); + for (name, cell) in &self.cells { + for object in &cell.objects { + if let Some(target) = &object.target { + let count = edges.entry((name.clone(), target.clone())).or_insert(0_u64); + *count = count.saturating_add(object.multiplicity); + } + } + } + edges + } + + pub fn canonical_dump(&self) -> String { + let mut out = format!( + "profile {PROFILE}\ncoordinates: integer database units; bounds: coordinate envelopes\n" + ); + for (tag, data) in &self.header { + writeln!(out, "{}={}", tag_name(*tag), format_data(*tag, data)).unwrap(); + } + for ((layer, dtype), name) in &self.layer_names { + writeln!(out, "layer {layer}/{dtype} name={name:?}").unwrap(); + } + for (name, cell) in &self.cells { + writeln!(out, "cell {name:?}").unwrap(); + for (tag, data) in &cell.attributes { + writeln!(out, " {}={}", tag_name(*tag), format_data(*tag, data)).unwrap(); + } + for object in cell.objects.iter().filter(|o| !o.metadata) { + writeln!(out, " {}", object.description()).unwrap(); + } + } + for issue in &self.issues { + writeln!(out, "INCOMPLETE: {issue}").unwrap(); + } + out + } + + pub fn record_dump(&self) -> String { + format_records(&self.records) + } +} + +/// Inspect record boundaries even when object grammar or metadata is invalid. +pub fn dump_records(input: &[u8]) -> Result { + Ok(format_records(&read_records(input)?)) +} + +fn format_records(records: &[Record<'_>]) -> String { + let mut out = String::new(); + for record in records { + writeln!( + out, + "{:010} {:04x} {} size={} {}", + record.offset, + record.tag, + tag_name(record.tag), + record.data.len() + 4, + format_data( + record.tag, + if record.tag & 0xff == 6 { + unpad(record.data) + } else { + record.data + } + ) + ) + .unwrap(); + } + out +} + +#[derive(Debug)] +pub struct ObjectChange { + pub offset: usize, + pub bounds: Option, + pub target: Option, + pub description: String, +} + +impl From<&Object<'_>> for ObjectChange { + fn from(object: &Object<'_>) -> Self { + Self { + offset: object.offset, + bounds: object.bounds, + target: object.target.clone(), + description: object.description(), + } + } +} + +#[derive(Debug)] +pub struct CellChange { + pub name: String, + pub old_offset: Option, + pub new_offset: Option, + pub attributes_changed: bool, + pub removed: Vec, + pub added: Vec, +} + +#[derive(Debug)] +pub struct LayerNameChange { + pub layer: Layer, + pub old: Option, + pub new: Option, +} + +#[derive(Debug)] +pub struct LibraryFieldChange { + pub field: String, + pub old: Vec, + pub new: Vec, +} + +#[derive(Debug)] +pub struct Comparison { + pub library_fields: Vec, + pub layer_names: Vec, + pub cells: Vec, + pub issues: Vec, +} + +impl Comparison { + pub fn between(old: &Document<'_>, new: &Document<'_>) -> Self { + let mut result = Self { + library_fields: Vec::new(), + layer_names: Vec::new(), + cells: Vec::new(), + issues: Vec::new(), + }; + for (side, doc) in [("old", old), ("new", new)] { + result + .issues + .extend(doc.issues.iter().map(|i| format!("{side}: {i}"))); + } + let header_tags: BTreeSet<_> = old + .header + .iter() + .chain(&new.header) + .map(|(tag, _)| *tag) + .collect(); + for tag in header_tags { + let a: Vec<_> = old + .header + .iter() + .filter(|(t, _)| *t == tag) + .map(|(_, value)| *value) + .collect(); + let b: Vec<_> = new + .header + .iter() + .filter(|(t, _)| *t == tag) + .map(|(_, value)| *value) + .collect(); + if a != b { + result.library_fields.push(LibraryFieldChange { + field: tag_name(tag), + old: a.iter().map(|data| format_data(tag, data)).collect(), + new: b.iter().map(|data| format_data(tag, data)).collect(), + }); + } + } + let layers: BTreeSet<_> = old + .layer_names + .keys() + .chain(new.layer_names.keys()) + .copied() + .collect(); + for layer in layers { + if old.layer_names.get(&layer) != new.layer_names.get(&layer) { + result.layer_names.push(LayerNameChange { + layer, + old: old.layer_names.get(&layer).cloned(), + new: new.layer_names.get(&layer).cloned(), + }); + } + } + let names: BTreeSet<_> = old.cells.keys().chain(new.cells.keys()).collect(); + for name in names { + let a = old.cells.get(name); + let b = new.cells.get(name); + let mut change = CellChange { + name: name.clone(), + old_offset: a.map(|c| c.offset), + new_offset: b.map(|c| c.offset), + attributes_changed: a.map(|c| &c.attributes) != b.map(|c| &c.attributes), + removed: Vec::new(), + added: Vec::new(), + }; + let a: Vec<_> = a + .into_iter() + .flat_map(|c| &c.objects) + .filter(|o| !o.metadata) + .collect(); + let b: Vec<_> = b + .into_iter() + .flat_map(|c| &c.objects) + .filter(|o| !o.metadata) + .collect(); + let (mut i, mut j) = (0, 0); + while i < a.len() || j < b.len() { + let order = match (a.get(i), b.get(j)) { + (Some(a), Some(b)) => a.key.cmp(&b.key), + (Some(_), None) => std::cmp::Ordering::Less, + _ => std::cmp::Ordering::Greater, + }; + match order { + std::cmp::Ordering::Equal => { + i += 1; + j += 1; + } + std::cmp::Ordering::Less => { + change.removed.push(a[i].into()); + i += 1; + } + std::cmp::Ordering::Greater => { + change.added.push(b[j].into()); + j += 1; + } + } + } + if change.old_offset.is_none() + || change.new_offset.is_none() + || change.attributes_changed + || !change.removed.is_empty() + || !change.added.is_empty() + { + result.cells.push(change); + } + } + result + } + + pub fn is_equal(&self) -> bool { + self.issues.is_empty() + && self.library_fields.is_empty() + && self.layer_names.is_empty() + && self.cells.is_empty() + } + + pub fn exit_code(&self) -> u8 { + if !self.issues.is_empty() { + 2 + } else if self.is_equal() { + 0 + } else { + 1 + } + } + + /// 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"); + for change in &self.library_fields { + writeln!( + out, + "library {}: {:?} -> {:?}", + change.field, change.old, change.new + ) + .unwrap(); + } + if self.library_fields.iter().any(|c| c.field == "UNITS") { + out.push_str("UNITS changed; coordinates remain in each file's database units\n"); + } + for change in &self.layer_names { + writeln!( + out, + "layer {}/{} name: {:?} -> {:?}", + change.layer.0, change.layer.1, change.old, change.new + ) + .unwrap(); + } + let total: usize = self + .cells + .iter() + .map(|c| c.removed.len() + c.added.len()) + .sum(); + let mut shown = 0; + for cell in &self.cells { + writeln!( + out, + "cell {:?} old@{:?} new@{:?}{}", + cell.name, + cell.old_offset, + cell.new_offset, + if cell.attributes_changed { + " [cell/header changed]" + } else { + "" + } + ) + .unwrap(); + for (sign, objects) in [("-", &cell.removed), ("+", &cell.added)] { + for object in objects { + if shown < max_objects { + writeln!( + out, + " {sign} @{} bbox={:?} {}", + object.offset, object.bounds, object.description + ) + .unwrap(); + shown += 1; + } + } + } + } + writeln!( + out, + "{} changed cells; {shown} of {total} object changes shown; {} layer-name changes", + self.cells.len(), + self.layer_names.len() + ) + .unwrap(); + for issue in &self.issues { + writeln!(out, "INCOMPLETE: {issue}").unwrap(); + } + if self.is_equal() { + out.push_str("equal under this profile\n"); + } + out + } +} + +/// The graph joins both revisions, retaining removed branches and old callers. +pub fn hierarchy( + old: &Document<'_>, + new: &Document<'_>, + diff: Option<&Comparison>, + mermaid: bool, + max_depth: usize, +) -> String { + let old_edges = old.edges(); + let new_edges = new.edges(); + let edges: BTreeSet<_> = old_edges.keys().chain(new_edges.keys()).cloned().collect(); + let direct: BTreeSet<_> = diff + .into_iter() + .flat_map(|d| d.cells.iter().map(|c| c.name.clone())) + .collect(); + let changed_refs: BTreeSet<_> = diff + .into_iter() + .flat_map(|d| &d.cells) + .flat_map(|c| { + c.removed + .iter() + .chain(&c.added) + .filter_map(|o| o.target.as_ref().map(|t| (c.name.clone(), t.clone()))) + }) + .collect(); + let mut parents = BTreeMap::<&str, Vec<&str>>::new(); + for (parent, child) in &edges { + parents.entry(child).or_default().push(parent); + } + let mut affected = direct.clone(); + let mut pending: Vec<_> = direct.iter().cloned().collect(); + while let Some(child) = pending.pop() { + for parent in parents.get(child.as_str()).into_iter().flatten() { + if affected.insert((*parent).to_string()) { + pending.push((*parent).to_string()); + } + } + } + let visible: BTreeSet<_> = if diff.is_some() { + affected + .iter() + .cloned() + .chain(changed_refs.iter().map(|(_, t)| t.clone())) + .collect() + } else { + old.cells + .keys() + .chain(new.cells.keys()) + .cloned() + .chain(edges.iter().map(|(_, t)| t.clone())) + .collect() + }; + let mut children = BTreeMap::>::new(); + let mut targets = BTreeSet::new(); + for (parent, target) in &edges { + if visible.contains(parent) && visible.contains(target) { + children + .entry(parent.clone()) + .or_default() + .push(target.clone()); + targets.insert(target.clone()); + } + } + let roots: Vec<_> = visible.difference(&targets).cloned().collect(); + // Distinguish rootless cycles from descendants hidden by the depth limit. + let mut reachable = BTreeSet::new(); + let mut pending = roots.clone(); + while let Some(name) = pending.pop() { + if reachable.insert(name.clone()) { + pending.extend(children.get(&name).into_iter().flatten().cloned()); + } + } + let mut included = BTreeSet::new(); + let mut rows = Vec::new(); + let mut stack: Vec<_> = roots + .iter() + .rev() + .map(|n| (n.clone(), 0, None::)) + .collect(); + while let Some((name, depth, parent)) = stack.pop() { + let seen = !included.insert(name.clone()); + let descendants = children.get(&name).map(Vec::as_slice).unwrap_or(&[]); + rows.push(( + name.clone(), + depth, + parent, + seen, + depth >= max_depth && !descendants.is_empty(), + )); + if !seen && depth < max_depth { + for child in descendants.iter().rev() { + stack.push((child.clone(), depth + 1, Some(name.clone()))); + } + } + } + for name in visible.difference(&reachable) { + rows.push((name.clone(), 0, None, false, true)); + } + let status = |name: &String| { + if direct.contains(name) { + " [cell changed]" + } else if affected.contains(name) { + " [affected]" + } else if diff.is_some() { + " [cell unchanged]" + } else { + "" + } + }; + let edge_label = |parent: &String, target: &String| { + let key = (parent.clone(), target.clone()); + let a = old_edges.get(&key).copied().unwrap_or(0); + let b = new_edges.get(&key).copied().unwrap_or(0); + let count = if a == b { + format!("x{b}") + } else { + format!("x{a} -> x{b}") + }; + format!( + "{count}{}", + if changed_refs.contains(&key) { + " [reference changed]" + } else { + "" + } + ) + }; + if mermaid { + let ids: BTreeMap<_, _> = rows + .iter() + .map(|r| &r.0) + .collect::>() + .into_iter() + .enumerate() + .map(|(i, n)| (n, i)) + .collect(); + let mut out = "flowchart TD\n".to_string(); + for (name, id) in &ids { + let label = format!("{name}{}", status(name)); + let label = label + .replace('&', "&") + .replace('"', """) + .replace('<', "<") + .replace('>', ">") + .replace(['\r', '\n'], " "); + writeln!(out, " n{id}[\"{label}\"]").unwrap(); + } + for (parent, target) in &edges { + if let (Some(a), Some(b)) = (ids.get(parent), ids.get(target)) { + writeln!(out, " n{a} -->|\"{}\"| n{b}", edge_label(parent, target)).unwrap(); + } + } + if rows.is_empty() { + out.push_str(" empty[\"No changed hierarchy\"]\n"); + } + out + } else { + let mut out = String::new(); + for (name, depth, parent, seen, limited) in rows { + let count = parent + .map(|p| edge_label(&p, &name)) + .unwrap_or_else(|| "x1".to_string()); + writeln!( + out, + "{}{name:?} {count}{}{}{}", + " ".repeat(depth), + status(&name), + if seen { " [shown above]" } else { "" }, + if limited { " [children omitted]" } else { "" } + ) + .unwrap(); + } + if visible.is_empty() { + out.push_str("No changed hierarchy\n"); + } + out + } +} + +fn quoted(data: &[u8]) -> String { + let mut out = "\"".to_string(); + for byte in data { + for escaped in std::ascii::escape_default(*byte) { + out.push(escaped as char); + } + } + out.push('"'); + out +} + +fn format_data(tag: u16, data: &[u8]) -> String { + if matches!( + tag, + RTAG_LAYER | RTAG_DATATYPE | RTAG_TEXTTYPE | RTAG_BOXTYPE | RTAG_NODETYPE + ) && data.len() == 2 + { + return integer(data).to_string(); + } + match tag & 0xff { + 0 if data.is_empty() => String::new(), + 2 if data.len() % 2 == 0 => format!( + "{:?}", + data.chunks_exact(2) + .map(|b| i16::from_be_bytes(b.try_into().unwrap())) + .collect::>() + ), + 3 if data.len() % 4 == 0 => format!( + "{:?}", + data.chunks_exact(4) + .map(|b| i32::from_be_bytes(b.try_into().unwrap())) + .collect::>() + ), + 5 if data.len() % 8 == 0 => format!( + "{:?} raw={}", + data.chunks_exact(8) + .map(|b| decode_real8(u64::from_be_bytes(b.try_into().unwrap()))) + .collect::>(), + hex(data) + ), + 6 => quoted(data), + _ => hex(data), + } +} + +fn hex(data: &[u8]) -> String { + let mut out = "0x".to_string(); + for byte in data { + write!(out, "{byte:02x}").unwrap(); + } + out +} + +fn kind_name(tag: u16) -> &'static str { + match tag { + RTAG_BOUNDARY => "BOUNDARY", + RTAG_PATH => "PATH", + RTAG_SREF => "SREF", + RTAG_AREF => "AREF", + RTAG_TEXT => "TEXT", + RTAG_NODE => "NODE", + RTAG_BOX => "BOX", + _ => "UNKNOWN", + } +} + +fn tag_name(tag: u16) -> String { + let name = match tag { + RTAG_HEADER => "HEADER", + RTAG_BGNLIB => "BGNLIB", + RTAG_LIBNAME => "LIBNAME", + RTAG_UNITS => "UNITS", + RTAG_ENDLIB => "ENDLIB", + RTAG_BGNSTR => "BGNSTR", + RTAG_STRNAME => "STRNAME", + RTAG_ENDSTR => "ENDSTR", + RTAG_ENDEL => "ENDEL", + RTAG_LAYER => "layer", + RTAG_DATATYPE => "datatype", + RTAG_TEXTTYPE => "texttype", + RTAG_XY => "xy", + RTAG_SNAME => "target", + RTAG_COLROW => "counts", + RTAG_STRANS => "strans", + RTAG_MAG => "mag", + RTAG_ANGLE => "angle", + RTAG_WIDTH => "width", + RTAG_PATHTYPE => "pathtype", + RTAG_STRING => "string", + RTAG_PROPATTR => "PROPATTR", + RTAG_PROPVALUE => "PROPVALUE", + RTAG_PRESENTATION => "presentation", + RTAG_BGNEXTN => "bgnextn", + RTAG_ENDEXTN => "endextn", + RTAG_BOXTYPE => "boxtype", + RTAG_NODETYPE => "nodetype", + RTAG_ELFLAGS => "elflags", + RTAG_PLEX => "plex", + RTAG_STRCLASS => "STRCLASS", + tag if is_element(tag) => kind_name(tag), + _ => return format!("record_{tag:04x}"), + }; + name.to_string() +} diff --git a/tests/golden/review-canonical.txt b/tests/golden/review-canonical.txt new file mode 100644 index 0000000..3cd359a --- /dev/null +++ b/tests/golden/review-canonical.txt @@ -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] diff --git a/tests/golden/review-hierarchy.mmd b/tests/golden/review-hierarchy.mmd new file mode 100644 index 0000000..86cffd6 --- /dev/null +++ b/tests/golden/review-hierarchy.mmd @@ -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 diff --git a/tests/golden/review-hierarchy.txt b/tests/golden/review-hierarchy.txt new file mode 100644 index 0000000..b6a0f97 --- /dev/null +++ b/tests/golden/review-hierarchy.txt @@ -0,0 +1,5 @@ +"CHIP" x1 [affected] + "left" x1 [affected] + "leaf" x2 [cell changed] + "right" x1 [affected] + "leaf" x3 [cell changed] [shown above] diff --git a/tests/review.rs b/tests/review.rs new file mode 100644 index 0000000..a0b0eae --- /dev/null +++ b/tests/review.rs @@ -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, 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, points: &[[i32; 2]]) { + record( + bytes, + RTAG_XY, + &points + .iter() + .flatten() + .flat_map(|v| v.to_be_bytes()) + .collect::>(), + ); +} + +fn layout(cells: &[(&str, Vec>)]) -> Vec { + 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 { + 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 { + polygon(&[[0, 0], [10, 0], [10, 10], [0, 10], [0, 0]]) +} + +fn triangle() -> Vec { + polygon(&[[0, 0], [10, 0], [0, 10], [0, 0]]) +} + +fn reference(target: &str, x: i32, count: i16) -> Vec { + 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 { + 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, value: &str) -> Vec { + 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) -> Vec { + 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, + new: Vec, + changed_cells: usize, + removed: usize, + added: usize, + metadata: usize, +} + +// Ten deliberately small fixture pairs specify the first object profile. +fn corpus() -> Vec { + 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::(), + pair.removed, + "{}", + pair.name + ); + assert_eq!( + diff.cells.iter().map(|c| c.added.len()).sum::(), + 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::>(); + 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) + ); +}