suppression_baseline_scan.py

Go to the documentation of this file.

# SPDX-License-Identifier: MIT
# Copyright (c) 2026 Brighton Sikarskie
"""Parse every authoritative ratchet baseline into suppression inventory rows."""
 
from __future__ import annotations
 
import hashlib
import json
import re
from dataclasses import dataclass
from pathlib import Path, PurePosixPath
 
from suppression_catalog import ownership
from suppression_model import Finding, Suppression
 
MIN_BASELINE_FILES = 9
PATH_COUNT_COLUMNS = 2
PATH_RULE_COUNT_COLUMNS = 3
TREE_MEASURED_COLUMNS = 6
TREE_UNMEASURED_COLUMNS = 3
TREE_METRIC_FIELDS = 4
MIN_BASELINE_ROWS = 5343
CEILING_LEDGER_PATH = ".github/suppression-debt-ceilings.tsv"
CEILING_LEDGER_SHA256 = "dcfbe6ffd0ecfe10e45646989ea32d1725d02e2c5585d3718440b27b267ce67b"
CEILING_LEDGER_HEADER = (
    "# Suppression debt per-key ceilings v1.",
    "# Key digests bind the canonical baseline path and consumer-semantic key.",
    "# Rows may disappear or decrease; a new key or weaker value is growth.",
    "# baseline<TAB>sha256<TAB>ceiling",
)
CEILING_LEDGER_COLUMNS = 3
 
 
@dataclass(frozen=True)
class BaselineSpec:
    """Grammar and provenance for one authoritative committed baseline."""
 
    tool: str
    shape: str
    consumer: str
    reason: str
    declared_pattern: str = ""
    declared_is_sum: bool = False
    key_shape: str = "path-rule"
    ceiling_shape: str = "count"
    provenance_anchors: tuple[str, ...] = ()
 
 
