heal-cli 0.4.0

//! Cross-observer `Finding` abstraction — promoted to `core` as the
//! prerequisite for v0.2 (Calibration, `heal status` cache,
//! `/heal-code-patch`).
//!
//! Every observer's report can be lowered into `Vec<Finding>` via the
//! [`IntoFindings`] trait. The lowering is deterministic and pure: it
//! does not consult Calibration, it does not classify severity, and it
//! does not flag hotspots. Those layers attach **on top** of a Finding
//! list (the `Feature::lower` pass) — until classification runs, every
//! emitted finding carries `severity = Severity::Ok` and `hotspot =
//! false`.
//!
//! `Finding::id` is **decision-stable**: identical input (metric +
//! canonical location + an observer-supplied content seed) hashes to
//! the same string across processes, toolchains, and commits. The
//! cache layer relies on this so a re-detected finding ties back to
//! its prior occurrence and `fixed.json` reconciliation works.

use std::path::PathBuf;

use serde::{Deserialize, Serialize};

use crate::core::hash::{fnv1a_64_chunked, fnv1a_hex};
pub use crate::core::severity::Severity;

/// A single point in the codebase a finding refers to. `line` and
/// `symbol` are optional because not every metric has them — hotspot
/// is file-level, duplication knows ranges but no symbol, complexity
/// has both.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Location {
    pub file: PathBuf,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub line: Option<u32>,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub symbol: Option<String>,
}

impl Location {
    #[must_use]
    pub fn file(file: PathBuf) -> Self {
        Self {
            file,
            line: None,
            symbol: None,
        }
    }
}

/// One actionable signal produced by an observer. Multi-site findings
/// (duplication blocks, coupling pairs) carry the canonical
/// representative in `location` and the rest in `locations`; the id
/// is derived from `location` + a metric-specific content seed so
/// alternative orderings of the same set hash identically.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct Finding {
    pub id: String,
    pub metric: String,
    #[serde(default)]
    pub severity: Severity,
    #[serde(default)]
    pub hotspot: bool,
    /// Workspace path (project-root relative) when the finding's
    /// `location.file` lives under a declared `[[project.workspaces]]`
    /// entry. `None` for files outside every declared workspace, or
    /// when no workspaces are declared. Tagged post-classify by
    /// [`crate::core::config::assign_workspace`]; not part of the id
    /// hash, so reclassifying a workspace boundary doesn't churn the
    /// fix-tracking history.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub workspace: Option<String>,
    pub location: Location,
    /// Sites beyond the canonical `location`. Populated for duplication
    /// blocks (other duplicates) and coupling pairs (the partner file).
    /// Skipped from JSON when empty so single-site findings stay terse.
    #[serde(default, skip_serializing_if = "Vec::is_empty")]
    pub locations: Vec<Location>,
    pub summary: String,
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub fix_hint: Option<String>,
    /// Decorated at render time by
    /// [`crate::core::accepted::decorate_findings`] when this finding's
    /// id is in `.heal/findings/accepted.json`. Renderers (status /
    /// diff / hook nudge) drop accepted findings from the drain queue
    /// and the Population counts; skills filter the drain queue on
    /// this flag. Persisted as `false` (the default) in `latest.json`
    /// since the cache is per-commit and acceptance is decorated per
    /// render.
    #[serde(default, skip_serializing_if = "is_false")]
    pub accepted: bool,
    /// Tagged post-classify by `Feature::lower` when `[features.test]`
    /// is enabled and `location.file` matches `[features.test].test_paths`.
    /// Skills filter on this to read test- vs production-side severities
    /// independently. Persisted in `latest.json` so consumers can split
    /// without re-deriving the matcher. Defaults to `false`; absent
    /// from JSON when false (`skip_serializing_if`) so non-test
    /// projects' caches stay byte-identical to v3.
    #[serde(default, skip_serializing_if = "is_false")]
    pub is_test_file: bool,
}

#[inline]
#[allow(clippy::trivially_copy_pass_by_ref)]
pub(crate) fn is_false(b: &bool) -> bool {
    !*b
}

