pheon/src/review.rs
Jan Petykiewicz 4aa36a6d65 Separate hierarchy traversal and text report modules
Build structured hierarchy rows and folded paths before rendering ASCII or Mermaid. Move compact and detailed diff writers alongside their text presentation helpers.
2026-11-19 09:29:21 -08:00

1679 lines
53 KiB
Rust
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

//! 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;
mod hierarchy;
pub mod names;
mod pair;
pub mod report;
pub mod selection;
mod text;
use changes::Replacement;
use pair::CellReuse;
pub use pair::RevisionPair;
use selection::{DisplayFilter, Scope};
pub use text::{TextReport, TextReportOptions, TextStyle};
/// 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, W: fmt::Write>(
out: &mut W,
kind: u16,
layer: Option<Layer>,
fields: impl Iterator<Item = (u16, &'a [u8])> + Clone,
properties: impl IntoIterator<Item = (u16, &'a [u8])>,
heading: impl FnOnce(&mut W, &'static str) -> fmt::Result,
) -> 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
};
heading(out, 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 impl fmt::Write, 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 {
self.format_with_heading(out, |out, name| write_object_heading(out, self.layer, name))
}
}
fn write_object_heading(
out: &mut impl fmt::Write,
layer: Option<Layer>,
name: &str,
) -> fmt::Result {
if let Some((layer, datatype)) = layer {
write!(out, "{layer}/{datatype}: ")?;
}
out.write_str(name)
}
impl Object<'_> {
fn format_with_heading<W: fmt::Write>(
&self,
out: &mut W,
heading: impl FnOnce(&mut W, &'static str) -> fmt::Result,
) -> 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(),
heading,
)
}
}
#[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);
hierarchy::render_hierarchy(&revision, &revision, None, mermaid, max_depth)
}
pub fn canonical_dump(&self) -> String {
let mut out = TextReport::default();
self.write_canonical_dump(&mut out);
out.into_string()
}
/// Append the canonical object dump and its presentation roles.
pub fn write_canonical_dump(&self, out: &mut TextReport) {
if !self.present {
out.write_styled(TextStyle::Heading, format_args!("library absent"));
out.push('\n');
return;
}
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());
out.write_styled(
TextStyle::Heading,
format_args!(
"library {} (GDSII {version}, {} user units/dbu, {} m/dbu)",
quoted(header(RTAG_LIBNAME)),
format_exact_value(RTAG_UNITS, user),
format_exact_value(RTAG_UNITS, meters)
),
);
out.push('\n');
self.scope.write_restrictions(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 {
out.write_styled(TextStyle::Layer, format_args!("{layer}/{dtype}"));
writeln!(out, ": name {name:?}").unwrap();
}
for (name, cell) in &self.cells {
out.write_styled(TextStyle::Heading, format_args!("cell {name:?}"));
out.push('\n');
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;
}
out.push_str(" ");
if count != 1 {
write!(out, "{count}x ").unwrap();
}
object
.format_with_heading(out, |out, name| {
if let Some((layer, datatype)) = object.layer {
out.write_styled(TextStyle::Layer, format_args!("{layer}/{datatype}"));
out.push_str(": ");
}
if matches!(object.kind, RTAG_SREF | RTAG_AREF) && object.layer.is_none() {
out.write_styled(TextStyle::Layer, format_args!("{name}"));
} else {
out.push_str(name);
}
Ok(())
})
.unwrap();
out.push('\n');
}
}
for diagnostic in &self.diagnostics {
out.write_styled(
TextStyle::Warning,
format_args!("INCOMPLETE: {}", diagnostic.message),
);
out.push('\n');
}
}
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> {
let mut out = TextReport::default();
write_record_dump(&mut out, input)?;
Ok(out.into_string())
}
/// Append the raw record dump and its presentation roles.
pub fn write_record_dump(out: &mut TextReport, input: &[u8]) -> Result<(), String> {
write_records(out, &read_records(input)?);
Ok(())
}
fn format_records(records: &[Record<'_>]) -> String {
let mut out = TextReport::default();
write_records(&mut out, records);
out.into_string()
}
fn write_records(out: &mut TextReport, records: &[Record<'_>]) {
for record in records {
write!(out, "{:010} {:04x} ", record.offset, record.tag).unwrap();
out.write_styled(TextStyle::Layer, format_args!("{}", tag_name(record.tag)));
writeln!(
out,
" size={} {}",
record.data.len() + 4,
format_data(
record.tag,
if record.tag & 0xff == 6 {
unpad_ascii(record.data)
} else {
record.data
}
)
)
.unwrap();
}
}
/// 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 {
self.format_with_heading(out, |out, name| write_object_heading(out, self.layer, name))
}
}
impl ObjectChange {
fn format_with_heading<W: fmt::Write>(
&self,
out: &mut W,
heading: impl FnOnce(&mut W, &'static str) -> fmt::Result,
) -> 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())),
heading,
)
}
}
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 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 {
hierarchy::render_hierarchy(&self.old, &self.new, Some(&self.cells), mermaid, max_depth)
}
}
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()
}