aprender_contracts_cli/commands/

lint.rs

use std::path::Path;

use provable_contracts::lint::config::{find_config, load_config};
use provable_contracts::lint::rules::RuleSeverity;
use provable_contracts::lint::shapes_gate::ShapesOptions;
use provable_contracts::lint::trend;
use provable_contracts::lint::{run_lint, GateDetail, LintConfig, LintReport};
use provable_contracts::ontology::verdict::Verdict;

use crate::contract_walk::{LintDeclined, LintRejected, ZeroContracts};

#[path = "lint_render.rs"]
mod lint_render;

#[path = "lint_html.rs"]
mod lint_html;

#[path = "lint_arming.rs"]
mod lint_arming;

/// Print long-form explanation for a lint rule.
pub fn explain_rule(rule_id: &str) {
    lint_render::print_explain(rule_id);
}

#[allow(clippy::too_many_arguments, clippy::fn_params_excessive_bools)]
pub fn run(
    contract_dir: &Path,
    binding_path: Option<&Path>,
    min_score: f64,
    format: Option<&str>,
    severity: Option<&str>,
    strict: bool,
    suppress: Option<&str>,
    suppress_rule: Option<&str>,
    suppress_file: Option<&str>,
    rule_overrides: &[String],
    config_path: Option<&Path>,
    diff_ref: Option<&str>,
    do_trend: bool,
    show_trend: bool,
    no_cache: bool,
    cache_stats: bool,
    coverage: bool,
    min_coverage: Option<f64>,
    crate_dir: Option<&Path>,
    min_level: Option<&str>,
    watch: bool,
    strict_test_binding: bool,
    armed_baseline_ref: Option<&str>,
    gate: Option<&str>,
    shapes_opts: ShapesOptions,
) -> Result<(), Box<dyn std::error::Error>> {
    refuse_missing_corpus(contract_dir)?;
    // Both preconditions before any dispatch: a single file under
    // --strict-test-binding is refused (this PR) whether or not --gate (ONT-6)
    // is asked for, because run_single_gate would otherwise report every ref
    // missing on exactly the input the refusal exists for.
    refuse_single_file_strict_binding(contract_dir, strict_test_binding)?;
    if let Some(name) = gate {
        return run_single_gate(contract_dir, name, &shapes_opts);
    }
    if watch {
        return run_watch(
            contract_dir,
            binding_path,
            min_score,
            format,
            severity,
            strict,
            suppress,
            suppress_rule,
            suppress_file,
            rule_overrides,
            config_path,
            no_cache,
            cache_stats,
            crate_dir,
            min_level,
            strict_test_binding,
        );
    }

    if show_trend {
        show_trend_history(contract_dir);
        return Ok(());
    }

    if let Some(base) = diff_ref {
        if let Some(result) = run_diff_check(contract_dir, base) {
            return result;
        }
    }

    let config = build_config(
        contract_dir,
        binding_path,
        min_score,
        format,
        severity,
        strict,
        suppress,
        suppress_rule,
        suppress_file,
        rule_overrides,
        config_path,
        no_cache,
        cache_stats,
        crate_dir,
        min_level,
        strict_test_binding,
    );

    // ONT-6 (PMAT-3451): the shrink check needs no lint run, so it refuses (exit 3) before one.
    let arming = lint_arming::resolve(contract_dir, armed_baseline_ref)?;

    let mut report = run_lint(&config);

    // PVL-1 (PMAT-1099): an EMPTY corpus is refused (exit 2) before any report is
    // printed — never `Result: PASS` over 0 contracts.
    refuse_empty_corpus(&report, contract_dir)?;

    report.arm(&arming.armed);
    report.armed_monotone = Some(arming.monotone);
    report.armed_shapes_monotone = Some(arming.shapes_monotone);

    if cache_stats {
        print_cache_stats(&report);
    }
    if do_trend {
        record_trend(contract_dir, &report);
    }

    let effective_format = resolve_format(format, config_path, contract_dir);
    print_report(&effective_format, &report)?;

    // --coverage: compute and print aggregate contract coverage metric
    if coverage {
        report_coverage(contract_dir, min_coverage)?;
    }

    meet_exit(&report)
}

