projd_core/

lib.rs

use std::collections::BTreeMap;
use std::ffi::OsStr;
use std::fs;
use std::path::{Component, Path, PathBuf};
use std::process::Command;

use anyhow::{Context, Result, bail};
use ignore::gitignore::{Gitignore, GitignoreBuilder};
use serde::{Deserialize, Serialize};

pub mod discover;

pub use discover::{
    Confidence, DiscoverOptions, DiscoverSummary, DiscoveredRoot, RootCategory, RootKind,
    category_token, discover_roots, relative_display, render_discover_json,
    render_discover_markdown, summarize_roots,
};

pub const NAME: &str = "Projd";
pub const VERSION: &str = env!("CARGO_PKG_VERSION");

pub fn describe() -> &'static str {
    "Scan software projects and generate structured reports."
}

#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct ProjectScan {
    pub root: PathBuf,
    pub project_name: String,
    pub identity: ProjectIdentity,
    pub indicators: Vec<ProjectIndicator>,
    pub languages: Vec<LanguageSummary>,
    pub build_systems: Vec<BuildSystemSummary>,
    pub code: CodeSummary,
    pub dependencies: DependencySummary,
    pub tests: TestSummary,
    pub hygiene: ScanHygiene,
    pub risks: RiskSummary,
    pub health: HealthSummary,
    pub documentation: DocumentationSummary,
    pub license: LicenseSummary,
    pub ci: CiSummary,
    pub vcs: VcsSummary,
    pub containers: ContainerSummary,
    pub files_scanned: usize,
    pub skipped_dirs: Vec<PathBuf>,
    pub report: ProjectReport,
}

impl ProjectScan {
    pub fn has_language(&self, kind: LanguageKind) -> bool {
        self.languages.iter().any(|language| language.kind == kind)
    }

    pub fn has_build_system(&self, kind: BuildSystemKind) -> bool {
        self.build_systems
            .iter()
            .any(|build_system| build_system.kind == kind)
    }

    pub fn has_risk(&self, code: RiskCode) -> bool {
        self.risks.findings.iter().any(|risk| risk.code == code)
    }

    pub fn risk(&self, code: RiskCode) -> Option<&RiskFinding> {
        self.risks.findings.iter().find(|risk| risk.code == code)
    }
}

#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct ProjectIdentity {
    pub name: String,
    pub version: Option<String>,
    pub kind: ProjectKind,
    pub source: IdentitySource,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum ProjectKind {
    RustWorkspace,
    RustPackage,
    NodePackage,
    PythonProject,
    Generic,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum IdentitySource {
    CargoToml,
    PackageJson,
    PyprojectToml,
    DirectoryName,
}

#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct ProjectIndicator {
    pub kind: IndicatorKind,
    pub path: PathBuf,
}

#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum IndicatorKind {
    RustWorkspace,
    RustPackage,
    GitRepository,
    Readme,
}

#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct LanguageSummary {
    pub kind: LanguageKind,
    pub files: usize,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum LanguageKind {
    Rust,
    TypeScript,
    JavaScript,
    Python,
    C,
    Cpp,
    Go,
}

#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct BuildSystemSummary {
    pub kind: BuildSystemKind,
    pub path: PathBuf,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum BuildSystemKind {
    Cargo,
    NodePackage,
    PythonProject,
    PythonRequirements,
    CMake,
    GoModule,
}

#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
pub struct CodeSummary {
    pub languages: Vec<CodeLanguageSummary>,
    pub total_files: usize,
    pub total_lines: usize,
    pub code_lines: usize,
    pub comment_lines: usize,
    pub blank_lines: usize,
}

#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct CodeLanguageSummary {
    pub kind: LanguageKind,
    pub files: usize,
    pub total_lines: usize,
    pub code_lines: usize,
    pub comment_lines: usize,
    pub blank_lines: usize,
}

#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
struct CodeLineCounts {
    total_lines: usize,
    code_lines: usize,
    comment_lines: usize,
    blank_lines: usize,
}

#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
pub struct DependencySummary {
    pub ecosystems: Vec<DependencyEcosystemSummary>,
    pub total_manifests: usize,
    pub total_dependencies: usize,
}

#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct DependencyEcosystemSummary {
    pub ecosystem: DependencyEcosystem,
    pub source: DependencySource,
    pub manifest: PathBuf,
    pub lockfile: Option<PathBuf>,
    pub normal: usize,
    pub development: usize,
    pub build: usize,
    pub optional: usize,
    pub total: usize,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum DependencyEcosystem {
    Rust,
    Node,
    Python,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum DependencySource {
    CargoToml,
    PackageJson,
    PyprojectToml,
    RequirementsTxt,
}

#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
pub struct TestSummary {
    pub has_tests_dir: bool,
    pub test_files: usize,
    pub test_directories: Vec<PathBuf>,
    pub commands: Vec<TestCommand>,
}

#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct TestCommand {
    pub ecosystem: TestEcosystem,
    pub source: PathBuf,
    pub name: String,
    pub command: String,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum TestEcosystem {
    Rust,
    Node,
    Python,
    CMake,
}

#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
pub struct ScanHygiene {
    pub has_gitignore: bool,
    pub has_ignore: bool,
}

#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
pub struct RiskSummary {
    pub findings: Vec<RiskFinding>,
    pub total: usize,
    pub high: usize,
    pub medium: usize,
    pub low: usize,
    pub info: usize,
}

#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct RiskFinding {
    pub severity: RiskSeverity,
    pub code: RiskCode,
    pub message: String,
    pub path: Option<PathBuf>,
}

#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct HealthSummary {
    pub grade: ProjectHealth,
    pub score: usize,
    pub risk_level: RiskSeverity,
    pub signals: Vec<HealthSignal>,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, Hash, Ord, PartialOrd, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum ProjectHealth {
    Healthy,
    NeedsAttention,
    Risky,
    Unknown,
}

#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct HealthSignal {
    pub kind: HealthSignalKind,
    pub status: HealthSignalStatus,
    pub score_delta: i32,
    pub evidence: String,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum HealthSignalKind {
    Readme,
    License,
    Ci,
    Tests,
    Lockfiles,
    Vcs,
    Activity,
    Docs,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum HealthSignalStatus {
    Pass,
    Warn,
    Info,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, Hash, Ord, PartialOrd, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum RiskSeverity {
    High,
    Medium,
    Low,
    Info,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum RiskCode {
    MissingReadme,
    MissingLicense,
    MissingCi,
    NoTestsDetected,
    ManifestWithoutLockfile,
    LargeProjectWithoutIgnoreRules,
    UnknownLicense,
    MultipleVcsRootsFound,
    NestedVcsRoot,
}

#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
pub struct DocumentationSummary {
    pub has_readme: bool,
    pub has_license: bool,
    pub has_docs_dir: bool,
}

#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
pub struct LicenseSummary {
    pub path: Option<PathBuf>,
    pub kind: LicenseKind,
}

#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum LicenseKind {
    Mit,
    Apache2,
    Gpl,
    Bsd,
    #[default]
    Unknown,
    Missing,
}

#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
pub struct CiSummary {
    pub has_github_actions: bool,
    pub has_gitee_go: bool,
    pub has_gitlab_ci: bool,
    pub has_circle_ci: bool,
    pub has_jenkins: bool,
    pub providers: Vec<CiProviderSummary>,
}

#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct CiProviderSummary {
    pub provider: CiProvider,
    pub path: PathBuf,
}

#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum CiProvider {
    GithubActions,
    GiteeGo,
    GitlabCi,
    CircleCi,
    Jenkins,
}

impl CiSummary {
    pub fn has_provider(&self, provider: CiProvider) -> bool {
        match provider {
            CiProvider::GithubActions => self.has_github_actions,
            CiProvider::GiteeGo => self.has_gitee_go,
            CiProvider::GitlabCi => self.has_gitlab_ci,
            CiProvider::CircleCi => self.has_circle_ci,
            CiProvider::Jenkins => self.has_jenkins,
        }
    }

    fn has_any_provider(&self) -> bool {
        !self.providers.is_empty()
            || self.has_github_actions
            || self.has_gitee_go
            || self.has_gitlab_ci
            || self.has_circle_ci
            || self.has_jenkins
    }

    fn add_provider(&mut self, provider: CiProvider, path: PathBuf) {
        match provider {
            CiProvider::GithubActions => self.has_github_actions = true,
            CiProvider::GiteeGo => self.has_gitee_go = true,
            CiProvider::GitlabCi => self.has_gitlab_ci = true,
            CiProvider::CircleCi => self.has_circle_ci = true,
            CiProvider::Jenkins => self.has_jenkins = true,
        }

        if self
            .providers
            .iter()
            .any(|existing| existing.provider == provider && existing.path == path)
        {
            return;
        }

        self.providers.push(CiProviderSummary { provider, path });
    }
}

#[derive(Clone, Copy, Debug, Default, Eq, PartialEq, Hash, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum VcsKind {
    #[default]
    None,
    Git,
    Hg,
    Svn,
    Fossil,
    Bzr,
}

impl VcsKind {
    pub fn label(self) -> &'static str {
        match self {
            Self::None => "none",
            Self::Git => "git",
            Self::Hg => "hg",
            Self::Svn => "svn",
            Self::Fossil => "fossil",
            Self::Bzr => "bzr",
        }
    }

    /// Display label for the `branch` field. SVN uses URL semantics; others use
    /// branch names.
    pub fn ref_label(self) -> &'static str {
        match self {
            Self::Svn => "URL",
            _ => "Branch",
        }
    }
}

#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
pub struct VcsSummary {
    pub kind: VcsKind,
    pub is_repository: bool,
    pub root: Option<PathBuf>,
    /// git/hg/fossil/bzr: branch name. svn: repository URL.
    pub branch: Option<String>,
    /// Latest revision identifier (commit hash, changeset id, svn revision number).
    pub revision: Option<String>,
    /// ISO-style timestamp of the latest commit, format passed through from the VCS.
    pub last_commit: Option<String>,
    pub is_dirty: bool,
    pub tracked_modified_files: usize,
    pub untracked_files: usize,
    pub activity: VcsActivity,
}

#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
pub struct VcsActivity {
    pub days_since_last_commit: Option<u32>,
    pub commits_last_90d: Option<u32>,
    pub contributors_count: Option<u32>,
    /// ISO-style timestamp of the repository's first commit (may be misleading
    /// for shallow clones).
    pub first_commit_date: Option<String>,
    /// Per-contributor breakdown. Always empty unless `ScanOptions.detailed_contributors`
    /// was set on the scan that produced this summary.
    pub contributors: Vec<VcsContributor>,
}

