//! 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::{ErrType, decode_name, decode_real8, encode_real8, unpad_ascii}, record::{Record as _, RecordFrame}, records::*, }; use std::{ borrow::Cow, collections::{BTreeMap, BTreeSet}, fmt::{self, Write}, }; pub mod changes; pub mod names; mod pair; pub mod report; pub mod selection; use changes::Replacement; use pair::CellReuse; pub use pair::RevisionPair; use selection::{DisplayFilter, Scope}; /// Input revision associated with a diagnostic. #[derive(Clone, Copy, Debug, Eq, PartialEq)] pub enum Side { Old, New, } impl fmt::Display for Side { fn fmt(&self, out: &mut fmt::Formatter<'_>) -> fmt::Result { out.write_str(match self { Self::Old => "old", Self::New => "new", }) } } /// A review error or comparison limitation, with structured source context. #[derive(Clone, Debug)] pub struct Diagnostic { pub code: &'static str, pub message: String, pub side: Option, pub offset: Option, pub cell: Option, pub layer: Option, pub target: Option, } impl Diagnostic { pub fn new(code: &'static str, message: impl Into, side: Option) -> Self { Self { code, message: message.into(), side, offset: None, cell: None, layer: None, target: None, } } fn at(code: &'static str, offset: usize, message: String) -> Self { Self { offset: Some(offset), ..Self::new(code, error(offset, message), None) } } } impl fmt::Display for Diagnostic { fn fmt(&self, out: &mut fmt::Formatter<'_>) -> fmt::Result { if let Some(side) = self.side { write!(out, "{side}: ")?; } out.write_str(&self.message) } } /// The five meaningful combinations of completeness and comparison result. #[derive(Clone, Copy, Debug, Eq, PartialEq)] pub enum Outcome { Equal, Different, Incomplete { different: bool }, Failed, } impl Outcome { pub fn status(self) -> &'static str { match self { Self::Equal | Self::Different => "complete", Self::Incomplete { .. } => "incomplete", Self::Failed => "failed", } } pub fn result(self) -> &'static str { match self { Self::Equal => "equal", Self::Different | Self::Incomplete { different: true } => "different", Self::Incomplete { different: false } | Self::Failed => "unknown", } } pub fn exit_code(self) -> u8 { match self { Self::Equal => 0, Self::Different => 1, _ => 2, } } pub fn is_equal(self) -> bool { self == Self::Equal } pub fn is_complete(self) -> bool { matches!(self, Self::Equal | Self::Different) } } pub const PROFILE: &str = "pheon-structural-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(Clone, Debug)] pub struct Object<'a> { pub offset: usize, pub end_offset: usize, pub kind: u16, pub layer: Option, pub bounds: Option, pub target: Option, pub multiplicity: u64, key: Key<'a>, metadata: bool, issues: Vec, } impl Object<'_> { fn field(&self, tag: u16) -> Option<&[u8]> { self.key .fields .iter() .find(|(t, _)| *t == tag) .map(|(_, v)| v.as_ref()) } } fn format_object<'a>( out: &mut fmt::Formatter<'_>, kind: u16, layer: Option, fields: impl Iterator + Clone, properties: impl IntoIterator, ) -> fmt::Result { let field = |tag| { fields .clone() .find_map(|(t, data)| (t == tag).then_some(data)) }; let rectangle = if is_polygon(kind) { field(RTAG_XY).and_then(XY::closed_rectangle) } else { None }; let target = if matches!(kind, RTAG_SREF | RTAG_AREF) { field(RTAG_SNAME) } else { None }; let dimensions = if kind == RTAG_AREF { field(RTAG_COLROW).and_then(array_dimensions) } else { None }; if let Some((layer, datatype)) = layer { write!(out, "{layer}/{datatype}: ")?; } out.write_str(object_name(kind, rectangle.is_some()))?; if let Some(target) = target { write!(out, " {}", quoted(target))?; } if let Some([columns, rows]) = dimensions { write!(out, " ({columns} × {rows})")?; } for (tag, value) in fields { if (layer.is_some() && matches_layer_field(kind, tag)) || (tag == RTAG_SNAME && target.is_some()) || (tag == RTAG_COLROW && dimensions.is_some()) { continue; } if tag == RTAG_XY && value.len().is_multiple_of(8) { if let Some([xmin, ymin, xmax, ymax]) = rectangle { write!(out, " ({xmin}, {ymin}) to ({xmax}, {ymax})")?; } else { write_points(out, value)?; } } else { write!(out, " {}={}", tag_name(tag), format_exact_value(tag, value))?; } } for (attribute, value) in properties { write!(out, " property[{attribute}]={}", quoted(value))?; } Ok(()) } fn array_dimensions(data: &[u8]) -> Option<[u16; 2]> { let [column_hi, column_lo, row_hi, row_lo]: [u8; 4] = data.try_into().ok()?; Some([ u16::from_be_bytes([column_hi, column_lo]), u16::from_be_bytes([row_hi, row_lo]), ]) } const POINTS_PER_LINE: usize = 4; fn write_points(out: &mut fmt::Formatter<'_>, data: &[u8]) -> fmt::Result { let mut points = XY::points(data); if points.len() == 1 { let [x, y] = points.next().unwrap(); return write!(out, " xy=({x}, {y})"); } out.write_str(" xy=[")?; for (index, [x, y]) in points.enumerate() { if index != 0 { out.write_str(if index % POINTS_PER_LINE == 0 { ",\n " } else { ", " })?; } write!(out, "({x}, {y})")?; } out.write_str("]") } impl fmt::Display for Object<'_> { fn fmt(&self, out: &mut fmt::Formatter<'_>) -> fmt::Result { format_object( out, self.kind, self.layer, self.key .fields .iter() .map(|(tag, data)| (*tag, data.as_ref())), self.key.properties.iter().copied(), ) } } #[derive(Debug)] pub struct Cell<'a> { pub offset: usize, /// Start of ENDSTR, for inserting records without rewriting the cell. pub end_offset: usize, pub objects: Vec>, attributes: Vec<(u16, &'a [u8])>, issues: Vec, } #[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 diagnostics: Vec, header: Vec<(u16, &'a [u8])>, global_issues: Vec, known_cells: BTreeSet, pub scope: Scope, present: bool, } fn error(offset: usize, message: impl std::fmt::Display) -> String { format!("at byte {offset}: {message}") } 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 integer(data: &[u8]) -> u16 { u16::from_be_bytes(data.try_into().unwrap()) } fn coordinate_bounds(points: impl IntoIterator) -> Bounds { let mut points = points.into_iter(); let [x, y] = points.next().unwrap(); points.fold([x, y, x, y], |[xmin, ymin, xmax, ymax], [x, y]| { [xmin.min(x), ymin.min(y), xmax.max(x), ymax.max(y)] }) } // Booth's least-rotation algorithm avoids quadratic work on repeated vertices. fn least_rotation(n: usize, point: impl Fn(usize) -> [i32; 2]) -> usize { let (mut i, mut j, mut k) = (0, 1, 0); while i < n && j < n && k < n { match point((i + k) % n).cmp(&point((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; } } } i.min(j) } fn canonical_ring(data: &[u8]) -> Option> { let (points, _) = data.as_chunks::<8>(); let (last, ring) = points.split_last()?; if ring.len() < 3 || ring.first() != Some(last) { return None; } let n = ring.len(); let first = least_rotation(n, |index| XY::point(ring[index])); let split = n - least_rotation(n, |index| XY::point(ring[n - 1 - index])); let forward = ring[first..].iter().chain(&ring[..first]); let backward = ring[..split].iter().rev().chain(ring[split..].iter().rev()); let decode = |point: &[u8; 8]| XY::point(*point); let use_forward = forward .clone() .map(decode) .cmp(backward.clone().map(decode)) .is_le(); if use_forward && first == 0 { return Some(Cow::Borrowed(data)); } let mut result = Vec::with_capacity(data.len()); if use_forward { result.extend(forward.flatten().copied()); } else { result.extend(backward.flatten().copied()); } result.extend_from_within(..8); Some(Cow::Owned(result)) } fn validate_payload(record: &Record<'_>) -> Result<(), String> { let size = record.data.len() as u16; check_payload_size(record.tag, size).map_err(|message| { error( record.offset, format!( "invalid payload size {size} for {}: {message}", tag_name(record.tag) ), ) })?; if record.tag == RTAG_UNITS { UNITS::read_data(record.data, size) .map_err(|(_, reason)| payload_error(record.offset, reason))?; } Ok(()) } fn payload_error(offset: usize, reason: ErrType) -> String { match reason { ErrType::Failed(message) => error(offset, message), ErrType::Incomplete(_) => error(offset, "truncated record payload"), } } fn is_element(tag: u16) -> bool { matches!( tag, RTAG_BOUNDARY | RTAG_PATH | RTAG_SREF | RTAG_AREF | RTAG_TEXT | RTAG_NODE | RTAG_BOX ) } fn is_polygon(kind: u16) -> bool { matches!(kind, RTAG_BOUNDARY | RTAG_BOX) } fn layer_type_tag(kind: u16) -> u16 { match kind { RTAG_TEXT => RTAG_TEXTTYPE, RTAG_NODE => RTAG_NODETYPE, RTAG_BOX => RTAG_BOXTYPE, _ => RTAG_DATATYPE, } } fn matches_layer_field(kind: u16, tag: u16) -> bool { tag == RTAG_LAYER || tag == layer_type_tag(kind) } 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 target = None; 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_ascii(value.data))); i += 2; continue; } if !allowed_field(first.tag, record.tag) { issues.push(Diagnostic::at( "unsupported_record", 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 == RTAG_SNAME && matches!(first.tag, RTAG_SREF | RTAG_AREF) { let name = decode_name(record.data).map_err(|message| error(record.offset, message))?; target = Some(name.to_owned()); data = Cow::Borrowed(name.as_bytes()); } else if record.tag & 0xff == 6 { data = Cow::Borrowed(unpad_ascii(record.data)); } if record.tag == RTAG_XY && is_polygon(first.tag) { data = canonical_ring(record.data).ok_or_else(|| { error( record.offset, "polygon must have at least three vertices and be closed", ) })?; } fields.push((record.tag, data)); i += 1; } fields.sort(); properties.sort(); let mut object = Object { offset: first.offset, end_offset: records.last().unwrap().offset + 4, kind: first.tag, layer: None, bounds: None, target, multiplicity: 1, key: Key { kind: first.tag, fields, properties, }, metadata: false, issues: Vec::new(), }; let xy = object .field(RTAG_XY) .ok_or_else(|| error(first.offset, "element has no XY record"))?; object.bounds = Some(if first.tag == RTAG_AREF { let counts = object .field(RTAG_COLROW) .ok_or_else(|| error(first.offset, "array has no COLROW"))?; let placement = ArrayPlacement::decode(counts, xy) .map_err(|(_, reason)| payload_error(first.offset, reason))?; let [columns, rows] = placement.counts; object.multiplicity = u64::from(columns) * u64::from(rows); coordinate_bounds(placement.points) } else { let points = XY::points(xy); let valid_count = match first.tag { RTAG_TEXT | RTAG_SREF => points.len() == 1, RTAG_PATH => points.len() >= 2, RTAG_NODE => points.len() > 0, RTAG_BOX => points.len() == 5, _ => true, }; if !valid_count { return Err(error(first.offset, "invalid coordinate count")); } coordinate_bounds(points) }); if matches!(first.tag, RTAG_SREF | RTAG_AREF) { if object.target.is_none() { return Err(error(first.offset, "reference has no SNAME")); } } else { let dtype = layer_type_tag(first.tag); 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> { read_records_with(input, |_, _| {}) } fn read_records_with<'a>( input: &'a [u8], mut observe: impl FnMut(usize, &Record<'a>), ) -> Result>, String> { if input.starts_with(b"\x1f\x8b") { return Err(error( 0, "gzip-compressed input. Decompress it before reading GDSII", )); } if input.starts_with(b"%SEMI-OASIS\r\n") { return Err(error(0, "OASIS input. Export the layout as GDSII")); } let mut records = Vec::new(); let mut remaining = input; while !remaining.is_empty() { let offset = input.len() - remaining.len(); let (next, frame) = RecordFrame::read(remaining).map_err(|(_, reason)| match reason { ErrType::Incomplete(_) => error(offset, "truncated record header"), ErrType::Failed(message) => error(offset, message), })?; let record = Record { offset, tag: frame.tag, data: frame.data, }; observe(records.len(), &record); records.push(record); remaining = next; if frame.tag == RTAG_ENDLIB { if remaining.iter().any(|b| *b != 0) { return Err(error( input.len() - remaining.len(), "nonzero data after ENDLIB", )); } break; } } Ok(records) } impl<'a> Document<'a> { pub fn parse(input: &'a [u8]) -> Result { let records = read_records(input)?; let mut doc = Self::parse_records(&records, None)?; doc.records = records; Ok(doc) } fn parse_records( records: &[Record<'a>], reuse: Option>, ) -> Result { 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: Vec::new(), cells: BTreeMap::new(), layer_names: BTreeMap::new(), diagnostics: Vec::new(), header: Vec::new(), global_issues: Vec::new(), known_cells: BTreeSet::new(), scope: Scope::default(), present: true, }; let mut i = 2; let mut global_seen = BTreeSet::new(); let mut cells_started = false; doc.header.push((RTAG_HEADER, records[0].data)); while i + 1 < records.len() { let record = &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.global_issues.push(Diagnostic::at( "unsupported_record", record.offset, format!("unsupported library record 0x{:04x}", record.tag), )); } doc.header.push(( record.tag, if record.tag == RTAG_LIBNAME { decode_name(record.data) .map_err(|message| error(record.offset, message))? .as_bytes() } else if record.tag & 0xff == 6 { unpad_ascii(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 = records .get(i) .filter(|r| r.tag == RTAG_STRNAME) .ok_or_else(|| error(offset, "BGNSTR must be followed by STRNAME"))?; let name = decode_name(name_record.data) .map_err(|message| error(name_record.offset, message))? .to_owned(); if name.is_empty() { return Err(error(name_record.offset, "empty cell name")); } if let Some(reuse) = &reuse && let Some((cell, end)) = reuse.cell(&name, offset, records) { if doc.cells.insert(name.clone(), cell).is_some() { return Err(error(offset, format!("duplicate cell name {name:?}"))); } i = end + 1; continue; } i += 1; let mut cell = Cell { offset, end_offset: 0, objects: Vec::new(), attributes: Vec::new(), issues: Vec::new(), }; loop { let record = records .get(i) .ok_or_else(|| error(offset, "missing ENDSTR"))?; if record.tag == RTAG_ENDSTR { cell.end_offset = record.offset; i += 1; break; } if is_element(record.tag) { let start = i; i += 1; while records.get(i).is_some_and(|r| r.tag != RTAG_ENDEL) { if matches!(records[i].tag, RTAG_ENDSTR | RTAG_ENDLIB | RTAG_BGNSTR) || is_element(records[i].tag) { return Err(error(records[i].offset, "missing ENDEL")); } i += 1; } if i == records.len() { return Err(error(offset, "missing ENDEL")); } let mut issues = Vec::new(); let mut parsed = object(&records[start..=i], &mut issues)?; parsed.issues = issues; cell.objects.push(parsed); i += 1; } else { if matches!(record.tag, RTAG_ENDLIB | RTAG_BGNSTR) { return Err(error(record.offset, "missing ENDSTR")); } if record.tag != RTAG_STRCLASS { cell.issues.push(Diagnostic::at( "unsupported_record", 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.known_cells = doc.cells.keys().cloned().collect(); doc.refresh_diagnostics(); Ok(doc) } fn check_graph(&mut self) { let mut unresolved = BTreeMap::new(); for (parent, cell) in &self.cells { for object in &cell.objects { if let Some(target) = &object.target && !self.known_cells.contains(target) { unresolved.entry((parent, target)).or_insert(object.offset); } } } for ((parent, target), offset) in unresolved { self.diagnostics.push(Diagnostic { code: "unresolved_reference", side: None, message: format!("cell {parent:?}: unresolved reference {target:?}"), offset: Some(offset), cell: Some(parent.clone()), layer: None, target: Some(target.clone()), }); } 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.diagnostics.push(Diagnostic { code: "hierarchy_cycle", side: None, message: format!("cyclic hierarchy involving {name:?}"), offset: self.cells.get(name).map(|c| c.offset), cell: Some(name.to_string()), layer: None, target: None, }); 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> { self.cells .iter() .flat_map(|(name, cell)| { let mut counts = BTreeMap::new(); for object in &cell.objects { if let Some(target) = object.target.as_deref() { let count = counts.entry(target).or_insert(0_u64); *count = count.saturating_add(object.multiplicity); } } counts .into_iter() .map(|(target, count)| ((name.clone(), target.to_owned()), count)) }) .collect() } pub fn hierarchy(&self, mermaid: bool, max_depth: usize) -> String { let revision = Revision::from_document(self); render_hierarchy(&revision, &revision, None, mermaid, max_depth, None) } pub fn canonical_dump(&self) -> String { if !self.present { return "library absent\n".to_string(); } let version_index = self .header .iter() .position(|(tag, _)| *tag == RTAG_HEADER) .unwrap(); let header = |tag| self.header.iter().find(|(t, _)| *t == tag).unwrap().1; let (user, meters) = header(RTAG_UNITS).split_at(8); let version = i16::from_be_bytes(self.header[version_index].1.try_into().unwrap()); let mut out = format!( "library {} (GDSII {version}, {} user units/dbu, {} m/dbu)\n", quoted(header(RTAG_LIBNAME)), format_exact_value(RTAG_UNITS, user), format_exact_value(RTAG_UNITS, meters) ); self.scope.write_restrictions(&mut out); for (index, (tag, data)) in self.header.iter().enumerate() { if index != version_index && !matches!(*tag, RTAG_LIBNAME | RTAG_UNITS) { writeln!(out, "{}={}", tag_name(*tag), format_exact_value(*tag, data)).unwrap(); } } for ((layer, dtype), name) in &self.layer_names { writeln!(out, "{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_exact_value(*tag, data) ) .unwrap(); } let mut objects = cell .objects .iter() .filter(|object| !object.metadata) .peekable(); while let Some(object) = objects.next() { let mut count = 1; while objects.next_if(|next| next.key == object.key).is_some() { count += 1; } if count == 1 { writeln!(out, " {object}").unwrap(); } else { writeln!(out, " {count}x {object}").unwrap(); } } } for diagnostic in &self.diagnostics { writeln!(out, "INCOMPLETE: {}", diagnostic.message).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_ascii(record.data) } else { record.data } ) ) .unwrap(); } out } /// A retained comparison field. Polygon coordinates and string padding follow /// the comparison profile; REAL encodings and unsupported payloads are exact. #[derive(Clone, Debug, Eq, PartialEq)] pub struct FieldValue { pub tag: u16, pub data: Vec, } fn owned_fields<'a>(fields: impl IntoIterator) -> Vec { fields .into_iter() .map(|(tag, data)| FieldValue { tag, data: data.to_vec(), }) .collect() } #[derive(Debug)] pub struct ObjectChange { pub offset: usize, pub end_offset: usize, pub kind: u16, pub layer: Option, pub bounds: Option, pub target: Option, pub origin: Option<[i32; 2]>, pub width: Option, pub counts: Option<[u16; 2]>, pub fields: Vec, pub properties: Vec<(u16, Vec)>, } impl fmt::Display for ObjectChange { fn fmt(&self, out: &mut fmt::Formatter<'_>) -> fmt::Result { format_object( out, self.kind, self.layer, self.fields .iter() .map(|field| (field.tag, field.data.as_slice())), self.properties .iter() .map(|(attribute, data)| (*attribute, data.as_slice())), ) } } impl From<&Object<'_>> for ObjectChange { fn from(object: &Object<'_>) -> Self { Self { offset: object.offset, end_offset: object.end_offset, kind: object.kind, layer: object.layer, bounds: object.bounds, target: object.target.clone(), origin: object .field(RTAG_XY) .and_then(|data| XY::points(data).next()), width: object .field(RTAG_WIDTH) .map(|data| i32::from_be_bytes(data.try_into().unwrap())), counts: object.target.as_ref().and_then(|_| { if object.kind == RTAG_AREF { object.field(RTAG_COLROW).and_then(array_dimensions) } else { Some([1, 1]) } }), fields: owned_fields( object .key .fields .iter() .map(|(tag, data)| (*tag, data.as_ref())), ), properties: object .key .properties .iter() .map(|(a, v)| (*a, v.to_vec())) .collect(), } } } /// An existing cell's source location and retained attributes. #[derive(Debug)] pub struct CellRevision { pub offset: usize, pub attributes: Vec, } impl From<&Cell<'_>> for CellRevision { fn from(cell: &Cell<'_>) -> Self { Self { offset: cell.offset, attributes: owned_fields(cell.attributes.iter().copied()), } } } #[derive(Debug)] pub struct CellChange { pub name: String, pub old: Option, pub new: Option, pub removed: Vec, pub added: Vec, pub replacements: Vec, } impl CellChange { pub fn attributes_changed(&self) -> bool { self.old.as_ref().map(|cell| &cell.attributes) != self.new.as_ref().map(|cell| &cell.attributes) } } #[derive(Debug)] pub struct LayerNameChange { pub layer: Layer, pub old: Option, pub new: Option, } /// Library presence or exact record payloads, formatted only when rendered. #[derive(Debug)] pub enum LibraryChange { Presence { old: bool, new: bool, }, Record { tag: u16, old: Vec>, new: Vec>, }, } impl fmt::Display for LibraryChange { fn fmt(&self, out: &mut fmt::Formatter<'_>) -> fmt::Result { match self { Self::Presence { old, new } => out.write_str(match (old, new) { (false, true) => "added", (true, false) => "removed", (true, true) => "present", (false, false) => "absent", }), Self::Record { tag, old, new } => { let values = if old.len() <= 1 && new.len() <= 1 { format_field_change( *tag, old.first().map(Vec::as_slice), new.first().map(Vec::as_slice), ) } else { let list = |items: &[Vec]| { if items.is_empty() { return "absent".to_string(); } let values = items .iter() .map(|data| format_exact_value(*tag, data)) .collect::>() .join(", "); format!("[{values}]") }; format!("{} -> {}", list(old), list(new)) }; write!(out, "{} {values}", tag_name(*tag)) } } } } /// Owned revision metadata and reference counts captured before documents are dropped. #[derive(Debug)] pub struct Revision { pub scope: Scope, pub present: bool, pub units: Option>, cells: BTreeSet, known_cells: BTreeSet, edges: BTreeMap<(String, String), u64>, } impl Revision { fn from_document(doc: &Document<'_>) -> Self { Self { scope: doc.scope.clone(), present: doc.present, units: doc .header .iter() .find(|(tag, _)| *tag == RTAG_UNITS && doc.present) .map(|(_, data)| data.to_vec()), cells: doc.cells.keys().cloned().collect(), known_cells: doc.known_cells.clone(), edges: doc.edges(), } } } #[derive(Debug)] pub struct Comparison { pub old: Revision, pub new: Revision, /// Unchanged layer names available to the text report. pub layer_legend: BTreeMap, pub library_changes: Vec, pub layer_names: Vec, pub cells: Vec, pub diagnostics: Vec, } /// A comparison for text and hierarchy reports. #[derive(Debug)] pub struct TextComparison { comparison: Comparison, } impl TextComparison { pub fn between(old: &Document<'_>, new: &Document<'_>) -> Self { Self::collect(old, new, &BTreeSet::new()) } fn collect(old: &Document<'_>, new: &Document<'_>, reused_cells: &BTreeSet<&str>) -> Self { Self { comparison: Comparison::collect(old, new, reused_cells, false), } } pub fn render_text( &self, max_objects: usize, show: &DisplayFilter, show_library_presence: bool, ) -> String { self.comparison .render_text(max_objects, show, show_library_presence) } /// Render the cell changes and their ASCII hierarchy together. pub fn render_text_with_ascii_hierarchy( &self, max_objects: usize, show: &DisplayFilter, show_library_presence: bool, max_depth: usize, ) -> String { self.comparison.render_text_with_ascii_hierarchy( max_objects, show, show_library_presence, max_depth, ) } pub fn outcome(&self) -> Outcome { self.comparison.outcome() } pub fn hierarchy(&self, mermaid: bool, max_depth: usize) -> String { self.comparison.hierarchy(mermaid, max_depth) } } impl Comparison { pub fn between(old: &Document<'_>, new: &Document<'_>) -> Self { Self::collect(old, new, &BTreeSet::new(), true) } fn collect( old: &Document<'_>, new: &Document<'_>, reused_cells: &BTreeSet<&str>, include_whole_cell_objects: bool, ) -> Self { let mut result = Self { old: Revision::from_document(old), new: Revision::from_document(new), layer_legend: old .layer_names .iter() .filter(|(pair, name)| new.layer_names.get(pair) == Some(*name)) .map(|(pair, name)| (*pair, name.clone())) .collect(), library_changes: Vec::new(), layer_names: Vec::new(), cells: Vec::new(), diagnostics: Vec::new(), }; if old.present != new.present { result.library_changes.push(LibraryChange::Presence { old: old.present, new: new.present, }); } for (side, doc) in [(Side::Old, old), (Side::New, new)] { result .diagnostics .extend(doc.diagnostics.iter().cloned().map(|mut diagnostic| { diagnostic.side = Some(side); diagnostic })); } if old.scope != new.scope { result.diagnostics.push(Diagnostic::new( "scope_mismatch", "comparison scopes differ", None, )); } 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_changes.push(LibraryChange::Record { tag, old: a.into_iter().map(<[u8]>::to_vec).collect(), new: b.into_iter().map(<[u8]>::to_vec).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 { if reused_cells.contains(name.as_str()) { continue; } let a = old.cells.get(name); let b = new.cells.get(name); let mut change = CellChange { name: name.clone(), old: a.map(CellRevision::from), new: b.map(CellRevision::from), removed: Vec::new(), added: Vec::new(), replacements: Vec::new(), }; if !include_whole_cell_objects && (a.is_none() || b.is_none()) { let details = if a.is_some() { &mut change.removed } else { &mut change.added }; // The hierarchy uses the changed reference targets. details.extend( a.or(b) .into_iter() .flat_map(|cell| &cell.objects) .filter(|object| !object.metadata && object.target.is_some()) .map(ObjectChange::from), ); result.cells.push(change); continue; } 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.attributes_changed() || !change.removed.is_empty() || !change.added.is_empty() { change.replacements = changes::replacements(&change.removed, &change.added); result.cells.push(change); } } result } pub fn outcome(&self) -> Outcome { let different = !self.library_changes.is_empty() || !self.layer_names.is_empty() || !self.cells.is_empty(); if !self.diagnostics.is_empty() { Outcome::Incomplete { different } } else if different { Outcome::Different } else { Outcome::Equal } } /// Render the affected hierarchy. ASCII output shows relationships between cells. pub fn hierarchy(&self, mermaid: bool, max_depth: usize) -> String { render_hierarchy( &self.old, &self.new, Some(&self.cells), mermaid, max_depth, None, ) } /// Limit presentation only: the complete comparison has already been made. pub fn text(&self, max_objects: usize) -> String { self.text_filtered(max_objects, &DisplayFilter::default()) } pub fn text_filtered(&self, max_objects: usize, show: &DisplayFilter) -> String { self.render_text(max_objects, show, true) } /// Render a text report. Set `show_library_presence` to false when a file /// header already announces the library addition or deletion. pub fn render_text( &self, max_objects: usize, show: &DisplayFilter, show_library_presence: bool, ) -> String { self.render_text_report(max_objects, show, show_library_presence, None) } /// Render the cell changes and omit simple hierarchy edges already shown there. pub fn render_text_with_ascii_hierarchy( &self, max_objects: usize, show: &DisplayFilter, show_library_presence: bool, max_depth: usize, ) -> String { self.render_text_report(max_objects, show, show_library_presence, Some(max_depth)) } fn render_text_report( &self, max_objects: usize, show: &DisplayFilter, show_library_presence: bool, ascii_depth: Option, ) -> String { let outcome = self.outcome(); let mut out = match outcome { Outcome::Equal => "Equal", Outcome::Different => "Different", Outcome::Incomplete { .. } => "Incomplete", Outcome::Failed => "Failed", } .to_string(); let headline_end = out.len(); let library_changes = self.library_changes.iter().filter(|change| { show_library_presence || !matches!(change, LibraryChange::Presence { .. }) }); for (count, label) in [ (library_changes.clone().count(), "library change"), (self.layer_names.len(), "layer name change"), ] { if count != 0 { let plural = if count == 1 { "" } else { "s" }; write!(out, " · {count} {label}{plural}").unwrap(); } } out.push('\n'); self.old.scope.write_restrictions(&mut out); if show.cell.is_some() || show.layer.is_some() { out.push_str("Display filter"); if let Some(cell) = &show.cell { write!(out, " cell={cell:?}").unwrap(); } if let Some((layer, datatype)) = show.layer { write!(out, " layer={layer}/{datatype}").unwrap(); } out.push('\n'); } let notice_start = out.len(); for change in library_changes { writeln!(out, "library {change}").unwrap(); } if self.library_changes.iter().any(|change| { matches!( change, LibraryChange::Record { tag: RTAG_UNITS, .. } ) }) { out.push_str("Coordinates use each file's database units\n"); } for change in &self.layer_names { let name = |value: Option<&str>| { value.map_or_else(|| "absent".to_string(), |value| format!("{value:?}")) }; writeln!( out, "{}/{}: name {} -> {}", change.layer.0, change.layer.1, name(change.old.as_deref()), name(change.new.as_deref()) ) .unwrap(); } let body_start = out.len(); let mut removed_cells = String::new(); let mut added_cells = String::new(); let mut layers = changes::LayerRows::new(&self.layer_legend); let mut annotations = Vec::new(); let mut covered_edges = BTreeSet::new(); let mut detail_total = 0; let mut selected = 0; let mut shown: usize = 0; let mut hidden_cell_changes = 0; let visible = |object: &ObjectChange| show.layer.is_none_or(|layer| object.layer == Some(layer)); for cell in &self.cells { let marker = cell_marker(cell.old.is_some(), cell.new.is_some()); let attributes_changed = marker == '*' && cell.attributes_changed(); if marker == '*' { detail_total += cell.removed.len() + cell.added.len(); } if show.cell.as_ref().is_some_and(|name| name != &cell.name) { hidden_cell_changes += usize::from(marker != '*' || attributes_changed); continue; } let name = cell_label(&cell.name); match marker { '-' => { writeln!(removed_cells, "- {name}").unwrap(); continue; } '+' => { writeln!(added_cells, "+ {name}").unwrap(); continue; } _ => (), }; let note = if attributes_changed { " (attributes changed)" } else { "" }; let cell_start = out.len(); let previously_shown = shown; writeln!(out, "* {name}{note}").unwrap(); let mut polygons = changes::PolygonChanges::default(); let mut shown_refs = BTreeMap::<&str, changes::ShownReferences>::new(); let mut paired_old = BTreeSet::new(); let mut paired_new = BTreeSet::new(); for replacement in &cell.replacements { paired_old.insert(replacement.removed); paired_new.insert(replacement.added); let a = &cell.removed[replacement.removed]; let b = &cell.added[replacement.added]; if max_objects - shown >= 2 && visible(a) && visible(b) { if is_polygon(a.kind) { polygons.replacement(a, b); } else { out.push_str(" ~ "); let row_start = out.len(); layers.record(a.layer, row_start); writeln!(out, "{}", changes::replacement_summary(a, b)).unwrap(); if let Some(target) = &a.target { shown_refs .entry(target) .or_default() .replacement(a, b, row_start); } } shown += 2; } } let mut removed_refs = BTreeMap::new(); let mut added_refs = BTreeMap::new(); for (removed, objects, paired, references) in [ (true, &cell.removed, &paired_old, &mut removed_refs), (false, &cell.added, &paired_new, &mut added_refs), ] { let sign = if removed { "-" } else { "+" }; let mut unmatched: Vec<(&ObjectChange, usize)> = Vec::new(); for (index, object) in objects.iter().enumerate() { if !visible(object) { continue; } selected += 1; if !paired.contains(&index) && shown < max_objects { if is_polygon(object.kind) { polygons.unmatched(object, removed); } else if let Some(target) = object.target.as_deref() { let (_, counts) = references .entry(target) .or_insert_with(|| (object, changes::ReferenceCounts::default())); counts.add(object); } else if let Some((last, count)) = unmatched.last_mut() && last.kind == object.kind && last.fields == object.fields && last.properties == object.properties { *count += 1; } else { unmatched.push((object, 1)); } shown += 1; } } // The comparison orders these objects by kind, fields, and properties. for (object, count) in unmatched { write!(out, " {sign} ").unwrap(); if count > 1 { write!(out, "{count}× ").unwrap(); } layers.record(object.layer, out.len()); changes::write_unmatched(&mut out, object); } } let no_refs = changes::ReferenceCounts::default(); for (target, (first, counts)) in removed_refs { let row_start = out.len(); if let Some((_, added)) = added_refs.remove(target) { counts.write_change(&mut out, target, &added); shown_refs .entry(target) .or_default() .unmatched(&counts, &added, row_start); } else { counts.write(&mut out, "-", target, first); shown_refs .entry(target) .or_default() .unmatched(&counts, &no_refs, row_start); } } for (target, (first, counts)) in added_refs { let row_start = out.len(); counts.write(&mut out, "+", target, first); shown_refs .entry(target) .or_default() .unmatched(&no_refs, &counts, row_start); } if !shown_refs.is_empty() { for target in cell .removed .iter() .chain(&cell.added) .filter_map(|o| o.target.as_deref()) { if let Some(shown) = shown_refs.get_mut(target) { shown.count_change(); } } for (target, shown) in shown_refs { if shown.complete() { let edge = (cell.name.clone(), target.to_owned()); let old = self.old.edges.get(&edge).copied().unwrap_or(0); let new = self.new.edges.get(&edge).copied().unwrap_or(0); shown.annotate(&out, &mut annotations, old, new); if ascii_depth.is_some() && outcome.is_complete() { covered_edges.insert(edge); } } } } polygons.write(&mut out, &mut layers); if shown == previously_shown && !attributes_changed { out.truncate(cell_start); } } let mut before_cells = String::new(); layers.finish(&out, &mut annotations, &mut before_cells); // Resolve row offsets before inserting the section headers. if !annotations.is_empty() { annotations.sort_unstable_by_key(|(at, _)| *at); let mut annotated = String::with_capacity(out.len()); let mut start = 0; for (at, annotation) in annotations { annotated.push_str(&out[start..at]); annotated.push_str(&annotation); start = at; } annotated.push_str(&out[start..]); out = annotated; } if out.len() > body_start || !removed_cells.is_empty() || !added_cells.is_empty() { before_cells.push_str("Cells:\n"); before_cells.push_str(&removed_cells); before_cells.push_str(&added_cells); } out.insert_str(body_start, &before_cells); let mut omissions = Vec::new(); for (count, label, reason) in [ (detail_total - selected, "object change", "filtered out"), (selected - shown, "object change", "over the limit"), (hidden_cell_changes, "cell-level change", "filtered out"), ] { if count != 0 { let plural = if count == 1 { "" } else { "s" }; omissions.push(format!("{count} {label}{plural} {reason}")); } } if !omissions.is_empty() { out.insert_str( notice_start, &format!("Omitted · {}\n", omissions.join(" · ")), ); } const COMPACT_HEADLINE_CELL_LIMIT: usize = 3; if !self.cells.is_empty() && (self.cells.len() > COMPACT_HEADLINE_CELL_LIMIT || !outcome.is_complete() || !omissions.is_empty()) { let (mut modified, mut added, mut removed) = (0_usize, 0_usize, 0_usize); for cell in &self.cells { match cell_marker(cell.old.is_some(), cell.new.is_some()) { '-' => removed += 1, '+' => added += 1, _ => modified += 1, } } let mut counts = [ (modified, "modified"), (added, "added"), (removed, "removed"), ] .into_iter() .filter(|(count, _)| *count != 0); if let Some((count, action)) = counts.next() { let noun = if count == 1 { "cell" } else { "cells" }; let mut summary = format!(" · {count} {noun} {action}"); for (count, action) in counts { write!(summary, ", {count} {action}").unwrap(); } out.insert_str(headline_end, &summary); } } // General comparison errors precede revision-specific errors in text. if !self.diagnostics.is_empty() { out.push_str("Diagnostics\n"); for diagnostic in self .diagnostics .iter() .filter(|d| d.side.is_none()) .chain(self.diagnostics.iter().filter(|d| d.side.is_some())) { writeln!(out, " {diagnostic}").unwrap(); } } if let Some(max_depth) = ascii_depth { out.push_str(&render_hierarchy( &self.old, &self.new, Some(&self.cells), false, max_depth, Some(&covered_edges), )); } out } } /// Graph facts shared by text, Mermaid, and JSON renderers. struct HierarchyAnalysis<'a> { old_edges: &'a BTreeMap<(String, String), u64>, new_edges: &'a BTreeMap<(String, String), u64>, edges: BTreeSet<(String, String)>, direct: BTreeSet, affected: BTreeSet, changed_refs: BTreeSet<(String, String)>, } impl<'a> HierarchyAnalysis<'a> { fn between(old: &'a Revision, new: &'a Revision, changes: Option<&[CellChange]>) -> Self { 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<_> = changes .into_iter() .flatten() .map(|cell| cell.name.clone()) .collect(); let changed_refs: BTreeSet<_> = changes .into_iter() .flatten() .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()); } } } Self { old_edges, new_edges, edges, direct, affected, changed_refs, } } } /// The graph joins both revisions, retaining removed branches and old callers. fn render_hierarchy( old: &Revision, new: &Revision, changes: Option<&[CellChange]>, mermaid: bool, max_depth: usize, covered_edges: Option<&BTreeSet<(String, String)>>, ) -> String { if !mermaid && changes.is_some_and(<[CellChange]>::is_empty) { return String::new(); } let HierarchyAnalysis { old_edges, new_edges, edges, direct, affected, changed_refs, } = HierarchyAnalysis::between(old, new, changes); let mut visible: BTreeSet<_> = if changes.is_some() { affected .iter() .cloned() .chain(changed_refs.iter().map(|(_, t)| t.clone())) .collect() } else { old.cells .iter() .chain(new.cells.iter()) .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()); } } if let Some(covered) = covered_edges { if !covered.is_empty() { let mut incoming = BTreeMap::new(); for target in children.values().flatten() { *incoming.entry(target).or_insert(0_usize) += 1; } // Keep changed or shared descendants, branches, and target status notes. let redundant: BTreeSet<_> = covered .iter() .map(|(_, target)| target) .filter(|&target| { incoming.get(target) == Some(&1) && !children.contains_key(target) && !affected.contains(target) && old.cells.contains(target) && new.cells.contains(target) }) .collect(); children.retain(|_, children| { children.retain(|target| !redundant.contains(target)); !children.is_empty() }); targets.retain(|target| !redundant.contains(target)); } visible.retain(|name| children.contains_key(name) || targets.contains(name)); } if changes.is_some() && !mermaid && children.is_empty() { return String::new(); } 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 !old.cells.contains(name) && !new.cells.contains(name) { if old.known_cells.contains(name) || new.known_cells.contains(name) { " [outside scope]" } else { " [unresolved]" } } else if direct.contains(name) { if mermaid { " [cell changed]" } else { "" } } else if affected.contains(name) { " [affected]" } else if mermaid && changes.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 (mermaid || a == b) && 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(); if changes.is_none() && new.scope != Scope::default() { writeln!(out, " %% {}", new.scope.description()).unwrap(); } 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 = "Hierarchy\n".to_string(); if changes.is_none() { new.scope.write_restrictions(&mut out); } for (name, depth, parent, seen, limited) in rows { out.push_str(&" ".repeat(depth)); if direct.contains(&name) { let marker = cell_marker(old.cells.contains(&name), new.cells.contains(&name)); write!(out, "{marker} ").unwrap(); } if changes.is_some() { out.push_str(&cell_label(&name)); } else { write!(out, "{name:?}").unwrap(); } if let Some(parent) = parent { write!(out, " {}", edge_label(&parent, &name)).unwrap(); } writeln!( out, "{}{}{}", 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 cell_marker(old: bool, new: bool) -> char { match (old, new) { (true, false) => '-', (false, true) => '+', _ => '*', } } fn cell_label(name: &str) -> Cow<'_, str> { if name .bytes() .all(|b| b.is_ascii_alphanumeric() || matches!(b, b'_' | b'$' | b'?' | b'.' | b'-')) { Cow::Borrowed(name) } else { Cow::Owned(format!("{name:?}")) } } 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 real8_words(data: &[u8]) -> impl ExactSizeIterator + '_ { data.as_chunks::<8>() .0 .iter() .copied() .map(u64::from_be_bytes) } fn format_real8(data: &[u8], show_bytes: bool) -> String { let mut values = real8_words(data).map(decode_real8); let mut out = if values.len() == 1 { format!("{:?}", values.next().unwrap()) } else { format!("{:?}", values.collect::>()) }; if show_bytes { write!(out, " raw={}", hex(data)).unwrap(); } out } fn is_real8(tag: u16, data: &[u8]) -> bool { tag & 0xff == 5 && data.len().is_multiple_of(8) } fn format_exact_value(tag: u16, data: &[u8]) -> String { if is_real8(tag, data) { let show_bytes = real8_words(data).any(|bits| encode_real8(decode_real8(bits)).ok() != Some(bits)); format_real8(data, show_bytes) } else { format_data(tag, data) } } fn format_field_change(tag: u16, before: Option<&[u8]>, after: Option<&[u8]>) -> String { let show_bytes = before.zip(after).is_some_and(|(a, b)| { is_real8(tag, a) && is_real8(tag, b) && real8_words(a) .zip(real8_words(b)) .any(|(a, b)| a != b && decode_real8(a).to_bits() == decode_real8(b).to_bits()) }); let format_value = |data: Option<&[u8]>| match data { Some(data) if is_real8(tag, data) => format_real8(data, show_bytes), Some(data) => format_data(tag, data), None => "absent".to_string(), }; format!("{} -> {}", format_value(before), format_value(after)) } 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().is_multiple_of(2) => format!( "{:?}", data.as_chunks::<2>() .0 .iter() .copied() .map(i16::from_be_bytes) .collect::>() ), 3 if data.len().is_multiple_of(4) => format!( "{:?}", data.as_chunks::<4>() .0 .iter() .copied() .map(i32::from_be_bytes) .collect::>() ), 5 if data.len().is_multiple_of(8) => format!( "{:?} raw={}", real8_words(data).map(decode_real8).collect::>(), hex(data) ), 6 => quoted(data), _ => hex(data), } } fn object_name(kind: u16, rectangular: bool) -> &'static str { match kind { RTAG_BOUNDARY if rectangular => "rectangle", RTAG_BOUNDARY => "polygon", RTAG_BOX => "box", RTAG_PATH => "path", RTAG_SREF => "reference", RTAG_AREF => "array reference", RTAG_TEXT => "label", RTAG_NODE => "node", _ => kind_name(kind), } } 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() }