testing_conventions/

config.rs

//! The testing-conventions config schema and loader. A malformed or unknown-key
//! config is an error, never a silently-accepted default.

use std::collections::BTreeSet;
use std::path::Path;

use anyhow::{bail, Context, Result};
use serde::Deserialize;

/// A fully-parsed testing-conventions config file.
#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Config {
    pub python: Option<PythonConfig>,
    pub typescript: Option<TypeScriptConfig>,
    pub rust: Option<RustConfig>,
    pub e2e: Option<E2eConfig>,
}

/// The `[python]` table.
#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct PythonConfig {
    pub coverage: Option<PythonCoverage>,
    /// The `one-function-per-file` threshold; see [`OneFunctionPerFile`].
    pub one_function_per_file: Option<OneFunctionPerFile>,
    #[serde(default)]
    pub exempt: Vec<Exemption>,
    /// The build declaration a build-dependent workflow job runs. `detect` reads it and the
    /// jobs run it; the binary only accepts the key so a consumer's config still loads.
    pub build_command: Option<String>,
    /// Free-form note on the build, never validated.
    #[serde(default)]
    pub reason: String,
}

/// The `[e2e]` table. `detect` renders these into `e2e verify --extra-scope` / `--exclude`;
/// the binary only accepts the table so a consumer declaring it still loads.
#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct E2eConfig {
    #[serde(default)]
    pub extra_scope: Vec<String>,
    #[serde(default)]
    pub exclude: Vec<String>,
}

/// The `[typescript]` table.
#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct TypeScriptConfig {
    pub coverage: Option<TypeScriptCoverage>,
    /// The `one-function-per-file` threshold; see [`OneFunctionPerFile`].
    pub one_function_per_file: Option<OneFunctionPerFile>,
    #[serde(default)]
    pub exempt: Vec<Exemption>,
    /// The build declaration; see [`PythonConfig::build_command`].
    pub build_command: Option<String>,
    /// Free-form note on the build, never validated.
    #[serde(default)]
    pub reason: String,
}

/// The `[rust]` table.
#[derive(Debug, Clone, Default, PartialEq, Eq, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct RustConfig {
    pub coverage: Option<RustCoverage>,
    /// The `one-function-per-file` threshold; see [`OneFunctionPerFile`].
    pub one_function_per_file: Option<OneFunctionPerFile>,
    /// Cargo features `unit coverage` and `unit mutation` pass to their engines.
    #[serde(default)]
    pub features: Vec<String>,
    #[serde(default)]
    pub exempt: Vec<Exemption>,
    /// The build declaration; see [`PythonConfig::build_command`].
    pub build_command: Option<String>,
    /// Free-form note on the build, never validated.
    #[serde(default)]
    pub reason: String,
}

/// `[python].coverage`. A partial override: a missing field falls back to
/// [`PythonCoverage::default`].
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct PythonCoverage {
    pub branch: bool,
    pub fail_under: u8,
}

/// Branch coverage on, `fail_under = 100`.
impl Default for PythonCoverage {
    fn default() -> Self {
        Self {
            branch: true,
            fail_under: 100,
        }
    }
}

/// `[typescript].coverage`. A partial override: a missing field falls back to
/// [`TypeScriptCoverage::default`].
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct TypeScriptCoverage {
    pub lines: u8,
    pub branches: u8,
    pub functions: u8,
    pub statements: u8,
}

/// All four metrics at 100.
impl Default for TypeScriptCoverage {
    fn default() -> Self {
        Self {
            lines: 100,
            branches: 100,
            functions: 100,
            statements: 100,
        }
    }
}

/// `[rust].coverage`. A partial override: a missing field falls back to
/// [`RustCoverage::default`]. `branch` instruments only on a nightly toolchain.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct RustCoverage {
    pub regions: Option<u8>,
    pub lines: u8,
    pub functions: Option<u8>,
    pub branch: Option<u8>,
}

/// `lines = 100`; the other metrics are opt-in.
impl Default for RustCoverage {
    fn default() -> Self {
        Self {
            regions: None,
            lines: 100,
            functions: None,
            branch: None,
        }
    }
}

/// `[<language>].one_function_per_file`. A partial override: a missing field falls back to
/// [`OneFunctionPerFile::default`].
#[derive(Debug, Clone, Copy, PartialEq, Eq, Deserialize)]
#[serde(default, deny_unknown_fields)]
pub struct OneFunctionPerFile {
    /// The longest body a module-scope function may have and still **share** a file.
    /// A function longer than this must be the file's only such function.
    pub max_lines: u32,
}

