repotoire 0.8.2

//! Dual-branch predictor for Python weak-hash calls.
//!
//! Implements decisions D1 (weights) and D3 (severity) from
//! `docs/superpowers/specs/2026-05-09-dual-branch-phase2-insecure-crypto-decisions.md`.
//!
//! # What this module does
//!
//! Given a Python call site for a weak hash primitive (`hashlib.md5`,
//! `hashlib.sha1`, `hashlib.new("md5")`, etc.), produce a [`Prediction`]
//! that:
//!
//! 1. Picks `RealBug` or `Benign` as the predicted branch.
//! 2. Carries the other branch as the alternative.
//! 3. Lists typed [`PredictionReason`]s the predictor used.
//! 4. Optionally lists [`ResolutionSignal`]s (collapsing or hint-grade).
//!
//! # Pipeline
//!
//! ```text
//! call_node ──extract_evidence──> Evidence ──predict──> Prediction
//! ```
//!
//! `extract_evidence` is pure AST traversal; `predict` is pure scoring.
//! The split makes both halves independently testable: scoring tests
//! don't need a parsed source tree, and evidence tests don't need
//! committed weights.
//!
//! # Sign convention
//!
//! `weight > 0` leans **Benign**; `weight < 0` leans **RealBug**. This
//! matches the convention recorded in `dual_branch::PredictionReason`
//! and the decisions doc.
//!
//! # Resolution signals (collapsing)
//!
//! Two signals fully collapse the prediction (skip weighted scoring,
//! commit to one branch):
//!
//! - `usedforsecurity=False` keyword argument → `Benign`, confidence 1.0.
//! - `# repotoire: protocol-required[<RFC>]` annotation → `Benign`,
//!   confidence 1.0. The RFC arg is informational; not validated.
//!
//! Both are also surfaced as [`ResolutionSignal`]s so a developer who
//! disagrees with the predictor's leaning has the documented mechanism
//! for forcing the Benign branch.
//!
//! # Why these weights
//!
//! See decision **D1**. The numbers are the design doc's published
//! example weights. They are tagged `TUNABLE` because the design doc
//! back-computed them to produce its 82%-confidence example, not from
//! ground-truth data. Phase 3 misprediction logging is the right place
//! to retune; until then, changes need to preserve the worked example.

use super::annotation::parse_python_comment;
use crate::dual_branch::{
    AlternativeBranch, BranchLabel, PredictionReason, PredictionReasonKind, ResolutionKind,
    ResolutionSignal,
};
use crate::models::Severity;

// ─────────────────────────────────────────────────────────────────────────────
// Tunable weights
// ─────────────────────────────────────────────────────────────────────────────

// TUNABLE: see Phase 3 misprediction logging.
//
// These are the design-doc example weights. Sum on the worked example
// (DigestAuth class + non-sensitive arg + truncation + urandom input)
// is 0.40 + 0.20 + 0.15 + 0.07 = 0.82, matching the doc's "82%
// confidence" output.
//
// Sign convention: positive leans Benign, negative leans RealBug.

/// Enclosing scope is a class whose name suggests an authentication
/// protocol (e.g. `DigestAuth`).
const W_AUTH_PROTOCOL_CLASS: f32 = 0.40;

/// First positional argument's identifier name matches a sensitive
/// lexicon (e.g. `password`, `secret`, `token`).
const W_FIRST_ARG_SENSITIVE: f32 = -0.40;

/// First positional argument's identifier name does NOT match the
/// sensitive lexicon (a generic name like `s`, `data`, `value`).
const W_FIRST_ARG_NON_SENSITIVE: f32 = 0.20;

/// The result of the hash is truncated with a `[:N]` slice.
const W_RESULT_TRUNCATED: f32 = 0.15;

/// The hash input includes `os.urandom(...)`, suggesting nonce/key-id
/// generation rather than security-relevant hashing.
const W_INPUT_INCLUDES_URANDOM: f32 = 0.07;

// ─────────────────────────────────────────────────────────────────────────────
// Sensitive-lexicon
// ─────────────────────────────────────────────────────────────────────────────

