heal-cli 0.4.0

//! HEAL configuration (`.heal/config.toml`).
//!
//! All structs use `deny_unknown_fields` so typos in user configs surface as
//! schema errors instead of silently dropping settings.

use std::collections::BTreeMap;
use std::path::Path;

use serde::{Deserialize, Serialize};

use crate::core::error::{Error, Result};
use crate::core::fs::atomic_write;

#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct Config {
    #[serde(default)]
    pub project: ProjectConfig,
    #[serde(default)]
    pub git: GitConfig,
    #[serde(default)]
    pub metrics: MetricsConfig,
    #[serde(default)]
    pub policy: PolicyConfig,
    #[serde(default)]
    pub diff: DiffConfig,
    #[serde(default)]
    pub features: FeaturesConfig,
}

/// `heal diff` settings. Defaults are tuned to feel safe on small to
/// mid-size repos; very large monorepos should override
/// `max_loc_threshold` (or run `heal status` against two branches and
/// diff the JSON manually instead).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct DiffConfig {
    /// LOC ceiling for the worktree-based mode of `heal diff`. When the
    /// current repo's LOC count exceeds this, the command exits with
    /// code 2 and points at the manual two-branch flow. The cost the
    /// gate is protecting against: `git worktree add` + a full observer
    /// scan against an arbitrary git ref, which scales with LOC.
    #[serde(default = "DiffConfig::default_max_loc_threshold")]
    pub max_loc_threshold: u64,
}

impl DiffConfig {
    pub(crate) const DEFAULT_MAX_LOC_THRESHOLD: u64 = 200_000;

    fn default_max_loc_threshold() -> u64 {
        Self::DEFAULT_MAX_LOC_THRESHOLD
    }
}

impl Default for DiffConfig {
    fn default() -> Self {
        Self {
            max_loc_threshold: Self::DEFAULT_MAX_LOC_THRESHOLD,
        }
    }
}

/// Top-level feature flags. Each `[features.<name>]` block gates an
/// optional capability that defaults to disabled, so an existing
/// `.heal/config.toml` from a prior version gains no new behavior
/// merely by upgrading the binary.
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct FeaturesConfig {
    #[serde(default)]
    pub docs: DocsConfig,
    #[serde(default)]
    pub test: TestConfig,
}

/// `[features.docs]` — optional doc-quality observers that compare
/// committed documentation against the source it describes (drift,
/// freshness, coverage, internal link health, orphans, TODO density).
/// Defaults to disabled. Network access stays out of scope — external
/// link checking and example execution belong to CI / dedicated tools.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct DocsConfig {
    /// Master enable switch. While false, every docs observer is a
    /// no-op and `.heal/doc_pairs.json` is not consulted.
    pub enabled: bool,
    /// Project-relative path to the doc-pairs `SSoT`. The file is the
    /// single source of truth for Layer A (paired) src ⇔ doc mappings;
    /// HEAL only reads it. Generation is the `/heal-doc-pair-setup`
    /// skill's responsibility. Defaults to `.heal/doc_pairs.json`.
    #[serde(default = "DocsConfig::default_pairs_path")]
    pub pairs_path: String,
    /// Project-relative root the `/heal-doc-scaffold` skill writes
    /// page skeletons into. The HEAL binary never reads or writes
    /// this tree itself; it is consumer metadata for the skill so
    /// teammates re-running the scaffold land in the same place.
    /// Defaults to `.heal/docs` — same `.heal/` umbrella as
    /// `pairs_path`, `calibration.toml`, and `findings/`. The
    /// default keeps scaffold output out of any pre-existing
    /// `docs/` tree the project already owns (Starlight, mdBook,
    /// mkdocs); promote to a published location with
    /// `scaffold_root = "docs"` once the skeletons are reviewed.
    #[serde(default = "DocsConfig::default_scaffold_root")]
    pub scaffold_root: String,
    /// Layer B — standalone prose docs (README, concept guides) that
    /// need link / orphan / todo / duplication checks but no pair
    /// matching.
    #[serde(default)]
    pub standalone: StandaloneDocsConfig,
    /// Calibration overrides for `doc_freshness`. Held in
    /// `config.toml` so they survive `heal calibrate --force`
    /// (invariants R9). Absolute commit-distance floors only — no
    /// percentile distribution.
    #[serde(default)]
    pub doc_freshness: DocFreshnessConfig,
    /// `[features.docs.hotspot]` — per-pair
    /// `paired_src_churn × debt` composite. Calibration-driven; the
    /// section holds `floor_ok`, `top_n`, and the `weight_drift`
    /// multiplier on the dangling-identifier component of the debt
    /// score so users can dial drift up if they care more about
    /// factually-wrong docs than about merely-stale ones.
    #[serde(default)]
    pub hotspot: DocHotspotConfig,
    /// `[features.docs.todo_density]` — per-doc marker counter
    /// behaviour. Defaults skip markers inside backtick-quoted spans
    /// (the doc is *quoting* the keyword, not flagging an action item)
    /// and apply no per-doc allowlist. Documents that legitimately
    /// describe `TODO` / `FIXME` keywords (e.g. an observer reference)
    /// can opt into per-path skipping via `allowlist_paths` without
    /// disabling the observer for the whole project.
    #[serde(default)]
    pub todo_density: TodoDensityConfig,
    /// `[features.docs.doc_link_health]` — knobs for the relative-link
    /// resolver. Defaults check every internal link against the
    /// repo-relative file tree; site-deploy-aware skipping is opt-in
    /// via `exclude_link_prefixes`.
    #[serde(default)]
    pub doc_link_health: DocLinkHealthConfig,
}

impl Eq for DocsConfig {}

impl DocsConfig {
    pub(crate) const DEFAULT_PAIRS_PATH: &'static str = ".heal/doc_pairs.json";
    pub(crate) const DEFAULT_SCAFFOLD_ROOT: &'static str = ".heal/docs";

    fn default_pairs_path() -> String {
        Self::DEFAULT_PAIRS_PATH.to_owned()
    }

    fn default_scaffold_root() -> String {
        Self::DEFAULT_SCAFFOLD_ROOT.to_owned()
    }
}

impl Default for DocsConfig {
    fn default() -> Self {
        Self {
            enabled: false,
            pairs_path: Self::default_pairs_path(),
            scaffold_root: Self::default_scaffold_root(),
            standalone: StandaloneDocsConfig::default(),
            doc_freshness: DocFreshnessConfig::default(),
            hotspot: DocHotspotConfig::default(),
            todo_density: TodoDensityConfig::default(),
            doc_link_health: DocLinkHealthConfig::default(),
        }
    }
}

/// `[features.docs.doc_link_health]` — link-resolver knobs.
///
/// The observer otherwise checks every internal link target against
/// the repo-relative file tree. `exclude_link_prefixes` opts links
/// whose target starts with any listed prefix out of that check
/// entirely — use it for static-site deploy URLs (Starlight `base:`,
/// `VitePress` `base:`, Docusaurus `baseUrl`) that rewrite to source
/// files HEAL can't observe without parsing the framework config.
/// The framework's own build-time link checker (e.g. `astro build`,
/// `vitepress build`) catches the same broken links from the deploy
/// side, so HEAL can defer that slice without losing coverage.
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct DocLinkHealthConfig {
    /// URL prefixes that mark a link as "deploy-side, not repo-side".
    /// Prefix-match (not glob); a link target starting with any entry
    /// is skipped entirely — neither path nor anchor is verified.
    /// Empty (default) preserves the pre-knob behaviour where every
    /// internal link is checked against the source tree.
    ///
    /// Typical values:
    /// - `["/heal/"]` for Starlight deployed under `base: '/heal'`
    /// - `["/docs/"]` for `VitePress` / Docusaurus deployed at `/docs/`
    #[serde(default)]
    pub exclude_link_prefixes: Vec<String>,
}

