feat(check): surface specific violations with unified diff output (#278)

* feat(check): surface specific violations with unified diff output

Replace the opaque 'does not match' error with a unified diff showing
exactly which lines differ between the on-disk pipeline and the freshly
compiled output. This makes it immediately clear what changed and why
recompilation is needed.

Changes:
- Add the 'similar' crate for line-level diffing
- Replace normalize_whitespace comparison with clean_generated_yaml
  canonicalization on both sides (preserves indentation and internal
  spaces, unlike the old approach which stripped all whitespace)
- Show a unified diff with 3 lines of context on check failure
- Truncate diff output after 80 changed lines for large pipelines
- Warn when the pipeline was compiled by a different compiler version
- Add tests for format_diff and clean_generated_yaml

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix(check): correct truncation counter and total change count in diff output

- Move changed_lines_shown increment after the truncation check so the
  count matches what is actually printed (was off-by-one: 81 vs 80).
- Compute total_added/total_removed in a first pass over all changes so
  the truncation message reports the real total, not just lines seen
  before the break.
- Use total counts in the Summary line so it stays accurate even when
  the diff is truncated.
- Add test_format_diff_truncates_at_limit covering the truncation path.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

* fix(check): buffer hunk lines to prevent orphaned headers on truncation

- Buffer each hunk's rendered lines before emitting the @@ header,
  so mid-hunk truncation doesn't leave a malformed hunk with
  mismatched line counts
- Consolidate two iter_all_changes() passes into a single fold for
  total_added/total_removed counting

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

---------

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: jamesadevine

Cargo.lock

@@ -33,6 +33,7 @@ subtle = "2.6.1"
 rand = "0.10.1"
 base64 = "0.22.1"
 glob-match = "0.2.1"
+similar = "3.1.0"
 
 [dev-dependencies]
 reqwest = { version = "0.12", features = ["blocking"] }

Cargo.toml

@@ -202,8 +202,9 @@ pub async fn compile_all_pipelines(skip_integrity: bool, debug_pipeline: bool) -
 /// Check that a compiled pipeline YAML matches its source markdown.
 ///
 /// Reads the `@ado-aw` header from `pipeline_path` to discover the source
-/// markdown file, compiles it fresh, and compares (whitespace-normalized)
-/// against the existing pipeline file. Returns an error if they differ.
+/// markdown file, compiles it fresh, and compares the canonicalized output
+/// against the existing pipeline file. When they differ, a unified diff is
+/// printed to stderr showing exactly which lines changed.
 pub async fn check_pipeline(pipeline_path: &str) -> Result<()> {
     let pipeline_path = Path::new(pipeline_path);
 
@@ -228,6 +229,16 @@ pub async fn check_pipeline(pipeline_path: &str) -> Result<()> {
             )
         })?;
 
+    // Warn if the pipeline was generated by a different compiler version
+    let current_version = env!("CARGO_PKG_VERSION");
+    if !header_meta.version.is_empty() && header_meta.version != current_version {
+        eprintln!(
+            "Warning: pipeline was generated by ado-aw v{}, current version is v{}. \
+             Version differences may cause expected changes in the output.",
+            header_meta.version, current_version
+        );
+    }
+
     // The header stores the source path relative to the repository root.
     // Walk up from the pipeline file to find the .git directory, then resolve
     // the source path relative to that root.
@@ -286,13 +297,19 @@ pub async fn check_pipeline(pipeline_path: &str) -> Result<()> {
             false,
         )
         .await?;
-    let pipeline_yaml = clean_generated_yaml(&pipeline_yaml);
 