/// `max_lines = 1`.
impl Default for OneFunctionPerFile {
    fn default() -> Self {
        Self { max_lines: 1 }
    }
}

/// A rule a file can be exempted from.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum Rule {
    /// The unit-test colocated-test check ([`crate::colocated_test`]).
    ColocatedTest,
    /// The unit-test coverage floor ([`crate::coverage`]).
    Coverage,
    /// The commit-scoped `co-change` check ([`crate::co_change`]).
    CoChange,
    /// `integration lint` — a test/fixture takes pytest's `monkeypatch` fixture ([`crate::lint`]).
    NoMonkeypatch,
    /// `integration lint` — a `patch(...)` called inline in a Python test body ([`crate::lint`]).
    NoInlinePatch,
    /// `integration lint` — direct mutation of `os.environ` in a Python test ([`crate::lint`]).
    NoEnvironMutation,
    /// The `no-constant-patch` lint ([`crate::lint`]).
    NoConstantPatch,
    /// `integration lint` — patching a first-party target in a Python integration test ([`crate::lint`]).
    NoFirstPartyPatch,
    /// `unit lint` — a call out of a Rust unit's own module ([`crate::isolation`]).
    NoOutOfModuleCall,
    /// `unit lint` — a foreign `use` in a Rust unit test ([`crate::isolation`]).
    NoOutOfModuleImport,
    /// `integration lint` — doubling a first-party item in a Rust integration test.
    NoFirstPartyDouble,
    /// `unit lint` — an un-mocked first-party/external import in a TS unit test ([`crate::ts`]).
    UnmockedCollaborator,
    /// `unit lint` — a `vi.mock` without a typed anchor in a TS unit test.
    UntypedMock,
    /// `integration lint` — a `vi.mock` of a first-party module in a TS integration test.
    NoFirstPartyMock,
    /// `integration lint` — a test file outside a standard suite tier.
    UnknownTier,
    /// `unit mutation` — a surviving mutant the unit suite didn't catch ([`crate::mutation`]).
    Mutation,
    /// `unit one-function-per-file` ([`crate::one_function`]).
    OneFunctionPerFile,
}

impl Rule {
    /// Whether a `lines` list may scope this rule — true for the measured-line rules.
    pub fn is_line_scopable(self) -> bool {
        matches!(self, Rule::Coverage | Rule::Mutation)
    }

    /// The rule's kebab-case id, mirroring the `serde(rename_all = "kebab-case")` encoding.
    pub fn id(self) -> &'static str {
        match self {
            Rule::ColocatedTest => "colocated-test",
            Rule::Coverage => "coverage",
            Rule::CoChange => "co-change",
            Rule::NoMonkeypatch => "no-monkeypatch",
            Rule::NoInlinePatch => "no-inline-patch",
            Rule::NoEnvironMutation => "no-environ-mutation",
            Rule::NoConstantPatch => "no-constant-patch",
            Rule::NoFirstPartyPatch => "no-first-party-patch",
            Rule::NoOutOfModuleCall => "no-out-of-module-call",
            Rule::NoOutOfModuleImport => "no-out-of-module-import",
            Rule::NoFirstPartyDouble => "no-first-party-double",
            Rule::UnmockedCollaborator => "unmocked-collaborator",
            Rule::UntypedMock => "untyped-mock",
            Rule::NoFirstPartyMock => "no-first-party-mock",
            Rule::UnknownTier => "unknown-tier",
            Rule::Mutation => "mutation",
            Rule::OneFunctionPerFile => "one-function-per-file",
        }
    }

    /// The [`Rule`] for a lint id, or `None` for an unknown / non-waivable id.
    pub fn from_id(id: &str) -> Option<Rule> {
        [
            Rule::ColocatedTest,
            Rule::Coverage,
            Rule::CoChange,
            Rule::NoMonkeypatch,
            Rule::NoInlinePatch,
            Rule::NoEnvironMutation,
            Rule::NoConstantPatch,
            Rule::NoFirstPartyPatch,
            Rule::NoOutOfModuleCall,
            Rule::NoOutOfModuleImport,
            Rule::NoFirstPartyDouble,
            Rule::UnmockedCollaborator,
            Rule::UntypedMock,
            Rule::NoFirstPartyMock,
            Rule::UnknownTier,
            Rule::Mutation,
            Rule::OneFunctionPerFile,
        ]
        .into_iter()
        .find(|rule| rule.id() == id)
    }
}

