amql_engine/

coverage.rs

//! Per-file annotation coverage analysis and sanity checks.
//!
//! Functions here cross-reference annotation data with the source file
//! system and code element caches to produce coverage reports, binding
//! spot-checks, and per-file summaries.

use crate::code_cache::{glob_source_files, CodeCache};
use crate::error::AqlError;
use crate::resolver::ResolverRegistry;
use crate::store::AnnotationStore;
use crate::types::{Binding, ProjectRoot, RelativePath, Scope, TagName};
use rustc_hash::{FxHashMap, FxHashSet};
use serde::Serialize;

/// Per-file annotation coverage entry.
#[non_exhaustive]
#[derive(Debug, Clone, Serialize)]
pub struct FileCoverage {
    /// Relative source file path.
    pub file: RelativePath,
    /// Whether a code resolver exists for this file's extension.
    pub has_resolver: bool,
    /// Number of annotations targeting this file.
    pub annotation_count: usize,
    /// True if at least one annotation exists for this file.
    pub covered: bool,
}

/// Result of spot-checking annotation bindings against code elements.
#[non_exhaustive]
#[derive(Debug, Clone, Serialize)]
pub struct SpotCheckResult {
    /// Number of bindings checked.
    pub checked: usize,
    /// Number that matched a code element.
    pub passed: usize,
    /// Number that did not match any code element.
    pub failed: usize,
    /// Details of each failure.
    pub failures: Vec<SpotCheckFailure>,
}

/// A single binding that failed the spot check.
#[non_exhaustive]
#[derive(Debug, Clone, Serialize)]
pub struct SpotCheckFailure {
    /// Source file the annotation targets.
    pub file: RelativePath,
    /// The binding value that did not match.
    pub binding: Binding,
    /// Human-readable reason for the failure.
    pub reason: String,
}

/// Per-file coverage for a specific set of files (diff-aware).
#[non_exhaustive]
#[derive(Debug, Clone, Serialize)]
pub struct FileDiffCoverage {
    /// Relative source file path.
    pub file: RelativePath,
    /// Total annotation count for this file.
    pub annotation_count: usize,
    /// Annotation count per tag.
    pub tags: FxHashMap<TagName, usize>,
    /// True if at least one annotation exists.
    pub covered: bool,
    /// Source file size in bytes (0 if file not found).
    pub source_bytes: usize,
}

/// Detailed single-file annotation summary.
#[non_exhaustive]
#[derive(Debug, Clone, Serialize)]
pub struct FileSummary {
    /// Relative source file path.
    pub file: RelativePath,
    /// Bindings grouped by tag.
    pub tags: FxHashMap<TagName, Vec<Binding>>,
    /// Total annotation count.
    pub annotation_count: usize,
    /// Source file size in bytes.
    pub source_bytes: usize,
    /// Serialized annotation size in bytes.
    pub annotation_bytes: usize,
    /// Compression ratio: annotation_bytes / source_bytes (None if source_bytes == 0).
    pub compression: Option<f64>,
    /// Whether a code resolver exists for this file.
    pub has_resolver: bool,
    /// Whether the sidecar is stale on disk.
    pub stale: bool,
}

/// Per-file annotation coverage report.
///
/// Iterates all source files within `scope`, cross-references with the
/// annotation store, and reports coverage per file.
pub fn file_coverage(
    root: &ProjectRoot,
    store: &AnnotationStore,
    resolvers: &ResolverRegistry,
    scope: &Scope,
) -> Vec<FileCoverage> {
    let source_files = glob_source_files(root, scope, resolvers);
    let annotated: FxHashSet<RelativePath> = store.annotated_files().into_iter().collect();

    let mut results: Vec<FileCoverage> = source_files
        .into_iter()
        .map(|abs_path| {
            let rel = crate::paths::relative(root, &abs_path);
            let has_resolver = resolvers.has_resolver_for(&abs_path);
            let anns = store.get_file_annotations(&rel);
            let annotation_count = anns.len();
            let covered = annotated.contains(&*rel);
            FileCoverage {
                file: rel,
                has_resolver,
                annotation_count,
                covered,
            }
        })
        .collect();

    results.sort_by(|a, b| a.file.cmp(&b.file));
    results
}

/// Spot-check annotation bindings against parsed code elements.
///
/// Collects all annotations in `scope`, sorts deterministically by
/// (file, binding), takes the first `n`, and verifies each binding
/// matches a code element name in the same file.
pub fn spot_check_bindings(
    store: &AnnotationStore,
    code_cache: &CodeCache,
    scope: &Scope,
    n: usize,
) -> SpotCheckResult {
    let annotations = store.annotations_in_scope(scope);

    // Flatten to (file, binding) pairs, sorted deterministically
    let mut pairs: Vec<(RelativePath, Binding)> = Vec::new();
    for (file, anns) in &annotations {
        for ann in anns {
            if !ann.binding.is_empty() {
                pairs.push(((*file).clone(), ann.binding.clone()));
            }
        }
    }
    pairs.sort_by(|a, b| (&a.0, &a.1).cmp(&(&b.0, &b.1)));
    pairs.dedup();
    pairs.truncate(n);

    let mut passed = 0usize;
    let mut failures = Vec::new();

    for (file, binding) in &pairs {
        let code = code_cache.get(file);
        let found = match code {
            Some(root) => has_code_name(root, binding),
            None => {
                failures.push(SpotCheckFailure {
                    file: file.clone(),
                    binding: binding.clone(),
                    reason: "file not in code cache (not parsed)".to_string(),
                });
                continue;
            }
        };
        if found {
            passed += 1;
        } else {
            failures.push(SpotCheckFailure {
                file: file.clone(),
                binding: binding.clone(),
                reason: "no code element with matching name".to_string(),
            });
        }
    }

    let checked = pairs.len();
    SpotCheckResult {
        checked,
        passed,
        failed: failures.len(),
        failures,
    }
}

