kardo_core/analysis/

structure.rs

//! Project structure quality analysis.
//!
//! Evaluates how well a project's file organization supports AI comprehension:
//! directory depth, documentation coverage, naming conventions,
//! standard structure patterns, and organization quality.

use serde::Serialize;
use std::collections::HashMap;
use std::path::Path;

use crate::scanner::DiscoveredFile;

/// Weight constants for each signal group.
const W_DEPTH: f64 = 0.15;
const W_COVERAGE: f64 = 0.25;
const W_NAMING: f64 = 0.20;
const W_STANDARD: f64 = 0.25;
const W_ORGANIZATION: f64 = 0.15;

/// Result of project structure analysis.
#[derive(Debug, Clone, Serialize)]
pub struct StructureResult {
    /// Weighted composite structure quality score (0.0-1.0).
    pub score: f64,
    /// Directory nesting depth quality (ideal average 2-4 levels).
    pub depth_score: f64,
    /// Documentation coverage ratio relative to total files.
    pub coverage_score: f64,
    /// File naming convention consistency (kebab/snake/camel).
    pub naming_score: f64,
    /// Presence of standard project directories (docs/, src/, tests/, .github/).
    pub standard_score: f64,
    /// Organization quality: no dumping grounds, separation of concerns.
    pub organization_score: f64,
}

pub struct StructureAnalyzer;

impl StructureAnalyzer {
    /// Analyze project structure quality.
    pub fn analyze(project_root: &Path, files: &[DiscoveredFile]) -> StructureResult {
        if files.is_empty() {
            return StructureResult {
                score: 0.0,
                depth_score: 0.0,
                coverage_score: 0.0,
                naming_score: 0.0,
                standard_score: 0.0,
                organization_score: 0.0,
            };
        }

        let depth_score = Self::score_depth(files);
        let coverage_score = Self::score_coverage(files);
        let naming_score = Self::score_naming(files);
        let standard_score = Self::score_standard(project_root);
        let organization_score = Self::score_organization(files);

        let score = W_DEPTH * depth_score
            + W_COVERAGE * coverage_score
            + W_NAMING * naming_score
            + W_STANDARD * standard_score
            + W_ORGANIZATION * organization_score;

        StructureResult {
            score,
            depth_score,
            coverage_score,
            naming_score,
            standard_score,
            organization_score,
        }
    }

    /// Score directory depth: ideal average is 2-4.
    fn score_depth(files: &[DiscoveredFile]) -> f64 {
        if files.is_empty() {
            return 0.0;
        }

        let depths: Vec<usize> = files
            .iter()
            .map(|f| f.relative_path.matches('/').count())
            .collect();

        let avg = depths.iter().sum::<usize>() as f64 / depths.len() as f64;

        if (2.0..=4.0).contains(&avg) {
            1.0
        } else if avg < 1.0 {
            0.6 // Very flat
        } else if avg < 2.0 {
            // Interpolate 0.6 → 1.0 as avg goes from 1.0 → 2.0
            0.6 + 0.4 * (avg - 1.0)
        } else if avg <= 6.0 {
            // Interpolate 1.0 → 0.5 as avg goes from 4.0 → 6.0
            1.0 - 0.5 * (avg - 4.0) / 2.0
        } else {
            0.5 // Too deep
        }
    }

    /// Score documentation coverage: ratio of markdown files to total.
    fn score_coverage(files: &[DiscoveredFile]) -> f64 {
        let total = files.len() as f64;
        let md_count = files.iter().filter(|f| f.is_markdown).count() as f64;
        let ratio = md_count / total;
        let pct = ratio * 100.0;

        if (5.0..=15.0).contains(&pct) {
            1.0
        } else if pct < 2.0 {
            0.3
        } else if pct < 5.0 {
            // Interpolate 0.3 → 1.0 as pct goes from 2 → 5
            0.3 + 0.7 * (pct - 2.0) / 3.0
        } else if pct <= 30.0 {
            // Interpolate 1.0 → 0.7 as pct goes from 15 → 30
            1.0 - 0.3 * (pct - 15.0) / 15.0
        } else {
            0.7 // Doc-heavy project
        }
    }

