testing_conventions/

lib.rs

pub mod agents;
pub mod co_change;
pub mod colocated_test;
pub mod config;
pub mod coverage;
pub mod e2e;
pub mod isolation;
pub mod lint;
pub mod mutation;
pub mod packaging;
pub mod patch_coverage;
pub mod tiers;
pub mod ts;
pub mod violation;
pub mod workflow;

use std::path::{Path, PathBuf};

use clap::{CommandFactory, Parser, Subcommand};

#[derive(Parser, Debug)]
#[command(
    name = "testing-conventions",
    version,
    about = "Enforce testing conventions in libraries (Python, TypeScript, and Rust).",
    long_about = None,
)]
pub struct Cli {
    #[command(subcommand)]
    command: Option<Command>,
}

#[derive(Subcommand, Debug)]
enum Command {
    /// Check the repository against its testing-conventions config.
    Check,
    /// Write the testing contract into the repository's agent context file:
    /// a marker-delimited, hash-versioned block in `AGENTS.md` that a
    /// coding agent reads before writing code. Idempotent — re-running
    /// refreshes the owned region and touches nothing outside it.
    Install {
        /// The agent context file to manage.
        #[arg(default_value = "AGENTS.md")]
        path: PathBuf,
    },
    /// Unit-test conventions.
    Unit {
        #[command(subcommand)]
        rule: UnitRule,
    },
    /// Integration-test conventions.
    Integration {
        #[command(subcommand)]
        rule: IntegrationRule,
    },
    /// Packaging conventions: test files must not ship in the built artifact.
    Packaging {
        /// Root of the built artifact to inspect (e.g. an unpacked wheel or `dist/`).
        path: PathBuf,
        /// Language convention to enforce (required).
        #[arg(long, value_enum)]
        language: colocated_test::Language,
    },
    /// Workflow guard (private — hidden from `--help`): every `testing-conventions`
    /// invocation in a CI workflow must name a subcommand this binary still exposes
    /// (guards the `@v0` path). Run from our own CI, not a documented consumer command;
    /// it stays in the binary because the guard needs the in-process command tree.
    #[command(hide = true)]
    Workflow {
        /// Workflow file (or a directory of them) to scan.
        path: PathBuf,
    },
    /// End-to-end-test conventions.
    E2e {
        #[command(subcommand)]
        command: E2eCommand,
    },
}

/// Rules enforced on the unit-test suite (the README's "Unit" taxonomy).
#[derive(Subcommand, Debug)]
enum UnitRule {
    /// Check that every source file has a colocated, matching-named unit test
    /// (tree-wide presence). With `--base`, additionally run the commit-scoped
    /// `co-change` check over `<base>...HEAD`: a modified or deleted source
    /// whose colocated test is not in the diff fails. Presence always runs;
    /// `--base` *adds* the diff-scoped check.
    ColocatedTest {
        /// Directory to scan recursively.
        path: PathBuf,
        /// Language convention to enforce (required).
        #[arg(long, value_enum)]
        language: colocated_test::Language,
        /// Opt-in commit-scoped co-change check: diff `<base>...HEAD` and
        /// also flag a modified or deleted source whose colocated test didn't
        /// co-change. Absent means presence-only — there is no default. Python /
        /// TypeScript only: `--base --language rust` is rejected (inline
        /// `#[cfg(test)]` units have no sibling test to go stale).
        #[arg(long)]
        base: Option<String>,
        /// testing-conventions config file providing the `exempt` list. Optional:
        /// if the file is absent, no files are exempt.
        #[arg(long, default_value = "testing-conventions.toml")]
        config: PathBuf,
    },
    /// Check that the unit suite meets the configured coverage floor. With
    /// `--base`, the same configured floor is measured over the `<base>...HEAD`
    /// diff (the changed lines) instead of the whole tree — a changed line
    /// below the floor fails, no matter how small the diff.
    Coverage {
        /// Directory whose unit suite is run and measured.
        path: PathBuf,
        /// Language convention to enforce (required).
        #[arg(long, value_enum)]
        language: colocated_test::Language,
        /// Opt-in diff-scoped coverage: diff `<base>...HEAD` and measure the
        /// configured floor over only the changed lines, instead of the whole tree.
        /// Absent means whole-tree — there is no default. This is the patch-scoped
        /// check the old `unit patch-coverage` command did, re-homed onto the floor
        /// it shares.
        #[arg(long)]
        base: Option<String>,
        /// testing-conventions config file with the coverage thresholds and
        /// `exempt` list. Optional: if the file — or its `[<language>].coverage`
        /// table — is absent, the language's sane default floor is used and
        /// nothing is exempt.
        #[arg(long, default_value = "testing-conventions.toml")]
        config: PathBuf,
    },
    /// Lint unit test files for isolation: mock every collaborator (Python, TypeScript, Rust).
    Lint {
        /// Crate root / source dir to scan recursively.
        path: PathBuf,
        /// Language convention to enforce (required).
        #[arg(long, value_enum)]
        language: isolation::Language,
        /// testing-conventions config file providing the `exempt` list (waivers).
        /// Optional: if the file is absent, nothing is waived.
        #[arg(long, default_value = "testing-conventions.toml")]
        config: PathBuf,
    },
    /// Run mutation testing over the unit suite and fail on any surviving mutant not
    /// lifted by a `mutation` exemption — the rung above coverage. The gate is
    /// on by default (no report-only mode). All three languages (Python, TypeScript,
    /// Rust) are at parity and wired into the reusable workflow as a diff-scoped,
    /// PR-only job.
    Mutation {
        /// Crate whose unit suite is mutated.
        path: PathBuf,
        /// Language convention to enforce (required): `python`, `typescript`, or `rust`.
        #[arg(long, value_enum)]
        language: colocated_test::Language,
        /// Opt-in diff-scoping: restrict to mutants on lines a `<base>...HEAD`
        /// diff added or modified, via cargo-mutants' `--in-diff`. Absent means the
        /// whole crate (slower).
        #[arg(long)]
        base: Option<String>,
        /// testing-conventions config file providing the `exempt` list. Optional:
        /// absent means nothing is exempt (every survivor must be killed).
        #[arg(long, default_value = "testing-conventions.toml")]
        config: PathBuf,
        /// Path to the bundled TypeScript mutation adapter (`dist/mutation/main.js`), used
        /// only by `--language typescript`. The npm launcher appends it; hidden because a
        /// consumer never sets it by hand.
        #[arg(long = "ts-mutation-adapter", hide = true)]
        ts_adapter: Option<PathBuf>,
    },
}

