sloc_core/

lib.rs

// SPDX-License-Identifier: AGPL-3.0-or-later
// Copyright (C) 2026 Nima Shafie <nimzshafie@gmail.com>
#![allow(clippy::multiple_crate_versions)]

pub mod baseline;
pub mod coverage;
pub mod delta;
pub mod history;
pub use baseline::{check_against_baseline, resolve_baselines_path, BaselineEntry, BaselineStore};
pub use coverage::{aggregate_line_coverage, lookup_coverage, parse_lcov, FileCoverage};
pub use delta::{compute_delta, FileChangeStatus, FileDelta, ScanComparison, SummaryDelta};
pub use history::{RegistryEntry, ScanRegistry, ScanSummarySnapshot, WatchedDirsStore};

use std::collections::{BTreeMap, BTreeSet, HashSet};
use std::fs;
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicBool, AtomicUsize, Ordering};
use std::sync::Arc;

use anyhow::{Context, Result};
use chrono::{DateTime, Utc};
use encoding_rs::{UTF_16BE, UTF_16LE, WINDOWS_1252};
use globset::{Glob, GlobSet, GlobSetBuilder};
use ignore::WalkBuilder;
use serde::{Deserialize, Serialize};
use uuid::Uuid;

use sloc_config::{
    AppConfig, BinaryFileBehavior, BlankInBlockCommentPolicy, ContinuationLinePolicy,
    FailureBehavior, MixedLinePolicy,
};
use sloc_languages::style::IndentStyle;
use sloc_languages::{
    analyze_text, detect_language, supported_languages, AnalysisOptions, Language, ParseMode,
    RawLineCounts, StyleAnalysis,
};

// ── Detection sample sizes and thresholds ────────────────────────────────────

/// Maximum number of worker threads used for parallel file analysis.
const MAX_ANALYSIS_THREADS: usize = 16;
/// Fallback thread count when `available_parallelism` is unavailable.
const DEFAULT_ANALYSIS_THREADS: usize = 4;
/// Byte sample used to detect `@generated` markers.
const GENERATED_SAMPLE_BYTES: usize = 1024;
/// Byte sample used to detect minified files via line-length heuristic.
const MINIFIED_SAMPLE_BYTES: usize = 4096;
/// Longest line length above which a file is considered minified.
const MINIFIED_LINE_THRESHOLD: usize = 2000;
/// Byte sample used to detect binary files via null-byte scan.
const BINARY_SAMPLE_BYTES: usize = 8192;

/// Atomics shared between `analyze()` and the caller so the caller can poll scan progress.
pub struct ProgressCounters {
    /// Number of candidate files processed so far (incremented per file, across all threads).
    pub files_done: Arc<AtomicUsize>,
    /// Total candidate files discovered (set before parallel analysis begins).
    pub files_total: Arc<AtomicUsize>,
}

/// Three-way outcome for metadata-level policy checks.
enum MetadataPolicyOutcome {
    /// Skip this file — include the record in output.
    Skip(Box<FileRecord>),
    /// Exclude this file entirely — no record in output (include-glob miss).
    Exclude,
    /// Continue to content checks.
    Continue,
}