impl Finding {
    /// Build a finding with the v0.2-prerequisite defaults: `Severity::Ok`
    /// (Calibration assigns the real severity later), `hotspot = false`,
    /// no extra locations, and no fix hint. The id is derived eagerly
    /// from `(metric, location, content_seed)` via [`Self::make_id`].
    /// Multi-site findings layer extras on with [`Self::with_locations`].
    #[must_use]
    pub fn new(metric: &str, location: Location, summary: String, content_seed: &str) -> Self {
        let id = Self::make_id(metric, &location, content_seed);
        Self {
            id,
            metric: metric.to_owned(),
            severity: Severity::Ok,
            hotspot: false,
            workspace: None,
            location,
            locations: Vec::new(),
            summary,
            fix_hint: None,
            accepted: false,
            is_test_file: false,
        }
    }

    #[must_use]
    pub fn with_locations(mut self, extras: Vec<Location>) -> Self {
        self.locations = extras;
        self
    }

    /// Pure change-coupling pair (any direction except Symmetric).
    pub const METRIC_CHANGE_COUPLING: &str = "change_coupling";
    /// Symmetric change-coupling — both files almost never move alone.
    pub const METRIC_CHANGE_COUPLING_SYMMETRIC: &str = "change_coupling.symmetric";
    /// Cross-workspace coupling — pair straddles two `[[project.workspaces]]`
    /// declarations. Routed to Advisory by default.
    pub const METRIC_CHANGE_COUPLING_CROSS_WORKSPACE: &str = "change_coupling.cross_workspace";
    /// "Expected" coupling — `TestSrc` / `DocSrc` pairs (test ↔ source,
    /// doc ↔ source) that are signal-aligned and shouldn't enter the
    /// drain queue, but get surfaced in the Advisory tier under
    /// `heal status --all` so users can see what was demoted.
    pub const METRIC_CHANGE_COUPLING_EXPECTED: &str = "change_coupling.expected";
    /// "Drifted" coupling — a `TestSrc` pair where the source side has
    /// recent commits but the paired test file is stale. Signals a test
    /// that no longer co-evolves with its subject. Surfaced as a real
    /// Finding (not demoted to Advisory) so it enters the drain queue.
    pub const METRIC_CHANGE_COUPLING_DRIFT: &str = "change_coupling.drift";

    /// Per-source-file line coverage percentage, ingested from an
    /// externally-generated lcov.info file. The metric is inverted in
    /// the calibration pipeline (`100 - coverage_pct` is fed to
    /// `MetricCalibration::classify`) so high coverage maps to
    /// `Severity::Ok` and low coverage to `Severity::Critical`. HEAL
    /// never runs tests itself; the lcov file is the user's contract.
    pub const METRIC_COVERAGE_PCT: &str = "coverage_pct";

    /// Per-test-file ratio of skipped tests to total tests, expressed as
    /// a percentage. Detected via tree-sitter walking of language-
    /// specific markers (`#[ignore]`, `it.skip`, `t.Skip()`,
    /// `@pytest.mark.skip`, `ScalaTest` `ignore`). Calibrated against
    /// `[calibration.skip_ratio]` with literature anchors > 1% Medium /
    /// > 5% High / > 20% Critical.
    pub const METRIC_SKIP_RATIO: &str = "skip_ratio";

    /// Per-src-file `commits × uncov_pct` composite. The test-family
    /// analogue of code Hotspot: ranks the src files where unverified
    /// change is piling up most. Always `Severity::Ok`; the importance
    /// is signaled via `hotspot=true` decoration on other test-family
    /// Findings (`coverage_pct`).
    pub const METRIC_TEST_HOTSPOT: &str = "test_hotspot";

    /// Per-pair `paired_src_churn × debt` composite. The docs-family
    /// analogue of code Hotspot: ranks the pairs whose paired src is
    /// churning fastest while the doc has fallen behind (or references
    /// names the src no longer defines). Always `Severity::Ok`;
    /// decorates docs-family Findings via `hotspot=true`.
    pub const METRIC_DOC_HOTSPOT: &str = "doc_hotspot";

    /// Family this finding belongs to, derived from `metric`.
    /// Mirrors `Feature::family()` — the dispatch surface for
    /// per-family `HotspotIndex` decoration is the same string-to-
    /// family map. Used by `heal status --feature <FAMILY>` and the
    /// per-family renderer in v0.4+.
    #[must_use]
    pub fn family(&self) -> crate::feature::Family {
        crate::feature::Family::for_metric(&self.metric)
    }

