kardo_core/analysis/

integrity.rs

//! Reference integrity checking: validate internal links and heading references.

use regex::Regex;
use serde::Serialize;
use std::collections::{HashMap, HashSet};
use std::path::Path;

/// A broken reference found during integrity analysis.
#[derive(Debug, Clone, Serialize)]
pub struct BrokenReference {
    /// File that contains the broken reference.
    pub source_file: String,
    /// The link target that could not be resolved.
    pub target: String,
    /// Classification of how the reference is broken.
    pub kind: BrokenRefKind,
}

#[derive(Debug, Clone, Serialize)]
pub enum BrokenRefKind {
    FileNotFound,
    HeadingNotFound,
    /// @filename directive reference (e.g. @AGENTS.md, @.claude/AGENT_FLOW_RULES.md)
    DirectiveReference,
}

/// Aggregate integrity result.
#[derive(Debug, Clone, Serialize)]
pub struct IntegrityResult {
    /// Ratio of valid references to total references (0.0-1.0).
    pub score: f64,
    /// Total number of internal references checked.
    pub total_refs: usize,
    /// Number of references that resolved successfully.
    pub valid_refs: usize,
    /// List of references that could not be resolved.
    pub broken: Vec<BrokenReference>,
}

pub struct IntegrityAnalyzer;

impl IntegrityAnalyzer {
    /// Check internal link integrity.
    ///
    /// `file_links`: map of (source_file_path → vec of link targets found in that file)
    /// `known_files`: set of all known file relative paths in the project
    /// `file_headings`: map of (file_path → vec of heading slugs in that file)
    pub fn analyze(
        file_links: &HashMap<String, Vec<String>>,
        known_files: &HashSet<String>,
        file_headings: &HashMap<String, Vec<String>>,
    ) -> IntegrityResult {
        let mut total_refs: usize = 0;
        let mut valid_refs: usize = 0;
        let mut broken = Vec::new();

        for (source, links) in file_links {
            let source_dir = Path::new(source)
                .parent()
                .map(|p| p.to_string_lossy().to_string())
                .unwrap_or_default();

            for link in links {
                // Skip external links
                if link.starts_with("http://") || link.starts_with("https://") || link.starts_with("mailto:") {
                    continue;
                }

                total_refs += 1;

                // Split link into file part and optional heading fragment
                let (file_part, heading_part) = if let Some(idx) = link.find('#') {
                    let file = &link[..idx];
                    let heading = &link[idx + 1..];
                    (file, if heading.is_empty() { None } else { Some(heading) })
                } else {
                    (link.as_str(), None)
                };

                // Resolve relative path
                let resolved = if file_part.is_empty() {
                    // Self-reference (#heading) — file is the source itself
                    source.clone()
                } else {
                    Self::resolve_path(&source_dir, file_part)
                };

                // Check if file exists
                if !file_part.is_empty() && !known_files.contains(&resolved) {
                    broken.push(BrokenReference {
                        source_file: source.clone(),
                        target: link.clone(),
                        kind: BrokenRefKind::FileNotFound,
                    });
                    continue;
                }

                // Check heading if present
                if let Some(heading) = heading_part {
                    let headings = file_headings.get(&resolved);
                    let heading_exists = headings
                        .map(|hs| hs.iter().any(|h| h == heading))
                        .unwrap_or(false);

                    if heading_exists {
                        valid_refs += 1;
                    } else {
                        broken.push(BrokenReference {
                            source_file: source.clone(),
                            target: link.clone(),
                            kind: BrokenRefKind::HeadingNotFound,
                        });
                    }
                } else {
                    valid_refs += 1;
                }
            }
        }

        // Additional pass: scan config files for @filename directive references
        Self::check_directive_references(
            file_links,
            known_files,
            &mut total_refs,
            &mut valid_refs,
            &mut broken,
        );

        let score = if total_refs == 0 {
            1.0 // No references = no broken references = perfect
        } else {
            valid_refs as f64 / total_refs as f64
        };

        IntegrityResult {
            score,
            total_refs,
            valid_refs,
            broken,
        }
    }

