Introduce Pheon GDSII parsing and layout review tools

Implement native GDSII reading and writing with Arrow interchange, hierarchy
scans and selective cell loading. Validate numeric packing and array pitches,
and preserve normalized REAL8 encodings exactly within the supported range.

Add standalone dump, structural diff, hierarchy, layer-name annotation and Git
diff commands. Provide scoped text and JSON reports, deterministic comparison,
and record-preserving metadata edits.

Package the shared library and optional Python Arrow readers as pheon using
CFFI ABI mode and Python-independent platform wheels. Include locked source
builds, native API checks, cross-platform artifact workflows, documentation
and regression coverage. Require Rust 1.88 or newer and Python 3.11 or newer.

Validation: 87 native tests, 14 binding tests on Python 3.11/3.13/3.14,
and 71 installed companion integration tests pass. Full, scanned and selected
Arrow layouts match the previous schemas.
This commit is contained in:
Jan Petykiewicz 2026-11-16 16:21:21 -08:00
commit b3346b40a4

633
tests/review/reports.rs Normal file
View file

@ -0,0 +1,633 @@
use super::*;
use pheon::review::{
DisplayFilter, Scope,
report::{ReportInputs, ReportOptions, failure_report},
};
use serde_json::{Value, json};
fn inputs() -> ReportInputs {
ReportInputs {
old: Some("before.gds".into()),
new: Some("after.gds".into()),
}
}
fn report(old: &[u8], new: &[u8], options: &ReportOptions) -> Value {
let a = Document::parse(old).unwrap();
let b = Document::parse(new).unwrap();
Comparison::between(&a, &b).json_report(&a, &b, &inputs(), options)
}
fn unknown(geometry: Vec<u8>) -> Vec<u8> {
let mut object = geometry;
object.truncate(object.len() - 4);
record(&mut object, 0x7f02, &[0, 42]);
record(&mut object, RTAG_ENDEL, &[]);
layout(&[("CHIP", vec![object])])
}
#[test]
fn reports_preserve_fixture_results_totals_and_replacement_links() {
for pair in corpus() {
let r = report(&pair.old, &pair.new, &ReportOptions::default());
assert_eq!(r["schema_version"], 1);
assert_eq!(r["comparison_profile"], "klamath-object-v2");
assert_eq!(r["producer"]["version"], env!("CARGO_PKG_VERSION"));
assert_eq!(r["status"], "complete", "{}", pair.name);
assert_eq!(
r["exit_code"],
if pair.changed_cells + pair.metadata == 0 {
0
} else {
1
}
);
assert_eq!(
r["summary"]["changed_cells"],
pair.changed_cells.to_string()
);
assert_eq!(r["summary"]["added_objects"], pair.added.to_string());
assert_eq!(r["summary"]["removed_objects"], pair.removed.to_string());
assert_eq!(
r["summary"]["layer_name_changes"],
pair.metadata.to_string()
);
assert_eq!(r["report_selection"]["truncated"], false);
for cell in r["cell_changes"].as_array().unwrap() {
for replacement in cell["replacements"].as_array().unwrap() {
assert!(
cell["removed"]
.as_array()
.unwrap()
.iter()
.any(|o| o["id"] == replacement["removed"])
);
assert!(
cell["added"]
.as_array()
.unwrap()
.iter()
.any(|o| o["id"] == replacement["added"])
);
}
}
assert_eq!(r, report(&pair.old, &pair.new, &ReportOptions::default()));
}
}
#[test]
fn incomplete_reports_distinguish_known_differences_and_include_structured_locations() {
let a = unknown(square());
let same = report(&a, &a, &ReportOptions::default());
assert_eq!(same["status"], "incomplete");
assert_eq!(same["result"], "unknown");
assert_eq!(same["exit_code"], 2);
assert_eq!(same["summary"]["counts"], "observed");
let diagnostic = &same["diagnostics"][0];
assert_eq!(diagnostic["code"], "unsupported_record");
assert_eq!(diagnostic["side"], "old");
assert_eq!(diagnostic["cell"], "CHIP");
assert_eq!(diagnostic["layer"], json!({"number":1,"purpose":0}));
let offset: usize = diagnostic["byte_offset"].as_str().unwrap().parse().unwrap();
assert_eq!(&a[offset + 2..offset + 4], &0x7f02_u16.to_be_bytes());
let changed = report(&a, &unknown(triangle()), &ReportOptions::default());
assert_eq!(changed["status"], "incomplete");
assert_eq!(changed["result"], "different");
assert_eq!(changed["exit_code"], 2);
assert_eq!(
changed["cell_changes"][0]["removed"][0]["fields"]
.as_array()
.unwrap()
.last()
.unwrap()["payload_hex"],
"0x002a"
);
}
#[test]
fn future_layer_metadata_remains_incomplete_under_geometry_scopes() {
for location in ["CHIP", "legend"] {
let bytes = if location == "CHIP" {
layout(&[(
"CHIP",
vec![square(), label((900, 7), "KLAMATH_LAYER_NAMES_V2")],
)])
} else {
layout(&[
("CHIP", vec![square()]),
("legend", vec![label((900, 7), "KLAMATH_LAYER_NAMES_V2")]),
])
};
let source = Document::parse(&bytes).unwrap().diagnostics[0].offset;
for scope in [
Scope::default(),
Scope {
layer: Some((1, 0)),
..Default::default()
},
Scope {
layer: Some((999, 0)),
..Default::default()
},
Scope {
top: Some("CHIP".into()),
..Default::default()
},
Scope {
cell: Some("CHIP".into()),
..Default::default()
},
Scope {
top: Some("CHIP".into()),
layer: Some((1, 0)),
..Default::default()
},
Scope {
cell: Some("CHIP".into()),
layer: Some((1, 0)),
..Default::default()
},
] {
let doc = Document::parse(&bytes)
.unwrap()
.selected(&scope, false)
.unwrap();
assert_eq!(doc.diagnostics.len(), 1, "{scope:?}");
let diagnostic = &doc.diagnostics[0];
assert_eq!(diagnostic.code, "unsupported_metadata_version");
assert_eq!(diagnostic.cell.as_deref(), Some(location));
assert_eq!(diagnostic.layer, Some((900, 7)));
assert_eq!(diagnostic.offset, source);
let diff = Comparison::between(&doc, &doc);
assert_eq!(diff.exit_code(), 2);
assert!(!diff.is_equal());
assert!(diff.text(0).contains("INCOMPLETE"));
let json = diff.json_report(&doc, &doc, &inputs(), &ReportOptions::default());
assert_eq!(json["status"], "incomplete");
assert_eq!(json["result"], "unknown");
assert_eq!(json["exit_code"], 2);
assert_eq!(json["diagnostics"].as_array().unwrap().len(), 2);
}
}
}
#[test]
fn json_is_unbounded_by_default_and_explicit_filters_do_not_change_totals() {
let a = layout(&[("CHIP", vec![])]);
let b = layout(&[("CHIP", vec![square(); 120])]);
let full = report(&a, &b, &ReportOptions::default());
assert_eq!(
full["cell_changes"][0]["added"].as_array().unwrap().len(),
120
);
let limited = report(
&a,
&b,
&ReportOptions {
max_objects: Some(1),
..Default::default()
},
);
assert_eq!(limited["summary"], full["summary"]);
assert_eq!(limited["exit_code"], 1);
assert_eq!(limited["report_selection"]["truncated"], true);
assert_eq!(limited["report_selection"]["limited_objects"], "119");
assert_eq!(limited["report_selection"]["emitted_objects"], "1");
let filtered = report(
&a,
&b,
&ReportOptions {
filter: DisplayFilter {
cell: Some("absent".into()),
layer: None,
},
..Default::default()
},
);
assert_eq!(filtered["summary"], full["summary"]);
assert_eq!(filtered["cell_changes"], json!([]));
assert_eq!(filtered["report_selection"]["filtered_cells"], "1");
assert_eq!(filtered["report_selection"]["filtered_objects"], "120");
let filtered = report(
&a,
&b,
&ReportOptions {
filter: DisplayFilter {
cell: None,
layer: Some((2, 0)),
},
..Default::default()
},
);
assert_eq!(filtered["summary"], full["summary"]);
assert_eq!(filtered["report_selection"]["filtered_objects"], "120");
assert_eq!(filtered["cell_changes"][0]["added"], json!([]));
}
#[test]
fn typed_evidence_preserves_defaults_properties_bytes_and_real_encodings() {
let mut a = reference("leaf", 0, 1);
a.truncate(a.len() - 4);
record(&mut a, RTAG_MAG, &0x4110000000000000_u64.to_be_bytes());
record(&mut a, RTAG_PROPATTR, &17_u16.to_be_bytes());
record(&mut a, RTAG_PROPVALUE, &[0xff, 0xfe]);
record(&mut a, RTAG_PROPATTR, &17_u16.to_be_bytes());
record(&mut a, RTAG_PROPVALUE, &[0xff, 0xfe]);
record(&mut a, RTAG_ENDEL, &[]);
let mut b = a.clone();
let mag = Document::parse(&layout(&[("CHIP", vec![a.clone()]), ("leaf", vec![])]))
.unwrap()
.records
.into_iter()
.find(|r| r.tag == RTAG_MAG)
.unwrap()
.offset;
// Replace the REAL8 payload within the object, retaining the same decoded value.
let within = a
.windows(8)
.position(|v| v == 0x4110000000000000_u64.to_be_bytes())
.unwrap();
b[within..within + 8].copy_from_slice(&0x4201000000000000_u64.to_be_bytes());
let a = layout(&[("CHIP", vec![a]), ("leaf", vec![])]);
let b = layout(&[("CHIP", vec![b]), ("leaf", vec![])]);
let r = report(&a, &b, &ReportOptions::default());
let replacement = &r["cell_changes"][0]["replacements"][0];
assert_eq!(replacement["match_rule"], "unique_kind_target");
let change = &replacement["field_changes"][0];
assert_eq!(change["tag"], RTAG_MAG);
assert_eq!(change["before"]["value"], change["after"]["value"]);
assert_ne!(
change["before"]["payload_hex"],
change["after"]["payload_hex"]
);
let removed = &r["cell_changes"][0]["removed"][0];
assert_eq!(removed["properties"].as_array().unwrap().len(), 2);
assert_eq!(removed["properties"][0]["attribute"], 17);
assert_eq!(removed["properties"][0]["value"], Value::Null);
assert_eq!(removed["properties"][0]["payload_hex"], "0xfffe");
let offset: usize = removed["source"]["byte_offset"]
.as_str()
.unwrap()
.parse()
.unwrap();
assert!(offset < mag);
let end: usize = removed["source"]["end_offset"]
.as_str()
.unwrap()
.parse()
.unwrap();
assert_eq!(&a[end - 4..end], &[0, 4, 17, 0]);
let mut path = square();
path[2..4].copy_from_slice(&RTAG_PATH.to_be_bytes());
let mut width = path.clone();
width.truncate(width.len() - 4);
record(&mut width, RTAG_WIDTH, &0_i32.to_be_bytes());
record(&mut width, RTAG_ENDEL, &[]);
let r = report(
&layout(&[("CHIP", vec![path])]),
&layout(&[("CHIP", vec![width])]),
&ReportOptions::default(),
);
let change = &r["cell_changes"][0]["replacements"][0]["field_changes"][0];
assert_eq!(change["tag"], RTAG_WIDTH);
assert_eq!(change["before"], Value::Null);
assert_eq!(change["after"]["value"], json!([0]));
}
#[test]
fn hierarchy_reports_shared_ancestors_and_symbolic_arrays() {
let options = ReportOptions {
hierarchy: true,
..Default::default()
};
let r = report(&shared(square()), &shared(triangle()), &options);
let graph = &r["hierarchy"];
assert_eq!(graph["nodes"].as_array().unwrap().len(), 4);
assert_eq!(
graph["nodes"]
.as_array()
.unwrap()
.iter()
.find(|n| n["cell"] == "CHIP")
.unwrap()["change"],
"affected"
);
assert_eq!(
graph["nodes"]
.as_array()
.unwrap()
.iter()
.find(|n| n["cell"] == "leaf")
.unwrap()["change"],
"direct"
);
let edge = graph["edges"]
.as_array()
.unwrap()
.iter()
.find(|e| e["parent"] == "right")
.unwrap();
assert_eq!(edge["before_count"], "3");
assert_eq!(edge["reference_changed"], false);
let bytes = shared(square());
let scope = Scope {
cell: Some("CHIP".into()),
..Default::default()
};
let doc = Document::parse(&bytes)
.unwrap()
.selected(&scope, false)
.unwrap();
let r = Comparison::between(&doc, &doc).json_report(&doc, &doc, &inputs(), &options);
assert_eq!(r["scope"]["cell"], "CHIP");
assert_eq!(
r["hierarchy"]["nodes"]
.as_array()
.unwrap()
.iter()
.find(|n| n["cell"] == "left")
.unwrap()["after"],
"outside_scope"
);
let dangling = layout(&[("CHIP", vec![reference("missing", 0, 1)])]);
let r = report(&dangling, &dangling, &options);
assert_eq!(r["diagnostics"][0]["code"], "unresolved_reference");
assert_eq!(r["diagnostics"][0]["target"], "missing");
assert_eq!(r["hierarchy"]["nodes"][1]["after"], "unresolved");
let cycle = layout(&[("CHIP", vec![reference("CHIP", 0, 1)])]);
assert_eq!(
report(&cycle, &cycle, &options)["diagnostics"][0]["code"],
"hierarchy_cycle"
);
}
#[test]
fn library_attributes_empty_cells_units_and_absence_are_explicit() {
let a = layout(&[]);
let b = layout(&[("empty", vec![])]);
let r = report(&a, &b, &ReportOptions::default());
assert_eq!(r["cell_changes"][0]["before"], Value::Null);
assert_eq!(r["cell_changes"][0]["after"]["attributes"], json!([]));
let mut b = b;
let end = Document::parse(&b).unwrap().cells["empty"].end_offset;
let mut attribute = Vec::new();
record(&mut attribute, RTAG_STRCLASS, &[0, 1]);
b.splice(end..end, attribute);
let r = report(&layout(&[("empty", vec![])]), &b, &ReportOptions::default());
assert_eq!(
r["cell_changes"][0]["after"]["attributes"][0]["value"],
json!([1])
);
assert_eq!(r["inputs"]["old"]["units"]["encoding"], "real8");
let doc = Document::parse(&a).unwrap();
let absent = doc.empty_like();
let r = Comparison::between(&absent, &doc).json_report(
&absent,
&doc,
&inputs(),
&ReportOptions::default(),
);
assert_eq!(r["inputs"]["old"]["present"], false);
assert_eq!(r["inputs"]["old"]["units"], Value::Null);
assert_eq!(
r["library_changes"],
json!([{"field":"presence","tag":null,"before":false,"after":true}])
);
let mut b = a.clone();
let units = doc
.records
.iter()
.find(|r| r.tag == RTAG_UNITS)
.unwrap()
.offset;
b[units + 12..units + 20].copy_from_slice(
&pheon::basic::encode_real8(2e-9)
.unwrap()
.to_be_bytes(),
);
let r = report(&a, &b, &ReportOptions::default());
assert_eq!(r["library_changes"][0]["tag"], RTAG_UNITS);
assert_ne!(r["inputs"]["old"]["units"], r["inputs"]["new"]["units"]);
}
#[test]
fn reports_keep_extreme_coordinates_unsigned_layers_and_timestamp_equality() {
let a = layout(&[("quoted\"\\\n日本", vec![])]);
let mut shape = polygon(&[
[i32::MIN, i32::MIN],
[i32::MAX, i32::MIN],
[i32::MAX, i32::MAX],
[i32::MIN, i32::MAX],
[i32::MIN, i32::MIN],
]);
shape[8..10].copy_from_slice(&u16::MAX.to_be_bytes());
let b = layout(&[("quoted\"\\\n日本", vec![shape])]);
let r = report(&a, &b, &ReportOptions::default());
let object = &r["cell_changes"][0]["added"][0];
assert_eq!(object["layer"]["number"], u16::MAX);
assert_eq!(
object["bounds"],
json!([i32::MIN, i32::MIN, i32::MAX, i32::MAX])
);
let encoded = serde_json::to_string(&r).unwrap();
assert_eq!(serde_json::from_str::<Value>(&encoded).unwrap(), r);
let mut times = b.clone();
let doc = Document::parse(&b).unwrap();
for record in doc
.records
.iter()
.filter(|r| matches!(r.tag, RTAG_BGNLIB | RTAG_BGNSTR))
{
times[record.offset + 4..record.offset + 28].fill(1);
}
let r = report(&b, &times, &ReportOptions::default());
assert_eq!(r["result"], "equal");
assert_eq!(r["exit_code"], 0);
}
#[cfg(unix)]
#[test]
fn cli_preserves_non_utf8_path_bytes_and_literal_option_names() {
use std::os::unix::ffi::OsStringExt;
let directory = std::env::temp_dir().join(format!("pheon json paths {}", std::process::id()));
fs::create_dir_all(&directory).unwrap();
struct Cleanup(PathBuf);
impl Drop for Cleanup {
fn drop(&mut self) {
let _ = fs::remove_dir_all(&self.0);
}
}
let _cleanup = Cleanup(directory.clone());
let path = directory.join(std::ffi::OsString::from_vec(b"file\xff.gds".to_vec()));
fs::write(&path, layout(&[])).unwrap();
let output = Command::new(env!("CARGO_BIN_EXE_pheon"))
.arg("diff")
.args(["--format", "json", "--"])
.arg(&path)
.arg(&path)
.output()
.unwrap();
assert_eq!(output.status.code(), Some(0));
let r: Value = serde_json::from_slice(&output.stdout).unwrap();
assert_eq!(r["inputs"]["old"]["path"], Value::Null);
let expected = "0x".to_string()
+ &path
.as_os_str()
.as_encoded_bytes()
.iter()
.map(|b| format!("{b:02x}"))
.collect::<String>();
assert_eq!(r["inputs"]["old"]["path_encoded_hex"], expected);
for name in ["--format", "json"] {
fs::write(directory.join(name), layout(&[])).unwrap();
}
let output = Command::new(env!("CARGO_BIN_EXE_pheon"))
.current_dir(&directory)
.args(["diff", "--", "--format", "json"])
.output()
.unwrap();
assert_eq!(output.status.code(), Some(0));
assert!(
String::from_utf8(output.stdout)
.unwrap()
.starts_with("profile ")
);
}
#[test]
fn machine_reports_match_versioned_goldens() {
let options = ReportOptions {
hierarchy: true,
..Default::default()
};
let equal = layout(&[("CHIP", vec![square()])]);
let metadata = corpus()
.into_iter()
.find(|p| p.name == "layer name only")
.unwrap();
let samples = [
("equal", report(&equal, &equal, &ReportOptions::default())),
(
"geometry",
report(&shared(square()), &shared(triangle()), &options),
),
(
"metadata",
report(&metadata.old, &metadata.new, &ReportOptions::default()),
),
(
"incomplete",
report(
&unknown(square()),
&unknown(square()),
&ReportOptions::default(),
),
),
(
"failed",
failure_report(
&inputs(),
&Scope::default(),
&ReportOptions::default(),
"invalid_input",
"truncated record",
Some("new"),
),
),
];
for (name, mut actual) in samples {
actual["producer"]["version"] = json!("test");
let path = PathBuf::from(env!("CARGO_MANIFEST_DIR"))
.join(format!("tests/golden/report-{name}.json"));
if std::env::var_os("PHEON_UPDATE_REPORT_GOLDENS").is_some() {
fs::write(&path, serde_json::to_string_pretty(&actual).unwrap() + "\n").unwrap();
}
let expected: Value = serde_json::from_slice(&fs::read(&path).unwrap()).unwrap();
assert_eq!(actual, expected, "{name}");
}
}
#[test]
fn cli_emits_json_for_success_input_errors_scope_errors_and_argument_errors() {
let directory = std::env::temp_dir().join(format!("pheon json {}", std::process::id()));
fs::create_dir_all(&directory).unwrap();
struct Cleanup(PathBuf);
impl Drop for Cleanup {
fn drop(&mut self) {
let _ = fs::remove_dir_all(&self.0);
}
}
let _cleanup = Cleanup(directory.clone());
let a = directory.join("before file.gds");
let b = directory.join("after file.gds");
fs::write(&a, shared(square())).unwrap();
fs::write(&b, shared(triangle())).unwrap();
let command = |extra: &[&str]| {
let output = Command::new(env!("CARGO_BIN_EXE_pheon"))
.arg("diff")
.arg(&a)
.arg(&b)
.args(["--format", "json"])
.args(extra)
.output()
.unwrap();
assert!(output.stderr.is_empty(), "{:?}", output.stderr);
let report: Value = serde_json::from_slice(&output.stdout).unwrap();
assert_eq!(
output.status.code().unwrap(),
report["exit_code"].as_i64().unwrap() as i32
);
report
};
let full = command(&["--hierarchy", "graph"]);
assert_eq!(full["result"], "different");
assert!(full["hierarchy"].is_object());
let limited = command(&["--max-changes", "0"]);
assert_eq!(limited["summary"], full["summary"]);
assert_eq!(limited["report_selection"]["emitted_objects"], "0");
for extra in [
&["--top", "missing"][..],
&["--unknown"],
&["--max-changes", "x"],
&["--hierarchy", "mermaid"],
&["--depth", "3"],
] {
let failure = command(extra);
assert_eq!(failure["status"], "failed");
assert_eq!(failure["result"], "unknown");
assert_eq!(failure["summary"], Value::Null);
}
fs::write(&b, b"invalid").unwrap();
let invalid = command(&[]);
assert_eq!(invalid["diagnostics"][0]["code"], "invalid_input");
assert_eq!(invalid["diagnostics"][0]["side"], "new");
assert_eq!(invalid["inputs"]["new"]["path"], b.to_str().unwrap());
fs::remove_file(&b).unwrap();
assert_eq!(command(&[])["diagnostics"][0]["code"], "io_error");
fs::write(&b, fs::read(&a).unwrap()).unwrap();
assert_eq!(command(&[])["result"], "equal");
fs::write(&b, unknown(square())).unwrap();
assert_eq!(command(&[])["status"], "incomplete");
fs::write(
&b,
layout(&[
("CHIP", vec![square()]),
("legend", vec![label((900, 7), "KLAMATH_LAYER_NAMES_V2")]),
]),
)
.unwrap();
for flags in [
&["--layer", "1/0"][..],
&["--top", "CHIP"],
&["--cell", "CHIP", "--layer", "1/0"],
] {
let report = command(flags);
assert_eq!(report["status"], "incomplete");
assert_eq!(report["exit_code"], 2);
assert_eq!(
report["diagnostics"][0]["code"],
"unsupported_metadata_version"
);
}
}