/// `[features.docs.hotspot]` — per-pair `paired_src_churn × debt`
/// composite. The composite reads from `ChurnReport`,
/// `DocFreshnessReport`, and `DocDriftReport`; this config block
/// carries the calibration `floor_ok` override (so it survives
/// `heal calibrate --force`, per `invariants.md` R9), the per-metric
/// `top_n`, and the `weight_drift` multiplier on the dangling-
/// identifier debt component.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct DocHotspotConfig {
    /// Calibration override — `None` defers to
    /// `core::calibration::FLOOR_OK_DOC_HOTSPOT`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub floor_ok: Option<f64>,
    /// Per-metric override for `metrics.top_n` — top doc-hotspot pairs.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub top_n: Option<usize>,
    /// Multiplier on `dangling_idents` inside the debt score
    /// (`debt = src_commits_since_doc + weight_drift × dangling_idents`).
    /// Default `1.0` — equal weight per signal unit. Raise it if
    /// factually-wrong docs (`doc_drift`) should outrank merely-stale
    /// ones (`doc_freshness`) in the same pair.
    #[serde(default = "default_weight")]
    pub weight_drift: f64,
}

impl Eq for DocHotspotConfig {}

impl Default for DocHotspotConfig {
    fn default() -> Self {
        Self {
            floor_ok: None,
            top_n: None,
            weight_drift: default_weight(),
        }
    }
}

/// `[features.docs.standalone]` — gitignore-syntax globs that pick
/// the Layer B prose-doc universe out of the project tree. Defaults
/// include common Markdown / RST docs and exclude history / governance
/// files where drift signals don't apply (CHANGELOG, ADR, generated
/// API reference).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct StandaloneDocsConfig {
    #[serde(default = "StandaloneDocsConfig::default_include")]
    pub include: Vec<String>,
    #[serde(default = "StandaloneDocsConfig::default_exclude")]
    pub exclude: Vec<String>,
    /// gitignore-syntax globs naming docs that are reachable through
    /// channels the observer can't see — Starlight / Hugo / Docusaurus
    /// sidebar configs, mkdocs nav lists, mdBook `SUMMARY.md`. Pages
    /// matching any entrypoint glob are never reported as
    /// `orphan_pages` even when no other Markdown body links to them.
    /// Extends the built-in `README.md` / `index.{md,mdx,rst}` recognition.
    #[serde(default)]
    pub entrypoints: Vec<String>,
}

impl StandaloneDocsConfig {
    fn default_include() -> Vec<String> {
        vec!["**/*.md".to_owned(), "**/*.rst".to_owned()]
    }

    fn default_exclude() -> Vec<String> {
        vec![
            // Governance / history files: drift detection doesn't apply.
            "CHANGELOG*".to_owned(),
            "CHANGELOG/**".to_owned(),
            "CONTRIBUTING*".to_owned(),
            "CODE_OF_CONDUCT*".to_owned(),
            "SECURITY*".to_owned(),
            // ADRs: each entry is dated and not edited after merge.
            "**/adr/**".to_owned(),
            // Generated API reference / build artefacts.
            "target/**".to_owned(),
            "dist/**".to_owned(),
            "node_modules/**".to_owned(),
        ]
    }
}

impl Default for StandaloneDocsConfig {
    fn default() -> Self {
        Self {
            include: Self::default_include(),
            exclude: Self::default_exclude(),
            entrypoints: Vec::new(),
        }
    }
}

/// `[features.docs.doc_freshness]` — absolute commit-distance floors
/// for the freshness observer. We measure src-side commits since the
/// last doc-side commit (mtime is forbidden by `scope.md` R2), so the
/// thresholds count source commits, not days. Per-pair distribution
/// percentiles aren't useful here — drift signal is absolute.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct DocFreshnessConfig {
    #[serde(default = "DocFreshnessConfig::default_high_commits")]
    pub high_commits: u32,
    #[serde(default = "DocFreshnessConfig::default_critical_commits")]
    pub critical_commits: u32,
}

impl DocFreshnessConfig {
    pub(crate) const DEFAULT_HIGH_COMMITS: u32 = 5;
    pub(crate) const DEFAULT_CRITICAL_COMMITS: u32 = 20;

    fn default_high_commits() -> u32 {
        Self::DEFAULT_HIGH_COMMITS
    }
    fn default_critical_commits() -> u32 {
        Self::DEFAULT_CRITICAL_COMMITS
    }
}

impl Default for DocFreshnessConfig {
    fn default() -> Self {
        Self {
            high_commits: Self::default_high_commits(),
            critical_commits: Self::default_critical_commits(),
        }
    }
}

/// `[features.docs.todo_density]` — per-doc marker counter behaviour.
/// The observer counts `TODO` / `FIXME` / `XXX` / `TBD` / `[要確認]` /
/// `[要修正]` occurrences in each doc; this block tunes which spans the
/// counter inspects. Marker count thresholds (`MEDIUM_THRESHOLD`,
/// `HIGH_THRESHOLD`) live alongside the observer.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct TodoDensityConfig {
    /// When true (default), markers inside single- or double-backtick
    /// inline-code spans are not counted. The doc is *quoting* the
    /// keyword (e.g. an observer reference describing `TODO` / `FIXME`
    /// markers) rather than flagging an action item, so the count
    /// should ignore them. Flip to `false` when the project
    /// deliberately uses inline-code spans for action items.
    #[serde(default = "TodoDensityConfig::default_ignore_in_inline_code")]
    pub ignore_in_inline_code: bool,
    /// Gitignore-syntax globs naming docs to skip entirely. Useful for
    /// reference pages that document the marker keywords themselves
    /// and would otherwise self-flag every paragraph. Validated at
    /// load via [`Config::validate`].
    #[serde(default)]
    pub allowlist_paths: Vec<String>,
}

impl TodoDensityConfig {
    pub(crate) const DEFAULT_IGNORE_IN_INLINE_CODE: bool = true;

    fn default_ignore_in_inline_code() -> bool {
        Self::DEFAULT_IGNORE_IN_INLINE_CODE
    }
}

impl Default for TodoDensityConfig {
    fn default() -> Self {
        Self {
            ignore_in_inline_code: Self::default_ignore_in_inline_code(),
            allowlist_paths: Vec::new(),
        }
    }
}

/// `[features.test]` — optional test-quality observers. Layer 1 ingests
/// externally-generated lcov coverage (`cargo llvm-cov`, `pytest-cov`,
/// `nyc`, `scoverage`) and surfaces low-coverage hotspots; Layer 2 tags
/// every Finding's [`crate::core::finding::Finding::is_test_file`]
/// against [`Self::test_paths`] so test/non-test severities can be read
/// and filtered separately by skills. HEAL never runs tests itself —
/// flakiness, runtime trends, isolation, etc. are forever out of scope
/// (`scope.md` R5). Defaults to disabled.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct TestConfig {
    /// Master enable switch. While false, every test observer is a no-op
    /// and `is_test_file` stays `false` on every Finding.
    pub enabled: bool,
    /// Gitignore-syntax globs marking which source files are tests. The
    /// matcher is consulted by `Feature::lower` to set
    /// `Finding.is_test_file`; the heuristic in
    /// `crate::observer::shared::file_role::is_test_path` is the
    /// fallback when this list is empty.
    #[serde(default = "TestConfig::default_test_paths")]
    pub test_paths: Vec<String>,
    /// `[features.test.coverage]` — lcov ingestion settings. Coverage is
    /// the only test-quality signal HEAL knows; everything else (skip
    /// rate, flakiness, mutation score) is deferred or out of scope.
    #[serde(default)]
    pub coverage: TestCoverageConfig,
    /// `[features.test.hotspot]` — per-src-file
    /// `commits × uncov_pct` composite. Calibration-driven; the
    /// section holds only `floor_ok` (the literature-anchored
    /// graduation gate) and `top_n` so floor overrides survive
    /// `heal calibrate --force`.
    #[serde(default)]
    pub hotspot: TestHotspotConfig,
}

