veerdiff 0.1.0

Semantic diff engine for LLM and agent execution traces — find exactly where two runs veer apart.
Documentation
//! Command-line front-end for the `veer` trace-diff engine.

use std::io::{IsTerminal, Write};
use std::path::{Path, PathBuf};
use std::process::ExitCode;

use anyhow::{Context, Result, bail};
use clap::{Parser, Subcommand, ValueEnum};

use veerdiff::config::Config;
use veerdiff::import::{self, Format};
use veerdiff::normalize::Mask;
use veerdiff::report::{RenderOptions, ReportFormat, render};

#[derive(Parser)]
#[command(
    name = "veer",
    version,
    about = "Semantic diff for LLM & agent execution traces",
    long_about = "veer aligns two agent/LLM runs and shows exactly where they diverge, \
                  ignoring incidental noise (ids, timestamps, JSON key order, whitespace)."
)]
struct Cli {
    #[command(subcommand)]
    cmd: Cmd,
}

#[derive(Subcommand)]
enum Cmd {
    /// Diff two traces.
    Diff(DiffArgs),
    /// Import a trace and print it in the normalized `veer` schema.
    Show(ShowArgs),
}

#[derive(Parser)]
struct DiffArgs {
    /// Left ("before") trace file.
    a: PathBuf,
    /// Right ("after") trace file.
    b: PathBuf,

    /// Output format.
    #[arg(short, long, value_enum, default_value_t = OutFormat::Human)]
    format: OutFormat,

    /// Input format for both files.
    #[arg(short, long, default_value = "auto")]
    input: String,

    /// Configuration file (`.toml` or `.json`).
    #[arg(short, long)]
    config: Option<PathBuf>,

    /// Apply a built-in masker (repeatable): uuid, timestamp, email, hex, number.
    #[arg(long = "mask", value_name = "NAME")]
    masks: Vec<String>,

    /// Drop a metadata key before comparison (repeatable).
    #[arg(long = "drop-meta", value_name = "KEY")]
    drop_meta: Vec<String>,

    /// When to colorize human output.
    #[arg(long, value_enum, default_value_t = ColorChoice::Auto)]
    color: ColorChoice,

    /// Show unchanged steps too.
    #[arg(short, long)]
    verbose: bool,

    /// Unchanged steps of context to show around each change.
    #[arg(long, default_value_t = 2)]
    context: usize,

    /// Exit non-zero when the traces differ (for CI).
    #[arg(long)]
    check: bool,

    /// With --check, tolerate differences while similarity is at least this.
    #[arg(long)]
    threshold: Option<f64>,
}

#[derive(Parser)]
struct ShowArgs {
    /// Trace file to import and normalize.
    file: PathBuf,
    /// Input format.
    #[arg(short, long, default_value = "auto")]
    input: String,
    /// Configuration file (`.toml` or `.json`).
    #[arg(short, long)]
    config: Option<PathBuf>,
    /// Print without applying normalization.
    #[arg(long)]
    raw: bool,
}

#[derive(Clone, Copy, PartialEq, Eq, ValueEnum)]
enum OutFormat {
    Human,
    Json,
    Summary,
}

impl From<OutFormat> for ReportFormat {
    fn from(f: OutFormat) -> Self {
        match f {
            OutFormat::Human => ReportFormat::Human,
            OutFormat::Json => ReportFormat::Json,
            OutFormat::Summary => ReportFormat::Summary,
        }
    }
}

#[derive(Clone, Copy, PartialEq, Eq, ValueEnum)]
enum ColorChoice {
    Auto,
    Always,
    Never,
}

fn main() -> ExitCode {
    let cli = Cli::parse();
    let result = match cli.cmd {
        Cmd::Diff(args) => run_diff(args),
        Cmd::Show(args) => run_show(args).map(|()| ExitCode::SUCCESS),
    };
    match result {
        Ok(code) => code,
        Err(e) => {
            eprintln!("veer: error: {e:#}");
            ExitCode::from(2)
        }
    }
}

fn run_diff(args: DiffArgs) -> Result<ExitCode> {
    let format = Format::parse(&args.input).map_err(anyhow::Error::from)?;
    let cfg = build_config(&args)?;

    let a = read_trace(&args.a, format)?;
    let b = read_trace(&args.b, format)?;

    let (diff, na, nb) = veerdiff::diff_normalized(a, b, &cfg);

    let color = match args.color {
        ColorChoice::Always => true,
        ColorChoice::Never => false,
        ColorChoice::Auto => {
            std::env::var_os("NO_COLOR").is_none() && std::io::stdout().is_terminal()
        }
    };
    let opts = RenderOptions {
        color,
        verbose: args.verbose,
        context: args.context,
    };

    let text = render(&diff, &na, &nb, args.format.into(), opts);
    let mut stdout = std::io::stdout().lock();
    writeln!(stdout, "{text}").ok();

    if args.check {
        let ok = match args.threshold {
            Some(t) => diff.similarity >= t,
            None => diff.is_identical(),
        };
        if !ok {
            return Ok(ExitCode::from(1));
        }
    }
    Ok(ExitCode::SUCCESS)
}

fn run_show(args: ShowArgs) -> Result<()> {
    let format = Format::parse(&args.input).map_err(anyhow::Error::from)?;
    let mut trace = read_trace(&args.file, format)?;
    if !args.raw {
        let cfg = load_config(args.config.as_deref())?;
        cfg.normalizer.apply(&mut trace);
    }
    let json = serde_json::to_string_pretty(&trace).context("serializing trace")?;
    println!("{json}");
    Ok(())
}

fn read_trace(path: &Path, format: Format) -> Result<veerdiff::Trace> {
    let text =
        std::fs::read_to_string(path).with_context(|| format!("reading {}", path.display()))?;
    import::import_str(&text, format)
        .map_err(anyhow::Error::from)
        .with_context(|| format!("importing {}", path.display()))
}

fn build_config(args: &DiffArgs) -> Result<Config> {
    let mut cfg = load_config(args.config.as_deref())?;
    for name in &args.masks {
        cfg.normalizer.mask.push(parse_mask(name)?);
    }
    cfg.normalizer
        .drop_meta
        .extend(args.drop_meta.iter().cloned());
    cfg.validate().map_err(anyhow::Error::from)?;
    Ok(cfg)
}

fn load_config(path: Option<&Path>) -> Result<Config> {
    let Some(path) = path else {
        return Ok(Config::default());
    };
    let text =
        std::fs::read_to_string(path).with_context(|| format!("reading {}", path.display()))?;
    let is_json = path.extension().and_then(|e| e.to_str()) == Some("json");
    let cfg = if is_json {
        Config::from_json_str(&text)
    } else {
        Config::from_toml_str(&text)
    };
    cfg.map_err(anyhow::Error::from)
        .with_context(|| format!("parsing config {}", path.display()))
}

fn parse_mask(name: &str) -> Result<Mask> {
    Ok(match name.to_ascii_lowercase().as_str() {
        "uuid" => Mask::Uuid,
        "timestamp" | "time" | "ts" => Mask::Timestamp,
        "email" => Mask::Email,
        "hex" | "hexhash" | "hash" => Mask::HexHash,
        "number" | "num" => Mask::Number,
        other => bail!("unknown mask `{other}` (expected uuid|timestamp|email|hex|number)"),
    })
}