SPECS: dict[str, BaselineSpec] = {
    ".github/agnostic-register-baseline.txt": BaselineSpec(
        "agnostic-registers",
        "path-rule-count",
        "scripts/checks/check_agnostic_registers.py",
        "Frozen driver reach-in debt first measured by issue #698; counts may only shrink.",
        provenance_anchors=(
            "# Concrete RA8 driver reach-in debt, per (file, peripheral family).",
            "# Consumed by scripts/checks/check_agnostic_registers.py --check",
        ),
    ),
    ".github/cite-baseline.txt": BaselineSpec(
        "cite-ratchet",
        "path-count",
        "scripts/checks/cite_ratchet.py",
        "Uncited MMIO debt predating issue #534 enforcement; counts may only shrink.",
        r"Total at this baseline:\s*(\d+)\s+uncited access",
        declared_is_sum=True,
        key_shape="path",
        provenance_anchors=(
            "# HUM citation-COVERAGE ratchet baseline -- per-file uncited-access counts.",
            "# Consumed by scripts/checks/cite_ratchet.py --check (CI gate: cite-check).",
        ),
    ),
    ".github/emulator-matrix-baseline.txt": BaselineSpec(
        "emulator-matrix",
        "matrix",
        "scripts/checks/matrix_ratchet.py",
        "CI-runner emulator failures measured under issue #400 need an explained cause.",
        r"total:\s*(\d+)",
        key_shape="matrix-app",
        ceiling_shape="matrix-verdict",
        provenance_anchors=(
            "# ra8_emulator example-matrix baseline -- see scripts/checks/matrix_ratchet.py",
            "# MEASURE THIS ON THE CI RUNNER, NEVER ON A DEVELOPER BOX -- see #400.",
        ),
    ),
    ".github/freestanding-runtime-baseline.json": BaselineSpec(
        "freestanding-runtime",
        "freestanding-apps",
        "scripts/checks/check_freestanding_runtime.py",
        "Zero-debt freestanding target ratchet from issue #847; per-app debt may only shrink.",
        key_shape="rule",
        ceiling_shape="count",
    ),
    ".github/hum-register-baseline.txt": BaselineSpec(
        "hum-register-map",
        "path-rule-count",
        "scripts/checks/check_hum_register_map.py",
        "Frozen register-map migration debt checked against the committed HUM.",
        provenance_anchors=(
            "# HUM register-map debt, per (file, rule). Generated by",
            "# scripts/checks/check_hum_register_map.py --update.",
        ),
    ),
    ".github/mcdc-baseline.txt": BaselineSpec(
        "llvm-cov-mcdc",
        "percentage",
        "scripts/ci/gates/tests.sh",
        "Aggregate MC/DC floor frozen from the pinned llvm-cov measurement.",
        key_shape="repository",
        ceiling_shape="percentage",
        provenance_anchors=(
            "# Aggregate reachable decision-complete MC/DC percentage ratchet floor.",
            "# Consumed by scripts/ci/gates/tests.sh (CI gate: mcdc).",
        ),
    ),
    ".github/mcdc-compound-baseline.txt": BaselineSpec(
        "mcdc-compound-ratchet",
        "path-rule-count",
        "scripts/checks/mcdc_compound_ratchet.py",
        "Compound decisions predating issue #426 enforcement; counts may only shrink.",
        r"Total at this baseline:\s*(\d+)\s+uncovered compound decision",
        declared_is_sum=True,
        provenance_anchors=(
            "# MC/DC compound-decision ratchet baseline -- per-file-per-function counts.",
            "# Consumed by scripts/checks/mcdc_compound_ratchet.py --check",
        ),
    ),
    ".github/misra-baseline.txt": BaselineSpec(
        "misra-ratchet",
        "path-rule-count",
        "scripts/checks/misra_ratchet.py",
        "Cppcheck 2.13 debt with migration provenance in issues #786 and #790.",
        r"total findings:\s*(\d+)",
        declared_is_sum=True,
        provenance_anchors=(
            "# MISRA-C 2012 ratchet baseline -- per-file-per-rule finding counts.",
            "# Consumed by scripts/checks/misra_ratchet.py --check (CI job: misra).",
        ),
    ),
    ".github/tidy-baseline.txt": BaselineSpec(
        "clang-tidy-ratchet",
        "path-rule-count",
        "scripts/checks/tidy_ratchet.py",
        "Findings exposed by issue #369 and #370 scope expansion; counts may only shrink.",
        provenance_anchors=(
            "# clang-tidy ratchet baseline -- per-file-per-check finding counts.",
            "# Consumed by scripts/checks/tidy_ratchet.py --check (CI gate: tidy).",
        ),
    ),
    ".github/tree-coverage-baseline.txt": BaselineSpec(
        "tree-coverage",
        "tree-coverage",
        "scripts/checks/check_tree_coverage.py",
        "Single-tree debt from the pinned gcovr producer; coverage may only improve.",
        r"rows:\s*(\d+)",
        key_shape="path",
        ceiling_shape="tree-coverage",
        provenance_anchors=(
            "# ONE coverage baseline for every first-party translation unit.",
            "# Emitted by `python3 scripts/checks/check_tree_coverage.py --update`.",
        ),
    ),
}
BASELINE_CEILINGS: dict[str, tuple[int, int]] = {
    ".github/agnostic-register-baseline.txt": (292, 672),
    ".github/cite-baseline.txt": (246, 2831),
    ".github/emulator-matrix-baseline.txt": (0, 0),
    ".github/freestanding-runtime-baseline.json": (7, 0),
    ".github/hum-register-baseline.txt": (46, 451),
    ".github/mcdc-baseline.txt": (1, 1),
    ".github/mcdc-compound-baseline.txt": (957, 1693),
    ".github/misra-baseline.txt": (2710, 20014),
    ".github/tidy-baseline.txt": (96, 121),
    ".github/tree-coverage-baseline.txt": (1059, 9404),
}
BASELINE_PERCENTAGE_FLOORS = {".github/mcdc-baseline.txt": 89.72}
 
 
KNOWN_MATRIX_VERDICTS = frozenset({"FAULT", "TRUNCATED", "UNKNOWN", "BUILD_FAIL", "NO_ELF"})
KNOWN_TREE_REASONS = frozenset(
    {
        "compiled-not-executed",
        "firmware-composition",
        "hosted-no-coverage-build",
        "platform-cross-only",
    }
)
DebtRow = tuple[str, str, int, str]
CeilingLedger = dict[str, tuple[str, str]]
ValidationContext = tuple[
    Path,
    str,
    BaselineSpec,
    dict[str, int],
    CeilingLedger | None,
    list[Finding],
]
SAFE_RULE_RE = re.compile(r"[A-Za-z0-9_.+@()/-]+")
PERCENT_RE = re.compile(r"(?:100(?:\.0+)?|[0-9]{1,2}(?:\.[0-9]+)?)")
SHA256_RE = re.compile(r"[0-9a-f]{64}")
 
 
def _safe_target(value: str) -> bool:
    """Return whether a target is one canonical safe repository-relative path."""
    path = PurePosixPath(value)
    return (
        bool(value)
        and bool(path.parts)
        and "\\" not in value
        and not path.is_absolute()
        and ".." not in path.parts
        and value == path.as_posix()
    )
 
 
