amql_engine/

repair.rs

//! Detect broken annotation bindings and suggest repairs.
//!
//! Basic repair heuristics:
//! - Detect bindings that are similar to other known binding names
//! - Suggest similar bindings based on Levenshtein edit distance

#[cfg(all(feature = "resolver", feature = "fs"))]
use crate::code_cache::CodeCache;
#[cfg(feature = "resolver")]
use crate::resolver::CodeElement;
use crate::store::AnnotationStore;
#[cfg(feature = "resolver")]
use crate::types::Scope;
use crate::types::{Binding, RelativePath};
use rustc_hash::FxHashSet;
use serde::Serialize;

/// A suggested fix for a broken annotation binding.
#[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 RepairSuggestion {
    /// Sidecar file path containing the broken binding.
    pub file: RelativePath,
    /// The original (potentially broken) binding value.
    pub binding: Binding,
    /// The suggested corrected binding.
    pub suggestion: Binding,
    /// Similarity score between 0.0 and 1.0.
    pub confidence: f64,
    /// Human-readable explanation of why this repair was suggested.
    pub reason: String,
}

/// Find annotations with bindings that look potentially broken
/// and suggest repairs based on other annotations and code element names.
/// If `code_cache` is provided, code element names are included in the known names set.
#[cfg(all(feature = "resolver", feature = "fs"))]
#[must_use]
pub fn suggest_repairs(
    store: &AnnotationStore,
    code_cache: Option<&CodeCache>,
) -> Vec<RepairSuggestion> {
    let mut known_names: FxHashSet<Binding> = collect_annotation_names(store);

    if let Some(cache) = code_cache {
        for (_rel, element) in cache.elements_in_scope(&Scope::from("")) {
            known_names.extend(collect_code_names(element));
        }
    }

    find_similar_bindings(store, &known_names)
}

/// Find annotations with bindings that look potentially broken (no code cache variant).
#[cfg(not(all(feature = "resolver", feature = "fs")))]
#[must_use]
pub fn suggest_repairs(store: &AnnotationStore) -> Vec<RepairSuggestion> {
    suggest_repairs_from_annotations(store)
}

/// Suggest repairs using only annotation data (no code cache).
///
/// Always available regardless of feature flags. Use this from contexts
/// where the code cache is unavailable (e.g. WASM).
#[must_use]
pub fn suggest_repairs_from_annotations(store: &AnnotationStore) -> Vec<RepairSuggestion> {
    let known_names = collect_annotation_names(store);
    find_similar_bindings(store, &known_names)
}

fn collect_annotation_names(store: &AnnotationStore) -> FxHashSet<Binding> {
    let mut known_names: FxHashSet<Binding> = FxHashSet::default();
    for file in store.annotated_files() {
        for ann in store.get_file_annotations(&file) {
            if !ann.binding.is_empty() {
                known_names.insert(ann.binding.clone());
            }
        }
    }
    known_names
}

fn find_similar_bindings(
    store: &AnnotationStore,
    known_names: &FxHashSet<Binding>,
) -> Vec<RepairSuggestion> {
    let mut suggestions = Vec::new();
    let known_names_vec: Vec<&Binding> = known_names.iter().collect();

    for file in store.annotated_files() {
        for ann in store.get_file_annotations(&file) {
            if ann.binding.is_empty() {
                continue;
            }
            let name = &ann.binding;

            for known in &known_names_vec {
                if *known == name {
                    continue;
                }
                let dist = levenshtein(name, known);
                let max_len = name.len().max(known.len());
                if max_len == 0 {
                    continue;
                }
                let similarity = 1.0 - (dist as f64 / max_len as f64);

                if (0.7..1.0).contains(&similarity) {
                    suggestions.push(RepairSuggestion {
                        file: store.locator().sidecar_for(&file),
                        binding: ann.binding.clone(),
                        suggestion: (*known).clone(),
                        confidence: similarity,
                        reason: format!(
                            "Binding '{}' is similar to '{}' ({}% similar)",
                            name,
                            known,
                            (similarity * 100.0).round() as u32
                        ),
                    });
                }
            }
        }
    }

    suggestions
}

/// Recursively collect code element names from a tree.
#[cfg(feature = "resolver")]
fn collect_code_names(element: &CodeElement) -> Vec<Binding> {
    let mut out = Vec::new();
    if !element.name.is_empty() {
        out.push(Binding::from(element.name.as_ref()));
    }
    for child in &element.children {
        out.extend(collect_code_names(child));
    }
    out
}

