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:
parent
a723ba2265
commit
df62677f5c
4 changed files with 870 additions and 504 deletions
|
|
@ -1,10 +1,11 @@
|
|||
//! Unique replacement matches that explain removed and added objects.
|
||||
|
||||
use super::*;
|
||||
|
||||
#[derive(Debug)]
|
||||
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,
|
||||
}
|
||||
|
|
@ -56,7 +57,6 @@ pub(super) fn replacements(old: &[ObjectChange], new: &[ObjectChange]) -> Vec<Re
|
|||
result.push(Replacement {
|
||||
removed: i,
|
||||
added: j,
|
||||
explanation: explain(&old[i], &new[j]),
|
||||
match_rule: if old[i].target.is_some() {
|
||||
"unique_kind_target"
|
||||
} else if bounds {
|
||||
|
|
@ -74,7 +74,7 @@ pub(super) fn replacements(old: &[ObjectChange], new: &[ObjectChange]) -> Vec<Re
|
|||
result
|
||||
}
|
||||
|
||||
fn explain(old: &ObjectChange, new: &ObjectChange) -> String {
|
||||
pub(super) fn explain(old: &ObjectChange, new: &ObjectChange) -> String {
|
||||
let mut parts = vec![format!(
|
||||
"{} modified{}",
|
||||
kind_name(old.kind),
|
||||
|
|
|
|||
|
|
@ -1,5 +1,66 @@
|
|||
//! Embedded layer names: parsing, recognition, and record-preserving updates.
|
||||
|
||||
use super::*;
|
||||
|
||||
const LAYER_PREFIX: &[u8] = b"PHEON_LAYER_NAMES_";
|
||||
pub const LAYER_SENTINEL: &str = "PHEON_LAYER_NAMES_V1";
|
||||
|
||||
impl Document<'_> {
|
||||
pub(super) fn read_metadata(&mut self) -> Result<(), String> {
|
||||
for (cell_name, cell) in &mut self.cells {
|
||||
for object in cell.objects.iter().filter(|o| o.kind == RTAG_TEXT) {
|
||||
let text = object.field(RTAG_STRING).unwrap();
|
||||
if text.starts_with(LAYER_PREFIX) && text != LAYER_SENTINEL.as_bytes() {
|
||||
// Layer names apply across the library. An unknown version
|
||||
// may describe layers used outside this carrier or cell, so
|
||||
// geometry scope selection cannot establish its relevance.
|
||||
let mut diagnostic = Diagnostic::at(
|
||||
"unsupported_metadata_version",
|
||||
object.offset,
|
||||
"unsupported layer-name metadata version".to_string(),
|
||||
);
|
||||
diagnostic.cell = Some(cell_name.clone());
|
||||
diagnostic.layer = object.layer;
|
||||
diagnostic.message = format!("cell {cell_name:?}: {}", diagnostic.message);
|
||||
self.global_issues.push(diagnostic);
|
||||
}
|
||||
}
|
||||
let carriers: BTreeSet<_> = cell
|
||||
.objects
|
||||
.iter()
|
||||
.filter(|o| {
|
||||
o.kind == RTAG_TEXT && o.field(RTAG_STRING) == Some(LAYER_SENTINEL.as_bytes())
|
||||
})
|
||||
.filter_map(|o| o.layer)
|
||||
.collect();
|
||||
for object in &mut cell.objects {
|
||||
if object.kind != RTAG_TEXT || !object.layer.is_some_and(|l| carriers.contains(&l))
|
||||
{
|
||||
continue;
|
||||
}
|
||||
let text = decoded_string(object.field(RTAG_STRING).unwrap(), object.offset)?;
|
||||
if text != LAYER_SENTINEL {
|
||||
let ((layer, dtype), name) =
|
||||
parse_layer_name(&text).map_err(|message| error(object.offset, message))?;
|
||||
if self
|
||||
.layer_names
|
||||
.get(&(layer, dtype))
|
||||
.is_some_and(|old| old != &name)
|
||||
{
|
||||
return Err(error(
|
||||
object.offset,
|
||||
format!("conflicting names for {layer}/{dtype}"),
|
||||
));
|
||||
}
|
||||
self.layer_names.insert((layer, dtype), name.to_string());
|
||||
}
|
||||
object.metadata = true;
|
||||
}
|
||||
}
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
|
||||
pub fn parse_layer(value: &str) -> Result<Layer, String> {
|
||||
let (a, b) = value
|
||||
.split_once('/')
|
||||
|
|
|
|||
|
|
@ -27,32 +27,37 @@ 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));
|
||||
fn input(path: Option<&Path>, revision: Option<&Revision>) -> Value {
|
||||
let units = revision
|
||||
.and_then(|r| r.units.as_deref())
|
||||
.map(|data| field(RTAG_UNITS, 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),
|
||||
"present": revision.map(|r| r.present),
|
||||
"units": units
|
||||
})
|
||||
}
|
||||
|
||||
fn envelope(inputs: &ReportInputs, selection: &Scope, options: &ReportOptions) -> Value {
|
||||
fn envelope(
|
||||
inputs: &ReportInputs,
|
||||
selection: &Scope,
|
||||
options: &ReportOptions,
|
||||
outcome: Outcome,
|
||||
revisions: Option<(&Revision, &Revision)>,
|
||||
) -> Value {
|
||||
json!({
|
||||
"schema_version": SCHEMA_VERSION,
|
||||
"kind": "diff",
|
||||
"producer": {"name": "pheon", "version": env!("CARGO_PKG_VERSION")},
|
||||
"comparison_profile": PROFILE,
|
||||
"inputs": {"old": input(inputs.old.as_deref(), None), "new": input(inputs.new.as_deref(), None)},
|
||||
"inputs": {"old": input(inputs.old.as_deref(), revisions.map(|r| r.0)), "new": input(inputs.new.as_deref(), revisions.map(|r| r.1))},
|
||||
"scope": scope(selection),
|
||||
"coordinates": {"unit": "database_unit", "frame": "cell_local", "bounds": "coordinate_envelope"},
|
||||
"status": "failed",
|
||||
"result": "unknown",
|
||||
"exit_code": 2,
|
||||
"status": outcome.status(),
|
||||
"result": outcome.result(),
|
||||
"exit_code": outcome.exit_code(),
|
||||
"summary": null,
|
||||
"report_selection": {
|
||||
"cell": options.filter.cell,
|
||||
|
|
@ -74,18 +79,22 @@ pub fn failure_report(
|
|||
inputs: &ReportInputs,
|
||||
selection: &Scope,
|
||||
options: &ReportOptions,
|
||||
code: &str,
|
||||
message: &str,
|
||||
side: Option<&str>,
|
||||
error: &Diagnostic,
|
||||
) -> 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
|
||||
}]);
|
||||
let mut report = envelope(inputs, selection, options, Outcome::Failed, None);
|
||||
report["diagnostics"] = json!([diagnostic(error)]);
|
||||
report
|
||||
}
|
||||
|
||||
fn diagnostic(value: &Diagnostic) -> Value {
|
||||
json!({
|
||||
"code": value.code, "severity": "error", "message": value.message,
|
||||
"side": value.side.map(|side| side.to_string()),
|
||||
"byte_offset": value.offset.map(|offset| offset.to_string()),
|
||||
"cell": value.cell, "layer": value.layer.map(layer), "target": value.target
|
||||
})
|
||||
}
|
||||
|
||||
fn field(tag: u16, data: &[u8]) -> Value {
|
||||
let (encoding, value) = if tag == RTAG_XY && data.len().is_multiple_of(8) {
|
||||
("xy", json!(points(data)))
|
||||
|
|
@ -195,40 +204,24 @@ fn field_changes(old: &ObjectChange, new: &ObjectChange) -> Vec<Value> {
|
|||
}
|
||||
|
||||
impl Comparison {
|
||||
/// Render evidence from the same documents used to construct this comparison.
|
||||
/// Render the captured comparison evidence without retaining its source documents.
|
||||
/// 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());
|
||||
pub fn json_report(&self, inputs: &ReportInputs, options: &ReportOptions) -> Value {
|
||||
let outcome = self.outcome();
|
||||
let mut report = envelope(
|
||||
inputs,
|
||||
&self.old.scope,
|
||||
options,
|
||||
outcome,
|
||||
Some((&self.old, &self.new)),
|
||||
);
|
||||
report["summary"] = json!({
|
||||
"counts": if self.issues.is_empty() { "exact" } else { "observed" },
|
||||
"counts": if outcome.is_complete() { "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()
|
||||
"library_field_changes": self.library_changes.len().to_string()
|
||||
});
|
||||
report["layer_legend"] = json!(
|
||||
self.layer_legend
|
||||
|
|
@ -244,11 +237,17 @@ impl Comparison {
|
|||
}))
|
||||
.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)})
|
||||
report["library_changes"] = json!(self.library_changes.iter().map(|change| {
|
||||
match change {
|
||||
LibraryChange::Presence { old, new } => {
|
||||
json!({"field": "presence", "tag": null, "before": old, "after": new})
|
||||
}
|
||||
LibraryChange::Record { tag, old, new } => {
|
||||
let values = |data: &[Vec<u8>]| {
|
||||
data.iter().map(|bytes| field(*tag, bytes)).collect::<Vec<_>>()
|
||||
};
|
||||
json!({"field": tag_name(*tag), "tag": tag, "before": values(old), "after": values(new)})
|
||||
}
|
||||
}
|
||||
}).collect::<Vec<_>>());
|
||||
let (mut emitted, mut filtered_objects, mut limited, mut filtered_cells) =
|
||||
|
|
@ -293,16 +292,16 @@ impl Comparison {
|
|||
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,
|
||||
"explanation": changes::explain(&cell.removed[r.removed], &cell.added[r.added]),
|
||||
"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,
|
||||
"before": cell.old.as_ref().map(|revision| json!({"byte_offset": revision.offset.to_string(), "attributes": fields(&revision.attributes)})),
|
||||
"after": cell.new.as_ref().map(|revision| json!({"byte_offset": revision.offset.to_string(), "attributes": fields(&revision.attributes)})),
|
||||
"attributes_changed": cell.attributes_changed(),
|
||||
"removed": removed, "added": added, "replacements": replacements
|
||||
}));
|
||||
}
|
||||
|
|
@ -317,37 +316,29 @@ impl Comparison {
|
|||
] {
|
||||
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);
|
||||
report["diagnostics"] = json!(self.diagnostics.iter().map(diagnostic).collect::<Vec<_>>());
|
||||
if options.hierarchy {
|
||||
report["hierarchy"] = graph(old, new, self);
|
||||
report["hierarchy"] = graph(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();
|
||||
fn graph(diff: &Comparison) -> Value {
|
||||
let old = &diff.old;
|
||||
let new = &diff.new;
|
||||
let HierarchyAnalysis {
|
||||
old_edges,
|
||||
new_edges,
|
||||
edges,
|
||||
direct,
|
||||
affected,
|
||||
changed_refs,
|
||||
} = HierarchyAnalysis::between(old, new, Some(&diff.cells));
|
||||
let names: BTreeSet<_> = old
|
||||
.cells
|
||||
.keys()
|
||||
.chain(new.cells.keys())
|
||||
.iter()
|
||||
.chain(new.cells.iter())
|
||||
.cloned()
|
||||
.chain(
|
||||
edges
|
||||
|
|
@ -355,34 +346,10 @@ fn graph(old: &Document<'_>, new: &Document<'_>, diff: &Comparison) -> Value {
|
|||
.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) {
|
||||
let old_targets: BTreeSet<_> = old_edges.keys().map(|(_, t)| t.as_str()).collect();
|
||||
let new_targets: BTreeSet<_> = new_edges.keys().map(|(_, t)| t.as_str()).collect();
|
||||
let state = |doc: &Revision, targets: &BTreeSet<&str>, name: &String| {
|
||||
if doc.cells.contains(name) {
|
||||
"included"
|
||||
} else if doc.known_cells.contains(name) {
|
||||
"outside_scope"
|
||||
|
|
@ -394,13 +361,13 @@ fn graph(old: &Document<'_>, new: &Document<'_>, diff: &Comparison) -> Value {
|
|||
};
|
||||
json!({
|
||||
"nodes": names.iter().map(|name| json!({
|
||||
"cell": name, "before": state(old, &a_targets, name), "after": state(new, &b_targets, name),
|
||||
"cell": name, "before": state(old, &old_targets, name), "after": state(new, &new_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(),
|
||||
"before_count": old_edges.get(edge).copied().unwrap_or(0).to_string(),
|
||||
"after_count": new_edges.get(edge).copied().unwrap_or(0).to_string(),
|
||||
"reference_changed": changed_refs.contains(edge)
|
||||
})).collect::<Vec<_>>()
|
||||
})
|
||||
|
|
|
|||
|
|
@ -1,3 +1,5 @@
|
|||
//! Comparison scope and display-only filters.
|
||||
|
||||
use super::*;
|
||||
|
||||
#[derive(Clone, Debug, Default, Eq, PartialEq)]
|
||||
|
|
@ -64,7 +66,6 @@ impl<'a> Document<'a> {
|
|||
records: Vec::new(),
|
||||
cells: BTreeMap::new(),
|
||||
layer_names: BTreeMap::new(),
|
||||
issues: Vec::new(),
|
||||
diagnostics: Vec::new(),
|
||||
header: self.header.clone(),
|
||||
global_issues: Vec::new(),
|
||||
|
|
@ -86,7 +87,7 @@ impl<'a> Document<'a> {
|
|||
found
|
||||
}
|
||||
|
||||
pub(super) fn refresh_issues(&mut self) {
|
||||
pub(super) fn refresh_diagnostics(&mut self) {
|
||||
self.diagnostics = self.global_issues.clone();
|
||||
for (name, cell) in &self.cells {
|
||||
for issue in &cell.issues {
|
||||
|
|
@ -106,7 +107,6 @@ impl<'a> Document<'a> {
|
|||
}
|
||||
}
|
||||
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
|
||||
|
|
@ -227,7 +227,7 @@ impl<'a> Document<'a> {
|
|||
self.layer_names.retain(|pair, _| layers.contains(pair));
|
||||
}
|
||||
self.scope = scope.clone();
|
||||
self.refresh_issues();
|
||||
self.refresh_diagnostics();
|
||||
Ok(self)
|
||||
}
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in a new issue