-    // Compare ignoring whitespace differences
-    if normalize_whitespace(&pipeline_yaml) != normalize_whitespace(&existing) {
+    // Canonicalize both sides: trim trailing whitespace, collapse blank lines,
+    // but preserve indentation and internal spaces for meaningful comparison.
+    let expected = clean_generated_yaml(&pipeline_yaml);
+    let existing = clean_generated_yaml(&existing);
+
+    if expected != existing {
+        let diff_output = format_diff(&existing, &expected, pipeline_path);
+        eprintln!("{}", diff_output);
+
         anyhow::bail!(
             "Integrity check failed: generated pipeline for '{}' does not match {}. \
-             Re-run compilation to update the pipeline file.",
+             Re-run `ado-aw compile` to update the pipeline file.",
             front_matter.name,
             pipeline_path.display()
         );
@@ -302,6 +319,96 @@ pub async fn check_pipeline(pipeline_path: &str) -> Result<()> {
     Ok(())
 }
 
+/// Maximum number of changed lines to display in the diff output.
+/// Keeps terminal output manageable for large pipeline files.
+const MAX_DIFF_CHANGED_LINES: usize = 80;
+
+/// Format a unified-style diff between the existing and expected pipeline content.
+///
+/// Shows changed lines with surrounding context and a summary of the total
+/// number of changes. Output is truncated after [`MAX_DIFF_CHANGED_LINES`]
+/// changed lines to avoid overwhelming the terminal.
+fn format_diff(existing: &str, expected: &str, pipeline_path: &Path) -> String {
+    use similar::{ChangeTag, TextDiff};
+
+    let diff = TextDiff::from_lines(existing, expected);
+    let mut output = String::new();
+
+    output.push_str(&format!(
+        "\n--- {} (on disk)\n+++ {} (expected from source)\n",
+        pipeline_path.display(),
+        pipeline_path.display(),
+    ));
+
+    // First pass: count total changes across the full diff.
+    let (total_added, total_removed) = diff.iter_all_changes().fold((0usize, 0usize), |(a, r), c| {
+        match c.tag() {
+            ChangeTag::Insert => (a + 1, r),
+            ChangeTag::Delete => (a, r + 1),
+            ChangeTag::Equal => (a, r),
+        }
+    });
+
+    let mut changed_lines_shown = 0usize;
+    let mut truncated = false;
+
+    for hunk in diff.unified_diff().context_radius(3).iter_hunks() {
+        if truncated {
+            break;
+        }
+
+        // Buffer hunk lines so we only emit the header if we have content to show.
+        // This avoids orphaned hunk headers when truncation fires mid-hunk.
+        let mut hunk_buf = String::new();
+
+        for change in hunk.iter_changes() {
+            let tag = change.tag();
+            let line = change.value();
+
+            if tag != ChangeTag::Equal {
+                if changed_lines_shown >= MAX_DIFF_CHANGED_LINES {
+                    truncated = true;
+                    break;
+                }
+                changed_lines_shown += 1;
+            }
+
+            let prefix = match tag {
+                ChangeTag::Delete => "-",
+                ChangeTag::Insert => "+",
+                ChangeTag::Equal => " ",
+            };
+            // Lines from TextDiff include trailing newlines; write directly.
+            if line.ends_with('\n') {
+                hunk_buf.push_str(&format!("{}{}", prefix, line));
+            } else {
+                hunk_buf.push_str(&format!("{}{}\n", prefix, line));
+            }
+        }
+
+        if !hunk_buf.is_empty() {
+            output.push_str(&format!("{}\n", hunk.header()));
+            output.push_str(&hunk_buf);
+        }
+    }
+
+    if truncated {
+        output.push_str(&format!(
+            "\n... diff truncated after {} changed lines (showing {} of {} total changes)\n",
+            MAX_DIFF_CHANGED_LINES,
+            changed_lines_shown,
+            total_added + total_removed,
+        ));
+    }
+
+    output.push_str(&format!(
+        "\nSummary: {} line(s) added, {} line(s) removed\n",
+        total_added, total_removed
+    ));
+
+    output
+}
+
 /// Walk up from `start` to find the nearest directory containing `.git`.
 fn find_repo_root(start: &Path) -> Option<PathBuf> {
     let mut current = start.to_path_buf();
@@ -315,14 +422,6 @@ fn find_repo_root(start: &Path) -> Option<PathBuf> {
     }
 }
 
-/// Normalize a string by removing all whitespace characters.
-///
-/// Used for integrity checks so that formatting-only differences
-/// (trailing spaces, blank lines, indentation changes) are ignored.
-fn normalize_whitespace(s: &str) -> String {
-    s.chars().filter(|c| !c.is_whitespace()).collect()
-}
-
 /// Clean up spacing artifacts in generated YAML.
 ///
 /// After template placeholder replacement, empty placeholders leave behind
@@ -483,37 +582,99 @@ Body
     }
 
     #[test]
-    fn test_normalize_whitespace_strips_all_whitespace() {
-        assert_eq!(normalize_whitespace("a b c"), "abc");
-        assert_eq!(normalize_whitespace("a\n  b\n  c\n"), "abc");
-        assert_eq!(normalize_whitespace("  hello  world  "), "helloworld");
+    fn test_clean_generated_yaml_strips_trailing_whitespace() {
+        let a = clean_generated_yaml("key: value\nother: data\n");
+        let b = clean_generated_yaml("key: value  \nother: data  \n");
+        assert_eq!(a, b);
+    }
+
+    #[test]
+    fn test_clean_generated_yaml_collapses_blank_lines() {
+        // Consecutive blank lines collapse to a single blank line
+        let a = clean_generated_yaml("key: value\n\nother: data\n");
+        let b = clean_generated_yaml("key: value\n\n\nother: data\n\n");
+        assert_eq!(a, b);
+    }
+
+    #[test]
+    fn test_clean_generated_yaml_preserves_indentation() {
+        let input = "steps:\n  - bash: echo hello\n    displayName: greet\n";
+        let cleaned = clean_generated_yaml(input);
+        assert!(cleaned.contains("  - bash: echo hello"));
+        assert!(cleaned.contains("    displayName: greet"));
     }
 
     #[test]
-    fn test_normalize_whitespace_identical_content_matches() {
-        let a = "key: value\nother: data\n";
-        let b = "key: value\nother: data\n";
-        assert_eq!(normalize_whitespace(a), normalize_whitespace(b));
+    fn test_clean_generated_yaml_preserves_internal_spaces() {
+        let input = "script: echo a b c\n";
+        let cleaned = clean_generated_yaml(input);
+        assert!(cleaned.contains("echo a b c"));
     }
 
     #[test]
-    fn test_normalize_whitespace_ignores_trailing_spaces() {
-        let a = "key: value\nother: data\n";
-        let b = "key: value  \nother: data  \n";
-        assert_eq!(normalize_whitespace(a), normalize_whitespace(b));
+    fn test_format_diff_shows_added_lines() {
+        let existing = "line1\nline2\n";
+        let expected = "line1\nline2\nline3\n";
+        let diff = format_diff(existing, expected, Path::new("test.yml"));
+        assert!(diff.contains("+line3"));
+        assert!(diff.contains("1 line(s) added"));
     }
 
     #[test]
-    fn test_normalize_whitespace_ignores_blank_lines() {
-        let a = "key: value\nother: data\n";
-        let b = "key: value\n\n\nother: data\n\n";
-        assert_eq!(normalize_whitespace(a), normalize_whitespace(b));
+    fn test_format_diff_shows_removed_lines() {
+        let existing = "line1\nline2\nline3\n";
+        let expected = "line1\nline3\n";
+        let diff = format_diff(existing, expected, Path::new("test.yml"));
+        assert!(diff.contains("-line2"));
+        assert!(diff.contains("1 line(s) removed"));
     }
 
     #[test]
-    fn test_normalize_whitespace_detects_content_difference() {
-        let a = "key: value1\n";
-        let b = "key: value2\n";
-        assert_ne!(normalize_whitespace(a), normalize_whitespace(b));
+    fn test_format_diff_shows_changed_lines() {
+        let existing = "key: old_value\nother: data\n";
+        let expected = "key: new_value\nother: data\n";
+        let diff = format_diff(existing, expected, Path::new("test.yml"));
+        assert!(diff.contains("-key: old_value"));
+        assert!(diff.contains("+key: new_value"));
+        assert!(diff.contains("1 line(s) added, 1 line(s) removed"));
+    }
+
+    #[test]
+    fn test_format_diff_identical_produces_no_hunks() {
+        let content = "line1\nline2\n";
+        let diff = format_diff(content, content, Path::new("test.yml"));
+        assert!(diff.contains("0 line(s) added, 0 line(s) removed"));
+        assert!(!diff.contains("@@"));
+    }
+
+    #[test]
+    fn test_format_diff_includes_file_path() {
+        let diff = format_diff("a\n", "b\n", Path::new("my-pipeline.yml"));
+        assert!(diff.contains("my-pipeline.yml (on disk)"));
+        assert!(diff.contains("my-pipeline.yml (expected from source)"));
+    }
+
+    #[test]
+    fn test_format_diff_truncates_at_limit() {
+        // 100 unique old lines replaced by 100 unique new lines = 200 total changes.
+        let existing: String = (0..100).map(|i| format!("old{}\n", i)).collect();
+        let expected: String = (0..100).map(|i| format!("new{}\n", i)).collect();
+        let diff = format_diff(&existing, &expected, Path::new("test.yml"));
+        assert!(
+            diff.contains("... diff truncated"),
+            "diff should be truncated for >80 changed lines"
+        );
+        // Exactly 80 changed lines shown, 200 total changes (100 removed + 100 added).
+        assert!(
+            diff.contains("showing 80 of 200 total changes"),
+            "truncation message should report 80 shown of 200 total, got:\n{}",
+            diff
+        );
+        // Summary should reflect ALL changes, not just the shown ones.
+        assert!(
+            diff.contains("100 line(s) added, 100 line(s) removed"),
+            "summary should report full totals, got:\n{}",
+            diff
+        );
     }
 }