dev_prune/commands/

doctor.rs

// Copyright 2026 VKrishna04
// SPDX-License-Identifier: Apache-2.0

// Handler for `dev-prune doctor`.
//
// One command that answers "why is this not doing what I expect". Without a path it
// checks the installation — binary, alias, PATH, config, integrations, package managers,
// registry, release check. With a path it checks that one repository and ends by naming
// the reason it would or would not be pruned right now.
//
// The plain doctor is read-only. A diagnostic that repairs things as it goes cannot be
// run twice to see whether the first run helped, so diagnosis and treatment are two
// separate invocations: the report names every finding it could repair, and `--fix` is
// the explicit second step that repairs them. `--fix` only mends what is already
// installed but broken — a missing or stale twin binary, hooks or a scheduler
// registered against a binary that no longer exists, a drifted hook chain, a missing
// `SKILL.md` export, registry entries whose repository is gone. It never installs an
// integration for the first time (`devp setup` and the individual commands are the
// opt-in for that), and it never touches an unreadable `registry.json`, because
// guessing at a config it cannot read is exactly what dev-prune refuses to do.
//
// Nothing here runs a package manager either: `enforce_lockfile` invokes `npm`,
// `cargo` and friends, which is minutes of work and, for the opted-in adapters, writes
// to tracked files. The doctor reports what it can see.

use std::path::{Path, PathBuf};

use anyhow::{Context, Result};
use chrono::Utc;

use crate::adapters;
use crate::commands::hook::{self, HookState};
use crate::config::{PerRepoConfig, Registry};
use crate::constants;
use crate::daemon;
use crate::engine::{self, BYTES_PER_MIB, SkipReason};
use crate::output;
use crate::scanner::{self, git};
use crate::setup;
use crate::workspace;

/// One repair `--fix` knows how to make. Every variant mends something that is already
/// installed but broken; none of them installs an integration for the first time.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Repair {
    /// The `dev-prune`/`devp` pair is missing a member, or the alias is stale.
    Twin,
    /// The `SKILL.md` export is missing or out of date.
    SkillFile,
    /// Installed hooks point at a deleted binary, or a chain has drifted.
    Hooks,
    /// The installed scheduler points at a deleted binary.
    Scheduler,
    /// Registered paths that no longer exist on disk.
    UnlinkMissing,
}

/// Tally of everything the report flagged, so the verdict is derived from the same
/// lines the user just read rather than recomputed from scratch.
#[derive(Default)]
struct Findings {
    warnings: Vec<String>,
    problems: Vec<String>,
    /// Repairs `--fix` would make, in the order their findings were reported.
    fixes: Vec<Repair>,
    /// Indices into `problems` that one of `fixes` addresses, so the repair verdict can
    /// tell "fixed by the pass that just ran" apart from "still needs a human".
    fixable_problems: Vec<usize>,
    /// The subset of `fixes` whose finding was a problem rather than a warning. A repair
    /// from this list that does not actually land leaves the problem standing, and the
    /// exit code has to say so.
    problem_repairs: Vec<Repair>,
}

impl Findings {
    /// A check that passed.
    fn ok(&mut self, label: &str, detail: &str) {
        println!("  {label:<22} {} {detail}", "✓".green());
    }

    /// Something to be aware of that is not stopping anything working.
    fn warn(&mut self, label: &str, detail: &str) {
        println!("  {label:<22} {} {detail}", "!".yellow());
        self.warnings.push(format!("{label}: {detail}"));
    }

    /// Something that is actually broken.
    fn problem(&mut self, label: &str, detail: &str) {
        println!("  {label:<22} {} {detail}", "✗".red());
        self.problems.push(format!("{label}: {detail}"));
    }

    /// Record that the most recent `warn` is one `--fix` can repair.
    fn fixable(&mut self, repair: Repair) {
        if !self.fixes.contains(&repair) {
            self.fixes.push(repair);
        }
    }

    /// Record that the most recent `problem` is one `--fix` can repair.
    ///
    /// Called immediately after the `problem` it belongs to, so the index bookkeeping
    /// stays next to the finding it describes.
    fn fixable_problem(&mut self, repair: Repair) {
        self.fixable(repair);
        if !self.problem_repairs.contains(&repair) {
            self.problem_repairs.push(repair);
        }
        if let Some(last) = self.problems.len().checked_sub(1) {
            if !self.fixable_problems.contains(&last) {
                self.fixable_problems.push(last);
            }
        }
    }

    /// A fact with no verdict attached.
    fn note(&self, label: &str, detail: &str) {
        println!("  {label:<22}   {detail}");
    }

    fn section(&self, title: &str) {
        println!();
        println!("{}", title.bold());
    }
}

// `colored` is used through these three, so the trait import stays local to the file.
use colored::Colorize as _;

/// Run the `doctor` command.
///
/// `path` is whatever the user typed, already tilde-expanded. `None` means the global
/// installation; `Some(".")` is an ordinary path like any other. `fix` applies the
/// repairs the installation check found; clap refuses `--fix` alongside a path, because
/// the repository check has nothing it could safely repair.
pub fn run(path: Option<&str>, fix: bool) -> Result<()> {
    match path {
        Some(p) => check_repository(p),
        None => check_installation(fix),
    }
}