/// `--coverage`: print the aggregate contract-coverage metric, and refuse below `--min-coverage`.
fn report_coverage(
    contract_dir: &Path,
    min_coverage: Option<f64>,
) -> Result<(), Box<dyn std::error::Error>> {
    let coverage_result = compute_contract_coverage(contract_dir);
    println!(
        "\nContract Coverage: {}/{} at Standard+ ({:.1}%)",
        coverage_result.standard_plus, coverage_result.total, coverage_result.percentage,
    );
    match min_coverage {
        Some(threshold) if coverage_result.percentage < threshold => Err(format!(
            "contract coverage {:.1}% is below minimum {:.1}%",
            coverage_result.percentage, threshold,
        )
        .into()),
        _ => Ok(()),
    }
}

/// aprender#3715: `--shape` and `--release-*` as the shapes gate's options. They mean something ONLY under
/// `--gate shapes`; anywhere else they are refused (exit 3), because a release flag that was silently ignored is
/// a release gate that silently did not run.
pub fn shapes_options(
    gate: Option<&str>,
    shape: Option<String>,
    release: &crate::cli::ReleaseArgs,
) -> Result<ShapesOptions, crate::contract_walk::ReleaseArgsRefused> {
    use crate::contract_walk::ReleaseArgsRefused;
    if (shape.is_some() || release.any()) && gate != Some("shapes") {
        return Err(ReleaseArgsRefused(
            "--shape and --release-* / --receipts* / --kernel-receipts / --dogfood-receipt apply only to \
             `--gate shapes`"
                .into(),
        ));
    }
    Ok(ShapesOptions {
        only: shape,
        release: release.subject().map_err(ReleaseArgsRefused)?,
    })
}

/// One gate's report. NOT a `LintReport`: `--gate` answers about one gate, and a reader must be able to tell the
/// two apart without counting keys.
#[derive(serde::Serialize)]
struct SingleGateReport<'a> {
    gate: &'a str,
    verdict: Verdict,
    passed: bool,
    duration_ms: u64,
    extra: Option<&'a provable_contracts::lint::GateExtra>,
    /// The same fields at the TOP level (ONT-4b): ONT-001 §5's probes read `.shapes_n`, `.focus_nodes_n`, `.pc_shape`,
    /// `.w3c_cases_passed` from the single-gate report directly, beside `.verdict` — the way `.gate` and `.verdict`
    /// already sit there. `extra` stays nested for anything that reads the structure; the flatten costs one `type` key.
    #[serde(flatten)]
    flat: Option<&'a provable_contracts::lint::GateExtra>,
    findings: Vec<SingleGateFinding<'a>>,
}

#[derive(serde::Serialize)]
struct SingleGateFinding<'a> {
    rule_id: &'a str,
    severity: String,
    message: &'a str,
    file: &'a str,
}

/// ONT-2b: `--gate <name>` runs ONE gate and reports only it, mapping its verdict through ONT-6's lattice —
/// Pass 0 · Fail 1 `reject:` · no Σ 2 `decline:` (R-2, zero is a decline) · malformed Σ 3 `error:`.
fn run_single_gate(
    contract_dir: &Path,
    name: &str,
    shapes_opts: &ShapesOptions,
) -> Result<(), Box<dyn std::error::Error>> {
    let (result, findings) = decide_named_gate(contract_dir, name, shapes_opts)?;

    let report = SingleGateReport {
        gate: &result.name,
        verdict: result.verdict,
        passed: result.passed,
        duration_ms: result.duration_ms,
        extra: result.extra.as_ref(),
        flat: result.extra.as_ref(),
        findings: findings
            .iter()
            .map(|f| SingleGateFinding {
                rule_id: &f.rule_id,
                severity: format!("{:?}", f.severity),
                message: &f.message,
                file: &f.file,
            })
            .collect(),
    };
    println!("{}", serde_json::to_string_pretty(&report)?);

    // The exit is the gate's VERDICT, not its `passed` bit: a gate that ran and answered `Unknown{Warn}` (ONT-4b, warnings
    // and no violation) is a decline, exit 2 — `passed` alone would print 0 for a corpus nobody judged clean.
    match result.verdict {
        provable_contracts::ontology::verdict::Verdict::Pass => Ok(()),
        provable_contracts::ontology::verdict::Verdict::Unknown(reason) => {
            Err(LintDeclined { reason }.into())
        }
        provable_contracts::ontology::verdict::Verdict::Fail => Err(LintRejected {
            passed: 0,
            armed: 1,
        }
        .into()),
    }
}

