kardo_core/git/

coupling.rs

//! Code-documentation coupling detection — finds docs that lag behind their referenced source files.

use super::analysis::GitFileInfo;
use std::collections::HashMap;

/// A detected case where source code changed more recently than its documentation.
#[derive(Debug, Clone)]
pub struct CouplingIssue {
    pub source_path: String,
    pub doc_path: String,
    pub source_last_modified: String,
    pub doc_last_modified: String,
    pub gap_days: i64,
}

/// Detects code-documentation coupling drift from git history.
pub struct CouplingDetector;

impl CouplingDetector {
    /// Detect code-doc coupling issues.
    ///
    /// Given a list of doc files and their referenced code paths,
    /// check if any code file changed more recently than the doc.
    ///
    /// `doc_files`: slice of (doc_path, referenced_code_paths)
    /// `git_infos`: git metadata for all relevant files
    pub fn detect(
        doc_files: &[(String, Vec<String>)],
        git_infos: &[GitFileInfo],
    ) -> Vec<CouplingIssue> {
        let info_map: HashMap<&str, &GitFileInfo> = git_infos
            .iter()
            .map(|info| (info.relative_path.as_str(), info))
            .collect();

        let mut issues = Vec::new();

        for (doc_path, code_paths) in doc_files {
            let doc_info = match info_map.get(doc_path.as_str()) {
                Some(info) => info,
                None => continue,
            };

            let doc_modified = match &doc_info.last_modified {
                Some(dt) => dt,
                None => continue,
            };

            let doc_days = match doc_info.days_since_modified {
                Some(d) => d,
                None => continue,
            };

            for code_path in code_paths {
                let code_info = match info_map.get(code_path.as_str()) {
                    Some(info) => info,
                    None => continue,
                };

                let code_modified = match &code_info.last_modified {
                    Some(dt) => dt,
                    None => continue,
                };

                let code_days = match code_info.days_since_modified {
                    Some(d) => d,
                    None => continue,
                };

                // Code was modified more recently than doc (fewer days since modified)
                if code_days < doc_days {
                    let gap = doc_days - code_days;
                    issues.push(CouplingIssue {
                        source_path: code_path.clone(),
                        doc_path: doc_path.clone(),
                        source_last_modified: code_modified.clone(),
                        doc_last_modified: doc_modified.clone(),
                        gap_days: gap,
                    });
                }
            }
        }

        issues
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use crate::git::analysis::GitAnalyzer;
    use git2::{Repository, Signature};
    use std::fs;
    use std::path::Path;
    use tempfile::TempDir;

    fn commit_file(repo: &Repository, path: &str, content: &str, message: &str) {
        let root = repo.workdir().unwrap();
        let file_path = root.join(path);
        if let Some(parent) = file_path.parent() {
            fs::create_dir_all(parent).unwrap();
        }
        fs::write(&file_path, content).unwrap();

        let mut index = repo.index().unwrap();
        index.add_path(Path::new(path)).unwrap();
        index.write().unwrap();

        let tree_id = index.write_tree().unwrap();
        let tree = repo.find_tree(tree_id).unwrap();
        let sig = Signature::now("Test", "test@test.com").unwrap();

        let parent = repo.head().ok().and_then(|h| h.peel_to_commit().ok());
        let parents: Vec<&git2::Commit> = parent.iter().collect();

        repo.commit(Some("HEAD"), &sig, &sig, message, &tree, &parents)
            .unwrap();
    }

    fn commit_file_with_time(
        repo: &Repository,
        path: &str,
        content: &str,
        message: &str,
        epoch_secs: i64,
    ) {
        let root = repo.workdir().unwrap();
        let file_path = root.join(path);
        if let Some(parent) = file_path.parent() {
            fs::create_dir_all(parent).unwrap();
        }
        fs::write(&file_path, content).unwrap();

        let mut index = repo.index().unwrap();
        index.add_path(Path::new(path)).unwrap();
        index.write().unwrap();

        let tree_id = index.write_tree().unwrap();
        let tree = repo.find_tree(tree_id).unwrap();
        let time = git2::Time::new(epoch_secs, 0);
        let sig = Signature::new("Test", "test@test.com", &time).unwrap();

        let parent = repo.head().ok().and_then(|h| h.peel_to_commit().ok());
        let parents: Vec<&git2::Commit> = parent.iter().collect();

        repo.commit(Some("HEAD"), &sig, &sig, message, &tree, &parents)
            .unwrap();
    }

    #[test]
    fn test_coupling_detection() {
        let dir = TempDir::new().unwrap();
        let repo = Repository::init(dir.path()).unwrap();

        // Doc committed 30 days ago
        let thirty_days_ago = chrono::Utc::now().timestamp() - 30 * 86400;
        commit_file_with_time(
            &repo,
            "docs/api.md",
            "# API docs",
            "Add docs",
            thirty_days_ago,
        );

        // Code committed now (after the doc)
        commit_file(&repo, "src/api.rs", "fn api() {}", "Update api code");

        let analyzer = GitAnalyzer::open(dir.path()).unwrap();
        let infos = analyzer
            .analyze_files(&[
                "docs/api.md".to_string(),
                "src/api.rs".to_string(),
            ])
            .unwrap();

        let doc_files = vec![(
            "docs/api.md".to_string(),
            vec!["src/api.rs".to_string()],
        )];

        let issues = CouplingDetector::detect(&doc_files, &infos);
        assert_eq!(issues.len(), 1);
        assert_eq!(issues[0].source_path, "src/api.rs");
        assert_eq!(issues[0].doc_path, "docs/api.md");
        assert!(issues[0].gap_days > 0);
    }

    #[test]
    fn test_no_coupling_issue() {
        let dir = TempDir::new().unwrap();
        let repo = Repository::init(dir.path()).unwrap();

        // Code committed 30 days ago
        let thirty_days_ago = chrono::Utc::now().timestamp() - 30 * 86400;
        commit_file_with_time(
            &repo,
            "src/api.rs",
            "fn api() {}",
            "Add api code",
            thirty_days_ago,
        );

        // Doc committed now (after the code) — doc is up to date
        commit_file(&repo, "docs/api.md", "# Updated API docs", "Update docs");

        let analyzer = GitAnalyzer::open(dir.path()).unwrap();
        let infos = analyzer
            .analyze_files(&[
                "docs/api.md".to_string(),
                "src/api.rs".to_string(),
            ])
            .unwrap();

        let doc_files = vec![(
            "docs/api.md".to_string(),
            vec!["src/api.rs".to_string()],
        )];

        let issues = CouplingDetector::detect(&doc_files, &infos);
        assert!(issues.is_empty(), "Expected no coupling issues");
    }
}