/// One element of an exemption's `lines` list: a single 1-based line, or an inclusive
/// `"start-end"` range. Semantic checks live in [`Config::validate`], so the error can name
/// the offending exemption.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum LineSpec {
    Single(u32),
    /// An inclusive line range, `start..=end`.
    Range(u32, u32),
}

impl LineSpec {
    /// Parse a string spec: `"12-13"` → a range, `"9"` → a single line.
    fn parse_str(s: &str) -> Result<LineSpec, String> {
        let parse = |part: &str| {
            part.trim()
                .parse::<u32>()
                .map_err(|_| format!("`{s}` is not a line number or \"start-end\" range"))
        };
        match s.split_once('-') {
            Some((start, end)) => Ok(LineSpec::Range(parse(start)?, parse(end)?)),
            None => Ok(LineSpec::Single(parse(s)?)),
        }
    }

    /// The lines this spec expands to, pushed into `set`.
    fn extend_into(self, set: &mut BTreeSet<u32>) {
        match self {
            LineSpec::Single(n) => {
                set.insert(n);
            }
            LineSpec::Range(start, end) => {
                for n in start..=end {
                    set.insert(n);
                }
            }
        }
    }
}

impl<'de> Deserialize<'de> for LineSpec {
    fn deserialize<D>(deserializer: D) -> std::result::Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        struct SpecVisitor;
        impl serde::de::Visitor<'_> for SpecVisitor {
            type Value = LineSpec;

            fn expecting(&self, f: &mut std::fmt::Formatter) -> std::fmt::Result {
                f.write_str("a line number or a \"start-end\" range string")
            }

            fn visit_u64<E: serde::de::Error>(self, v: u64) -> std::result::Result<LineSpec, E> {
                u32::try_from(v)
                    .map(LineSpec::Single)
                    .map_err(|_| E::custom(format!("line number {v} is out of range")))
            }

            // TOML integers arrive as i64, so a negative line number reaches this visitor.
            fn visit_i64<E: serde::de::Error>(self, v: i64) -> std::result::Result<LineSpec, E> {
                u64::try_from(v)
                    .map_err(|_| E::custom(format!("line number {v} must be positive")))
                    .and_then(|v| self.visit_u64(v))
            }

            fn visit_str<E: serde::de::Error>(self, v: &str) -> std::result::Result<LineSpec, E> {
                LineSpec::parse_str(v).map_err(E::custom)
            }
        }
        deserializer.deserialize_any(SpecVisitor)
    }
}

/// One auditable per-file exemption — a `[[<language>.exempt]]` entry.
#[derive(Debug, Clone, PartialEq, Eq, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct Exemption {
    /// Path to the exempt file, relative to the scanned root.
    pub path: String,
    /// Which rules the exemption lifts.
    pub rules: Vec<Rule>,
    /// Lines this exemption is scoped to; empty is a whole-file exemption.
    #[serde(default)]
    pub lines: Vec<LineSpec>,
    /// Why the omission is deliberate — required, and never empty.
    pub reason: String,
}

impl Exemption {
    /// The 1-based line numbers this exemption is scoped to, with ranges expanded.
    pub fn line_set(&self) -> BTreeSet<u32> {
        let mut set = BTreeSet::new();
        for spec in &self.lines {
            spec.extend_into(&mut set);
        }
        set
    }
}

/// What an exemption lifts for one file: the whole file, or only specific lines.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum LineScope {
    WholeFile,
    /// Only these 1-based lines are exempt.
    Lines(BTreeSet<u32>),
}

impl LineScope {
    /// Merge two scopes for the same path: whole-file subsumes line-scoped, otherwise union.
    fn merged_with(self, other: LineScope) -> LineScope {
        match (self, other) {
            (LineScope::WholeFile, _) | (_, LineScope::WholeFile) => LineScope::WholeFile,
            (LineScope::Lines(mut a), LineScope::Lines(b)) => {
                a.extend(b);
                LineScope::Lines(a)
            }
        }
    }
}

/// The migration record an unknown-key rejection points at: a stale key left by a rename
/// reads identically to a typo at parse time.
const MIGRATIONS_URL: &str =
    "https://github.com/thekevinscott/testing-conventions/blob/main/packages/rust/MIGRATIONS.md";

/// Append the [`MIGRATIONS_URL`] pointer to a `deny_unknown_fields` rejection, passing every
/// other TOML parse error through untouched.
fn annotate_toml_error(err: toml::de::Error) -> anyhow::Error {
    if err.message().contains("unknown field") {
        anyhow::anyhow!(err).context(format!(
            "an unrecognized key can be a typo or a key a release renamed or removed — see {MIGRATIONS_URL}"
        ))
    } else {
        anyhow::anyhow!(err)
    }
}