/// One gate's run, mapped to a report or to the refusal/decline that stands in its place. Every non-verdict
/// answer says WHY on stderr before it returns, because an exit code without a reason is the thing this gate
/// exists to refuse.
type NamedGateAnswer = (
    Box<provable_contracts::lint::GateResult>,
    Vec<provable_contracts::lint::finding::LintFinding>,
);

fn decide_named_gate(
    contract_dir: &Path,
    name: &str,
    shapes_opts: &ShapesOptions,
) -> Result<NamedGateAnswer, Box<dyn std::error::Error>> {
    use provable_contracts::lint::{
        relations_gate::RelationsOutcome, sigma_gate::SigmaOutcome, NamedGateOutcome, NAMED_GATES,
    };

    match provable_contracts::lint::run_named_gate_with(contract_dir, name, shapes_opts) {
        NamedGateOutcome::UnknownGate => Err(crate::contract_walk::UnknownGate {
            asked: name.to_string(),
            known: NAMED_GATES.iter().map(|g| (*g).to_string()).collect(),
        }
        .into()),
        NamedGateOutcome::Sigma(SigmaOutcome::NoSigma) => Err(LintDeclined {
            reason: provable_contracts::ontology::verdict::Reason::NoCheckable,
        }
        .into()),
        NamedGateOutcome::Sigma(SigmaOutcome::Malformed(e)) => {
            Err(crate::contract_walk::SigmaMalformed(e.to_string()).into())
        }
        NamedGateOutcome::Relations(
            RelationsOutcome::NoSigma | RelationsOutcome::NoRelations { .. },
        ) => Err(LintDeclined {
            reason: provable_contracts::ontology::verdict::Reason::NoCheckable,
        }
        .into()),
        NamedGateOutcome::Relations(RelationsOutcome::Malformed(e)) => {
            Err(crate::contract_walk::SigmaMalformed(e.to_string()).into())
        }
        NamedGateOutcome::Shapes(outcome) => decide_shapes_gate(outcome),
        NamedGateOutcome::Sigma(SigmaOutcome::Ran { result, findings })
        | NamedGateOutcome::Relations(RelationsOutcome::Ran { result, findings })
        | NamedGateOutcome::Ran { result, findings } => Ok((result, findings)),
    }
}

/// The `shapes` gate's answers (ONT-4b, ONT-4c1, ONT-4b2). Only `Ran` is a verdict about the corpus; every
/// other arm prints what could not be checked before it returns its decline or refusal.
fn decide_shapes_gate(
    outcome: provable_contracts::lint::shapes_gate::ShapesOutcome,
) -> Result<NamedGateAnswer, Box<dyn std::error::Error>> {
    use provable_contracts::lint::shapes_gate::ShapesOutcome;
    use provable_contracts::ontology::verdict::Reason;

    match outcome {
        ShapesOutcome::Unsupported(e) => {
            Err(crate::contract_walk::SigmaMalformed(e.to_string()).into())
        }
        ShapesOutcome::ExtractFailed(e) => {
            Err(crate::contract_walk::SigmaMalformed(e.to_string()).into())
        }
        ShapesOutcome::NoShapes { .. } => Err(LintDeclined {
            reason: Reason::NoShapes,
        }
        .into()),
        ShapesOutcome::NoFocus { .. } => Err(LintDeclined {
            reason: Reason::NoFocus,
        }
        .into()),
        ShapesOutcome::WrongCorpus {
            shapes_n,
            expected,
            found,
            refused,
        } => {
            eprintln!(
                "shapes: extract:parity-receipt matched {found} focus node(s);                  evidence/parity/EXPECTED_RECEIPTS says {expected} ({shapes_n} shape(s))"
            );
            for r in &refused {
                eprintln!("shapes: refused {r}");
            }
            Err(LintDeclined {
                reason: Reason::WrongCorpus,
            }
            .into())
        }
        ShapesOutcome::NoReceipts { shapes_n, dir } => {
            // ONT-4c1: the WHY travels with the decline — the lattice has no ReceiptUnmeasured element (ONT-6's
            // 15 reasons), so the reason is NoCheckable and this line says what could not be checked.
            eprintln!(
                "shapes: {shapes_n} shape(s) resolve receipts and the tree holds none under {dir}/"
            );
            Err(LintDeclined {
                reason: Reason::NoCheckable,
            }
            .into())
        }
        ShapesOutcome::PositiveControlFailed { which, .. } => {
            eprintln!("shapes: positive control {which} did not fire");
            Err(LintDeclined {
                reason: Reason::PositiveControlFailed,
            }
            .into())
        }
        ShapesOutcome::Differential {
            passed, n, failed, ..
        } => {
            // ONT-4b2: the validator failed a vendored W3C case for a form it claims — no corpus verdict.
            eprintln!(
                "shapes: W3C SHACL-Core differential — {passed} of {n} vendored case(s) pass"
            );
            for f in &failed {
                eprintln!("  {f}");
            }
            Err(LintDeclined {
                reason: Reason::Differential,
            }
            .into())
        }
        ShapesOutcome::Ran { result, findings } => Ok((result, findings)),
    }
}