#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct VcsContributor {
    pub name: String,
    pub email: String,
    pub commit_count: u32,
}

#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
pub struct ContainerSummary {
    pub has_dockerfile: bool,
    pub has_compose_file: bool,
}

#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct ProjectReport {
    pub summary: String,
    pub next_steps: Vec<String>,
}

#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct MultiProjectScan {
    pub root: PathBuf,
    pub summary: MultiProjectSummary,
    pub roots: Vec<ProjectScan>,
    pub skipped: Vec<MultiProjectScanError>,
}

#[derive(Clone, Debug, Default, Eq, PartialEq, Serialize, Deserialize)]
pub struct MultiProjectSummary {
    pub total: usize,
    pub by_kind: BTreeMap<RootKind, usize>,
    pub by_grade: BTreeMap<ProjectHealth, usize>,
    pub by_risk_level: BTreeMap<RiskSeverity, usize>,
    pub files_scanned: usize,
}

#[derive(Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub struct MultiProjectScanError {
    pub path: PathBuf,
    pub message: String,
}

/// Options that adjust how `scan_path_with` (and `scan_paths_recursive`) build
/// the resulting `ProjectScan`. Defaults stay conservative: no personal data
/// is collected.
#[derive(Clone, Debug, Default)]
pub struct ScanOptions {
    /// When true, populate `VcsActivity.contributors` with names/emails parsed
    /// from `git shortlog`. Defaults to false to keep privacy-sensitive data
    /// off by default.
    pub detailed_contributors: bool,
}

pub fn scan_path(path: impl AsRef<Path>) -> Result<ProjectScan> {
    scan_path_with(path, &ScanOptions::default())
}

pub fn scan_path_with(path: impl AsRef<Path>, opts: &ScanOptions) -> Result<ProjectScan> {
    let root = path.as_ref();
    let metadata =
        fs::metadata(root).with_context(|| format!("failed to inspect `{}`", root.display()))?;

    if !metadata.is_dir() {
        bail!("project path must be a directory: `{}`", root.display());
    }

    let root = root
        .canonicalize()
        .with_context(|| format!("failed to resolve `{}`", root.display()))?;
    let project_name = root
        .file_name()
        .and_then(|value| value.to_str())
        .unwrap_or("project")
        .to_owned();
    let identity = detect_identity(&root, &project_name);
    let indicators = detect_indicators(&root);
    let inventory = scan_inventory(&root)?;
    let multi_root_check = detect_multi_root_situation(&root);
    let risks = build_risk_summary(&inventory, &multi_root_check);
    let vcs = detect_vcs_summary(&root, opts);
    let health = build_health_summary(&inventory, &risks, &vcs);
    let report = build_report(&identity.name, &indicators, &inventory, &health);

    Ok(ProjectScan {
        root,
        project_name: identity.name.clone(),
        identity,
        indicators,
        languages: inventory.languages,
        build_systems: inventory.build_systems,
        code: inventory.code,
        dependencies: inventory.dependencies,
        tests: inventory.tests,
        hygiene: inventory.hygiene,
        risks,
        health,
        documentation: inventory.documentation,
        license: inventory.license,
        ci: inventory.ci,
        vcs,
        containers: inventory.containers,
        files_scanned: inventory.files_scanned,
        skipped_dirs: inventory.skipped_dirs,
        report,
    })
}

pub fn scan_paths_recursive(
    path: impl AsRef<Path>,
    opts: &discover::DiscoverOptions,
) -> Result<MultiProjectScan> {
    scan_paths_recursive_with(path, opts, &ScanOptions::default())
}

pub fn scan_paths_recursive_with(
    path: impl AsRef<Path>,
    discover_opts: &discover::DiscoverOptions,
    scan_opts: &ScanOptions,
) -> Result<MultiProjectScan> {
    let input = path.as_ref();
    let canonical = fs::canonicalize(input)
        .with_context(|| format!("failed to resolve `{}`", input.display()))?;
    if !canonical.is_dir() {
        bail!("`{}` is not a directory", canonical.display());
    }

    let roots = discover::discover_roots(&canonical, discover_opts)?;

    let mut scans: Vec<ProjectScan> = Vec::new();
    let mut skipped: Vec<MultiProjectScanError> = Vec::new();
    for entry in &roots {
        match scan_path_with(&entry.path, scan_opts) {
            Ok(scan) => scans.push(scan),
            Err(err) => skipped.push(MultiProjectScanError {
                path: entry.path.clone(),
                message: format!("{err:#}"),
            }),
        }
    }

    let summary = build_multi_summary(&roots, &scans);

    Ok(MultiProjectScan {
        root: canonical,
        summary,
        roots: scans,
        skipped,
    })
}

fn build_multi_summary(
    discovered: &[discover::DiscoveredRoot],
    scans: &[ProjectScan],
) -> MultiProjectSummary {
    let mut by_kind: BTreeMap<RootKind, usize> = BTreeMap::new();
    for entry in discovered {
        for kind in &entry.kinds {
            *by_kind.entry(*kind).or_insert(0) += 1;
        }
    }

    let mut by_grade: BTreeMap<ProjectHealth, usize> = BTreeMap::new();
    let mut by_risk_level: BTreeMap<RiskSeverity, usize> = BTreeMap::new();
    let mut files_scanned = 0usize;
    for scan in scans {
        *by_grade.entry(scan.health.grade).or_insert(0) += 1;
        *by_risk_level.entry(scan.health.risk_level).or_insert(0) += 1;
        files_scanned = files_scanned.saturating_add(scan.files_scanned);
    }

    MultiProjectSummary {
        total: scans.len(),
        by_kind,
        by_grade,
        by_risk_level,
        files_scanned,
    }
}

pub fn render_multi_markdown(scan: &MultiProjectScan) -> String {
    let mut out = String::new();
    out.push_str("# Projd Recursive Scan Report\n\n");
    out.push_str(&format!("- Root: `{}`\n", scan.root.display()));
    out.push_str(&format!("- Total project roots: {}\n", scan.summary.total));
    if !scan.summary.by_grade.is_empty() {
        let parts: Vec<String> = [
            ProjectHealth::Healthy,
            ProjectHealth::NeedsAttention,
            ProjectHealth::Risky,
            ProjectHealth::Unknown,
        ]
        .iter()
        .filter_map(|grade| {
            scan.summary
                .by_grade
                .get(grade)
                .map(|count| format!("{}: {}", grade.as_str(), count))
        })
        .collect();
        if !parts.is_empty() {
            out.push_str(&format!("- Grade: {}\n", parts.join(" / ")));
        }
    }
    if !scan.summary.by_risk_level.is_empty() {
        let parts: Vec<String> = [
            RiskSeverity::High,
            RiskSeverity::Medium,
            RiskSeverity::Low,
            RiskSeverity::Info,
        ]
        .iter()
        .filter_map(|level| {
            scan.summary
                .by_risk_level
                .get(level)
                .map(|count| format!("{}: {}", level.as_str(), count))
        })
        .collect();
        if !parts.is_empty() {
            out.push_str(&format!("- Risk level: {}\n", parts.join(" / ")));
        }
    }
    out.push_str(&format!(
        "- Files scanned: {}\n",
        scan.summary.files_scanned
    ));
    if !scan.skipped.is_empty() {
        out.push_str(&format!("- Skipped: {}\n", scan.skipped.len()));
    }
    out.push('\n');

    if scan.roots.is_empty() {
        out.push_str("No project roots found.\n");
        if !scan.skipped.is_empty() {
            out.push_str("\n## Skipped\n\n");
            for entry in &scan.skipped {
                out.push_str(&format!(
                    "- `{}`: {}\n",
                    entry.path.display(),
                    entry.message
                ));
            }
        }
        return out;
    }

    for (index, project) in scan.roots.iter().enumerate() {
        let rel = discover::relative_display(&scan.root, &project.root);
        out.push_str(&format!(
            "## [{}/{}] `{}` — {} ({})\n\n",
            index + 1,
            scan.roots.len(),
            rel,
            project.health.grade.as_str(),
            project.health.score
        ));
        out.push_str(&render_markdown(project));
        out.push('\n');
    }

    if !scan.skipped.is_empty() {
        out.push_str("## Skipped\n\n");
        for entry in &scan.skipped {
            out.push_str(&format!(
                "- `{}`: {}\n",
                entry.path.display(),
                entry.message
            ));
        }
    }
    out
}

pub fn render_multi_json(scan: &MultiProjectScan) -> Result<String> {
    serde_json::to_string_pretty(scan).context("failed to serialize MultiProjectScan as JSON")
}