/// Read one config file at `path` into a [`Config`], validating it on the way.
pub fn load_config(path: impl AsRef<Path>) -> Result<Config> {
    let path = path.as_ref();
    let contents = std::fs::read_to_string(path)
        .with_context(|| format!("reading config file `{}`", path.display()))?;
    let config: Config = toml::from_str(&contents)
        .map_err(annotate_toml_error)
        .with_context(|| format!("parsing config file `{}`", path.display()))?;
    config
        .validate()
        .with_context(|| format!("validating config file `{}`", path.display()))?;
    Ok(config)
}

impl Config {
    /// The `exempt` list for `language` (empty when the table is absent).
    pub fn exemptions(&self, language: crate::colocated_test::Language) -> &[Exemption] {
        match language {
            crate::colocated_test::Language::Python => {
                self.python.as_ref().map_or(&[], |c| &c.exempt)
            }
            crate::colocated_test::Language::TypeScript => {
                self.typescript.as_ref().map_or(&[], |c| &c.exempt)
            }
            crate::colocated_test::Language::Rust => self.rust_exemptions(),
        }
    }

    /// The `one-function-per-file` threshold for `language`, or `None` when the rule is off.
    /// Python and TypeScript default to [`OneFunctionPerFile::default`]; Rust is off until a
    /// `[rust].one_function_per_file` table opts in.
    pub fn one_function_threshold(&self, language: crate::colocated_test::Language) -> Option<u32> {
        match language {
            crate::colocated_test::Language::Python => Some(
                self.python
                    .as_ref()
                    .and_then(|c| c.one_function_per_file)
                    .unwrap_or_default()
                    .max_lines,
            ),
            crate::colocated_test::Language::TypeScript => Some(
                self.typescript
                    .as_ref()
                    .and_then(|c| c.one_function_per_file)
                    .unwrap_or_default()
                    .max_lines,
            ),
            crate::colocated_test::Language::Rust => self
                .rust
                .as_ref()
                .and_then(|c| c.one_function_per_file)
                .map(|table| table.max_lines),
        }
    }

    /// The `[[rust.exempt]]` list (empty when the table is absent).
    pub fn rust_exemptions(&self) -> &[Exemption] {
        self.rust.as_ref().map_or(&[], |c| &c.exempt)
    }

    /// Reject any `exempt` entry that names no rule or carries an empty reason.
    fn validate(&self) -> Result<()> {
        let tables = [
            ("python", self.python.as_ref().map(|c| &c.exempt)),
            ("typescript", self.typescript.as_ref().map(|c| &c.exempt)),
            ("rust", self.rust.as_ref().map(|c| &c.exempt)),
        ];
        for (table, exempt) in tables.into_iter().filter_map(|(t, e)| e.map(|e| (t, e))) {
            for entry in exempt {
                if entry.rules.is_empty() {
                    bail!(
                        "[{table}].exempt entry for `{}` names no rules — set \
                         `rules = [\"colocated-test\"]` and/or `\"coverage\"`",
                        entry.path
                    );
                }
                if entry.reason.trim().is_empty() {
                    bail!(
                        "[{table}].exempt entry for `{}` has an empty reason — \
                         every exemption must say why the file is exempt",
                        entry.path
                    );
                }
                let has_scopable = entry.rules.iter().any(|rule| rule.is_line_scopable());
                let has_whole_file = entry.rules.iter().any(|rule| !rule.is_line_scopable());
                if entry.lines.is_empty() {
                    if has_scopable {
                        let rule = entry.rules.iter().find(|r| r.is_line_scopable()).unwrap();
                        bail!(
                            "[{table}].exempt entry for `{}` names `{}` but lists no `lines` — \
                             a `coverage` / `mutation` exemption must name the exact lines it \
                             covers (whole-file exemptions are for presence / lint rules only)",
                            entry.path,
                            rule.id()
                        );
                    }
                } else {
                    if has_whole_file {
                        let rule = entry.rules.iter().find(|r| !r.is_line_scopable()).unwrap();
                        bail!(
                            "[{table}].exempt entry for `{}` has `lines` alongside rule \
                             `{}` — line-scoped exemptions apply only to `coverage` and \
                             `mutation`; move the whole-file rules to a separate entry",
                            entry.path,
                            rule.id()
                        );
                    }
                    for spec in &entry.lines {
                        let invalid = match spec {
                            LineSpec::Single(n) => *n == 0,
                            LineSpec::Range(start, end) => *start == 0 || start > end,
                        };
                        if invalid {
                            bail!(
                                "[{table}].exempt entry for `{}` has an invalid line spec — \
                                 line numbers are 1-based and a range's start must not exceed \
                                 its end",
                                entry.path
                            );
                        }
                    }
                }
            }
        }
        Ok(())
    }
}