    /// Scan config file contents for @filename directive patterns and validate them.
    ///
    /// Recognizes patterns like: `@AGENTS.md`, `@.claude/AGENT_FLOW_RULES.md`,
    /// `@instructions` (mapped to `.claude/instructions`)
    fn check_directive_references(
        file_links: &HashMap<String, Vec<String>>,
        known_files: &HashSet<String>,
        total_refs: &mut usize,
        valid_refs: &mut usize,
        broken: &mut Vec<BrokenReference>,
    ) {
        // We need the raw file contents to scan for @directives.
        // file_links keys are source files that had links parsed — we use them
        // to identify config files. For now, scan known config files.
        // Note: This is called from analyze() which receives file_links.
        // The caller should provide config file contents separately for full coverage.
        // For backwards compatibility, we scan the link targets for @-prefixed entries.

        // Pattern: @filepath (word boundary before @, filepath has at least one . or /)
        let directive_re = Regex::new(r"@([a-zA-Z0-9_./-]+(?:\.[a-zA-Z]{1,6}|/[a-zA-Z0-9_.-]+))").unwrap();

        for (source, links) in file_links {
            // Look for @-prefixed references in the link targets
            // These may have been extracted as raw text by the parser
            for link in links {
                // Skip external links
                if link.starts_with("http://") || link.starts_with("https://") || link.starts_with("mailto:") {
                    continue;
                }
                if let Some(cap) = directive_re.captures(link) {
                    let target = cap.get(1).unwrap().as_str();
                    *total_refs += 1;

                    if known_files.contains(target) {
                        *valid_refs += 1;
                    } else {
                        broken.push(BrokenReference {
                            source_file: source.clone(),
                            target: format!("@{}", target),
                            kind: BrokenRefKind::DirectiveReference,
                        });
                    }
                }
            }
        }
    }

    /// Analyze directive references found in config file contents.
    ///
    /// Call this with a map of config files (path → content) to validate
    /// @filename directives like `@AGENTS.md` or `@.claude/instructions`.
    pub fn analyze_directives(
        config_contents: &HashMap<String, String>,
        known_files: &HashSet<String>,
    ) -> Vec<BrokenReference> {
        let directive_re = Regex::new(r"@([a-zA-Z0-9_./-]+(?:\.[a-zA-Z]{1,6}|/[a-zA-Z0-9_.-]+))").unwrap();
        let mut broken = Vec::new();

        for (source, content) in config_contents {
            for cap in directive_re.captures_iter(content) {
                let target = cap.get(1).unwrap().as_str();
                if !known_files.contains(target) {
                    broken.push(BrokenReference {
                        source_file: source.clone(),
                        target: format!("@{}", target),
                        kind: BrokenRefKind::DirectiveReference,
                    });
                }
            }
        }

        broken
    }