impl TestConfig {
    fn default_test_paths() -> Vec<String> {
        vec![
            // Rust convention.
            "tests/**".to_owned(),
            "**/*_test.rs".to_owned(),
            // JS / TS convention — both `.test.*` and `.spec.*` ship
            // widely; `__tests__/` is the React / Jest sibling form.
            "**/*.test.ts".to_owned(),
            "**/*.test.tsx".to_owned(),
            "**/*.test.js".to_owned(),
            "**/*.test.jsx".to_owned(),
            "**/*.spec.ts".to_owned(),
            "**/*.spec.tsx".to_owned(),
            "**/*.spec.js".to_owned(),
            "**/*.spec.jsx".to_owned(),
            "**/__tests__/**".to_owned(),
            // Go convention — same-directory `*_test.go` is the only
            // form `go test` recognises.
            "**/*_test.go".to_owned(),
            // Python convention — both pytest patterns ship widely.
            "**/test_*.py".to_owned(),
            "**/*_test.py".to_owned(),
            // Scala / sbt convention — `Test`/`Spec` suffix on the class
            // file name is the ScalaTest / Specs2 idiom.
            "**/*Test.scala".to_owned(),
            "**/*Spec.scala".to_owned(),
        ]
    }
}

impl Default for TestConfig {
    fn default() -> Self {
        Self {
            enabled: false,
            test_paths: Self::default_test_paths(),
            coverage: TestCoverageConfig::default(),
            hotspot: TestHotspotConfig::default(),
        }
    }
}

/// `[features.test.hotspot]` — per-src-file `commits × uncov_pct`
/// composite. The composite itself reads from `ChurnReport` and
/// `CoverageReport`; this config block only carries the calibration
/// `floor_ok` override (so it survives `heal calibrate --force`,
/// per `invariants.md` R9) and the per-metric `top_n` for
/// `heal metrics test_hotspot`.
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct TestHotspotConfig {
    /// Calibration override — `None` defers to
    /// `core::calibration::FLOOR_OK_TEST_HOTSPOT`. Set to a number to
    /// raise / lower the graduation gate (lower = stricter; the floor
    /// blocks decoration even when a file sits in the top decile of
    /// the project's `test_hotspot` distribution).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub floor_ok: Option<f64>,
    /// Per-metric override for `metrics.top_n` — top test-hotspot files.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub top_n: Option<usize>,
}

impl Eq for TestHotspotConfig {}

/// `[features.test.coverage]` — lcov.info ingestion. Generation is
/// outsourced to the user's CI / local toolchain (`cargo llvm-cov`,
/// `pytest --cov`, `nyc`, `scoverage`); HEAL only reads the file. The
/// `lcov_paths` list is tried in order; the first existing file wins.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct TestCoverageConfig {
    /// Sub-feature switch. `enabled = false` keeps the lcov reader idle
    /// even when `[features.test].enabled = true`. Defaults to false so
    /// projects that opt into `is_test_file` tagging don't get a noisy
    /// "lcov not found" warning before they've wired up a reporter.
    pub enabled: bool,
    /// Project-relative paths the reader probes for an lcov.info file.
    /// First existing match wins; missing files are silent. The
    /// defaults cover the common reporter conventions: bare
    /// `lcov.info`, the `nyc` / `pytest-cov` `coverage/` dir, and
    /// `cargo llvm-cov`'s `target/llvm-cov/lcov.info`.
    #[serde(default = "TestCoverageConfig::default_lcov_paths")]
    pub lcov_paths: Vec<String>,
    /// Optional shell command HEAL spawns from `heal hook commit`
    /// (i.e. the post-commit git hook) to keep `lcov.info` fresh after
    /// each commit. The process is detached and its output discarded —
    /// the user's commit flow doesn't wait. Wrap heavy reporters
    /// (`cargo llvm-cov`, `sbt coverageReport`) in this so HEAL never
    /// reads stale coverage on the next `heal status`. `None` keeps
    /// the post-commit nudge as a no-op for coverage.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub post_commit_refresh: Option<String>,
}

impl TestCoverageConfig {
    fn default_lcov_paths() -> Vec<String> {
        vec![
            "lcov.info".to_owned(),
            "coverage/lcov.info".to_owned(),
            "target/llvm-cov/lcov.info".to_owned(),
            "coverage/lcov-report/lcov.info".to_owned(),
        ]
    }
}

impl Default for TestCoverageConfig {
    fn default() -> Self {
        Self {
            enabled: false,
            lcov_paths: Self::default_lcov_paths(),
            post_commit_refresh: None,
        }
    }
}

#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct ProjectConfig {
    /// Natural language for AI-generated explanations (`heal status`
    /// output, future `run-*` proposals). Free-form so users can write
    /// `"Japanese"`, `"日本語"`, `"ja"`, `"français"` — the value is
    /// passed verbatim to the model. `None` keeps the model default.
    #[serde(default)]
    pub response_language: Option<String>,
    /// Declared sub-projects inside a monorepo. Each overlay scopes a
    /// path prefix and (optionally) overrides the auto-detected
    /// `language` for that subtree. Empty (the v0.1+ default) means
    /// the whole repo is one cohort, exactly matching pre-monorepo
    /// behavior. See `[[project.workspaces]]` in `references/config.md`.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub workspaces: Vec<WorkspaceOverlay>,
}

/// One entry under `[[project.workspaces]]`. The path is project-root
/// relative ("packages/web", not "/abs/path/packages/web"); validation
/// happens in [`Config::validate`].
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct WorkspaceOverlay {
    /// Path prefix relative to the project root, slash-separated.
    /// Example: `"packages/web"` or `"services/api"`.
    pub path: String,
    /// Override the auto-detected primary language for this workspace.
    /// Free-form, lowercased on write — same shape as the field
    /// `LocReport::primary` produces. Maps to the TOML key `language`.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub language: Option<String>,
    /// Workspace-local extra excludes layered on top of
    /// `git.exclude_paths` and `metrics.loc.exclude_paths`. Each entry
    /// is a `.gitignore` line **relative to the workspace root**:
    /// `["vendor/"]` under `path = "packages/web"` excludes
    /// `packages/web/**/vendor/`. Leading `/` anchors at the
    /// workspace root (translated to project-root + workspace path),
    /// `!pat` negates a prior exclusion, glob (`*`, `**`, `?`,
    /// `[abc]`) and `#` comments work as in `.gitignore`.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub exclude_paths: Vec<String>,
    /// Per-metric calibration-floor overrides scoped to this
    /// workspace. Apply *after* the global `[metrics.<m>]` overrides,
    /// so workspace settings win when both are present.
    #[serde(default, skip_serializing_if = "WorkspaceMetricsOverlay::is_empty")]
    pub metrics: WorkspaceMetricsOverlay,
}

impl Eq for WorkspaceOverlay {}

/// Per-metric calibration-floor override bag for a single workspace.
/// Mirrors only the floors (data-driven percentile breaks already vary
/// per workspace via `Calibration::workspaces`); other knobs like
/// `min_coupling` or `since_days` would require scan-time machinery
/// and stay deferred.
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct WorkspaceMetricsOverlay {
    #[serde(default, skip_serializing_if = "WorkspaceMetricOverlay::is_empty")]
    pub ccn: WorkspaceMetricOverlay,
    #[serde(default, skip_serializing_if = "WorkspaceMetricOverlay::is_empty")]
    pub cognitive: WorkspaceMetricOverlay,
    #[serde(default, skip_serializing_if = "WorkspaceMetricOverlay::is_empty")]
    pub duplication: WorkspaceMetricOverlay,
    #[serde(default, skip_serializing_if = "WorkspaceMetricOverlay::is_empty")]
    pub change_coupling: WorkspaceMetricOverlay,
    #[serde(default, skip_serializing_if = "WorkspaceMetricOverlay::is_empty")]
    pub lcom: WorkspaceMetricOverlay,
}

