Add an opt-in detailed text diff

This commit is contained in:
Jan Petykiewicz 2026-11-18 23:20:00 -08:00
commit f3275fc161
6 changed files with 266 additions and 45 deletions

View file

@ -122,6 +122,7 @@ Pheon lists the choices. A valid numeric pair always selects that pair directly.
```sh
pheon diff before.gds after.gds --show-cell RESONATOR --show-layer WG
pheon diff before.gds after.gds --show-cell RESONATOR --details --max-changes 20
pheon diff before.gds after.gds --hierarchy mermaid --depth 4
```
@ -136,6 +137,12 @@ changes hidden by filters or the limit. JSON has no default object limit and rep
omissions from both display filters and any explicit limit in `report_selection`.
See the [JSON reference](diff-reports.md) for the selection counters.
`--details` shows individual object evidence inside modified cells in text
reports. Replacement rows include a nested `-` row for the old object and a
`+` row for the new object, with cell-local coordinates in database units,
retained fields, and properties. Both sides count toward `--max-changes`.
For added and removed cells, the report lists the cell name.
The diff hierarchy shows directly changed cells, affected ancestors, and targets
of modified references. It includes references from both revisions so removed
branches remain visible. Counts represent direct placements, with symbolic

View file

@ -34,7 +34,9 @@ graph and ancestors when a hierarchy is requested.
`TextComparison::between` captures the data needed for text and hierarchy
reports. Both comparison types provide `render_text_with_ascii_hierarchy`
to render a combined report with redundant terminal edges omitted.
to render a combined report with redundant terminal edges omitted. Pass
`TextReportOptions { details: true, ..Default::default() }` to
`render_text_with_options` to show individual object evidence.
Use `RevisionPair::parse(&old_bytes, &new_bytes)` for an unscoped comparison
that can reuse matching cells. Its `compare` and `compare_text` methods return

View file