/// Check if any code element in the tree has a name matching `binding`.
fn has_code_name(element: &crate::resolver::CodeElement, binding: &str) -> bool {
    if element.name.as_ref() == binding {
        return true;
    }
    element.children.iter().any(|c| has_code_name(c, binding))
}

/// Annotation coverage for a specific set of files (diff-aware).
///
/// For each requested file, counts annotations by tag and checks
/// resolver availability.
pub fn diff_file_coverage(
    store: &AnnotationStore,
    root: &ProjectRoot,
    files: &[RelativePath],
) -> Vec<FileDiffCoverage> {
    files
        .iter()
        .map(|file| {
            let anns = store.get_file_annotations(file);
            let annotation_count = anns.len();

            let mut tags: FxHashMap<TagName, usize> = FxHashMap::default();
            for ann in &anns {
                *tags.entry(ann.tag.clone()).or_insert(0) += 1;
            }

            let abs_path = root.join(AsRef::<std::path::Path>::as_ref(file));
            let source_bytes = std::fs::metadata(&abs_path)
                .map(|m| m.len() as usize)
                .unwrap_or(0);

            FileDiffCoverage {
                file: file.clone(),
                annotation_count,
                tags,
                covered: annotation_count > 0,
                source_bytes,
            }
        })
        .collect()
}

/// Detailed single-file annotation summary.
///
/// Groups annotations by tag with their bindings, computes sizes,
/// and checks staleness.
pub fn file_summary(
    store: &AnnotationStore,
    resolvers: &ResolverRegistry,
    root: &ProjectRoot,
    file: &RelativePath,
) -> Result<FileSummary, AqlError> {
    let anns = store.get_file_annotations(file);

    let mut tags: FxHashMap<TagName, Vec<Binding>> = FxHashMap::default();
    for ann in &anns {
        tags.entry(ann.tag.clone())
            .or_default()
            .push(ann.binding.clone());
    }

    let annotation_count = anns.len();

    let abs_path = root.join(AsRef::<std::path::Path>::as_ref(file));
    let source_bytes = std::fs::metadata(&abs_path)
        .map(|m| m.len() as usize)
        .unwrap_or(0);

    let annotation_bytes = serde_json::to_string(&anns).map(|s| s.len()).unwrap_or(0);

    let compression = if source_bytes > 0 {
        Some(annotation_bytes as f64 / source_bytes as f64)
    } else {
        None
    };

    let has_resolver = resolvers.has_resolver_for(&abs_path);
    let stale = store.is_stale(file);

    Ok(FileSummary {
        file: file.clone(),
        tags,
        annotation_count,
        source_bytes,
        annotation_bytes,
        compression,
        has_resolver,
        stale,
    })
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::store::Annotation;
    use std::path::Path;

    fn test_store() -> AnnotationStore {
        let mut store = AnnotationStore::new(Path::new("/tmp/test-project"));
        store.inject_test_data(
            &RelativePath::from("src/api.ts"),
            vec![Annotation {
                tag: TagName::from("route"),
                attrs: FxHashMap::default(),
                binding: Binding::from("getUser"),
                file: RelativePath::from("src/api.ts"),
                children: vec![],
            }],
        );
        store
    }

    #[test]
    fn spot_check_reports_missing_code() {
        // Arrange
        let store = test_store();
        let code_cache = CodeCache::new(Path::new("/tmp/test-project"));

        // Act
        let result = spot_check_bindings(&store, &code_cache, &Scope::from(""), 100);

        // Assert
        assert_eq!(result.checked, 1, "should check one binding");
        assert_eq!(result.failed, 1, "should fail — file not parsed");
        assert_eq!(
            result.failures[0].binding, "getUser",
            "failure should name the binding"
        );
    }

    #[test]
    fn diff_coverage_counts_tags() {
        // Arrange
        let mut store = AnnotationStore::new(Path::new("/tmp/test-project"));
        store.inject_test_data(
            &RelativePath::from("src/api.ts"),
            vec![
                Annotation {
                    tag: TagName::from("route"),
                    attrs: FxHashMap::default(),
                    binding: Binding::from("a"),
                    file: RelativePath::from("src/api.ts"),
                    children: vec![],
                },
                Annotation {
                    tag: TagName::from("route"),
                    attrs: FxHashMap::default(),
                    binding: Binding::from("b"),
                    file: RelativePath::from("src/api.ts"),
                    children: vec![],
                },
                Annotation {
                    tag: TagName::from("middleware"),
                    attrs: FxHashMap::default(),
                    binding: Binding::from("c"),
                    file: RelativePath::from("src/api.ts"),
                    children: vec![],
                },
            ],
        );
        let root = ProjectRoot::from(Path::new("/tmp/test-project"));

        // Act
        let results = diff_file_coverage(&store, &root, &[RelativePath::from("src/api.ts")]);

        // Assert
        assert_eq!(results.len(), 1, "should have one file result");
        assert_eq!(
            results[0].annotation_count, 3,
            "should count all annotations"
        );
        assert_eq!(
            results[0].tags.get(&TagName::from("route")),
            Some(&2),
            "route tag should have count 2"
        );
        assert_eq!(
            results[0].tags.get(&TagName::from("middleware")),
            Some(&1),
            "middleware tag should have count 1"
        );
        assert!(results[0].covered, "file should be covered");
    }
}