/// Languages the integration-test lints support — its own set (Python,
/// TypeScript, Rust), distinct from the file-pairing `colocated_test::Language`,
/// so adding Rust here doesn't touch the colocated-test/coverage rules.
#[derive(Debug, Clone, Copy, PartialEq, Eq, clap::ValueEnum)]
pub enum IntegrationLintLanguage {
    /// Python test files (`*_test.py`, `test_*.py`, `conftest.py`).
    #[value(name = "python")]
    Python,
    /// TypeScript test files (`*.test.{ts,tsx,mts,cts}`).
    #[value(name = "typescript")]
    TypeScript,
    /// Rust integration crates under `tests/`.
    #[value(name = "rust")]
    Rust,
}

/// Lints enforced on integration tests (mocking mechanism & style, and more to
/// come). The README's "Integration" taxonomy.
#[derive(Subcommand, Debug)]
enum IntegrationRule {
    /// Lint integration test files for mocking mechanism & style (Python, TypeScript, Rust).
    Lint {
        /// Directory to scan recursively for test files.
        path: PathBuf,
        /// Language convention to enforce (required).
        #[arg(long, value_enum)]
        language: IntegrationLintLanguage,
        /// testing-conventions config file providing the `exempt` list (waivers).
        /// Optional: if the file is absent, nothing is waived.
        #[arg(long, default_value = "testing-conventions.toml")]
        config: PathBuf,
    },
}

/// E2E attestation commands: record a local e2e run and (later)
/// verify in CI that the latest code commit is attested.
#[derive(Subcommand, Debug)]
enum E2eCommand {
    /// Run the e2e suite and write a committed attestation naming the current commit.
    Attest {
        /// The e2e command to run (e.g. `pnpm run e2e`), executed via the shell.
        command: String,
    },
    /// Verify the committed attestation names the latest code commit (the CI gate).
    Verify {
        /// Directory whose committed e2e-attestation.json is verified (default: current directory).
        #[arg(default_value = ".")]
        path: PathBuf,
        /// Directory the "latest code commit" freshness walk is scoped to, if
        /// narrower than `path` (default: `path` itself, byte-identical to before
        /// this flag existed). Must be `path` or a descendant of it.
        #[arg(long)]
        scope: Option<PathBuf>,
        /// Opt-in diff-scoping: restrict freshness to the commits this
        /// branch introduced (`<base>..HEAD`) rather than all reachable history.
        /// A branch that didn't touch the scoped source passes with nothing to
        /// re-attest — the way the changed-line coverage/mutation gates pass on an
        /// empty diff, and what makes the gate safe for a squash-merging repo.
        /// Absent means the whole history (byte-identical to before this flag).
        #[arg(long)]
        base: Option<String>,
        /// Extra freshness roots: repo-root-relative directories outside
        /// `path` whose commits join the freshness walk — a shared source tree
        /// beside the package (a native core bound into several bindings) that no
        /// `--scope` at-or-below `path` can reach. Repeatable; the attestation
        /// must name the newest in-range commit touching the union of `--scope`
        /// and every `--extra-scope`. Absent means the walk covers only `--scope`.
        #[arg(long = "extra-scope")]
        extra_scope: Vec<PathBuf>,
        /// Feature-gated subtrees carved back out of the `--extra-scope` union:
        /// repo-root-relative directories (a core `cli/` compiled out of
        /// the bindings) whose commits must not stale the attestation. Repeatable.
        #[arg(long = "exclude")]
        exclude: Vec<PathBuf>,
    },
}

