feat(review): add versioned JSON comparison reports

This commit is contained in:
Jan Petykiewicz 2026-11-15 10:38:48 -08:00
commit 248f6bcff7

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

@ -0,0 +1,545 @@
use super::*;
use klamath_rs_ext::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 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(
&klamath_rs_ext::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!("klamath 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_klamath"))
.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_klamath"))
.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("KLAMATH_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!("klamath 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_klamath"))
.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");
}