feat: implement image-diff CLI with terminal previews and recursive directory diffing

- Core pixel-by-pixel comparison with threshold support
- Parallel directory walking and comparison using Rayon
- ANSI half-block terminal preview for instant feedback
- Semantic exit codes and directory summary reporting

Author: maskedsyntax

.gitignore

@@ -1,21 +1,6 @@
-# Generated by Cargo
-# will have compiled files and executables
-debug
-target
-
-# These are backup files generated by rustfmt
-**/*.rs.bk
-
-# MSVC Windows builds of rustc generate these, which store debugging information
-*.pdb
-
-# Generated by cargo mutants
-# Contains mutation testing data
-**/mutants.out*/
-
-# RustRover
-#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
-#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
-#  and can be added to the global gitignore or merged into this file.  For a more nuclear
-#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
-#.idea/
+/target
+Cargo.lock
+.DS_Store
+*.png
+*.jpg
+*.jpeg

Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "image-diff"
+version = "0.1.0"
+edition = "2021"
+authors = ["Batman"]
+description = "Visual Difference Detection CLI for Images"
+
+[dependencies]
+image = "0.25.1"
+clap = { version = "4.5.4", features = ["derive"] }
+rayon = "1.10.0"
+walkdir = "2.5.0"
+anyhow = "1.0.82"
+colored = "2.1.0"
+indicatif = "0.17.8"
+terminal_size = "0.3.0"
+pathdiff = "0.2.1"

src/compare.rs

@@ -0,0 +1,88 @@
+use anyhow::Result;
+use image::{GenericImageView, ImageBuffer, Rgba};
+use std::path::Path;
+
+pub struct DiffResult {
+    pub score: f64,
+    pub diff_pixels: u64,
+    pub total_pixels: u64,
+    pub diff_image: Option<ImageBuffer<Rgba<u8>, Vec<u8>>>,
+}
+
+pub fn compare_images(
+    path_a: &Path,
+    path_b: &Path,
+    threshold: f32,
+    generate_diff: bool,
+) -> Result<DiffResult> {
+    let img_a = image::open(path_a)?;
+    let img_b = image::open(path_b)?;
+
+    let (width_a, height_a) = img_a.dimensions();
+    let (width_b, height_b) = img_b.dimensions();
+
+    let max_width = width_a.max(width_b);
+    let max_height = height_a.max(height_b);
+
+    let mut diff_pixels = 0u64;
+    let total_pixels = (max_width as u64) * (max_height as u64);
+
+    let mut diff_buffer = if generate_diff {
+        Some(ImageBuffer::new(max_width, max_height))
+    } else {
+        None
+    };
+
+    for y in 0..max_height {
+        for x in 0..max_width {
+            let pixel_a = if x < width_a && y < height_a {
+                img_a.get_pixel(x, y)
+            } else {
+                Rgba([0, 0, 0, 0])
+            };
+
+            let pixel_b = if x < width_b && y < height_b {
+                img_b.get_pixel(x, y)
+            } else {
+                Rgba([0, 0, 0, 0])
+            };
+
+            let dist = color_distance(&pixel_a, &pixel_b);
+            
+            let is_different = dist > (threshold as f64);
+
+            if is_different {
+                diff_pixels += 1;
+                if let Some(ref mut buffer) = diff_buffer {
+                    // Magenta for differences
+                    buffer.put_pixel(x, y, Rgba([255, 0, 255, 255]));
+                }
+            } else if let Some(ref mut buffer) = diff_buffer {
+                // Dimmed version of original for non-diff
+                let r = (pixel_a[0] as f32 * 0.1) as u8;
+                let g = (pixel_a[1] as f32 * 0.1) as u8;
+                let b = (pixel_a[2] as f32 * 0.1) as u8;
+                buffer.put_pixel(x, y, Rgba([r, g, b, 255]));
+            }
+        }
+    }
+
+    let score = 1.0 - (diff_pixels as f64 / total_pixels as f64);
+
+    Ok(DiffResult {
+        score,
+        diff_pixels,
+        total_pixels,
+        diff_image: diff_buffer,
+    })
+}
+
+fn color_distance(p1: &Rgba<u8>, p2: &Rgba<u8>) -> f64 {
+    let r_diff = (p1[0] as f64 - p2[0] as f64) / 255.0;
+    let g_diff = (p1[1] as f64 - p2[1] as f64) / 255.0;
+    let b_diff = (p1[2] as f64 - p2[2] as f64) / 255.0;
+    let a_diff = (p1[3] as f64 - p2[3] as f64) / 255.0;
+
+    // Euclidean distance in RGBA space
+    (r_diff * r_diff + g_diff * g_diff + b_diff * b_diff + a_diff * a_diff).sqrt()
+}