pub fn run<I, T>(args: I) -> anyhow::Result<i32>
where
    I: IntoIterator<Item = T>,
    T: Into<std::ffi::OsString> + Clone,
{
    let cli = Cli::try_parse_from(args)?;
    match cli.command {
        // The config-driven `check` umbrella isn't wired yet; the scaffold
        // proves the wiring while individual rules land under their test-kind
        // group (e.g. `unit colocated-test`).
        Some(Command::Check) | None => Ok(0),
        Some(Command::Unit { rule }) => match rule {
            UnitRule::ColocatedTest {
                path,
                language,
                base,
                config,
            } => run_unit_colocated_test(&path, language, base.as_deref(), &config),
            UnitRule::Coverage {
                path,
                language,
                base,
                config,
            } => run_unit_coverage(&path, language, base.as_deref(), &config),
            UnitRule::Lint {
                path,
                language,
                config,
            } => run_unit_lint(&path, language, &config),
            UnitRule::Mutation {
                path,
                language,
                base,
                config,
                ts_adapter,
            } => run_unit_mutation(
                &path,
                language,
                base.as_deref(),
                &config,
                ts_adapter.as_deref(),
            ),
        },
        Some(Command::Integration { rule }) => match rule {
            IntegrationRule::Lint {
                path,
                language,
                config,
            } => run_integration_lint(&path, language, &config),
        },
        Some(Command::Packaging { path, language }) => run_packaging(&path, language),
        Some(Command::Workflow { path }) => run_workflow(&path),
        Some(Command::E2e { command }) => match command {
            E2eCommand::Attest { command } => run_e2e_attest(&command),
            E2eCommand::Verify {
                path,
                scope,
                base,
                extra_scope,
                exclude,
            } => run_e2e_verify(
                &path,
                scope.as_deref(),
                base.as_deref(),
                &extra_scope,
                &exclude,
            ),
        },
        Some(Command::Install { path }) => {
            agents::install(&path)?;
            Ok(0)
        }
    }
}

/// The binary's own clap command tree — the source of truth for which subcommands
/// it exposes. The `workflow` guard checks a workflow's invocations against
/// it, so a renamed or removed subcommand is caught the moment they diverge.
pub fn command() -> clap::Command {
    Cli::command()
}

/// Run the unit colocated-test check over `root` for `language`. Always runs the
/// tree-wide **presence** check (every source file has its colocated test; Rust:
/// an inline `#[cfg(test)]` module). When `base` is `Some`, *additionally* runs the
/// commit-scoped **co-change** check over `<base>...HEAD` — a modified or
/// deleted source whose colocated test didn't co-change — and the run fails if
/// either check does. Returns `0` only when both pass.
///
/// Presence loads the `colocated-test`-rule exemptions and co-change the
/// `co-change`-rule exemptions from the config at `config_path` (no config file →
/// no exemptions). `--base` rejects `--language rust`: Rust units are inline
/// `#[cfg(test)]` in the same file, so a sibling test can't go stale (presence,
/// without `--base`, still supports Rust).
fn run_unit_colocated_test(
    root: &Path,
    language: colocated_test::Language,
    base: Option<&str>,
    config_path: &Path,
) -> anyhow::Result<i32> {
    // `--base` carries the co-change check, which rejects Rust the same way the
    // standalone `unit co-change` did — before any work, so the message matches.
    if base.is_some() && language == colocated_test::Language::Rust {
        anyhow::bail!(
            "`unit colocated-test --base` supports `--language python` / `typescript`; Rust \
             units are inline `#[cfg(test)]` in the same file, so a sibling test can't go stale"
        );
    }
    let presence_clean = report_colocated_presence(root, language, config_path)?;
    let co_change_clean = match base {
        Some(base) => report_co_change(root, base, language, config_path)?,
        None => true,
    };
    Ok(if presence_clean && co_change_clean {
        0
    } else {
        1
    })
}