def _semantic_key(spec: BaselineSpec, target: str, rule: str) -> str:
    """Return the baseline consumer's canonical bucket identity."""
    if spec.key_shape == "path-rule":
        return f"{target}\0{rule}"
    if spec.key_shape == "path":
        return target
    if spec.key_shape == "rule":
        return rule
    if spec.key_shape == "repository":
        return "repository"
    raise ValueError(spec.key_shape)
 
 
def _ceiling_key(baseline: str, semantic_key: str) -> str:
    """Hash one canonical consumer bucket together with its owning baseline."""
    payload = f"{baseline}\0{semantic_key}".encode("ascii")
    return hashlib.sha256(payload).hexdigest()
 
 
def _record_evidence(record: Suppression, prefix: str) -> str:
    """Return one required evidence value from a suppression record."""
    return next(item.removeprefix(prefix) for item in record.evidence if item.startswith(prefix))
 
 
def _record(
    baseline: str,
    line: int,
    spec: BaselineSpec,
    debt: DebtRow,
    *,
    ceiling: tuple[str, str] = ("", ""),
) -> Suppression:
    """Build one source-located ratchet inventory row."""
    target, rule, count, reason = debt
    semantic_key, ceiling_value = ceiling
    key = semantic_key or _semantic_key(spec, target, rule)
    value = ceiling_value or ("present" if spec.ceiling_shape == "presence" else str(count))
    return Suppression(
        baseline,
        line,
        1,
        "baseline-ratchet",
        spec.tool,
        rule,
        "committed-baseline",
        "repository" if not target else f"file:{target}",
        reason or spec.reason,
        "ratchet-baseline",
        ownership(target) if target else "first-party",
        (),
        evidence=(
            f"consumer:{spec.consumer}",
            f"target:{target or 'repository'}",
            f"frozen-count:{count}",
            f"ceiling-key:{_ceiling_key(baseline, key)}",
            f"ceiling-value:{value}",
        ),
        match_count=count,
        recommendation="burn-down-only",
    )
 
 
ParseResult = tuple[Suppression | None, str]
 
 
def _positive_count(value: str) -> int | None:
    """Parse a strictly positive decimal baseline count."""
    return int(value) if re.fullmatch(r"[1-9][0-9]*", value) else None
 
 
def _parse_path_rule_count(baseline: str, line: int, raw: str, spec: BaselineSpec) -> ParseResult:
    """Parse path, rule, and count fields."""
    fields = raw.split("\t")
    if len(fields) != PATH_RULE_COUNT_COLUMNS:
        return None, "expected path<TAB>rule<TAB>count"
    target, rule, count_text = fields
    count = _positive_count(count_text)
    if not _safe_target(target) or SAFE_RULE_RE.fullmatch(rule) is None or count is None:
        return None, "invalid path, rule, or positive count"
    return _record(baseline, line, spec, (target, rule, count, "")), ""
 
 