/// Print the verdict and pick the exit code.
///
/// Warnings exit `0`. A doctor that fails the build because the scheduler is not
/// installed is a doctor people stop running; only the things that stop dev-prune doing
/// its job are worth a non-zero status.
fn verdict(f: &Findings, all_clear: &str, headline: Option<&str>) -> Result<()> {
    f.section("Verdict");

    if let Some(line) = headline {
        println!("  {line}");
        println!();
    }

    if f.problems.is_empty() && f.warnings.is_empty() {
        output::print_success(all_clear);
        return Ok(());
    }

    for w in &f.warnings {
        println!("  {} {w}", "!".yellow());
    }
    for p in &f.problems {
        println!("  {} {p}", "✗".red());
    }

    if !f.fixes.is_empty() {
        println!();
        println!(
            "  {} of these can be repaired automatically — run `devp doctor --fix`.",
            f.fixes.len()
        );
    }

    println!();
    println!("  Troubleshooting: {}", constants::TROUBLESHOOTING_URL);

    if f.problems.is_empty() {
        println!();
        output::print_info(&format!(
            "{} {} — nothing broken.",
            f.warnings.len(),
            output::plural(f.warnings.len(), "warning", "warnings")
        ));
        return Ok(());
    }

    anyhow::bail!(
        "{} {} found.",
        f.problems.len(),
        output::plural(f.problems.len(), "problem", "problems")
    )
}

// ---------------------------------------------------------------------------
// Global installation
// ---------------------------------------------------------------------------

fn check_installation(fix: bool) -> Result<()> {
    output::print_header("dev-prune doctor");
    let mut f = Findings::default();

    check_binary(&mut f);
    let registry = check_configuration(&mut f);
    check_integrations(&mut f, registry.as_ref());
    check_package_managers(&mut f, registry.as_ref());
    check_registry_health(&mut f, registry.as_ref());
    check_release_state(&mut f, registry.as_ref());

    if fix && !f.fixes.is_empty() {
        return apply_repairs(&f, registry.as_ref());
    }
    if fix {
        // `--fix` with nothing repairable falls through to the ordinary verdict: what
        // remains (if anything) needs a human, and saying which things is the verdict's
        // whole job.
        return verdict(&f, "Everything checks out — nothing to repair.", None);
    }
    verdict(&f, "Everything checks out.", None)
}

/// Apply every repair the diagnosis recorded, then give the repair verdict.
///
/// Each repair goes through the same `setup::ensure_*` passes the automatic setup uses,
/// so a repair can never do something the setup pass would not — and like that pass,
/// each one re-checks the state itself before touching anything, so a finding that
/// healed between diagnosis and repair reports "already in place" rather than being
/// re-applied.
///
/// `DEV_PRUNE_NO_AUTO_SETUP` disables every self-installation path, and the repairs
/// that write outside the config directory — the twin binary, the git hooks, the OS
/// scheduler — are exactly that, so with the variable set they are skipped and named.
/// Bookkeeping inside dev-prune's own config directory (the `SKILL.md` export, dead
/// registry entries) is not an installation and still runs.
///
/// Exit code: `0` unless a repair failed outright, a *problem*-level finding was left
/// unrepaired, or a problem remains that no repair addresses. A skipped repair whose
/// finding was only a warning (the twin is a running executable) exits `0` like any
/// other warning — the report says what to do, and nothing is more broken than it
/// already was.
fn apply_repairs(f: &Findings, registry: Option<&Registry>) -> Result<()> {
    f.section("Repairs");

    let ok = |label: &str, detail: &str| println!("  {label:<22} {} {detail}", "✓".green());
    let skipped = |label: &str, detail: &str| println!("  {label:<22} {} {detail}", "!".yellow());
    let failed_line = |label: &str, detail: &str| println!("  {label:<22} {} {detail}", "✗".red());

    let chain = registry
        .map(|r| r.settings.auto_hooks_chain)
        .unwrap_or(false);
    let interval = registry
        .map(|r| r.settings.check_interval_days)
        .unwrap_or(constants::DEFAULT_CHECK_INTERVAL_DAYS);
    let installs_off = setup::no_auto_setup_requested();

    let mut repaired = 0usize;
    let mut failures = 0usize;
    let mut attention = 0usize;
    // Problems whose repair was skipped rather than failed. Failures already count
    // toward the exit code; a skipped problem has to as well, because the breakage the
    // diagnosis reported is still there.
    let mut skipped_problems = 0usize;

    for repair in &f.fixes {
        let is_problem = f.problem_repairs.contains(repair);
        let (label, manual) = match repair {
            Repair::Twin => ("Binary pair", "run `dev-prune setup` yourself"),
            Repair::SkillFile => ("SKILL.md", "run `devp skill` yourself"),
            Repair::Hooks => ("Git hooks", "run `devp hook install` yourself"),
            Repair::Scheduler => ("Scheduler", "run `devp daemon install` yourself"),
            Repair::UnlinkMissing => {
                match crate::commands::link::run_unlink_missing() {
                    Ok(()) => repaired += 1,
                    Err(e) => {
                        failed_line("Registry", &format!("{e:#}"));
                        failures += 1;
                    }
                }
                continue;
            }
        };
        // These three write outside the config directory, which is precisely what the
        // variable exists to forbid.
        if installs_off && matches!(repair, Repair::Twin | Repair::Hooks | Repair::Scheduler) {
            skipped(
                label,
                &format!("{} is set — {manual}", setup::ENV_NO_AUTO_SETUP),
            );
            attention += 1;
            if is_problem {
                skipped_problems += 1;
            }
            continue;
        }
        let outcome = match repair {
            Repair::Twin => setup::ensure_alias(),
            Repair::SkillFile => setup::ensure_skill_file(),
            Repair::Hooks => setup::ensure_hooks(chain),
            Repair::Scheduler => setup::ensure_daemon(interval),
            Repair::UnlinkMissing => unreachable!("handled above"),
        };
        match outcome {
            setup::Outcome::Installed => {
                ok(label, "repaired");
                repaired += 1;
            }
            setup::Outcome::AlreadyPresent => {
                ok(label, "already in place");
                repaired += 1;
            }
            setup::Outcome::Skipped(why) => {
                skipped(label, &why);
                attention += 1;
                if is_problem {
                    skipped_problems += 1;
                }
            }
            setup::Outcome::Failed(why) => {
                failed_line(label, &why);
                failures += 1;
            }
        }
    }

    f.section("Verdict");
    let unfixable: Vec<&String> = f
        .problems
        .iter()
        .enumerate()
        .filter(|(i, _)| !f.fixable_problems.contains(i))
        .map(|(_, p)| p)
        .collect();
    for p in &unfixable {
        println!("  {} {p} (not auto-repairable)", "✗".red());
    }
    if !unfixable.is_empty() {
        println!();
        println!("  Troubleshooting: {}", constants::TROUBLESHOOTING_URL);
    }
    println!();
    output::print_info(&format!(
        "{repaired} repaired, {attention} skipped, {failures} failed. \
         Run `devp doctor` to confirm."
    ));

    let unresolved = failures + skipped_problems + unfixable.len();
    if unresolved > 0 {
        anyhow::bail!(
            "{unresolved} {} could not be repaired.",
            output::plural(unresolved, "finding", "findings")
        );
    }
    Ok(())
}

