codelore-lib 0.26.0

//! Deterministic per-file and diff fact sheets.
//!
//! A fact sheet is a compact, sorted, pre-formatted serialization of values the
//! existing analyses already compute — [`FileFactSheet::build`] calls the same
//! `run_*` functions the CLI dispatches to, never new computation. It is the
//! grounding input for the advisory narrative layer and the content the sidecar
//! cache keys on, so two builds over the same fact store must produce
//! byte-identical text: every float is rendered through the single shared
//! [`fmt_num`] helper, and every section / key is emitted in the fixed
//! insertion order the builders produce.

use crate::analyses::code_health::{SMELL_WEIGHTS, run_code_health};
use crate::analyses::coupling::run_coupling;
use crate::analyses::cycle_health::run_cycle_health;
use crate::analyses::function_xray::run_function_xray;
use crate::analyses::hotspots::run_hotspots;
use crate::analyses::ownership::run_ownership;
use crate::defect_calibration;
use crate::defect_calibration::validate::capture_intensities;
use crate::facts::FactsDb;
use crate::repo::Repo;
use crate::{CodeLoreError, Options, Result};

use sha2::{Digest, Sha256};

/// One `(key, value)` fact. Values are pre-formatted strings — numeric values
/// through [`fmt_num`], everything else verbatim.
type Kv = (String, String);
/// One named section: a title and its ordered facts.
type Section = (String, Vec<Kv>);

/// Number of coupling partners / function leaders / cycle rows a fact sheet
/// keeps. Small enough to stay reviewer-legible and keep the prompt compact.
const TOP_N: usize = 5;

/// Format a float for a fact sheet: fixed six decimals, then trailing zeros
/// (and a bare trailing point) trimmed. The single float formatter for every
/// fact sheet — sharing it is what keeps two builds byte-identical.
///
/// `2.0` renders `"2"`, `0.803` renders `"0.803"`, `0.0` renders `"0"`.
#[must_use]
pub fn fmt_num(value: f64) -> String {
    let formatted = format!("{value:.6}");
    let trimmed = formatted.trim_end_matches('0').trim_end_matches('.');
    trimmed.to_string()
}

/// Render sections as canonical text: `section\n  key = value\n` lines, in
/// insertion order. The cache-key + prompt input; deterministic by
/// construction.
fn render_canonical(sections: &[Section]) -> String {
    let mut out = String::new();
    for (section, facts) in sections {
        out.push_str(section);
        out.push('\n');
        for (key, value) in facts {
            out.push_str("  ");
            out.push_str(key);
            out.push_str(" = ");
            out.push_str(value);
            out.push('\n');
        }
    }
    out
}

/// Every value that parses whole as a finite float, in section then key order —
/// the fact-value set the narrative citation check matches against.
fn collect_numeric(sections: &[Section]) -> Vec<f64> {
    let mut out = Vec::new();
    for (_, facts) in sections {
        for (_, value) in facts {
            if let Ok(n) = value.trim().parse::<f64>()
                && n.is_finite()
            {
                out.push(n);
            }
        }
    }
    out
}

/// Lowercase hex SHA-256 of `text`.
fn digest_of(text: &str) -> String {
    let mut hasher = Sha256::new();
    hasher.update(text.as_bytes());
    hex::encode(hasher.finalize())
}

/// A deterministic per-file evidence dossier: ordered sections of pre-formatted
/// facts drawn from the analyses. See the module docs for the determinism
/// contract.
#[derive(Debug, Clone)]
pub struct FileFactSheet {
    /// Repo-relative path the sheet describes.
    pub path: String,
    /// Ordered `(section, [(key, value)])` facts — already sorted, values
    /// pre-formatted.
    pub sections: Vec<(String, Vec<(String, String)>)>,
}

