amql_engine/

diff.rs

//! Annotation drift detection between current state and a git baseline.
//!
//! Compares the current AnnotationStore against a serialized baseline
//! (typically from `git show HEAD`) to report added, removed, and changed
//! annotations.

use crate::store::Annotation;
use crate::types::{Binding, RelativePath, TagName};
use serde::Serialize;

/// Summary of annotation changes between two states.
#[non_exhaustive]
#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
#[cfg_attr(feature = "flow", derive(flowjs_rs::Flow))]
#[cfg_attr(feature = "ts", ts(export))]
#[cfg_attr(feature = "flow", flow(export))]
#[derive(Debug, Clone, Serialize)]
pub struct DiffResult {
    /// Annotations present now but not in the baseline.
    pub added: Vec<DiffEntry>,
    /// Annotations present in the baseline but not now.
    pub removed: Vec<DiffEntry>,
    /// Annotations where tag+binding match but attributes differ.
    pub changed: Vec<DiffChange>,
}

/// A single annotation in a diff.
#[non_exhaustive]
#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
#[cfg_attr(feature = "flow", derive(flowjs_rs::Flow))]
#[cfg_attr(feature = "ts", ts(export))]
#[cfg_attr(feature = "flow", flow(export))]
#[derive(Debug, Clone, Serialize)]
pub struct DiffEntry {
    /// File the annotation belongs to.
    pub file: RelativePath,
    /// Annotation tag.
    pub tag: TagName,
    /// Annotation binding.
    pub binding: Binding,
}

/// An annotation that changed between baseline and current.
#[non_exhaustive]
#[cfg_attr(feature = "ts", derive(ts_rs::TS))]
#[cfg_attr(feature = "flow", derive(flowjs_rs::Flow))]
#[cfg_attr(feature = "ts", ts(export))]
#[cfg_attr(feature = "flow", flow(export))]
#[derive(Debug, Clone, Serialize)]
pub struct DiffChange {
    /// File the annotation belongs to.
    pub file: RelativePath,
    /// Annotation tag.
    pub tag: TagName,
    /// Annotation binding.
    pub binding: Binding,
    /// Attributes in the baseline that differ or are absent in current.
    pub baseline_attrs: Vec<String>,
    /// Attributes in current that differ or are absent in baseline.
    pub current_attrs: Vec<String>,
}

/// Compute the diff between baseline annotations and current annotations.
///
/// Both inputs are flat lists of annotations. Matching is by (file, tag, binding).
#[must_use = "diff result contains added, removed, and changed annotations"]
pub fn diff_annotations(baseline: &[Annotation], current: &[Annotation]) -> DiffResult {
    let mut added = Vec::new();
    let mut removed = Vec::new();
    let mut changed = Vec::new();

    // Index baseline by (file, tag, binding)
    let baseline_set: rustc_hash::FxHashMap<(&str, &str, &str), &Annotation> = baseline
        .iter()
        .map(|a| (a.file.as_ref(), a.tag.as_ref(), a.binding.as_ref()))
        .zip(baseline.iter())
        .collect();

    let current_set: rustc_hash::FxHashMap<(&str, &str, &str), &Annotation> = current
        .iter()
        .map(|a| (a.file.as_ref(), a.tag.as_ref(), a.binding.as_ref()))
        .zip(current.iter())
        .collect();

    // Find added and changed
    for (key, curr_ann) in &current_set {
        match baseline_set.get(key) {
            None => {
                added.push(DiffEntry {
                    file: curr_ann.file.clone(),
                    tag: curr_ann.tag.clone(),
                    binding: curr_ann.binding.clone(),
                });
            }
            Some(base_ann) => {
                let diff = attr_diff(base_ann, curr_ann);
                if !diff.0.is_empty() || !diff.1.is_empty() {
                    changed.push(DiffChange {
                        file: curr_ann.file.clone(),
                        tag: curr_ann.tag.clone(),
                        binding: curr_ann.binding.clone(),
                        baseline_attrs: diff.0,
                        current_attrs: diff.1,
                    });
                }
            }
        }
    }

    // Find removed
    for (key, base_ann) in &baseline_set {
        if !current_set.contains_key(key) {
            removed.push(DiffEntry {
                file: base_ann.file.clone(),
                tag: base_ann.tag.clone(),
                binding: base_ann.binding.clone(),
            });
        }
    }

    DiffResult {
        added,
        removed,
        changed,
    }
}