/// ONT-001 §3.4: the exit is the armed meet — Pass 0, Fail 1 (`reject:`), Unknown 2 (`decline: <reason>`).
/// `report.passed` (every gate passed or skipped) no longer decides it: a skipped armed gate is not a pass.
fn meet_exit(report: &LintReport) -> Result<(), Box<dyn std::error::Error>> {
    match report.verdict {
        Verdict::Pass => Ok(()),
        Verdict::Fail => Err(LintRejected {
            passed: report
                .armed_gates
                .iter()
                .filter(|g| g.verdict == Verdict::Pass)
                .count(),
            armed: report.armed_gates.len(),
        }
        .into()),
        Verdict::Unknown(reason) => Err(LintDeclined { reason }.into()),
    }
}

/// PVL-1 (PMAT-1099): the corpus is EMPTY when the gate NAMED `validate` counted
/// nothing. Only that gate carries the count (parsed + parse errors):
/// `duplicate-stems` reuses the `Validate` detail shape with zeros as a
/// placeholder, so a shape-only match refused every VALID corpus — measured:
/// one valid contract was refused while an invalid fixture, whose later gates
/// are skipped, was counted. A corpus whose files all fail to parse is NOT
/// empty (errors > 0): it was measured, and fails at exit 1.
fn refuse_empty_corpus(report: &LintReport, contract_dir: &Path) -> Result<(), ZeroContracts> {
    let empty = report.gates.iter().any(|g| {
        g.name == "validate"
            && matches!(
                g.detail,
                GateDetail::Validate {
                    contracts: 0,
                    errors: 0,
                    ..
                }
            )
    });
    if empty {
        return Err(ZeroContracts {
            path: contract_dir.to_path_buf(),
            filter: None,
        });
    }
    Ok(())
}

struct CoverageResult {
    standard_plus: usize,
    total: usize,
    percentage: f64,
}

/// Count contracts at `Standard+` level (have both `falsification_tests` AND `kani_harnesses`).
fn compute_contract_coverage(contract_dir: &Path) -> CoverageResult {
    let mut total = 0usize;
    let mut standard_plus = 0usize;

    let mut yaml_paths = Vec::new();
    collect_yaml_files_lint(contract_dir, &mut yaml_paths);

    for path in &yaml_paths {
        let Ok(contract) = provable_contracts::schema::parse_contract(path) else {
            continue;
        };
        // Coverage is a kernel-contract metric. Skip registries,
        // model-family schemas, pattern contracts, and reference documents.
        if !contract.requires_proofs() {
            continue;
        }
        total += 1;
        if !contract.falsification_tests.is_empty() && !contract.kani_harnesses.is_empty() {
            standard_plus += 1;
        }
    }

    #[allow(clippy::cast_precision_loss)]
    let percentage = if total > 0 {
        (standard_plus as f64 / total as f64) * 100.0
    } else {
        100.0
    };

    CoverageResult {
        standard_plus,
        total,
        percentage,
    }
}

fn show_trend_history(contract_dir: &Path) {
    let trend_root = trend::trend_dir(contract_dir);
    let snapshots = trend::load_snapshots(&trend_root);
    if snapshots.is_empty() {
        println!("No trend data. Run `pv lint --trend` to record snapshots.");
    } else {
        println!("{}", trend::format_trend(&snapshots, 30));
    }
}