pub fn render_markdown(scan: &ProjectScan) -> String {
    let mut output = String::new();
    output.push_str("# Project Report\n\n");
    output.push_str(&format!("Project: `{}`\n\n", scan.project_name));
    output.push_str(&format!("Root: `{}`\n\n", scan.root.display()));
    output.push_str("## Identity\n\n");
    output.push_str(&format!("- Name: `{}`\n", scan.identity.name));
    output.push_str(&format!(
        "- Version: {}\n",
        scan.identity
            .version
            .as_deref()
            .map(|version| format!("`{version}`"))
            .unwrap_or_else(|| "unknown".to_owned())
    ));
    output.push_str(&format!("- Kind: {:?}\n", scan.identity.kind));
    output.push_str(&format!("- Source: {:?}\n\n", scan.identity.source));
    output.push_str("## Summary\n\n");
    output.push_str(&scan.report.summary);
    output.push_str("\n\n## Health\n\n");
    output.push_str(&format!("- Grade: `{}`\n", scan.health.grade.as_str()));
    output.push_str(&format!("- Score: {}/100\n", scan.health.score));
    output.push_str(&format!(
        "- Risk level: `{}`\n",
        scan.health.risk_level.as_str()
    ));
    output.push_str("- Signals:\n");
    for signal in &scan.health.signals {
        output.push_str(&format!(
            "  - {}: {} ({:+}) - {}\n",
            signal.kind.as_str(),
            signal.status.as_str(),
            signal.score_delta,
            signal.evidence
        ));
    }

    output.push_str("\n## Scan Observations\n\n");
    output.push_str(&format!("- Files scanned: {}\n", scan.files_scanned));
    output.push_str(&format!(
        "- Skipped directories: {}\n",
        scan.skipped_dirs.len()
    ));
    output.push_str(&format!(
        "- `.gitignore`: {}\n",
        yes_no(scan.hygiene.has_gitignore)
    ));
    output.push_str(&format!(
        "- `.ignore`: {}\n",
        yes_no(scan.hygiene.has_ignore)
    ));

    output.push_str("\n## Indicators\n\n");

    if scan.indicators.is_empty() {
        output.push_str("- No known project indicators detected.\n");
    } else {
        for indicator in &scan.indicators {
            output.push_str(&format!(
                "- {:?}: `{}`\n",
                indicator.kind,
                indicator.path.display()
            ));
        }
    }

    output.push_str("\n## Languages\n\n");
    if scan.languages.is_empty() {
        output.push_str("- No source language files detected.\n");
    } else {
        for language in &scan.languages {
            output.push_str(&format!(
                "- {:?}: {} file(s)\n",
                language.kind, language.files
            ));
        }
    }

    output.push_str("\n## Code Statistics\n\n");
    output.push_str(&format!(
        "- Total source files: {}\n",
        scan.code.total_files
    ));
    output.push_str(&format!("- Total lines: {}\n", scan.code.total_lines));
    output.push_str(&format!("- Code lines: {}\n", scan.code.code_lines));
    output.push_str(&format!("- Comment lines: {}\n", scan.code.comment_lines));
    output.push_str(&format!("- Blank lines: {}\n", scan.code.blank_lines));
    if scan.code.languages.is_empty() {
        output.push_str("- No code statistics detected.\n");
    } else {
        output.push_str("- By language:\n");
        for language in &scan.code.languages {
            output.push_str(&format!(
                "  - {:?}: {} file(s), {} total, {} code, {} comment, {} blank\n",
                language.kind,
                language.files,
                language.total_lines,
                language.code_lines,
                language.comment_lines,
                language.blank_lines
            ));
        }
    }

    output.push_str("\n## Build Systems\n\n");
    if scan.build_systems.is_empty() {
        output.push_str("- No known build systems detected.\n");
    } else {
        for build_system in &scan.build_systems {
            output.push_str(&format!(
                "- {:?}: `{}`\n",
                build_system.kind,
                build_system.path.display()
            ));
        }
    }

    output.push_str("\n## Dependencies\n\n");
    output.push_str(&format!(
        "- Total manifests: {}\n",
        scan.dependencies.total_manifests
    ));
    output.push_str(&format!(
        "- Total dependency entries: {}\n",
        scan.dependencies.total_dependencies
    ));
    if scan.dependencies.ecosystems.is_empty() {
        output.push_str("- No dependency manifests detected.\n");
    } else {
        for summary in &scan.dependencies.ecosystems {
            output.push_str(&format!(
                "- {:?} {:?}: `{}` normal {}, dev {}, build {}, optional {}, total {}, lockfile {}\n",
                summary.ecosystem,
                summary.source,
                summary.manifest.display(),
                summary.normal,
                summary.development,
                summary.build,
                summary.optional,
                summary.total,
                yes_no(summary.lockfile.is_some())
            ));
        }
    }

    output.push_str("\n## Tests\n\n");
    output.push_str(&format!(
        "- Test directories: {}\n",
        scan.tests.test_directories.len()
    ));
    output.push_str(&format!("- Test files: {}\n", scan.tests.test_files));
    if scan.tests.commands.is_empty() {
        output.push_str("- Commands: none detected\n");
    } else {
        output.push_str("- Commands:\n");
        for command in &scan.tests.commands {
            output.push_str(&format!(
                "  - {:?}: {} (`{}`)\n",
                command.ecosystem,
                command.command,
                command.source.display()
            ));
        }
    }

    output.push_str("\n## Risks\n\n");
    if scan.risks.findings.is_empty() {
        output.push_str("- No risks detected by current rules.\n");
    } else {
        for risk in &scan.risks.findings {
            output.push_str(&format!(
                "- {} {}: {}",
                risk.severity.as_str(),
                risk.code.as_str(),
                risk.message
            ));
            if let Some(path) = &risk.path {
                output.push_str(&format!(" (`{}`)", path.display()));
            }
            output.push('\n');
        }
    }

    output.push_str("\n## Project Facilities\n\n");
    output.push_str(&format!(
        "- README: {}\n",
        yes_no(scan.documentation.has_readme)
    ));
    output.push_str(&format!(
        "- License: {}\n",
        yes_no(scan.documentation.has_license)
    ));
    output.push_str(&format!("- License kind: {:?}\n", scan.license.kind));
    output.push_str(&format!(
        "- docs/: {}\n",
        yes_no(scan.documentation.has_docs_dir)
    ));
    output.push_str(&format!(
        "- GitHub Actions: {}\n",
        yes_no(scan.ci.has_github_actions)
    ));
    output.push_str(&format!("- Gitee Go: {}\n", yes_no(scan.ci.has_gitee_go)));
    output.push_str(&format!("- GitLab CI: {}\n", yes_no(scan.ci.has_gitlab_ci)));
    output.push_str(&format!("- CircleCI: {}\n", yes_no(scan.ci.has_circle_ci)));
    output.push_str(&format!("- Jenkins: {}\n", yes_no(scan.ci.has_jenkins)));
    output.push_str(&format!(
        "- {} repository: {}\n",
        scan.vcs.kind.label(),
        yes_no(scan.vcs.is_repository)
    ));
    if let Some(days) = scan.vcs.activity.days_since_last_commit {
        output.push_str(&format!("- Activity: last commit {days} day(s) ago\n"));
    }
    if let Some(count) = scan.vcs.activity.commits_last_90d {
        output.push_str(&format!("- Commits (90d): {count}\n"));
    }
    if let Some(count) = scan.vcs.activity.contributors_count {
        output.push_str(&format!("- Contributors: {count}\n"));
    }
    if let Some(first) = &scan.vcs.activity.first_commit_date {
        output.push_str(&format!("- First commit: {first}\n"));
    }
    output.push_str(&format!(
        "- Dockerfile: {}\n",
        yes_no(scan.containers.has_dockerfile)
    ));
    output.push_str(&format!(
        "- Compose file: {}\n",
        yes_no(scan.containers.has_compose_file)
    ));

    output.push_str("\n## Next Steps\n\n");
    for step in &scan.report.next_steps {
        output.push_str(&format!("- {step}\n"));
    }

    output
}

pub fn render_json(scan: &ProjectScan) -> Result<String> {
    serde_json::to_string_pretty(scan).context("failed to render scan result as json")
}

struct ScanInventory {
    languages: Vec<LanguageSummary>,
    build_systems: Vec<BuildSystemSummary>,
    code: CodeSummary,
    dependencies: DependencySummary,
    tests: TestSummary,
    hygiene: ScanHygiene,
    documentation: DocumentationSummary,
    license: LicenseSummary,
    ci: CiSummary,
    containers: ContainerSummary,
    files_scanned: usize,
    skipped_dirs: Vec<PathBuf>,
}

fn detect_identity(root: &Path, fallback_name: &str) -> ProjectIdentity {
    detect_cargo_identity(root, fallback_name)
        .or_else(|| detect_node_identity(root))
        .or_else(|| detect_python_identity(root))
        .unwrap_or_else(|| ProjectIdentity {
            name: fallback_name.to_owned(),
            version: None,
            kind: ProjectKind::Generic,
            source: IdentitySource::DirectoryName,
        })
}

fn detect_cargo_identity(root: &Path, fallback_name: &str) -> Option<ProjectIdentity> {
    let manifest = read_toml_value(&root.join("Cargo.toml"))?;

    if let Some(package) = manifest.get("package") {
        let name = package.get("name")?.as_str()?.to_owned();
        let version = package
            .get("version")
            .and_then(|value| value.as_str())
            .map(str::to_owned);

        return Some(ProjectIdentity {
            name,
            version,
            kind: ProjectKind::RustPackage,
            source: IdentitySource::CargoToml,
        });
    }

    if manifest.get("workspace").is_some() {
        let version = manifest
            .get("workspace")
            .and_then(|workspace| workspace.get("package"))
            .and_then(|package| package.get("version"))
            .and_then(|value| value.as_str())
            .map(str::to_owned);

        return Some(ProjectIdentity {
            name: fallback_name.to_owned(),
            version,
            kind: ProjectKind::RustWorkspace,
            source: IdentitySource::CargoToml,
        });
    }

    None
}

fn detect_node_identity(root: &Path) -> Option<ProjectIdentity> {
    let manifest = read_json_value(&root.join("package.json"))?;
    let name = manifest.get("name")?.as_str()?.to_owned();
    let version = manifest
        .get("version")
        .and_then(|value| value.as_str())
        .map(str::to_owned);

    Some(ProjectIdentity {
        name,
        version,
        kind: ProjectKind::NodePackage,
        source: IdentitySource::PackageJson,
    })
}

fn detect_python_identity(root: &Path) -> Option<ProjectIdentity> {
    let manifest = read_toml_value(&root.join("pyproject.toml"))?;
    let project = manifest.get("project")?;
    let name = project.get("name")?.as_str()?.to_owned();
    let version = project
        .get("version")
        .and_then(|value| value.as_str())
        .map(str::to_owned);

    Some(ProjectIdentity {
        name,
        version,
        kind: ProjectKind::PythonProject,
        source: IdentitySource::PyprojectToml,
    })
}

fn read_toml_value(path: &Path) -> Option<toml::Value> {
    let content = fs::read_to_string(path).ok()?;
    toml::from_str(&content).ok()
}

fn read_json_value(path: &Path) -> Option<serde_json::Value> {
    let content = fs::read_to_string(path).ok()?;
    serde_json::from_str(&content).ok()
}

fn build_dependency_summary(manifests: Vec<PathBuf>) -> DependencySummary {
    let mut ecosystems = Vec::new();

    for manifest in manifests {
        let Some(file_name) = manifest.file_name().and_then(|value| value.to_str()) else {
            continue;
        };

        let summary = match file_name {
            "Cargo.toml" => summarize_cargo_dependencies(&manifest),
            "package.json" => summarize_node_dependencies(&manifest),
            "pyproject.toml" => summarize_pyproject_dependencies(&manifest),
            "requirements.txt" => summarize_requirements_dependencies(&manifest),
            _ => None,
        };

        if let Some(summary) = summary {
            ecosystems.push(summary);
        }
    }

    let total_manifests = ecosystems.len();
    let total_dependencies = ecosystems.iter().map(|summary| summary.total).sum();

    DependencySummary {
        ecosystems,
        total_manifests,
        total_dependencies,
    }
}

