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) + ); +}