    /// Compact "metric=N" tag used by `heal status` rows and the
    /// post-commit nudge. The numeric tail is recovered from
    /// `summary` so observers don't have to expose a second value
    /// channel; metrics whose summary doesn't carry a leading number
    /// (`duplication`, `change_coupling`, `hotspot`) fall back to a
    /// short label.
    #[must_use]
    pub fn short_label(&self) -> String {
        match self.metric.as_str() {
            "ccn" => extract_leading_number(&self.summary, "CCN=")
                .map_or_else(|| "CCN".to_owned(), |v| format!("CCN={v}")),
            "cognitive" => extract_leading_number(&self.summary, "Cognitive=")
                .map_or_else(|| "Cognitive".to_owned(), |v| format!("Cognitive={v}")),
            "duplication" => "duplication".to_owned(),
            Self::METRIC_CHANGE_COUPLING => "coupled".to_owned(),
            Self::METRIC_CHANGE_COUPLING_SYMMETRIC => "coupled (sym)".to_owned(),
            Self::METRIC_CHANGE_COUPLING_CROSS_WORKSPACE => "coupled (cross-ws)".to_owned(),
            Self::METRIC_CHANGE_COUPLING_EXPECTED => "coupled (expected)".to_owned(),
            Self::METRIC_CHANGE_COUPLING_DRIFT => "coupled (drift)".to_owned(),
            Self::METRIC_COVERAGE_PCT => extract_leading_number(&self.summary, "Coverage=")
                .map_or_else(|| "Coverage".to_owned(), |v| format!("Coverage={v}%")),
            Self::METRIC_SKIP_RATIO => extract_leading_number(&self.summary, "Skip=")
                .map_or_else(|| "Skip".to_owned(), |v| format!("Skip={v}%")),
            "hotspot" => "hotspot".to_owned(),
            "lcom" => extract_leading_number(&self.summary, "LCOM=")
                .map_or_else(|| "LCOM".to_owned(), |v| format!("LCOM={v}")),
            other => other.to_owned(),
        }
    }

    /// Numeric value recovered from `summary`, when the metric carries
    /// one. Mirrors the prefix table `short_label` uses; metrics with
    /// label-only summaries (`duplication`, `change_coupling`,
    /// `hotspot`) return `None`.
    #[must_use]
    pub fn metric_value(&self) -> Option<f64> {
        let prefix = match self.metric.as_str() {
            "ccn" => "CCN=",
            "cognitive" => "Cognitive=",
            "lcom" => "LCOM=",
            Self::METRIC_COVERAGE_PCT => "Coverage=",
            Self::METRIC_SKIP_RATIO => "Skip=",
            _ => return None,
        };
        extract_leading_number(&self.summary, prefix)?.parse().ok()
    }

    /// Compose the stable id for a finding.
    ///
    /// Format: `<metric>:<file>:<symbol-or-*>:<16-hex-fnv1a>`. The hex
    /// digest covers `metric || file || symbol || content_seed`, so
    /// even when two findings share a (metric, file, symbol) triple
    /// the seed differentiates them. Conversely, an unchanged finding
    /// across commits hashes identically because the inputs are
    /// observer-derived strings, not line numbers or scores.
    #[must_use]
    pub fn make_id(metric: &str, location: &Location, content_seed: &str) -> String {
        let path = location.file.to_string_lossy();
        let symbol = location.symbol.as_deref().unwrap_or("*");
        let h = fnv1a_64_chunked(&[
            metric.as_bytes(),
            path.as_bytes(),
            symbol.as_bytes(),
            content_seed.as_bytes(),
        ]);
        format!("{metric}:{path}:{symbol}:{}", fnv1a_hex(h))
    }
}

/// Pluck the `<digits>` immediately after `prefix` from `summary`,
/// returning `None` when no digit follows. Used by [`Finding::short_label`]
/// to recover CCN/Cognitive numbers without round-tripping observer state.
fn extract_leading_number(summary: &str, prefix: &str) -> Option<String> {
    let after = summary.strip_prefix(prefix)?;
    let value: String = after.chars().take_while(char::is_ascii_digit).collect();
    if value.is_empty() {
        None
    } else {
        Some(value)
    }
}