def _parse_path_count(baseline: str, line: int, raw: str, spec: BaselineSpec) -> ParseResult:
    """Parse path and count fields."""
    fields = raw.split("\t")
    if len(fields) != PATH_COUNT_COLUMNS:
        return None, "expected path<TAB>count"
    target, count_text = fields
    count = _positive_count(count_text)
    if not _safe_target(target) or count is None:
        return None, "invalid path or positive count"
    return _record(baseline, line, spec, (target, "uncited-mmio", count, "")), ""
 
 
def _parse_path(baseline: str, line: int, raw: str, spec: BaselineSpec) -> ParseResult:
    """Parse one repository-relative path."""
    if "\t" in raw or not _safe_target(raw):
        return None, "expected one repository-relative path"
    return _record(baseline, line, spec, (raw, "historical-gap", 1, "")), ""
 
 
def _parse_percentage(baseline: str, line: int, raw: str, spec: BaselineSpec) -> ParseResult:
    """Parse one aggregate percentage floor."""
    if PERCENT_RE.fullmatch(raw) is None:
        return None, "expected one percentage in the inclusive range 0..100"
    reason = f"Aggregate MC/DC may not fall below {raw}%."
    return (
        _record(
            baseline,
            line,
            spec,
            ("", "aggregate-mcdc-floor", 1, reason),
            ceiling=("", raw),
        ),
        "",
    )
 
 
def _parse_matrix(baseline: str, line: int, raw: str, spec: BaselineSpec) -> ParseResult:
    """Parse one explained emulator debt row."""
    fields = raw.split("\t")
    if len(fields) != PATH_RULE_COUNT_COLUMNS:
        return None, "expected app<TAB>verdict<TAB>cause"
    app, verdict, cause = fields
    if not _safe_target(app) or verdict not in KNOWN_MATRIX_VERDICTS or not cause.strip():
        return None, "unknown verdict or blank failure cause"
    return (
        _record(
            baseline,
            line,
            spec,
            ("", verdict, 1, cause.strip()),
            ceiling=(app, verdict),
        ),
        "",
    )
 
 
def _parse_tree_coverage(baseline: str, line: int, raw: str, spec: BaselineSpec) -> ParseResult:
    """Parse gcovr measured and declared-unmeasured rows."""
    fields = raw.split("\t")
    if len(fields) == TREE_UNMEASURED_COLUMNS and fields[1] == "UNMEASURED":
        target, _kind, reason = fields
        if not _safe_target(target) or reason not in KNOWN_TREE_REASONS:
            return None, "invalid UNMEASURED path or reason class"
        debt = (target, f"unmeasured:{reason}", 1, reason)
        return _record(baseline, line, spec, debt, ceiling=("", f"U:{reason}")), ""
    if len(fields) == TREE_MEASURED_COLUMNS and fields[1] == "MEASURED":
        target = fields[0]
        counts = fields[2:]
        if not _safe_target(target) or any(not value.isdecimal() for value in counts):
            return None, "invalid MEASURED path or non-negative counts"
        covered_line, total_line, covered_branch, total_branch = map(int, counts)
        if covered_line > total_line or covered_branch > total_branch:
            return None, "covered count exceeds total count"
        debt = (total_line - covered_line) + (total_branch - covered_branch)
        row = (target, "measured-line-branch-floor", max(debt, 1), "")
        value = f"M:{covered_line},{total_line},{covered_branch},{total_branch}"
        return _record(baseline, line, spec, row, ceiling=("", value)), ""
    return None, "expected a tool-emitted MEASURED or UNMEASURED row"
 
 
def _parse_opaque(baseline: str, line: int, raw: str, spec: BaselineSpec) -> ParseResult:
    """Parse one nonempty checker-owned key."""
    if not raw.strip() or "\t" in raw:
        return None, "expected one nonempty checker-owned key"
    return _record(baseline, line, spec, ("", raw.strip(), 1, "")), ""
 
 
def _freestanding_archive_units(archives: object) -> int | None:
    """Count live-archive debt units, or None when malformed."""
    if not isinstance(archives, dict):
        return None
    members = 0
    for name, items in archives.items():
        if not isinstance(name, str) or not isinstance(items, list):
            return None
        if not all(isinstance(m, str) for m in items):
            return None
        members += len(items)
    return members
 
 
