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(DiffArgs),
Show(ShowArgs),
}
#[derive(Parser)]
struct DiffArgs {
a: PathBuf,
b: PathBuf,
#[arg(short, long, value_enum, default_value_t = OutFormat::Human)]
format: OutFormat,
#[arg(short, long, default_value = "auto")]
input: String,
#[arg(short, long)]
config: Option<PathBuf>,
#[arg(long = "mask", value_name = "NAME")]
masks: Vec<String>,
#[arg(long = "drop-meta", value_name = "KEY")]
drop_meta: Vec<String>,
#[arg(long, value_enum, default_value_t = ColorChoice::Auto)]
color: ColorChoice,
#[arg(short, long)]
verbose: bool,
#[arg(long, default_value_t = 2)]
context: usize,
#[arg(long)]
check: bool,
#[arg(long)]
threshold: Option<f64>,
}
#[derive(Parser)]
struct ShowArgs {
file: PathBuf,
#[arg(short, long, default_value = "auto")]
input: String,
#[arg(short, long)]
config: Option<PathBuf>,
#[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)"),
})
}