fn build_test_summary(mut tests: TestSummary, sources: Vec<PathBuf>) -> TestSummary {
    for source in sources {
        let Some(file_name) = source.file_name().and_then(|value| value.to_str()) else {
            continue;
        };

        match file_name {
            "Cargo.toml" => add_rust_test_command(&mut tests, &source),
            "package.json" => add_node_test_commands(&mut tests, &source),
            "pyproject.toml" => add_python_test_command(&mut tests, &source),
            "CMakeLists.txt" => add_cmake_test_command(&mut tests, &source),
            _ => {}
        }
    }

    tests
}

struct MultiRootCheck {
    siblings: Vec<PathBuf>,
    nested: Vec<PathBuf>,
}

fn detect_multi_root_situation(root: &Path) -> MultiRootCheck {
    let default_opts = discover::DiscoverOptions {
        min_confidence: discover::Confidence::Strong,
        ..discover::DiscoverOptions::default()
    };
    let default_roots = discover::discover_roots(root, &default_opts).unwrap_or_default();
    let siblings: Vec<PathBuf> = default_roots
        .iter()
        .filter(|entry| entry.path != root)
        .map(|entry| entry.path.clone())
        .collect();

    let nested_opts = discover::DiscoverOptions {
        min_confidence: discover::Confidence::Strong,
        nested_vcs: true,
        ..discover::DiscoverOptions::default()
    };
    let nested_roots_all = discover::discover_roots(root, &nested_opts).unwrap_or_default();
    let nested: Vec<PathBuf> = nested_roots_all
        .iter()
        .filter(|entry| !default_roots.iter().any(|d| d.path == entry.path))
        .map(|entry| entry.path.clone())
        .collect();

    MultiRootCheck { siblings, nested }
}

fn build_risk_summary(inventory: &ScanInventory, multi_root: &MultiRootCheck) -> RiskSummary {
    let mut findings = Vec::new();

    if !inventory.documentation.has_readme {
        findings.push(RiskFinding {
            severity: RiskSeverity::Medium,
            code: RiskCode::MissingReadme,
            message: "No README file detected.".to_owned(),
            path: None,
        });
    }

    if !inventory.documentation.has_license {
        findings.push(RiskFinding {
            severity: RiskSeverity::Medium,
            code: RiskCode::MissingLicense,
            message: "No LICENSE file detected.".to_owned(),
            path: None,
        });
    } else if inventory.license.kind == LicenseKind::Unknown {
        findings.push(RiskFinding {
            severity: RiskSeverity::Low,
            code: RiskCode::UnknownLicense,
            message: "License file was detected, but the license type was not recognized."
                .to_owned(),
            path: inventory.license.path.clone(),
        });
    }

    if !inventory.ci.has_any_provider() {
        findings.push(RiskFinding {
            severity: RiskSeverity::Low,
            code: RiskCode::MissingCi,
            message: "No known CI workflow detected.".to_owned(),
            path: None,
        });
    }

    if inventory.tests.test_files == 0 && inventory.tests.commands.is_empty() {
        findings.push(RiskFinding {
            severity: RiskSeverity::Medium,
            code: RiskCode::NoTestsDetected,
            message: "No test files or test commands detected.".to_owned(),
            path: None,
        });
    }

    for summary in &inventory.dependencies.ecosystems {
        if summary.total > 0 && summary.lockfile.is_none() {
            findings.push(RiskFinding {
                severity: RiskSeverity::Low,
                code: RiskCode::ManifestWithoutLockfile,
                message: "Dependency manifest has entries but no lockfile was detected.".to_owned(),
                path: Some(summary.manifest.clone()),
            });
        }
    }

    if inventory.files_scanned >= 1000
        && !inventory.hygiene.has_gitignore
        && !inventory.hygiene.has_ignore
    {
        findings.push(RiskFinding {
            severity: RiskSeverity::Info,
            code: RiskCode::LargeProjectWithoutIgnoreRules,
            message: "Large project scanned without .gitignore or .ignore rules.".to_owned(),
            path: None,
        });
    }

    if multi_root.siblings.len() >= 2 {
        findings.push(RiskFinding {
            severity: RiskSeverity::Medium,
            code: RiskCode::MultipleVcsRootsFound,
            message: format!(
                "{} additional project root(s) detected under this path; consider `projd scan --recursive` or `projd discover`.",
                multi_root.siblings.len()
            ),
            path: None,
        });
    }

    if !multi_root.nested.is_empty() {
        findings.push(RiskFinding {
            severity: RiskSeverity::Low,
            code: RiskCode::NestedVcsRoot,
            message: format!(
                "{} nested VCS root(s) detected (vendored or submodule); pass --nested-vcs to enumerate them.",
                multi_root.nested.len()
            ),
            path: multi_root.nested.first().cloned(),
        });
    }

    RiskSummary::from_findings(findings)
}

impl RiskSummary {
    fn from_findings(findings: Vec<RiskFinding>) -> Self {
        let total = findings.len();
        let high = findings
            .iter()
            .filter(|risk| risk.severity == RiskSeverity::High)
            .count();
        let medium = findings
            .iter()
            .filter(|risk| risk.severity == RiskSeverity::Medium)
            .count();
        let low = findings
            .iter()
            .filter(|risk| risk.severity == RiskSeverity::Low)
            .count();
        let info = findings
            .iter()
            .filter(|risk| risk.severity == RiskSeverity::Info)
            .count();

        Self {
            findings,
            total,
            high,
            medium,
            low,
            info,
        }
    }
}

impl RiskSeverity {
    fn as_str(self) -> &'static str {
        match self {
            Self::High => "high",
            Self::Medium => "medium",
            Self::Low => "low",
            Self::Info => "info",
        }
    }
}

impl ProjectHealth {
    pub fn as_str(self) -> &'static str {
        match self {
            Self::Healthy => "healthy",
            Self::NeedsAttention => "needs-attention",
            Self::Risky => "risky",
            Self::Unknown => "unknown",
        }
    }
}

impl HealthSignalKind {
    fn as_str(self) -> &'static str {
        match self {
            Self::Readme => "readme",
            Self::License => "license",
            Self::Ci => "ci",
            Self::Tests => "tests",
            Self::Lockfiles => "lockfiles",
            Self::Vcs => "vcs",
            Self::Activity => "activity",
            Self::Docs => "docs",
        }
    }
}

impl HealthSignalStatus {
    fn as_str(self) -> &'static str {
        match self {
            Self::Pass => "pass",
            Self::Warn => "warn",
            Self::Info => "info",
        }
    }
}

fn build_health_summary(
    inventory: &ScanInventory,
    risks: &RiskSummary,
    vcs: &VcsSummary,
) -> HealthSummary {
    let mut signals = Vec::new();

    signals.push(HealthSignal {
        kind: HealthSignalKind::Readme,
        status: pass_warn(inventory.documentation.has_readme),
        score_delta: if inventory.documentation.has_readme {
            10
        } else {
            -10
        },
        evidence: if inventory.documentation.has_readme {
            "README detected".to_owned()
        } else {
            "no README file detected".to_owned()
        },
    });
    signals.push(HealthSignal {
        kind: HealthSignalKind::License,
        status: pass_warn(inventory.documentation.has_license),
        score_delta: if inventory.documentation.has_license {
            20
        } else {
            -20
        },
        evidence: match (&inventory.license.path, inventory.license.kind) {
            (Some(path), kind) => format!("{} ({})", path.display(), kind.as_str()),
            (None, LicenseKind::Missing) => "no license file detected".to_owned(),
            (None, kind) => kind.as_str().to_owned(),
        },
    });
    signals.push(HealthSignal {
        kind: HealthSignalKind::Ci,
        status: pass_warn(inventory.ci.has_any_provider()),
        score_delta: if inventory.ci.has_any_provider() {
            20
        } else {
            -15
        },
        evidence: if inventory.ci.providers.is_empty() {
            "no known CI provider detected".to_owned()
        } else {
            let mut providers = inventory
                .ci
                .providers
                .iter()
                .map(|provider| provider.provider.as_str())
                .collect::<Vec<_>>();
            providers.sort_unstable();
            providers.dedup();
            providers.join(", ")
        },
    });
    let has_tests = inventory.tests.test_files > 0 || !inventory.tests.commands.is_empty();
    signals.push(HealthSignal {
        kind: HealthSignalKind::Tests,
        status: pass_warn(has_tests),
        score_delta: if has_tests { 20 } else { -20 },
        evidence: format!(
            "{} test file(s), {} command source(s)",
            inventory.tests.test_files,
            inventory.tests.commands.len()
        ),
    });

    let lockfiles_ok = lockfiles_ok(&inventory.dependencies);
    signals.push(HealthSignal {
        kind: HealthSignalKind::Lockfiles,
        status: pass_warn(lockfiles_ok),
        score_delta: if lockfiles_ok { 10 } else { -10 },
        evidence: lockfile_evidence(&inventory.dependencies),
    });

    let (vcs_status, vcs_delta, vcs_evidence) = if !vcs.is_repository {
        (
            HealthSignalStatus::Info,
            0,
            "no source control detected".to_owned(),
        )
    } else if vcs.is_dirty {
        (
            HealthSignalStatus::Warn,
            5,
            format!(
                "{} {}, dirty, {} modified, {} untracked",
                vcs.kind.label(),
                vcs.branch.as_deref().unwrap_or("unknown ref"),
                vcs.tracked_modified_files,
                vcs.untracked_files
            ),
        )
    } else {
        (
            HealthSignalStatus::Pass,
            15,
            format!(
                "{} {}, clean",
                vcs.kind.label(),
                vcs.branch.as_deref().unwrap_or("unknown ref")
            ),
        )
    };
    signals.push(HealthSignal {
        kind: HealthSignalKind::Vcs,
        status: vcs_status,
        score_delta: vcs_delta,
        evidence: vcs_evidence,
    });

    let (activity_status, activity_delta, activity_evidence) =
        match vcs.activity.days_since_last_commit {
            None => (HealthSignalStatus::Info, 0, "activity unknown".to_owned()),
            Some(days) if days < 90 => (
                HealthSignalStatus::Pass,
                10,
                format!("active, last commit {days} day(s) ago"),
            ),
            Some(days) if days < 365 => (
                HealthSignalStatus::Warn,
                -5,
                format!("stale, last commit {days} day(s) ago"),
            ),
            Some(days) => (
                HealthSignalStatus::Warn,
                -10,
                format!("dormant, last commit {days} day(s) ago"),
            ),
        };
    signals.push(HealthSignal {
        kind: HealthSignalKind::Activity,
        status: activity_status,
        score_delta: activity_delta,
        evidence: activity_evidence,
    });

    signals.push(HealthSignal {
        kind: HealthSignalKind::Docs,
        status: if inventory.documentation.has_docs_dir {
            HealthSignalStatus::Pass
        } else {
            HealthSignalStatus::Info
        },
        score_delta: if inventory.documentation.has_docs_dir {
            5
        } else {
            0
        },
        evidence: if inventory.documentation.has_docs_dir {
            "docs directory detected".to_owned()
        } else {
            "no docs directory detected".to_owned()
        },
    });

    let positive_score = signals
        .iter()
        .filter(|signal| signal.score_delta > 0)
        .map(|signal| signal.score_delta as usize)
        .sum::<usize>();
    let score = positive_score
        .saturating_sub(risks.high * 20)
        .saturating_sub(risks.medium * 8)
        .saturating_sub(risks.low * 3)
        .min(100);
    let risk_level = overall_risk_level(risks);
    let grade = project_health_grade(score, risk_level, inventory.files_scanned);

    HealthSummary {
        grade,
        score,
        risk_level,
        signals,
    }
}