def _freestanding_units(entry: object) -> int | None:
    """Count debt units in one freestanding app entry, or None when malformed."""
    if not isinstance(entry, dict):
        return None
    symbols = entry.get("forbidden_symbols")
    if not isinstance(symbols, list) or not all(isinstance(s, str) for s in symbols):
        return None
    members = _freestanding_archive_units(entry.get("forbidden_archives"))
    provider = entry.get("sbrk_provider")
    end = entry.get("end_symbol")
    if members is None or not isinstance(provider, str) or not isinstance(end, bool):
        return None
    return len(symbols) + members + (0 if provider == "none" else 1) + (1 if end else 0)
 
 
def _json_key_line(text: str, key: str) -> int:
    """Return the 1-based line defining one JSON object key."""
    match = re.search(r'"' + re.escape(key) + r'"\s*:', text)
    if match is None:
        return 1
    return text.count("\n", 0, match.start()) + 1
 
 
def _freestanding_rows(
    text: str,
) -> tuple[list[tuple[DebtRow, int]], str]:
    """Parse the freestanding JSON ratchet into located per-app debt rows."""
    try:
        data = json.loads(text)
    except json.JSONDecodeError:
        return [], "baseline is not valid JSON"
    if not isinstance(data, dict):
        return [], "baseline root must be an object"
    apps = data.get("apps")
    exceptions = data.get("linker_script_exceptions")
    if not isinstance(apps, dict) or not isinstance(exceptions, list):
        return [], "baseline must define apps and linker_script_exceptions"
    if not all(isinstance(e, str) for e in exceptions):
        return [], "linker_script_exceptions must list strings"
    rows, error = _freestanding_app_rows(text, apps)
    if error:
        return [], error
    rows.append(
        (
            ("", "linker-script-exceptions", len(exceptions), ""),
            _json_key_line(text, "linker_script_exceptions"),
        )
    )
    return rows, ""
 
 
def _freestanding_app_rows(
    text: str, apps: dict[object, object]
) -> tuple[list[tuple[DebtRow, int]], str]:
    """Parse sorted per-app debt rows with source locations."""
    names = sorted(app for app in apps if isinstance(app, str))
    if len(names) != len(apps):
        return [], "app keys must be strings"
    rows: list[tuple[DebtRow, int]] = []
    for app in names:
        if SAFE_RULE_RE.fullmatch(app) is None:
            return [], f"unsafe app key {app!r}"
        units = _freestanding_units(apps[app])
        if units is None:
            return [], f"malformed app entry {app!r}"
        rows.append((("", app, units, ""), _json_key_line(text, app)))
    return rows, ""
 
 
PARSERS = {
    "path-rule-count": _parse_path_rule_count,
    "path-count": _parse_path_count,
    "path": _parse_path,
    "percentage": _parse_percentage,
    "matrix": _parse_matrix,
    "tree-coverage": _parse_tree_coverage,
    "opaque": _parse_opaque,
}
 
 
def _validate_target(
    root: Path, baseline: str, record: Suppression, findings: list[Finding]
) -> None:
    """Reject stale paths and exempt-owner baseline rows."""
    target = next(
        item.removeprefix("target:") for item in record.evidence if item.startswith("target:")
    )
    if target == "repository":
        return
    if not (root / target).is_file():
        findings.append(Finding("stale-baseline-path", target, baseline, record.line))
    if record.owner != "first-party":
        message = f"{target} is {record.owner}"
        findings.append(Finding("baseline-owner-mismatch", message, baseline, record.line))
 
 
def _only_lost_code(now: tuple[int, int], base: tuple[int, int]) -> bool:
    """Return whether a smaller metric lost no more covered than total items."""
    covered, total = now
    base_covered, base_total = base
    return (total < base_total) and ((base_covered - covered) <= (base_total - total))
 
 