/// The exempt paths for `rule` as `/`-joined, `root`-relative strings. A stale entry — a
/// path that no longer exists — is an error, so the exempt list can't silently rot.
pub fn resolve_exempt(
    root: &Path,
    exemptions: &[Exemption],
    rule: Rule,
) -> Result<BTreeSet<String>> {
    Ok(resolve_exempt_scoped(root, exemptions, rule)?
        .into_keys()
        .collect())
}

/// The per-file exempt [`LineScope`] for `rule`. Like [`resolve_exempt`], a stale path is a
/// hard error; two entries naming the same file merge via [`LineScope::merged_with`].
pub fn resolve_exempt_scoped(
    root: &Path,
    exemptions: &[Exemption],
    rule: Rule,
) -> Result<std::collections::BTreeMap<String, LineScope>> {
    let mut scopes: std::collections::BTreeMap<String, LineScope> =
        std::collections::BTreeMap::new();
    for entry in exemptions {
        if !entry.rules.contains(&rule) {
            continue;
        }
        if !root.join(&entry.path).is_file() {
            bail!(
                "exempt entry `{}` matches no file under `{}` — remove the stale \
                 entry or fix the path",
                entry.path,
                root.display()
            );
        }
        let key = entry.path.replace('\\', "/");
        let scope = if entry.lines.is_empty() {
            LineScope::WholeFile
        } else {
            LineScope::Lines(entry.line_set())
        };
        let merged = match scopes.remove(&key) {
            Some(existing) => existing.merged_with(scope),
            None => scope,
        };
        scopes.insert(key, merged);
    }
    Ok(scopes)
}

#[cfg(test)]
mod tests {
    use super::*;
    use std::sync::atomic::{AtomicU64, Ordering};

    fn parse(toml_src: &str) -> Result<Config> {
        let config: Config = toml::from_str(toml_src)?;
        config.validate()?;
        Ok(config)
    }

    /// The `toml::de::Error` from parsing `toml_src` into a [`Config`] — the exact error type
    /// [`annotate_toml_error`] receives from `load_config`.
    fn toml_error(toml_src: &str) -> toml::de::Error {
        toml::from_str::<Config>(toml_src).expect_err("the source should fail to parse")
    }

    #[test]
    fn annotate_points_an_unknown_key_error_at_migrations() {
        let annotated = annotate_toml_error(toml_error("[python]\nbogus = true\n"));
        let chain = format!("{annotated:#}");
        assert!(chain.contains("MIGRATIONS.md"), "got: {chain}");
        // The serde message — the rejected key and the accepted set — survives underneath.
        assert!(chain.contains("unknown field `bogus`"), "got: {chain}");
    }

    #[test]
    fn annotate_leaves_a_non_unknown_key_error_untouched() {
        // A type error is not an unknown-key rejection, so no migration pointer is appended —
        // the record has nothing to say about a well-named key given the wrong type.
        let annotated = annotate_toml_error(toml_error(
            "[python]\ncoverage = { fail_under = \"lots\" }\n",
        ));
        assert!(
            !format!("{annotated:#}").contains("MIGRATIONS.md"),
            "got: {annotated:#}"
        );
    }

    #[test]
    fn an_exemption_with_no_rules_is_rejected() {
        let err = parse(
            "[python]\ncoverage = { branch = true, fail_under = 100 }\n\
             [[python.exempt]]\npath = \"cli.py\"\nrules = []\nreason = \"shim\"\n",
        )
        .unwrap_err();
        assert!(err.to_string().contains("names no rules"), "got: {err}");
    }

    #[test]
    fn an_exemption_with_an_empty_reason_is_rejected() {
        let err = parse(
            "[python]\ncoverage = { branch = true, fail_under = 100 }\n\
             [[python.exempt]]\npath = \"cli.py\"\nrules = [\"colocated-test\"]\nreason = \"  \"\n",
        )
        .unwrap_err();
        assert!(err.to_string().contains("empty reason"), "got: {err}");
    }

    #[test]
    fn an_unknown_rule_is_rejected() {
        assert!(parse(
            "[python]\ncoverage = { branch = true, fail_under = 100 }\n\
             [[python.exempt]]\npath = \"cli.py\"\nrules = [\"packaging\"]\nreason = \"x\"\n",
        )
        .is_err());
    }

