churnloom 0.1.0

Fast codebase health reports woven from churn, LOC, structure, and Cargo ownership
Documentation
use std::path::PathBuf;

use clap::{Args, Parser, ValueEnum};

use crate::options::default_jobs;

/// Format written by the command-line interface.
#[derive(Clone, Copy, Debug, Default, ValueEnum)]
pub enum OutputFormat {
    /// Human-readable terminal output.
    #[default]
    Text,
    /// Stable, machine-readable JSON output.
    Json,
}

/// Weave code size, structure, Cargo ownership, and Git churn into one report.
#[derive(Debug, Parser)]
#[command(version, about, long_about = None)]
pub struct Cli {
    /// Repository or project directory to analyze.
    #[arg(default_value = ".")]
    pub path: PathBuf,

    /// Number of ranked files to display (0 displays every file).
    #[arg(long, default_value_t = 20)]
    pub top: usize,

    /// Worker threads for parallel counting and analysis.
    #[arg(long, default_value_t = default_jobs(), value_parser = parse_jobs)]
    pub jobs: usize,

    /// Recent Git churn window in days.
    #[arg(long, visible_alias = "days-short", default_value_t = 7, value_parser = clap::value_parser!(u32).range(1..))]
    pub short_days: u32,

    /// Longer Git churn window in days.
    #[arg(long, visible_alias = "days-long", default_value_t = 30, value_parser = clap::value_parser!(u32).range(1..))]
    pub long_days: u32,

    /// Output format.
    #[arg(long, value_enum, default_value_t)]
    pub format: OutputFormat,

    /// Limit ranked files emitted in JSON (0 emits every file).
    #[arg(long, default_value_t = 0)]
    pub json_top: usize,

    /// Print the long window's per-day throughput table.
    #[arg(long)]
    pub show_daily: bool,

    #[command(flatten)]
    /// Source discovery and filtering controls.
    pub source: SourceOptions,
}

/// Source discovery and filtering controls shared by CLI arguments.
#[derive(Args, Debug)]
pub struct SourceOptions {
    /// Include generated source in reports.
    #[arg(long)]
    pub include_generated: bool,

    /// Analyze ignored and hidden source files too.
    #[arg(long)]
    pub all_files: bool,

    /// Additional gitignore-style exclusion (repeatable).
    #[arg(long, value_name = "PATTERN", action = clap::ArgAction::Append)]
    pub exclude: Vec<String>,

    /// File extension to analyze (repeatable, for example `--ext .rs`).
    #[arg(long = "ext", value_name = "EXTENSION", action = clap::ArgAction::Append, value_parser = parse_extension)]
    pub extensions: Vec<String>,

    /// Analyze only repository-relative paths with this prefix (repeatable).
    #[arg(long, value_name = "PREFIX", action = clap::ArgAction::Append)]
    pub include_prefix: Vec<String>,

    /// Exclude repository-relative paths with this prefix (repeatable).
    #[arg(long, value_name = "PREFIX", action = clap::ArgAction::Append)]
    pub exclude_prefix: Vec<String>,

    /// Skip Cargo workspace discovery even when Cargo.toml is present.
    #[arg(long)]
    pub no_cargo: bool,
}

fn parse_jobs(value: &str) -> Result<usize, String> {
    value
        .parse::<usize>()
        .ok()
        .filter(|jobs| *jobs > 0)
        .ok_or_else(|| "jobs must be a positive integer".to_string())
}

fn parse_extension(value: &str) -> Result<String, String> {
    let extension = value.trim().trim_start_matches('.');
    if extension.is_empty() || extension.contains(['/', '\\']) {
        return Err("extension must be a non-empty file suffix".to_string());
    }
    Ok(extension.to_ascii_lowercase())
}

#[cfg(test)]
mod tests {
    use clap::Parser;

    use super::Cli;

    #[test]
    fn accepts_legacy_window_aliases_and_source_filters() {
        let cli = Cli::try_parse_from([
            "churnloom",
            "--days-short",
            "5",
            "--days-long",
            "20",
            "--ext",
            ".RS",
            "--include-prefix",
            "crates/",
            "--exclude-prefix",
            "crates/generated/",
            "--show-daily",
        ])
        .expect("legacy-compatible arguments parse");

        assert_eq!(cli.short_days, 5);
        assert_eq!(cli.long_days, 20);
        assert_eq!(cli.source.extensions, ["rs"]);
        assert_eq!(cli.source.include_prefix, ["crates/"]);
        assert_eq!(cli.source.exclude_prefix, ["crates/generated/"]);
        assert!(cli.show_daily);
    }
}