diff --git a/docs/cli.md b/docs/cli.md index fbaadba..bee1df3 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -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 diff --git a/docs/native-api.md b/docs/native-api.md index 14f3c6e..ee55e50 100644 --- a/docs/native-api.md +++ b/docs/native-api.md @@ -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 diff --git a/src/bin/pheon.rs b/src/bin/pheon.rs index 372a8fa..5b99354 100644 --- a/src/bin/pheon.rs +++ b/src/bin/pheon.rs @@ -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 { "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 { (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,20 +484,19 @@ fn run(args: &[OsString]) -> Result { } } let show_library_presence = !old_missing && !new_missing; - if format == "ascii" { - output.push_str(&diff.render_text_with_ascii_hierarchy( - max_changes, - &selectors.filter, - show_library_presence, - 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"); - } + output.push_str(&diff.render_text_with_options( + max_changes, + &selectors.filter, + show_library_presence, + TextReportOptions { + details, + ascii_depth: (format == "ascii").then_some(depth), + }, + )); + 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 diff --git a/src/review.rs b/src/review.rs index dcdb302..70b2b4b 100644 --- a/src/review.rs +++ b/src/review.rs @@ -1202,6 +1202,15 @@ pub struct Comparison { pub diagnostics: Vec, } +/// 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, +} + /// 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, + options: TextReportOptions, ) -> String { + let TextReportOptions { + details, + ascii_depth, + } = options; let outcome = self.outcome(); let mut out = match outcome { Outcome::Equal => "Equal", @@ -1594,27 +1632,36 @@ impl Comparison { } paired_old.insert(replacement.removed); paired_new.insert(replacement.added); - if max_objects - shown >= 2 { + 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 { - out.push_str(" ~ "); changes::write_layer_transition(&mut out, a, b, Some(&mut layers)); - out.push('\n'); - } else if is_polygon(a.kind) { - polygons.replacement(a, b); } else { - out.push_str(" ~ "); - let row_start = out.len(); layers.record(a.layer, row_start); - writeln!(out, "{}", changes::replacement_summary(a, b)).unwrap(); - if let Some(target) = &a.target { - shown_refs - .entry(target) - .or_default() - .replacement(a, b, row_start); + if details { + out.push_str(&changes::replacement_heading(a, b)); + } else { + out.push_str(&changes::replacement_summary(a, b)); } } - shown += 2; + out.push('\n'); + if details { + changes::write_replacement_objects(&mut out, a, b); + } + if let Some(target) = &a.target { + shown_refs + .entry(target) + .or_default() + .replacement(a, b, row_start); + } } + shown += 2; } let mut removed_refs = BTreeMap::new(); let mut added_refs = BTreeMap::new(); @@ -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,8 +1702,19 @@ impl Comparison { if count > 1 { write!(out, "{count}× ").unwrap(); } - layers.record(object.layer, out.len()); - changes::write_unmatched(&mut out, object); + 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(); diff --git a/src/review/changes.rs b/src/review/changes.rs index 9b4e88b..824b00d 100644 --- a/src/review/changes.rs +++ b/src/review/changes.rs @@ -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 { " " }; diff --git a/tests/review.rs b/tests/review.rs index 72b8a05..ad625bb 100644 --- a/tests/review.rs +++ b/tests/review.rs @@ -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:"));