fn check_binary(f: &mut Findings) {
    f.section("Installation");
    f.note("Version", constants::VERSION);

    let Ok(exe) = std::env::current_exe() else {
        f.warn("Executable", "the running binary's own path is unavailable");
        return;
    };
    f.note("Executable", &output::clean_path(&exe));

    let Some(dir) = exe.parent() else { return };

    // The pair is one binary under two names, and either one can be the one running
    // right now. Looking for `devp` unconditionally made this check vacuous whenever
    // the user typed `devp doctor` — the file being looked for was the file doing the
    // looking, so it always "passed". Look for whichever name is *not* running.
    let running = if exe
        .file_stem()
        .and_then(|s| s.to_str())
        .is_some_and(|stem| stem.eq_ignore_ascii_case("devp"))
    {
        "devp"
    } else {
        "dev-prune"
    };
    let twin_stem = if running == "devp" {
        "dev-prune"
    } else {
        "devp"
    };
    let twin = dir.join(if cfg!(windows) {
        format!("{twin_stem}.exe")
    } else {
        twin_stem.to_string()
    });
    if !twin.exists() {
        f.warn(
            twin_stem,
            &format!("not installed next to {running} — run `{running} setup`"),
        );
        // Either name may recreate a twin that is missing outright.
        f.fixable(Repair::Twin);
    } else if same_binary(&exe, &twin) {
        f.ok(twin_stem, &output::clean_path(&twin));
    } else {
        // An upgrade that could not replace a running executable leaves exactly this
        // state, and the stale name silently runs the previous version from then on.
        f.warn(
            twin_stem,
            &format!(
                "{} is not the same binary as {} — one of the pair is stale and \
                 silently runs a different version. `dev-prune setup` refreshes `devp` \
                 from the canonical `dev-prune`.",
                output::clean_path(&twin),
                output::clean_path(&exe)
            ),
        );
        // Only the canonical `dev-prune` may overwrite a differing twin — `devp`
        // refreshing `dev-prune` could reinstall the version an upgrade just replaced.
        // So this is repairable only from the canonical side.
        if running == "dev-prune" {
            f.fixable(Repair::Twin);
        }
    }

    let sep = if cfg!(windows) { ';' } else { ':' };
    let on_path = std::env::var("PATH")
        .unwrap_or_default()
        .split(sep)
        .any(|p| !p.is_empty() && same_dir(Path::new(p), dir));
    if on_path {
        f.ok("PATH", &output::clean_path(dir));
    } else {
        f.problem(
            "PATH",
            &format!(
                "{} is not on PATH — `devp` will not resolve in a new shell",
                output::clean_path(dir)
            ),
        );
    }
}

/// Whether a PATH entry names the directory the binary lives in.
///
/// Windows paths are case-insensitive but `Path` equality is not, and PATH entries
/// routinely carry a trailing backslash the installer never wrote. Either mismatch made
/// doctor report a perfectly good install as "not on PATH" — as a problem, so `devp
/// doctor` exited 1 on a healthy machine.
fn same_dir(entry: &Path, dir: &Path) -> bool {
    if entry == dir {
        return true;
    }
    cfg!(windows) && {
        let norm = |p: &Path| {
            p.to_string_lossy()
                .trim_end_matches(['\\', '/'])
                .to_lowercase()
        };
        norm(entry) == norm(dir)
    }
}

/// Whether two files hold the same bytes.
///
/// Doctor runs at human speed, so when the cheap size test cannot rule the pair
/// different this reads both files outright — a stale twin left by a failed upgrade can
/// share a size with its replacement, and "same version" is the whole question here.
fn same_binary(a: &Path, b: &Path) -> bool {
    let (Ok(ma), Ok(mb)) = (std::fs::metadata(a), std::fs::metadata(b)) else {
        return false;
    };
    if ma.len() != mb.len() {
        return false;
    }
    matches!((std::fs::read(a), std::fs::read(b)), (Ok(ba), Ok(bb)) if ba == bb)
}

