churnloom 0.1.0

Fast codebase health reports woven from churn, LOC, structure, and Cargo ownership
Documentation
//! Codebase-health analysis for command-line and programmatic use.
//!
//! [`analyze`] returns the same structured report used by the `churnloom` CLI
//! without writing to standard output.
//!
//! ```no_run
//! use churnloom::{AnalysisOptions, analyze};
//!
//! # fn main() -> anyhow::Result<()> {
//! let mut options = AnalysisOptions::new(".");
//! options.long_days = 90;
//! let report = analyze(&options)?;
//! println!("{} files", report.summary.files);
//! # Ok(())
//! # }
//! ```

#![deny(missing_docs)]

/// Command-line argument types.
pub mod cli;

mod cargo_context;
mod churn;
mod discovery;
/// Structured analysis report types.
pub mod model;
mod options;
mod output;
mod rust_tests;
mod score;
mod structure;

use std::{
    collections::{BTreeMap, HashMap, HashSet},
    fs,
    path::{Path, PathBuf},
};

use anyhow::{Context, Result, bail};
use rayon::prelude::*;

use crate::{
    cargo_context::CargoContext,
    churn::{FileChurn, GitHistory},
    cli::{Cli, OutputFormat},
    discovery::{SourceFile, discover_sources, slash_path},
    model::{
        AnalysisReport, Churn, CrateSummary, FileMetrics, LanguageSummary, LineStats,
        ProjectSummary, SourceKind, ThroughputSummary,
    },
};

pub use options::AnalysisOptions;

/// Analyze a project and print the selected report format.
///
/// # Errors
///
/// Returns an error when the path/options are invalid, analysis cannot read the
/// project, or JSON serialization fails.
pub fn run(cli: &Cli) -> Result<()> {
    if cli.short_days > cli.long_days {
        bail!("--short-days cannot exceed --long-days");
    }
    let report = analyze(&AnalysisOptions::from(cli))?;
    match cli.format {
        OutputFormat::Text => output::print_text(&report, cli.top, cli.show_daily),
        OutputFormat::Json => output::print_json(&report, cli.json_top)?,
    }
    Ok(())
}

/// Analyze a project without writing output.
///
/// # Errors
///
/// Returns an error when the project path is invalid or source discovery/read fails.
/// Cargo and Git failures are retained as report warnings so LOC analysis can continue.
pub fn analyze(options: &AnalysisOptions) -> Result<AnalysisReport> {
    if options.jobs == 0 {
        bail!("jobs must be a positive integer");
    }
    if options.short_days == 0 || options.long_days == 0 {
        bail!("churn windows must contain at least one day");
    }
    if options.short_days > options.long_days {
        bail!("short churn window cannot exceed long churn window");
    }
    let pool = rayon::ThreadPoolBuilder::new()
        .num_threads(options.jobs)
        .build()
        .context("failed to create analysis worker pool")?;
    pool.install(|| analyze_in_pool(options))
}

fn analyze_in_pool(options: &AnalysisOptions) -> Result<AnalysisReport> {
    let project_root = resolve_project_root(&options.path)?;
    let git_root = churn::find_git_root(&project_root);
    let mut warnings = Vec::new();
    let cargo = if options.no_cargo {
        CargoContext::default()
    } else {
        match CargoContext::discover(&project_root) {
            Ok(context) => context,
            Err(error) => {
                warnings.push(format!("Cargo workspace discovery skipped: {error:#}"));
                CargoContext::default()
            }
        }
    };
    let sources = discover_sources(
        &project_root,
        options.all_files,
        options.include_generated,
        &options.exclude,
        &options.extensions,
        &options.include_prefix,
        &options.exclude_prefix,
    )?;
    let mut files = analyze_files(sources, &cargo)?;
    let history = collect_history(
        git_root.as_deref(),
        &project_root,
        &files,
        &options.extensions,
        options.short_days,
        options.long_days,
        &mut warnings,
    );
    apply_churn(
        &mut files,
        git_root.as_deref(),
        &project_root,
        &history.files,
    );
    score::assign_hotspot_scores(&mut files);

    let languages = summarize_languages(&files);
    let crates = summarize_crates(&files, &cargo);
    let summary = summarize_project(&files, crates.len());
    Ok(AnalysisReport {
        schema_version: 1,
        project_root: project_root.display().to_string(),
        git_root: git_root.map(|root| root.display().to_string()),
        short_days: options.short_days,
        long_days: options.long_days,
        summary,
        throughput_short: history.short,
        throughput_long: history.long,
        daily_long: history.daily_long,
        languages,
        crates,
        files,
        warnings,
    })
}

fn resolve_project_root(path: &Path) -> Result<PathBuf> {
    let root = path
        .canonicalize()
        .with_context(|| format!("cannot access project path {}", path.display()))?;
    if !root.is_dir() {
        bail!("project path is not a directory: {}", root.display());
    }
    Ok(root)
}

fn analyze_files(sources: Vec<SourceFile>, cargo: &CargoContext) -> Result<Vec<FileMetrics>> {
    sources
        .into_par_iter()
        .map(|source| {
            let bytes = fs::read(&source.absolute_path)
                .with_context(|| format!("failed to read {}", source.absolute_path.display()))?;
            let text = String::from_utf8_lossy(&bytes);
            let (crate_name, kind) = cargo.classify(&source.absolute_path);
            let extension = source
                .absolute_path
                .extension()
                .and_then(|value| value.to_str());
            let inline_test_lines = if extension == Some("rs") && kind == SourceKind::Production {
                rust_tests::inline_test_lines(&text)
            } else {
                LineStats::default()
            };
            Ok(FileMetrics {
                path: source.relative_path,
                language: source.language,
                crate_name,
                kind,
                lines: source.lines,
                inline_test_lines,
                churn_short: Churn::default(),
                churn_long: Churn::default(),
                structure: structure::analyze(&text, source.lines.code, extension),
                hotspot_score: 0.0,
            })
        })
        .collect()
}