impl Eq for WorkspaceMetricsOverlay {}

impl WorkspaceMetricsOverlay {
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.ccn.is_empty()
            && self.cognitive.is_empty()
            && self.duplication.is_empty()
            && self.change_coupling.is_empty()
            && self.lcom.is_empty()
    }
}

/// One per-metric override entry. `floor_critical` raises (or lowers)
/// the absolute Critical threshold; `floor_ok` does the same for the
/// graduation gate. Metrics that don't expose a `floor_ok` (e.g.
/// `change_coupling`) silently ignore that field at apply time.
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct WorkspaceMetricOverlay {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub floor_critical: Option<f64>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub floor_ok: Option<f64>,
}

impl Eq for WorkspaceMetricOverlay {}

impl WorkspaceMetricOverlay {
    #[must_use]
    pub fn is_empty(&self) -> bool {
        self.floor_critical.is_none() && self.floor_ok.is_none()
    }
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct GitConfig {
    #[serde(default = "default_since_days")]
    pub since_days: u32,
    /// Project-wide exclude lines, evaluated as `.gitignore` syntax:
    /// `target/`, `*.log`, `/build`, `**/__snapshots__/`, `!keep.log`,
    /// `# comment` all behave as in a real `.gitignore` file. Every
    /// observer applies these.
    #[serde(default)]
    pub exclude_paths: Vec<String>,
}

impl Default for GitConfig {
    fn default() -> Self {
        Self {
            since_days: default_since_days(),
            exclude_paths: Vec::new(),
        }
    }
}

fn default_since_days() -> u32 {
    90
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct MetricsConfig {
    /// Default `worst_n` width for `heal metrics` rankings. Each metric
    /// below can override this with its own `top_n = N`; absent overrides
    /// fall back to this value.
    #[serde(default = "default_top_n")]
    pub top_n: usize,
    /// Code metrics this project disables. Strings are `Finding.metric`
    /// names (`churn`, `hotspot`, `change_coupling`, `duplication`,
    /// `ccn`, `cognitive`, `lcom`); unknown names surface as a
    /// `ConfigInvalid` schema error at load. `loc` is foundational and
    /// cannot be disabled — every other observer (hotspot, churn
    /// weighting, primary-language detection) depends on it. The list
    /// is the single switch for opt-out; per-metric `[metrics.<m>]`
    /// blocks now hold tunables only, no `enabled = true/false`.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub disabled: Vec<String>,
    #[serde(default)]
    pub loc: LocConfig,
    #[serde(default)]
    pub churn: ChurnConfig,
    #[serde(default)]
    pub hotspot: HotspotConfig,
    #[serde(default)]
    pub change_coupling: ChangeCouplingConfig,
    #[serde(default)]
    pub duplication: DuplicationConfig,
    #[serde(default)]
    pub ccn: CcnConfig,
    #[serde(default)]
    pub cognitive: CognitiveConfig,
    #[serde(default)]
    pub lcom: LcomConfig,
}

impl Eq for MetricsConfig {}

impl Default for MetricsConfig {
    fn default() -> Self {
        // Match serde's "section missing" behavior so programmatic `default()`
        // and `from_toml_str("")` produce the same struct.
        Self {
            top_n: default_top_n(),
            disabled: Vec::new(),
            loc: LocConfig::default(),
            churn: ChurnConfig::default(),
            hotspot: HotspotConfig::default(),
            change_coupling: ChangeCouplingConfig::default(),
            duplication: DuplicationConfig::default(),
            ccn: CcnConfig::default(),
            cognitive: CognitiveConfig::default(),
            lcom: LcomConfig::default(),
        }
    }
}

/// Code metrics that `metrics.disabled` may name. `loc` is excluded
/// on purpose — disabling it would break every observer that depends
/// on language detection, so the validator rejects it explicitly.
pub const DISABLEABLE_METRICS: &[&str] = &[
    "churn",
    "hotspot",
    "change_coupling",
    "duplication",
    "ccn",
    "cognitive",
    "lcom",
];

impl MetricsConfig {
    /// True iff the named metric is **not** in `disabled`. Pass the
    /// `snake_case` `Finding.metric` name (`churn`, `change_coupling`,
    /// `lcom`, ...). Unknown names always read enabled — validation
    /// rejects them at config-load time, so the runtime path stays
    /// branch-free.
    #[must_use]
    pub fn is_enabled(&self, metric: &str) -> bool {
        !self.disabled.iter().any(|m| m == metric)
    }

    /// Resolve the effective `top_n` for a given metric: per-metric override
    /// wins, otherwise fall back to the global `metrics.top_n`.
    #[must_use]
    pub fn top_n_loc(&self) -> usize {
        self.loc.top_n.unwrap_or(self.top_n)
    }
    #[must_use]
    pub fn top_n_complexity(&self) -> usize {
        self.ccn.top_n.unwrap_or(self.top_n)
    }
    #[must_use]
    pub fn top_n_churn(&self) -> usize {
        self.churn.top_n.unwrap_or(self.top_n)
    }
    #[must_use]
    pub fn top_n_change_coupling(&self) -> usize {
        self.change_coupling.top_n.unwrap_or(self.top_n)
    }
    #[must_use]
    pub fn top_n_duplication(&self) -> usize {
        self.duplication.top_n.unwrap_or(self.top_n)
    }
    #[must_use]
    pub fn top_n_hotspot(&self) -> usize {
        self.hotspot.top_n.unwrap_or(self.top_n)
    }
    #[must_use]
    pub fn top_n_lcom(&self) -> usize {
        self.lcom.top_n.unwrap_or(self.top_n)
    }
}

/// LOC has no enable/disable toggle: it is a foundational metric that other
/// observers (hotspot, churn weighting, primary-language detection) depend on.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct LocConfig {
    #[serde(default = "default_true")]
    pub inherit_git_excludes: bool,
    /// Additional `.gitignore`-style exclude lines layered on top of
    /// `git.exclude_paths`. Same syntax (glob, anchored, negation,
    /// directory-only).
    #[serde(default)]
    pub exclude_paths: Vec<String>,
    /// Per-metric override for `metrics.top_n` — only the top languages list.
    #[serde(default)]
    pub top_n: Option<usize>,
}

impl Default for LocConfig {
    fn default() -> Self {
        Self {
            inherit_git_excludes: true,
            exclude_paths: Vec::new(),
            top_n: None,
        }
    }
}

fn default_true() -> bool {
    true
}

fn default_top_n() -> usize {
    5
}

#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct CognitiveConfig {
    /// Calibration override — see `core::calibration::FLOOR_COGNITIVE`
    /// for the v0.2 default (50, `SonarQube` Critical baseline).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub floor_critical: Option<f64>,
    /// Graduation gate override — see `core::calibration::FLOOR_OK_COGNITIVE`
    /// (8, half of `Sonar`'s "review" threshold). Values strictly below this
    /// classify as Ok regardless of percentile.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub floor_ok: Option<f64>,
}

impl Eq for CognitiveConfig {}

#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct ChurnConfig {
    /// Per-metric override for `metrics.top_n` — most-churned files list.
    #[serde(default)]
    pub top_n: Option<usize>,
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct HotspotConfig {
    #[serde(default = "default_weight")]
    pub weight_churn: f64,
    #[serde(default = "default_weight")]
    pub weight_complexity: f64,
    /// Per-metric override for `metrics.top_n` — top hotspot files.
    #[serde(default)]
    pub top_n: Option<usize>,
    /// Absolute graduation floor on the composite `commits × ccn_sum`
    /// score. Scores strictly below this never flag as hotspots even
    /// when they sit in the top 10% of a uniformly-cold codebase.
    /// `None` defers to the literature-anchored default
    /// (`FLOOR_OK_HOTSPOT = 22 = 2 × FLOOR_OK_CCN`).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub floor_ok: Option<f64>,
}