impl FileFactSheet {
    /// Assemble the fact sheet for `path` from the analyses, in a fixed order.
    ///
    /// The code-health section is mandatory: an error naming the path is
    /// returned when the path has no code-health row (it is not a tracked
    /// source file, or has too few revisions). The hotspots, functions, cycle,
    /// and defect-evidence sections are conditional and are simply omitted when
    /// they have no data for the path.
    ///
    /// # Errors
    ///
    /// Returns [`CodeLoreError::Analysis`] when the path has no code-health data,
    /// and propagates any analysis or fact-store error from the feeds.
    pub fn build<R: Repo>(db: &FactsDb, repo: &R, opts: &Options, path: &str) -> Result<Self> {
        // Row limits are a cosmetic output cap; a fact sheet must find its
        // target regardless of `--rows`, so every feed runs un-row-limited.
        let opts = opts.with_no_row_limit();
        let mut sections: Vec<Section> = Vec::new();

        // (1) code-health — mandatory.
        sections.push(code_health_section(db, &opts, path)?);
        // (2) biomarkers — MUST come immediately after the HEAD code-health run
        // above: `capture_intensities` reads the temporary biomarker table that
        // run replaced, and any intervening code-health scan would overwrite it.
        if let Some(section) = biomarkers_section(db, path)? {
            sections.push(section);
        }
        // (3) hotspots — rank + score, when the path is ranked.
        if let Some(section) = hotspots_section(db, &opts, path)? {
            sections.push(section);
        }
        // (4) coupling — top partners by degree.
        if let Some(section) = coupling_section(db, &opts, path)? {
            sections.push(section);
        }
        // (5) ownership — main author, revisions, fragmentation.
        if let Some(section) = ownership_section(db, &opts, path)? {
            sections.push(section);
        }
        // (6) functions — churn leaders; skipped for non-Tier-1 paths.
        if let Some(section) = functions_section(db, repo, &opts, path) {
            sections.push(section);
        }
        // (7) cycle — import-cycle membership / extraction candidate.
        if let Some(section) = cycle_section(db, &opts, path)? {
            sections.push(section);
        }
        // (8) defect-evidence — only with a configured calibration artifact.
        if let Some(section) = defect_evidence_section(&opts)? {
            sections.push(section);
        }

        Ok(Self {
            path: path.to_string(),
            sections,
        })
    }

    /// Canonical text: the deterministic cache-key + prompt input.
    #[must_use]
    pub fn to_canonical_text(&self) -> String {
        render_canonical(&self.sections)
    }

    /// Human-readable dossier rendering for `explain <path>`.
    #[must_use]
    pub fn to_human_text(&self) -> String {
        let mut out = format!("fact sheet for {}\n", self.path);
        for (section, facts) in &self.sections {
            out.push('\n');
            out.push('[');
            out.push_str(section);
            out.push_str("]\n");
            for (key, value) in facts {
                out.push_str("  ");
                out.push_str(key);
                out.push_str(" = ");
                out.push_str(value);
                out.push('\n');
            }
        }
        out
    }

    /// Lowercase hex SHA-256 of the canonical text.
    #[must_use]
    pub fn digest(&self) -> String {
        digest_of(&self.to_canonical_text())
    }

    /// Every parseable numeric value, for the narrative citation check.
    #[must_use]
    pub fn numeric_values(&self) -> Vec<f64> {
        collect_numeric(&self.sections)
    }
}

/// A deterministic diff evidence dossier. Shares the canonical-text / digest /
/// numeric-value rendering with [`FileFactSheet`]; the CLI flattens its
/// `DiffOutput` into sections and hands them to [`DiffFactSheet::from_sections`]
/// (the `DiffOutput` type lives in the CLI crate, so the lib side takes the
/// pre-flattened sections instead).
#[derive(Debug, Clone)]
pub struct DiffFactSheet {
    /// Ordered `(section, [(key, value)])` facts — already sorted, values
    /// pre-formatted.
    pub sections: Vec<(String, Vec<(String, String)>)>,
}

impl DiffFactSheet {
    /// Construct from pre-flattened sections (the CLI-side flattening of a
    /// `DiffOutput`).
    #[must_use]
    pub fn from_sections(sections: Vec<(String, Vec<(String, String)>)>) -> Self {
        Self { sections }
    }