fn collect_history(
    git_root: Option<&Path>,
    project_root: &Path,
    files: &[FileMetrics],
    extensions: &[String],
    short_days: u32,
    long_days: u32,
    warnings: &mut Vec<String>,
) -> GitHistory {
    let Some(git_root) = git_root else {
        warnings.push("No Git repository found; churn metrics are zero".to_string());
        return empty_history(short_days, long_days);
    };
    let eligible = files
        .iter()
        .map(|file| git_relative_path(git_root, project_root, &file.path))
        .collect::<HashSet<_>>();
    let pathspecs = history_pathspecs(git_root, project_root, extensions);
    match churn::collect(git_root, &eligible, &pathspecs, short_days, long_days) {
        Ok(history) => history,
        Err(error) => {
            warnings.push(format!("Git churn collection skipped: {error:#}"));
            empty_history(short_days, long_days)
        }
    }
}

fn history_pathspecs(git_root: &Path, project_root: &Path, extensions: &[String]) -> Vec<String> {
    if extensions.is_empty() {
        return Vec::new();
    }
    let project_prefix = project_root
        .strip_prefix(git_root)
        .ok()
        .map(slash_path)
        .filter(|prefix| !prefix.is_empty())
        .map(|prefix| format!("{prefix}/"))
        .unwrap_or_default();
    extensions
        .iter()
        .map(|extension| format!(":(glob){project_prefix}**/*.{extension}"))
        .collect()
}

fn empty_history(short_days: u32, long_days: u32) -> GitHistory {
    GitHistory {
        short: ThroughputSummary {
            days: short_days,
            ..ThroughputSummary::default()
        },
        long: ThroughputSummary {
            days: long_days,
            ..ThroughputSummary::default()
        },
        ..GitHistory::default()
    }
}

fn apply_churn(
    files: &mut [FileMetrics],
    git_root: Option<&Path>,
    project_root: &Path,
    history: &HashMap<String, FileChurn>,
) {
    let Some(git_root) = git_root else { return };
    for file in files {
        let path = git_relative_path(git_root, project_root, &file.path);
        if let Some(churn) = history.get(&path) {
            file.churn_short = churn.short;
            file.churn_long = churn.long;
        }
    }
}

fn git_relative_path(git_root: &Path, project_root: &Path, file_path: &str) -> String {
    let path = project_root.join(file_path);
    path.strip_prefix(git_root)
        .map_or_else(|_| file_path.to_string(), slash_path)
}

fn summarize_languages(files: &[FileMetrics]) -> BTreeMap<String, LanguageSummary> {
    let mut summaries = BTreeMap::<String, LanguageSummary>::new();
    for file in files {
        let summary = summaries.entry(file.language.clone()).or_default();
        summary.files += 1;
        summary.lines.add_assign(file.lines);
    }
    summaries
}

fn summarize_crates(files: &[FileMetrics], cargo: &CargoContext) -> Vec<CrateSummary> {
    let mut summaries = cargo
        .package_names()
        .map(|name| {
            (
                name.to_string(),
                CrateSummary {
                    name: name.to_string(),
                    ..CrateSummary::default()
                },
            )
        })
        .collect::<BTreeMap<_, _>>();
    for file in files {
        let Some(crate_name) = &file.crate_name else {
            continue;
        };
        let summary = summaries
            .entry(crate_name.clone())
            .or_insert_with(|| CrateSummary {
                name: crate_name.clone(),
                ..CrateSummary::default()
            });
        summary.files += 1;
        summary.churn_short += file.churn_short.changed();
        summary.churn_long += file.churn_long.changed();
        match file.kind {
            SourceKind::Production => {
                summary.production_code += file.production_code();
                summary.unit_test_code += file.inline_test_lines.code;
            }
            SourceKind::UnitTest => summary.unit_test_code += file.lines.code,
            SourceKind::IntegrationTest => summary.integration_test_code += file.lines.code,
            SourceKind::Bench => summary.bench_code += file.lines.code,
            SourceKind::Example => summary.example_code += file.lines.code,
            SourceKind::Build => summary.build_code += file.lines.code,
            SourceKind::Other => summary.other_code += file.lines.code,
        }
    }
    let mut summaries = summaries.into_values().collect::<Vec<_>>();
    summaries.sort_by(|left, right| {
        right
            .total_code()
            .cmp(&left.total_code())
            .then_with(|| left.name.cmp(&right.name))
    });
    summaries
}

fn summarize_project(files: &[FileMetrics], crate_count: usize) -> ProjectSummary {
    let mut summary = ProjectSummary {
        files: files.len(),
        crates: crate_count,
        ..ProjectSummary::default()
    };
    for file in files {
        summary.lines.add_assign(file.lines);
        summary.production_code += file.production_code();
        summary.test_code += file.test_code();
    }
    summary
}

#[cfg(test)]
mod tests {
    use std::path::Path;

    use super::history_pathspecs;

    #[test]
    fn history_pathspecs_scope_extensions_under_project_subdirectories() {
        assert_eq!(
            history_pathspecs(
                Path::new("/repo"),
                Path::new("/repo/crates/viewer"),
                &["rs".to_string(), "wgsl".to_string()],
            ),
            [
                ":(glob)crates/viewer/**/*.rs",
                ":(glob)crates/viewer/**/*.wgsl",
            ]
        );
        assert!(history_pathspecs(Path::new("/repo"), Path::new("/repo"), &[]).is_empty());
    }
}