    /// Score naming convention consistency.
    fn score_naming(files: &[DiscoveredFile]) -> f64 {
        let mut kebab = 0usize;
        let mut snake = 0usize;
        let mut camel = 0usize;

        for file in files {
            let name = match file.relative_path.rsplit('/').next() {
                Some(n) => {
                    // Strip extension
                    match n.rfind('.') {
                        Some(idx) => &n[..idx],
                        None => n,
                    }
                }
                None => continue,
            };

            // Skip very short names or names with no casing/separator signal
            if name.len() < 2 {
                continue;
            }

            if name.contains('-') && !name.contains('_') {
                kebab += 1;
            } else if name.contains('_') && !name.contains('-') {
                snake += 1;
            } else if name.chars().any(|c| c.is_uppercase()) && !name.contains('-') && !name.contains('_') {
                camel += 1;
            }
            // else: single word or ambiguous — skip
        }

        let total_classified = kebab + snake + camel;
        if total_classified == 0 {
            return 0.8; // All single-word: consistent enough
        }

        let counts = [kebab, snake, camel];
        let dominant = *counts.iter().max().unwrap_or(&0);
        let consistency = dominant as f64 / total_classified as f64;

        if consistency >= 0.8 {
            1.0
        } else if consistency >= 0.6 {
            0.7
        } else {
            0.5
        }
    }

    /// Score standard project structure patterns.
    fn score_standard(root: &Path) -> f64 {
        let mut score = 0.0;

        // Has docs/ or doc/ directory
        if root.join("docs").is_dir() || root.join("doc").is_dir() {
            score += 0.3;
        }

        // Has src/ or lib/ directory
        if root.join("src").is_dir() || root.join("lib").is_dir() {
            score += 0.2;
        }

        // Has tests/ or test/ or __tests__/
        if root.join("tests").is_dir() || root.join("test").is_dir() || root.join("__tests__").is_dir() {
            score += 0.2;
        }

        // Has .github/ or .gitlab-ci.yml
        if root.join(".github").is_dir() || root.join(".gitlab-ci.yml").exists() {
            score += 0.15;
        }

        // Has README.md in root
        if root.join("README.md").exists() {
            score += 0.15;
        }

        score
    }

    /// Score organization quality: no dumping ground dirs, separation of concerns.
    fn score_organization(files: &[DiscoveredFile]) -> f64 {
        // Count files per directory
        let mut dir_counts: HashMap<String, usize> = HashMap::new();

        for file in files {
            let dir = match file.relative_path.rfind('/') {
                Some(idx) => file.relative_path[..idx].to_string(),
                None => ".".to_string(), // root
            };
            *dir_counts.entry(dir).or_insert(0) += 1;
        }

        // No dumping ground: no directory with >50 files
        let has_dumping_ground = dir_counts.values().any(|&count| count > 50);
        let dump_score = if has_dumping_ground { 0.0 } else { 0.5 };

        // Separation of concerns: docs are in separate dir from source
        let has_doc_separation = dir_counts.keys().any(|k| {
            k == "docs" || k == "doc" || k.starts_with("docs/") || k.starts_with("doc/")
        });
        let has_src_separation = dir_counts.keys().any(|k| {
            k == "src" || k == "lib" || k.starts_with("src/") || k.starts_with("lib/")
        });
        let separation_score = if has_doc_separation && has_src_separation {
            0.5
        } else if has_doc_separation || has_src_separation {
            0.3
        } else {
            0.0
        };

        dump_score + separation_score
    }
}

#[cfg(test)]
mod tests {
    use super::*;
    use chrono::Utc;
    use std::path::PathBuf;

    fn make_file(relative_path: &str) -> DiscoveredFile {
        let is_markdown = relative_path.ends_with(".md");
        DiscoveredFile {
            path: PathBuf::from(relative_path),
            relative_path: relative_path.to_string(),
            size: 100,
            modified_at: Some(Utc::now()),
            extension: relative_path.rsplit('.').next().map(|s| s.to_string()),
            is_markdown,
            content_hash: String::new(),
        }
    }

    fn make_files(paths: &[&str]) -> Vec<DiscoveredFile> {
        paths.iter().map(|p| make_file(p)).collect()
    }