    #[test]
    fn a_wrong_typed_line_spec_names_the_expected_forms() {
        let err = parse(
            "[python]\ncoverage = { branch = true, fail_under = 100 }\n\
             [[python.exempt]]\npath = \"cli.py\"\nrules = [\"colocated-test\"]\n\
             lines = [true]\nreason = \"x\"\n",
        )
        .unwrap_err();
        assert!(
            err.to_string()
                .contains("a line number or a \"start-end\" range string"),
            "got: {err}"
        );
    }

    #[test]
    fn default_python_coverage_is_the_strict_floor() {
        // The zero-config floor is strict by default: branch on, 100.
        // Locked here so it can't silently drift from the Defaults reference.
        assert_eq!(
            PythonCoverage::default(),
            PythonCoverage {
                branch: true,
                fail_under: 100,
            }
        );
    }

    #[test]
    fn default_typescript_coverage_is_the_strict_floor() {
        // The zero-config floor is strict by default: all four metrics
        // at 100. Locked here so it can't silently drift from the Defaults reference.
        assert_eq!(
            TypeScriptCoverage::default(),
            TypeScriptCoverage {
                lines: 100,
                branches: 100,
                functions: 100,
                statements: 100,
            }
        );
    }

    #[test]
    fn default_rust_coverage_is_the_strict_line_floor() {
        assert_eq!(
            RustCoverage::default(),
            RustCoverage {
                regions: None,
                lines: 100,
                functions: None,
                branch: None,
            }
        );
    }

    #[test]
    fn rust_coverage_table_parses_with_regions_omitted() {
        // `regions` is opt-in: a `[rust].coverage` table may set `lines` alone,
        // leaving the region check off.
        let config = parse("[rust]\ncoverage = { lines = 90 }\n").unwrap();
        let coverage = config.rust.unwrap().coverage.unwrap();
        assert_eq!(coverage.regions, None);
        assert_eq!(coverage.lines, 90);
    }

    #[test]
    fn a_python_build_command_with_an_optional_reason_parses() {
        // The build_command survives, and an optional `reason` note is retained.
        let config = parse(
            "[python]\nbuild_command = \"uv run maturin develop\"\n\
             reason = \"maturin's PEP 517 backend has no pre-build shell hook\"\n",
        )
        .unwrap();
        let python = config.python.unwrap();
        assert_eq!(
            python.build_command.as_deref(),
            Some("uv run maturin develop")
        );
        assert_eq!(
            python.reason,
            "maturin's PEP 517 backend has no pre-build shell hook"
        );
    }

    #[test]
    fn a_python_build_command_with_no_reason_loads() {
        // `build_command` needs no reason — it supplies a necessary fact, it doesn't waive
        // a check. A bare command (reason serde-defaulted to empty) loads.
        let config = parse("[python]\nbuild_command = \"uv run maturin develop\"\n").unwrap();
        let python = config.python.unwrap();
        assert_eq!(
            python.build_command.as_deref(),
            Some("uv run maturin develop")
        );
        assert!(python.reason.is_empty());
    }

    #[test]
    fn a_typescript_build_command_with_no_reason_loads() {
        // The common TS case: a compile-before-pack named with no boilerplate justification.
        let config = parse("[typescript]\nbuild_command = \"pnpm build\"\n").unwrap();
        assert_eq!(
            config.typescript.unwrap().build_command.as_deref(),
            Some("pnpm build")
        );
    }

    #[test]
    fn a_valid_exemption_parses() {
        // A whole-file presence exemption (a launcher shim with no colocated test).
        let config = parse(
            "[python]\ncoverage = { branch = true, fail_under = 100 }\n\
             [[python.exempt]]\npath = \"cli.py\"\nrules = [\"colocated-test\"]\n\
             reason = \"thin launcher\"\n",
        )
        .unwrap();
        let exempt = &config.python.unwrap().exempt;
        assert_eq!(exempt.len(), 1);
        assert_eq!(exempt[0].rules, vec![Rule::ColocatedTest]);
        assert!(exempt[0].lines.is_empty());
    }

    #[test]
    fn exemptions_reads_the_rust_table() {
        let config = parse(
            "[[rust.exempt]]\npath = \"build.rs\"\nrules = [\"no-out-of-module-call\"]\n\
             reason = \"generated\"\n",
        )
        .unwrap();
        let rust = config.exemptions(crate::colocated_test::Language::Rust);
        assert_eq!(rust.len(), 1);
        assert_eq!(rust[0].path, "build.rs");
    }