/// Read the config directory and validate every stored setting.
///
/// Returns `None` when the registry cannot be read, which is the one failure that makes
/// every later section meaningless — they all need the settings.
fn check_configuration(f: &mut Findings) -> Option<Registry> {
    f.section("Configuration");

    let dir = match Registry::config_dir() {
        Ok(d) => d,
        Err(e) => {
            f.problem("Config directory", &format!("cannot be resolved: {e}"));
            return None;
        }
    };
    f.note("Config directory", &output::clean_path(&dir));
    if std::env::var(constants::ENV_CONFIG_DIR_OVERRIDE).is_ok() {
        f.note(
            "",
            &format!("(set by {})", constants::ENV_CONFIG_DIR_OVERRIDE),
        );
    }

    let path = dir.join(constants::REGISTRY_FILENAME);
    if !path.exists() {
        // Not a fault. Absent configuration means defaults, which is the documented
        // behaviour — it is an unreadable one that dev-prune refuses to guess about.
        f.ok("registry.json", "not created yet — defaults apply");
        return Some(Registry::default());
    }

    let registry = match Registry::load_from(&path) {
        Ok(r) => r,
        Err(e) => {
            f.problem(
                "registry.json",
                &format!(
                    "{} — dev-prune refuses to guess at a config it cannot read. \
                     Fix the syntax, or delete the file to start from defaults.",
                    root_cause(&e)
                ),
            );
            return None;
        }
    };

    f.ok(
        "registry.json",
        &format!(
            "readable — {} {} registered",
            registry.repo_count(),
            output::plural(registry.repo_count(), "repository", "repositories")
        ),
    );

    let invalid = crate::commands::config::invalid_settings(&registry.settings);
    if invalid.is_empty() {
        f.ok(
            "Settings",
            &format!(
                "all {} within range",
                crate::commands::config::setting_count()
            ),
        );
    } else {
        for (key, why) in &invalid {
            f.problem("Settings", &format!("{key}: {why}"));
        }
    }

    Some(registry)
}

fn check_integrations(f: &mut Findings, registry: Option<&Registry>) {
    f.section("Integrations");

    match setup::skill_path() {
        Ok(p) if p.exists() => f.ok("SKILL.md", &output::clean_path(&p)),
        _ => {
            f.warn("SKILL.md", "not exported — run `devp skill`");
            f.fixable(Repair::SkillFile);
        }
    }

    if crate::commands::icon::is_registered() {
        f.ok("File icons", "registered with the file manager");
    } else {
        f.warn("File icons", "not registered — run `devp icon`");
    }

    if !hook::git_available() {
        f.warn(
            "Git hooks",
            "git is not on PATH, so repositories cannot auto-register",
        );
    } else {
        match hook::state() {
            Ok(HookState::Active) => check_hook_target(f, "active"),
            Ok(HookState::Absent) => f.warn("Git hooks", "not installed — run `devp hook install`"),
            Ok(HookState::Chained { previous, drifted }) if drifted.is_empty() => {
                check_hook_target(f, &format!("active, chained to `{previous}`"))
            }
            Ok(HookState::Chained { previous, drifted }) => {
                f.warn(
                    "Git hooks",
                    &format!(
                        "chained to `{previous}`, but {} not forwarded ({}) — \
                         re-run `devp hook install --chain`",
                        drifted.len(),
                        drifted.join(", ")
                    ),
                );
                // The chain is installed and merely out of date; reinstalling it is the
                // same repair the automatic setup pass makes.
                f.fixable(Repair::Hooks);
            }
            Ok(HookState::Foreign(p)) => f.warn(
                "Git hooks",
                &format!(
                    "core.hooksPath belongs to `{p}` — install in front of it with \
                     `devp hook install --chain`"
                ),
            ),
            Err(e) => f.warn("Git hooks", &format!("state unknown ({e})")),
        }
    }

    match daemon::daemon_status() {
        Ok(daemon::DaemonStatus::Installed) => check_scheduler_target(f),
        Ok(daemon::DaemonStatus::NotInstalled) => f.warn(
            "Scheduler",
            "not installed — nothing prunes on its own. `devp daemon install` adds it.",
        ),
        Ok(daemon::DaemonStatus::Unknown(why)) => f.warn("Scheduler", &why),
        Err(e) => f.warn("Scheduler", &format!("state unknown ({e})")),
    }

    if let Some(r) = registry {
        f.note(
            "Automatic setup",
            &format!(
                "auto_setup={} auto_hooks={} auto_daemon={}",
                r.settings.auto_setup, r.settings.auto_hooks, r.settings.auto_daemon
            ),
        );
    }

    // Said out loud, because "auto_setup = true" next to integrations that never install
    // is a contradiction the user has no other way to explain.
    if let Some(why) = setup::unattended_environment() {
        f.note("", &format!("unattended installation is off because {why}"));
    }
    // The same presence test the suppression itself uses — `=true`, `=0` and even an
    // empty value all switch setup off, so all of them must be reported here.
    if setup::no_auto_setup_requested() {
        f.note(
            "",
            &format!(
                "{} is set — nothing installs by itself. `devp setup` still works.",
                setup::ENV_NO_AUTO_SETUP
            ),
        );
    }
}

/// Report an installed integration, and whether the binary it will run is still there.
///
/// An installed scheduler and an installed hook are both silent by construction — the
/// scheduled task has no console and the hook throws its own output away — so a recorded
/// path that has since been deleted produces no symptom whatsoever. Every interval, the
/// task fails instantly; every commit, the hook does nothing. This is the only place that
/// says so.
///
/// The path goes stale when the integration is installed from somewhere temporary:
/// `npx dev-prune`, `uvx dev-prune`, or a `target/debug` build during development. Those
/// no longer record the temporary path (see `setup::stable_exe_path`), but entries
/// registered before that are still out there, and a user can always delete the binary
/// out from under a perfectly ordinary install.
fn report_integration_target(
    f: &mut Findings,
    label: &str,
    installed: &str,
    recorded: Option<std::path::PathBuf>,
    repair: &str,
) -> bool {
    match recorded {
        // Nothing to report: the entry is unreadable on this machine, which is not
        // evidence of a problem. Saying so would be a warning nobody can act on.
        None => f.ok(label, installed),
        Some(path) if path.is_file() => f.ok(
            label,
            &format!("{installed} — {}", output::clean_path(&path)),
        ),
        Some(path) => {
            f.problem(
                label,
                &format!(
                    "registered, but `{}` no longer exists — it never runs. {repair}",
                    output::clean_path(&path)
                ),
            );
            return true;
        }
    }
    false
}

fn check_scheduler_target(f: &mut Findings) {
    if report_integration_target(
        f,
        "Scheduler",
        "installed",
        daemon::registered_exe_path(),
        "Re-register it with `devp daemon install`.",
    ) {
        f.fixable_problem(Repair::Scheduler);
    }
}