impl Eq for HotspotConfig {}

impl Default for HotspotConfig {
    fn default() -> Self {
        Self {
            weight_churn: default_weight(),
            weight_complexity: default_weight(),
            top_n: None,
            floor_ok: None,
        }
    }
}

fn default_weight() -> f64 {
    1.0
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct ChangeCouplingConfig {
    #[serde(default = "default_min_coupling")]
    pub min_coupling: u32,
    /// Lift threshold for filtering coincidental pairs. Lift =
    /// `P(A∩B) / (P(A) × P(B))` — a value of 1.0 means the pair
    /// co-occurs at chance, 2.0 means twice as often as chance. Pairs
    /// below this drop before ranking; default 2.0 keeps strong
    /// associations only.
    #[serde(default = "default_min_lift")]
    pub min_lift: f64,
    /// Threshold both `P(B|A)` and `P(A|B)` must meet for a pair to
    /// classify as `Symmetric` rather than `OneWay`. 0.5 (default) =
    /// each file's edits coincide with the partner at least half the
    /// time. Lower it to surface looser symmetry; raise it to require
    /// near-lockstep changes.
    #[serde(default = "default_symmetric_threshold")]
    pub symmetric_threshold: f64,
    /// Per-metric override for `metrics.top_n` — most-coupled pairs list.
    #[serde(default)]
    pub top_n: Option<usize>,
    /// Calibration override. `min_coupling` already serves as the
    /// scan-time floor, so the absolute Critical floor here is rare in
    /// practice — leave `None` to defer entirely to percentile breaks.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub floor_critical: Option<f64>,
    /// What to do with pairs whose two files belong to *different*
    /// declared workspaces. `Surface` (default) retags such pairs as
    /// `change_coupling.cross_workspace` so they collect in their own
    /// Advisory bucket — surfacing module-boundary leaks without
    /// pushing them into the drain queue. `Hide` drops them entirely;
    /// useful for monorepos where the cross-workspace coupling is
    /// expected (shared schema, intentionally co-evolving APIs).
    /// Ignored when `[[project.workspaces]]` is empty.
    #[serde(default)]
    pub cross_workspace: CrossWorkspacePolicy,
}

#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
pub enum CrossWorkspacePolicy {
    #[default]
    Surface,
    Hide,
}

impl Eq for ChangeCouplingConfig {}

impl Default for ChangeCouplingConfig {
    fn default() -> Self {
        Self {
            min_coupling: default_min_coupling(),
            min_lift: default_min_lift(),
            symmetric_threshold: default_symmetric_threshold(),
            top_n: None,
            floor_critical: None,
            cross_workspace: CrossWorkspacePolicy::default(),
        }
    }
}

fn default_min_coupling() -> u32 {
    3
}

fn default_min_lift() -> f64 {
    2.0
}

fn default_symmetric_threshold() -> f64 {
    0.5
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct LcomConfig {
    /// Extraction backend. v0.2 ships only `tree-sitter-approx`; a
    /// typed `lsp` variant lands in v0.5+. Typo-resistant by virtue
    /// of being an enum.
    #[serde(default)]
    pub backend: LcomBackend,
    /// Classes whose `cluster_count` is below this floor are not
    /// surfaced as Findings. `2` is the natural baseline — `1` means
    /// the class is cohesive and `0` means it has no methods.
    #[serde(default = "default_min_cluster_count")]
    pub min_cluster_count: u32,
    /// Per-metric override for `metrics.top_n` — most-split classes list.
    #[serde(default)]
    pub top_n: Option<usize>,
    /// Calibration override. `min_cluster_count` already serves as the
    /// scan-time floor; absolute Critical floor here is rare.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub floor_critical: Option<f64>,
}

#[derive(Debug, Clone, Copy, Default, Serialize, Deserialize, PartialEq, Eq)]
#[serde(rename_all = "kebab-case")]
pub enum LcomBackend {
    #[default]
    TreeSitterApprox,
    /// Reserved for the v0.5+ LSP-backed implementation; not yet
    /// usable from a `LcomObserver` scan, but the variant is wired so
    /// configs that opt in early don't fail to parse.
    Lsp,
}

impl Eq for LcomConfig {}

impl Default for LcomConfig {
    fn default() -> Self {
        Self {
            backend: LcomBackend::default(),
            min_cluster_count: default_min_cluster_count(),
            top_n: None,
            floor_critical: None,
        }
    }
}

fn default_min_cluster_count() -> u32 {
    2
}

#[derive(Debug, Clone, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct DuplicationConfig {
    #[serde(default = "default_min_tokens")]
    pub min_tokens: u32,
    /// Window size in tokens applied to **Markdown / RST docs** when
    /// `[features.docs]` is enabled. Prose carries more filler per
    /// concept than code, so the floor is intentionally larger than
    /// `min_tokens`. Ignored when `features.docs.enabled = false`.
    #[serde(default = "default_docs_min_tokens")]
    pub docs_min_tokens: u32,
    /// Per-metric override for `metrics.top_n` — largest duplicate blocks.
    #[serde(default)]
    pub top_n: Option<usize>,
    /// Calibration override (per-file duplicate %). v0.2 default is
    /// `core::calibration::FLOOR_DUPLICATION_PCT` (30%).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub floor_critical: Option<f64>,
}

impl Eq for DuplicationConfig {}

impl Default for DuplicationConfig {
    fn default() -> Self {
        Self {
            min_tokens: default_min_tokens(),
            docs_min_tokens: default_docs_min_tokens(),
            top_n: None,
            floor_critical: None,
        }
    }
}

fn default_min_tokens() -> u32 {
    50
}

fn default_docs_min_tokens() -> u32 {
    100
}

#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct CcnConfig {
    /// Per-metric override for `metrics.top_n` — covers both CCN and
    /// Cognitive listings since they share the "complexity:" section in
    /// `heal metrics`.
    #[serde(default)]
    pub top_n: Option<usize>,
    /// Calibration override — see `core::calibration::FLOOR_CCN` for the
    /// v0.2 default (25, `McCabe`'s "untestable" threshold).
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub floor_critical: Option<f64>,
    /// Graduation gate override — see `core::calibration::FLOOR_OK_CCN`
    /// (11, `McCabe`'s "simple, low risk" boundary). Values strictly below
    /// this classify as Ok regardless of percentile.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub floor_ok: Option<f64>,
}

impl Eq for CcnConfig {}

/// Top-level `[policy]` block. Currently holds the `drain` queue
/// policy. The autonomous-action machinery (`heal run`) is a v0.4+
/// roadmap item; its config schema lives next to the implementation
/// when it lands rather than as a parse-only placeholder here.
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq)]
#[serde(deny_unknown_fields)]
pub struct PolicyConfig {
    #[serde(default)]
    pub drain: PolicyDrainConfig,
}