/// The tree-wide colocated-test **presence** check: every source file under `root`
/// has its colocated unit test (Rust: an inline `#[cfg(test)]` module). Prints each
/// orphan to stderr and returns `Ok(false)` when any are found, `Ok(true)` when the
/// tree is clean. The `colocated-test`-rule exemptions from the config at
/// `config_path` lift a file (no config file → nothing exempt).
fn report_colocated_presence(
    root: &Path,
    language: colocated_test::Language,
    config_path: &Path,
) -> anyhow::Result<bool> {
    let exempt = colocated_test_exemptions(root, language, config_path)?;
    let orphans = match language {
        // Rust units are inline `#[cfg(test)]` modules, so "colocated" means a test
        // module in the same file, not a sibling file.
        colocated_test::Language::Rust => colocated_test::missing_inline_tests(root, &exempt)?,
        _ => colocated_test::missing_unit_tests(root, language, &exempt)?,
    };
    if orphans.is_empty() {
        return Ok(true);
    }
    let (label, summary) = match language {
        colocated_test::Language::Rust => (
            "missing inline `#[cfg(test)]` tests",
            "source file(s) with testable code but no inline `#[cfg(test)]` module \
             (add an inline test module, or an `exempt` entry with a reason)",
        ),
        _ => (
            "missing colocated unit test",
            "source file(s) missing a colocated unit test \
             (add a colocated test, or an `exempt` entry with a reason)",
        ),
    };
    for orphan in &orphans {
        eprintln!("{label}: {}", orphan.display());
    }
    eprintln!("error: {} {summary}", orphans.len());
    Ok(false)
}

/// The `colocated-test`-rule exempt paths for `language`, resolved (and validated)
/// from the config at `config_path`. A missing config file means no exemptions —
/// the check still runs, just with nothing exempted.
fn colocated_test_exemptions(
    root: &Path,
    language: colocated_test::Language,
    config_path: &Path,
) -> anyhow::Result<std::collections::BTreeSet<String>> {
    if !config_path.exists() {
        return Ok(std::collections::BTreeSet::new());
    }
    let config = config::load_config(config_path)?;
    config::resolve_exempt(
        root,
        config.exemptions(language),
        config::Rule::ColocatedTest,
    )
}

/// The commit-scoped **co-change** check over `root`, diffing `<base>...HEAD`:
/// every modified or deleted source whose colocated test didn't co-change. Prints
/// each stale source to stderr and returns `Ok(false)` when any are found,
/// `Ok(true)` when clean.
///
/// Loads the `co-change`-rule exemptions from the config at `config_path` (no
/// config file → no exemptions); an exempt source needn't co-change. The caller
/// rejects `--language rust` before this runs: Rust units are inline `#[cfg(test)]`
/// in the same file, so a sibling test can't go stale.
fn report_co_change(
    root: &Path,
    base: &str,
    language: colocated_test::Language,
    config_path: &Path,
) -> anyhow::Result<bool> {
    let exempt = co_change_exemptions(root, language, config_path)?;
    let stale = co_change::stale_sources(root, base, language, &exempt)?;
    if stale.is_empty() {
        return Ok(true);
    }
    for source in &stale {
        eprintln!(
            "source changed without its colocated test: {}",
            source.display()
        );
    }
    eprintln!(
        "error: {} source file(s) changed without their colocated test co-changing \
         (update the test, or add an `exempt` entry with a reason)",
        stale.len()
    );
    Ok(false)
}

/// The `co-change`-rule exempt paths for `language`, resolved (and validated)
/// from the config at `config_path`. A missing config file means no exemptions —
/// every changed source must co-change its test.
fn co_change_exemptions(
    root: &Path,
    language: colocated_test::Language,
    config_path: &Path,
) -> anyhow::Result<std::collections::BTreeSet<String>> {
    if !config_path.exists() {
        return Ok(std::collections::BTreeSet::new());
    }
    let config = config::load_config(config_path)?;
    config::resolve_exempt(root, config.exemptions(language), config::Rule::CoChange)
}

/// Split a resolved exempt-scope map into the whole-file paths and the
/// line-scoped sets — the two shapes the `coverage` / `mutation` measure functions
/// take. A [`config::LineScope::WholeFile`] becomes a path in the first vec; a
/// [`config::LineScope::Lines`] a `path → lines` entry in the second map.
fn split_scopes(
    scopes: std::collections::BTreeMap<String, config::LineScope>,
) -> (
    Vec<String>,
    std::collections::BTreeMap<String, std::collections::BTreeSet<u32>>,
) {
    let mut whole_file = Vec::new();
    let mut line_scoped = std::collections::BTreeMap::new();
    for (path, scope) in scopes {
        match scope {
            config::LineScope::WholeFile => whole_file.push(path),
            config::LineScope::Lines(lines) => {
                line_scoped.insert(path, lines);
            }
        }
    }
    (whole_file, line_scoped)
}