/// Lower an observer report into a list of findings.
///
/// Implementations live next to each observer report (`observer::*`).
/// The trait is sealed by convention — only HEAL's own observers are
/// expected to implement it.
///
/// The method takes `&self` (not `self`) because callers usually keep
/// the report around for `heal metrics` rendering after extracting
/// findings.
pub trait IntoFindings {
    #[allow(clippy::wrong_self_convention)]
    fn into_findings(&self) -> Vec<Finding>;
}

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

    fn loc(file: &str, symbol: Option<&str>, line: Option<u32>) -> Location {
        Location {
            file: PathBuf::from(file),
            line,
            symbol: symbol.map(str::to_owned),
        }
    }

    #[test]
    fn make_id_is_stable_for_identical_input() {
        let l = loc("src/foo.rs", Some("bar"), Some(10));
        let a = Finding::make_id("ccn", &l, "seed-1");
        let b = Finding::make_id("ccn", &l, "seed-1");
        assert_eq!(a, b);
        assert!(a.starts_with("ccn:src/foo.rs:bar:"));
    }

    #[test]
    fn make_id_differs_when_any_component_differs() {
        let l = loc("src/foo.rs", Some("bar"), None);
        let base = Finding::make_id("ccn", &l, "");
        assert_ne!(base, Finding::make_id("cognitive", &l, ""));
        assert_ne!(
            base,
            Finding::make_id("ccn", &loc("src/baz.rs", Some("bar"), None), "")
        );
        assert_ne!(
            base,
            Finding::make_id("ccn", &loc("src/foo.rs", Some("baz"), None), "")
        );
        assert_ne!(base, Finding::make_id("ccn", &l, "extra"));
    }

    #[test]
    fn make_id_avoids_concatenation_collisions() {
        // Without separators, ("ab","c") and ("a","bc") would collide.
        let a = Finding::make_id("ab", &loc("c", None, None), "");
        let b = Finding::make_id("a", &loc("bc", None, None), "");
        assert_ne!(a, b);
    }

    #[test]
    fn make_id_uses_star_when_symbol_missing() {
        let l = loc("src/foo.rs", None, None);
        let id = Finding::make_id("hotspot", &l, "");
        assert!(id.starts_with("hotspot:src/foo.rs:*:"));
    }

    #[test]
    fn short_label_extracts_metric_number_or_falls_back() {
        let mut ccn = Finding::new(
            "ccn",
            loc("src/foo.rs", Some("bar"), Some(10)),
            "CCN=28 bar (rust)".into(),
            "seed",
        );
        ccn.severity = Severity::Critical;
        assert_eq!(ccn.short_label(), "CCN=28");

        let cog = Finding::new(
            "cognitive",
            loc("src/foo.rs", Some("bar"), Some(10)),
            "Cognitive=42 bar (rust)".into(),
            "seed",
        );
        assert_eq!(cog.short_label(), "Cognitive=42");

        // Summary with no digit after `CCN=` falls back to the bare label.
        let bare = Finding::new(
            "ccn",
            loc("src/foo.rs", Some("bar"), Some(10)),
            "no number here".into(),
            "seed",
        );
        assert_eq!(bare.short_label(), "CCN");

        let dup = Finding::new(
            "duplication",
            loc("src/foo.rs", None, None),
            "anything".into(),
            "",
        );
        assert_eq!(dup.short_label(), "duplication");
    }

    #[test]
    fn finding_serialises_without_empty_locations_or_fix_hint() {
        let f = Finding {
            id: "x".into(),
            metric: "ccn".into(),
            severity: Severity::Ok,
            hotspot: false,
            workspace: None,
            location: loc("src/foo.rs", Some("bar"), Some(1)),
            locations: vec![],
            summary: "hi".into(),
            fix_hint: None,
            accepted: false,
            is_test_file: false,
        };
        let json = serde_json::to_string(&f).unwrap();
        assert!(!json.contains("locations"));
        assert!(!json.contains("fix_hint"));
        assert!(!json.contains("workspace"));
        assert!(!json.contains("accepted"));
        assert!(!json.contains("is_test_file"));
    }
}