/// Returns `Some(Ok(()))` to short-circuit when no contracts changed,
/// or `None` to continue with full lint.
/// PVL-1 (PMAT-1099): refuse an empty corpus BEFORE anything touches the tree —
/// the `.pv` cache directory, the diff probe, the watcher. The third review
/// quorum on #3093 measured `pv lint /nonexistent` leaking `cannot create /.pv:
/// Permission denied` AHEAD of the refusal: two stderr lines for one decline,
/// three under `--diff`. `has_contract_files` does not parse; the post-report
/// guard in `run` stays for a corpus that parses to nothing.
/// `pv lint <one-file> --strict-test-binding` REFUSES rather than reporting a
/// false negative (#3347).
///
/// The gate resolves cited test names against a source index rooted at the
/// contract path's PARENT. For the directory form that parent is the repo
/// root and the index finds `crates/`; for a single file it is `contracts/`,
/// which holds no source at all, so every cited ref resolves to nothing and
/// every one is reported missing.
///
/// Measured on `contracts/pv-artifact-kinds-v1.yaml`, a contract whose eight
/// refs all resolve:
///
/// ```text
/// pv lint contracts/pv-artifact-kinds-v1.yaml --strict-test-binding
///     total_refs 8, existing 0, missing 8
/// pv lint contracts/ --strict-test-binding
///     total_refs 548, existing 521, missing 27   <- and none of the 27 is this contract
/// ```
///
/// A control contract failing identically to a broken one is the definition
/// of a gate that cannot discriminate, so the single-file form is refused.
///
/// REFUSED rather than repaired: the scan root is computed inside
/// `provable_contracts::lint`, which this ticket does not own. A refusal is
/// in the caller, is honest, and cannot be mistaken for a clean bill.
///
/// Exit 1, not the exit-2 `decline:` class: exit 2 belongs to `ZeroContracts`
/// and its message ("0 contracts under ...") would be false here -- there IS
/// a contract, it is the gate that cannot run over it.
fn refuse_single_file_strict_binding(
    path: &Path,
    strict_test_binding: bool,
) -> Result<(), Box<dyn std::error::Error>> {
    if !strict_test_binding || !path.is_file() {
        return Ok(());
    }
    let dir = path.parent().unwrap_or(Path::new("contracts"));
    Err(format!(
        "--strict-test-binding cannot run over a single contract file ({}): \
         the gate resolves cited test names against a source tree rooted at \
         that file's parent directory, which holds contracts and no source, \
         so every reference would be reported missing -- including those that \
         do resolve. Run the directory form instead: \
         `pv lint {} --strict-test-binding`.",
        path.display(),
        dir.display(),
    )
    .into())
}

fn refuse_missing_corpus(contract_dir: &Path) -> Result<(), Box<dyn std::error::Error>> {
    if crate::contract_walk::has_contract_files(contract_dir) {
        return Ok(());
    }
    Err(crate::contract_walk::ZeroContracts {
        path: contract_dir.to_path_buf(),
        filter: None,
    }
    .into())
}

fn run_diff_check(
    contract_dir: &Path,
    base: &str,
) -> Option<Result<(), Box<dyn std::error::Error>>> {
    match provable_contracts::lint::diff::changed_contracts(contract_dir, base) {
        Ok(changed) if changed.is_empty() => {
            // PVL-1 (PMAT-1099): "nothing changed" over 0 contracts is the vacuous
            // pass again — refuse a corpus with no contract file (exit 2) before
            // saying so; the probe does not parse (nothing changed = fast path).
            if !crate::contract_walk::has_contract_files(contract_dir) {
                return Some(Err(crate::contract_walk::ZeroContracts {
                    path: contract_dir.to_path_buf(),
                    filter: None,
                }
                .into()));
            }
            println!("No contracts changed since {base}. Nothing to lint.");
            Some(Ok(()))
        }
        Ok(changed) => {
            println!(
                "Diff-aware: {} contracts changed since {base}",
                changed.len()
            );
            for stem in &changed {
                println!("  {stem}");
            }
            println!();
            None
        }
        Err(e) => {
            eprintln!("Warning: diff-aware mode failed ({e}), linting all contracts");
            None
        }
    }
}

fn print_cache_stats(report: &LintReport) {
    eprintln!(
        "Cache: {} total, {} hits, {} misses ({:.0}% hit rate)",
        report.cache_stats.total,
        report.cache_stats.hits,
        report.cache_stats.misses,
        report.cache_stats.hit_rate() * 100.0,
    );
}