@ -5,7 +5,7 @@ use flate2::read::MultiGzDecoder;
use pheon::review::report::{ReportInputs, ReportOptions, failure_report};
use pheon::review::{
Comparison, Diagnostic, Document, Layer, Outcome, RevisionPair, Side, TextComparison,
dump_records,
TextReportOptions, dump_records,
names::{parse_layer, parse_layer_name, resolve_layer_name, write_layer_names},
selection::{DisplayFilter, Scope},
};
@ -22,7 +22,7 @@ use termcolor::ColorChoice;
const HELP: &str = "Usage:
pheon dump FILE [--records] [--color auto|always|never]
pheon diff OLD NEW [--top NAME] [--cell NAME] [--layer L/T|NAME]\n [--show-cell NAME] [--show-layer L/T|NAME] [--hierarchy ascii|mermaid|none|graph]\n [--max-changes N] [--depth N] [--format text|json]
pheon diff OLD NEW [--top NAME] [--cell NAME] [--layer L/T|NAME]\n [--show-cell NAME] [--show-layer L/T|NAME] [--hierarchy ascii|mermaid|none|graph]\n [--details] [--max-changes N] [--depth N] [--format text|json]
[--color auto|always|never]
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 ...
@ -346,6 +346,7 @@ fn run(args: &[OsString]) -> Result<u8, String> {
"ascii".to_string()
};
let mut max_changes = 100;
let mut details = false;
let mut explicit_max = None;
let mut output_format = "text".to_string();
let mut depth = 8;
@ -383,6 +384,7 @@ fn run(args: &[OsString]) -> Result<u8, String> {
(selectors.filter.layer, selectors.show_layer_name) =
layer_argument(value(args, &mut i)?);
}
Some("--details") if compare => details = true,
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)?,
@ -482,21 +484,20 @@ fn run(args: &[OsString]) -> Result<u8, String> {
}
}
let show_library_presence = !old_missing && !new_missing;
if format == "ascii" {
output.push_str(&diff.render_text_with_ascii_hierarchy(
output.push_str(&diff.render_text_with_options(
max_changes,
&selectors.filter,
show_library_presence,
depth,
TextReportOptions {
details,
ascii_depth: (format == "ascii").then_some(depth),
},
));
} else {
output.push_str(&diff.render_text(max_changes, &selectors.filter, show_library_presence));
if format == "mermaid" {
output.push_str("Hierarchy\n```mermaid\n");
output.push_str(&diff.hierarchy(true, depth));
output.push_str("```\n");
}
}
color::print(&output, color::Report::Diff, color_choice).map_err(|error| error.to_string())?;
// Git's external driver expects successful rendering for either equality
// or differences. Actual comparison/input failures remain nonzero.

View file

@ -1202,6 +1202,15 @@ pub struct Comparison {
pub diagnostics: Vec<Diagnostic>,
}
/// Additional presentation options for a text comparison.
#[derive(Clone, Copy, Debug, Default)]
pub struct TextReportOptions {
/// Print individual object evidence, including both sides of replacements.
pub details: bool,
/// Append the ASCII hierarchy at this depth when provided.
pub ascii_depth: Option<usize>,
}
/// A comparison for text and hierarchy reports.
#[derive(Debug)]
pub struct TextComparison {
@ -1229,6 +1238,17 @@ impl TextComparison {
.render_text(max_objects, show, show_library_presence)
}
pub fn render_text_with_options(
&self,
max_objects: usize,
show: &DisplayFilter,
show_library_presence: bool,
options: TextReportOptions,
) -> String {
self.comparison
.render_text_with_options(max_objects, show, show_library_presence, options)
}
/// Render the cell changes and their ASCII hierarchy together.
pub fn render_text_with_ascii_hierarchy(
&self,
@ -1457,7 +1477,12 @@ impl Comparison {
show: &DisplayFilter,
show_library_presence: bool,
) -> String {
self.render_text_report(max_objects, show, show_library_presence, None)
self.render_text_with_options(
max_objects,
show,
show_library_presence,
TextReportOptions::default(),
)
}
/// Render the cell changes and omit simple hierarchy edges already shown there.
@ -1468,16 +1493,29 @@ impl Comparison {
show_library_presence: bool,
max_depth: usize,
) -> String {
self.render_text_report(max_objects, show, show_library_presence, Some(max_depth))
self.render_text_with_options(
max_objects,
show,
show_library_presence,
TextReportOptions {
ascii_depth: Some(max_depth),
..TextReportOptions::default()
},
)
}
fn render_text_report(
/// Render the selected changes with optional object details and ASCII hierarchy.
pub fn render_text_with_options(
&self,
max_objects: usize,
show: &DisplayFilter,
show_library_presence: bool,
ascii_depth: Option<usize>,
options: TextReportOptions,
) -> String {
let TextReportOptions {
details,
ascii_depth,
} = options;
let outcome = self.outcome();
let mut out = match outcome {
Outcome::Equal => "Equal",
@ -1594,18 +1632,28 @@ impl Comparison {
}
paired_old.insert(replacement.removed);
paired_new.insert(replacement.added);
if max_objects - shown >= 2 {
if a.layer != b.layer {
out.push_str(" ~ ");
changes::write_layer_transition(&mut out, a, b, Some(&mut layers));
out.push('\n');
} else if is_polygon(a.kind) {
if max_objects - shown < 2 {
continue;
}
if !details && a.layer == b.layer && is_polygon(a.kind) {
polygons.replacement(a, b);
} else {
out.push_str(" ~ ");
let row_start = out.len();
if a.layer != b.layer {
changes::write_layer_transition(&mut out, a, b, Some(&mut layers));
} else {
layers.record(a.layer, row_start);
writeln!(out, "{}", changes::replacement_summary(a, b)).unwrap();
if details {
out.push_str(&changes::replacement_heading(a, b));
} else {
out.push_str(&changes::replacement_summary(a, b));
}
}
out.push('\n');
if details {
changes::write_replacement_objects(&mut out, a, b);
}
if let Some(target) = &a.target {
shown_refs
.entry(target)
@ -1615,7 +1663,6 @@ impl Comparison {
}
shown += 2;
}
}
let mut removed_refs = BTreeMap::new();
let mut added_refs = BTreeMap::new();
for (removed, objects, paired, references) in [
@ -1630,9 +1677,9 @@ impl Comparison {
}
selected += 1;
if !paired.contains(&index) && shown < max_objects {
if is_polygon(object.kind) {
if !details && is_polygon(object.kind) {
polygons.unmatched(object, removed);
} else if let Some(target) = object.target.as_deref() {
} else if !details && let Some(target) = object.target.as_deref() {
let (_, counts) = references
.entry(target)
.or_insert_with(|| (object, changes::ReferenceCounts::default()));
@ -1655,10 +1702,21 @@ impl Comparison {
if count > 1 {
write!(out, "{count}× ").unwrap();
}
layers.record(object.layer, out.len());
let row_start = out.len();
layers.record(object.layer, row_start);
if details {
writeln!(out, "{object}").unwrap();
if let Some(target) = object.target.as_deref() {
shown_refs
.entry(target)
.or_default()
.individual(object, removed, count, row_start);
}
} else {
changes::write_unmatched(&mut out, object);
}
}
}
let no_refs = changes::ReferenceCounts::default();
for (target, (first, counts)) in removed_refs {
let row_start = out.len();

View file

@ -426,6 +426,23 @@ impl ShownReferences {
self.row_start = row_start;
}
pub fn individual(
&mut self,
object: &ObjectChange,
removed: bool,
count: usize,
row_start: usize,
) {
let placements = if removed {
&mut self.removed
} else {
&mut self.added
};
*placements += reference_placements(object) * count as u128;
self.shown += count;
self.row_start = row_start;
}
pub fn count_change(&mut self) {
self.total += 1;
}
@ -555,6 +572,28 @@ fn polygon_replacement(old: &ObjectChange, new: &ObjectChange) -> String {
out
}
pub(super) fn replacement_heading(old: &ObjectChange, new: &ObjectChange) -> String {
let rectangular = is_polygon(old.kind)
&& rectangle_size(object_xy(old)).is_some()
&& rectangle_size(object_xy(new)).is_some();
let mut heading = object_heading(old, object_name(old.kind, rectangular));
if let Some(target) = &old.target {
write!(heading, " {target:?}").unwrap();
}
heading
}
pub(super) fn write_replacement_objects(out: &mut String, old: &ObjectChange, new: &ObjectChange) {
for (sign, object) in [('-', old), ('+', new)] {
let description = object.to_string();
let mut lines = description.split('\n');
writeln!(out, " {sign} {}", lines.next().unwrap()).unwrap();
for line in lines {
writeln!(out, " {line}").unwrap();
}
}
}
pub(super) fn replacement_summary(old: &ObjectChange, new: &ObjectChange) -> String {
if old.layer != new.layer && old.layer.is_some() && new.layer.is_some() {
let mut out = String::new();
@ -565,11 +604,7 @@ pub(super) fn replacement_summary(old: &ObjectChange, new: &ObjectChange) -> Str
let mut out = if polygon {
polygon_replacement(old, new)
} else {
let mut heading = object_heading(old, object_name(old.kind, false));
if let Some(target) = &old.target {
write!(heading, " {target:?}").unwrap();
}
heading
replacement_heading(old, new)
};
let mut separator = if polygon { "\n " } else { " " };

View file

@ -6,7 +6,8 @@ use common::{library_header, record};
use pheon::{
records::*,
review::{
Comparison, Document, TextComparison, names::LAYER_SENTINEL, selection::DisplayFilter,
Comparison, Document, TextComparison, TextReportOptions, names::LAYER_SENTINEL,
selection::DisplayFilter,
},
};
use std::{fs, path::PathBuf, process::Command};
@ -1006,6 +1007,107 @@ fn cli_color_preserves_plain_output_and_machine_formats() {
}
}
#[test]
fn cli_details_show_coordinates_and_properties_within_filters_and_limits() {
let directory = std::env::temp_dir().join(format!("pheon-details-{}", 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 old = directory.join("old.gds");
let new = directory.join("new.gds");
let common_ref = reference("leaf", 0, 1);
let additional_ref = reference("leaf", 5, 1);
let points = [[0, 0], [4, 0], [4, -5], [13, -5], [13, 9]];
let shifted = polygon(&[[2, -1], [12, -1], [12, 9], [2, 9], [2, -1]]);
fs::write(
&old,
layout(&[
(
"CHIP",
vec![with_property(square(), "old"), common_ref.clone()],
),
("leaf", vec![]),
("other", vec![label((2, 0), "before other")]),
("removed", vec![label((2, 0), "payload in removed cell")]),
]),
)
.unwrap();
fs::write(
&new,
layout(&[
(
"CHIP",
vec![
with_property(shifted, "new"),
with_property(path(Some(8), &points), "path property"),
common_ref,
additional_ref.clone(),
additional_ref,
],
),
("leaf", vec![]),
("other", vec![label((2, 0), "after other")]),
("added", vec![label((2, 0), "payload in added cell")]),
]),
)
.unwrap();
let diff = |options: &[&str]| {
let output = Command::new(env!("CARGO_BIN_EXE_pheon"))
.arg("diff")
.arg(&old)
.arg(&new)
.args(options)
.output()
.unwrap();
assert_eq!(
output.status.code(),
Some(1),
"{}",
String::from_utf8_lossy(&output.stderr)
);
String::from_utf8(output.stdout).unwrap()
};
let detailed = diff(&["--show-cell", "CHIP", "--details", "--hierarchy", "ascii"]);
assert!(detailed.contains(concat!(
" ~ 1/0: rectangle\n",
" - 1/0: rectangle (0, 0) to (10, 10) property[17]=\"old\"\n",
" + 1/0: rectangle (2, -1) to (12, 9) property[17]=\"new\"\n",
)));
assert!(detailed.contains(concat!(
" + 1/0: path width=[8] xy=[(0, 0), (4, 0), (4, -5), (13, -5),\n",
" (13, 9)] property[17]=\"path property\"\n",
)));
assert!(detailed.contains(" + 2× reference \"leaf\" xy=(5, 0) · placements 1 -> 3\n"));
assert!(!detailed.contains("Hierarchy\n"));
assert!(!detailed.contains("after other"));
let limited = diff(&[
"--show-cell",
"CHIP",
"--details",
"--max-changes",
"1",
"--hierarchy",
"ascii",
]);
assert!(limited.contains("4 object changes over the limit"));
assert!(!limited.contains("~ 1/0: rectangle"));
assert!(!limited.contains("property[17]=\"old\""));
assert!(limited.ends_with("Hierarchy\n* CHIP\n leaf x1 -> x3\n"));
let all = diff(&["--details"]);
assert!(all.contains("Cells:\n- removed\n+ added\n* CHIP\n"));
assert!(!all.contains("payload in"));
assert_eq!(
diff(&["--details", "--format", "json"]),
diff(&["--format", "json"])
);
}
#[test]
fn cli_decodes_gzip_by_header_and_checks_the_trailer() {
let directory = std::env::temp_dir().join(format!("pheon gzip {}", std::process::id()));
@ -1830,6 +1932,22 @@ fn layer_only_shape_replacements_keep_evidence_and_respect_selection() {
diff.text(2),
"Different\nCells:\n* CHIP\n ~ 1/0 (WG) → 2/0 (CORE) · rectangle\n"
);
assert!(
diff.render_text_with_options(
2,
&Default::default(),
true,
TextReportOptions {
details: true,
..Default::default()
},
)
.ends_with(concat!(
" ~ 1/0 (WG) → 2/0 (CORE) · rectangle\n",
" - 1/0: rectangle (0, 0) to (10, 10)\n",
" + 2/0: rectangle (0, 0) to (10, 10)\n",
))
);
let limited = diff.text(1);
assert!(limited.contains("2 object changes over the limit"));
assert!(!limited.contains("Cells:"));