    /// Canonical text: the deterministic cache-key + prompt input.
    #[must_use]
    pub fn to_canonical_text(&self) -> String {
        render_canonical(&self.sections)
    }

    /// Lowercase hex SHA-256 of the canonical text.
    #[must_use]
    pub fn digest(&self) -> String {
        digest_of(&self.to_canonical_text())
    }

    /// Every parseable numeric value, for the narrative citation check.
    #[must_use]
    pub fn numeric_values(&self) -> Vec<f64> {
        collect_numeric(&self.sections)
    }
}

/// (1) code-health — mandatory. Errors, naming the path, when absent.
fn code_health_section(db: &FactsDb, opts: &Options, path: &str) -> Result<Section> {
    let rows = run_code_health(db, opts)?;
    let row = rows.iter().find(|r| r.path == path).ok_or_else(|| {
        CodeLoreError::Analysis(format!(
            "no code-health data for {path} — is it a tracked source file?"
        ))
    })?;
    let mut facts = vec![
        ("score".to_string(), fmt_num(row.score)),
        ("band".to_string(), row.band.clone()),
        ("structural_risk".to_string(), fmt_num(row.structural_risk)),
        ("percentile".to_string(), fmt_num(row.percentile)),
    ];
    if let Some(corpus) = row.corpus_percentile {
        facts.push(("corpus_percentile".to_string(), fmt_num(corpus)));
        // Wilson 95% interval on that percentile — the corpus is a finite
        // sample, so the rank carries sampling uncertainty, not a point value.
        if let (Some(lo), Some(hi)) = (row.corpus_percentile_ci_low, row.corpus_percentile_ci_high)
        {
            facts.push((
                "corpus_percentile_ci".to_string(),
                format!("{}–{}", fmt_num(lo), fmt_num(hi)),
            ));
        }
    }
    facts.push(("cognitive".to_string(), fmt_num(row.cognitive)));
    Ok(("code-health".to_string(), facts))
}

/// (2) biomarkers — the eight intensities in `SMELL_WEIGHTS` order. Omitted
/// when the path has no captured biomarker row.
fn biomarkers_section(db: &FactsDb, path: &str) -> Result<Option<Section>> {
    let intensities = capture_intensities(db)?;
    let Some(values) = intensities.get(path) else {
        return Ok(None);
    };
    let facts = SMELL_WEIGHTS
        .iter()
        .enumerate()
        .map(|(i, &(name, _))| (name.to_string(), fmt_num(values[i])))
        .collect();
    Ok(Some(("biomarkers".to_string(), facts)))
}

/// (3) hotspots — 1-based rank in the ranking plus the score. Omitted when the
/// path is not ranked.
fn hotspots_section(db: &FactsDb, opts: &Options, path: &str) -> Result<Option<Section>> {
    let rows = run_hotspots(db, opts)?;
    let Some(rank) = rows.iter().position(|r| r.path == path) else {
        return Ok(None);
    };
    let row = &rows[rank];
    let facts = vec![
        ("rank".to_string(), (rank + 1).to_string()),
        ("hotspot_score".to_string(), fmt_num(row.hotspot_score)),
    ];
    Ok(Some(("hotspots".to_string(), facts)))
}