/// `[policy.drain]` — which `(severity, hotspot)` combinations the
/// `/heal-code-patch` skill must drain (`must`, T0) vs may drain when
/// bandwidth allows (`should`, T1). Anything not matched falls into
/// the Advisory tier (rendered separately, never auto-drained).
///
/// Per-metric overrides under `[policy.drain.metrics.<name>]` let
/// teams tune the drain gate by metric (e.g. stricter `must` for
/// `ccn` because it's a proxy; looser for `duplication` because it's
/// Goodhart-safe).
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct PolicyDrainConfig {
    /// T0 — drain to zero. Default: `["critical:hotspot"]`.
    #[serde(default = "default_drain_must")]
    pub must: Vec<DrainSpec>,
    /// T1 — drain when convenient. Default:
    /// `["critical", "high:hotspot"]`.
    #[serde(default = "default_drain_should")]
    pub should: Vec<DrainSpec>,
    /// Per-metric overrides keyed by metric name (`ccn`, `cognitive`,
    /// `duplication`, `change_coupling`, `lcom`, `hotspot`). Each
    /// override may set `must` and / or `should`; missing fields fall
    /// back to the global lists above.
    #[serde(default, skip_serializing_if = "BTreeMap::is_empty")]
    pub metrics: BTreeMap<String, PolicyDrainMetricOverride>,
}

/// One per-metric override under `[policy.drain.metrics.<name>]`.
/// Either field may be `None` to inherit the corresponding global
/// list.
#[derive(Debug, Clone, Default, Serialize, Deserialize, PartialEq, Eq)]
#[serde(deny_unknown_fields)]
pub struct PolicyDrainMetricOverride {
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub must: Option<Vec<DrainSpec>>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub should: Option<Vec<DrainSpec>>,
}

impl Default for PolicyDrainConfig {
    fn default() -> Self {
        Self {
            must: default_drain_must(),
            should: default_drain_should(),
            metrics: BTreeMap::new(),
        }
    }
}

fn default_drain_must() -> Vec<DrainSpec> {
    vec![DrainSpec {
        severity: crate::core::severity::Severity::Critical,
        hotspot: HotspotMatch::Required,
    }]
}

fn default_drain_should() -> Vec<DrainSpec> {
    vec![
        DrainSpec {
            severity: crate::core::severity::Severity::Critical,
            hotspot: HotspotMatch::Any,
        },
        DrainSpec {
            severity: crate::core::severity::Severity::High,
            hotspot: HotspotMatch::Required,
        },
    ]
}

/// One entry in a `must` / `should` list. The DSL on disk is
/// `<severity>` (any hotspot) or `<severity>:hotspot` (hotspot=true
/// required). Both halves accept lowercase severity names
/// (`critical`, `high`, `medium`, `ok`).
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DrainSpec {
    pub severity: crate::core::severity::Severity,
    pub hotspot: HotspotMatch,
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum HotspotMatch {
    /// Match the spec regardless of the finding's hotspot flag.
    Any,
    /// Match only when the finding has `hotspot = true`.
    Required,
}

impl DrainSpec {
    /// True iff the finding is in scope for this spec (severity and
    /// hotspot constraints both satisfied).
    #[must_use]
    pub fn matches(&self, finding: &crate::core::finding::Finding) -> bool {
        self.matches_attrs(finding.severity, finding.hotspot)
    }

    /// Attribute-only variant for callers that don't have a full
    /// `Finding` in hand (e.g. `DiffEntry`, where only the
    /// `(severity, hotspot)` pair survives the diff projection).
    #[must_use]
    pub fn matches_attrs(&self, severity: crate::core::severity::Severity, hotspot: bool) -> bool {
        if severity != self.severity {
            return false;
        }
        match self.hotspot {
            HotspotMatch::Any => true,
            HotspotMatch::Required => hotspot,
        }
    }
}

/// Which drain bucket a finding belongs to under a given drain policy.
/// `Must` is the "drain to zero" target; `Should` is the bandwidth-
/// permitting tier; `Advisory` is everything else above `Severity::Ok`.
/// Findings classified as `Severity::Ok` are not surfaced as drain
/// candidates and never reach `Advisory` — see `tier_for`.
#[derive(Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord)]
pub enum DrainTier {
    Must,
    Should,
    Advisory,
}

impl PolicyDrainConfig {
    /// Classify a finding into its drain tier. Returns `None` for
    /// `Severity::Ok` findings — those are excluded from drain queues
    /// entirely (the renderer surfaces them via the separate Ok summary).
    /// Per-metric overrides at `[policy.drain.metrics.<name>]` take
    /// precedence over the global `must` / `should` lists; missing
    /// overrides inherit the global value.
    #[must_use]
    pub fn tier_for(&self, finding: &crate::core::finding::Finding) -> Option<DrainTier> {
        self.tier_for_attrs(&finding.metric, finding.severity, finding.hotspot)
    }

    /// Attribute-only variant: same classification as `tier_for` but
    /// driven by the `(metric, severity, hotspot)` triple. Used by the
    /// diff command, where `DiffEntry` carries the same triple but
    /// not a full `Finding`.
    #[must_use]
    pub fn tier_for_attrs(
        &self,
        metric: &str,
        severity: crate::core::severity::Severity,
        hotspot: bool,
    ) -> Option<DrainTier> {
        if severity == crate::core::severity::Severity::Ok {
            return None;
        }
        // Cross-workspace coupling is parked in Advisory by default
        // regardless of severity — the right fix is usually an
        // architectural conversation, not a single-commit drain. Users
        // can opt back in with an explicit
        // `[policy.drain.metrics."change_coupling.cross_workspace"]`.
        if metric == crate::core::finding::Finding::METRIC_CHANGE_COUPLING_CROSS_WORKSPACE
            && !self.metrics.contains_key(metric)
        {
            return Some(DrainTier::Advisory);
        }
        let (must, should) = self.specs_for(metric);
        if must.iter().any(|s| s.matches_attrs(severity, hotspot)) {
            return Some(DrainTier::Must);
        }
        if should.iter().any(|s| s.matches_attrs(severity, hotspot)) {
            return Some(DrainTier::Should);
        }
        Some(DrainTier::Advisory)
    }

    /// Resolve the effective `(must, should)` spec lists for a metric.
    /// Looks up the per-metric override first; metrics without an
    /// override see the global lists. Sub-metrics (`change_coupling.symmetric`)
    /// fall back to their parent (`change_coupling`) before going global.
    fn specs_for(&self, metric: &str) -> (&[DrainSpec], &[DrainSpec]) {
        let mut must: &[DrainSpec] = &self.must;
        let mut should: &[DrainSpec] = &self.should;
        let override_chain =
            std::iter::once(metric).chain(metric.split_once('.').map(|(parent, _)| parent));
        for key in override_chain {
            if let Some(ov) = self.metrics.get(key) {
                if let Some(m) = ov.must.as_ref() {
                    must = m;
                }
                if let Some(s) = ov.should.as_ref() {
                    should = s;
                }
                if ov.must.is_some() && ov.should.is_some() {
                    break;
                }
            }
        }
        (must, should)
    }
}

impl std::str::FromStr for DrainSpec {
    type Err = String;

    fn from_str(s: &str) -> std::result::Result<Self, Self::Err> {
        let mut parts = s.split(':');
        let severity_token = parts
            .next()
            .ok_or_else(|| format!("drain spec '{s}' is empty"))?;
        let severity = severity_token
            .parse::<crate::core::severity::Severity>()
            .map_err(|_| {
                format!(
                    "drain spec '{s}' has unknown severity '{severity_token}' (expected one of \
                     critical / high / medium / ok)"
                )
            })?;
        let hotspot = match parts.next() {
            None => HotspotMatch::Any,
            Some("hotspot") => HotspotMatch::Required,
            Some(other) => {
                return Err(format!(
                    "drain spec '{s}' has unknown flag '{other}' (only 'hotspot' is supported)"
                ));
            }
        };
        if parts.next().is_some() {
            return Err(format!(
                "drain spec '{s}' has too many ':' segments (expected at most one)"
            ));
        }
        Ok(Self { severity, hotspot })
    }
}

impl serde::Serialize for DrainSpec {
    fn serialize<S: serde::Serializer>(&self, ser: S) -> std::result::Result<S::Ok, S::Error> {
        let severity = self.severity.as_str();
        let body = match self.hotspot {
            HotspotMatch::Any => severity.to_owned(),
            HotspotMatch::Required => format!("{severity}:hotspot"),
        };
        ser.serialize_str(&body)
    }
}

impl<'de> serde::Deserialize<'de> for DrainSpec {
    fn deserialize<D: serde::Deserializer<'de>>(de: D) -> std::result::Result<Self, D::Error> {
        let s = String::deserialize(de)?;
        s.parse::<Self>().map_err(serde::de::Error::custom)
    }
}