def _metric_regressed(now: tuple[int, int], base: tuple[int, int]) -> bool:
    """Return whether uncovered debt grew or a non-shrink ratio fell."""
    covered, total = now
    base_covered, base_total = base
    debt_grew = (total - covered) > (base_total - base_covered)
    ratio_fell = (
        base_total > 0
        and covered * base_total < base_covered * total
        and not _only_lost_code(now, base)
    )
    return debt_grew or ratio_fell
 
 
def _tree_value(value: str) -> tuple[str, tuple[int, ...] | str] | None:
    """Parse one compact tree-coverage ceiling value."""
    if value.startswith("U:") and value.removeprefix("U:") in KNOWN_TREE_REASONS:
        return "U", value.removeprefix("U:")
    if value.startswith("M:"):
        fields = value.removeprefix("M:").split(",")
        if len(fields) == TREE_METRIC_FIELDS and all(field.isdecimal() for field in fields):
            counts = tuple(int(field) for field in fields)
            if counts[0] <= counts[1] and counts[2] <= counts[3]:
                return "M", counts
    return None
 
 
def _tree_regressed(candidate: str, audited: str) -> bool:
    """Return whether a candidate tree row weakens its audited per-metric floor."""
    now = _tree_value(candidate)
    base = _tree_value(audited)
    regressed = now is None or base is None
    if now is not None and base is not None:
        now_kind, now_value = now
        base_kind, base_value = base
        if base_kind == "U" and now_kind == "U":
            regressed = now_value != base_value
        elif base_kind == "U" and isinstance(now_value, tuple):
            line_ok = now_value[1] == 0 or now_value[0] * 100 >= now_value[1] * 90
            branch_ok = now_value[3] == 0 or now_value[2] * 100 >= now_value[3] * 80
            regressed = not (line_ok and branch_ok)
        elif (
            base_kind == "M"
            and now_kind == "M"
            and isinstance(now_value, tuple)
            and isinstance(base_value, tuple)
        ):
            regressed = _metric_regressed(now_value[:2], base_value[:2]) or _metric_regressed(
                now_value[2:], base_value[2:]
            )
        else:
            regressed = True
    return regressed
 
 
def _ceiling_regressed(spec: BaselineSpec, candidate: str, audited: str) -> bool:
    """Compare one candidate value with its immutable per-key ceiling."""
    if spec.ceiling_shape == "count":
        return not candidate.isdecimal() or not audited.isdecimal() or int(candidate) > int(audited)
    if spec.ceiling_shape == "presence":
        return candidate != "present" or audited != "present"
    if spec.ceiling_shape == "percentage":
        return PERCENT_RE.fullmatch(candidate) is None or float(candidate) < float(audited)
    if spec.ceiling_shape == "matrix-verdict":
        return candidate != audited
    if spec.ceiling_shape == "tree-coverage":
        return _tree_regressed(candidate, audited)
    return True
 
 
def ceiling_snapshot(records: list[Suppression]) -> CeilingLedger:
    """Return the immutable semantic-key ceiling map represented by records."""
    return {
        _record_evidence(record, "ceiling-key:"): (
            record.path,
            _record_evidence(record, "ceiling-value:"),
        )
        for record in records
    }
 
 
def _parse_ceiling_ledger(text: str) -> tuple[CeilingLedger, list[str]]:
    """Parse the exact committed ceiling-ledger grammar."""
    lines = text.splitlines()
    errors: list[str] = []
    if tuple(lines[: len(CEILING_LEDGER_HEADER)]) != CEILING_LEDGER_HEADER:
        errors.append("header does not match the authenticated v1 ledger header")
    ledger: CeilingLedger = {}
    for line_no, raw in enumerate(lines[len(CEILING_LEDGER_HEADER) :], start=5):
        if not raw:
            continue
        fields = raw.split("\t")
        if len(fields) != CEILING_LEDGER_COLUMNS:
            errors.append(f"line {line_no}: expected baseline<TAB>sha256<TAB>ceiling")
            continue
        baseline, digest, value = fields
        if baseline not in SPECS or SHA256_RE.fullmatch(digest) is None or not value:
            errors.append(f"line {line_no}: invalid baseline, digest, or ceiling")
            continue
        if digest in ledger:
            errors.append(f"line {line_no}: duplicate digest {digest}")
            continue
        ledger[digest] = (baseline, value)
    return ledger, errors
 
 
