veerdiff 0.1.0

Semantic diff engine for LLM and agent execution traces — find exactly where two runs veer apart.
Documentation
//! Runtime configuration for a diff: how to normalize, how to weight fields,
//! and where the thresholds sit.
//!
//! A [`Config`] can be built programmatically or deserialized from JSON (always
//! available) or TOML (with the `cli` feature). All fields have sensible
//! defaults, so `Config::default()` is a good starting point.

use serde::{Deserialize, Serialize};

use crate::error::{Error, Result};
use crate::normalize::Normalizer;
use crate::similarity::Weights;

/// Top-level configuration for [`crate::diff`].
#[derive(Clone, Debug, PartialEq, Serialize, Deserialize)]
#[serde(default)]
pub struct Config {
    /// Normalization applied to both traces before alignment.
    pub normalizer: Normalizer,
    /// Field weights used when scoring step similarity.
    pub weights: Weights,
    /// Similarity at or above which two aligned steps are considered *equal*
    /// (reported with no field-level diff). Range `[0, 1]`.
    pub equal_threshold: f64,
    /// Minimum similarity required to align (pair) two steps at all. Below this
    /// a candidate pairing is rejected and the steps are reported as a
    /// delete + insert rather than a change. Range `[0, 1]`.
    pub align_floor: f64,
}

impl Default for Config {
    fn default() -> Self {
        Config {
            normalizer: Normalizer::default(),
            weights: Weights::default(),
            equal_threshold: 0.999,
            align_floor: 0.4,
        }
    }
}

impl Config {
    /// Validate that thresholds are in range and coherent.
    pub fn validate(&self) -> Result<()> {
        for (name, v) in [
            ("equal_threshold", self.equal_threshold),
            ("align_floor", self.align_floor),
        ] {
            if !(0.0..=1.0).contains(&v) {
                return Err(Error::Config(format!("{name} must be in [0, 1], got {v}")));
            }
        }
        if self.align_floor > self.equal_threshold {
            return Err(Error::Config(
                "align_floor must not exceed equal_threshold".into(),
            ));
        }
        Ok(())
    }

    /// Parse a configuration from a JSON string.
    pub fn from_json_str(s: &str) -> Result<Self> {
        let cfg: Config = serde_json::from_str(s)?;
        cfg.validate()?;
        Ok(cfg)
    }

    /// Parse a configuration from a TOML string.
    #[cfg(feature = "cli")]
    pub fn from_toml_str(s: &str) -> Result<Self> {
        let cfg: Config =
            toml::from_str(s).map_err(|e| Error::Config(format!("invalid TOML: {e}")))?;
        cfg.validate()?;
        Ok(cfg)
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn defaults_validate() {
        Config::default().validate().unwrap();
    }

    #[test]
    fn out_of_range_threshold_is_rejected() {
        let cfg = Config {
            equal_threshold: 1.5,
            ..Config::default()
        };
        assert!(cfg.validate().is_err());
    }

    #[test]
    fn floor_above_equal_is_rejected() {
        let cfg = Config {
            align_floor: 0.99,
            equal_threshold: 0.5,
            ..Config::default()
        };
        assert!(cfg.validate().is_err());
    }

    #[test]
    fn roundtrips_through_json() {
        let cfg = Config::default();
        let s = serde_json::to_string(&cfg).unwrap();
        let back = Config::from_json_str(&s).unwrap();
        assert_eq!(cfg, back);
    }
}