fn check_hook_target(f: &mut Findings, installed: &str) {
    if report_integration_target(
        f,
        "Git hooks",
        installed,
        hook::registered_exe_path(),
        "Rewrite them with `devp hook install`.",
    ) {
        f.fixable_problem(Repair::Hooks);
    }
}

/// Check the package-manager binaries the registered repositories actually need.
///
/// Every adapter, not just the needed ones, would report `bun: not found` on a machine
/// with no JavaScript on it at all — a warning about a tool the user has deliberately not
/// installed. So the list comes from what is registered, and only falls back to all eight
/// when nothing is registered yet and there is nothing else to go on.
fn check_package_managers(f: &mut Findings, registry: Option<&Registry>) {
    f.section("Package managers");

    // `required` distinguishes a manager some registered repository actually depends on
    // from one merely listed for completeness. Warning that `go` is absent on a machine
    // with no Go project on it is noise the user cannot act on and would not want to.
    let (needed, required): (Vec<String>, bool) = match registry {
        Some(r) if r.repo_count() > 0 => {
            let mut names: Vec<String> = engine::get_full_status(r)
                .into_iter()
                .flat_map(|e| e.adapters)
                .collect();
            names.sort();
            names.dedup();
            (names, true)
        }
        _ => (
            adapters::get_all_adapters()
                .iter()
                .map(|a| a.name().to_string())
                .collect(),
            false,
        ),
    };

    if needed.is_empty() {
        f.note(
            "",
            "no package managers are needed by the registered repositories",
        );
        return;
    }
    if !required {
        f.note("", "nothing is registered yet, so this is the full list");
    }

    for status in adapters::scan_required_binaries(&needed) {
        match (status.available, status.version) {
            (true, Some(v)) => f.ok(&status.name, &v),
            (true, None) => f.ok(&status.name, "available"),
            (false, _) if required => f.warn(
                &status.name,
                "not on PATH — projects using it cannot be verified, pruned or restored",
            ),
            (false, _) => f.note(&status.name, "not installed"),
        }
    }

    // `venv` is filtered out of the binary scan because it is not a command; its restore
    // path still needs an interpreter, and that is worth saying once.
    if required && needed.iter().any(|n| n == "venv") && !adapters::binary_available("python") {
        f.warn(
            "python",
            "not on PATH — `devp restore` cannot rebuild a plain virtual environment",
        );
    }
}

fn check_registry_health(f: &mut Findings, registry: Option<&Registry>) {
    f.section("Registered repositories");

    let Some(registry) = registry else { return };
    if registry.repo_count() == 0 {
        f.note("", "none yet — `devp init ~/Code` or `devp link .`");
        return;
    }

    let entries = engine::get_full_status(registry);
    let count = |want: &SkipReason| {
        entries
            .iter()
            .filter(|e| std::mem::discriminant(&e.reason) == std::mem::discriminant(want))
            .count()
    };
    let reclaimable: u64 = entries.iter().map(|e| e.reclaimable_bytes).sum();

    f.note(
        "Total",
        &format!(
            "{} registered, {} reclaimable",
            entries.len(),
            output::format_bytes(reclaimable)
        ),
    );
    f.note(
        "Breakdown",
        &format!(
            "{} candidates, {} active, {} ignored, {} with no bloat",
            count(&SkipReason::Candidate),
            count(&SkipReason::Active),
            count(&SkipReason::Ignored),
            count(&SkipReason::NoBloat),
        ),
    );

    // A path that has gone is stale bookkeeping, not breakage: the pass reports it and
    // moves on, so this warns rather than failing. Listing thirty of them individually
    // buries every other finding, and thirty `devp unlink` lines is not a fix anyone will
    // run — so they collapse to a count and the one command that clears all of them.
    let missing: Vec<&Path> = entries
        .iter()
        .filter(|e| matches!(e.reason, SkipReason::PathMissing))
        .map(|e| e.path.as_path())
        .collect();

    match missing.len() {
        0 => {}
        1 => {
            f.warn(
                "Missing",
                &format!(
                    "{} no longer exists — `devp unlink {}`",
                    output::clean_path(missing[0]),
                    output::clean_path(missing[0])
                ),
            );
            f.fixable(Repair::UnlinkMissing);
        }
        n => {
            f.warn(
                "Missing",
                &format!(
                    "{n} registered paths no longer exist, starting with {} \
                     — `devp unlink --missing` clears all of them",
                    output::clean_path(missing[0])
                ),
            );
            f.fixable(Repair::UnlinkMissing);
        }
    }

    // An unreadable `.devprune.json` *is* breakage: the file that cannot be read may be
    // the one saying `"ignore": true`, so the repository is skipped until it is fixed.
    for entry in &entries {
        if let SkipReason::ConfigError(e) = &entry.reason {
            f.problem(
                "Unreadable config",
                &format!("{}: {e}", output::clean_path(&entry.path)),
            );
        }
    }
}

fn check_release_state(f: &mut Findings, registry: Option<&Registry>) {
    f.section("Release check");

    let Some(registry) = registry else { return };
    if !registry.settings.update_check {
        f.note(
            "update_check",
            "off — dev-prune opens no network connection",
        );
        return;
    }

    f.note(
        "update_check",
        &format!(
            "on, every {} {}",
            registry.settings.update_check_interval_days,
            output::plural(
                registry.settings.update_check_interval_days as usize,
                "day",
                "days"
            )
        ),
    );

    match registry.last_update_check {
        Some(at) => f.note(
            "Last checked",
            &format!(
                "{} ({} days ago)",
                at.format("%Y-%m-%d %H:%M UTC"),
                (Utc::now() - at).num_days()
            ),
        ),
        None => f.note("Last checked", "never"),
    }

    match registry.latest_known_version.as_deref() {
        Some(latest) if latest.trim_start_matches('v') != constants::VERSION => f.warn(
            "Latest release",
            &format!("{latest} is available — `devp update` shows how to upgrade"),
        ),
        Some(latest) => f.ok("Latest release", &format!("{latest} — up to date")),
        None => f.note("Latest release", "not known yet"),
    }
}