/// Run the unit-test coverage check over `root` for `language`, enforcing the
/// floor from the config at `config_path`. Returns `0` when the floor is met,
/// `1` otherwise.
///
/// With `base` set, the same configured floor is measured over the
/// `<base>...HEAD` diff (the changed lines) rather than the whole tree,
/// via the diff-scoped [`patch_coverage::measure`] / `measure_typescript` /
/// `measure_rust`; without it, the whole-tree [`coverage::measure`] family runs.
///
/// Coverage is zero-config by default for Python and TypeScript: a missing
/// config file — or a config with no `[<language>].coverage` table — falls back to
/// the language's sane default floor ([`config::PythonCoverage::default`] /
/// [`config::TypeScriptCoverage::default`]), the same way `unit colocated-test` and
/// `integration lint` treat an absent config as "nothing exempt". A present
/// `coverage` table overrides the default; `coverage`-rule exemptions still apply.
/// Rust is zero-config too: a missing `[rust].coverage` table falls back to
/// [`config::RustCoverage::default`] (`lines = 100`, `regions` opt-in, no branch).
fn run_unit_coverage(
    root: &Path,
    language: colocated_test::Language,
    base: Option<&str>,
    config_path: &Path,
) -> anyhow::Result<i32> {
    let config = if config_path.exists() {
        config::load_config(config_path)?
    } else {
        config::Config::default()
    };
    let outcome = match language {
        colocated_test::Language::Python => {
            let python = config.python.unwrap_or_default();
            let coverage = python.coverage.unwrap_or_default();
            let thresholds = coverage::Thresholds {
                fail_under: coverage.fail_under,
                branch: coverage.branch,
            };
            let (omit, exempt_lines) = split_scopes(config::resolve_exempt_scoped(
                root,
                &python.exempt,
                config::Rule::Coverage,
            )?);
            match base {
                Some(base) => {
                    patch_coverage::measure(root, base, thresholds, &omit, &exempt_lines)?
                }
                None if exempt_lines.is_empty() => coverage::measure(root, thresholds, &omit)?,
                None => {
                    patch_coverage::measure_line_exempt(root, thresholds, &omit, &exempt_lines)?
                }
            }
        }
        colocated_test::Language::TypeScript => {
            let typescript = config.typescript.unwrap_or_default();
            let coverage = typescript.coverage.unwrap_or_default();
            let thresholds = coverage::TypeScriptThresholds {
                lines: coverage.lines,
                branches: coverage.branches,
                functions: coverage.functions,
                statements: coverage.statements,
            };
            let (exclude, exempt_lines) = split_scopes(config::resolve_exempt_scoped(
                root,
                &typescript.exempt,
                config::Rule::Coverage,
            )?);
            match base {
                Some(base) => patch_coverage::measure_typescript(
                    root,
                    base,
                    thresholds,
                    &exclude,
                    &exempt_lines,
                )?,
                None if exempt_lines.is_empty() => {
                    coverage::measure_typescript(root, thresholds, &exclude)?
                }
                None => patch_coverage::measure_line_exempt_typescript(
                    root,
                    thresholds,
                    &exclude,
                    &exempt_lines,
                )?,
            }
        }
        colocated_test::Language::Rust => {
            let rust = config.rust.unwrap_or_default();
            // Zero-config: a missing `[rust].coverage` table falls back to the
            // default Rust floor (`lines = 100`, with `regions` opt-in and no branch
            // component) — matching Python/TypeScript — rather than erroring for a
            // required table. A present table overrides it.
            let coverage = rust.coverage.unwrap_or_default();
            let thresholds = coverage::RustThresholds {
                regions: coverage.regions,
                lines: coverage.lines,
                functions: coverage.functions,
                branch: coverage.branch,
            };
            let (ignore, exempt_lines) = split_scopes(config::resolve_exempt_scoped(
                root,
                &rust.exempt,
                config::Rule::Coverage,
            )?);
            match base {
                Some(base) => patch_coverage::measure_rust(
                    root,
                    base,
                    thresholds,
                    &ignore,
                    &exempt_lines,
                    &rust.features,
                )?,
                None if exempt_lines.is_empty() => {
                    coverage::measure_rust(root, thresholds, &ignore, &rust.features)?
                }
                None => patch_coverage::measure_line_exempt_rust(
                    root,
                    thresholds,
                    &ignore,
                    &exempt_lines,
                    &rust.features,
                )?,
            }
        }
    };
    match outcome {
        coverage::Outcome::Pass => Ok(0),
        coverage::Outcome::Fail(reason) => {
            eprintln!("error: coverage check failed — {reason}");
            Ok(1)
        }
    }
}