fn pass_warn(pass: bool) -> HealthSignalStatus {
    if pass {
        HealthSignalStatus::Pass
    } else {
        HealthSignalStatus::Warn
    }
}

fn lockfiles_ok(dependencies: &DependencySummary) -> bool {
    dependencies
        .ecosystems
        .iter()
        .all(|summary| summary.total == 0 || summary.lockfile.is_some())
}

fn lockfile_evidence(dependencies: &DependencySummary) -> String {
    if dependencies.ecosystems.is_empty() {
        return "no dependency manifests".to_owned();
    }

    let lockfiles = dependencies
        .ecosystems
        .iter()
        .filter(|summary| summary.lockfile.is_some())
        .count();
    let missing = dependencies
        .ecosystems
        .iter()
        .filter(|summary| summary.total > 0 && summary.lockfile.is_none())
        .count();

    format!(
        "{} manifest(s), {} lockfile(s), {} missing",
        dependencies.total_manifests, lockfiles, missing
    )
}

fn overall_risk_level(risks: &RiskSummary) -> RiskSeverity {
    if risks.high > 0 {
        RiskSeverity::High
    } else if risks.medium > 0 {
        RiskSeverity::Medium
    } else if risks.low > 0 {
        RiskSeverity::Low
    } else {
        RiskSeverity::Info
    }
}

fn project_health_grade(
    score: usize,
    risk_level: RiskSeverity,
    files_scanned: usize,
) -> ProjectHealth {
    if files_scanned == 0 {
        return ProjectHealth::Unknown;
    }

    match (score, risk_level) {
        (_, RiskSeverity::High) => ProjectHealth::Risky,
        (80..=100, RiskSeverity::Info | RiskSeverity::Low) => ProjectHealth::Healthy,
        (50..=79, _) | (80..=100, RiskSeverity::Medium) => ProjectHealth::NeedsAttention,
        _ => ProjectHealth::Risky,
    }
}

impl RiskCode {
    fn as_str(self) -> &'static str {
        match self {
            Self::MissingReadme => "missing-readme",
            Self::MissingLicense => "missing-license",
            Self::MissingCi => "missing-ci",
            Self::NoTestsDetected => "no-tests-detected",
            Self::ManifestWithoutLockfile => "manifest-without-lockfile",
            Self::LargeProjectWithoutIgnoreRules => "large-project-without-ignore-rules",
            Self::UnknownLicense => "unknown-license",
            Self::MultipleVcsRootsFound => "multiple-vcs-roots-found",
            Self::NestedVcsRoot => "nested-vcs-root",
        }
    }
}

impl LicenseKind {
    fn as_str(self) -> &'static str {
        match self {
            Self::Mit => "MIT",
            Self::Apache2 => "Apache-2.0",
            Self::Gpl => "GPL",
            Self::Bsd => "BSD",
            Self::Unknown => "unknown",
            Self::Missing => "missing",
        }
    }
}

impl CiProvider {
    fn as_str(self) -> &'static str {
        match self {
            Self::GithubActions => "GitHub Actions",
            Self::GiteeGo => "Gitee Go",
            Self::GitlabCi => "GitLab CI",
            Self::CircleCi => "CircleCI",
            Self::Jenkins => "Jenkins",
        }
    }
}

fn add_rust_test_command(tests: &mut TestSummary, source: &Path) {
    add_test_command(
        tests,
        TestCommand {
            ecosystem: TestEcosystem::Rust,
            source: source.to_path_buf(),
            name: "cargo test".to_owned(),
            command: "cargo test".to_owned(),
        },
    );
}

fn add_node_test_commands(tests: &mut TestSummary, source: &Path) {
    let Some(value) = read_json_value(source) else {
        return;
    };
    let Some(scripts) = value.get("scripts").and_then(|value| value.as_object()) else {
        return;
    };

    for (name, command) in scripts {
        if name == "test" || name.starts_with("test:") {
            if let Some(command) = command.as_str() {
                add_test_command(
                    tests,
                    TestCommand {
                        ecosystem: TestEcosystem::Node,
                        source: source.to_path_buf(),
                        name: name.to_owned(),
                        command: command.to_owned(),
                    },
                );
            }
        }
    }
}

fn add_python_test_command(tests: &mut TestSummary, source: &Path) {
    let Some(value) = read_toml_value(source) else {
        return;
    };

    let has_pytest_config = value
        .get("tool")
        .and_then(|tool| tool.get("pytest"))
        .and_then(|pytest| pytest.get("ini_options"))
        .is_some();

    if has_pytest_config {
        add_test_command(
            tests,
            TestCommand {
                ecosystem: TestEcosystem::Python,
                source: source.to_path_buf(),
                name: "pytest".to_owned(),
                command: "pytest".to_owned(),
            },
        );
    }
}

fn add_cmake_test_command(tests: &mut TestSummary, source: &Path) {
    let Ok(content) = fs::read_to_string(source) else {
        return;
    };
    let lower = content.to_ascii_lowercase();

    if lower.contains("enable_testing") || lower.contains("add_test") {
        add_test_command(
            tests,
            TestCommand {
                ecosystem: TestEcosystem::CMake,
                source: source.to_path_buf(),
                name: "ctest".to_owned(),
                command: "ctest".to_owned(),
            },
        );
    }
}

fn add_test_command(tests: &mut TestSummary, command: TestCommand) {
    if tests.commands.iter().any(|existing| {
        existing.ecosystem == command.ecosystem
            && existing.source == command.source
            && existing.name == command.name
            && existing.command == command.command
    }) {
        return;
    }

    tests.commands.push(command);
}

fn summarize_cargo_dependencies(manifest: &Path) -> Option<DependencyEcosystemSummary> {
    let value = read_toml_value(manifest)?;
    let normal = count_toml_table_entries(value.get("dependencies"));
    let development = count_toml_table_entries(value.get("dev-dependencies"));
    let build = count_toml_table_entries(value.get("build-dependencies"));
    let optional = count_optional_cargo_dependencies(value.get("dependencies"));
    let total = normal + development + build;

    Some(DependencyEcosystemSummary {
        ecosystem: DependencyEcosystem::Rust,
        source: DependencySource::CargoToml,
        manifest: manifest.to_path_buf(),
        lockfile: find_nearest_lockfile(manifest, &["Cargo.lock"]),
        normal,
        development,
        build,
        optional,
        total,
    })
}

fn summarize_node_dependencies(manifest: &Path) -> Option<DependencyEcosystemSummary> {
    let value = read_json_value(manifest)?;
    let normal = count_json_object_entries(value.get("dependencies"));
    let development = count_json_object_entries(value.get("devDependencies"));
    let optional = count_json_object_entries(value.get("optionalDependencies"));
    let total = normal + development + optional;

    Some(DependencyEcosystemSummary {
        ecosystem: DependencyEcosystem::Node,
        source: DependencySource::PackageJson,
        manifest: manifest.to_path_buf(),
        lockfile: find_sibling_lockfile(
            manifest,
            &[
                "pnpm-lock.yaml",
                "yarn.lock",
                "package-lock.json",
                "bun.lockb",
            ],
        ),
        normal,
        development,
        build: 0,
        optional,
        total,
    })
}

fn summarize_pyproject_dependencies(manifest: &Path) -> Option<DependencyEcosystemSummary> {
    let value = read_toml_value(manifest)?;
    let project = value.get("project");
    let normal = project
        .and_then(|project| project.get("dependencies"))
        .and_then(|dependencies| dependencies.as_array())
        .map_or(0, Vec::len);
    let optional = project
        .and_then(|project| project.get("optional-dependencies"))
        .and_then(|dependencies| dependencies.as_table())
        .map(|groups| {
            groups
                .values()
                .filter_map(|value| value.as_array())
                .map(Vec::len)
                .sum()
        })
        .unwrap_or(0);
    let development = project
        .and_then(|project| project.get("optional-dependencies"))
        .and_then(|dependencies| dependencies.get("dev"))
        .and_then(|dependencies| dependencies.as_array())
        .map_or(0, Vec::len);
    let total = normal + optional;

    Some(DependencyEcosystemSummary {
        ecosystem: DependencyEcosystem::Python,
        source: DependencySource::PyprojectToml,
        manifest: manifest.to_path_buf(),
        lockfile: find_sibling_lockfile(manifest, &["uv.lock", "poetry.lock", "pdm.lock"]),
        normal,
        development,
        build: 0,
        optional,
        total,
    })
}

fn summarize_requirements_dependencies(manifest: &Path) -> Option<DependencyEcosystemSummary> {
    let content = fs::read_to_string(manifest).ok()?;
    let normal = content
        .lines()
        .map(str::trim)
        .filter(|line| is_requirement_entry(line))
        .count();

    Some(DependencyEcosystemSummary {
        ecosystem: DependencyEcosystem::Python,
        source: DependencySource::RequirementsTxt,
        manifest: manifest.to_path_buf(),
        lockfile: find_sibling_lockfile(manifest, &["uv.lock", "poetry.lock", "pdm.lock"]),
        normal,
        development: 0,
        build: 0,
        optional: 0,
        total: normal,
    })
}

fn count_toml_table_entries(value: Option<&toml::Value>) -> usize {
    value
        .and_then(|value| value.as_table())
        .map_or(0, |table| table.len())
}

fn count_optional_cargo_dependencies(value: Option<&toml::Value>) -> usize {
    value
        .and_then(|value| value.as_table())
        .map(|dependencies| {
            dependencies
                .values()
                .filter(|value| {
                    value
                        .as_table()
                        .and_then(|table| table.get("optional"))
                        .and_then(|optional| optional.as_bool())
                        .unwrap_or(false)
                })
                .count()
        })
        .unwrap_or(0)
}