src/dir.rs

@@ -0,0 +1,67 @@
+use crate::compare::{compare_images, DiffResult};
+use anyhow::Result;
+use indicatif::{ProgressBar, ProgressStyle};
+use rayon::prelude::*;
+use std::path::{Path, PathBuf};
+use walkdir::WalkDir;
+
+pub enum DirDiffStatus {
+    Match(DiffResult),
+    MissingInB,
+    Error(String),
+}
+
+pub struct DirDiffItem {
+    pub relative_path: PathBuf,
+    pub status: DirDiffStatus,
+}
+
+pub fn compare_directories(
+    dir_a: &Path,
+    dir_b: &Path,
+    threshold: f32,
+) -> Result<Vec<DirDiffItem>> {
+    let files_a: Vec<PathBuf> = WalkDir::new(dir_a)
+        .into_iter()
+        .filter_map(|e| e.ok())
+        .filter(|e| is_image(e.path()))
+        .map(|e| e.path().to_path_buf())
+        .collect();
+
+    let pb = ProgressBar::new(files_a.len() as u64);
+    pb.set_style(ProgressStyle::default_bar()
+        .template("{spinner:.green} [{elapsed_precise}] [{bar:40.cyan/blue}] {pos}/{len} ({eta})")
+        .unwrap());
+
+    let results: Vec<DirDiffItem> = files_a
+        .into_par_iter()
+        .map(|path_a| {
+            let relative = path_a.strip_prefix(dir_a).unwrap();
+            let path_b = dir_b.join(relative);
+
+            let status = if !path_b.exists() {
+                DirDiffStatus::MissingInB
+            } else {
+                match compare_images(&path_a, &path_b, threshold, false) {
+                    Ok(res) => DirDiffStatus::Match(res),
+                    Err(e) => DirDiffStatus::Error(e.to_string()),
+                }
+            };
+
+            pb.inc(1);
+
+            DirDiffItem {
+                relative_path: relative.to_path_buf(),
+                status,
+            }
+        })
+        .collect();
+
+    pb.finish_with_message("Done");
+    Ok(results)
+}
+
+fn is_image(path: &Path) -> bool {
+    let ext = path.extension().and_then(|s| s.to_str()).unwrap_or("").to_lowercase();
+    matches!(ext.as_str(), "png" | "jpg" | "jpeg" | "webp" | "bmp")
+}

src/main.rs