fn record_trend(contract_dir: &Path, report: &LintReport) {
    let trend_root = trend::trend_dir(contract_dir);
    let contracts_count = count_contracts(report);
    match trend::record_snapshot(&trend_root, report, contracts_count) {
        Ok(path) => eprintln!("Trend snapshot saved: {}", path.display()),
        Err(e) => eprintln!("Warning: failed to save trend snapshot: {e}"),
    }
    let snapshots = trend::load_snapshots(&trend_root);
    if let Some(drop) = trend::detect_drift(&snapshots, 0.05) {
        eprintln!("Warning: quality drift detected (score dropped {drop:.3})");
    }
}

fn print_report(format: &str, report: &LintReport) -> Result<(), Box<dyn std::error::Error>> {
    match format {
        "json" => lint_render::print_json(report)?,
        "sarif" => lint_render::print_sarif(report),
        "github" => lint_render::print_github(report),
        "html" => println!("{}", lint_html::render_html(report)),
        _ => lint_render::print_text(report),
    }
    Ok(())
}

fn count_contracts(report: &LintReport) -> usize {
    for gate in &report.gates {
        match &gate.detail {
            GateDetail::Validate { contracts, .. }
            | GateDetail::Audit { contracts, .. }
            | GateDetail::Score { contracts, .. } => return *contracts,
            GateDetail::Verify { .. }
            | GateDetail::Enforce { .. }
            | GateDetail::ReverseCoverage { .. }
            | GateDetail::Composition { .. }
            | GateDetail::Skipped { .. } => {}
        }
    }
    0
}

/// Watch mode: polling-based re-lint every 5 seconds.
#[allow(clippy::too_many_arguments, clippy::fn_params_excessive_bools)]
fn run_watch(
    contract_dir: &Path,
    binding_path: Option<&Path>,
    min_score: f64,
    format: Option<&str>,
    severity: Option<&str>,
    strict: bool,
    suppress: Option<&str>,
    suppress_rule: Option<&str>,
    suppress_file: Option<&str>,
    rule_overrides: &[String],
    config_path: Option<&Path>,
    no_cache: bool,
    cache_stats: bool,
    crate_dir: Option<&Path>,
    min_level: Option<&str>,
    strict_test_binding: bool,
) -> Result<(), Box<dyn std::error::Error>> {
    loop {
        let config = build_config(
            contract_dir,
            binding_path,
            min_score,
            format,
            severity,
            strict,
            suppress,
            suppress_rule,
            suppress_file,
            rule_overrides,
            config_path,
            no_cache,
            cache_stats,
            crate_dir,
            min_level,
            strict_test_binding,
        );

        let mut report = run_lint(&config);

        // PVL-1 (PMAT-1099): watch mode is the same gate on a timer — an empty
        // corpus is refused (exit 2) at the first tick, never reported over.
        refuse_empty_corpus(&report, contract_dir)?;
        // ONT-6: the declared arming, re-read each tick; the monotone check is a one-shot run's job.
        report.arm(&lint_arming::declared(contract_dir)?);

        if cache_stats {
            print_cache_stats(&report);
        }

        let effective_format = resolve_format(format, config_path, contract_dir);
        print_report(&effective_format, &report)?;

        println!("\n--- Watching for changes (Ctrl+C to stop) ---\n");
        std::thread::sleep(std::time::Duration::from_secs(5));
    }
}

fn resolve_format(format: Option<&str>, config_path: Option<&Path>, contract_dir: &Path) -> String {
    // CLI flag takes precedence when explicitly set
    if let Some(f) = format {
        return f.to_string();
    }
    // Fall back to config file
    let pv_config = config_path
        .and_then(|cp| load_config(cp).ok())
        .or_else(|| find_config(contract_dir).and_then(|p| load_config(&p).ok()))
        .unwrap_or_default();
    pv_config.output.format.unwrap_or_else(|| "text".into())
}