// ---------------------------------------------------------------------------
// One repository
// ---------------------------------------------------------------------------

fn check_repository(path_str: &str) -> Result<()> {
    let path = Path::new(path_str)
        .canonicalize()
        .with_context(|| format!("Path not found: {path_str}"))?;

    output::print_header(&format!("dev-prune doctor ({})", output::clean_path(&path)));
    let mut f = Findings::default();

    // Loaded, not defaulted: a repository's verdict depends on the global thresholds, and
    // silently using the defaults would explain the wrong tool's behaviour.
    let registry = Registry::load().unwrap_or_default();

    let ctx = check_repo_basics(&mut f, &path, &registry);
    let projects = check_repo_projects(&mut f, &path, &ctx);
    let headline = repo_verdict(&ctx, &projects);

    verdict(
        &f,
        &format!("{} is in good shape.", output::clean_path(&ctx.path)),
        Some(&headline),
    )
}

/// Everything about the repository that is decided before any project is looked at.
struct RepoContext {
    path: PathBuf,
    is_git: bool,
    registered: bool,
    opted_out: Option<String>,
    config_broken: bool,
    idle: bool,
    idle_days: u64,
    min_size_bytes: u64,
    depth: usize,
}

fn check_repo_basics(f: &mut Findings, path: &Path, registry: &Registry) -> RepoContext {
    f.section("Repository");

    let is_git = scanner::is_git_repo(path);
    if is_git {
        f.ok("Git repository", "yes");
    } else {
        f.problem(
            "Git repository",
            "no — dev-prune only ever touches Git repositories",
        );
    }

    let key = crate::config::canonical_key(path);
    let entry = registry.repositories.get(&key);
    match entry {
        Some(e) if e.enabled => f.ok(
            "Registered",
            &format!("yes, since {}", e.added_at.format("%Y-%m-%d")),
        ),
        Some(e) => f.warn(
            "Registered",
            &format!(
                "yes since {}, but disabled — `devp config {} --update`",
                e.added_at.format("%Y-%m-%d"),
                output::clean_path(path)
            ),
        ),
        None => f.warn(
            "Registered",
            "no — a prune pass will not visit it. `devp link .` registers it.",
        ),
    }
    if let Some(at) = entry.and_then(|e| e.last_pruned_at) {
        f.note("Last pruned", &at.format("%Y-%m-%d %H:%M UTC").to_string());
    }

    // Read exactly the way the prune pass reads it, refusal to guess included.
    let (per_repo, config_broken) = match PerRepoConfig::load_with_diagnostics(path) {
        Ok(Some(cfg)) => {
            f.ok(constants::PER_REPO_CONFIG_FILE, &describe_overrides(&cfg));
            (Some(cfg), false)
        }
        Ok(None) => {
            f.note(
                constants::PER_REPO_CONFIG_FILE,
                "absent — global settings apply",
            );
            (None, false)
        }
        Err(e) => {
            f.problem(
                constants::PER_REPO_CONFIG_FILE,
                &format!("{e} — the repository is skipped entirely until this parses"),
            );
            (None, true)
        }
    };

    let mut opted_out = None;
    if path.join(constants::DEVPRUNE_IGNORE_FILE).exists() {
        opted_out = Some(format!("{} is present", constants::DEVPRUNE_IGNORE_FILE));
    } else if per_repo.as_ref().is_some_and(|c| c.ignore) {
        opted_out = Some(format!(
            "\"ignore\": true in {}",
            constants::PER_REPO_CONFIG_FILE
        ));
    } else if entry.is_some_and(|e| !e.enabled) {
        opted_out = Some("disabled in the registry".to_string());
    }
    match &opted_out {
        Some(why) => f.note("Opt-out", why),
        None => f.note("Opt-out", "none"),
    }

    // The same three-level resolution the engine performs: the repository's own file
    // beats its registry override, which beats the global setting.
    let idle_days = per_repo
        .as_ref()
        .and_then(|c| c.override_idle_days)
        .or_else(|| entry.and_then(|e| e.override_idle_days))
        .unwrap_or(registry.settings.idle_days);

    let activity = git::get_last_activity(path).ok().flatten();
    let idle = git::is_idle_at(activity, idle_days);
    match activity {
        Some(t) => {
            let days = chrono::DateTime::<Utc>::from(t);
            let ago = (Utc::now() - days).num_days();
            let detail = format!(
                "{} ({ago} {} ago), threshold {idle_days}",
                days.format("%Y-%m-%d"),
                output::plural(ago.unsigned_abs() as usize, "day", "days")
            );
            if idle {
                f.ok("Activity", &format!("{detail} — idle"));
            } else {
                f.note("Activity", &format!("{detail} — active"));
            }
        }
        None => f.note(
            "Activity",
            &format!("no commits or source edits found, threshold {idle_days}"),
        ),
    }

    let min_size_mb = per_repo
        .as_ref()
        .and_then(|c| c.min_size_mb)
        .unwrap_or(registry.settings.min_size_mb);
    f.note(
        "Size floor",
        &if min_size_mb == 0 {
            "none — every recognised directory counts".to_string()
        } else {
            format!("{min_size_mb} MiB")
        },
    );

    let depth = workspace::resolve_depth(path, registry.settings.scan_depth);
    f.note("Scan depth", &format!("{depth} levels below the root"));

    RepoContext {
        path: path.to_path_buf(),
        is_git,
        registered: entry.is_some(),
        opted_out,
        config_broken,
        idle,
        idle_days,
        min_size_bytes: min_size_mb.saturating_mul(BYTES_PER_MIB),
        depth,
    }
}