def _load_ceiling_ledger(root: Path) -> tuple[CeilingLedger, list[Finding]]:
    """Load and authenticate the committed per-key ceiling ledger."""
    path = root / CEILING_LEDGER_PATH
    if not path.is_file():
        return {}, [Finding("missing-baseline-ceilings", CEILING_LEDGER_PATH)]
    raw = path.read_bytes()
    digest = hashlib.sha256(raw).hexdigest()
    findings: list[Finding] = []
    if digest != CEILING_LEDGER_SHA256:
        findings.append(
            Finding(
                "baseline-ceiling-integrity",
                f"ledger sha256 {digest} does not match {CEILING_LEDGER_SHA256}",
                CEILING_LEDGER_PATH,
            )
        )
    try:
        text = raw.decode("ascii")
    except UnicodeDecodeError as error:
        decode_finding = Finding("baseline-ceiling-integrity", str(error), CEILING_LEDGER_PATH)
        return {}, [*findings, decode_finding]
    ledger, errors = _parse_ceiling_ledger(text)
    findings.extend(
        Finding("baseline-ceiling-integrity", message, CEILING_LEDGER_PATH) for message in errors
    )
    return ledger, findings
 
 
def _validate_ceiling(
    baseline: str,
    spec: BaselineSpec,
    record: Suppression,
    ledger: CeilingLedger,
    findings: list[Finding],
) -> None:
    """Reject a new semantic bucket or a weaker value for an audited bucket."""
    digest = _record_evidence(record, "ceiling-key:")
    candidate = _record_evidence(record, "ceiling-value:")
    entry = ledger.get(digest)
    if entry is None:
        findings.append(
            Finding("baseline-growth", "new consumer-semantic debt bucket", baseline, record.line)
        )
        return
    owner, audited = entry
    if owner != baseline or _ceiling_regressed(spec, candidate, audited):
        message = f"bucket ceiling {audited!r} weakened to {candidate!r}"
        findings.append(Finding("baseline-growth", message, baseline, record.line))
 
 
def _accept_record(record: Suppression, context: ValidationContext) -> None:
    """Apply semantic duplicate, target, ceiling, and percentage validation."""
    root, baseline, spec, keys, ledger, findings = context
    key = _record_evidence(record, "ceiling-key:")
    prior = keys.get(key)
    if prior is not None:
        message = f"consumer-semantic key duplicates line {prior}"
        findings.append(Finding("duplicate-baseline-row", message, baseline, record.line))
    else:
        keys[key] = record.line
    _validate_target(root, baseline, record, findings)
    if ledger is not None:
        _validate_ceiling(baseline, spec, record, ledger, findings)
    minimum = BASELINE_PERCENTAGE_FLOORS.get(baseline)
    value = _record_evidence(record, "ceiling-value:")
    if minimum is not None and float(value) < minimum:
        message = f"{value}% is below the audited {minimum:.2f}% floor"
        findings.append(Finding("baseline-growth", message, baseline, record.line))
 
 
def _parse_file(
    root: Path, baseline: str, spec: BaselineSpec, ledger: CeilingLedger | None
) -> tuple[list[Suppression], list[Finding]]:
    """Parse and structurally validate one committed baseline."""
    text = (root / baseline).read_text(encoding="ascii")
    if spec.shape == "freestanding-apps":
        return _parse_freestanding_file(root, baseline, spec, ledger)
    records: list[Suppression] = []
    findings: list[Finding] = []
    keys: dict[str, int] = {}
    parser = PARSERS[spec.shape]
    exact_lines = frozenset(text.splitlines())
    findings.extend(
        Finding("missing-baseline-provenance", repr(anchor), baseline)
        for anchor in spec.provenance_anchors
        if anchor not in exact_lines
    )
    for line_no, raw in enumerate(text.splitlines(), start=1):
        if not raw.strip() or raw.lstrip().startswith("#"):
            continue
        record, error = parser(baseline, line_no, raw, spec)
        if record is None:
            findings.append(Finding("malformed-baseline-row", error, baseline, line_no))
            continue
        _accept_record(record, (root, baseline, spec, keys, ledger, findings))
        records.append(record)
    findings.extend(_check_file_totals(baseline, spec, records, text))
    return records, findings
 
 