/// (4) coupling — the path's top `TOP_N` Fisher-significant partners by degree
/// (ties broken by partner path). Omitted when the path has no partners.
fn coupling_section(db: &FactsDb, opts: &Options, path: &str) -> Result<Option<Section>> {
    let rows = run_coupling(db, opts)?;
    let mut partners: Vec<(&str, u32, f64, f64)> = rows
        .iter()
        .filter_map(|r| {
            if r.entity_a == path {
                Some((r.entity_b.as_str(), r.shared, r.degree, r.fisher_p))
            } else if r.entity_b == path {
                Some((r.entity_a.as_str(), r.shared, r.degree, r.fisher_p))
            } else {
                None
            }
        })
        .collect();
    if partners.is_empty() {
        return Ok(None);
    }
    partners.sort_by(|a, b| b.2.total_cmp(&a.2).then_with(|| a.0.cmp(b.0)));
    partners.truncate(TOP_N);

    let mut facts = Vec::new();
    for (i, (partner, shared, degree, fisher_p)) in partners.iter().enumerate() {
        let n = i + 1;
        facts.push((format!("{n}.partner"), (*partner).to_string()));
        facts.push((format!("{n}.shared"), shared.to_string()));
        facts.push((format!("{n}.degree"), fmt_num(*degree)));
        facts.push((format!("{n}.fisher_p"), fmt_num(*fisher_p)));
    }
    Ok(Some(("coupling".to_string(), facts)))
}

/// (5) ownership — main author, revision count, fragmentation. Omitted when the
/// path has no ownership row.
fn ownership_section(db: &FactsDb, opts: &Options, path: &str) -> Result<Option<Section>> {
    let rows = run_ownership(db, opts)?;
    let Some(row) = rows.iter().find(|r| r.path == path) else {
        return Ok(None);
    };
    let facts = vec![
        ("main_author".to_string(), row.main_author.clone()),
        ("total_revs".to_string(), row.total_revs.to_string()),
        ("fractal_value".to_string(), fmt_num(row.fractal_value)),
    ];
    Ok(Some(("ownership".to_string(), facts)))
}

/// (6) functions — the path's top `TOP_N` churn-leading functions. Skipped
/// entirely (no section) when function-xray errors — not every path is a
/// supported Tier-1 source file — or when the file has no functions.
fn functions_section<R: Repo>(
    db: &FactsDb,
    repo: &R,
    opts: &Options,
    path: &str,
) -> Option<Section> {
    // A hard error here means the path is not Tier-1 (or has no HEAD-alive
    // functions); an advisory dossier degrades by omitting the section rather
    // than failing the whole build.
    let rows = run_function_xray(db, repo, opts, path).ok()?;
    if rows.is_empty() {
        return None;
    }
    let mut facts = Vec::new();
    // Rows arrive sorted by change_freq DESC, function ASC.
    for (i, row) in rows.iter().take(TOP_N).enumerate() {
        let n = i + 1;
        facts.push((format!("{n}.function"), row.function.clone()));
        facts.push((format!("{n}.change_freq"), row.change_freq.to_string()));
        facts.push((format!("{n}.loc"), row.loc.to_string()));
        if let Some(cyclomatic) = row.cyclomatic {
            facts.push((format!("{n}.cyclomatic"), cyclomatic.to_string()));
        }
        if let Some(cognitive) = row.cognitive {
            facts.push((format!("{n}.cognitive"), cognitive.to_string()));
        }
    }
    Some(("functions".to_string(), facts))
}

/// (7) cycle — the import cycles the path drives (extract candidate) or is a
/// member of. Omitted when the path is in no cycle.
fn cycle_section(db: &FactsDb, opts: &Options, path: &str) -> Result<Option<Section>> {
    let rows = run_cycle_health(db, opts)?;
    let mut facts = Vec::new();
    let mut n = 0;
    for row in &rows {
        if row.extract_candidate != path && !row.members_preview.contains(path) {
            continue;
        }
        n += 1;
        facts.push((format!("{n}.cycle_id"), row.cycle_id.to_string()));
        facts.push((format!("{n}.size"), row.size.to_string()));
        facts.push((format!("{n}.heat_pct"), fmt_num(row.heat_pct)));
        facts.push((format!("{n}.verdict"), row.verdict.clone()));
        facts.push((
            format!("{n}.extract_candidate"),
            row.extract_candidate.clone(),
        ));
        if let Some(drop) = row.predicted_pc_drop {
            facts.push((format!("{n}.predicted_pc_drop"), fmt_num(drop)));
        }
    }
    if facts.is_empty() {
        return Ok(None);
    }
    Ok(Some(("cycle".to_string(), facts)))
}