    #[test]
    fn exemptions_reads_the_typescript_table() {
        let config = parse(
            "[[typescript.exempt]]\npath = \"cli.ts\"\nrules = [\"colocated-test\"]\n\
             reason = \"thin launcher\"\n",
        )
        .unwrap();
        let ts = config.exemptions(crate::colocated_test::Language::TypeScript);
        assert_eq!(ts.len(), 1);
        assert_eq!(ts[0].path, "cli.ts");
    }

    #[test]
    fn a_line_number_past_u32_is_rejected() {
        let err = toml_error(
            "[[python.exempt]]\npath = \"shim.py\"\nrules = [\"coverage\"]\n\
             lines = [4294967296]\nreason = \"dead branch\"\n",
        );
        assert!(err.to_string().contains("out of range"), "got: {err}");
    }

    #[test]
    fn a_negative_line_number_is_rejected() {
        let err = toml_error(
            "[[python.exempt]]\npath = \"shim.py\"\nrules = [\"coverage\"]\n\
             lines = [-1]\nreason = \"dead branch\"\n",
        );
        assert!(err.to_string().contains("must be positive"), "got: {err}");
    }

    /// A throwaway directory tree, removed on drop.
    struct TempTree(std::path::PathBuf);

    impl TempTree {
        fn new(files: &[&str]) -> Self {
            static COUNTER: AtomicU64 = AtomicU64::new(0);
            let root = std::env::temp_dir().join(format!(
                "tc-exempt-{}-{}",
                std::process::id(),
                COUNTER.fetch_add(1, Ordering::Relaxed),
            ));
            for rel in files {
                let path = root.join(rel);
                std::fs::create_dir_all(path.parent().unwrap()).unwrap();
                std::fs::write(path, "x = 1\n").unwrap();
            }
            TempTree(root)
        }
    }

    impl Drop for TempTree {
        fn drop(&mut self) {
            let _ = std::fs::remove_dir_all(&self.0);
        }
    }

    fn exemption(path: &str, rules: &[Rule]) -> Exemption {
        Exemption {
            path: path.to_string(),
            rules: rules.to_vec(),
            lines: vec![],
            reason: "deliberate".to_string(),
        }
    }

    #[test]
    fn resolve_keeps_only_the_requested_rule_and_returns_sorted_paths() {
        let tree = TempTree::new(&["cli.py", "pkg/gen.py", "loc_only.py"]);
        let exemptions = [
            exemption("cli.py", &[Rule::ColocatedTest, Rule::Coverage]),
            exemption("pkg/gen.py", &[Rule::Coverage]),
            exemption("loc_only.py", &[Rule::ColocatedTest]),
        ];
        let coverage = resolve_exempt(&tree.0, &exemptions, Rule::Coverage).unwrap();
        assert_eq!(
            coverage.into_iter().collect::<Vec<_>>(),
            vec!["cli.py".to_string(), "pkg/gen.py".to_string()],
        );
        let colocated_test = resolve_exempt(&tree.0, &exemptions, Rule::ColocatedTest).unwrap();
        assert_eq!(
            colocated_test.into_iter().collect::<Vec<_>>(),
            vec!["cli.py".to_string(), "loc_only.py".to_string()],
        );
    }

    #[test]
    fn a_stale_exempt_path_is_an_error() {
        let tree = TempTree::new(&["cli.py"]);
        let exemptions = [exemption("ghost.py", &[Rule::ColocatedTest])];
        let err = resolve_exempt(&tree.0, &exemptions, Rule::ColocatedTest).unwrap_err();
        assert!(err.to_string().contains("matches no file"), "got: {err}");
    }

    #[test]
    fn line_specs_parse_from_ints_and_range_strings() {
        // `lines = [9, 10, "12-13"]` — a TOML integer is a single line, a "start-end"
        // string is an inclusive range.
        let config = parse(
            "[[python.exempt]]\npath = \"shim.py\"\nrules = [\"coverage\"]\n\
             lines = [9, 10, \"12-13\"]\nreason = \"dead branch\"\n",
        )
        .unwrap();
        let exempt = &config.python.unwrap().exempt[0];
        assert_eq!(
            exempt.lines,
            vec![
                LineSpec::Single(9),
                LineSpec::Single(10),
                LineSpec::Range(12, 13),
            ]
        );
        // `line_set` expands the range and de-duplicates into a sorted set.
        assert_eq!(
            exempt.line_set().into_iter().collect::<Vec<_>>(),
            vec![9, 10, 12, 13]
        );
    }