fn count_json_object_entries(value: Option<&serde_json::Value>) -> usize {
    value
        .and_then(|value| value.as_object())
        .map_or(0, |object| object.len())
}

fn is_requirement_entry(line: &str) -> bool {
    !line.is_empty() && !line.starts_with('#') && !line.starts_with('-') && !line.starts_with("--")
}

fn find_nearest_lockfile(manifest: &Path, names: &[&str]) -> Option<PathBuf> {
    let mut current = manifest.parent();
    while let Some(dir) = current {
        if let Some(lockfile) = find_lockfile_in_dir(dir, names) {
            return Some(lockfile);
        }
        current = dir.parent();
    }

    None
}

fn find_sibling_lockfile(manifest: &Path, names: &[&str]) -> Option<PathBuf> {
    find_lockfile_in_dir(manifest.parent()?, names)
}

fn find_lockfile_in_dir(dir: &Path, names: &[&str]) -> Option<PathBuf> {
    names
        .iter()
        .map(|name| dir.join(name))
        .find(|path| path.is_file())
}

fn detect_vcs_summary(root: &Path, opts: &ScanOptions) -> VcsSummary {
    if root.join(".git").exists() {
        return detect_git_into(root, opts);
    }
    if root.join(".hg").is_dir() {
        return detect_hg_into(root);
    }
    if root.join(".svn").is_dir() {
        return detect_svn_into(root);
    }
    if root.join(".fslckout").is_file() || root.join("_FOSSIL_").is_file() {
        return VcsSummary {
            kind: VcsKind::Fossil,
            is_repository: true,
            root: Some(root.to_path_buf()),
            ..VcsSummary::default()
        };
    }
    if root.join(".bzr").is_dir() {
        return VcsSummary {
            kind: VcsKind::Bzr,
            is_repository: true,
            root: Some(root.to_path_buf()),
            ..VcsSummary::default()
        };
    }
    VcsSummary::default()
}

fn detect_git_into(root: &Path, opts: &ScanOptions) -> VcsSummary {
    let detected_root = run_vcs_output("git", root, &["rev-parse", "--show-toplevel"])
        .and_then(|output| output.lines().next().map(PathBuf::from))
        .or_else(|| Some(root.to_path_buf()));

    let branch = run_vcs_output("git", root, &["branch", "--show-current"])
        .and_then(|output| non_empty_trimmed(&output));
    let revision = run_vcs_output("git", root, &["rev-parse", "HEAD"])
        .and_then(|output| non_empty_trimmed(&output));
    let last_commit = run_vcs_output("git", root, &["log", "-1", "--format=%cI"])
        .and_then(|output| non_empty_trimmed(&output));
    let porcelain = run_vcs_output("git", root, &["status", "--porcelain"]).unwrap_or_default();
    let mut tracked_modified_files = 0;
    let mut untracked_files = 0;

    for line in porcelain.lines() {
        if line.starts_with("??") {
            untracked_files += 1;
        } else if !line.trim().is_empty() {
            tracked_modified_files += 1;
        }
    }

    let activity = detect_git_activity(root, opts);

    VcsSummary {
        kind: VcsKind::Git,
        is_repository: true,
        root: detected_root,
        branch,
        revision,
        last_commit,
        is_dirty: tracked_modified_files > 0 || untracked_files > 0,
        tracked_modified_files,
        untracked_files,
        activity,
    }
}

fn detect_git_activity(root: &Path, opts: &ScanOptions) -> VcsActivity {
    let last_commit_ts = run_vcs_output("git", root, &["log", "-1", "--format=%ct"])
        .and_then(|s| s.trim().parse::<i64>().ok());
    let days_since_last_commit = last_commit_ts.and_then(|ts| {
        let now = std::time::SystemTime::now()
            .duration_since(std::time::UNIX_EPOCH)
            .ok()?
            .as_secs() as i64;
        let delta = (now - ts).max(0);
        Some((delta / 86_400) as u32)
    });

    let commits_last_90d = run_vcs_output(
        "git",
        root,
        &["rev-list", "--count", "--since=90 days ago", "HEAD"],
    )
    .and_then(|s| s.trim().parse::<u32>().ok());

    let contributors_count =
        run_vcs_output("git", root, &["shortlog", "-sne", "HEAD"]).map(|output| {
            output
                .lines()
                .filter(|line| !line.trim().is_empty())
                .count() as u32
        });

    let first_commit_date = run_vcs_output(
        "git",
        root,
        &["log", "--max-parents=0", "--format=%aI", "HEAD"],
    )
    .and_then(|output| output.lines().next().map(|s| s.trim().to_owned()))
    .filter(|s| !s.is_empty());

    let contributors = if opts.detailed_contributors {
        parse_git_shortlog(
            &run_vcs_output("git", root, &["shortlog", "-sne", "HEAD"]).unwrap_or_default(),
        )
    } else {
        Vec::new()
    };

    VcsActivity {
        days_since_last_commit,
        commits_last_90d,
        contributors_count,
        first_commit_date,
        contributors,
    }
}

fn parse_git_shortlog(text: &str) -> Vec<VcsContributor> {
    let mut out = Vec::new();
    for line in text.lines() {
        let trimmed = line.trim();
        if trimmed.is_empty() {
            continue;
        }
        // Format: "    <count>\t<name> <<email>>"
        let mut parts = trimmed.splitn(2, char::is_whitespace);
        let count_str = parts.next().unwrap_or("");
        let rest = parts.next().unwrap_or("").trim();
        let Ok(count) = count_str.parse::<u32>() else {
            continue;
        };
        let (name, email) = match (rest.rfind('<'), rest.rfind('>')) {
            (Some(open), Some(close)) if open < close => {
                let name = rest[..open].trim().to_owned();
                let email = rest[open + 1..close].trim().to_owned();
                (name, email)
            }
            _ => (rest.to_owned(), String::new()),
        };
        out.push(VcsContributor {
            name,
            email,
            commit_count: count,
        });
    }
    out
}

fn detect_hg_into(root: &Path) -> VcsSummary {
    let detected_root = run_vcs_output("hg", root, &["root"])
        .and_then(|output| output.lines().next().map(PathBuf::from))
        .or_else(|| Some(root.to_path_buf()));

    let branch = run_vcs_output("hg", root, &["branch"]).and_then(|s| non_empty_trimmed(&s));
    let revision = run_vcs_output("hg", root, &["log", "-r", ".", "--template", "{node}"])
        .and_then(|s| non_empty_trimmed(&s));
    let last_commit = run_vcs_output(
        "hg",
        root,
        &["log", "-r", ".", "--template", "{date|isodatesec}"],
    )
    .and_then(|s| non_empty_trimmed(&s));

    let status_text = run_vcs_output("hg", root, &["status"]).unwrap_or_default();
    let mut tracked_modified_files = 0;
    let mut untracked_files = 0;
    for line in status_text.lines() {
        let mut chars = line.chars();
        match chars.next() {
            Some('?') => untracked_files += 1,
            Some(c) if "MARC!".contains(c) => tracked_modified_files += 1,
            _ => {}
        }
    }

    VcsSummary {
        kind: VcsKind::Hg,
        is_repository: true,
        root: detected_root,
        branch,
        revision,
        last_commit,
        is_dirty: tracked_modified_files > 0 || untracked_files > 0,
        tracked_modified_files,
        untracked_files,
        activity: VcsActivity::default(),
    }
}

fn detect_svn_into(root: &Path) -> VcsSummary {
    let detected_root = run_vcs_output("svn", root, &["info", "--show-item", "wc-root"])
        .and_then(|s| non_empty_trimmed(&s))
        .map(PathBuf::from)
        .or_else(|| Some(root.to_path_buf()));
    let branch = run_vcs_output("svn", root, &["info", "--show-item", "url"])
        .and_then(|s| non_empty_trimmed(&s));
    let revision = run_vcs_output("svn", root, &["info", "--show-item", "revision"])
        .and_then(|s| non_empty_trimmed(&s));
    let last_commit = run_vcs_output("svn", root, &["info", "--show-item", "last-changed-date"])
        .and_then(|s| non_empty_trimmed(&s));

    let status_text = run_vcs_output("svn", root, &["status"]).unwrap_or_default();
    let mut tracked_modified_files = 0;
    let mut untracked_files = 0;
    for line in status_text.lines() {
        let mut chars = line.chars();
        match chars.next() {
            Some('?') => untracked_files += 1,
            Some(c) if "ADMRC!~".contains(c) => tracked_modified_files += 1,
            _ => {}
        }
    }

    VcsSummary {
        kind: VcsKind::Svn,
        is_repository: true,
        root: detected_root,
        branch,
        revision,
        last_commit,
        is_dirty: tracked_modified_files > 0 || untracked_files > 0,
        tracked_modified_files,
        untracked_files,
        activity: VcsActivity::default(),
    }
}

fn run_vcs_output(program: &str, root: &Path, args: &[&str]) -> Option<String> {
    let output = Command::new(program)
        .args(args)
        .current_dir(root)
        .output()
        .ok()?;

    if !output.status.success() {
        return None;
    }

    Some(String::from_utf8_lossy(&output.stdout).trim().to_owned())
}

fn non_empty_trimmed(value: &str) -> Option<String> {
    let value = value.trim();
    if value.is_empty() {
        None
    } else {
        Some(value.to_owned())
    }
}

fn detect_indicators(root: &Path) -> Vec<ProjectIndicator> {
    let checks = [
        ("Cargo.toml", IndicatorKind::RustWorkspace),
        (".git", IndicatorKind::GitRepository),
        ("README.md", IndicatorKind::Readme),
    ];

    let mut indicators = Vec::new();
    for (relative, kind) in checks {
        let path = root.join(relative);
        if path.exists() {
            indicators.push(ProjectIndicator { kind, path });
        }
    }

    let cargo_manifest = root.join("Cargo.toml");
    if cargo_manifest.exists() {
        indicators.push(ProjectIndicator {
            kind: IndicatorKind::RustPackage,
            path: cargo_manifest,
        });
    }

    indicators
}

fn scan_inventory(root: &Path) -> Result<ScanInventory> {
    let mut inventory = MutableInventory::default();
    let ignore_matcher = IgnoreMatcher::new(root);
    walk_project(root, &ignore_matcher, &mut inventory)?;

    Ok(ScanInventory {
        languages: inventory.languages,
        build_systems: inventory.build_systems,
        code: inventory.code,
        dependencies: build_dependency_summary(inventory.dependency_manifests),
        tests: build_test_summary(inventory.tests, inventory.test_command_sources),
        hygiene: inventory.hygiene,
        documentation: inventory.documentation,
        license: build_license_summary(&inventory.license_files),
        ci: inventory.ci,
        containers: inventory.containers,
        files_scanned: inventory.files_scanned,
        skipped_dirs: inventory.skipped_dirs,
    })
}