impl Config {
    /// Read and validate a config from disk.
    pub fn load(path: &Path) -> Result<Self> {
        let raw = std::fs::read_to_string(path).map_err(|e| {
            if e.kind() == std::io::ErrorKind::NotFound {
                Error::ConfigMissing(path.to_path_buf())
            } else {
                Error::Io {
                    path: path.to_path_buf(),
                    source: e,
                }
            }
        })?;
        let cfg = Self::from_toml_str(&raw).map_err(|source| Error::ConfigParse {
            path: path.to_path_buf(),
            source,
        })?;
        cfg.validate(path)?;
        Ok(cfg)
    }

    /// Parse a TOML body. Useful for tests and for round-trip checks.
    /// Does **not** run [`Self::validate`] — call it explicitly when
    /// the values come from outside a trusted producer.
    #[must_use = "ignoring the parse result will silently swallow schema errors"]
    pub fn from_toml_str(s: &str) -> std::result::Result<Self, toml::de::Error> {
        toml::from_str(s)
    }

    /// Cross-field invariants. Currently checks `[[project.workspaces]]`
    /// paths (non-empty, slash-separated, repo-root-relative, no
    /// duplicates, no nesting), every `exclude_paths` entry as
    /// `.gitignore` syntax, and that every name in `metrics.disabled`
    /// is a known disable-able metric (`loc` is foundational and is
    /// rejected here).
    pub fn validate(&self, path: &Path) -> Result<()> {
        validate_workspaces(&self.project.workspaces).map_err(|message| Error::ConfigInvalid {
            path: path.to_path_buf(),
            message: message.clone(),
        })?;
        validate_gitignore_lines(&self.exclude_lines()).map_err(|message| {
            Error::ConfigInvalid {
                path: path.to_path_buf(),
                message,
            }
        })?;
        let standalone = &self.features.docs.standalone;
        validate_gitignore_lines(&standalone.include)
            .and_then(|()| validate_gitignore_lines(&standalone.exclude))
            .and_then(|()| validate_gitignore_lines(&standalone.entrypoints))
            .and_then(|()| {
                validate_gitignore_lines(&self.features.docs.todo_density.allowlist_paths)
            })
            .map_err(|message| Error::ConfigInvalid {
                path: path.to_path_buf(),
                message,
            })?;
        validate_disabled_metrics(&self.metrics.disabled).map_err(|message| {
            Error::ConfigInvalid {
                path: path.to_path_buf(),
                message,
            }
        })?;
        Ok(())
    }

    /// Serialize back to TOML, preserving every field — including
    /// values that match the serde default. Used by `heal init
    /// --explicit` and by tests that want a full round-trip target;
    /// the everyday code path is [`Self::to_minimal_toml`], which
    /// strips defaults so the emitted file shows only what the team
    /// actually customized.
    #[must_use = "the serialized string is the only return value"]
    pub fn to_explicit_toml(&self) -> std::result::Result<String, toml::ser::Error> {
        toml::to_string_pretty(self)
    }

    /// Serialize to TOML with every field that matches the serde
    /// default removed. The `heal init` default flow writes this form
    /// so a fresh `.heal/config.toml` highlights the (currently empty)
    /// set of customizations rather than restating the defaults the
    /// loader would have applied anyway. Round-trips with
    /// [`Self::from_toml_str`] because missing fields fall back to
    /// `Default` on read.
    #[must_use = "the serialized string is the only return value"]
    pub fn to_minimal_toml(&self) -> std::result::Result<String, toml::ser::Error> {
        let mut actual = toml::Value::try_from(self)?;
        let default = toml::Value::try_from(Self::default())?;
        prune_against_default(&mut actual, &default);
        toml::to_string_pretty(&actual)
    }

    /// Persist the config atomically (temp file + rename) in minimal
    /// form — only fields that diverge from the serde default land
    /// on disk. Use [`Self::save_explicit`] when the caller wants
    /// every field surfaced (e.g. `heal init --explicit`).
    pub fn save(&self, path: &Path) -> Result<()> {
        let body = self
            .to_minimal_toml()
            .expect("serialization is infallible for owned data");
        atomic_write(path, with_config_header(&body).as_bytes())
    }

    /// Persist every field — defaults included — atomically. Drives
    /// `heal init --explicit` so a freshly-initialized project can
    /// show every knob `heal-setup` might want to tune.
    pub fn save_explicit(&self, path: &Path) -> Result<()> {
        let body = self
            .to_explicit_toml()
            .expect("serialization is infallible for owned data");
        atomic_write(path, with_config_header(&body).as_bytes())
    }

    /// Gitignore lines every observer should honor, in source-order
    /// precedence: `git.exclude_paths` (when
    /// `metrics.loc.inherit_git_excludes` is true) followed by
    /// `metrics.loc.exclude_paths`, then each workspace's
    /// `[[project.workspaces]].exclude_paths` translated to project-
    /// root-relative patterns. Each entry is a single `.gitignore`
    /// line — see `ExcludeMatcher` for the syntax.
    ///
    /// Workspace pattern translation:
    /// - `vendor/` under `pkg/web` → `pkg/web/**/vendor/` (match the
    ///   directory anywhere inside the workspace).
    /// - `/build` (anchored) under `pkg/web` → `/pkg/web/build` (anchor
    ///   propagates to the project root + workspace path).
    /// - `!keep.log` under `pkg/web` → `!pkg/web/**/keep.log` (negation
    ///   re-attaches after body translation).
    #[must_use]
    pub fn exclude_lines(&self) -> Vec<String> {
        let mut lines: Vec<String> = if self.metrics.loc.inherit_git_excludes {
            self.git.exclude_paths.clone()
        } else {
            Vec::new()
        };
        lines.extend(self.metrics.loc.exclude_paths.iter().cloned());
        for ws in &self.project.workspaces {
            let prefix = ws.path.trim_end_matches('/');
            for ex in &ws.exclude_paths {
                lines.push(translate_workspace_pattern(prefix, ex));
            }
        }
        lines
    }
}

/// Verify every name in `metrics.disabled` is a known disable-able
/// code metric. `loc` is foundational and gets a dedicated error
/// message because users will reach for it; everything else falls
/// back to "unknown metric — pick one of …". Returning `Result<(),
/// String>` keeps the caller (`Config::validate`) free to attach
/// the source path it has handy.
fn validate_disabled_metrics(disabled: &[String]) -> std::result::Result<(), String> {
    for name in disabled {
        if name == "loc" {
            return Err(
                "metrics.disabled cannot contain `loc` — LOC is a foundational \
                metric required by hotspot, churn weighting, and primary-language \
                detection"
                    .to_owned(),
            );
        }
        if !DISABLEABLE_METRICS.contains(&name.as_str()) {
            return Err(format!(
                "metrics.disabled contains unknown metric `{name}` — \
                expected one of: {}",
                DISABLEABLE_METRICS.join(", "),
            ));
        }
    }
    Ok(())
}

/// Verify each line parses as `.gitignore` syntax. Builds a throwaway
/// matcher against an arbitrary root since we only care about parser
/// errors, not match results — `Path::new("/")` works on every
/// platform we support. Returns the first malformed line so the
/// caller can surface a precise schema error at config-load time.
fn validate_gitignore_lines(lines: &[String]) -> std::result::Result<(), String> {
    if lines.is_empty() {
        return Ok(());
    }
    let mut builder = ignore::gitignore::GitignoreBuilder::new(Path::new("/"));
    for line in lines {
        if let Err(e) = builder.add_line(None, line) {
            return Err(format!("invalid gitignore pattern `{line}`: {e}"));
        }
    }
    builder
        .build()
        .map(|_| ())
        .map_err(|e| format!("gitignore matcher build failed: {e}"))
}

