veerdiff 0.1.0

Semantic diff engine for LLM and agent execution traces — find exactly where two runs veer apart.
Documentation
//! Small hand-written scanners backing the built-in [`Mask`](super::Mask)
//! variants. These deliberately avoid a regular-expression dependency: each is
//! a single left-to-right pass that recognizes an ASCII pattern and replaces it
//! with a placeholder, copying all other bytes (including multi-byte UTF-8
//! sequences) through unchanged.

/// Length in bytes of the UTF-8 character whose leading byte is `b`.
fn utf8_len(b: u8) -> usize {
    match b {
        0x00..=0x7F => 1,
        0xC0..=0xDF => 2,
        0xE0..=0xEF => 3,
        _ => 4,
    }
}

/// Walk `s` left to right; at each position, ask `matcher` whether a pattern
/// starts there. On a match spanning `[i, j)`, emit `placeholder` and jump to
/// `j`; otherwise copy one whole character and advance.
fn scan_replace(
    s: &str,
    placeholder: &str,
    matcher: impl Fn(&[u8], usize) -> Option<usize>,
) -> String {
    let bytes = s.as_bytes();
    let mut out = String::with_capacity(s.len());
    let mut i = 0;
    while i < bytes.len() {
        if let Some(j) = matcher(bytes, i)
            && j > i
        {
            out.push_str(placeholder);
            i = j;
            continue;
        }
        let len = utf8_len(bytes[i]).min(bytes.len() - i);
        // Safety: `i` sits on a char boundary and `len` is that char's length.
        out.push_str(std::str::from_utf8(&bytes[i..i + len]).unwrap_or("\u{fffd}"));
        i += len;
    }
    out
}

fn n_hex(b: &[u8], start: usize, count: usize) -> bool {
    start + count <= b.len() && b[start..start + count].iter().all(u8::is_ascii_hexdigit)
}

fn n_digit(b: &[u8], start: usize, count: usize) -> bool {
    start + count <= b.len() && b[start..start + count].iter().all(u8::is_ascii_digit)
}

/// Replace RFC-4122 style UUIDs (`8-4-4-4-12` hex) with `<uuid>`.
pub fn mask_uuid(s: &str) -> String {
    scan_replace(s, "<uuid>", |b, i| {
        // Only start at a boundary so we do not match inside a longer hex run.
        if i > 0 && (b[i - 1].is_ascii_hexdigit() || b[i - 1] == b'-') {
            return None;
        }
        let groups = [8, 4, 4, 4, 12];
        let mut pos = i;
        for (g, &len) in groups.iter().enumerate() {
            if !n_hex(b, pos, len) {
                return None;
            }
            pos += len;
            if g < groups.len() - 1 {
                if pos >= b.len() || b[pos] != b'-' {
                    return None;
                }
                pos += 1;
            }
        }
        // Reject if the run continues (would make it not a bare UUID).
        if pos < b.len() && (b[pos].is_ascii_hexdigit() || b[pos] == b'-') {
            return None;
        }
        Some(pos)
    })
}

/// Replace ISO-8601 date-times (`YYYY-MM-DDThh:mm:ss[.f][Z|±hh:mm]`) with
/// `<timestamp>`.
pub fn mask_timestamp(s: &str) -> String {
    scan_replace(s, "<timestamp>", |b, i| {
        if i > 0 && b[i - 1].is_ascii_digit() {
            return None;
        }
        let mut p = i;
        // YYYY-MM-DD
        if !n_digit(b, p, 4) {
            return None;
        }
        p += 4;
        for _ in 0..2 {
            if p >= b.len() || b[p] != b'-' || !n_digit(b, p + 1, 2) {
                return None;
            }
            p += 3;
        }
        // Separator between date and time.
        if p >= b.len() || (b[p] != b'T' && b[p] != b' ' && b[p] != b't') {
            return None;
        }
        p += 1;
        // hh:mm:ss
        if !n_digit(b, p, 2) {
            return None;
        }
        p += 2;
        for _ in 0..2 {
            if p >= b.len() || b[p] != b':' || !n_digit(b, p + 1, 2) {
                return None;
            }
            p += 3;
        }
        // Optional fractional seconds.
        if p < b.len() && b[p] == b'.' {
            let mut q = p + 1;
            while q < b.len() && b[q].is_ascii_digit() {
                q += 1;
            }
            if q > p + 1 {
                p = q;
            }
        }
        // Optional timezone.
        if p < b.len() && (b[p] == b'Z' || b[p] == b'z') {
            p += 1;
        } else if p < b.len() && (b[p] == b'+' || b[p] == b'-') && n_digit(b, p + 1, 2) {
            p += 3;
            if p < b.len() && b[p] == b':' && n_digit(b, p + 1, 2) {
                p += 3;
            }
        }
        Some(p)
    })
}