fn walk_project(
    path: &Path,
    ignore_matcher: &IgnoreMatcher,
    inventory: &mut MutableInventory,
) -> Result<()> {
    let local_ignore_matcher = ignore_matcher.with_child_ignores(path);
    let mut entries = Vec::new();

    for entry in
        fs::read_dir(path).with_context(|| format!("failed to read `{}`", path.display()))?
    {
        let entry =
            entry.with_context(|| format!("failed to read entry under `{}`", path.display()))?;
        entries.push(entry);
    }

    entries.sort_by_key(|entry| entry.file_name());

    for entry in entries {
        let entry_path = entry.path();
        let file_type = entry
            .file_type()
            .with_context(|| format!("failed to inspect `{}`", entry_path.display()))?;

        if file_type.is_dir() {
            if should_skip_dir(entry.file_name().as_os_str())
                || local_ignore_matcher.is_ignored(&entry_path, true)
            {
                inventory.add_skipped_dir(entry_path);
                continue;
            }

            observe_directory(&entry_path, inventory);
            walk_project(&entry_path, &local_ignore_matcher, inventory)?;
            continue;
        }

        if file_type.is_file() {
            if local_ignore_matcher.is_ignored(&entry_path, false) {
                continue;
            }

            inventory.files_scanned += 1;
            observe_file(&entry_path, inventory);
        }
    }

    Ok(())
}

fn should_skip_dir(name: &OsStr) -> bool {
    matches!(
        name.to_str(),
        Some(".git" | ".hg" | ".svn" | "target" | "node_modules")
    )
}

#[derive(Clone)]
struct IgnoreMatcher {
    matchers: Vec<Gitignore>,
}

impl IgnoreMatcher {
    fn new(root: &Path) -> Self {
        Self {
            matchers: Self::build_matchers(root),
        }
    }

    fn with_child_ignores(&self, dir: &Path) -> Self {
        let mut matchers = self.matchers.clone();
        matchers.extend(Self::build_matchers(dir));
        Self { matchers }
    }

    fn is_ignored(&self, path: &Path, is_dir: bool) -> bool {
        self.matchers
            .iter()
            .rev()
            .find_map(|matcher| {
                let result = matcher.matched(path, is_dir);
                if result.is_none() {
                    None
                } else {
                    Some(result.is_ignore())
                }
            })
            .unwrap_or(false)
    }

    fn build_matchers(dir: &Path) -> Vec<Gitignore> {
        [".gitignore", ".ignore"]
            .into_iter()
            .filter_map(|file_name| Self::build_matcher(dir, file_name))
            .collect()
    }

    fn build_matcher(dir: &Path, file_name: &str) -> Option<Gitignore> {
        let path = dir.join(file_name);
        if !path.is_file() {
            return None;
        }

        let mut builder = GitignoreBuilder::new(dir);
        let _ = builder.add(&path);
        builder.build().ok()
    }
}

fn observe_directory(path: &Path, inventory: &mut MutableInventory) {
    if path.file_name().and_then(|value| value.to_str()) == Some("docs") {
        inventory.documentation.has_docs_dir = true;
    }
    if is_test_directory(path) {
        add_test_directory(&mut inventory.tests, path.to_path_buf());
    }
}

fn observe_file(path: &Path, inventory: &mut MutableInventory) {
    if let Some(kind) = language_for_path(path) {
        inventory.add_language(kind);
        inventory.add_code_file(kind, path);
    }

    if let Some(kind) = build_system_for_path(path) {
        inventory.add_build_system(kind, path.to_path_buf());
    }
    if is_dependency_manifest(path) {
        inventory.add_dependency_manifest(path.to_path_buf());
    }
    if is_test_file(path) {
        inventory.tests.test_files += 1;
    }
    if is_test_command_source(path) {
        inventory.add_test_command_source(path.to_path_buf());
    }
    observe_hygiene_file(path, &mut inventory.hygiene);

    observe_documentation_file(path, &mut inventory.documentation);
    if is_license_file(path) {
        inventory.add_license_file(path.to_path_buf());
    }
    observe_ci_file(path, &mut inventory.ci);
    observe_container_file(path, &mut inventory.containers);
}

fn language_for_path(path: &Path) -> Option<LanguageKind> {
    let extension = path
        .extension()
        .and_then(|value| value.to_str())
        .map(str::to_ascii_lowercase)?;

    match extension.as_str() {
        "rs" => Some(LanguageKind::Rust),
        "ts" | "tsx" => Some(LanguageKind::TypeScript),
        "js" | "jsx" | "mjs" | "cjs" => Some(LanguageKind::JavaScript),
        "py" => Some(LanguageKind::Python),
        "c" => Some(LanguageKind::C),
        "cc" | "cpp" | "cxx" | "hpp" | "hxx" => Some(LanguageKind::Cpp),
        "go" => Some(LanguageKind::Go),
        _ => None,
    }
}

fn count_code_lines(path: &Path, kind: LanguageKind) -> CodeLineCounts {
    let Ok(content) = fs::read_to_string(path) else {
        return CodeLineCounts::default();
    };

    let mut counts = CodeLineCounts::default();
    let mut in_block_comment = false;

    for line in content.lines() {
        counts.total_lines += 1;
        let trimmed = line.trim();

        if trimmed.is_empty() {
            counts.blank_lines += 1;
            continue;
        }

        let classification = classify_code_line(trimmed, kind, &mut in_block_comment);
        if classification.has_comment {
            counts.comment_lines += 1;
        }
        if classification.has_code {
            counts.code_lines += 1;
        }
    }

    counts
}

#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
struct CodeLineClassification {
    has_code: bool,
    has_comment: bool,
}

fn classify_code_line(
    mut line: &str,
    kind: LanguageKind,
    in_block_comment: &mut bool,
) -> CodeLineClassification {
    if !supports_c_style_block_comments(kind) {
        return classify_simple_comment_line(line, kind);
    }

    let mut classification = CodeLineClassification::default();

    loop {
        if *in_block_comment {
            classification.has_comment = true;
            if let Some(end) = line.find("*/") {
                *in_block_comment = false;
                line = &line[end + 2..];
                if line.trim().is_empty() {
                    break;
                }
                continue;
            }
            break;
        }

        let current = line.trim_start();
        if current.is_empty() {
            break;
        }
        if current.starts_with("//") {
            classification.has_comment = true;
            break;
        }

        let block_start = current.find("/*");
        let line_comment_start = current.find("//");

        match (block_start, line_comment_start) {
            (Some(block), Some(comment)) if comment < block => {
                classification.has_comment = true;
                if !current[..comment].trim().is_empty() {
                    classification.has_code = true;
                }
                break;
            }
            (Some(block), _) => {
                classification.has_comment = true;
                if !current[..block].trim().is_empty() {
                    classification.has_code = true;
                }
                let after_block_start = &current[block + 2..];
                if let Some(end) = after_block_start.find("*/") {
                    line = &after_block_start[end + 2..];
                    if line.trim().is_empty() {
                        break;
                    }
                    continue;
                }
                *in_block_comment = true;
                break;
            }
            (None, Some(comment)) => {
                classification.has_comment = true;
                if !current[..comment].trim().is_empty() {
                    classification.has_code = true;
                }
                break;
            }
            (None, None) => {
                classification.has_code = true;
                break;
            }
        }
    }

    classification
}

fn classify_simple_comment_line(line: &str, kind: LanguageKind) -> CodeLineClassification {
    let markers = simple_comment_markers(kind);

    if markers.iter().any(|marker| line.starts_with(marker)) {
        CodeLineClassification {
            has_code: false,
            has_comment: true,
        }
    } else {
        CodeLineClassification {
            has_code: true,
            has_comment: markers
                .iter()
                .any(|marker| line.find(marker).is_some_and(|index| index > 0)),
        }
    }
}

fn supports_c_style_block_comments(kind: LanguageKind) -> bool {
    matches!(
        kind,
        LanguageKind::Rust
            | LanguageKind::TypeScript
            | LanguageKind::JavaScript
            | LanguageKind::C
            | LanguageKind::Cpp
            | LanguageKind::Go
    )
}

fn simple_comment_markers(kind: LanguageKind) -> &'static [&'static str] {
    match kind {
        LanguageKind::Python => &["#"],
        LanguageKind::Rust
        | LanguageKind::TypeScript
        | LanguageKind::JavaScript
        | LanguageKind::C
        | LanguageKind::Cpp
        | LanguageKind::Go => &["//"],
    }
}

fn build_system_for_path(path: &Path) -> Option<BuildSystemKind> {
    let file_name = path.file_name()?.to_str()?;

    match file_name {
        "Cargo.toml" => Some(BuildSystemKind::Cargo),
        "package.json" => Some(BuildSystemKind::NodePackage),
        "pyproject.toml" => Some(BuildSystemKind::PythonProject),
        "requirements.txt" => Some(BuildSystemKind::PythonRequirements),
        "CMakeLists.txt" => Some(BuildSystemKind::CMake),
        "go.mod" => Some(BuildSystemKind::GoModule),
        _ => None,
    }
}

fn is_dependency_manifest(path: &Path) -> bool {
    matches!(
        path.file_name().and_then(|value| value.to_str()),
        Some("Cargo.toml" | "package.json" | "pyproject.toml" | "requirements.txt")
    )
}

fn is_test_command_source(path: &Path) -> bool {
    matches!(
        path.file_name().and_then(|value| value.to_str()),
        Some("Cargo.toml" | "package.json" | "pyproject.toml" | "CMakeLists.txt")
    )
}

fn is_test_directory(path: &Path) -> bool {
    matches!(
        path.file_name().and_then(|value| value.to_str()),
        Some("tests" | "test" | "__tests__" | "spec")
    )
}

fn add_test_directory(tests: &mut TestSummary, path: PathBuf) {
    tests.has_tests_dir = true;
    if tests
        .test_directories
        .iter()
        .any(|existing| existing == &path)
    {
        return;
    }

    tests.test_directories.push(path);
}