/// Rewrite a workspace-relative `.gitignore` line so it works as a
/// project-root-relative pattern. `!`-negation is preserved by stripping
/// it before translation and re-attaching it after; comments and empty
/// lines pass through unchanged so users can keep them in workspace
/// `exclude_paths` arrays for clarity.
#[must_use]
pub(crate) fn translate_workspace_pattern(workspace_path: &str, line: &str) -> String {
    let trimmed = line.trim_start();
    if trimmed.is_empty() || trimmed.starts_with('#') {
        return line.to_owned();
    }
    let (negated, body) = trimmed
        .strip_prefix('!')
        .map_or((false, trimmed), |rest| (true, rest));
    let translated = if let Some(anchored) = body.strip_prefix('/') {
        // `/foo` under `pkg/web` → `/pkg/web/foo`. Anchor propagates
        // from "workspace root" to "project root + workspace path".
        format!("/{workspace_path}/{anchored}")
    } else {
        // Unanchored → match anywhere inside the workspace.
        format!("{workspace_path}/**/{body}")
    };
    if negated {
        format!("!{translated}")
    } else {
        translated
    }
}

/// Convenience: load from `.heal/config.toml` under a project root.
pub fn load_from_project(project_root: &Path) -> Result<Config> {
    Config::load(&crate::core::paths::HealPaths::new(project_root).config())
}

/// Reject malformed `[[project.workspaces]]` entries before they reach
/// the rest of the system. Errors are returned as a single string so
/// the caller can wrap with the file `path` for context.
fn validate_workspaces(workspaces: &[WorkspaceOverlay]) -> std::result::Result<(), String> {
    let mut normalized: Vec<String> = Vec::with_capacity(workspaces.len());
    for w in workspaces {
        let p = w.path.trim();
        if p.is_empty() {
            return Err("[[project.workspaces]] entry has empty `path`".into());
        }
        if p.starts_with('/') {
            return Err(format!(
                "[[project.workspaces]] path `{p}` must be repo-root relative (no leading `/`)"
            ));
        }
        if p.split('/').any(|seg| seg == "..") {
            return Err(format!(
                "[[project.workspaces]] path `{p}` must not contain `..`"
            ));
        }
        for ex in &w.exclude_paths {
            let e = ex.trim();
            // Comments and empty lines are valid gitignore content;
            // pass them through. Leading `!` is negation — strip it
            // before semantic checks so the body decides.
            let body = e.strip_prefix('!').unwrap_or(e);
            if body.is_empty() || body.starts_with('#') {
                continue;
            }
            // Leading `/` is gitignore-significant ("anchor to
            // workspace root"); the translator preserves it. Only
            // reject `..` since the workspace-prefix translation
            // can't represent escaping the workspace cleanly.
            if body.split('/').any(|seg| seg == "..") {
                return Err(format!(
                    "[[project.workspaces]] `{p}` exclude `{e}` must not contain `..`"
                ));
            }
        }
        let canonical = p.trim_end_matches('/').to_string();
        normalized.push(canonical);
    }
    for (i, a) in normalized.iter().enumerate() {
        for b in normalized.iter().skip(i + 1) {
            if a == b {
                return Err(format!(
                    "[[project.workspaces]] declares `{a}` more than once"
                ));
            }
            let pa = Path::new(a);
            let pb = Path::new(b);
            if path_has_prefix(pb, pa, true) || path_has_prefix(pa, pb, true) {
                return Err(format!(
                    "[[project.workspaces]] `{a}` and `{b}` nest; one workspace cannot live inside another"
                ));
            }
        }
    }
    Ok(())
}

/// Header prepended to every `.heal/config.toml` heal writes. Two
/// short lines: identify the file (so an empty body isn't a mystery)
/// and point at the `/heal-setup` skill that knows how to fill it in.
const CONFIG_HEADER: &str = "\
# .heal/config.toml — heal's per-project config. Omitted keys fall back to defaults; run `heal init --explicit` to write the full default body.
# Run `claude /heal-setup` to calibrate the codebase and tune thresholds.
";

/// Prepend [`CONFIG_HEADER`] to `body`, separating with a blank line
/// when the body has its own content. Keeps the empty-default case
/// header-only (no trailing blank line that round-trip parsing would
/// have to tolerate).
fn with_config_header(body: &str) -> String {
    let trimmed = body.trim_start_matches('\n');
    if trimmed.is_empty() {
        CONFIG_HEADER.to_owned()
    } else {
        format!("{CONFIG_HEADER}\n{trimmed}")
    }
}

/// Walk an `actual` config TOML tree alongside the `default` tree
/// (both produced by serializing the matching `Config` value) and
/// remove every key in `actual` whose value matches `default`. Empty
/// tables that result from the prune are removed as well, so a
/// fresh `Config::default()` round-trips to a near-empty TOML body.
///
/// Keys present in `actual` but not in `default` (e.g. user-declared
/// `[[project.workspaces]]`, hand-written `exclude_paths` entries)
/// are kept untouched — the function never strips customization.
fn prune_against_default(actual: &mut toml::Value, default: &toml::Value) {
    let (Some(actual_table), Some(default_table)) = (actual.as_table_mut(), default.as_table())
    else {
        return;
    };
    let keys: Vec<String> = actual_table.keys().cloned().collect();
    for key in keys {
        let Some(default_val) = default_table.get(&key) else {
            continue;
        };
        let actual_is_table = actual_table.get(&key).is_some_and(toml::Value::is_table);
        let default_is_table = default_val.is_table();
        if actual_is_table && default_is_table {
            if let Some(actual_val) = actual_table.get_mut(&key) {
                prune_against_default(actual_val, default_val);
                if actual_val.as_table().is_some_and(toml::Table::is_empty) {
                    actual_table.remove(&key);
                }
            }
        } else if actual_table.get(&key) == Some(default_val) {
            actual_table.remove(&key);
        }
    }
}

/// True iff `prefix` is a path-prefix of `path` (segment-wise via
/// `Path::strip_prefix`, so `pkg/web` does **not** match
/// `pkg/webapp/foo.ts`). `strict = true` additionally rejects the
/// equal case (`prefix == path`); used by [`validate_workspaces`] to
/// detect nesting between two workspace declarations. `strict = false`
/// allows equality so [`assign_workspace`] also matches a file path
/// that *is* the workspace root.
fn path_has_prefix(path: &Path, prefix: &Path, strict: bool) -> bool {
    if path.strip_prefix(prefix).is_err() {
        return false;
    }
    !(strict && path == prefix)
}

/// Resolve a finding's file path to the workspace it belongs to (if
/// any). Longest-prefix match: with workspaces `["pkg", "pkg/web"]` a
/// file at `pkg/web/foo.ts` resolves to `"pkg/web"`. Returns `None`
/// when the file lives outside every declared workspace, or when the
/// list is empty (the v0.1+ default).
///
/// `file` is interpreted relative to the project root (which is how
/// observers store paths in `Location.file`). Comparisons are
/// segment-wise so `pkg/web` does not match `pkg/webapp`.
#[must_use]
pub fn assign_workspace<'a>(file: &Path, workspaces: &'a [WorkspaceOverlay]) -> Option<&'a str> {
    let mut best: Option<&str> = None;
    for w in workspaces {
        let candidate = w.path.trim_end_matches('/');
        if path_has_prefix(file, Path::new(candidate), false)
            && best.is_none_or(|b: &str| candidate.len() > b.len())
        {
            best = Some(candidate);
        }
    }
    best
}