#[allow(clippy::too_many_arguments, clippy::fn_params_excessive_bools)]
fn build_config<'a>(
    contract_dir: &'a Path,
    binding_path: Option<&'a Path>,
    min_score: f64,
    _format: Option<&str>,
    severity: Option<&str>,
    strict: bool,
    suppress: Option<&str>,
    suppress_rule: Option<&str>,
    suppress_file: Option<&str>,
    rule_overrides: &[String],
    config_path: Option<&Path>,
    no_cache: bool,
    cache_stats: bool,
    crate_dir: Option<&'a Path>,
    min_level: Option<&str>,
    strict_test_binding: bool,
) -> LintConfig<'a> {
    let pv_config = config_path
        .and_then(|cp| match load_config(cp) {
            Ok(c) => {
                if c.lint.min_score.is_none()
                    && !c.lint.strict
                    && c.lint.severity.is_none()
                    && c.lint.rules.is_empty()
                    && c.output.format.is_none()
                {
                    eprintln!(
                        "Warning: config {} parsed but no lint settings found",
                        cp.display()
                    );
                }
                Some(c)
            }
            Err(e) => {
                eprintln!("Warning: failed to load config {}: {e}", cp.display());
                None
            }
        })
        .or_else(|| find_config(contract_dir).and_then(|p| load_config(&p).ok()))
        .unwrap_or_default();

    let effective_min_score = if min_score > 0.0 {
        min_score
    } else {
        pv_config.lint.min_score.unwrap_or(0.0)
    };

    let severity_filter = severity
        .or(pv_config.lint.severity.as_deref())
        .and_then(RuleSeverity::from_str_opt);

    let effective_strict = strict || pv_config.lint.strict;

    let suppressed_findings: Vec<String> = parse_csv(suppress)
        .into_iter()
        .chain(pv_config.lint.suppress.findings.iter().cloned())
        .collect();
    let suppressed_rules: Vec<String> = parse_csv(suppress_rule)
        .into_iter()
        .chain(pv_config.lint.suppress.rules.iter().cloned())
        .collect();
    let suppressed_files: Vec<String> = parse_csv(suppress_file)
        .into_iter()
        .chain(pv_config.lint.suppress.files.iter().cloned())
        .collect();

    let mut severity_overrides = std::collections::HashMap::new();
    for entry in &pv_config.lint.rules {
        if let Some(sev) = RuleSeverity::from_str_opt(entry.1) {
            severity_overrides.insert(entry.0.clone(), sev);
        }
    }
    for r in rule_overrides {
        if let Some((id, sev_str)) = r.split_once('=') {
            if let Some(sev) = RuleSeverity::from_str_opt(sev_str) {
                severity_overrides.insert(id.to_string(), sev);
            }
        }
    }

    LintConfig {
        contract_dir,
        binding_path,
        min_score: effective_min_score,
        severity_filter,
        severity_overrides,
        suppressed_findings,
        suppressed_rules,
        suppressed_files,
        strict: effective_strict,
        no_cache,
        cache_stats,
        crate_dir,
        min_level: min_level.and_then(parse_enforcement_level),
        strict_test_binding,
    }
}

fn parse_enforcement_level(s: &str) -> Option<provable_contracts::schema::EnforcementLevel> {
    use provable_contracts::schema::EnforcementLevel;
    match s.to_lowercase().as_str() {
        "basic" => Some(EnforcementLevel::Basic),
        "standard" => Some(EnforcementLevel::Standard),
        "strict" => Some(EnforcementLevel::Strict),
        "proven" => Some(EnforcementLevel::Proven),
        _ => None,
    }
}

fn parse_csv(s: Option<&str>) -> Vec<String> {
    s.map(|v| {
        v.split(',')
            .map(|s| s.trim().to_string())
            .filter(|s| !s.is_empty())
            .collect()
    })
    .unwrap_or_default()
}

/// Recursively collect `.yaml` contract files, skipping non-contract directories.
fn collect_yaml_files_lint(dir: &std::path::Path, out: &mut Vec<std::path::PathBuf>) {
    let Ok(entries) = std::fs::read_dir(dir) else {
        return;
    };
    for entry in entries.flatten() {
        let path = entry.path();
        if path.is_dir() {
            let dirname = path.file_name().and_then(|n| n.to_str()).unwrap_or("");
            if dirname == "kaizen" || dirname == "legacy" || dirname == "pipelines" {
                continue;
            }
            collect_yaml_files_lint(&path, out);
        } else if path.extension().and_then(|e| e.to_str()) == Some("yaml")
            && !matches!(
                path.file_name().and_then(|n| n.to_str()),
                Some("binding.yaml" | "binding.yml")
            )
        {
            out.push(path);
        }
    }
}