/// Levenshtein edit distance between two strings.
/// Uses two-row optimization: O(n) memory instead of O(m×n).
fn levenshtein(a: &str, b: &str) -> usize {
    let m = a.len();
    let n = b.len();
    let a_bytes = a.as_bytes();
    let b_bytes = b.as_bytes();

    if m == 0 {
        return n;
    }
    if n == 0 {
        return m;
    }

    let mut prev = vec![0usize; n + 1];
    let mut curr = vec![0usize; n + 1];

    for (j, val) in prev.iter_mut().enumerate().take(n + 1) {
        *val = j;
    }

    for i in 1..=m {
        curr[0] = i;
        for j in 1..=n {
            curr[j] = if a_bytes[i - 1] == b_bytes[j - 1] {
                prev[j - 1]
            } else {
                1 + prev[j].min(curr[j - 1]).min(prev[j - 1])
            };
        }
        std::mem::swap(&mut prev, &mut curr);
    }

    prev[n]
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::store::{Annotation, AnnotationStore};
    use crate::types::{Binding, RelativePath, TagName};
    use rustc_hash::FxHashMap;
    use std::path::Path;

    /// Helper: build a minimal `Annotation` with just a binding.
    fn ann(binding: &str, file: &str) -> Annotation {
        Annotation {
            tag: TagName::from("function"),
            attrs: FxHashMap::default(),
            binding: Binding::from(binding),
            file: RelativePath::from(file),
            children: vec![],
        }
    }

    #[test]
    fn levenshtein_distance() {
        // Arrange
        let cases: &[(&str, &str, usize)] = &[
            ("hello", "hello", 0), // identical strings
            ("hello", "helo", 1),  // one deletion
            ("abc", "xyz", 3),     // completely different
        ];

        // Act + Assert
        for &(a, b, expected) in cases {
            assert_eq!(
                levenshtein(a, b),
                expected,
                "levenshtein(\"{a}\", \"{b}\") should be {expected}"
            );
        }
    }

    #[test]
    fn suggest_repairs_test() {
        // Arrange — similar bindings that should produce a suggestion
        let mut store_similar = AnnotationStore::new(Path::new("/project"));
        store_similar.inject_test_data(
            &RelativePath::from("src/a.rs"),
            vec![ann("parse_selector", "src/a.rs")],
        );
        store_similar.inject_test_data(
            &RelativePath::from("src/b.rs"),
            vec![ann("parse_selectr", "src/b.rs")],
        );

        // Arrange — identical bindings (no suggestion expected)
        let mut store_identical = AnnotationStore::new(Path::new("/project"));
        store_identical.inject_test_data(
            &RelativePath::from("src/a.rs"),
            vec![ann("parse_selector", "src/a.rs")],
        );
        store_identical.inject_test_data(
            &RelativePath::from("src/b.rs"),
            vec![ann("parse_selector", "src/b.rs")],
        );

        // Arrange — distant bindings (no suggestion expected)
        let mut store_distant = AnnotationStore::new(Path::new("/project"));
        store_distant.inject_test_data(
            &RelativePath::from("src/a.rs"),
            vec![ann("foo", "src/a.rs")],
        );
        store_distant.inject_test_data(
            &RelativePath::from("src/b.rs"),
            vec![ann("bar_baz_qux", "src/b.rs")],
        );

        // Arrange — empty binding (no suggestion expected)
        let mut store_empty = AnnotationStore::new(Path::new("/project"));
        store_empty.inject_test_data(&RelativePath::from("src/a.rs"), vec![ann("", "src/a.rs")]);

        // Act
        let similar = super::suggest_repairs(&store_similar, None);
        let identical = super::suggest_repairs(&store_identical, None);
        let distant = super::suggest_repairs(&store_distant, None);
        let empty = super::suggest_repairs(&store_empty, None);

        // Assert
        assert!(
            !similar.is_empty(),
            "expected at least one repair suggestion for similar bindings"
        );
        let has_expected = similar.iter().any(|s| {
            (s.binding == "parse_selectr" && s.suggestion == "parse_selector")
                || (s.binding == "parse_selector" && s.suggestion == "parse_selectr")
        });
        assert!(
            has_expected,
            "expected a suggestion pairing parse_selectr and parse_selector, got: {similar:?}"
        );

        assert!(
            identical.is_empty(),
            "identical bindings should not produce suggestions, got: {identical:?}"
        );
        assert!(
            distant.is_empty(),
            "very different bindings should not produce suggestions, got: {distant:?}"
        );
        assert!(
            empty.is_empty(),
            "empty bindings should not produce suggestions, got: {empty:?}"
        );
    }

    #[test]
    fn suggest_repairs_with_code_cache() {
        use crate::code_cache::CodeCache;
        use crate::resolver::{CodeElement, SourceLocation};

        // Arrange — annotation binding similar to a code element name
        let mut store = AnnotationStore::new(Path::new("/project"));
        store.inject_test_data(
            &RelativePath::from("src/a.rs"),
            vec![ann("parse_selectr", "src/a.rs")],
        );

        let mut cache = CodeCache::new(Path::new("/project"));
        cache.inject_test_data(
            "src/selector.rs",
            CodeElement {
                tag: crate::types::TagName::from("module"),
                name: crate::types::CodeElementName::from("selector.rs"),
                attrs: rustc_hash::FxHashMap::default(),
                children: vec![CodeElement {
                    tag: crate::types::TagName::from("function"),
                    name: crate::types::CodeElementName::from("parse_selector"),
                    attrs: rustc_hash::FxHashMap::default(),
                    children: vec![],
                    source: SourceLocation {
                        file: RelativePath::from("src/selector.rs"),
                        line: 1,
                        column: 0,
                        end_line: None,
                        end_column: None,
                        start_byte: 0,
                        end_byte: 0,
                    },
                }],
                source: SourceLocation {
                    file: RelativePath::from("src/selector.rs"),
                    line: 1,
                    column: 0,
                    end_line: None,
                    end_column: None,
                    start_byte: 0,
                    end_byte: 0,
                },
            },
        );

        // Act
        let suggestions = super::suggest_repairs(&store, Some(&cache));

        // Assert
        let has_expected = suggestions
            .iter()
            .any(|s| s.binding == "parse_selectr" && s.suggestion == "parse_selector");
        assert!(
            has_expected,
            "expected a suggestion pairing parse_selectr with code element parse_selector, got: {suggestions:?}"
        );
    }
}