    #[test]
    fn test_well_structured_project() {
        let dir = tempfile::TempDir::new().unwrap();
        let root = dir.path();

        // Create standard dirs
        std::fs::create_dir_all(root.join("docs")).unwrap();
        std::fs::create_dir_all(root.join("src/components")).unwrap();
        std::fs::create_dir_all(root.join("tests")).unwrap();
        std::fs::create_dir_all(root.join(".github")).unwrap();
        std::fs::write(root.join("README.md"), "# Project").unwrap();

        let files = make_files(&[
            "README.md",
            "docs/api.md",
            "docs/setup.md",
            "src/main.rs",
            "src/lib.rs",
            "src/components/button.rs",
            "src/components/input.rs",
            "tests/test_main.rs",
            "tests/test_lib.rs",
            "Cargo.toml",
        ]);

        let result = StructureAnalyzer::analyze(root, &files);
        assert!(
            result.score > 0.6,
            "Well-structured project should score > 0.6, got {}",
            result.score
        );
        assert!(
            (result.standard_score - 1.0).abs() < 0.01,
            "All standard dirs present → standard_score = 1.0, got {}",
            result.standard_score
        );
    }

    #[test]
    fn test_flat_project() {
        let dir = tempfile::TempDir::new().unwrap();
        let root = dir.path();

        let files = make_files(&[
            "main.py",
            "utils.py",
            "config.py",
            "test.py",
            "README.md",
        ]);

        let result = StructureAnalyzer::analyze(root, &files);
        assert!(
            result.depth_score <= 0.6,
            "Flat project should have low depth score, got {}",
            result.depth_score
        );
    }

    #[test]
    fn test_no_markdown_low_coverage() {
        let dir = tempfile::TempDir::new().unwrap();
        let root = dir.path();

        let files = make_files(&[
            "src/main.rs",
            "src/lib.rs",
            "src/utils.rs",
            "src/config.rs",
            "src/models.rs",
        ]);

        let result = StructureAnalyzer::analyze(root, &files);
        assert!(
            result.coverage_score <= 0.3,
            "No markdown → coverage_score should be 0.3, got {}",
            result.coverage_score
        );
    }

    #[test]
    fn test_consistent_naming() {
        let dir = tempfile::TempDir::new().unwrap();
        let root = dir.path();

        let files = make_files(&[
            "src/my-component.ts",
            "src/my-utils.ts",
            "src/my-config.ts",
            "src/main-app.ts",
            "src/test-runner.ts",
        ]);

        let result = StructureAnalyzer::analyze(root, &files);
        assert!(
            result.naming_score >= 1.0,
            "All kebab-case → naming_score should be 1.0, got {}",
            result.naming_score
        );
    }

    #[test]
    fn test_dumping_ground_low_organization() {
        let dir = tempfile::TempDir::new().unwrap();
        let root = dir.path();

        // Create 51+ files in a single directory (via DiscoveredFile paths)
        let mut paths: Vec<String> = (0..55)
            .map(|i| format!("src/file_{}.rs", i))
            .collect();
        paths.push("README.md".to_string());
        let path_refs: Vec<&str> = paths.iter().map(|s| s.as_str()).collect();
        let files = make_files(&path_refs);

        let result = StructureAnalyzer::analyze(root, &files);
        assert!(
            result.organization_score < 0.5,
            "Dumping ground dir → low organization score, got {}",
            result.organization_score
        );
    }

    #[test]
    fn test_empty_project() {
        let dir = tempfile::TempDir::new().unwrap();
        let result = StructureAnalyzer::analyze(dir.path(), &[]);
        assert!(
            result.score < 0.01,
            "Empty project should have 0 score, got {}",
            result.score
        );
    }

    #[test]
    fn test_mixed_naming_low_score() {
        let dir = tempfile::TempDir::new().unwrap();
        let root = dir.path();

        let files = make_files(&[
            "src/my-component.ts",
            "src/my_utils.ts",
            "src/MyConfig.ts",
            "src/main-app.ts",
            "src/test_runner.ts",
            "src/AnotherFile.ts",
        ]);

        let result = StructureAnalyzer::analyze(root, &files);
        assert!(
            result.naming_score <= 0.7,
            "Mixed naming should score low, got {}",
            result.naming_score
        );
    }
}