@@ -0,0 +1,131 @@
+mod compare;
+mod dir;
+mod terminal;
+
+use anyhow::Result;
+use clap::Parser;
+use colored::*;
+use std::path::PathBuf;
+
+#[derive(Parser, Debug)]
+#[command(author, version, about, long_about = None)]
+struct Args {
+    /// First image or directory
+    path_a: PathBuf,
+
+    /// Second image or directory
+    path_b: PathBuf,
+
+    /// Threshold for difference (0.0 to 1.0)
+    #[arg(short, long, default_value_t = 0.1)]
+    threshold: f32,
+
+    /// Output path for diff overlay image (single file mode only)
+    #[arg(short, long)]
+    output: Option<PathBuf>,
+
+    /// Print preview in terminal
+    #[arg(short, long)]
+    preview: bool,
+
+    /// Fail if any difference is found (non-zero exit code)
+    #[arg(long)]
+    fail_on_diff: bool,
+}
+
+fn main() -> Result<()> {
+    let args = Args::parse();
+
+    if args.path_a.is_dir() && args.path_b.is_dir() {
+        run_dir_diff(&args)
+    } else {
+        run_file_diff(&args)
+    }
+}
+
+fn run_file_diff(args: &Args) -> Result<()> {
+    let res = compare::compare_images(
+        &args.path_a,
+        &args.path_b,
+        args.threshold,
+        args.output.is_some() || args.preview,
+    )?;
+
+    println!("{}", "Comparison Result:".bold());
+    println!("  Similarity: {:.2}%", res.score * 100.0);
+    println!("  Diff Pixels: {}", res.diff_pixels);
+    println!("  Total Pixels: {}", res.total_pixels);
+
+    if let Some(diff_img) = &res.diff_image {
+        if let Some(output_path) = &args.output {
+            diff_img.save(output_path)?;
+            println!("  Diff image saved to: {}", output_path.display().to_string().cyan());
+        }
+
+        if args.preview {
+            println!("\n{}", "Terminal Preview:".bold());
+            let dynamic_img = image::DynamicImage::ImageRgba8(diff_img.clone());
+            terminal::print_preview(&dynamic_img);
+        }
+    }
+
+    if args.fail_on_diff && res.diff_pixels > 0 {
+        std::process::exit(1);
+    }
+
+    Ok(())
+}
+
+fn run_dir_diff(args: &Args) -> Result<()> {
+    let items = dir::compare_directories(&args.path_a, &args.path_b, args.threshold)?;
+
+    println!("\n{:<40} {:<10} {:<10}", "File", "Score", "Status");
+    println!("{}", "-".repeat(65));
+
+    let mut diff_count = 0;
+
+    let total_files = items.len();
+    for item in items {
+        match item.status {
+            dir::DirDiffStatus::Match(res) => {
+                let status = if res.diff_pixels > 0 {
+                    diff_count += 1;
+                    "DIFF".red()
+                } else {
+                    "OK".green()
+                };
+                println!("{:<40} {:<10.2}% {:<10}", 
+                    item.relative_path.display().to_string(),
+                    res.score * 100.0,
+                    status
+                );
+            }
+            dir::DirDiffStatus::MissingInB => {
+                diff_count += 1;
+                println!("{:<40} {:<10} {:<10}", 
+                    item.relative_path.display().to_string(),
+                    "-".dimmed(),
+                    "MISSING".yellow()
+                );
+            }
+            dir::DirDiffStatus::Error(e) => {
+                println!("{:<40} {:<10} {:<10}", 
+                    item.relative_path.display().to_string(),
+                    "ERROR".red(),
+                    e.yellow()
+                );
+            }
+        }
+    }
+
+    println!("\nSummary: {} files compared, {} differences found.", 
+        total_files, 
+        diff_count
+    );
+
+    if args.fail_on_diff && diff_count > 0 {
+        std::process::exit(1);
+    }
+
+    Ok(())
+}

src/terminal.rs

@@ -0,0 +1,47 @@
+use colored::*;
+use image::{DynamicImage, GenericImageView, Rgba};
+use terminal_size::{terminal_size, Width};
+
+pub fn print_preview(img: &DynamicImage) {
+    let (tw, _th) = if let Some((Width(w), h)) = terminal_size() {
+        (w as u32, h.0 as u32)
+    } else {
+        (80, 24)
+    };
+
+    let (width, height) = img.dimensions();
+    let aspect_ratio = height as f32 / width as f32;
+    
+    // We use half blocks, so each character is 2 vertical pixels
+    let target_width = tw.min(width).min(80); // Cap width for readability
+    let target_height = (target_width as f32 * aspect_ratio) as u32;
+    
+    let resized = img.resize_exact(target_width, target_height * 2, image::imageops::FilterType::Nearest);
+    
+    for y in (0..resized.height()).step_by(2) {
+        for x in 0..resized.width() {
+            let top = resized.get_pixel(x, y);
+            let bottom = if y + 1 < resized.height() {
+                resized.get_pixel(x, y + 1)
+            } else {
+                Rgba([0, 0, 0, 0])
+            };
+
+            let top_color = to_ansi_color(top);
+            let bottom_color = to_ansi_color(bottom);
+
+            print!("{}", "▀".truecolor(top_color.0, top_color.1, top_color.2)
+                            .on_truecolor(bottom_color.0, bottom_color.1, bottom_color.2));
+        }
+        println!();
+    }
+}
+
+fn to_ansi_color(pixel: Rgba<u8>) -> (u8, u8, u8) {
+    let alpha = pixel[3] as f32 / 255.0;
+    (
+        (pixel[0] as f32 * alpha) as u8,
+        (pixel[1] as f32 * alpha) as u8,
+        (pixel[2] as f32 * alpha) as u8,
+    )
+}