#[derive(Debug, Clone, Copy, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum FileStatus {
    AnalyzedExact,
    AnalyzedBestEffort,
    SkippedBinary,
    SkippedDecodeError,
    SkippedUnsupported,
    SkippedByPolicy,
    ErrorInternal,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct EffectiveCounts {
    pub code_lines: u64,
    pub comment_lines: u64,
    pub blank_lines: u64,
    pub mixed_lines_separate: u64,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct ToolMetadata {
    pub name: String,
    pub version: String,
    pub run_id: String,
    pub timestamp_utc: DateTime<Utc>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct EnvironmentMetadata {
    pub operating_system: String,
    pub architecture: String,
    pub runtime_mode: String,
    pub initiator_username: String,
    pub initiator_hostname: String,
    /// CI system name when the scan runs inside a known CI environment (Jenkins,
    /// GitHub Actions, GitLab CI, …). `None` for interactive / local runs.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub ci_name: Option<String>,
}

#[derive(Debug, Clone, Serialize, Deserialize, Default)]
pub struct SummaryTotals {
    pub files_considered: u64,
    pub files_analyzed: u64,
    pub files_skipped: u64,
    pub total_physical_lines: u64,
    pub code_lines: u64,
    pub comment_lines: u64,
    pub blank_lines: u64,
    pub mixed_lines_separate: u64,
    #[serde(default)]
    pub functions: u64,
    #[serde(default)]
    pub classes: u64,
    #[serde(default)]
    pub variables: u64,
    #[serde(default)]
    pub imports: u64,
    #[serde(default)]
    pub test_count: u64,
    /// Lexically detected test assertion call lines across all analyzed files.
    #[serde(default)]
    pub test_assertion_count: u64,
    /// Lexically detected test suite / fixture / group declaration lines across all analyzed files.
    #[serde(default)]
    pub test_suite_count: u64,
    /// Aggregated from LCOV data when provided.
    #[serde(default)]
    pub coverage_lines_found: u64,
    #[serde(default)]
    pub coverage_lines_hit: u64,
    #[serde(default)]
    pub coverage_functions_found: u64,
    #[serde(default)]
    pub coverage_functions_hit: u64,
    #[serde(default)]
    pub coverage_branches_found: u64,
    #[serde(default)]
    pub coverage_branches_hit: u64,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LanguageSummary {
    pub language: Language,
    pub files: u64,
    pub total_physical_lines: u64,
    pub code_lines: u64,
    pub comment_lines: u64,
    pub blank_lines: u64,
    pub mixed_lines_separate: u64,
    #[serde(default)]
    pub functions: u64,
    #[serde(default)]
    pub classes: u64,
    #[serde(default)]
    pub variables: u64,
    #[serde(default)]
    pub imports: u64,
    #[serde(default)]
    pub test_count: u64,
    #[serde(default)]
    pub test_assertion_count: u64,
    #[serde(default)]
    pub test_suite_count: u64,
    #[serde(default)]
    pub coverage_lines_found: u64,
    #[serde(default)]
    pub coverage_lines_hit: u64,
    #[serde(default)]
    pub coverage_functions_found: u64,
    #[serde(default)]
    pub coverage_functions_hit: u64,
    #[serde(default)]
    pub coverage_branches_found: u64,
    #[serde(default)]
    pub coverage_branches_hit: u64,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct FileRecord {
    pub path: String,
    pub relative_path: String,
    pub language: Option<Language>,
    pub size_bytes: u64,
    pub detected_encoding: Option<String>,
    pub raw_line_categories: RawLineCounts,
    pub effective_counts: EffectiveCounts,
    pub status: FileStatus,
    pub warnings: Vec<String>,
    pub generated: bool,
    pub minified: bool,
    pub vendor: bool,
    pub parse_mode: Option<ParseMode>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub submodule: Option<String>,
    /// Line/function/branch coverage from an external LCOV file, when provided.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub coverage: Option<FileCoverage>,
    /// Lexical style-guide adherence analysis; `None` for unsupported languages.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub style_analysis: Option<StyleAnalysis>,
}

/// Per-language-family style aggregation within a `StyleSummary`.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct LanguageStyleGroup {
    /// Display label, e.g. `"C / C++"`, `"Python"`, `"JavaScript"`.
    pub language_family: String,
    /// Number of files in this group.
    pub files_count: u32,
    /// Name of the guide with the highest average adherence.
    pub dominant_guide: String,
    /// Average adherence of the dominant guide (0–100).
    pub dominant_score_pct: u8,
    /// Most common indent style across the group.
    pub common_indent_style: String,
    /// Average guide adherence scores (guide name, 0–100) sorted descending.
    pub guide_avg_scores: Vec<(String, u8)>,
    /// Percentage of files (0–100) where ≤ 5 % of lines exceed 80 chars.
    pub line80_compliant_pct: u8,
}

/// Aggregate multi-language style-guide adherence across all analysed files.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct StyleSummary {
    /// Total files for which style data was produced.
    pub files_analyzed: u32,
    /// Most common indent style across *all* analysed files.
    pub common_indent_style: String,
    /// Percentage of all analysed files (0–100) with ≤ 5 % of lines over 80 chars.
    pub line80_compliant_pct: u8,
    /// Per-language-family breakdown, sorted by `files_count` descending.
    pub by_language: Vec<LanguageStyleGroup>,
}

/// Backward-compatible alias kept so that `sloc-report` and `sloc-web` can migrate
/// incrementally without a breaking change on the same release.
pub type CppStyleSummary = StyleSummary;

/// Per-submodule aggregated stats produced when `submodule_breakdown` is enabled.
#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct SubmoduleSummary {
    pub name: String,
    pub relative_path: String,
    pub files_analyzed: u64,
    pub total_physical_lines: u64,
    pub code_lines: u64,
    pub comment_lines: u64,
    pub blank_lines: u64,
    pub language_summaries: Vec<LanguageSummary>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AnalysisRun {
    pub tool: ToolMetadata,
    pub environment: EnvironmentMetadata,
    pub effective_configuration: AppConfig,
    pub input_roots: Vec<String>,
    pub summary_totals: SummaryTotals,
    pub totals_by_language: Vec<LanguageSummary>,
    pub per_file_records: Vec<FileRecord>,
    pub skipped_file_records: Vec<FileRecord>,
    pub warnings: Vec<String>,
    /// Non-empty only when `discovery.submodule_breakdown` is enabled.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub submodule_summaries: Vec<SubmoduleSummary>,
    /// Short git commit SHA (7 chars) at scan time, if the project is a git repo.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub git_commit_short: Option<String>,
    /// Full git commit SHA at scan time, if the project is a git repo.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub git_commit_long: Option<String>,
    /// Git branch active at scan time, if the project is a git repo.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub git_branch: Option<String>,
    /// Author of the last git commit at scan time.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub git_commit_author: Option<String>,
    /// Comma-separated git tags pointing at HEAD at scan time.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub git_tags: Option<String>,
    /// Nearest ancestor release tag (output of `git describe --tags --abbrev=0`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub git_nearest_tag: Option<String>,
    /// ISO 8601 author-date of the last git commit at scan time.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub git_commit_date: Option<String>,
    /// URL of the `origin` remote as recorded in `.git/config` at scan time.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub git_remote_url: Option<String>,
    /// Multi-language style-guide adherence; `None` when no supported files were analysed.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub style_summary: Option<StyleSummary>,
}

#[derive(Default)]
struct GitInfo {
    commit_short: Option<String>,
    commit_long: Option<String>,
    branch: Option<String>,
    author: Option<String>,
    tags: Option<String>,
    nearest_tag: Option<String>,
    commit_date: Option<String>,
    remote_url: Option<String>,
}

/// Locate the `.git` directory by walking up from `start`.
/// Handles plain repos, worktrees (`.git` is a file with `gitdir:` pointer), and
/// submodules. Returns `None` if no git repo is found.
fn find_git_dir(start: &Path) -> Option<PathBuf> {
    let mut current = Some(start);
    while let Some(dir) = current {
        let candidate = dir.join(".git");
        if candidate.is_dir() {
            return Some(candidate);
        }
        if candidate.is_file() {
            if let Some(resolved) = resolve_git_file_pointer(&candidate, dir) {
                return Some(resolved);
            }
        }
        current = dir.parent();
    }
    None
}

/// Resolve a `.git` *file* (worktree/submodule pointer) to the absolute path it
/// points to. Returns `None` if the file is unreadable or lacks a `gitdir:` line,
/// or if the resolved path is not an existing directory.
fn resolve_git_file_pointer(file: &Path, base_dir: &Path) -> Option<PathBuf> {
    let content = fs::read_to_string(file).ok()?;
    let ptr = content.trim().strip_prefix("gitdir: ")?;
    // Normalise forward-slash paths to the OS separator so that Path operations
    // (join, exists, canonicalize) work correctly on Windows.
    let ptr_native = ptr.replace('/', std::path::MAIN_SEPARATOR_STR);
    let resolved = if Path::new(&ptr_native).is_absolute() {
        PathBuf::from(&ptr_native)
    } else {
        base_dir.join(&ptr_native)
    };
    // canonicalize resolves ".." components and symlinks; fall back to the
    // un-canonicalized path if it fails (e.g. some Windows configurations
    // return a UNC "\\?\" prefix that confuses later path operations).
    let final_path = resolved.canonicalize().unwrap_or(resolved);
    if final_path.is_dir() {
        Some(final_path)
    } else {
        None
    }
}

/// Resolve a git ref name (e.g. `refs/heads/main`) to a full 40-char commit SHA.
/// Checks loose ref files first, then `packed-refs`.
fn resolve_ref(git_dir: &Path, refname: &str) -> Option<String> {
    // Build the OS-native path to the loose ref file by joining each
    // forward-slash component individually.  This produces the correct
    // separator on every platform without any manual replacement.
    let ref_path = refname
        .split('/')
        .fold(git_dir.to_path_buf(), |p, c| p.join(c));
    if ref_path.exists() {
        let sha = fs::read_to_string(&ref_path)
            .ok()
            .map(|s| s.trim().to_string())
            .filter(|s| s.len() >= 40 && s.chars().all(|c| c.is_ascii_hexdigit()));
        if sha.is_some() {
            return sha;
        }
    }
    // Packed refs: each line is "<sha> <refname>" (lines starting with '#' are
    // comments; lines starting with '^' are peeled tag objects to skip).
    // str::lines() handles both \n and \r\n, so Windows line endings are fine.
    let packed = fs::read_to_string(git_dir.join("packed-refs")).ok()?;
    for line in packed.lines() {
        if line.starts_with('#') || line.starts_with('^') {
            continue;
        }
        let mut cols = line.splitn(2, ' ');
        let sha = cols.next()?;
        let name = cols.next()?.trim();
        if name == refname {
            return Some(sha.to_string());
        }
    }
    None
}

/// Extract the URL value from a `url = <value>` git-config line, returning `None` if absent or empty.
fn parse_url_line(line: &str) -> Option<&str> {
    let rest = line.strip_prefix("url")?;
    let rest = rest.trim_start_matches([' ', '\t']);
    let url = rest.strip_prefix('=')?.trim();
    if url.is_empty() {
        None
    } else {
        Some(url)
    }
}

/// Parse `.git/config` and return the URL of the `origin` remote, if present.
fn read_git_remote_url(git_dir: &Path) -> Option<String> {
    let config = fs::read_to_string(git_dir.join("config")).ok()?;
    let mut in_origin = false;
    for line in config.lines() {
        let trimmed = line.trim();
        if trimmed.starts_with('[') {
            in_origin = trimmed == r#"[remote "origin"]"#;
        } else if in_origin {
            if let Some(url) = parse_url_line(trimmed) {
                return Some(url.to_owned());
            }
        }
    }
    None
}

/// Detect git metadata by reading `.git/` files directly — no `git` executable
/// needed. Falls back gracefully for detached HEADs, shallow clones, and missing
/// reflogs.
fn detect_git_for_run(project_path: &Path) -> GitInfo {
    // Resolve the CI branch early so it can fill in any gap in git metadata.
    let ci_branch = ci_branch_from_env();

    let Some(git_dir) = find_git_dir(project_path) else {
        // No .git directory (e.g. scanning a non-repo path in CI). Use whatever
        // the CI system tells us about the branch.
        return GitInfo {
            branch: ci_branch,
            ..GitInfo::default()
        };
    };

    let head_raw = match fs::read_to_string(git_dir.join("HEAD")) {
        Ok(s) => s.trim().to_string(),
        Err(_) => {
            return GitInfo {
                branch: ci_branch,
                ..GitInfo::default()
            }
        }
    };

    let (branch_from_head, commit_long) = head_raw.strip_prefix("ref: ").map_or_else(
        || {
            if head_raw.len() >= 40 && head_raw.chars().all(|c| c.is_ascii_hexdigit()) {
                // Detached HEAD — HEAD file is the commit SHA (common in CI checkouts).
                (None, Some(head_raw[..40].to_string()))
            } else {
                (None, None)
            }
        },
        |refname| {
            let branch = refname
                .strip_prefix("refs/heads/")
                .map(|b| b.trim().to_string());
            let sha = resolve_ref(&git_dir, refname.trim());
            (branch, sha)
        },
    );
    // Prefer the branch name derived from the HEAD ref; fall back to the CI
    // env var (covers detached-HEAD checkouts done by Jenkins, GitHub Actions, etc.).
    let branch = branch_from_head.or(ci_branch);

    let commit_short = commit_long
        .as_deref()
        .map(|s| s.chars().take(7).collect::<String>());

    let author = run_git_cmd(project_path, &["log", "-1", "--format=%an", "HEAD"]);
    let commit_date = run_git_cmd(project_path, &["log", "-1", "--format=%aI", "HEAD"]);
    let remote_url = read_git_remote_url(&git_dir);

    // Tags and nearest-tag still require git CLI — try it as a best-effort bonus
    // but don't block on it. If git isn't available these will simply be None.
    let tags = run_git_cmd(project_path, &["tag", "--points-at", "HEAD"]).map(|t| {
        t.lines()
            .filter(|l| !l.is_empty())
            .collect::<Vec<_>>()
            .join(", ")
    });
    let nearest_tag = run_git_cmd(project_path, &["describe", "--tags", "--abbrev=0", "HEAD"]);

    GitInfo {
        commit_short,
        commit_long,
        branch,
        author,
        tags,
        nearest_tag,
        commit_date,
        remote_url,
    }
}

/// Run a git command as a best-effort supplemental source.
fn run_git_cmd(dir: &Path, args: &[&str]) -> Option<String> {
    // Try the bare name first (works when git is on PATH), then fall back to
    // absolute paths for service accounts that run with a stripped PATH.
    // Unix paths silently fail on Windows and vice-versa.
    let candidates: &[&str] = &[
        // Works on all platforms when git is on PATH
        "git",
        // Common Linux / macOS install locations
        "/usr/bin/git",
        "/usr/local/bin/git",
        "/opt/homebrew/bin/git",
        // Git for Windows default installation paths
        r"C:\Program Files\Git\cmd\git.exe",
        r"C:\Program Files\Git\bin\git.exe",
        r"C:\Program Files (x86)\Git\cmd\git.exe",
    ];
    for &exe in candidates {
        let result = std::process::Command::new(exe)
            .args(["-c", "safe.directory=*"])
            .args(args)
            .current_dir(dir)
            .output()
            .ok()
            .filter(|o| o.status.success())
            .and_then(|o| String::from_utf8(o.stdout).ok())
            .map(|s| s.trim().to_string())
            .filter(|s| !s.is_empty());
        if result.is_some() {
            return result;
        }
    }
    None
}

/// Return the name of the CI system if the process is running inside one.
fn detect_ci_system() -> Option<&'static str> {
    let ev = |k: &str| std::env::var(k).is_ok();
    let ev_true = |k: &str| std::env::var(k).as_deref() == Ok("true");
    if ev("JENKINS_URL") || ev("JENKINS_HOME") || ev("BUILD_URL") {
        return Some("Jenkins");
    }
    if ev_true("GITHUB_ACTIONS") {
        return Some("GitHub Actions");
    }
    if ev_true("GITLAB_CI") {
        return Some("GitLab CI");
    }
    if ev_true("CIRCLECI") {
        return Some("CircleCI");
    }
    if ev_true("TRAVIS") {
        return Some("Travis CI");
    }
    if ev_true("TF_BUILD") {
        return Some("Azure DevOps");
    }
    if ev("TEAMCITY_VERSION") {
        return Some("TeamCity");
    }
    None
}

/// Read the current branch name from well-known CI environment variables.
/// Called as a fallback when the git HEAD is detached (common in CI checkouts).
fn ci_branch_from_env() -> Option<String> {
    const VARS: &[&str] = &[
        "BRANCH_NAME",        // Jenkins Pipeline
        "GIT_BRANCH",         // Jenkins Freestyle (may carry "origin/<branch>")
        "GITHUB_REF_NAME",    // GitHub Actions
        "CI_COMMIT_BRANCH",   // GitLab CI
        "CIRCLE_BRANCH",      // CircleCI
        "TRAVIS_BRANCH",      // Travis CI
        "BUILD_SOURCEBRANCH", // Azure DevOps (may carry "refs/heads/<branch>")
    ];
    for &var in VARS {
        if let Ok(val) = std::env::var(var) {
            let val = val.trim();
            let val = val
                .strip_prefix("refs/heads/")
                .or_else(|| val.strip_prefix("origin/"))
                .unwrap_or(val);
            if !val.is_empty() && val != "HEAD" {
                return Some(val.to_string());
            }
        }
    }
    None
}

fn get_current_username() -> String {
    std::env::var("USERNAME")
        .or_else(|_| std::env::var("USER"))
        .unwrap_or_else(|_| "unknown".to_string())
}

fn non_empty_env(var: &str) -> Option<String> {
    let v = std::env::var(var).ok()?;
    if v.is_empty() {
        None
    } else {
        Some(v)
    }
}

fn is_jenkins_env() -> bool {
    std::env::var("JENKINS_URL").is_ok()
        || std::env::var("JENKINS_HOME").is_ok()
        || std::env::var("BUILD_URL").is_ok()
}

fn get_hostname() -> String {
    // In CI environments prefer a human-readable agent/runner identifier over
    // whatever hostname the container was assigned.
    if is_jenkins_env() {
        if let Some(n) = non_empty_env("NODE_NAME") {
            return n;
        }
    }
    if std::env::var("GITHUB_ACTIONS").as_deref() == Ok("true") {
        if let Some(r) = non_empty_env("RUNNER_NAME") {
            return r;
        }
    }
    if std::env::var("GITLAB_CI").as_deref() == Ok("true") {
        if let Some(r) = non_empty_env("CI_RUNNER_DESCRIPTION") {
            return r;
        }
    }
    std::env::var("COMPUTERNAME")
        .or_else(|_| std::env::var("HOSTNAME"))
        .or_else(|_| std::fs::read_to_string("/etc/hostname").map(|s| s.trim().to_string()))
        .unwrap_or_else(|_| "unknown".to_string())
}

/// Walk a single directory root and collect file records into the output vectors.
#[allow(clippy::too_many_arguments)]
fn walk_root(
    root: &Path,
    config: &AppConfig,
    include_globs: Option<&GlobSet>,
    exclude_globs: Option<&GlobSet>,
    enabled_languages: Option<&BTreeSet<Language>>,
    seen_paths: &mut HashSet<PathBuf>,
    analyzed: &mut Vec<FileRecord>,
    skipped: &mut Vec<FileRecord>,
    warnings: &mut Vec<String>,
    cancel: Option<&AtomicBool>,
    progress: Option<&ProgressCounters>,
) -> Result<()> {
    let mut builder = WalkBuilder::new(root);
    builder
        .follow_links(config.discovery.follow_symlinks)
        .hidden(config.discovery.ignore_hidden_files)
        .ignore(config.discovery.honor_ignore_files)
        .parents(config.discovery.honor_ignore_files)
        .git_ignore(config.discovery.honor_ignore_files)
        .git_global(config.discovery.honor_ignore_files)
        .git_exclude(config.discovery.honor_ignore_files);

    let paths = collect_walk_paths(&builder, seen_paths, warnings);
    if paths.is_empty() {
        return Ok(());
    }

    if let Some(p) = progress {
        p.files_total.fetch_add(paths.len(), Ordering::Relaxed);
    }

    let chunk_results = run_parallel_analysis(
        &paths,
        root,
        config,
        include_globs,
        exclude_globs,
        enabled_languages,
        cancel,
        progress,
    )?;
    merge_chunk_results(chunk_results, analyzed, skipped, warnings)
}

fn collect_walk_paths(
    builder: &WalkBuilder,
    seen_paths: &mut HashSet<PathBuf>,
    warnings: &mut Vec<String>,
) -> Vec<PathBuf> {
    // build_parallel() walks the directory tree across multiple threads (work-stealing
    // internally), which is meaningfully faster for deeply nested repos with many directories.
    // We collect results via an MPSC channel so each walker thread sends without contention.
    let (tx, rx) = std::sync::mpsc::channel::<std::result::Result<PathBuf, String>>();

    builder.build_parallel().run(|| {
        let tx = tx.clone();
        Box::new(move |entry| {
            match entry {
                Err(e) => {
                    let _ = tx.send(Err(format!("discovery warning: {e}")));
                }
                Ok(e) => {
                    let path = e.into_path();
                    if !path.is_dir() {
                        let _ = tx.send(Ok(path));
                    }
                }
            }
            ignore::WalkState::Continue
        })
    });

    // Drop the sender that the outer scope holds; the per-thread clones were dropped when
    // run() returned (all threads finished). Dropping this last sender closes the channel.
    drop(tx);

    rx.into_iter()
        .filter_map(|msg| match msg {
            Ok(path) => {
                if seen_paths.insert(path.clone()) {
                    Some(path)
                } else {
                    None
                }
            }
            Err(warn) => {
                warnings.push(warn);
                None
            }
        })
        .collect()
}

/// Inner work loop executed by each analysis thread.
#[allow(clippy::too_many_arguments)]
fn worker_loop(
    paths: &[PathBuf],
    root: &Path,
    config: &AppConfig,
    include_globs: Option<&GlobSet>,
    exclude_globs: Option<&GlobSet>,
    enabled_languages: Option<&BTreeSet<Language>>,
    cancel: Option<&AtomicBool>,
    next_index: &AtomicUsize,
    files_done: Option<&AtomicUsize>,
) -> Vec<Result<Option<FileRecord>>> {
    let mut results = Vec::new();
    loop {
        if cancel.is_some_and(|c| c.load(Ordering::Relaxed)) {
            results.push(Err(anyhow::anyhow!("analysis cancelled")));
            break;
        }
        let i = next_index.fetch_add(1, Ordering::Relaxed);
        if i >= paths.len() {
            break;
        }
        results.push(analyze_candidate_file(
            &paths[i],
            root,
            config,
            include_globs,
            exclude_globs,
            enabled_languages,
        ));
        if let Some(fd) = files_done {
            fd.fetch_add(1, Ordering::Relaxed);
        }
    }
    results
}

#[allow(clippy::too_many_arguments)]
fn run_parallel_analysis(
    paths: &[PathBuf],
    root: &Path,
    config: &AppConfig,
    include_globs: Option<&GlobSet>,
    exclude_globs: Option<&GlobSet>,
    enabled_languages: Option<&BTreeSet<Language>>,
    cancel: Option<&AtomicBool>,
    progress: Option<&ProgressCounters>,
) -> Result<Vec<Vec<Result<Option<FileRecord>>>>> {
    let thread_count = std::thread::available_parallelism().map_or(DEFAULT_ANALYSIS_THREADS, |n| {
        n.get().min(MAX_ANALYSIS_THREADS)
    });
    // Shared work-queue index: each thread atomically claims the next path to process.
    // This eliminates static-chunk load imbalance — threads that finish early immediately
    // pick up more work instead of sitting idle while one overloaded chunk finishes.
    let next_index = AtomicUsize::new(0);
    let files_done: Option<&AtomicUsize> = progress.map(|p| p.files_done.as_ref());

    std::thread::scope(|s| -> Result<Vec<Vec<Result<Option<FileRecord>>>>> {
        // IMPORTANT: collect ALL handles before joining any of them.
        // A lazy spawn-then-join chain would serialize threads one at a time.
        let mut handles = Vec::with_capacity(thread_count);
        for _ in 0..thread_count {
            handles.push(s.spawn(|| {
                worker_loop(
                    paths,
                    root,
                    config,
                    include_globs,
                    exclude_globs,
                    enabled_languages,
                    cancel,
                    &next_index,
                    files_done,
                )
            }));
        }
        handles
            .into_iter()
            .map(|h| {
                h.join()
                    .map_err(|_| anyhow::anyhow!("analysis thread panicked"))
            })
            .collect()
    })
}

fn merge_chunk_results(
    chunk_results: Vec<Vec<Result<Option<FileRecord>>>>,
    analyzed: &mut Vec<FileRecord>,
    skipped: &mut Vec<FileRecord>,
    warnings: &mut Vec<String>,
) -> Result<()> {
    for chunk in chunk_results {
        for result in chunk {
            if let Some(record) = result? {
                push_record(record, analyzed, skipped, warnings);
            }
        }
    }
    Ok(())
}

/// Label each analyzed file with its submodule and build per-submodule summaries.
fn process_submodules(config: &AppConfig, analyzed: &mut [FileRecord]) -> Vec<SubmoduleSummary> {
    let root = config.discovery.root_paths[0]
        .canonicalize()
        .unwrap_or_else(|_| config.discovery.root_paths[0].clone());
    let submodules = detect_submodules(&root);
    if submodules.is_empty() {
        return Vec::new();
    }

    for file in analyzed.iter_mut() {
        for (name, sub_path) in &submodules {
            let prefix = sub_path.to_string_lossy().replace('\\', "/");
            let rel = &file.relative_path;
            if rel == &prefix || rel.starts_with(&format!("{prefix}/")) {
                file.submodule = Some(name.clone());
                break;
            }
        }
    }

    build_submodule_summaries(analyzed, &submodules)
}

/// Assemble the final `AnalysisRun` from collected records and metadata.
fn assemble_run(
    config: &AppConfig,
    runtime_mode: &str,
    analyzed: Vec<FileRecord>,
    skipped: Vec<FileRecord>,
    warnings: Vec<String>,
    submodule_summaries: Vec<SubmoduleSummary>,
) -> AnalysisRun {
    let summary = build_summary(&analyzed, &skipped);
    let language_summaries = build_language_summaries(&analyzed);
    let style_summary = build_style_summary(&analyzed);

    let first_root = config
        .discovery
        .root_paths
        .first()
        .map(|p| p.canonicalize().unwrap_or_else(|_| p.clone()));
    let git = first_root
        .as_deref()
        .map(detect_git_for_run)
        .unwrap_or_default();

    let now = Utc::now();
    let run_id = {
        let uuid_suffix = Uuid::new_v4().simple().to_string();
        format!("{}-{}", now.format("%Y%m%d-%H%M"), uuid_suffix)
    };

    AnalysisRun {
        tool: ToolMetadata {
            name: "sloc".into(),
            version: env!("CARGO_PKG_VERSION").into(),
            run_id,
            timestamp_utc: now,
        },
        environment: EnvironmentMetadata {
            operating_system: std::env::consts::OS.into(),
            architecture: std::env::consts::ARCH.into(),
            runtime_mode: runtime_mode.into(),
            initiator_username: get_current_username(),
            initiator_hostname: get_hostname(),
            ci_name: detect_ci_system().map(str::to_string),
        },
        effective_configuration: config.clone(),
        input_roots: config
            .discovery
            .root_paths
            .iter()
            .map(|p| path_to_string(p))
            .collect(),
        summary_totals: summary,
        totals_by_language: language_summaries,
        per_file_records: analyzed,
        skipped_file_records: skipped,
        warnings,
        submodule_summaries,
        git_commit_short: git.commit_short,
        git_commit_long: git.commit_long,
        git_branch: git.branch,
        git_commit_author: git.author,
        git_tags: git.tags,
        git_nearest_tag: git.nearest_tag,
        git_commit_date: git.commit_date,
        git_remote_url: git.remote_url,
        style_summary,
    }
}

/// # Errors
///
/// Returns an error if the config is invalid, root paths cannot be walked, or any file
/// analysis step fails in a way that cannot be recovered from.
#[allow(clippy::too_many_lines)]
pub fn analyze(
    config: &AppConfig,
    runtime_mode: &str,
    cancel: Option<&AtomicBool>,
    progress: Option<&ProgressCounters>,
) -> Result<AnalysisRun> {
    config.validate()?;

    if config.discovery.root_paths.is_empty() {
        anyhow::bail!("no input paths were provided");
    }

    let include_globs = compile_globset(&config.discovery.include_globs)?;
    let exclude_globs = compile_globset(&config.discovery.exclude_globs)?;
    let enabled_languages = parse_enabled_languages(&config.analysis.enabled_languages)?;

    let mut analyzed = Vec::new();
    let mut skipped = Vec::new();
    let mut warnings = Vec::new();
    let mut seen_paths = HashSet::new();

    for root in &config.discovery.root_paths {
        if cancel.is_some_and(|c| c.load(Ordering::Relaxed)) {
            anyhow::bail!("analysis cancelled");
        }

        let root = root.canonicalize().unwrap_or_else(|_| root.clone());

        if root.is_file() {
            if let Some(record) = analyze_candidate_file(
                &root,
                root.parent().unwrap_or_else(|| Path::new(".")),
                config,
                include_globs.as_ref(),
                exclude_globs.as_ref(),
                enabled_languages.as_ref(),
            )? {
                push_record(record, &mut analyzed, &mut skipped, &mut warnings);
            }
            continue;
        }

        walk_root(
            &root,
            config,
            include_globs.as_ref(),
            exclude_globs.as_ref(),
            enabled_languages.as_ref(),
            &mut seen_paths,
            &mut analyzed,
            &mut skipped,
            &mut warnings,
            cancel,
            progress,
        )?;
    }

    analyzed.sort_by(|a, b| a.relative_path.cmp(&b.relative_path));
    skipped.sort_by(|a, b| a.relative_path.cmp(&b.relative_path));

    // Submodule detection: label each file with its submodule and build per-submodule summaries.
    let submodule_summaries = if config.discovery.submodule_breakdown {
        process_submodules(config, &mut analyzed)
    } else {
        Vec::new()
    };

    attach_coverage(config, &mut analyzed, &mut warnings);

    Ok(assemble_run(
        config,
        runtime_mode,
        analyzed,
        skipped,
        warnings,
        submodule_summaries,
    ))
}

fn attach_coverage(config: &AppConfig, analyzed: &mut [FileRecord], warnings: &mut Vec<String>) {
    let Some(cov_path) = coverage::resolve_coverage_file(config.analysis.coverage_file.as_deref())
    else {
        return;
    };
    tracing::debug!(path = %cov_path.display(), "loading coverage file");
    match fs::read_to_string(&cov_path) {
        Ok(content) => {
            let cov_map = coverage::parse_coverage_auto(&cov_path, &content);
            let mut matched: u32 = 0;
            let mut unmatched: u32 = 0;
            for record in analyzed.iter_mut() {
                record.coverage =
                    coverage::lookup_coverage(&cov_map, &record.relative_path).cloned();
                if record.coverage.is_some() {
                    matched += 1;
                } else {
                    unmatched += 1;
                }
            }
            tracing::debug!(
                path = %cov_path.display(),
                coverage_entries = cov_map.len(),
                files_matched = matched,
                files_unmatched = unmatched,
                "coverage attached"
            );
            if unmatched > 0 && matched == 0 {
                tracing::warn!(
                    path = %cov_path.display(),
                    "coverage file loaded but no source files could be matched — check that paths in the coverage report match the scanned directory"
                );
            }
        }
        Err(e) => {
            tracing::warn!(path = %cov_path.display(), error = %e, "coverage file could not be read");
            warnings.push(format!(
                "coverage file '{}' could not be read: {e}",
                cov_path.display()
            ));
        }
    }
}

fn push_record(
    record: FileRecord,
    analyzed: &mut Vec<FileRecord>,
    skipped: &mut Vec<FileRecord>,
    warnings: &mut Vec<String>,
) {
    warnings.extend(
        record
            .warnings
            .iter()
            .map(|warning| format!("{}: {warning}", record.relative_path)),
    );

    match record.status {
        FileStatus::AnalyzedExact | FileStatus::AnalyzedBestEffort => analyzed.push(record),
        _ => skipped.push(record),
    }
}

/// Convenience wrapper: build a boxed `Skip` outcome with a single-item warning message.
#[inline]
fn skip_with_reason(
    path: &Path,
    root: &Path,
    size: u64,
    reason: impl Into<String>,
) -> MetadataPolicyOutcome {
    MetadataPolicyOutcome::Skip(Box::new(skipped_record(
        path,
        root,
        size,
        FileStatus::SkippedByPolicy,
        vec![reason.into()],
    )))
}

/// Apply metadata-level policy checks (symlink, name, dir exclusion, size, globs, lockfile).
/// Returns `Skip(record)` to skip, `Exclude` to omit from output entirely (include-glob miss),
/// or `Continue` to proceed to content checks.
#[allow(clippy::too_many_arguments)]
fn check_metadata_policy(
    path: &Path,
    root: &Path,
    relative_path: &str,
    metadata: &fs::Metadata,
    config: &AppConfig,
    include_globs: Option<&GlobSet>,
    exclude_globs: Option<&GlobSet>,
) -> MetadataPolicyOutcome {
    let size = metadata.len();

    if metadata.file_type().is_symlink() && !config.discovery.follow_symlinks {
        return skip_with_reason(path, root, size, "symlink skipped by policy");
    }
    if file_name_eq(path, ".gitignore") {
        return skip_with_reason(path, root, size, ".gitignore is always excluded");
    }
    if is_excluded_dir_path(path, &config.discovery.excluded_directories) {
        return skip_with_reason(path, root, size, "path matched excluded directory setting");
    }
    if size > config.discovery.max_file_size_bytes {
        return skip_with_reason(
            path,
            root,
            size,
            format!(
                "file exceeded max_file_size_bytes ({})",
                config.discovery.max_file_size_bytes
            ),
        );
    }
    if let Some(globs) = include_globs {
        if !globs.is_match(Path::new(relative_path)) && !globs.is_match(path) {
            return MetadataPolicyOutcome::Exclude;
        }
    }
    if let Some(globs) = exclude_globs {
        if globs.is_match(Path::new(relative_path)) || globs.is_match(path) {
            return skip_with_reason(path, root, size, "path matched exclude glob");
        }
    }
    if is_known_lockfile(path) && !config.analysis.include_lockfiles {
        return skip_with_reason(path, root, size, "lockfile skipped by default policy");
    }

    MetadataPolicyOutcome::Continue
}

struct ContentPolicyResult {
    vendor: bool,
    generated: bool,
    minified: bool,
    skip_record: Option<FileRecord>,
}

/// Apply content-level policy checks (vendor, generated, minified).
/// `skip_record` is `Some` when the file should be skipped.
fn check_content_policy(
    path: &Path,
    root: &Path,
    size_bytes: u64,
    bytes: &[u8],
    config: &AppConfig,
) -> ContentPolicyResult {
    let vendor = is_vendor_path(path);
    if vendor && config.analysis.vendor_directory_detection {
        return ContentPolicyResult {
            vendor,
            generated: false,
            minified: false,
            skip_record: Some(skipped_record(
                path,
                root,
                size_bytes,
                FileStatus::SkippedByPolicy,
                vec!["vendor file skipped by policy".into()],
            )),
        };
    }

    let generated = config.analysis.generated_file_detection && looks_generated(path, bytes);
    if generated {
        return ContentPolicyResult {
            vendor,
            generated,
            minified: false,
            skip_record: Some(skipped_record(
                path,
                root,
                size_bytes,
                FileStatus::SkippedByPolicy,
                vec!["generated file skipped by policy".into()],
            )),
        };
    }

    let minified = config.analysis.minified_file_detection && looks_minified(path, bytes);
    if minified {
        return ContentPolicyResult {
            vendor,
            generated,
            minified,
            skip_record: Some(skipped_record(
                path,
                root,
                size_bytes,
                FileStatus::SkippedByPolicy,
                vec!["minified file skipped by policy".into()],
            )),
        };
    }

    ContentPolicyResult {
        vendor,
        generated,
        minified,
        skip_record: None,
    }
}

/// Decode file bytes to a UTF-8 string, handling binary detection and decode failures.
fn decode_file_contents(
    path: &Path,
    root: &Path,
    size_bytes: u64,
    bytes: &[u8],
    config: &AppConfig,
) -> Result<Option<(String, String, Vec<String>)>> {
    if is_binary(bytes) {
        return match config.analysis.binary_file_behavior {
            BinaryFileBehavior::Skip => Ok(None),
            BinaryFileBehavior::Fail => {
                anyhow::bail!("binary file encountered: {}", path.display())
            }
        };
    }

    match decode_bytes(bytes) {
        Ok(result) => Ok(Some(result)),
        Err(err) => match config.analysis.decode_failure_behavior {
            FailureBehavior::WarnSkip => {
                // Caller will handle the None as a SkippedDecodeError record.
                // We use a sentinel: return Ok(None) but encode the error into a field.
                // Instead, propagate as a skipped record via the caller.
                let _ = (path, root, size_bytes); // suppress unused warnings
                Err(anyhow::anyhow!("__decode_warn__: {err}"))
            }
            FailureBehavior::Fail => {
                anyhow::bail!("decode failure for {}: {err}", path.display())
            }
        },
    }
}

#[allow(clippy::too_many_lines)]
fn analyze_candidate_file(
    path: &Path,
    root: &Path,
    config: &AppConfig,
    include_globs: Option<&GlobSet>,
    exclude_globs: Option<&GlobSet>,
    enabled_languages: Option<&BTreeSet<Language>>,
) -> Result<Option<FileRecord>> {
    let metadata = match fs::symlink_metadata(path) {
        Ok(metadata) => metadata,
        Err(err) => {
            return Ok(Some(skipped_record(
                path,
                root,
                0,
                FileStatus::ErrorInternal,
                vec![format!("failed to read metadata: {err}")],
            )));
        }
    };

    let relative_path = relative_path_string(path, root);

    // Metadata-level policy checks.
    match check_metadata_policy(
        path,
        root,
        &relative_path,
        &metadata,
        config,
        include_globs,
        exclude_globs,
    ) {
        MetadataPolicyOutcome::Skip(record) => return Ok(Some(*record)),
        MetadataPolicyOutcome::Exclude => return Ok(None),
        MetadataPolicyOutcome::Continue => {}
    }

    let bytes = match fs::read(path) {
        Ok(bytes) => bytes,
        Err(err) => {
            return Ok(Some(skipped_record(
                path,
                root,
                metadata.len(),
                FileStatus::ErrorInternal,
                vec![format!("failed to read file: {err}")],
            )));
        }
    };

    // Content-level policy checks (vendor, generated, minified).
    let content_policy = check_content_policy(path, root, metadata.len(), &bytes, config);
    if let Some(record) = content_policy.skip_record {
        return Ok(Some(record));
    }
    let (vendor, generated, minified) = (
        content_policy.vendor,
        content_policy.generated,
        content_policy.minified,
    );

    // Decode content, handling binary and decode failures.
    let (text, encoding, decode_warnings) =
        match decode_file_contents(path, root, metadata.len(), &bytes, config) {
            Ok(Some(result)) => result,
            Ok(None) => {
                return Ok(Some(skipped_record(
                    path,
                    root,
                    metadata.len(),
                    FileStatus::SkippedBinary,
                    vec!["binary file skipped by default".into()],
                )));
            }
            Err(err) => {
                let msg = err.to_string();
                if let Some(warn_msg) = msg.strip_prefix("__decode_warn__: ") {
                    return Ok(Some(skipped_record(
                        path,
                        root,
                        metadata.len(),
                        FileStatus::SkippedDecodeError,
                        vec![warn_msg.to_string()],
                    )));
                }
                return Err(err);
            }
        };

    let first_line = text.lines().next();
    let language = detect_language(
        path,
        first_line,
        &config.analysis.extension_overrides,
        config.analysis.shebang_detection,
    );

    let Some(language) = language else {
        return Ok(Some(skipped_record(
            path,
            root,
            metadata.len(),
            FileStatus::SkippedUnsupported,
            vec!["unsupported or undetected language".into()],
        )));
    };

    if let Some(enabled) = enabled_languages {
        if !enabled.contains(&language) {
            return Ok(Some(skipped_record(
                path,
                root,
                metadata.len(),
                FileStatus::SkippedByPolicy,
                vec![format!(
                    "language {} disabled by configuration",
                    language.display_name()
                )],
            )));
        }
    }

    let ieee_opts = AnalysisOptions {
        blank_in_block_comment_as_comment: config.analysis.blank_in_block_comment_policy
            == BlankInBlockCommentPolicy::CountAsComment,
        collapse_continuation_lines: config.analysis.continuation_line_policy
            == ContinuationLinePolicy::CollapseToLogical,
    };
    let analysis = analyze_text(language, &text, ieee_opts);
    let effective_counts = compute_effective_counts(
        &analysis.raw,
        config.analysis.mixed_line_policy,
        config.analysis.python_docstrings_as_comments,
        config.analysis.count_compiler_directives,
    );

    let mut warnings = decode_warnings;
    warnings.extend(analysis.warnings.clone());

    Ok(Some(FileRecord {
        path: path_to_string(path),
        relative_path,
        language: Some(language),
        size_bytes: metadata.len(),
        detected_encoding: Some(encoding),
        raw_line_categories: analysis.raw,
        effective_counts,
        status: match analysis.parse_mode {
            ParseMode::Lexical | ParseMode::TreeSitter => FileStatus::AnalyzedExact,
            ParseMode::LexicalBestEffort => FileStatus::AnalyzedBestEffort,
        },
        warnings,
        generated,
        minified,
        vendor,
        parse_mode: Some(analysis.parse_mode),
        submodule: None,
        coverage: None,
        style_analysis: analysis.style_analysis,
    }))
}

const fn compute_effective_counts(
    raw: &RawLineCounts,
    mixed_line_policy: MixedLinePolicy,
    python_docstrings_as_comments: bool,
    count_compiler_directives: bool,
) -> EffectiveCounts {
    let mut effective = EffectiveCounts {
        code_lines: raw.code_only_lines,
        comment_lines: raw.single_comment_only_lines + raw.multi_comment_only_lines,
        blank_lines: raw.blank_only_lines,
        mixed_lines_separate: 0,
    };

    if python_docstrings_as_comments {
        effective.comment_lines += raw.docstring_comment_lines;
    } else {
        effective.code_lines += raw.docstring_comment_lines;
    }

    let mixed_total = raw.mixed_code_single_comment_lines + raw.mixed_code_multi_comment_lines;
    match mixed_line_policy {
        MixedLinePolicy::CodeOnly => effective.code_lines += mixed_total,
        MixedLinePolicy::CodeAndComment => {
            effective.code_lines += mixed_total;
            effective.comment_lines += mixed_total;
        }
        MixedLinePolicy::CommentOnly => effective.comment_lines += mixed_total,
        MixedLinePolicy::SeparateMixedCategory => effective.mixed_lines_separate += mixed_total,
    }

    // IEEE 1045-1992 §4.2: optionally exclude preprocessor/compiler directives from code SLOC.
    // compiler_directive_lines is a subset of code_only_lines, so subtract it directly.
    if !count_compiler_directives {
        effective.code_lines = effective
            .code_lines
            .saturating_sub(raw.compiler_directive_lines);
    }

    effective
}

fn build_summary(analyzed: &[FileRecord], skipped: &[FileRecord]) -> SummaryTotals {
    let mut summary = SummaryTotals {
        files_considered: (analyzed.len() + skipped.len()) as u64,
        files_analyzed: analyzed.len() as u64,
        files_skipped: skipped.len() as u64,
        ..Default::default()
    };

    for record in analyzed {
        summary.total_physical_lines += record.raw_line_categories.total_physical_lines;
        summary.code_lines += record.effective_counts.code_lines;
        summary.comment_lines += record.effective_counts.comment_lines;
        summary.blank_lines += record.effective_counts.blank_lines;
        summary.mixed_lines_separate += record.effective_counts.mixed_lines_separate;
        summary.functions += record.raw_line_categories.functions;
        summary.classes += record.raw_line_categories.classes;
        summary.variables += record.raw_line_categories.variables;
        summary.imports += record.raw_line_categories.imports;
        summary.test_count += record.raw_line_categories.test_count;
        summary.test_assertion_count += record.raw_line_categories.test_assertion_count;
        summary.test_suite_count += record.raw_line_categories.test_suite_count;
        if let Some(cov) = &record.coverage {
            summary.coverage_lines_found += u64::from(cov.lines_found);
            summary.coverage_lines_hit += u64::from(cov.lines_hit);
            summary.coverage_functions_found += u64::from(cov.functions_found);
            summary.coverage_functions_hit += u64::from(cov.functions_hit);
            summary.coverage_branches_found += u64::from(cov.branches_found);
            summary.coverage_branches_hit += u64::from(cov.branches_hit);
        }
    }

    summary
}

/// Construct a zero-filled `LanguageSummary` for the given language.
const fn zeroed_summary(language: Language) -> LanguageSummary {
    LanguageSummary {
        language,
        files: 0,
        total_physical_lines: 0,
        code_lines: 0,
        comment_lines: 0,
        blank_lines: 0,
        mixed_lines_separate: 0,
        functions: 0,
        classes: 0,
        variables: 0,
        imports: 0,
        test_count: 0,
        test_assertion_count: 0,
        test_suite_count: 0,
        coverage_lines_found: 0,
        coverage_lines_hit: 0,
        coverage_functions_found: 0,
        coverage_functions_hit: 0,
        coverage_branches_found: 0,
        coverage_branches_hit: 0,
    }
}

/// Accumulate all per-file counters from `record` into an existing `LanguageSummary`.
fn accumulate_record_into_summary(entry: &mut LanguageSummary, record: &FileRecord) {
    entry.files += 1;
    let r = &record.raw_line_categories;
    entry.total_physical_lines += r.total_physical_lines;
    entry.code_lines += record.effective_counts.code_lines;
    entry.comment_lines += record.effective_counts.comment_lines;
    entry.blank_lines += record.effective_counts.blank_lines;
    entry.mixed_lines_separate += record.effective_counts.mixed_lines_separate;
    entry.functions += r.functions;
    entry.classes += r.classes;
    entry.variables += r.variables;
    entry.imports += r.imports;
    entry.test_count += r.test_count;
    entry.test_assertion_count += r.test_assertion_count;
    entry.test_suite_count += r.test_suite_count;
    if let Some(cov) = &record.coverage {
        entry.coverage_lines_found += u64::from(cov.lines_found);
        entry.coverage_lines_hit += u64::from(cov.lines_hit);
        entry.coverage_functions_found += u64::from(cov.functions_found);
        entry.coverage_functions_hit += u64::from(cov.functions_hit);
        entry.coverage_branches_found += u64::from(cov.branches_found);
        entry.coverage_branches_hit += u64::from(cov.branches_hit);
    }
}

fn build_language_summaries(analyzed: &[FileRecord]) -> Vec<LanguageSummary> {
    let mut by_language: BTreeMap<Language, LanguageSummary> = BTreeMap::new();
    for record in analyzed {
        let Some(language) = record.language else {
            continue;
        };
        let entry = by_language
            .entry(language)
            .or_insert_with(|| zeroed_summary(language));
        accumulate_record_into_summary(entry, record);
    }
    by_language.into_values().collect()
}

fn skipped_record(
    path: &Path,
    root: &Path,
    size_bytes: u64,
    status: FileStatus,
    warnings: Vec<String>,
) -> FileRecord {
    FileRecord {
        path: path_to_string(path),
        relative_path: relative_path_string(path, root),
        language: None,
        size_bytes,
        detected_encoding: None,
        raw_line_categories: RawLineCounts::default(),
        effective_counts: EffectiveCounts::default(),
        status,
        warnings,
        generated: false,
        minified: false,
        vendor: false,
        parse_mode: None,
        submodule: None,
        coverage: None,
        style_analysis: None,
    }
}

fn relative_path_string(path: &Path, root: &Path) -> String {
    path.strip_prefix(root)
        .unwrap_or(path)
        .to_string_lossy()
        .replace('\\', "/")
}

fn path_to_string(path: &Path) -> String {
    path.to_string_lossy().replace('\\', "/")
}

/// Parse `.gitmodules` in `root` and return `(name, relative_path)` for each submodule found.
#[must_use]
pub fn detect_submodules(root: &Path) -> Vec<(String, PathBuf)> {
    let gitmodules = root.join(".gitmodules");
    if !gitmodules.is_file() {
        return Vec::new();
    }
    let Ok(content) = fs::read_to_string(&gitmodules) else {
        return Vec::new();
    };

    let mut result = Vec::new();
    let mut current_name: Option<String> = None;
    let mut current_path: Option<PathBuf> = None;

    for line in content.lines() {
        let trimmed = line.trim();
        if trimmed.starts_with("[submodule \"") && trimmed.ends_with("\"]") {
            if let (Some(name), Some(path)) = (current_name.take(), current_path.take()) {
                result.push((name, path));
            }
            let name = trimmed["[submodule \"".len()..trimmed.len() - 2].to_string();
            current_name = Some(name);
        } else if let Some(rest) = trimmed.strip_prefix("path") {
            if let Some(eq_pos) = rest.find('=') {
                let path_str = rest[eq_pos + 1..].trim();
                current_path = Some(PathBuf::from(path_str));
            }
        }
    }
    if let (Some(name), Some(path)) = (current_name, current_path) {
        result.push((name, path));
    }

    result
}

fn build_submodule_summaries(
    analyzed: &[FileRecord],
    submodules: &[(String, PathBuf)],
) -> Vec<SubmoduleSummary> {
    submodules
        .iter()
        .map(|(name, path)| {
            let files: Vec<&FileRecord> = analyzed
                .iter()
                .filter(|f| f.submodule.as_deref() == Some(name.as_str()))
                .collect();

            let files_analyzed = files.len() as u64;
            let total_physical_lines = files
                .iter()
                .map(|f| f.raw_line_categories.total_physical_lines)
                .sum();
            let code_lines = files.iter().map(|f| f.effective_counts.code_lines).sum();
            let comment_lines = files.iter().map(|f| f.effective_counts.comment_lines).sum();
            let blank_lines = files.iter().map(|f| f.effective_counts.blank_lines).sum();
            let language_summaries = build_language_summaries_from_slice(&files);

            SubmoduleSummary {
                name: name.clone(),
                relative_path: path.to_string_lossy().replace('\\', "/"),
                files_analyzed,
                total_physical_lines,
                code_lines,
                comment_lines,
                blank_lines,
                language_summaries,
            }
        })
        .filter(|s| s.files_analyzed > 0)
        .collect()
}

/// Dominant indent label from vote counts.
#[allow(clippy::cast_possible_truncation, clippy::cast_precision_loss)]
fn dominant_indent_label(files: &[&StyleAnalysis]) -> String {
    let mut votes = [0u32; 6];
    for f in files {
        let idx = match f.indent_style {
            IndentStyle::Tabs => 0,
            IndentStyle::Spaces2 => 1,
            IndentStyle::Spaces4 => 2,
            IndentStyle::Spaces8 => 3,
            IndentStyle::Mixed => 4,
            IndentStyle::Unknown => 5,
        };
        votes[idx] += 1;
    }
    let labels = ["Tabs", "2-Space", "4-Space", "8-Space", "Mixed", "\u{2014}"];
    labels[votes
        .iter()
        .enumerate()
        .max_by_key(|(_, v)| *v)
        .map(|(i, _)| i)
        .unwrap_or(5)]
    .to_string()
}

/// Line-80 compliance percentage for a slice of style analyses.
#[allow(clippy::cast_possible_truncation, clippy::cast_precision_loss)]
fn line80_pct(files: &[&StyleAnalysis]) -> u8 {
    if files.is_empty() {
        return 0;
    }
    let compliant = files
        .iter()
        .filter(|f| f.total_lines == 0 || (f.lines_over_80 as f32 / f.total_lines as f32) <= 0.05)
        .count() as u32;
    ((compliant * 100) / files.len() as u32) as u8
}

/// Build a `LanguageStyleGroup` from a non-empty slice of `StyleAnalysis` for one family.
#[allow(clippy::cast_possible_truncation, clippy::cast_precision_loss)]
fn build_language_group(family: &str, files: &[&StyleAnalysis]) -> LanguageStyleGroup {
    let count = files.len() as u32;

    // Collect every unique guide name across all files in this group.
    let mut all_names: Vec<String> = Vec::new();
    for f in files {
        for g in &f.guide_scores {
            if !all_names.contains(&g.name) {
                all_names.push(g.name.clone());
            }
        }
    }

    let mut guide_avg_scores: Vec<(String, u8)> = all_names
        .into_iter()
        .map(|name| {
            let sum: u32 = files
                .iter()
                .filter_map(|f| f.guide_scores.iter().find(|g| g.name == name))
                .map(|g| u32::from(g.score_pct))
                .sum();
            let avg = (sum / count) as u8;
            (name, avg)
        })
        .collect();
    guide_avg_scores.sort_by_key(|s| std::cmp::Reverse(s.1));

    let (dominant_guide, dominant_score_pct) = guide_avg_scores
        .first()
        .map(|(n, s)| (n.clone(), *s))
        .unwrap_or_default();

    LanguageStyleGroup {
        language_family: family.to_string(),
        files_count: count,
        dominant_guide,
        dominant_score_pct,
        common_indent_style: dominant_indent_label(files),
        guide_avg_scores,
        line80_compliant_pct: line80_pct(files),
    }
}

/// Build aggregate multi-language style-guide adherence.
/// Returns `None` when no files had style data.
#[allow(clippy::cast_possible_truncation, clippy::cast_precision_loss)]
fn build_style_summary(analyzed: &[FileRecord]) -> Option<StyleSummary> {
    let all_style: Vec<&StyleAnalysis> = analyzed
        .iter()
        .filter_map(|f| f.style_analysis.as_ref())
        .collect();

    if all_style.is_empty() {
        return None;
    }

    // Group by language_family.
    let mut families: std::collections::BTreeMap<&str, Vec<&StyleAnalysis>> =
        std::collections::BTreeMap::new();
    for sa in &all_style {
        families
            .entry(sa.language_family.as_str())
            .or_default()
            .push(sa);
    }

    let mut by_language: Vec<LanguageStyleGroup> = families
        .iter()
        .map(|(family, files)| build_language_group(family, files))
        .collect();
    by_language.sort_by_key(|g| std::cmp::Reverse(g.files_count));

    let files_analyzed = all_style.len() as u32;
    let common_indent_style = dominant_indent_label(&all_style);
    let line80_compliant_pct = line80_pct(&all_style);

    Some(StyleSummary {
        files_analyzed,
        common_indent_style,
        line80_compliant_pct,
        by_language,
    })
}

fn build_language_summaries_from_slice(files: &[&FileRecord]) -> Vec<LanguageSummary> {
    let mut map: BTreeMap<String, LanguageSummary> = BTreeMap::new();
    for file in files {
        let Some(lang) = file.language else { continue };
        let entry = map
            .entry(lang.display_name().to_string())
            .or_insert_with(|| zeroed_summary(lang));
        accumulate_record_into_summary(entry, file);
    }
    map.into_values().collect()
}

fn file_name_eq(path: &Path, expected: &str) -> bool {
    path.file_name()
        .and_then(|name| name.to_str())
        .is_some_and(|name| name == expected)
}

fn is_excluded_dir_path(path: &Path, excluded_dirs: &[String]) -> bool {
    path.components().any(|component| {
        component
            .as_os_str()
            .to_str()
            .is_some_and(|part| excluded_dirs.iter().any(|excluded| excluded == part))
    })
}

fn is_vendor_path(path: &Path) -> bool {
    path.components().any(|component| {
        component
            .as_os_str()
            .to_str()
            .is_some_and(|part| matches!(part, "vendor" | "node_modules" | "packages"))
    })
}

fn is_known_lockfile(path: &Path) -> bool {
    path.file_name()
        .and_then(|name| name.to_str())
        .is_some_and(|name| {
            matches!(
                name,
                "Cargo.lock"
                    | "package-lock.json"
                    | "yarn.lock"
                    | "pnpm-lock.yaml"
                    | "Pipfile.lock"
                    | "poetry.lock"
                    | "composer.lock"
            )
        })
}

fn looks_generated(path: &Path, bytes: &[u8]) -> bool {
    let file_name = path
        .file_name()
        .and_then(|name| name.to_str())
        .unwrap_or_default();
    if file_name.contains(".generated.") || file_name.contains(".g.") {
        return true;
    }

    let sample = String::from_utf8_lossy(&bytes[..bytes.len().min(GENERATED_SAMPLE_BYTES)])
        .to_ascii_lowercase();
    sample.contains("@generated") || sample.contains("generated by")
}

fn looks_minified(path: &Path, bytes: &[u8]) -> bool {
    let file_name = path
        .file_name()
        .and_then(|name| name.to_str())
        .unwrap_or_default();
    if file_name.contains(".min.") {
        return true;
    }

    let sample = String::from_utf8_lossy(&bytes[..bytes.len().min(MINIFIED_SAMPLE_BYTES)]);
    let longest_line = sample.lines().map(str::len).max().unwrap_or(0);
    let whitespace = sample.chars().filter(|c| c.is_whitespace()).count();
    longest_line > MINIFIED_LINE_THRESHOLD && whitespace * 100 < sample.len().max(1)
}

fn is_binary(bytes: &[u8]) -> bool {
    if bytes.starts_with(&[0xEF, 0xBB, 0xBF])
        || bytes.starts_with(&[0xFF, 0xFE])
        || bytes.starts_with(&[0xFE, 0xFF])
    {
        return false;
    }

    let sample = &bytes[..bytes.len().min(BINARY_SAMPLE_BYTES)];
    sample.contains(&0)
}

/// Decode a BOM-stripped UTF-16 byte slice using the given encoding.
/// Returns `(text, encoding_label, warnings)`.
fn decode_utf16_bom(
    bom_stripped: &[u8],
    encoding: &'static encoding_rs::Encoding,
    label: &str,
) -> (String, String, Vec<String>) {
    let (cow, _, had_errors) = encoding.decode(bom_stripped);
    let mut warnings = Vec::new();
    if had_errors {
        warnings.push(format!("{label} decode contained replacement characters"));
    }
    (cow.into_owned(), label.into(), warnings)
}

fn decode_bytes(bytes: &[u8]) -> std::result::Result<(String, String, Vec<String>), String> {
    if bytes.starts_with(&[0xEF, 0xBB, 0xBF]) {
        let text = String::from_utf8(bytes[3..].to_vec()).map_err(|err| err.to_string())?;
        return Ok((text, "utf-8-bom".into(), vec![]));
    }
    if bytes.starts_with(&[0xFF, 0xFE]) {
        return Ok(decode_utf16_bom(&bytes[2..], UTF_16LE, "utf-16le"));
    }
    if bytes.starts_with(&[0xFE, 0xFF]) {
        return Ok(decode_utf16_bom(&bytes[2..], UTF_16BE, "utf-16be"));
    }

    // Multiple statements in the else branch make map_or_else awkward here.
    #[allow(clippy::option_if_let_else)]
    if let Ok(text) = String::from_utf8(bytes.to_vec()) {
        Ok((text, "utf-8".into(), vec![]))
    } else {
        let (cow, _, had_errors) = WINDOWS_1252.decode(bytes);
        let mut warnings = vec!["decoded using windows-1252 fallback".into()];
        if had_errors {
            warnings.push("fallback decode contained replacement characters".into());
        }
        Ok((cow.into_owned(), "windows-1252".into(), warnings))
    }
}

fn compile_globset(patterns: &[String]) -> Result<Option<GlobSet>> {
    if patterns.is_empty() {
        return Ok(None);
    }

    let mut builder = GlobSetBuilder::new();
    for pattern in patterns {
        builder
            .add(Glob::new(pattern).with_context(|| format!("invalid glob pattern: {pattern}"))?);
    }
    Ok(Some(
        builder.build().context("failed to compile glob filters")?,
    ))
}

fn parse_enabled_languages(enabled: &[String]) -> Result<Option<BTreeSet<Language>>> {
    if enabled.is_empty() {
        return Ok(None);
    }

    let supported = supported_languages();
    let mut set = BTreeSet::new();
    for name in enabled {
        let language = Language::from_name(name)
            .with_context(|| format!("unsupported language in config: {name}"))?;
        if !supported.contains(&language) {
            anyhow::bail!("language {name} is not supported in this build");
        }
        set.insert(language);
    }
    Ok(Some(set))
}

/// # Errors
///
/// Returns an error if serialization fails or the output file cannot be written.
pub fn write_json(run: &AnalysisRun, output_path: &Path) -> Result<()> {
    let json = serde_json::to_string_pretty(run).context("failed to serialize analysis run")?;
    fs::write(output_path, json)
        .with_context(|| format!("failed to write JSON output to {}", output_path.display()))
}

/// # Errors
///
/// Returns an error if the file cannot be read or the JSON cannot be parsed.
pub fn read_json(path: &Path) -> Result<AnalysisRun> {
    let contents = fs::read_to_string(path)
        .with_context(|| format!("failed to read result file {}", path.display()))?;
    serde_json::from_str(&contents)
        .with_context(|| format!("failed to parse JSON result {}", path.display()))
}

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

    #[test]
    fn effective_counts_respect_code_only_policy() {
        let raw = RawLineCounts {
            code_only_lines: 2,
            single_comment_only_lines: 1,
            mixed_code_single_comment_lines: 3,
            docstring_comment_lines: 2,
            ..RawLineCounts::default()
        };
        let counts = compute_effective_counts(&raw, MixedLinePolicy::CodeOnly, true, true);
        assert_eq!(counts.code_lines, 5);
        assert_eq!(counts.comment_lines, 3);
    }

    #[test]
    fn effective_counts_can_separate_mixed() {
        let raw = RawLineCounts {
            mixed_code_single_comment_lines: 2,
            mixed_code_multi_comment_lines: 1,
            ..RawLineCounts::default()
        };
        let counts =
            compute_effective_counts(&raw, MixedLinePolicy::SeparateMixedCategory, true, true);
        assert_eq!(counts.mixed_lines_separate, 3);
        assert_eq!(counts.code_lines, 0);
        assert_eq!(counts.comment_lines, 0);
    }

    #[test]
    fn windows_1252_fallback_decodes() {
        let bytes = vec![0x48, 0x65, 0x6c, 0x6c, 0x6f, 0x96, 0x57];
        let (text, encoding, warnings) = decode_bytes(&bytes).unwrap();
        assert_eq!(encoding, "windows-1252");
        assert!(text.contains('–'));
        assert!(!warnings.is_empty());
    }
}