Make Pheon structural review results self-contained

Capture revision metadata, cell presence and attributes, and structured
diagnostics in owned comparison results. Derive outcomes and render text,
JSON, and hierarchy reports without retaining source documents. Keep derived
descriptions and graph analysis in their renderers.

Use pheon-structural-v1 and PHEON_LAYER_NAMES_V1 consistently, expose helpers
through their defining modules, and remove obsolete re-exports. Update user
guides and report fixtures without changing schema version 1.

Cover dropped inputs, diagnostic ordering, absent and empty cells, offset
independence, and CLI failures. All 92 Rust tests pass in debug and release;
report and hierarchy goldens retain their behavior.
This commit is contained in:
Jan Petykiewicz 2026-11-16 20:45:06 -08:00
commit df62677f5c

View file

@ -1,11 +1,12 @@
use pheon::review::report::{ReportInputs, ReportOptions, failure_report};
use pheon::review::{
Comparison, DisplayFilter, Document, Scope, dump_records, hierarchy, parse_layer,
parse_layer_name, write_layer_names,
Comparison, Diagnostic, Document, Outcome, Side, dump_records,
names::{parse_layer, parse_layer_name, write_layer_names},
selection::{DisplayFilter, Scope},
};
use std::{
collections::BTreeMap,
ffi::OsString,
ffi::{OsStr, OsString},
fs,
io::{self, Write},
path::PathBuf,
@ -18,7 +19,7 @@ const HELP: &str = "Usage:
pheon hierarchy FILE [--format ascii|mermaid] [--depth N] [--top NAME]\n pheon git-diff [OPTIONS] -- PATH OLD OLD_OID OLD_MODE NEW NEW_OID NEW_MODE
pheon name-layers INPUT OUTPUT --cell NAME --carrier L/T --name L:T:NAME ...
Object profile: ignore timestamps and element order, normalize polygon start/winding,
Structural comparison: ignore timestamps and element order, normalize polygon start/winding,
preserve duplicates, compare all retained fields exactly. No geometric XOR or tolerance.
Exit status: 0 equal/success, 1 different, 2 invalid/unsupported/incomplete.
";
@ -93,40 +94,68 @@ fn json_stdout(report: &serde_json::Value) -> Result<(), String> {
output.write_all(b"\n").map_err(|e| e.to_string())
}
fn prepare_comparison(
old_path: Option<&OsStr>,
new_path: Option<&OsStr>,
scope: &Scope,
) -> Result<Comparison, Diagnostic> {
let read = |path: Option<&OsStr>, side| {
path.map(|path| {
fs::read(path).map_err(|error| {
Diagnostic::new("io_error", format!("{path:?}: {error}"), Some(side))
})
})
.transpose()
};
let old_bytes = read(old_path, Side::Old)?;
let new_bytes = read(new_path, Side::New)?;
let old = old_bytes
.as_deref()
.map(Document::parse)
.transpose()
.map_err(|message| Diagnostic::new("invalid_input", message, Some(Side::Old)))?;
let new = new_bytes
.as_deref()
.map(Document::parse)
.transpose()
.map_err(|message| Diagnostic::new("invalid_input", message, Some(Side::New)))?;
let (old, new) = match (old, new) {
(Some(old), Some(new)) => (old, new),
(None, Some(new)) => (new.empty_like(), new),
(Some(old), None) => {
let new = old.empty_like();
(old, new)
}
(None, None) => {
return Err(Diagnostic::new(
"invalid_input",
"both Git revisions are absent",
None,
));
}
};
scope
.validate_pair(&old, &new)
.map_err(|message| Diagnostic::new("invalid_scope", message, None))?;
let old = old
.selected(scope, true)
.map_err(|message| Diagnostic::new("invalid_scope", message, Some(Side::Old)))?;
let new = new
.selected(scope, true)
.map_err(|message| Diagnostic::new("invalid_scope", message, Some(Side::New)))?;
Ok(Comparison::between(&old, &new))
}
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,
let (report, outcome) = match prepare_comparison(Some(&paths[0]), Some(&paths[1]), scope) {
Ok(diff) => (diff.json_report(&inputs, options), diff.outcome()),
Err(error) => (
failure_report(&inputs, scope, options, &error),
Outcome::Failed,
),
};
if let Err(error) = json_stdout(&report) {
@ -134,7 +163,7 @@ fn json_diff(paths: &[OsString], scope: &Scope, options: &ReportOptions) -> Resu
eprintln!("pheon: {error}");
return Ok(2);
}
Ok(status)
Ok(outcome.exit_code())
}
fn run(args: &[OsString]) -> Result<u8, String> {
@ -252,40 +281,25 @@ fn run(args: &[OsString]) -> Result<u8, String> {
let output = if command == "dump" {
doc.canonical_dump()
} else {
hierarchy(&doc, &doc, None, format == "mermaid", depth)
doc.hierarchy(format == "mermaid", depth)
};
stdout(&output)?;
if command == "hierarchy" {
for issue in &doc.issues {
eprintln!("INCOMPLETE: {issue}");
for diagnostic in &doc.diagnostics {
eprintln!("INCOMPLETE: {}", diagnostic.message);
}
}
return Ok(if doc.issues.is_empty() { 0 } else { 2 });
return Ok(if doc.diagnostics.is_empty() { 0 } else { 2 });
}
let git = command == "git-diff";
let old_missing = git && (paths[3] == "000000" || paths[3] == ".");
let new_missing = git && (paths[6] == "000000" || paths[6] == ".");
if old_missing && new_missing {
return Err("both Git revisions are absent".to_string());
}
let old_bytes = if old_missing {
None
} else {
Some(read(&paths[if git { 1 } else { 0 }])?)
};
let new_bytes = if new_missing {
None
} else {
Some(read(&paths[if git { 4 } else { 1 }])?)
};
let old = old_bytes.as_ref().map(|b| Document::parse(b)).transpose()?;
let new = new_bytes.as_ref().map(|b| Document::parse(b)).transpose()?;
let old = old.unwrap_or_else(|| new.as_ref().unwrap().empty_like());
let new = new.unwrap_or_else(|| old.empty_like());
scope.validate_pair(&old, &new)?;
let old = old.selected(&scope, true)?;
let new = new.selected(&scope, true)?;
let diff = Comparison::between(&old, &new);
let diff = prepare_comparison(
(!old_missing).then_some(paths[if git { 1 } else { 0 }].as_os_str()),
(!new_missing).then_some(paths[if git { 4 } else { 1 }].as_os_str()),
&scope,
)
.map_err(|error| error.message)?;
let mut output = String::new();
if git {
if paths.len() == 9 {
@ -307,13 +321,7 @@ fn run(args: &[OsString]) -> Result<u8, String> {
if format == "mermaid" {
output.push_str("```mermaid\n");
}
output.push_str(&hierarchy(
&old,
&new,
Some(&diff),
format == "mermaid",
depth,
));
output.push_str(&diff.hierarchy(format == "mermaid", depth));
if format == "mermaid" {
output.push_str("```\n");
}
@ -321,10 +329,10 @@ fn run(args: &[OsString]) -> Result<u8, String> {
stdout(&output)?;
// Git's external driver expects successful rendering for either equality
// or differences. Actual comparison/input failures remain nonzero.
Ok(if git && diff.exit_code() == 1 {
Ok(if git && diff.outcome().exit_code() == 1 {
0
} else {
diff.exit_code()
diff.outcome().exit_code()
})
}
@ -363,9 +371,7 @@ fn main() -> ExitCode {
&ReportInputs::default(),
&Scope::default(),
&ReportOptions::default(),
"command_error",
&message,
None,
&Diagnostic::new("command_error", message, None),
);
if let Err(error) = json_stdout(&report) {
eprintln!("pheon: {error}");