feat(review): add versioned JSON comparison reports

This commit is contained in:
Jan Petykiewicz 2026-11-15 10:38:48 -08:00
commit 248f6bcff7
5 changed files with 2312 additions and 43 deletions

View file

@ -1,3 +1,4 @@
use klamath_rs_ext::review::report::{ReportInputs, ReportOptions, failure_report};
use klamath_rs_ext::review::{
Comparison, DisplayFilter, Document, Scope, dump_records, hierarchy, parse_layer,
parse_layer_name, write_layer_names,
@ -7,12 +8,13 @@ use std::{
ffi::OsString,
fs,
io::{self, Write},
path::PathBuf,
process::ExitCode,
};
const HELP: &str = "Usage:
klamath dump FILE [--records]
klamath diff OLD NEW [--top NAME] [--cell NAME] [--layer L/T]\n [--show-cell NAME] [--show-layer L/T] [--hierarchy ascii|mermaid|none]\n [--max-changes N] [--depth N]
klamath diff OLD NEW [--top NAME] [--cell NAME] [--layer L/T]\n [--show-cell NAME] [--show-layer L/T] [--hierarchy ascii|mermaid|none|graph]\n [--max-changes N] [--depth N] [--format text|json]
klamath hierarchy FILE [--format ascii|mermaid] [--depth N] [--top NAME]\n klamath git-diff [OPTIONS] -- PATH OLD OLD_OID OLD_MODE NEW NEW_OID NEW_MODE
klamath name-layers INPUT OUTPUT --cell NAME --carrier L/T --name L:T:NAME ...
@ -85,8 +87,57 @@ fn stdout(output: &str) -> Result<(), String> {
.map_err(|e| e.to_string())
}
fn run() -> Result<u8, String> {
let args: Vec<_> = std::env::args_os().skip(1).collect();
fn json_stdout(report: &serde_json::Value) -> Result<(), String> {
let mut output = io::stdout().lock();
serde_json::to_writer_pretty(&mut output, report).map_err(|e| e.to_string())?;
output.write_all(b"\n").map_err(|e| e.to_string())
}
fn json_diff(paths: &[OsString], scope: &Scope, options: &ReportOptions) -> Result<u8, String> {
let inputs = ReportInputs {
old: Some(PathBuf::from(&paths[0])),
new: Some(PathBuf::from(&paths[1])),
};
let comparison = || {
let read = |index, side| {
fs::read(&paths[index])
.map_err(|e| ("io_error", format!("{:?}: {e}", paths[index]), Some(side)))
};
let old_bytes = read(0, "old")?;
let new_bytes = read(1, "new")?;
let old = Document::parse(&old_bytes).map_err(|e| ("invalid_input", e, Some("old")))?;
let new = Document::parse(&new_bytes).map_err(|e| ("invalid_input", e, Some("new")))?;
scope
.validate_pair(&old, &new)
.map_err(|e| ("invalid_scope", e, None))?;
let old = old
.selected(scope, true)
.map_err(|e| ("invalid_scope", e, Some("old")))?;
let new = new
.selected(scope, true)
.map_err(|e| ("invalid_scope", e, Some("new")))?;
let diff = Comparison::between(&old, &new);
Ok::<_, (&str, String, Option<&str>)>((
diff.json_report(&old, &new, &inputs, options),
diff.exit_code(),
))
};
let (report, status) = match comparison() {
Ok(result) => result,
Err((code, message, side)) => (
failure_report(&inputs, scope, options, code, &message, side),
2,
),
};
if let Err(error) = json_stdout(&report) {
// Once output starts, never append a second report on a write failure.
eprintln!("klamath: {error}");
return Ok(2);
}
Ok(status)
}
fn run(args: &[OsString]) -> Result<u8, String> {
if args.is_empty() || args[0] == "--help" || args[0] == "-h" {
stdout(HELP)?;
return Ok(0);
@ -111,7 +162,10 @@ fn run() -> Result<u8, String> {
"ascii".to_string()
};
let mut max_changes = 100;
let mut explicit_max = None;
let mut output_format = "text".to_string();
let mut depth = 8;
let mut explicit_depth = false;
let mut paths = Vec::new();
let mut literal = false;
let mut i = 1;
@ -128,22 +182,25 @@ fn run() -> Result<u8, String> {
return Ok(0);
}
Some("--records") if command == "dump" => raw = true,
Some("--top") => scope.top = Some(value(&args, &mut i)?),
Some("--cell") => scope.cell = Some(value(&args, &mut i)?),
Some("--layer") => scope.layer = Some(parse_layer(&value(&args, &mut i)?)?),
Some("--show-cell") if compare => show.cell = Some(value(&args, &mut i)?),
Some("--top") => scope.top = Some(value(args, &mut i)?),
Some("--cell") => scope.cell = Some(value(args, &mut i)?),
Some("--layer") => scope.layer = Some(parse_layer(&value(args, &mut i)?)?),
Some("--show-cell") if compare => show.cell = Some(value(args, &mut i)?),
Some("--show-layer") if compare => {
show.layer = Some(parse_layer(&value(&args, &mut i)?)?)
show.layer = Some(parse_layer(&value(args, &mut i)?)?)
}
Some("--hierarchy") if compare => format = value(&args, &mut i)?,
Some("--format") if command == "hierarchy" => format = value(&args, &mut i)?,
Some("--hierarchy") if compare => format = value(args, &mut i)?,
Some("--format") if command == "hierarchy" => format = value(args, &mut i)?,
Some("--format") if command == "diff" => output_format = value(args, &mut i)?,
Some("--max-changes") if compare => {
max_changes = value(&args, &mut i)?
max_changes = value(args, &mut i)?
.parse()
.map_err(|_| "invalid change limit")?
.map_err(|_| "invalid change limit")?;
explicit_max = Some(max_changes);
}
Some("--depth") if command != "dump" => {
depth = value(&args, &mut i)?.parse().map_err(|_| "invalid depth")?
depth = value(args, &mut i)?.parse().map_err(|_| "invalid depth")?;
explicit_depth = true;
}
Some(s) if s.starts_with('-') => return Err(format!("unknown option {s:?}")),
_ => paths.push(args[i].clone()),
@ -153,6 +210,25 @@ fn run() -> Result<u8, String> {
if paths.len() != expected && !(command == "git-diff" && paths.len() == 9) {
return Err(HELP.to_string());
}
if !matches!(output_format.as_str(), "text" | "json") {
return Err("diff format must be text or json".to_string());
}
if output_format == "json" {
if !matches!(format.as_str(), "none" | "graph") || explicit_depth {
return Err(
"JSON accepts --hierarchy graph|none; --depth applies to text output".to_string(),
);
}
return json_diff(
&paths,
&scope,
&ReportOptions {
filter: show,
max_objects: explicit_max,
hierarchy: format == "graph",
},
);
}
if !matches!(format.as_str(), "ascii" | "mermaid" | "none")
|| (command == "hierarchy" && format == "none")
{
@ -248,11 +324,51 @@ fn run() -> Result<u8, String> {
})
}
fn wants_json(args: &[OsString]) -> bool {
if args.first().is_none_or(|arg| arg != "diff") {
return false;
}
let mut format = None;
let mut i = 1;
while i < args.len() {
match args[i].to_str() {
Some("--") => break,
Some("--format") => {
format = args.get(i + 1).and_then(|v| v.to_str());
i += 1;
}
Some(
"--top" | "--cell" | "--layer" | "--show-cell" | "--show-layer" | "--hierarchy"
| "--max-changes" | "--depth",
) => i += 1,
_ => (),
}
i += 1;
}
format == Some("json")
}
fn main() -> ExitCode {
match run() {
let args: Vec<_> = std::env::args_os().skip(1).collect();
let json = wants_json(&args);
match run(&args) {
Ok(status) => ExitCode::from(status),
Err(message) => {
eprintln!("klamath: {message}");
if json {
let report = failure_report(
&ReportInputs::default(),
&Scope::default(),
&ReportOptions::default(),
"command_error",
&message,
None,
);
if let Err(error) = json_stdout(&report) {
eprintln!("klamath: {error}");
}
} else {
eprintln!("klamath: {message}");
}
ExitCode::from(2)
}
}

View file

@ -14,6 +14,31 @@ mod selection;
pub use selection::{DisplayFilter, Scope};
mod changes;
pub use changes::Replacement;
pub mod report;
/// A comparison limitation with source context independent of its wording.
#[derive(Clone, Debug)]
pub struct Diagnostic {
pub code: &'static str,
pub message: String,
pub offset: Option<usize>,
pub cell: Option<String>,
pub layer: Option<Layer>,
pub target: Option<String>,
}
impl Diagnostic {
fn at(code: &'static str, offset: usize, message: String) -> Self {
Self {
code,
message: error(offset, message),
offset: Some(offset),
cell: None,
layer: None,
target: None,
}
}
}
pub const PROFILE: &str = "klamath-object-v2";
pub const LAYER_SENTINEL: &str = "KLAMATH_LAYER_NAMES_V1";
@ -45,7 +70,7 @@ pub struct Object<'a> {
pub multiplicity: u64,
key: Key<'a>,
metadata: bool,
issues: Vec<String>,
issues: Vec<Diagnostic>,
}
impl Object<'_> {
@ -76,7 +101,7 @@ pub struct Cell<'a> {
pub end_offset: usize,
pub objects: Vec<Object<'a>>,
attributes: Vec<(u16, &'a [u8])>,
issues: Vec<String>,
issues: Vec<Diagnostic>,
}
#[derive(Debug)]
@ -86,8 +111,9 @@ pub struct Document<'a> {
pub layer_names: BTreeMap<Layer, String>,
/// Unsupported features or invalid reference graphs prevent an equality claim.
pub issues: Vec<String>,
pub diagnostics: Vec<Diagnostic>,
header: Vec<(u16, &'a [u8])>,
global_issues: Vec<String>,
global_issues: Vec<Diagnostic>,
known_cells: BTreeSet<String>,
pub scope: Scope,
present: bool,
@ -246,7 +272,7 @@ fn allowed_field(kind: u16, tag: u16) -> bool {
}
}
fn object<'a>(records: &[Record<'a>], issues: &mut Vec<String>) -> Result<Object<'a>, String> {
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();
@ -264,7 +290,8 @@ fn object<'a>(records: &[Record<'a>], issues: &mut Vec<String>) -> Result<Object
continue;
}
if !allowed_field(first.tag, record.tag) {
issues.push(error(
issues.push(Diagnostic::at(
"unsupported_record",
record.offset,
format!(
"unsupported record 0x{:04x} in {}",
@ -424,6 +451,7 @@ impl<'a> Document<'a> {
cells: BTreeMap::new(),
layer_names: BTreeMap::new(),
issues: Vec::new(),
diagnostics: Vec::new(),
header: Vec::new(),
global_issues: Vec::new(),
known_cells: BTreeSet::new(),
@ -461,7 +489,8 @@ impl<'a> Document<'a> {
| RTAG_SRFNAME
| RTAG_LIBSECUR
) {
doc.global_issues.push(error(
doc.global_issues.push(Diagnostic::at(
"unsupported_record",
record.offset,
format!("unsupported library record 0x{:04x}", record.tag),
));
@ -534,7 +563,8 @@ impl<'a> Document<'a> {
return Err(error(record.offset, "missing ENDSTR"));
}
if record.tag != RTAG_STRCLASS {
cell.issues.push(error(
cell.issues.push(Diagnostic::at(
"unsupported_record",
record.offset,
format!("unsupported cell record 0x{:04x}", record.tag),
));
@ -571,9 +601,10 @@ impl<'a> Document<'a> {
for object in cell.objects.iter_mut().filter(|o| o.kind == RTAG_TEXT) {
let text = object.field(RTAG_STRING).unwrap();
if text.starts_with(b"KLAMATH_LAYER_NAMES_") && text != LAYER_SENTINEL.as_bytes() {
object.issues.push(error(
object.issues.push(Diagnostic::at(
"unsupported_metadata_version",
object.offset,
"unsupported layer-name metadata version",
"unsupported layer-name metadata version".to_string(),
));
}
}
@ -613,13 +644,26 @@ impl<'a> Document<'a> {
}
fn check_graph(&mut self) {
let edges = self.edges();
for (parent, target) in edges.keys() {
if !self.known_cells.contains(target) {
self.issues
.push(format!("cell {parent:?}: unresolved reference {target:?}"));
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",
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)];
@ -631,8 +675,14 @@ impl<'a> Document<'a> {
match state.get(name) {
Some(2) => continue,
Some(1) => {
self.issues
.push(format!("cyclic hierarchy involving {name:?}"));
self.diagnostics.push(Diagnostic {
code: "hierarchy_cycle",
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;
}
_ => (),
@ -723,9 +773,28 @@ fn format_records(records: &[Record<'_>]) -> String {
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>,
@ -734,12 +803,15 @@ pub struct ObjectChange {
pub width: Option<i32>,
pub counts: Option<[u16; 2]>,
pub description: String,
pub fields: Vec<FieldValue>,
pub properties: Vec<(u16, Vec<u8>)>,
}
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,
@ -754,12 +826,27 @@ impl From<&Object<'_>> for ObjectChange {
.field(RTAG_WIDTH)
.map(|data| i32::from_be_bytes(data.try_into().unwrap())),
counts: object.target.as_ref().map(|_| {
object
.field(RTAG_COLROW)
.map(|data| [integer(&data[..2]), integer(&data[2..])])
.unwrap_or([1, 1])
if object.kind == RTAG_AREF {
let data = object.field(RTAG_COLROW).unwrap();
[integer(&data[..2]), integer(&data[2..])]
} else {
[1, 1]
}
}),
description: object.description(),
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(),
}
}
}
@ -770,6 +857,8 @@ pub struct CellChange {
pub old_offset: Option<usize>,
pub new_offset: Option<usize>,
pub attributes_changed: bool,
pub old_attributes: Vec<FieldValue>,
pub new_attributes: Vec<FieldValue>,
pub removed: Vec<ObjectChange>,
pub added: Vec<ObjectChange>,
pub replacements: Vec<Replacement>,
@ -785,6 +874,9 @@ pub struct LayerNameChange {
#[derive(Debug)]
pub struct LibraryFieldChange {
pub field: String,
pub tag: Option<u16>,
pub old_fields: Vec<FieldValue>,
pub new_fields: Vec<FieldValue>,
pub old: Vec<String>,
pub new: Vec<String>,
}
@ -821,6 +913,9 @@ impl Comparison {
if old.present != new.present {
result.library_fields.push(LibraryFieldChange {
field: "presence".to_string(),
tag: None,
old_fields: Vec::new(),
new_fields: Vec::new(),
old: vec![if old.present { "present" } else { "absent" }.to_string()],
new: vec![if new.present { "present" } else { "absent" }.to_string()],
});
@ -852,6 +947,9 @@ impl Comparison {
if a != b {
result.library_fields.push(LibraryFieldChange {
field: tag_name(tag),
tag: Some(tag),
old_fields: owned_fields(a.iter().map(|data| (tag, *data))),
new_fields: owned_fields(b.iter().map(|data| (tag, *data))),
old: a.iter().map(|data| format_data(tag, data)).collect(),
new: b.iter().map(|data| format_data(tag, data)).collect(),
});
@ -881,6 +979,12 @@ impl Comparison {
old_offset: a.map(|c| c.offset),
new_offset: b.map(|c| c.offset),
attributes_changed: a.map(|c| &c.attributes) != b.map(|c| &c.attributes),
old_attributes: owned_fields(
a.into_iter().flat_map(|c| c.attributes.iter().copied()),
),
new_attributes: owned_fields(
b.into_iter().flat_map(|c| c.attributes.iter().copied()),
),
removed: Vec::new(),
added: Vec::new(),
replacements: Vec::new(),

View file

@ -5,6 +5,8 @@ pub struct Replacement {
pub removed: usize,
pub added: usize,
pub explanation: String,
/// Explanation matching is never object identity or geometric equivalence.
pub match_rule: &'static str,
}
type Group = (u16, Option<Layer>, Option<String>, Option<Bounds>);
@ -54,6 +56,13 @@ pub(super) fn replacements(old: &[ObjectChange], new: &[ObjectChange]) -> Vec<Re
removed: i,
added: j,
explanation: explain(&old[i], &new[j]),
match_rule: if old[i].target.is_some() {
"unique_kind_target"
} else if bounds {
"unique_kind_layer_bounds"
} else {
"unique_kind_layer"
},
});
used_old.insert(i);
used_new.insert(j);

385
src/review/report.rs Normal file
View file

@ -0,0 +1,385 @@
//! Versioned machine-readable diff reports. No consumer needs to parse prose.
use super::*;
use serde_json::{Value, json};
use std::path::{Path, PathBuf};
pub const SCHEMA_VERSION: u32 = 1;
#[derive(Clone, Debug, Default)]
pub struct ReportInputs {
pub old: Option<PathBuf>,
pub new: Option<PathBuf>,
}
/// Limits affect evidence only. The default includes every changed object.
#[derive(Clone, Debug, Default)]
pub struct ReportOptions {
pub filter: DisplayFilter,
pub max_objects: Option<usize>,
pub hierarchy: bool,
}
fn layer(pair: Layer) -> Value {
json!({"number": pair.0, "purpose": pair.1})
}
fn scope(value: &Scope) -> Value {
json!({"top": value.top, "cell": value.cell, "layer": value.layer.map(layer)})
}
fn input(path: Option<&Path>, doc: Option<&Document<'_>>) -> Value {
let units = doc
.filter(|d| d.present)
.and_then(|d| d.header.iter().find(|(tag, _)| *tag == RTAG_UNITS))
.map(|(tag, data)| field(*tag, data));
json!({
"path": path.and_then(Path::to_str),
"path_encoded_hex": path.filter(|p| p.to_str().is_none())
.map(|p| hex(p.as_os_str().as_encoded_bytes())),
"present": doc.map(|d| d.present),
"units": units
})
}
fn envelope(inputs: &ReportInputs, selection: &Scope, options: &ReportOptions) -> Value {
json!({
"schema_version": SCHEMA_VERSION,
"kind": "diff",
"producer": {"name": "klamath", "version": env!("CARGO_PKG_VERSION")},
"comparison_profile": PROFILE,
"inputs": {"old": input(inputs.old.as_deref(), None), "new": input(inputs.new.as_deref(), None)},
"scope": scope(selection),
"coordinates": {"unit": "database_unit", "frame": "cell_local", "bounds": "coordinate_envelope"},
"status": "failed",
"result": "unknown",
"exit_code": 2,
"summary": null,
"report_selection": {
"cell": options.filter.cell,
"layer": options.filter.layer.map(layer),
"max_objects": options.max_objects.map(|n| n.to_string()),
"truncated": false,
"filtered_cells": "0", "filtered_objects": "0", "limited_objects": "0", "emitted_objects": "0"
},
"layer_legend": [],
"library_changes": [], "layer_name_changes": [], "cell_changes": [],
"hierarchy": null,
"diagnostics": []
})
}
/// Input/selection failures still produce a valid report. Unknown locations are
/// null rather than inferred by parsing an error's human-readable message.
pub fn failure_report(
inputs: &ReportInputs,
selection: &Scope,
options: &ReportOptions,
code: &str,
message: &str,
side: Option<&str>,
) -> Value {
let mut report = envelope(inputs, selection, options);
report["diagnostics"] = json!([{
"code": code, "severity": "error", "message": message,
"side": side, "byte_offset": null, "cell": null, "layer": null, "target": null
}]);
report
}
fn field(tag: u16, data: &[u8]) -> Value {
let (encoding, value) = if tag == RTAG_XY && data.len().is_multiple_of(8) {
("xy", json!(points(data)))
} else if matches!(
tag,
RTAG_LAYER | RTAG_DATATYPE | RTAG_TEXTTYPE | RTAG_NODETYPE | RTAG_BOXTYPE
) && data.len().is_multiple_of(2)
{
(
"uint16",
json!(data.chunks_exact(2).map(integer).collect::<Vec<_>>()),
)
} else {
match tag & 0xff {
0 if data.is_empty() => ("none", Value::Null),
1 if data.len().is_multiple_of(2) => (
"bits",
json!(data.chunks_exact(2).map(integer).collect::<Vec<_>>()),
),
2 if data.len().is_multiple_of(2) => (
"int16",
json!(
data.chunks_exact(2)
.map(|v| i16::from_be_bytes(v.try_into().unwrap()))
.collect::<Vec<_>>()
),
),
3 if data.len().is_multiple_of(4) => (
"int32",
json!(
data.chunks_exact(4)
.map(|v| i32::from_be_bytes(v.try_into().unwrap()))
.collect::<Vec<_>>()
),
),
5 if data.len().is_multiple_of(8) => (
"real8",
json!(
data.chunks_exact(8)
.map(|v| decode_real8(u64::from_be_bytes(v.try_into().unwrap())))
.collect::<Vec<_>>()
),
),
6 => ("ascii", json!(std::str::from_utf8(data).ok())),
_ => ("bytes", Value::Null),
}
};
json!({"tag": tag, "name": tag_name(tag), "encoding": encoding, "value": value, "payload_hex": hex(data)})
}
fn fields(values: &[FieldValue]) -> Vec<Value> {
values.iter().map(|f| field(f.tag, &f.data)).collect()
}
fn object(value: &ObjectChange, id: &str, side: &str) -> Value {
json!({
"id": id, "kind": kind_name(value.kind), "tag": value.kind,
"source": {"side": side, "byte_offset": value.offset.to_string(), "end_offset": value.end_offset.to_string()},
"layer": value.layer.map(layer), "bounds": value.bounds, "target": value.target,
"origin": value.origin.filter(|_| matches!(value.kind, RTAG_SREF | RTAG_AREF | RTAG_TEXT)), "width": value.width, "counts": value.counts,
"fields": fields(&value.fields),
"properties": value.properties.iter().map(|(attribute, bytes)| json!({
"attribute": attribute, "value": std::str::from_utf8(bytes).ok(), "payload_hex": hex(bytes)
})).collect::<Vec<_>>()
})
}
fn field_changes(old: &ObjectChange, new: &ObjectChange) -> Vec<Value> {
let a: BTreeMap<_, _> = old.fields.iter().map(|f| (f.tag, &f.data)).collect();
let b: BTreeMap<_, _> = new.fields.iter().map(|f| (f.tag, &f.data)).collect();
a.keys()
.chain(b.keys())
.copied()
.collect::<BTreeSet<_>>()
.into_iter()
.filter(|tag| a.get(tag) != b.get(tag))
.map(|tag| {
json!({
"tag": tag,
"before": a.get(&tag).map(|data| field(tag, data)),
"after": b.get(&tag).map(|data| field(tag, data))
})
})
.collect()
}
impl Comparison {
/// Render evidence from the same documents used to construct this comparison.
/// IDs are local to this report, not persistent object identities.
pub fn json_report(
&self,
old: &Document<'_>,
new: &Document<'_>,
inputs: &ReportInputs,
options: &ReportOptions,
) -> Value {
let mut report = envelope(inputs, &self.scope, options);
report["inputs"] = json!({"old": input(inputs.old.as_deref(), Some(old)), "new": input(inputs.new.as_deref(), Some(new))});
let different = !self.cells.is_empty()
|| !self.library_fields.is_empty()
|| !self.layer_names.is_empty();
report["status"] = json!(if self.issues.is_empty() {
"complete"
} else {
"incomplete"
});
report["result"] = json!(if different {
"different"
} else if self.is_equal() {
"equal"
} else {
"unknown"
});
report["exit_code"] = json!(self.exit_code());
report["summary"] = json!({
"counts": if self.issues.is_empty() { "exact" } else { "observed" },
"changed_cells": self.cells.len().to_string(),
"removed_objects": self.cells.iter().map(|c| c.removed.len()).sum::<usize>().to_string(),
"added_objects": self.cells.iter().map(|c| c.added.len()).sum::<usize>().to_string(),
"layer_name_changes": self.layer_names.len().to_string(),
"library_field_changes": self.library_fields.len().to_string()
});
report["layer_legend"] = json!(
self.layer_legend
.iter()
.map(|(pair, name)| json!({"layer": layer(*pair), "name": name}))
.collect::<Vec<_>>()
);
report["layer_name_changes"] = json!(
self.layer_names
.iter()
.map(|c| json!({
"layer": layer(c.layer), "before": c.old, "after": c.new
}))
.collect::<Vec<_>>()
);
report["library_changes"] = json!(self.library_fields.iter().map(|c| {
if c.tag.is_none() {
json!({"field": "presence", "tag": null, "before": old.present, "after": new.present})
} else {
json!({"field": c.field, "tag": c.tag, "before": fields(&c.old_fields), "after": fields(&c.new_fields)})
}
}).collect::<Vec<_>>());
let (mut emitted, mut filtered_objects, mut limited, mut filtered_cells) =
(0_usize, 0_usize, 0_usize, 0_usize);
let mut cells = Vec::new();
for (cell_index, cell) in self.cells.iter().enumerate() {
if options
.filter
.cell
.as_ref()
.is_some_and(|name| name != &cell.name)
{
filtered_cells += 1;
filtered_objects += cell.removed.len() + cell.added.len();
continue;
}
let (mut removed, mut added) = (Vec::new(), Vec::new());
let mut shown = BTreeSet::new();
for (side, objects, output) in [
("old", &cell.removed, &mut removed),
("new", &cell.added, &mut added),
] {
for (index, change) in objects.iter().enumerate() {
if options
.filter
.layer
.is_some_and(|l| change.layer != Some(l))
{
filtered_objects += 1;
} else if options.max_objects.is_some_and(|max| emitted >= max) {
limited += 1;
} else {
let id = format!("c{cell_index}:{side}:{index}");
output.push(object(change, &id, side));
shown.insert(id);
emitted += 1;
}
}
}
let replacements: Vec<_> = cell.replacements.iter().filter_map(|r| {
let a = format!("c{cell_index}:old:{}", r.removed);
let b = format!("c{cell_index}:new:{}", r.added);
(shown.contains(&a) && shown.contains(&b)).then(|| json!({
"removed": a, "added": b, "match_rule": r.match_rule,
"explanation": r.explanation,
"field_changes": field_changes(&cell.removed[r.removed], &cell.added[r.added]),
"properties_changed": cell.removed[r.removed].properties != cell.added[r.added].properties
}))
}).collect();
cells.push(json!({
"name": cell.name,
"before": cell.old_offset.map(|offset| json!({"byte_offset": offset.to_string(), "attributes": fields(&cell.old_attributes)})),
"after": cell.new_offset.map(|offset| json!({"byte_offset": offset.to_string(), "attributes": fields(&cell.new_attributes)})),
"attributes_changed": cell.attributes_changed,
"removed": removed, "added": added, "replacements": replacements
}));
}
report["cell_changes"] = json!(cells);
report["report_selection"]["truncated"] =
json!(filtered_cells > 0 || filtered_objects > 0 || limited > 0);
for (key, count) in [
("filtered_cells", filtered_cells),
("filtered_objects", filtered_objects),
("limited_objects", limited),
("emitted_objects", emitted),
] {
report["report_selection"][key] = json!(count.to_string());
}
let mut diagnostics: Vec<_> = [("old", old), ("new", new)]
.into_iter()
.flat_map(|(side, doc)| {
doc.diagnostics.iter().map(move |d| {
json!({
"code": d.code, "severity": "error", "message": d.message, "side": side,
"byte_offset": d.offset.map(|n| n.to_string()), "cell": d.cell,
"layer": d.layer.map(layer), "target": d.target
})
})
})
.collect();
if old.scope != new.scope {
diagnostics.push(json!({"code": "scope_mismatch", "severity": "error", "message": "comparison scopes differ", "side": null, "byte_offset": null, "cell": null, "layer": null, "target": null}));
}
report["diagnostics"] = json!(diagnostics);
if options.hierarchy {
report["hierarchy"] = graph(old, new, self);
}
report
}
}
fn graph(old: &Document<'_>, new: &Document<'_>, diff: &Comparison) -> Value {
let a = old.edges();
let b = new.edges();
let edges: BTreeSet<_> = a.keys().chain(b.keys()).cloned().collect();
let names: BTreeSet<_> = old
.cells
.keys()
.chain(new.cells.keys())
.cloned()
.chain(
edges
.iter()
.flat_map(|(parent, child)| [parent.clone(), child.clone()]),
)
.collect();
let direct: BTreeSet<_> = diff.cells.iter().map(|c| c.name.clone()).collect();
let mut affected = direct.clone();
let mut parents = BTreeMap::<&str, Vec<&str>>::new();
for (parent, child) in &edges {
parents.entry(child).or_default().push(parent);
}
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());
}
}
}
let changed_refs: BTreeSet<_> = diff
.cells
.iter()
.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 a_targets: BTreeSet<_> = a.keys().map(|(_, t)| t.as_str()).collect();
let b_targets: BTreeSet<_> = b.keys().map(|(_, t)| t.as_str()).collect();
let state = |doc: &Document<'_>, targets: &BTreeSet<&str>, name: &String| {
if doc.cells.contains_key(name) {
"included"
} else if doc.known_cells.contains(name) {
"outside_scope"
} else if targets.contains(name.as_str()) {
"unresolved"
} else {
"absent"
}
};
json!({
"nodes": names.iter().map(|name| json!({
"cell": name, "before": state(old, &a_targets, name), "after": state(new, &b_targets, name),
"change": if direct.contains(name) { "direct" } else if affected.contains(name) { "affected" } else { "unchanged" }
})).collect::<Vec<_>>(),
"edges": edges.iter().map(|edge| json!({
"parent": edge.0, "target": edge.1,
"before_count": a.get(edge).copied().unwrap_or(0).to_string(),
"after_count": b.get(edge).copied().unwrap_or(0).to_string(),
"reference_changed": changed_refs.contains(edge)
})).collect::<Vec<_>>()
})
}

View file

@ -63,6 +63,7 @@ impl<'a> Document<'a> {
cells: BTreeMap::new(),
layer_names: BTreeMap::new(),
issues: Vec::new(),
diagnostics: Vec::new(),
header: self.header.clone(),
global_issues: Vec::new(),
known_cells: BTreeSet::new(),
@ -84,17 +85,26 @@ impl<'a> Document<'a> {
}
pub(super) fn refresh_issues(&mut self) {
self.issues = self.global_issues.clone();
self.diagnostics = self.global_issues.clone();
for (name, cell) in &self.cells {
for issue in cell
.issues
.iter()
.chain(cell.objects.iter().flat_map(|o| &o.issues))
{
self.issues.push(format!("cell {name:?}: {issue}"));
for issue in &cell.issues {
let mut issue = issue.clone();
issue.cell = Some(name.clone());
issue.message = format!("cell {name:?}: {}", issue.message);
self.diagnostics.push(issue);
}
for object in &cell.objects {
for issue in &object.issues {
let mut issue = issue.clone();
issue.cell = Some(name.clone());
issue.layer = object.layer;
issue.message = format!("cell {name:?}: {}", issue.message);
self.diagnostics.push(issue);
}
}
}
self.check_graph();
self.issues = self.diagnostics.iter().map(|d| d.message.clone()).collect();
}
/// Project a parsed document. Missing selectors are allowed only for one