/// One project's worth of findings, kept so the verdict can reason over all of them.
struct ProjectReport {
    /// Whether any bloat directory here is above the floor and not symlinked.
    prunable: bool,
    /// Whether anything was found at all.
    has_bloat: bool,
}

fn check_repo_projects(f: &mut Findings, path: &Path, ctx: &RepoContext) -> Vec<ProjectReport> {
    f.section("Projects");

    if ctx.config_broken {
        f.note(
            "",
            "not scanned — the configuration above has to parse first",
        );
        return Vec::new();
    }

    let projects = workspace::discover_to_depth(path, ctx.depth);
    if projects.is_empty() {
        f.note(
            "",
            &format!(
                "no recognised package-manager project within {} levels. \
                 Raise it with `devp config set scan_depth N`.",
                ctx.depth
            ),
        );
        return Vec::new();
    }

    let mut reports = Vec::new();
    for project in &projects {
        for adapter in &project.adapters {
            println!();
            println!("  {} ({})", project.relative.bold(), adapter.name());

            // Presence only. Proving a lockfile is *usable* means running the package
            // manager, which is minutes of work and, for cargo and go, a write.
            let missing: Vec<&str> = adapter
                .lockfiles()
                .iter()
                .copied()
                .filter(|n| !project.path.join(n).exists())
                .collect();
            match (adapter.lockfiles().is_empty(), missing.is_empty()) {
                (true, _) => f.note("    Lockfile", "no single file identifies this manager"),
                (false, true) => f.ok(
                    "    Lockfile",
                    &format!("{} present", adapter.lockfiles().join(", ")),
                ),
                // Every listed file absent — for bun, whose two spellings are
                // alternatives, that means neither is there.
                (false, false) if missing.len() == adapter.lockfiles().len() => f.problem(
                    "    Lockfile",
                    &format!(
                        "{} missing — nothing can prove the directory is rebuildable, \
                         so it will never be pruned",
                        missing.join(" / ")
                    ),
                ),
                (false, false) => f.ok(
                    "    Lockfile",
                    &format!(
                        "{} present",
                        adapter
                            .lockfiles()
                            .iter()
                            .filter(|n| !missing.contains(n))
                            .copied()
                            .collect::<Vec<_>>()
                            .join(", ")
                    ),
                ),
            }

            let bloat = adapter.bloat_dirs(&project.path);
            if bloat.is_empty() {
                f.note("    Bloat", "nothing installed — nothing to reclaim");
                reports.push(ProjectReport {
                    prunable: false,
                    has_bloat: false,
                });
                continue;
            }

            let mut prunable = false;
            for bd in &bloat {
                let label = workspace::relative_label(path, &bd.path);
                let size = output::format_bytes(bd.size_bytes);

                if std::fs::symlink_metadata(&bd.path)
                    .map(|m| m.file_type().is_symlink())
                    .unwrap_or(false)
                {
                    f.warn(
                        "    Bloat",
                        &format!(
                            "{label} ({size}) is a symlink — refused, because the storage \
                             it points at is not this repository's to delete"
                        ),
                    );
                } else if bd.size_bytes < ctx.min_size_bytes {
                    f.warn(
                        "    Bloat",
                        &format!("{label} ({size}) is below the size floor — left alone"),
                    );
                } else {
                    f.ok("    Bloat", &format!("{label} ({size})"));
                    prunable = true;
                }
            }
            reports.push(ProjectReport {
                prunable,
                has_bloat: true,
            });
        }
    }

    reports
}

/// Name the one reason this repository would not be pruned right now.
///
/// In the order the prune pass applies them, so the answer matches what `devp run` would
/// actually do rather than listing everything that happens to be true.
fn repo_verdict(ctx: &RepoContext, projects: &[ProjectReport]) -> String {
    let clean = output::clean_path(&ctx.path);
    let no = |detail: String| format!("{} Would `devp run` prune this? {detail}", "✗".red());

    if !ctx.is_git {
        no("No — not a Git repository. Nothing else is even checked.".to_string())
    } else if ctx.config_broken {
        no(format!(
            "No — `{}` does not parse, and dev-prune will not guess at a config it \
             cannot read.",
            constants::PER_REPO_CONFIG_FILE
        ))
    } else if let Some(why) = &ctx.opted_out {
        no(format!("No — opted out: {why}."))
    } else if !ctx.registered {
        no(format!(
            "Not in a full pass — it is not registered. `devp link {clean}` adds it; \
             `devp run {clean}` prunes it once without registering."
        ))
    } else if !ctx.idle {
        no(format!(
            "No — active within the last {} {}. `devp --ignore-idle run {clean}` overrides \
             exactly that check and nothing else.",
            ctx.idle_days,
            output::plural(ctx.idle_days as usize, "day", "days")
        ))
    } else if projects.is_empty() {
        no("No — no package-manager project was found to prune.".to_string())
    } else if !projects.iter().any(|p| p.has_bloat) {
        no("No — every project here is already clean.".to_string())
    } else if !projects.iter().any(|p| p.prunable) {
        no("No — everything found is symlinked or below the size floor. See above.".to_string())
    } else {
        format!(
            "{} Would `devp run` prune this? Yes — subject to each lockfile verifying. \
             `devp run {clean} --dry-run` lists what would go.",
            "✓".green()
        )
    }
}