/// Replace email addresses with `<email>`.
pub fn mask_email(s: &str) -> String {
    fn is_local(b: u8) -> bool {
        b.is_ascii_alphanumeric() || matches!(b, b'.' | b'_' | b'%' | b'+' | b'-')
    }
    fn is_domain(b: u8) -> bool {
        b.is_ascii_alphanumeric() || b == b'-'
    }
    scan_replace(s, "<email>", |b, i| {
        if i > 0 && is_local(b[i - 1]) {
            return None;
        }
        let mut p = i;
        while p < b.len() && is_local(b[p]) {
            p += 1;
        }
        if p == i || p >= b.len() || b[p] != b'@' {
            return None;
        }
        p += 1;
        // At least one dotted label followed by a 2+ letter TLD.
        let mut saw_dot = false;
        let domain_start = p;
        loop {
            let label_start = p;
            while p < b.len() && is_domain(b[p]) {
                p += 1;
            }
            if p == label_start {
                return None;
            }
            if p < b.len() && b[p] == b'.' {
                saw_dot = true;
                p += 1;
            } else {
                break;
            }
        }
        if !saw_dot || p == domain_start {
            return None;
        }
        // Require the final label (TLD) to be ≥ 2 ASCII letters.
        let mut tld_start = p;
        while tld_start > domain_start && b[tld_start - 1] != b'.' {
            tld_start -= 1;
        }
        let tld = &b[tld_start..p];
        if tld.len() < 2 || !tld.iter().all(u8::is_ascii_alphabetic) {
            return None;
        }
        Some(p)
    })
}

/// Replace long hexadecimal runs (≥ 32 chars — request ids, hashes) with
/// `<hex>`.
pub fn mask_hex(s: &str) -> String {
    scan_replace(s, "<hex>", |b, i| {
        if i > 0 && b[i - 1].is_ascii_hexdigit() {
            return None;
        }
        let mut p = i;
        while p < b.len() && b[p].is_ascii_hexdigit() {
            p += 1;
        }
        if p - i >= 32 { Some(p) } else { None }
    })
}

/// Replace standalone numeric literals with `<num>`.
pub fn mask_number(s: &str) -> String {
    scan_replace(s, "<num>", |b, i| {
        if i > 0 && (b[i - 1].is_ascii_alphanumeric() || b[i - 1] == b'.') {
            return None;
        }
        let mut p = i;
        if b[p] == b'-' {
            p += 1;
        }
        let int_start = p;
        while p < b.len() && b[p].is_ascii_digit() {
            p += 1;
        }
        if p == int_start {
            return None;
        }
        if p < b.len() && b[p] == b'.' {
            let frac_start = p + 1;
            let mut q = frac_start;
            while q < b.len() && b[q].is_ascii_digit() {
                q += 1;
            }
            if q > frac_start {
                p = q;
            }
        }
        if p < b.len() && (b[p] == b'e' || b[p] == b'E') {
            let mut q = p + 1;
            if q < b.len() && (b[q] == b'+' || b[q] == b'-') {
                q += 1;
            }
            let exp_start = q;
            while q < b.len() && b[q].is_ascii_digit() {
                q += 1;
            }
            if q > exp_start {
                p = q;
            }
        }
        // Reject if a letter follows (e.g. `2xx`, `3d`).
        if p < b.len() && b[p].is_ascii_alphabetic() {
            return None;
        }
        Some(p)
    })
}

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

    #[test]
    fn uuid() {
        assert_eq!(
            mask_uuid("id=550e8400-e29b-41d4-a716-446655440000 done"),
            "id=<uuid> done"
        );
        assert_eq!(mask_uuid("no uuid here"), "no uuid here");
    }

    #[test]
    fn timestamp() {
        assert_eq!(
            mask_timestamp("at 2024-01-02T03:04:05Z ok"),
            "at <timestamp> ok"
        );
        assert_eq!(
            mask_timestamp("2024-01-02T03:04:05.123+05:30"),
            "<timestamp>"
        );
        assert_eq!(mask_timestamp("2024-01-02 03:04:05"), "<timestamp>");
        assert_eq!(mask_timestamp("version 2024 only"), "version 2024 only");
    }

    #[test]
    fn email() {
        assert_eq!(mask_email("to a.b+x@mail.co.uk!"), "to <email>!");
        assert_eq!(mask_email("not@ an email"), "not@ an email");
        assert_eq!(mask_email("plain text"), "plain text");
    }

    #[test]
    fn hex() {
        let h = "a".repeat(40);
        assert_eq!(mask_hex(&format!("sha {h}")), "sha <hex>");
        assert_eq!(mask_hex("cafe"), "cafe"); // too short
    }

    #[test]
    fn number() {
        assert_eq!(
            mask_number("count 42 and -3.14e2 end"),
            "count <num> and <num> end"
        );
        assert_eq!(mask_number("v2 model"), "v2 model");
        assert_eq!(mask_number("id2a3"), "id2a3");
    }

    #[test]
    fn preserves_multibyte_characters() {
        assert_eq!(mask_number("café 3 é"), "café <num> é");
    }
}