/// Lowercased identifier substrings that mark an argument as
/// security-sensitive.
///
/// Substring match (not exact) so `user_password`, `pw`, `secret_token`
/// all hit. Order doesn't matter; first match wins for evidence
/// purposes (the weight is the same either way).
///
/// TUNABLE: this lexicon is conservative. Phase 3 misprediction logging
/// will inform additions/removals.
const SENSITIVE_IDENT_SUBSTRINGS: &[&str] = &[
    "password",
    "passwd",
    "secret",
    "token",
    "credential",
    "apikey",
    "api_key",
    "private_key",
    "privatekey",
    "auth",
    "session",
];

/// Class-name substrings (case-insensitive) that mark the enclosing
/// class as an authentication-protocol implementation.
///
/// `DigestAuth` (HTTPX) is the design-doc canonical example. `Hmac` is
/// excluded because hmac classes are themselves the security
/// implementation, not callers; their MD5 use IS the bug.
const AUTH_PROTOCOL_CLASS_SUBSTRINGS: &[&str] = &[
    "digestauth",
    "ntlmauth",
    "krb5",
    "oauth1signature", // OAuth 1 used HMAC-SHA1 by spec
];

// ─────────────────────────────────────────────────────────────────────────────
// Evidence
// ─────────────────────────────────────────────────────────────────────────────

/// Structured evidence extracted from a call site, ready for scoring.
///
/// Each field corresponds to one signal class. Fields are `Option` /
/// `bool` so the scorer can ignore absent evidence; the scorer doesn't
/// need to know HOW the evidence was extracted (AST walk, line-text
/// regex, graph lookup), only WHAT it is.
#[derive(Debug, Clone, Default, PartialEq)]
pub(super) struct Evidence {
    /// Name of the enclosing class, if any. `None` at module level or
    /// inside a function not nested in a class.
    pub enclosing_class: Option<String>,

    /// Name of the enclosing function, if any.
    pub enclosing_function: Option<String>,

    /// Name of the first positional argument's identifier, if the
    /// argument is a bare identifier (not a string literal, not an
    /// expression). For `hashlib.sha1(password)` this is `Some("password")`;
    /// for `hashlib.sha1(data + nonce)` this is `None`.
    pub first_arg_ident: Option<String>,

    /// True if the call's result is sliced with `[:N]` for some
    /// integer `N`. Indicates truncation, which suggests the caller
    /// wants a short identifier rather than a cryptographic digest.
    pub result_truncated: bool,

    /// True if the first argument expression includes a call to
    /// `os.urandom(...)`. Suggests nonce/key-id generation.
    pub input_includes_urandom: bool,

    /// True if the call has `usedforsecurity=False` as a keyword
    /// argument. **Collapsing**: forces Benign with confidence 1.0.
    pub usedforsecurity_false: bool,

    /// `Some(rfc)` if a `# repotoire: protocol-required[<rfc>]`
    /// annotation appears on the call line. **Collapsing**: forces
    /// Benign with confidence 1.0. The `rfc` string is informational.
    pub protocol_required_annotation: Option<String>,
}