fn is_test_file(path: &Path) -> bool {
    let file_name = path
        .file_name()
        .and_then(|value| value.to_str())
        .unwrap_or_default()
        .to_ascii_lowercase();
    let extension = path
        .extension()
        .and_then(|value| value.to_str())
        .unwrap_or_default()
        .to_ascii_lowercase();

    if is_under_named_dir(path, "tests") || is_under_named_dir(path, "__tests__") {
        return matches!(
            extension.as_str(),
            "rs" | "js" | "jsx" | "ts" | "tsx" | "py"
        );
    }

    file_name.ends_with("_test.rs")
        || file_name.ends_with(".test.js")
        || file_name.ends_with(".test.jsx")
        || file_name.ends_with(".test.ts")
        || file_name.ends_with(".test.tsx")
        || file_name.ends_with(".spec.js")
        || file_name.ends_with(".spec.jsx")
        || file_name.ends_with(".spec.ts")
        || file_name.ends_with(".spec.tsx")
        || (file_name.starts_with("test_") && file_name.ends_with(".py"))
        || file_name.ends_with("_test.py")
        || file_name.ends_with("_test.cpp")
        || file_name.ends_with("_test.cc")
        || file_name.ends_with("_test.cxx")
        || file_name.ends_with("_tests.cpp")
}

fn is_under_named_dir(path: &Path, directory_name: &str) -> bool {
    path.components()
        .any(|component| component == Component::Normal(OsStr::new(directory_name)))
}

fn observe_documentation_file(path: &Path, documentation: &mut DocumentationSummary) {
    let Some(file_name) = path.file_name().and_then(|value| value.to_str()) else {
        return;
    };
    let file_name = file_name.to_ascii_lowercase();

    if file_name == "readme.md" || file_name == "readme" {
        documentation.has_readme = true;
    }
    if file_name == "license" || file_name.starts_with("license.") {
        documentation.has_license = true;
    }
}

fn is_license_file(path: &Path) -> bool {
    let Some(file_name) = path.file_name().and_then(|value| value.to_str()) else {
        return false;
    };
    let file_name = file_name.to_ascii_lowercase();
    file_name == "license" || file_name.starts_with("license.")
}

fn build_license_summary(files: &[PathBuf]) -> LicenseSummary {
    let Some(path) = files.first() else {
        return LicenseSummary {
            path: None,
            kind: LicenseKind::Missing,
        };
    };

    let content = fs::read_to_string(path).unwrap_or_default();
    LicenseSummary {
        path: Some(path.clone()),
        kind: detect_license_kind(&content),
    }
}

fn detect_license_kind(content: &str) -> LicenseKind {
    let lower = content.to_ascii_lowercase();
    let normalized = lower.trim();

    if normalized == "mit"
        || normalized == "mit license"
        || lower.contains("mit license")
        || lower.contains("permission is hereby granted")
    {
        LicenseKind::Mit
    } else if normalized == "apache-2.0"
        || normalized == "apache 2.0"
        || lower.contains("apache license")
        || lower.contains("apache-2.0")
        || lower.contains("www.apache.org/licenses/license-2.0")
    {
        LicenseKind::Apache2
    } else if normalized.starts_with("gpl")
        || lower.contains("gnu general public license")
        || lower.contains("gpl")
    {
        LicenseKind::Gpl
    } else if normalized.starts_with("bsd")
        || (lower.contains("bsd") && lower.contains("redistribution and use"))
    {
        LicenseKind::Bsd
    } else {
        LicenseKind::Unknown
    }
}

fn observe_hygiene_file(path: &Path, hygiene: &mut ScanHygiene) {
    match path.file_name().and_then(|value| value.to_str()) {
        Some(".gitignore") => hygiene.has_gitignore = true,
        Some(".ignore") => hygiene.has_ignore = true,
        _ => {}
    }
}

fn observe_ci_file(path: &Path, ci: &mut CiSummary) {
    if has_component_pair(path, ".github", "workflows") {
        ci.add_provider(CiProvider::GithubActions, path.to_path_buf());
    }
    if has_component(path, ".workflow") {
        ci.add_provider(CiProvider::GiteeGo, path.to_path_buf());
    }
    if path.file_name().and_then(|value| value.to_str()) == Some(".gitlab-ci.yml") {
        ci.add_provider(CiProvider::GitlabCi, path.to_path_buf());
    }
    if has_component(path, ".circleci") {
        ci.add_provider(CiProvider::CircleCi, path.to_path_buf());
    }
    if path.file_name().and_then(|value| value.to_str()) == Some("Jenkinsfile") {
        ci.add_provider(CiProvider::Jenkins, path.to_path_buf());
    }
}

fn has_component(path: &Path, name: &str) -> bool {
    path.components()
        .any(|component| component == Component::Normal(OsStr::new(name)))
}

fn has_component_pair(path: &Path, first: &str, second: &str) -> bool {
    let mut components = path.components();
    while let Some(component) = components.next() {
        if component == Component::Normal(OsStr::new(first))
            && components.next() == Some(Component::Normal(OsStr::new(second)))
        {
            return true;
        }
    }

    false
}

fn observe_container_file(path: &Path, containers: &mut ContainerSummary) {
    let Some(file_name) = path.file_name().and_then(|value| value.to_str()) else {
        return;
    };
    let file_name = file_name.to_ascii_lowercase();

    if file_name == "dockerfile" || file_name.starts_with("dockerfile.") {
        containers.has_dockerfile = true;
    }
    if matches!(
        file_name.as_str(),
        "docker-compose.yml" | "docker-compose.yaml" | "compose.yml" | "compose.yaml"
    ) {
        containers.has_compose_file = true;
    }
}

#[derive(Default)]
struct MutableInventory {
    languages: Vec<LanguageSummary>,
    build_systems: Vec<BuildSystemSummary>,
    code: CodeSummary,
    dependency_manifests: Vec<PathBuf>,
    tests: TestSummary,
    test_command_sources: Vec<PathBuf>,
    hygiene: ScanHygiene,
    documentation: DocumentationSummary,
    license_files: Vec<PathBuf>,
    ci: CiSummary,
    containers: ContainerSummary,
    files_scanned: usize,
    skipped_dirs: Vec<PathBuf>,
}

impl MutableInventory {
    fn add_language(&mut self, kind: LanguageKind) {
        if let Some(language) = self
            .languages
            .iter_mut()
            .find(|language| language.kind == kind)
        {
            language.files += 1;
            return;
        }

        self.languages.push(LanguageSummary { kind, files: 1 });
    }

    fn add_code_file(&mut self, kind: LanguageKind, path: &Path) {
        let counts = count_code_lines(path, kind);
        self.code.total_files += 1;
        self.code.total_lines += counts.total_lines;
        self.code.code_lines += counts.code_lines;
        self.code.comment_lines += counts.comment_lines;
        self.code.blank_lines += counts.blank_lines;

        if let Some(language) = self
            .code
            .languages
            .iter_mut()
            .find(|language| language.kind == kind)
        {
            language.files += 1;
            language.total_lines += counts.total_lines;
            language.code_lines += counts.code_lines;
            language.comment_lines += counts.comment_lines;
            language.blank_lines += counts.blank_lines;
            return;
        }

        self.code.languages.push(CodeLanguageSummary {
            kind,
            files: 1,
            total_lines: counts.total_lines,
            code_lines: counts.code_lines,
            comment_lines: counts.comment_lines,
            blank_lines: counts.blank_lines,
        });
    }

    fn add_build_system(&mut self, kind: BuildSystemKind, path: PathBuf) {
        if self
            .build_systems
            .iter()
            .any(|build_system| build_system.kind == kind && build_system.path == path)
        {
            return;
        }

        self.build_systems.push(BuildSystemSummary { kind, path });
    }

    fn add_dependency_manifest(&mut self, path: PathBuf) {
        if self
            .dependency_manifests
            .iter()
            .any(|existing| existing == &path)
        {
            return;
        }

        self.dependency_manifests.push(path);
    }

    fn add_test_command_source(&mut self, path: PathBuf) {
        if self
            .test_command_sources
            .iter()
            .any(|existing| existing == &path)
        {
            return;
        }

        self.test_command_sources.push(path);
    }

    fn add_license_file(&mut self, path: PathBuf) {
        if self.license_files.iter().any(|existing| existing == &path) {
            return;
        }

        self.license_files.push(path);
    }

    fn add_skipped_dir(&mut self, path: PathBuf) {
        if self.skipped_dirs.iter().any(|existing| existing == &path) {
            return;
        }

        self.skipped_dirs.push(path);
    }
}

fn build_report(
    project_name: &str,
    indicators: &[ProjectIndicator],
    inventory: &ScanInventory,
    health: &HealthSummary,
) -> ProjectReport {
    let summary = if indicators.is_empty() {
        format!("{project_name} was scanned, but no known project markers were detected yet.")
    } else {
        format!(
            "{project_name} was scanned across {} file(s), with {} project marker(s), {} language(s), {} build system(s), and {} health detected.",
            inventory.files_scanned,
            indicators.len(),
            inventory.languages.len(),
            inventory.build_systems.len(),
            health.grade.as_str()
        )
    };

    ProjectReport {
        summary,
        next_steps: vec![
            "Add language, dependency, and repository activity scanners.".to_owned(),
            "Keep CLI and GUI features backed by projd-core data structures.".to_owned(),
            "Export Markdown and JSON reports before adding richer GUI visualizations.".to_owned(),
        ],
    }
}

fn yes_no(value: bool) -> &'static str {
    if value { "yes" } else { "no" }
}

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

    #[test]
    fn renders_markdown_without_indicators() {
        let scan = ProjectScan {
            root: PathBuf::from("example"),
            project_name: "example".to_owned(),
            identity: ProjectIdentity {
                name: "example".to_owned(),
                version: None,
                kind: ProjectKind::Generic,
                source: IdentitySource::DirectoryName,
            },
            indicators: Vec::new(),
            languages: Vec::new(),
            build_systems: Vec::new(),
            code: CodeSummary::default(),
            dependencies: DependencySummary::default(),
            tests: TestSummary::default(),
            hygiene: ScanHygiene::default(),
            risks: RiskSummary::default(),
            health: HealthSummary {
                grade: ProjectHealth::Unknown,
                score: 0,
                risk_level: RiskSeverity::Info,
                signals: Vec::new(),
            },
            documentation: DocumentationSummary::default(),
            license: LicenseSummary::default(),
            ci: CiSummary::default(),
            vcs: VcsSummary::default(),
            containers: ContainerSummary::default(),
            files_scanned: 0,
            skipped_dirs: Vec::new(),
            report: ProjectReport {
                summary: "example summary".to_owned(),
                next_steps: vec!["next".to_owned()],
            },
        };

        let rendered = render_markdown(&scan);

        assert!(rendered.contains("# Project Report"));
        assert!(rendered.contains("example summary"));
        assert!(rendered.contains("No known project indicators"));
    }
}