/// One line describing what a `.devprune.json` actually overrides.
fn describe_overrides(cfg: &PerRepoConfig) -> String {
    let mut parts = Vec::new();
    if let Some(name) = &cfg.project_name {
        parts.push(format!("name={name}"));
    }
    if let Some(days) = cfg.override_idle_days {
        parts.push(format!("idle_days={days}"));
    }
    if let Some(mb) = cfg.min_size_mb {
        parts.push(format!("min_size_mb={mb}"));
    }
    if let Some(depth) = cfg.scan_depth {
        parts.push(format!("scan_depth={depth}"));
    }
    if cfg.ignore {
        parts.push("ignore=true".to_string());
    }
    if cfg.disable_hooks {
        parts.push("disable_hooks=true".to_string());
    }
    if cfg.disable_daemon {
        parts.push("disable_daemon=true".to_string());
    }
    if parts.is_empty() {
        "parses; overrides nothing".to_string()
    } else {
        format!("parses; {}", parts.join(", "))
    }
}

/// The innermost cause of an error, which is the part that says what is actually wrong.
///
/// `anyhow`'s `{:#}` prints the whole chain, and the outer links here are all "failed to
/// parse the registry at <path>" — which the report has already said.
fn root_cause(e: &anyhow::Error) -> String {
    e.chain().last().map(|c| c.to_string()).unwrap_or_default()
}

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

    #[test]
    fn an_integration_pointing_at_a_deleted_binary_is_a_problem_not_a_warning() {
        // The whole point of the check: this is broken, not merely worth knowing, so it
        // has to reach the non-zero exit code.
        let mut f = Findings::default();
        report_integration_target(
            &mut f,
            "Scheduler",
            "installed",
            Some(PathBuf::from("/nonexistent/dev-prune")),
            "Re-register it.",
        );
        assert_eq!(f.warnings.len(), 0);
        assert_eq!(f.problems.len(), 1);
        assert!(f.problems[0].contains("no longer exists"));
    }

    #[test]
    fn an_integration_whose_binary_is_present_passes() {
        let tmp = TempDir::new().unwrap();
        let exe = tmp.path().join("dev-prune");
        std::fs::write(&exe, b"binary").unwrap();

        let mut f = Findings::default();
        report_integration_target(&mut f, "Scheduler", "installed", Some(exe), "Re-register.");
        assert!(f.problems.is_empty() && f.warnings.is_empty());
    }

    #[test]
    fn an_unreadable_entry_is_not_reported_as_broken() {
        // `None` means the platform could not tell us, which is not evidence of a
        // problem — reporting it would be a warning nobody can act on.
        let mut f = Findings::default();
        report_integration_target(&mut f, "Scheduler", "installed", None, "Re-register.");
        assert!(f.problems.is_empty() && f.warnings.is_empty());
    }

    #[test]
    fn overrides_are_listed_by_name() {
        let mut cfg = PerRepoConfig::default();
        assert_eq!(describe_overrides(&cfg), "parses; overrides nothing");

        cfg.override_idle_days = Some(30);
        cfg.ignore = true;
        assert_eq!(
            describe_overrides(&cfg),
            "parses; idle_days=30, ignore=true"
        );
    }

    /// `min_size_mb: 0` is a value, not an absence — it opts a repository out of a global
    /// floor, so the report has to show it rather than treating it as unset.
    #[test]
    fn a_zero_floor_is_reported_as_an_override() {
        let cfg = PerRepoConfig {
            min_size_mb: Some(0),
            ..PerRepoConfig::default()
        };
        assert_eq!(describe_overrides(&cfg), "parses; min_size_mb=0");
    }

    #[test]
    fn a_repository_that_is_not_a_git_repo_is_the_first_thing_reported() {
        let dir = TempDir::new().unwrap();
        let ctx = RepoContext {
            path: dir.path().to_path_buf(),
            is_git: false,
            registered: false,
            opted_out: Some("ignore.devprune.json is present".to_string()),
            config_broken: true,
            idle: true,
            idle_days: 15,
            min_size_bytes: 0,
            depth: 6,
        };
        // Three reasons are true at once; the verdict names the one the prune pass would
        // hit first, which is the one the user has to fix before any other matters.
        let line = repo_verdict(&ctx, &[]);
        assert!(line.contains("not a Git repository"), "{line}");
    }

    #[test]
    fn warnings_alone_do_not_fail_the_command() {
        let mut f = Findings::default();
        f.warn("Scheduler", "not installed");
        assert!(verdict(&f, "fine", None).is_ok());

        f.problem("PATH", "missing");
        assert!(verdict(&f, "fine", None).is_err());
    }

    #[test]
    #[cfg(windows)]
    fn a_path_entry_matches_regardless_of_case_and_trailing_separator() {
        // Both differences are ones Windows itself ignores, and either used to turn
        // into a "not on PATH" problem — a healthy install failing `devp doctor`.
        let dir = Path::new(r"C:\Users\Someone\AppData\Roaming\dev-prune\bin");
        assert!(same_dir(
            Path::new(r"c:\users\someone\appdata\roaming\dev-prune\bin\"),
            dir
        ));
        assert!(!same_dir(Path::new(r"C:\Windows"), dir));
    }

    #[test]
    #[cfg(not(windows))]
    fn a_path_entry_on_unix_is_matched_exactly() {
        assert!(same_dir(
            Path::new("/usr/local/bin"),
            Path::new("/usr/local/bin")
        ));
        assert!(!same_dir(
            Path::new("/USR/local/bin"),
            Path::new("/usr/local/bin")
        ));
    }

    #[test]
    fn a_stale_twin_is_told_apart_from_a_current_one() {
        let dir = TempDir::new().unwrap();
        let a = dir.path().join("dev-prune");
        let b = dir.path().join("devp");
        std::fs::write(&a, b"version two").unwrap();
        std::fs::write(&b, b"version two").unwrap();
        assert!(same_binary(&a, &b));

        // Same length, different bytes — the case a size-only test waves through.
        std::fs::write(&b, b"version one").unwrap();
        assert!(!same_binary(&a, &b));

        std::fs::write(&b, b"short").unwrap();
        assert!(!same_binary(&a, &b));
        assert!(!same_binary(&a, &dir.path().join("missing")));
    }
}