/// Run `unit mutation` over `root`: run the per-language engine and fail
/// on any surviving mutant not lifted by a `mutation` exemption.
///
/// The gate is **on by default and binary** — "no *unexplained* surviving mutant":
/// every survivor must be killed with an assertion, or lifted by a reason-required
/// `[[<language>.exempt]] rules = ["mutation"]` for an equivalent / deliberately-defensive
/// mutation. There is no percentage floor (equivalent mutants make one unreachable)
/// and no report-only mode — the only loosening is a reasoned, per-file exemption.
/// All three languages are wired: Rust (cargo-mutants), TypeScript (Stryker), and
/// Python (cosmic-ray). `--base` scopes the run to the diff.
fn run_unit_mutation(
    root: &Path,
    language: colocated_test::Language,
    base: Option<&str>,
    config_path: &Path,
    ts_adapter: Option<&Path>,
) -> anyhow::Result<i32> {
    let config = if config_path.exists() {
        config::load_config(config_path)?
    } else {
        config::Config::default()
    };
    let survivors = match language {
        colocated_test::Language::Rust => {
            let rust = config.rust.unwrap_or_default();
            let (exempt, exempt_lines) = split_scopes(config::resolve_exempt_scoped(
                root,
                &rust.exempt,
                config::Rule::Mutation,
            )?);
            mutation::measure_rust(root, &exempt, &exempt_lines, base, &rust.features)?
        }
        colocated_test::Language::TypeScript => {
            let typescript = config.typescript.unwrap_or_default();
            let (exempt, exempt_lines) = split_scopes(config::resolve_exempt_scoped(
                root,
                &typescript.exempt,
                config::Rule::Mutation,
            )?);
            // The npm launcher appends `--ts-mutation-adapter`; its absence means the binary
            // was run directly, not through the published CLI.
            let adapter = ts_adapter.ok_or_else(|| {
                anyhow::anyhow!(
                    "the TypeScript mutation adapter path is required: pass \
                     `--ts-mutation-adapter <path>`. The npm `testing-conventions` CLI appends it \
                     automatically — run the rule through that CLI, not the raw binary."
                )
            })?;
            mutation::measure_typescript(root, &exempt, &exempt_lines, base, adapter)?
        }
        colocated_test::Language::Python => {
            let python = config.python.unwrap_or_default();
            let (exempt, exempt_lines) = split_scopes(config::resolve_exempt_scoped(
                root,
                &python.exempt,
                config::Rule::Mutation,
            )?);
            mutation::measure_python(root, &exempt, &exempt_lines, base)?
        }
    };
    if survivors.is_empty() {
        println!("unit mutation: no surviving mutants — every mutation was caught");
        return Ok(0);
    }

    eprintln!(
        "error: {} unexplained surviving mutant(s) — kill each with an assertion, or lift an \
         equivalent/defensive one with a reason-required `[[<language>.exempt]] rules = [\"mutation\"]`:",
        survivors.len()
    );
    for survivor in &survivors {
        eprintln!(
            "  {}:{}: {}",
            survivor.file, survivor.line, survivor.description
        );
    }
    Ok(1)
}

/// Run the `unit lint` check over `root` for `language` — the unit-suite
/// isolation lints (`unmocked-collaborator`, `untyped-mock`, `no-out-of-module-call`,
/// `no-out-of-module-import`) — printing each violation to stderr as
/// `path:line: rule — message` and returning `1` when any are found, `0` otherwise.
fn run_unit_lint(
    root: &Path,
    language: isolation::Language,
    config_path: &Path,
) -> anyhow::Result<i32> {
    let (raw, select): (Vec<lint::Violation>, ExemptSelect) = match language {
        isolation::Language::Rust => (isolation::find_violations(root)?, |c| c.rust_exemptions()),
        isolation::Language::TypeScript => (ts::find_unit_violations(root)?, |c| {
            c.exemptions(colocated_test::Language::TypeScript)
        }),
        isolation::Language::Python => (lint::find_unit_isolation_violations(root)?, |c| {
            c.exemptions(colocated_test::Language::Python)
        }),
    };
    let violations = apply_waivers(raw, root, config_path, select)?;
    if violations.is_empty() {
        return Ok(0);
    }
    for v in &violations {
        eprintln!(
            "{}:{}: {} — {}",
            v.file.display(),
            v.line,
            v.rule,
            v.message
        );
    }
    eprintln!("error: {} isolation violation(s)", violations.len());
    Ok(1)
}