    #[test]
    fn a_coverage_exemption_without_lines_is_rejected() {
        // `lines` is required for the measured-line rules: an exemption can't
        // lift a whole file from coverage, only the lines it can prove are uncovered.
        let err = parse(
            "[[python.exempt]]\npath = \"cli.py\"\nrules = [\"coverage\"]\nreason = \"gen\"\n",
        )
        .unwrap_err();
        assert!(err.to_string().contains("lists no `lines`"), "got: {err}");
    }

    #[test]
    fn a_mutation_exemption_without_lines_is_rejected() {
        let err = parse(
            "[[rust.exempt]]\npath = \"src/lib.rs\"\nrules = [\"mutation\"]\nreason = \"eq\"\n",
        )
        .unwrap_err();
        assert!(err.to_string().contains("lists no `lines`"), "got: {err}");
    }

    #[test]
    fn lines_on_a_whole_file_rule_is_rejected() {
        // `colocated-test` is whole-file presence, so a `lines` key alongside it can't
        // mean anything — rejected on load.
        let err = parse(
            "[[python.exempt]]\npath = \"cli.py\"\nrules = [\"colocated-test\", \"coverage\"]\n\
             lines = [3]\nreason = \"shim\"\n",
        )
        .unwrap_err();
        assert!(
            err.to_string()
                .contains("line-scoped exemptions apply only"),
            "got: {err}"
        );
    }

    #[test]
    fn a_zero_line_is_rejected() {
        let err = parse(
            "[[python.exempt]]\npath = \"cli.py\"\nrules = [\"coverage\"]\n\
             lines = [0]\nreason = \"x\"\n",
        )
        .unwrap_err();
        assert!(err.to_string().contains("invalid line spec"), "got: {err}");
    }

    #[test]
    fn a_reversed_range_is_rejected() {
        let err = parse(
            "[[python.exempt]]\npath = \"cli.py\"\nrules = [\"coverage\"]\n\
             lines = [\"13-12\"]\nreason = \"x\"\n",
        )
        .unwrap_err();
        assert!(err.to_string().contains("invalid line spec"), "got: {err}");
    }

    #[test]
    fn a_non_numeric_line_spec_is_a_parse_error() {
        // Not a line number or range at all — rejected by the deserializer.
        assert!(parse(
            "[[python.exempt]]\npath = \"cli.py\"\nrules = [\"coverage\"]\n\
             lines = [\"oops\"]\nreason = \"x\"\n",
        )
        .is_err());
    }

    #[test]
    fn resolve_scoped_distinguishes_whole_file_from_lines() {
        // A `coverage` entry resolves to its lines; a `colocated-test` entry (whole-file
        // presence) to the whole file.
        let tree = TempTree::new(&["barrel.py", "scoped.py"]);
        let exemptions = [
            exemption("barrel.py", &[Rule::ColocatedTest]),
            Exemption {
                path: "scoped.py".to_string(),
                rules: vec![Rule::Coverage],
                lines: vec![LineSpec::Single(2), LineSpec::Range(4, 5)],
                reason: "dead branch".to_string(),
            },
        ];
        let coverage = resolve_exempt_scoped(&tree.0, &exemptions, Rule::Coverage).unwrap();
        assert_eq!(
            coverage["scoped.py"],
            LineScope::Lines([2, 4, 5].into_iter().collect())
        );
        let presence = resolve_exempt_scoped(&tree.0, &exemptions, Rule::ColocatedTest).unwrap();
        assert_eq!(presence["barrel.py"], LineScope::WholeFile);
    }

    #[test]
    fn resolve_scoped_merges_two_entries_for_one_file() {
        // Two line-scoped entries for one file union their lines; two whole-file entries
        // stay whole-file.
        let tree = TempTree::new(&["a.py", "b.py"]);
        let line = |n: u32| Exemption {
            path: "a.py".to_string(),
            rules: vec![Rule::Mutation],
            lines: vec![LineSpec::Single(n)],
            reason: "equivalent mutant".to_string(),
        };
        let mutation = [line(3), line(7)];
        let scopes = resolve_exempt_scoped(&tree.0, &mutation, Rule::Mutation).unwrap();
        assert_eq!(
            scopes["a.py"],
            LineScope::Lines([3, 7].into_iter().collect())
        );

        let presence = [
            exemption("b.py", &[Rule::ColocatedTest]),
            exemption("b.py", &[Rule::ColocatedTest]),
        ];
        let scopes = resolve_exempt_scoped(&tree.0, &presence, Rule::ColocatedTest).unwrap();
        assert_eq!(scopes["b.py"], LineScope::WholeFile);
    }
}