latent.lint.baseline

latent lint baseline — the count-per-rule×file ratchet lockfile.

Schema: {rule_id: {repo_relative_posix_path: count}} in .lint-baseline.yaml — the twin of config/thresholds.yaml. Counts are a ratchet, never an allowlist of lines: a (rule, file) group may hold at or below its baselined count and trips on any increase; absence means allowed 0. Stdlib + pyyaml only; never imports the rest of latent — the atomic-write pattern is duplicated from latent/stats/thresholds.py deliberately (pattern reuse, not import; ADR-003 §B).

Classes

Exceedance

Exceedance(rule: str, path: str, actual: int, allowed: int)

A (rule, file) whose unwaived-finding count exceeds its baseline allowance.

Functions

compare

compare(findings: Iterable[Finding], baseline: dict[str, dict[str, int]]) -> list[Exceedance]

(rule, file) groups whose unwaived count exceeds the baseline allowance.

Absent from the baseline means allowed 0, so with an empty baseline every unwaived finding is an exceedance — exactly the no-baseline behavior. Baseline entries with no matching findings (fixed violations) are not exceedances: the ratchet only trips upward; baseline write reclaims.

default_baseline_path

default_baseline_path(repo_root: Path | str) -> Path

/.lint-baseline.yaml — the only path the CLI uses.

A dotfile at the root, not config/: the ratchet is generated bookkeeping a consumer never edits by hand, and it should not sit in their config directory looking like something they are meant to tune. config/lint.yaml — which they DO edit — stays where it is.

load_baseline

load_baseline(path: Path | str) -> dict[str, dict[str, int]]

Parse a lint baseline; absent file -> {}. Malformed raises ValueError.

write_baseline

write_baseline(findings: Iterable[Finding], path: Path | str) -> None

Write the ratchet file: unwaived counts, sorted both levels, atomic.

Raises ValueError when findings contain LT999 — a run with engine errors undercounts (unparsed files contributed no rule findings) and must not be grandfathered.