def _check_file_totals(
    baseline: str, spec: BaselineSpec, records: list[Suppression], text: str
) -> list[Finding]:
    """Enforce audited row/unit ceilings and declared totals for one baseline."""
    findings: list[Finding] = []
    row_ceiling, unit_ceiling = BASELINE_CEILINGS[baseline]
    units = sum(item.match_count for item in records)
    if len(records) > row_ceiling or units > unit_ceiling:
        message = (
            f"parsed {len(records)} row(s)/{units} debt unit(s); "
            f"audited ceilings are {row_ceiling}/{unit_ceiling}"
        )
        findings.append(Finding("baseline-growth", message, baseline))
    if spec.declared_pattern:
        match = re.search(spec.declared_pattern, text, re.IGNORECASE)
        if match is None:
            findings.append(Finding("missing-baseline-total", spec.declared_pattern, baseline))
        else:
            declared = int(match.group(1))
            actual = (
                sum(item.match_count for item in records) if spec.declared_is_sum else len(records)
            )
            if declared != actual:
                message = f"declares {declared}, parsed {actual}"
                findings.append(Finding("stale-baseline-total", message, baseline))
    return findings
 
 
def _parse_freestanding_file(
    root: Path, baseline: str, spec: BaselineSpec, ledger: CeilingLedger | None
) -> tuple[list[Suppression], list[Finding]]:
    """Parse the freestanding JSON ratchet through the shared validation path."""
    text = (root / baseline).read_text(encoding="ascii")
    records: list[Suppression] = []
    findings: list[Finding] = []
    keys: dict[str, int] = {}
    rows, error = _freestanding_rows(text)
    if error:
        return [], [Finding("malformed-baseline-row", error, baseline)]
    for debt, line_no in rows:
        record = _record(baseline, line_no, spec, debt)
        _accept_record(record, (root, baseline, spec, keys, ledger, findings))
        records.append(record)
    findings.extend(_check_file_totals(baseline, spec, records, text))
    return records, findings
 
 
def scan_baseline_repository(
    root: Path,
    paths: list[str],
    *,
    enforce_floors: bool,
    ceiling_ledger: CeilingLedger | None = None,
) -> tuple[list[Suppression], list[Finding]]:
    """Discover, parse, and inventory all authoritative ratchet baselines."""
    authorities = sorted(
        rel
        for rel in paths
        if rel.startswith(".github/")
        and re.search(r"baseline|ratchet", PurePosixPath(rel).name, re.IGNORECASE)
    )
    discovered = [rel for rel in authorities if rel in SPECS]
    records: list[Suppression] = []
    findings = [
        Finding("unknown-baseline-file", authority, authority)
        for authority in authorities
        if authority not in SPECS
    ]
    ledger = ceiling_ledger
    if enforce_floors and ledger is None:
        ledger, ledger_findings = _load_ceiling_ledger(root)
        findings.extend(ledger_findings)
    for baseline in discovered:
        spec = SPECS[baseline]
        if not (root / spec.consumer).is_file():
            findings.append(Finding("missing-baseline-consumer", spec.consumer, baseline))
        parsed, errors = _parse_file(root, baseline, spec, ledger)
        records.extend(parsed)
        findings.extend(errors)
    if enforce_floors:
        findings.extend(
            Finding("missing-baseline-file", baseline, baseline)
            for baseline in sorted(set(SPECS) - set(discovered))
        )
        if len(discovered) < MIN_BASELINE_FILES:
            message = f"only {len(discovered)} files; floor is {MIN_BASELINE_FILES}"
            findings.append(Finding("vacuous-baseline-files", message))
        if len(records) < MIN_BASELINE_ROWS:
            message = f"only {len(records)} rows; audited floor is {MIN_BASELINE_ROWS}"
            findings.append(Finding("vacuous-baseline-rows", message))
    return records, findings