/// (8) defect-evidence — the configured calibration artifact's headline
/// validation numbers. Per-file defect implication is not derivable from the
/// artifact, so only the artifact-wide metrics are surfaced. Omitted when no
/// artifact is configured.
fn defect_evidence_section(opts: &Options) -> Result<Option<Section>> {
    let Some(artifact_path) = &opts.defect_calibration else {
        return Ok(None);
    };
    let artifact = defect_calibration::load(artifact_path)?;
    defect_calibration::check_repo_identity(
        &artifact,
        &opts.repo_path,
        opts.allow_foreign_calibration,
    )?;
    let validation = &artifact.validation;
    let mut facts = vec![("vintage".to_string(), artifact.vintage.clone())];
    if let Some(auc) = validation.auc_default {
        facts.push(("auc_default".to_string(), fmt_num(auc)));
    }
    if let Some(precision) = validation.precision_at_10 {
        facts.push(("precision_at_10".to_string(), fmt_num(precision)));
    }
    if let Some(precision) = validation.precision_at_red {
        facts.push(("precision_at_red".to_string(), fmt_num(precision)));
    }
    facts.push((
        "implicated_files".to_string(),
        validation.implicated_files.to_string(),
    ));
    facts.push((
        "linked_defects".to_string(),
        validation.linked_defects.to_string(),
    ));
    for (band, changes, share) in &validation.band_table {
        facts.push((format!("band:{band}:changes"), changes.to_string()));
        facts.push((format!("band:{band}:share"), fmt_num(*share)));
    }
    Ok(Some(("defect-evidence".to_string(), facts)))
}

#[cfg(test)]
mod tests {
    use super::{DiffFactSheet, FileFactSheet, fmt_num};

    #[test]
    fn fmt_num_trims_trailing_zeros_and_point() {
        assert_eq!(fmt_num(2.0), "2");
        assert_eq!(fmt_num(0.0), "0");
        assert_eq!(fmt_num(0.803), "0.803");
        assert_eq!(fmt_num(87.5), "87.5");
        assert_eq!(fmt_num(0.000_001), "0.000001");
    }

    #[test]
    fn canonical_text_is_section_key_value_lines() {
        let sheet = FileFactSheet {
            path: "x.rs".to_string(),
            sections: vec![(
                "code-health".to_string(),
                vec![
                    ("score".to_string(), "87.5".to_string()),
                    ("band".to_string(), "green".to_string()),
                ],
            )],
        };
        assert_eq!(
            sheet.to_canonical_text(),
            "code-health\n  score = 87.5\n  band = green\n"
        );
    }

    #[test]
    fn numeric_values_parses_only_whole_number_values() {
        let sheet = FileFactSheet {
            path: "x.rs".to_string(),
            sections: vec![
                (
                    "code-health".to_string(),
                    vec![
                        ("score".to_string(), "87.5".to_string()),
                        ("band".to_string(), "green".to_string()),
                    ],
                ),
                (
                    "biomarkers".to_string(),
                    vec![
                        ("dry".to_string(), "0.5".to_string()),
                        ("count".to_string(), "3".to_string()),
                    ],
                ),
            ],
        };
        assert_eq!(sheet.numeric_values(), vec![87.5, 0.5, 3.0]);
    }

    #[test]
    fn diff_sheet_shares_the_canonical_renderer() {
        let sections = vec![(
            "verdict".to_string(),
            vec![("ratio".to_string(), "1.25".to_string())],
        )];
        let sheet = DiffFactSheet::from_sections(sections);
        assert_eq!(sheet.to_canonical_text(), "verdict\n  ratio = 1.25\n");
        assert_eq!(sheet.numeric_values(), vec![1.25]);
        // Digest is the SHA-256 of the canonical text — stable and lowercase hex.
        assert_eq!(sheet.digest().len(), 64);
        assert!(sheet.digest().chars().all(|c| c.is_ascii_hexdigit()));
    }
}