/// Run the integration-test lints over `root` for `language`, printing each
/// violation to stderr as `path:line: rule — message` and returning `1` when any
/// are found, `0` otherwise.
///
/// The subjects derive from the package root — the nearest directory at or
/// above `root` holding the language's manifest: the `tests/integration/` and
/// `tests/e2e/` suites (Rust: the crate root's `tests/`, cargo's own layout).
/// A tree with no manifest — loose scripts — is scanned at `root` directly, and
/// exemption paths resolve relative to whichever root the scan used.
fn run_integration_lint(
    root: &Path,
    language: IntegrationLintLanguage,
    config_path: &Path,
) -> anyhow::Result<i32> {
    let manifest = match language {
        IntegrationLintLanguage::Python => "pyproject.toml",
        IntegrationLintLanguage::TypeScript => "package.json",
        IntegrationLintLanguage::Rust => "Cargo.toml",
    };
    let package_root = tiers::package_root(root, manifest);
    let scan_root = package_root.as_deref().unwrap_or(root);
    let (raw, select): (Vec<lint::Violation>, ExemptSelect) = match language {
        IntegrationLintLanguage::Python => (
            match &package_root {
                Some(package_root) => lint::find_suite_violations(package_root)?,
                None => lint::find_violations(root)?,
            },
            |c| c.exemptions(colocated_test::Language::Python),
        ),
        IntegrationLintLanguage::TypeScript => (
            match &package_root {
                Some(package_root) => ts::find_suite_violations(package_root)?,
                None => ts::find_integration_violations(root)?,
            },
            |c| c.exemptions(colocated_test::Language::TypeScript),
        ),
        IntegrationLintLanguage::Rust => {
            (isolation::find_integration_violations(scan_root)?, |c| {
                c.rust_exemptions()
            })
        }
    };
    let violations = apply_waivers(raw, scan_root, config_path, select)?;
    if violations.is_empty() {
        return Ok(0);
    }
    for v in &violations {
        eprintln!(
            "{}:{}: {} — {}",
            v.file.display(),
            v.line,
            v.rule,
            v.message
        );
    }
    eprintln!("error: {} lint violation(s)", violations.len());
    Ok(1)
}

/// Selects a language's `[[<lang>.exempt]]` table from a loaded config — the one
/// varying piece between the `unit lint` and `integration lint` waiver paths.
type ExemptSelect = fn(&config::Config) -> &[config::Exemption];

/// Drop the violations waived by the config's `exempt` list. A
/// violation is waived when its `rule` is a known [`config::Rule`] and its
/// `root`-relative path is exempt for that rule. `exemptions` selects the
/// language's `[[<lang>.exempt]]` table from the loaded config. A missing config
/// file waives nothing; a reason-less or stale entry errors (via `load_config` /
/// `resolve_exempt`), so the escape hatch can't silently rot.
fn apply_waivers(
    violations: Vec<lint::Violation>,
    root: &Path,
    config_path: &Path,
    exemptions: ExemptSelect,
) -> anyhow::Result<Vec<lint::Violation>> {
    use std::collections::hash_map::Entry;

    if !config_path.exists() {
        return Ok(violations);
    }
    let config = config::load_config(config_path)?;
    let exempt = exemptions(&config);
    // Resolve each rule's exempt set once (and surface a stale entry as an error).
    let mut resolved: std::collections::HashMap<config::Rule, std::collections::BTreeSet<String>> =
        std::collections::HashMap::new();
    let mut kept = Vec::new();
    for violation in violations {
        let waived = match config::Rule::from_id(violation.rule) {
            Some(rule) => {
                let exempt_paths = match resolved.entry(rule) {
                    Entry::Occupied(entry) => entry.into_mut(),
                    Entry::Vacant(entry) => {
                        entry.insert(config::resolve_exempt(root, exempt, rule)?)
                    }
                };
                violation
                    .file
                    .strip_prefix(root)
                    .ok()
                    .map(|rel| rel.to_string_lossy().replace('\\', "/"))
                    .is_some_and(|rel| exempt_paths.contains(&rel))
            }
            None => false,
        };
        if !waived {
            kept.push(violation);
        }
    }
    Ok(kept)
}

/// Run the packaging check: inspect the built artifact at `artifact` for test
/// files that must not ship (README "Packaging"), per `language`'s test-file
/// globs.
///
/// `artifact` is either an already-unpacked directory or a packed artifact the
/// rule unpacks itself — a Python wheel (`.whl`) today; the TypeScript and
/// Rust archives follow. Returns `0` when no test file is present, `1`
/// otherwise (after printing each offending path, relative to the artifact root).
fn run_packaging(artifact: &Path, language: colocated_test::Language) -> anyhow::Result<i32> {
    let globs = match language {
        colocated_test::Language::Python => vec!["*_test.py".to_string()],
        colocated_test::Language::TypeScript => vec!["*.test.*".to_string()],
        // `#[cfg(test)]` units compile out for free; the only thing to keep out of
        // the `.crate` source tarball is the crate-root integration `tests/` dir.
        colocated_test::Language::Rust => vec!["tests/".to_string()],
    };
    let offenders = packaging::inspect(artifact, &globs)?;
    if offenders.is_empty() {
        return Ok(0);
    }
    for offender in &offenders {
        eprintln!("test file in built artifact: {}", offender.display());
    }
    eprintln!(
        "error: {} test file(s) present in the built artifact \
         (they must be excluded from packaging)",
        offenders.len()
    );
    Ok(1)
}