impl Evidence {
    /// Convenience for tests: empty evidence (no signals at all).
    #[cfg(test)]
    pub(super) fn empty() -> Self {
        Self::default()
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// Prediction
// ─────────────────────────────────────────────────────────────────────────────

/// The output of running [`predict`] on extracted evidence.
///
/// The caller's job is to map this onto a `Finding`:
///
/// - `predicted_severity` becomes the primary `Finding::severity`.
/// - `predicted_*_text` (title/description/fix) become primary fields.
/// - An [`AlternativeBranch`] for the opposite label is built from
///   `alternative_*_text` and pushed via `Finding::with_alternative_branch`.
/// - Each [`PredictionReason`] is pushed via `with_prediction_reason`.
/// - Each [`ResolutionSignal`] is pushed via `with_resolution_signal`.
#[derive(Debug, Clone)]
pub(super) struct Prediction {
    /// Which interpretation the predictor chose.
    pub predicted: BranchLabel,
    /// The alternative interpretation, mirror-image of `predicted`.
    pub alternative_branch: AlternativeBranch,
    /// Severity to use for the predicted branch.
    pub predicted_severity: Severity,
    /// Typed evidence list, in the order it was scored.
    pub reasons: Vec<PredictionReason>,
    /// Collapsing or hint-grade resolution signals.
    pub resolutions: Vec<ResolutionSignal>,
}

// ─────────────────────────────────────────────────────────────────────────────
// Scorer
// ─────────────────────────────────────────────────────────────────────────────

/// Build a [`Prediction`] from extracted [`Evidence`].
///
/// # Algorithm
///
/// 1. **Collapsing signals first.** If `usedforsecurity_false` or
///    `protocol_required_annotation` is set, commit to Benign with
///    confidence 1.0 and skip weighted scoring. The other branch is
///    still constructed so consumers can render it on demand.
///
/// 2. **Weighted scoring.** Sum weights for each present signal:
///    - `enclosing_class` matching `AUTH_PROTOCOL_CLASS_SUBSTRINGS` →
///      `W_AUTH_PROTOCOL_CLASS` (Benign).
///    - `first_arg_ident` matching `SENSITIVE_IDENT_SUBSTRINGS` →
///      `W_FIRST_ARG_SENSITIVE` (RealBug).
///    - `first_arg_ident` not in lexicon (and not None) →
///      `W_FIRST_ARG_NON_SENSITIVE` (Benign).
///    - `result_truncated` → `W_RESULT_TRUNCATED` (Benign).
///    - `input_includes_urandom` → `W_INPUT_INCLUDES_URANDOM` (Benign).
///
/// 3. **Tiebreak**: if the sum is exactly 0.0, predict RealBug. Bias
///    toward false-positives over false-negatives for security findings.
///    (Documented; not configurable.)
///
/// # Severity mapping
///
/// - Predicted RealBug → `Severity::High` (matches existing weak-hash
///   severity).
/// - Predicted Benign → `Severity::Info` (the call is correct usage).
///
/// The alternative branch carries the OPPOSITE severity.
pub(super) fn predict(
    evidence: &Evidence,
    algo_label: &str, // e.g. "MD5", "SHA1" — for messages
) -> Prediction {
    // ── Step 1: collapsing signals. ──
    if evidence.usedforsecurity_false {
        return collapse_to_benign(
            algo_label,
            ResolutionSignal {
                kind: ResolutionKind::KeywordArgument {
                    name: "usedforsecurity".to_string(),
                    value: "False".to_string(),
                },
                description: format!(
                    "`usedforsecurity=False` declares this {algo_label} call as \
                     non-security (Python 3.9+); the finding collapses to Info."
                ),
                example: Some(format!(
                    "hashlib.{}(data, usedforsecurity=False)",
                    algo_label.to_lowercase()
                )),
                collapses_to: BranchLabel::Benign,
            },
            PredictionReason {
                kind: PredictionReasonKind::KeywordArgument {
                    name: "usedforsecurity".to_string(),
                    value: "False".to_string(),
                },
                weight: 1.0,
                note: format!(
                    "Caller explicitly opted out of security semantics for this \
                     {algo_label} call."
                ),
            },
        );
    }
    if let Some(rfc) = &evidence.protocol_required_annotation {
        return collapse_to_benign(
            algo_label,
            ResolutionSignal {
                kind: ResolutionKind::SourceAnnotation {
                    syntax: format!("# repotoire: protocol-required[{rfc}]"),
                },
                description: format!(
                    "`protocol-required[{rfc}]` annotation declares this {algo_label} \
                     call as required by an external protocol; the finding collapses \
                     to Info."
                ),
                example: Some(format!(
                    "hashlib.{}(data)  # repotoire: protocol-required[{rfc}]",
                    algo_label.to_lowercase()
                )),
                collapses_to: BranchLabel::Benign,
            },
            PredictionReason {
                kind: PredictionReasonKind::Custom {
                    description: format!("protocol-required[{rfc}] annotation"),
                },
                weight: 1.0,
                note: format!(
                    "Annotated as required by {rfc}; not a discretionary algorithm choice."
                ),
            },
        );
    }

    // ── Step 2: weighted scoring. ──
    let mut sum: f32 = 0.0;
    let mut reasons: Vec<PredictionReason> = Vec::new();

    if let Some(class_name) = &evidence.enclosing_class {
        if matches_auth_protocol_class(class_name) {
            sum += W_AUTH_PROTOCOL_CLASS;
            reasons.push(PredictionReason {
                kind: PredictionReasonKind::EnclosingScope {
                    scope_kind: "class".to_string(),
                    name: class_name.clone(),
                },
                weight: W_AUTH_PROTOCOL_CLASS,
                note: format!(
                    "Enclosing class `{class_name}` matches an authentication-protocol \
                     pattern; {algo_label} use is likely protocol-required."
                ),
            });
        }
    }

    if let Some(arg_name) = &evidence.first_arg_ident {
        if matches_sensitive_ident(arg_name) {
            sum += W_FIRST_ARG_SENSITIVE;
            reasons.push(PredictionReason {
                kind: PredictionReasonKind::FirstArgIdentifier {
                    name: arg_name.clone(),
                },
                weight: W_FIRST_ARG_SENSITIVE,
                note: format!(
                    "First argument is `{arg_name}`, which matches a sensitive-data \
                     lexicon; this looks like security-relevant hashing."
                ),
            });
        } else {
            sum += W_FIRST_ARG_NON_SENSITIVE;
            reasons.push(PredictionReason {
                kind: PredictionReasonKind::FirstArgIdentifier {
                    name: arg_name.clone(),
                },
                weight: W_FIRST_ARG_NON_SENSITIVE,
                note: format!(
                    "First argument is `{arg_name}`, which does not look like sensitive \
                     data; suggests non-security use."
                ),
            });
        }
    }

    if evidence.result_truncated {
        sum += W_RESULT_TRUNCATED;
        reasons.push(PredictionReason {
            kind: PredictionReasonKind::StructuralPattern {
                description: "result truncated to [:N]".to_string(),
            },
            weight: W_RESULT_TRUNCATED,
            note: "Truncating the digest discards bits; suggests use as a short \
                   identifier rather than a cryptographic hash."
                .to_string(),
        });
    }

    if evidence.input_includes_urandom {
        sum += W_INPUT_INCLUDES_URANDOM;
        reasons.push(PredictionReason {
            kind: PredictionReasonKind::StructuralPattern {
                description: "input includes os.urandom".to_string(),
            },
            weight: W_INPUT_INCLUDES_URANDOM,
            note: "Hashing entropy from `os.urandom` is consistent with nonce or \
                   key-id derivation, not data integrity."
                .to_string(),
        });
    }

    // ── Step 3: tiebreak + severity mapping. ──
    let predicted = if sum > 0.0 {
        BranchLabel::Benign
    } else {
        // Strict 0.0 tiebreak: lean RealBug. Documented in scorer docs.
        BranchLabel::RealBug
    };

    build_prediction(predicted, algo_label, reasons, Vec::new())
}

// ─────────────────────────────────────────────────────────────────────────────
// Helpers
// ─────────────────────────────────────────────────────────────────────────────

fn matches_auth_protocol_class(name: &str) -> bool {
    let lower = name.to_lowercase();
    AUTH_PROTOCOL_CLASS_SUBSTRINGS
        .iter()
        .any(|sub| lower.contains(sub))
}

fn matches_sensitive_ident(name: &str) -> bool {
    let lower = name.to_lowercase();
    SENSITIVE_IDENT_SUBSTRINGS
        .iter()
        .any(|sub| lower.contains(sub))
}

/// Construct a Prediction for a fully-collapsed Benign case.
fn collapse_to_benign(
    algo_label: &str,
    resolution: ResolutionSignal,
    reason: PredictionReason,
) -> Prediction {
    build_prediction(
        BranchLabel::Benign,
        algo_label,
        vec![reason],
        vec![resolution],
    )
}

/// Build the Prediction struct given the chosen branch and reasons.
///
/// Centralized so the predicted/alternative text and severity mapping
/// live in one place.
fn build_prediction(
    predicted: BranchLabel,
    algo_label: &str,
    reasons: Vec<PredictionReason>,
    resolutions: Vec<ResolutionSignal>,
) -> Prediction {
    let predicted_severity = severity_for_branch(predicted);
    let alternative_label = predicted.opposite();
    let alternative_severity = severity_for_branch(alternative_label);

    let alternative_branch = AlternativeBranch {
        label: alternative_label,
        severity: alternative_severity,
        title: title_for_branch(alternative_label, algo_label),
        description: description_for_branch(alternative_label, algo_label),
        suggested_fix: suggested_fix_for_branch(alternative_label, algo_label),
    };

    Prediction {
        predicted,
        alternative_branch,
        predicted_severity,
        reasons,
        resolutions,
    }
}

/// Map a branch to the severity used in the rendered Finding.
fn severity_for_branch(label: BranchLabel) -> Severity {
    match label {
        BranchLabel::RealBug => Severity::High,
        BranchLabel::Benign => Severity::Info,
    }
}

fn title_for_branch(label: BranchLabel, algo_label: &str) -> String {
    match label {
        BranchLabel::RealBug => format!("Weak hash algorithm ({algo_label})"),
        BranchLabel::Benign => {
            format!("Non-security use of {algo_label} (informational)")
        }
    }
}

fn description_for_branch(label: BranchLabel, algo_label: &str) -> String {
    match label {
        BranchLabel::RealBug => format!(
            "{algo_label} is cryptographically broken. If this call is protecting \
             security-sensitive data (passwords, signatures, integrity), it must be \
             replaced with SHA-256+ or a password-hashing function (Argon2/scrypt)."
        ),
        BranchLabel::Benign => format!(
            "{algo_label} appears to be used for a non-security purpose (cache key, \
             nonce, identifier, or protocol-required computation). The algorithm's \
             cryptographic weakness is irrelevant in this context, but the call is \
             carried as an alternative interpretation in case the predictor is wrong."
        ),
    }
}

fn suggested_fix_for_branch(label: BranchLabel, algo_label: &str) -> Option<String> {
    match label {
        BranchLabel::RealBug => Some(format!(
            "Replace `{algo_label}` with SHA-256, SHA-3, or BLAKE3. For password \
             hashing use Argon2 or scrypt."
        )),
        BranchLabel::Benign => Some(
            "If this is intentional non-security use, add `usedforsecurity=False` \
             (Python 3.9+) or annotate `# repotoire: protocol-required[<RFC>]` to \
             collapse the finding to Info."
                .to_string(),
        ),
    }
}

// ─────────────────────────────────────────────────��───────────────────────────
// Annotation lookup helper (called by evidence extraction)
// ─────────────────────────────────────────────────────────────────────────────

/// If `line` carries a `# repotoire: protocol-required[<rfc>]`
/// annotation, return the RFC string. Other annotations are ignored.
///
/// Defaults to `"unknown"` if no RFC arg was supplied.
pub(super) fn extract_protocol_required_rfc(line: &str) -> Option<String> {
    let ann = parse_python_comment(line)?;
    if ann.kind != "protocol-required" {
        return None;
    }
    if ann.args.is_empty() {
        Some("unknown".to_string())
    } else {
        Some(ann.args[0].clone())
    }
}

// ─────────────────────────────────────────────────────────────────────────────
// Tests
// ─────────────────────────────────────────────────────────────────────────────

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

    // ── Worked example sanity ──

    #[test]
    fn worked_example_sums_to_design_doc_82_percent() {
        // The design doc's worked example: enclosing class DigestAuth,
        // first arg `s` (non-sensitive), result truncated, input includes
        // urandom. Sum should be 0.40 + 0.20 + 0.15 + 0.07 = 0.82.
        let ev = Evidence {
            enclosing_class: Some("DigestAuth".to_string()),
            enclosing_function: Some("_get_client_nonce".to_string()),
            first_arg_ident: Some("s".to_string()),
            result_truncated: true,
            input_includes_urandom: true,
            usedforsecurity_false: false,
            protocol_required_annotation: None,
        };
        let pred = predict(&ev, "SHA1");
        assert_eq!(pred.predicted, BranchLabel::Benign);
        assert_eq!(pred.predicted_severity, Severity::Info);
        let sum: f32 = pred.reasons.iter().map(|r| r.weight).sum();
        // f32 sum may be 0.8200001 etc. Compare with epsilon.
        assert!(
            (sum - 0.82).abs() < 0.001,
            "expected sum ~= 0.82 (design doc), got {sum}"
        );
        // Four reasons, in scoring order.
        assert_eq!(pred.reasons.len(), 4);
    }

    // ── Collapsing signals ──

    #[test]
    fn usedforsecurity_false_collapses_to_benign() {
        let ev = Evidence {
            usedforsecurity_false: true,
            // Even with sensitive arg name, the kwarg wins.
            first_arg_ident: Some("password".to_string()),
            ..Evidence::empty()
        };
        let pred = predict(&ev, "MD5");
        assert_eq!(pred.predicted, BranchLabel::Benign);
        assert_eq!(pred.predicted_severity, Severity::Info);
        // No weighted reasons should appear; only the collapsing reason.
        assert_eq!(pred.reasons.len(), 1);
        assert_eq!(pred.reasons[0].weight, 1.0);
        // And exactly one resolution signal.
        assert_eq!(pred.resolutions.len(), 1);
        match &pred.resolutions[0].kind {
            ResolutionKind::KeywordArgument { name, value } => {
                assert_eq!(name, "usedforsecurity");
                assert_eq!(value, "False");
            }
            other => panic!("unexpected resolution kind: {other:?}"),
        }
    }

    #[test]
    fn protocol_required_annotation_collapses_to_benign() {
        let ev = Evidence {
            protocol_required_annotation: Some("RFC7616".to_string()),
            // Even with sensitive arg name, the annotation wins.
            first_arg_ident: Some("password".to_string()),
            ..Evidence::empty()
        };
        let pred = predict(&ev, "SHA1");
        assert_eq!(pred.predicted, BranchLabel::Benign);
        assert_eq!(pred.resolutions.len(), 1);
        match &pred.resolutions[0].kind {
            ResolutionKind::SourceAnnotation { syntax } => {
                assert!(syntax.contains("RFC7616"));
                assert!(syntax.starts_with("# repotoire:"));
            }
            other => panic!("unexpected resolution kind: {other:?}"),
        }
    }

    // ── 2x2 fixture matrix from decisions doc ──

    #[test]
    fn matrix_predicted_benign_actual_benign() {
        // DigestAuth._get_client_nonce — the real HTTPX case.
        // Reused from worked_example test, but asserts the matrix cell.
        let ev = Evidence {
            enclosing_class: Some("DigestAuth".to_string()),
            enclosing_function: Some("_get_client_nonce".to_string()),
            first_arg_ident: Some("s".to_string()),
            result_truncated: true,
            input_includes_urandom: true,
            ..Evidence::empty()
        };
        let pred = predict(&ev, "SHA1");
        assert_eq!(pred.predicted, BranchLabel::Benign);
    }

    #[test]
    fn matrix_predicted_benign_actual_realbug_synthetic() {
        // The "DigestAuthBug" case: auth class name (looks benign) but
        // the first arg is `password` (sensitive). The lexicon hit is
        // -0.40, AuthClass is +0.40, sum is 0.0 — tiebreak is RealBug.
        // This is the expected behavior: when signals contradict, we
        // err toward RealBug.
        let ev = Evidence {
            enclosing_class: Some("DigestAuthBug".to_string()),
            first_arg_ident: Some("password".to_string()),
            ..Evidence::empty()
        };
        let pred = predict(&ev, "MD5");
        assert_eq!(
            pred.predicted,
            BranchLabel::RealBug,
            "auth-class + sensitive-arg should tie at 0 and tiebreak RealBug"
        );
    }

    #[test]
    fn matrix_predicted_realbug_actual_benign_synthetic() {
        // `def cache_key(self, s)`: no auth class, no truncation, no
        // urandom. First arg `s` is non-sensitive (+0.20). Sum = 0.20,
        // predicted Benign. To make this predict RealBug as the matrix
        // requires, we need to remove the non-sensitive bonus, which
        // happens when the first arg is NOT a bare identifier (e.g.
        // `hashlib.sha1(s + nonce)` — first_arg_ident = None).
        let ev = Evidence {
            enclosing_class: None,
            enclosing_function: Some("cache_key".to_string()),
            first_arg_ident: None, // non-identifier expression
            ..Evidence::empty()
        };
        let pred = predict(&ev, "SHA1");
        assert_eq!(
            pred.predicted,
            BranchLabel::RealBug,
            "no signals at all should tiebreak RealBug"
        );
    }

    #[test]
    fn matrix_predicted_realbug_actual_realbug() {
        // hash_password(pw): function name in auth lexicon doesn't
        // help (we score on class), arg name "pw" doesn't match
        // sensitive lexicon literally (it's substring; "pw" doesn't
        // contain "password"). Use "pwd" which IS a substring? No,
        // "pwd" doesn't contain "password" either. Use literally
        // "password".
        let ev = Evidence {
            enclosing_function: Some("hash_password".to_string()),
            first_arg_ident: Some("password".to_string()),
            ..Evidence::empty()
        };
        let pred = predict(&ev, "MD5");
        assert_eq!(pred.predicted, BranchLabel::RealBug);
        assert_eq!(pred.predicted_severity, Severity::High);
    }

    // ── Lexicon matchers ──

    #[test]
    fn sensitive_lexicon_substring_matches() {
        assert!(matches_sensitive_ident("password"));
        assert!(matches_sensitive_ident("user_password"));
        assert!(matches_sensitive_ident("USER_PASSWORD")); // case insensitive
        assert!(matches_sensitive_ident("api_key"));
        assert!(matches_sensitive_ident("session_token"));
        assert!(!matches_sensitive_ident("s"));
        assert!(!matches_sensitive_ident("data"));
        assert!(!matches_sensitive_ident("nonce"));
    }

    #[test]
    fn auth_protocol_class_matches() {
        assert!(matches_auth_protocol_class("DigestAuth"));
        assert!(matches_auth_protocol_class("HTTPDigestAuth"));
        assert!(matches_auth_protocol_class("digestauth")); // case insensitive
        assert!(!matches_auth_protocol_class("MyHasher"));
        assert!(!matches_auth_protocol_class("HmacBuilder"));
    }

    // ── Alternative branch shape ──

    #[test]
    fn predicted_benign_carries_realbug_alternative() {
        let ev = Evidence {
            enclosing_class: Some("DigestAuth".to_string()),
            first_arg_ident: Some("s".to_string()),
            result_truncated: true,
            input_includes_urandom: true,
            ..Evidence::empty()
        };
        let pred = predict(&ev, "SHA1");
        assert_eq!(pred.predicted, BranchLabel::Benign);
        assert_eq!(pred.alternative_branch.label, BranchLabel::RealBug);
        assert_eq!(pred.alternative_branch.severity, Severity::High);
        assert!(pred.alternative_branch.title.contains("Weak hash"));
    }

    #[test]
    fn predicted_realbug_carries_benign_alternative() {
        let ev = Evidence {
            first_arg_ident: Some("password".to_string()),
            ..Evidence::empty()
        };
        let pred = predict(&ev, "MD5");
        assert_eq!(pred.predicted, BranchLabel::RealBug);
        assert_eq!(pred.alternative_branch.label, BranchLabel::Benign);
        assert_eq!(pred.alternative_branch.severity, Severity::Info);
    }

    // ── Empty evidence (nothing extractable) ──

    #[test]
    fn empty_evidence_predicts_realbug() {
        let pred = predict(&Evidence::empty(), "MD5");
        assert_eq!(
            pred.predicted,
            BranchLabel::RealBug,
            "with no evidence we lean conservative"
        );
        assert!(pred.reasons.is_empty());
    }

    // ── Annotation extraction helper ──

    #[test]
    fn extracts_protocol_required_rfc() {
        assert_eq!(
            extract_protocol_required_rfc("h.sha1(s)  # repotoire: protocol-required[RFC7616]"),
            Some("RFC7616".to_string()),
        );
    }

    #[test]
    fn extract_protocol_required_defaults_when_no_rfc() {
        assert_eq!(
            extract_protocol_required_rfc("h.sha1(s)  # repotoire: protocol-required"),
            Some("unknown".to_string()),
        );
        assert_eq!(
            extract_protocol_required_rfc("h.sha1(s)  # repotoire: protocol-required[]"),
            Some("unknown".to_string()),
        );
    }

    #[test]
    fn extract_protocol_required_ignores_other_kinds() {
        assert_eq!(
            extract_protocol_required_rfc("h.sha1(s)  # repotoire: low-entropy[md5]"),
            None,
        );
        assert_eq!(extract_protocol_required_rfc("h.sha1(s)  # noqa"), None,);
    }
}