pheon/src/review.rs

2331 lines
77 KiB
Rust
Raw Normal View History

//! 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<Side>,
pub offset: Option<usize>,
pub cell: Option<String>,
pub layer: Option<Layer>,
pub target: Option<String>,
}
impl Diagnostic {
pub fn new(code: &'static str, message: impl Into<String>, side: Option<Side>) -> 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<Layer>,
pub bounds: Option<Bounds>,
pub target: Option<String>,
pub multiplicity: u64,
key: Key<'a>,
metadata: bool,
issues: Vec<Diagnostic>,
}
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<Layer>,
fields: impl Iterator<Item = (u16, &'a [u8])> + Clone,
properties: impl IntoIterator<Item = (u16, &'a [u8])>,
) -> 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<Object<'a>>,
attributes: Vec<(u16, &'a [u8])>,
issues: Vec<Diagnostic>,
}
#[derive(Debug)]
pub struct Document<'a> {
pub records: Vec<Record<'a>>,
pub cells: BTreeMap<String, Cell<'a>>,
pub layer_names: BTreeMap<Layer, String>,
/// Unsupported features or invalid reference graphs prevent an equality claim.
pub diagnostics: Vec<Diagnostic>,
header: Vec<(u16, &'a [u8])>,
global_issues: Vec<Diagnostic>,
known_cells: BTreeSet<String>,
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<String, String> {
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<Item = [i32; 2]>) -> 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<Cow<'_, [u8]>> {
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<Diagnostic>) -> Result<Object<'a>, 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<Vec<Record<'_>>, String> {
read_records_with(input, |_, _| {})
}
fn read_records_with<'a>(
input: &'a [u8],
mut observe: impl FnMut(usize, &Record<'a>),
) -> Result<Vec<Record<'a>>, 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<Self, String> {
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<CellReuse<'a, '_>>,
) -> Result<Self, String> {
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<String, String> {
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<u8>,
}
fn owned_fields<'a>(fields: impl IntoIterator<Item = (u16, &'a [u8])>) -> Vec<FieldValue> {
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<Layer>,
pub bounds: Option<Bounds>,
pub target: Option<String>,
pub origin: Option<[i32; 2]>,
pub width: Option<i32>,
pub counts: Option<[u16; 2]>,
pub fields: Vec<FieldValue>,
pub properties: Vec<(u16, Vec<u8>)>,
}
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<FieldValue>,
}
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<CellRevision>,
pub new: Option<CellRevision>,
pub removed: Vec<ObjectChange>,
pub added: Vec<ObjectChange>,
pub replacements: Vec<Replacement>,
}
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<String>,
pub new: Option<String>,
}
/// 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<Vec<u8>>,
new: Vec<Vec<u8>>,
},
}
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<u8>]| {
if items.is_empty() {
return "absent".to_string();
}
let values = items
.iter()
.map(|data| format_exact_value(*tag, data))
.collect::<Vec<_>>()
.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<Vec<u8>>,
cells: BTreeSet<String>,
known_cells: BTreeSet<String>,
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<Layer, String>,
pub library_changes: Vec<LibraryChange>,
pub layer_names: Vec<LayerNameChange>,
pub cells: Vec<CellChange>,
pub diagnostics: Vec<Diagnostic>,
}
/// 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<usize>,
) -> 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<String>,
affected: BTreeSet<String>,
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::<String, Vec<String>>::new();
let mut targets = BTreeSet::new();
2026-11-18 23:04:24 -08:00
let fold_paths = !mermaid && changes.is_some();
let mut shared = BTreeSet::new();
for (parent, target) in &edges {
if visible.contains(parent) && visible.contains(target) {
children
.entry(parent.clone())
.or_default()
.push(target.clone());
2026-11-18 23:04:24 -08:00
if !targets.insert(target.clone()) && fold_paths {
shared.insert(target.clone());
}
}
}
if let Some(covered) = covered_edges {
if !covered.is_empty() {
// Keep changed or shared descendants, branches, and target status notes.
let redundant: BTreeSet<_> = covered
.iter()
.map(|(_, target)| target)
.filter(|&target| {
2026-11-18 23:04:24 -08:00
targets.contains(target)
&& !shared.contains(target)
&& !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();
2026-11-18 23:04:24 -08:00
struct Row {
name: String,
depth: usize,
parent: Option<String>,
note: &'static str,
}
let mut rows = Vec::new();
let mut stack: Vec<_> = roots
.iter()
.rev()
.map(|n| (n.clone(), 0, None::<String>))
.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(&[]);
let note = if descendants.is_empty() {
""
} else if depth >= max_depth {
" [children omitted]"
} else if seen {
" [subtree elided]"
} else {
""
};
2026-11-18 23:04:24 -08:00
rows.push(Row {
name: name.clone(),
depth,
parent,
note,
});
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) {
2026-11-18 23:04:24 -08:00
rows.push(Row {
name: name.clone(),
depth: 0,
parent: None,
note: " [children omitted]",
});
}
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()
2026-11-18 23:04:24 -08:00
.map(|row| &row.name)
.collect::<BTreeSet<_>>()
.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('&', "&amp;")
.replace('"', "&quot;")
.replace('<', "&lt;")
.replace('>', "&gt;")
.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 {
2026-11-18 23:04:24 -08:00
let single_placement = |parent: &String, target: &String| {
let key = (parent.clone(), target.clone());
old_edges.get(&key) == Some(&1)
&& new_edges.get(&key) == Some(&1)
&& !changed_refs.contains(&key)
};
let unbranched = |name: &String| {
!shared.contains(name)
&& children
.get(name)
.is_none_or(|descendants| descendants.len() == 1)
};
let can_join = |parent: &Row, child: &Row| {
child.parent.as_ref() == Some(&parent.name)
&& parent.note.is_empty()
&& !direct.contains(&parent.name)
&& affected.contains(&parent.name)
&& unbranched(&child.name)
&& (old.cells.contains(&child.name) || new.cells.contains(&child.name))
&& single_placement(&parent.name, &child.name)
};
let mut out = "Hierarchy\n".to_string();
if changes.is_none() {
new.scope.write_restrictions(&mut out);
}
2026-11-18 23:04:24 -08:00
let mut index = 0;
let mut ancestor_depths = Vec::new();
while let Some(first) = rows.get(index) {
let mut end = index;
if fold_paths
&& unbranched(&first.name)
&& first
.parent
.as_ref()
.is_none_or(|parent| single_placement(parent, &first.name))
{
while rows
.get(end + 1)
.is_some_and(|next| can_join(&rows[end], next))
{
end += 1;
}
// Two rows are already easy to scan.
if end - index < 2 {
end = index;
}
}
2026-11-18 23:04:24 -08:00
while ancestor_depths
.last()
.is_some_and(|&depth| depth >= first.depth)
{
ancestor_depths.pop();
}
2026-11-18 23:04:24 -08:00
out.push_str(&" ".repeat(ancestor_depths.len()));
for (i, row) in rows[index..=end].iter().enumerate() {
let name = &row.name;
if i != 0 {
out.push_str(" → ");
}
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 i == 0
&& let Some(parent) = &row.parent
{
write!(out, " {}", edge_label(parent, name)).unwrap();
}
}
2026-11-18 23:04:24 -08:00
let last = &rows[end];
writeln!(out, "{}{}", status(&last.name), last.note).unwrap();
ancestor_depths.push(last.depth);
index = end + 1;
}
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<Item = u64> + '_ {
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::<Vec<_>>())
};
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::<Vec<_>>()
),
3 if data.len().is_multiple_of(4) => format!(
"{:?}",
data.as_chunks::<4>()
.0
.iter()
.copied()
.map(i32::from_be_bytes)
.collect::<Vec<_>>()
),
5 if data.len().is_multiple_of(8) => format!(
"{:?} raw={}",
real8_words(data).map(decode_real8).collect::<Vec<_>>(),
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()
}