/// Run the workflow guard over `path` (a workflow file or directory): flag every
/// `testing-conventions` invocation that names a subcommand this binary no longer
/// exposes, printing each as `path:line: rule — message` and returning `1` when any
/// are found, `0` otherwise.
fn run_workflow(path: &Path) -> anyhow::Result<i32> {
    let violations = workflow::check(path, &command())?;
    if violations.is_empty() {
        return Ok(0);
    }
    for v in &violations {
        eprintln!(
            "{}:{}: {} — {}",
            v.file.display(),
            v.line,
            v.rule,
            v.message
        );
    }
    eprintln!(
        "error: {} workflow invocation(s) name a subcommand this binary no longer exposes",
        violations.len()
    );
    Ok(1)
}

/// Run `command` as an e2e suite and write a committed attestation naming the
/// current commit. Force-runs: the attestation is written regardless of
/// the command's exit code, so this exits `0` once the attestation is recorded.
fn run_e2e_attest(command: &str) -> anyhow::Result<i32> {
    let repo = std::env::current_dir()?;
    let attestation = e2e::attest(&repo, command)?;
    println!(
        "e2e attestation recorded for commit {} (command exited {})",
        attestation.commit, attestation.exit_code
    );
    Ok(0)
}

/// Verify the committed e2e attestation names the latest code commit — the
/// CI side of the nudge. Exits `0` when fresh; otherwise prints the actionable
/// hint and exits `1`. Never runs e2e, never judges the recorded run.
///
/// `path` is the directory whose committed `e2e-attestation.json` is checked
/// — the default `.` resolves against the current directory, so a
/// no-argument call behaves exactly like the `current_dir()` read.
/// Passing a package subdirectory scopes discovery to it, matching a call made
/// with that directory as cwd. `scope`, when set, narrows the "latest code
/// commit" freshness walk to a directory under `path` instead of all of it
/// — `None` behaves exactly like passing `path` itself. `base`, when set,
/// restricts the walk to the commits this branch introduced (`<base>..HEAD`)
/// instead of all history — `None` behaves exactly like before the flag.
/// `extra_scopes` join repo-root-relative sibling trees into the walk and
/// `excludes` carve feature-gated subtrees back out — both empty behaves
/// exactly like before those flags.
fn run_e2e_verify(
    path: &Path,
    scope: Option<&Path>,
    base: Option<&str>,
    extra_scopes: &[PathBuf],
    excludes: &[PathBuf],
) -> anyhow::Result<i32> {
    match e2e::verify_extra_scoped(path, scope.unwrap_or(path), base, extra_scopes, excludes)? {
        e2e::Verification::Fresh => Ok(0),
        e2e::Verification::Missing => {
            eprintln!(
                "e2e attestation missing — run `testing-conventions e2e attest '<your e2e command>'`"
            );
            Ok(1)
        }
        e2e::Verification::Stale { attested, latest } => {
            eprintln!(
                "e2e attestation out of date: attested {}, latest code commit {} — \
                 run `testing-conventions e2e attest '<your e2e command>'`",
                &attested[..attested.len().min(7)],
                &latest[..latest.len().min(7)]
            );
            Ok(1)
        }
    }
}

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

    #[test]
    fn no_args_returns_ok_zero() {
        assert_eq!(run(["testing-conventions"]).unwrap(), 0);
    }

    #[test]
    fn check_returns_ok_zero() {
        assert_eq!(run(["testing-conventions", "check"]).unwrap(), 0);
    }

    #[test]
    fn unknown_flag_errors() {
        assert!(run(["testing-conventions", "--bogus"]).is_err());
    }

    #[test]
    fn help_flag_returns_clap_display_help() {
        let err = run(["testing-conventions", "--help"]).expect_err("--help should bubble");
        let clap_err = err
            .downcast_ref::<clap::Error>()
            .expect("error should be a clap::Error");
        assert_eq!(clap_err.kind(), clap::error::ErrorKind::DisplayHelp);
    }

    #[test]
    fn version_flag_returns_clap_display_version() {
        let err = run(["testing-conventions", "--version"]).expect_err("--version should bubble");
        let clap_err = err
            .downcast_ref::<clap::Error>()
            .expect("error should be a clap::Error");
        assert_eq!(clap_err.kind(), clap::error::ErrorKind::DisplayVersion);
    }
}