/// Compare attributes between two annotations, returning changed attr names.
fn attr_diff(baseline: &Annotation, current: &Annotation) -> (Vec<String>, Vec<String>) {
    let mut baseline_diff = Vec::new();
    let mut current_diff = Vec::new();

    for (key, base_val) in &baseline.attrs {
        match current.attrs.get(key.as_ref()) {
            None => baseline_diff.push(format!("-{key}")),
            Some(curr_val) if curr_val != base_val => {
                baseline_diff.push(format!("{key}={base_val}"));
                current_diff.push(format!("{key}={curr_val}"));
            }
            _ => {}
        }
    }

    for key in current.attrs.keys() {
        if !baseline.attrs.contains_key(key.as_ref()) {
            current_diff.push(format!("+{key}"));
        }
    }

    (baseline_diff, current_diff)
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::types::{AttrName, Binding, TagName};
    use rustc_hash::FxHashMap;
    use serde_json::Value as JsonValue;

    fn ann(tag: &str, binding: &str, file: &str, attrs: Vec<(&str, &str)>) -> Annotation {
        let mut attr_map = FxHashMap::default();
        for (k, v) in attrs {
            attr_map.insert(AttrName::from(k), JsonValue::String(v.to_string()));
        }
        Annotation {
            tag: TagName::from(tag),
            attrs: attr_map,
            binding: Binding::from(binding),
            file: RelativePath::from(file),
            children: vec![],
        }
    }

    #[test]
    fn detects_added_annotations() {
        // Arrange
        let baseline = vec![ann("route", "GET /users", "api.ts", vec![])];
        let current = vec![
            ann("route", "GET /users", "api.ts", vec![]),
            ann("route", "POST /users", "api.ts", vec![]),
        ];

        // Act
        let diff = diff_annotations(&baseline, &current);

        // Assert
        assert_eq!(diff.added.len(), 1, "should detect 1 added annotation");
        assert_eq!(diff.added[0].binding, "POST /users", "added binding");
        assert!(diff.removed.is_empty(), "nothing removed");
    }

    #[test]
    fn detects_removed_annotations() {
        // Arrange
        let baseline = vec![
            ann("route", "GET /users", "api.ts", vec![]),
            ann("route", "DELETE /users", "api.ts", vec![]),
        ];
        let current = vec![ann("route", "GET /users", "api.ts", vec![])];

        // Act
        let diff = diff_annotations(&baseline, &current);

        // Assert
        assert_eq!(diff.removed.len(), 1, "should detect 1 removed annotation");
        assert_eq!(diff.removed[0].binding, "DELETE /users", "removed binding");
    }

    #[test]
    fn detects_changed_attributes() {
        // Arrange
        let baseline = vec![ann("route", "GET /users", "api.ts", vec![("auth", "none")])];
        let current = vec![ann(
            "route",
            "GET /users",
            "api.ts",
            vec![("auth", "required")],
        )];

        // Act
        let diff = diff_annotations(&baseline, &current);

        // Assert
        assert!(diff.added.is_empty(), "nothing added");
        assert!(diff.removed.is_empty(), "nothing removed");
        assert_eq!(diff.changed.len(), 1, "should detect 1 changed annotation");
    }

    #[test]
    fn no_diff_on_identical() {
        // Arrange
        let anns = vec![ann(
            "route",
            "GET /users",
            "api.ts",
            vec![("method", "GET")],
        )];

        // Act
        let diff = diff_annotations(&anns, &anns);

        // Assert
        assert!(diff.added.is_empty(), "nothing added");
        assert!(diff.removed.is_empty(), "nothing removed");
        assert!(diff.changed.is_empty(), "nothing changed");
    }
}