    /// Resolve a relative path against a base directory.
    fn resolve_path(base_dir: &str, relative: &str) -> String {
        if relative.starts_with('/') {
            // Absolute from project root
            relative.trim_start_matches('/').to_string()
        } else {
            let base = Path::new(base_dir);
            let resolved = base.join(relative);
            // Normalize: remove `.` and `..` components
            let mut parts: Vec<&str> = Vec::new();
            for component in resolved.components() {
                match component {
                    std::path::Component::Normal(s) => {
                        parts.push(s.to_str().unwrap_or(""));
                    }
                    std::path::Component::ParentDir => {
                        parts.pop();
                    }
                    std::path::Component::CurDir => {}
                    _ => {}
                }
            }
            parts.join("/")
        }
    }
}

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

    fn make_known_files(files: &[&str]) -> HashSet<String> {
        files.iter().map(|s| s.to_string()).collect()
    }

    fn make_headings(entries: &[(&str, &[&str])]) -> HashMap<String, Vec<String>> {
        entries
            .iter()
            .map(|(file, headings)| {
                (file.to_string(), headings.iter().map(|h| h.to_string()).collect())
            })
            .collect()
    }

    #[test]
    fn test_all_valid_links() {
        let mut links = HashMap::new();
        links.insert(
            "docs/guide.md".to_string(),
            vec!["../README.md".to_string(), "./api.md".to_string()],
        );

        let files = make_known_files(&["README.md", "docs/guide.md", "docs/api.md"]);
        let headings = HashMap::new();

        let result = IntegrityAnalyzer::analyze(&links, &files, &headings);
        assert_eq!(result.total_refs, 2);
        assert_eq!(result.valid_refs, 2);
        assert!((result.score - 1.0).abs() < 0.01);
        assert!(result.broken.is_empty());
    }

    #[test]
    fn test_broken_file_link() {
        let mut links = HashMap::new();
        links.insert(
            "README.md".to_string(),
            vec!["docs/missing.md".to_string()],
        );

        let files = make_known_files(&["README.md"]);
        let headings = HashMap::new();

        let result = IntegrityAnalyzer::analyze(&links, &files, &headings);
        assert_eq!(result.total_refs, 1);
        assert_eq!(result.valid_refs, 0);
        assert!((result.score - 0.0).abs() < 0.01);
        assert_eq!(result.broken.len(), 1);
        assert!(matches!(result.broken[0].kind, BrokenRefKind::FileNotFound));
    }

    #[test]
    fn test_broken_heading_link() {
        let mut links = HashMap::new();
        links.insert(
            "README.md".to_string(),
            vec!["docs/api.md#nonexistent".to_string()],
        );

        let files = make_known_files(&["README.md", "docs/api.md"]);
        let headings = make_headings(&[("docs/api.md", &["getting-started", "usage"])]);

        let result = IntegrityAnalyzer::analyze(&links, &files, &headings);
        assert_eq!(result.total_refs, 1);
        assert_eq!(result.valid_refs, 0);
        assert_eq!(result.broken.len(), 1);
        assert!(matches!(result.broken[0].kind, BrokenRefKind::HeadingNotFound));
    }

    #[test]
    fn test_valid_heading_link() {
        let mut links = HashMap::new();
        links.insert(
            "README.md".to_string(),
            vec!["docs/api.md#usage".to_string()],
        );

        let files = make_known_files(&["README.md", "docs/api.md"]);
        let headings = make_headings(&[("docs/api.md", &["usage"])]);

        let result = IntegrityAnalyzer::analyze(&links, &files, &headings);
        assert_eq!(result.valid_refs, 1);
        assert!((result.score - 1.0).abs() < 0.01);
    }

    #[test]
    fn test_external_links_skipped() {
        let mut links = HashMap::new();
        links.insert(
            "README.md".to_string(),
            vec![
                "https://example.com".to_string(),
                "http://example.com".to_string(),
                "mailto:test@test.com".to_string(),
            ],
        );

        let files = make_known_files(&["README.md"]);
        let headings = HashMap::new();

        let result = IntegrityAnalyzer::analyze(&links, &files, &headings);
        assert_eq!(result.total_refs, 0); // External links not counted
        assert!((result.score - 1.0).abs() < 0.01);
    }

    #[test]
    fn test_no_links() {
        let links = HashMap::new();
        let files = make_known_files(&["README.md"]);
        let headings = HashMap::new();

        let result = IntegrityAnalyzer::analyze(&links, &files, &headings);
        assert!((result.score - 1.0).abs() < 0.01);
    }

    #[test]
    fn test_at_reference_valid() {
        // Test that @AGENTS.md is validated against known_files
        let mut config = HashMap::new();
        config.insert("CLAUDE.md".to_string(), "@AGENTS.md\n@.claude/instructions".to_string());

        let files = make_known_files(&["CLAUDE.md", "AGENTS.md", ".claude/instructions"]);
        let broken = IntegrityAnalyzer::analyze_directives(&config, &files);
        assert!(broken.is_empty(), "Valid @references should not be broken");
    }

    #[test]
    fn test_at_reference_broken() {
        let mut config = HashMap::new();
        config.insert("CLAUDE.md".to_string(), "@AGENTS.md\n@.claude/missing.md".to_string());

        let files = make_known_files(&["CLAUDE.md", "AGENTS.md"]);
        let broken = IntegrityAnalyzer::analyze_directives(&config, &files);
        assert_eq!(broken.len(), 1);
        assert!(broken[0].target.contains("missing.md"));
        assert!(matches!(broken[0].kind, BrokenRefKind::DirectiveReference));
    }

    #[test]
    fn test_claude_dir_reference_validation() {
        let mut config = HashMap::new();
        config.insert(
            "CLAUDE.md".to_string(),
            "Read @.claude/AGENT_FLOW_RULES.md for details".to_string(),
        );

        let files = make_known_files(&["CLAUDE.md", ".claude/AGENT_FLOW_RULES.md"]);
        let broken = IntegrityAnalyzer::analyze_directives(&config, &files);
        assert!(broken.is_empty());

        // Now without the target file
        let files_without = make_known_files(&["CLAUDE.md"]);
        let broken2 = IntegrityAnalyzer::analyze_directives(&config, &files_without);
        assert_eq!(broken2.len(), 1);
    }

    #[test]
    fn test_mixed_valid_and_broken() {
        let mut links = HashMap::new();
        links.insert(
            "README.md".to_string(),
            vec![
                "docs/api.md".to_string(),     // valid
                "docs/missing.md".to_string(),  // broken
            ],
        );

        let files = make_known_files(&["README.md", "docs/api.md"]);
        let headings = HashMap::new();

        let result = IntegrityAnalyzer::analyze(&links, &files, &headings);
        assert_eq!(result.total_refs, 2);
        assert_eq!(result.valid_refs, 1);
        assert!((result.score - 0.5).abs() < 0.01);
    }
}