check_floor_coverage.py

#!/usr/bin/env python3
"""check_floor_coverage.py - prove every declared error/rule code is exercised.

The mutation discipline (METHOD section 2) proves a *covered* check bites; it
never proves *coverage* - that every code a tool can emit has at least one floor
case. "Complet" was asserted by the author, never verified (METHOD v0.41). This
meta-check closes that channel. Coverage and teeth are orthogonal: this gates
the first (is there a case at all), mutation gates the second (does it bite).

The authority is the **tool**, not the floor. Each code-emitting tool declares,
at module level::

    CODES = frozenset({"R1", "R2", "R3"})   # what this tool can emit
    FLOOR = "check_remontee_runbook.py"      # the floor that exercises them

`FLOOR` is resolved relative to the tool file's own directory. A tool with no
code vocabulary (a generator, a parser, a discoverer) declares
``CODES = frozenset()`` and still names its FLOOR, so the floor is *claimed*
(see F4). Discovery mirrors discover_floors (G5): scan ``*.py`` for a
module-level ``CODES`` assignment, by AST, never by importing.

Coverage rule: a code is exercised iff it appears as a **word-bounded token**
inside some string literal of its floor - so ``R1`` matches ``["R1"]`` and
``"<label>/R1a"`` matches ``R1a`` but never ``R1`` (the trailing ``a`` is a word
char). This measures *presence of a case*, not whether it bites (teeth = mutation).

Codes this tool emits:
  F1 - a tool with a non-empty CODES set declares no FLOOR.
  F2 - a declared FLOOR path does not exist.
  F3 - a code in CODES is not exercised (no token) in its FLOOR.
  F4 - a discovered floor (# FLOOR marker, or tests/test_*.py) is claimed by no
       tool's FLOOR - an un-audited tool that never declared its registry.

Usage::

    python scripts/check_floor_coverage.py            # scan repo from cwd
    python scripts/check_floor_coverage.py <root>     # scan a given root

Exit 0 = every declared code is exercised and every floor is claimed;
exit 1 = at least one F-code fired.
"""

from __future__ import annotations

import argparse
import ast
import itertools
import re
import sys
from pathlib import Path

CODES = frozenset({"F1", "F2", "F3", "F4"})
FLOOR = "test_check_floor_coverage.py"

EXCLUDED_DIRS = {".git", ".venv", "__pycache__", "node_modules", "dist"}
FLOOR_MARKER = "# FLOOR"
MARKER_SCAN_LINES = 5


class Tool:
    def __init__(self, path: Path, codes: frozenset[str], floor: str | None) -> None:
        self.path = path
        self.codes = codes
        self.floor = floor
        self.floor_path: Path | None = None  # resolved, if it exists


class Finding:
    def __init__(self, code: str, where: Path, detail: str) -> None:
        self.code = code
        self.where = where
        self.detail = detail


def _string_set(node: ast.AST) -> frozenset[str] | None:
    if isinstance(node, ast.Call):
        func = node.func
        is_frozenset = (isinstance(func, ast.Name) and func.id == "frozenset") or (
            isinstance(func, ast.Attribute) and func.attr == "frozenset"
        )
        if is_frozenset:
            return frozenset() if not node.args else _string_set(node.args[0])
        return None
    if isinstance(node, (ast.Set, ast.List, ast.Tuple)):
        out: set[str] = set()
        for elt in node.elts:
            if isinstance(elt, ast.Constant) and isinstance(elt.value, str):
                out.add(elt.value)
            else:
                return None
        return frozenset(out)
    return None


def _module_assign(tree: ast.Module, name: str) -> ast.AST | None:
    for stmt in tree.body:
        if isinstance(stmt, ast.Assign):
            for tgt in stmt.targets:
                if isinstance(tgt, ast.Name) and tgt.id == name:
                    return stmt.value
        elif isinstance(stmt, ast.AnnAssign):
            tgt = stmt.target
            if isinstance(tgt, ast.Name) and tgt.id == name and stmt.value is not None:
                return stmt.value
    return None


def is_floor(path: Path) -> bool:
    """True iff one of the file's first lines is the bare # FLOOR marker."""
    try:
        with path.open(encoding="utf-8") as handle:
            for line in itertools.islice(handle, MARKER_SCAN_LINES):
                if line.strip() == FLOOR_MARKER:
                    return True
    except (OSError, UnicodeDecodeError):
        return False
    return False


def discover_tools(root: Path) -> list[Tool]:
    tools: list[Tool] = []
    for path in sorted(root.rglob("*.py")):
        if EXCLUDED_DIRS.intersection(path.parts):
            continue
        try:
            tree = ast.parse(path.read_text(encoding="utf-8"))
        except (OSError, UnicodeDecodeError, SyntaxError):
            continue
        codes_node = _module_assign(tree, "CODES")
        if codes_node is None:
            continue
        codes = _string_set(codes_node)
        if codes is None:
            continue
        floor_node = _module_assign(tree, "FLOOR")
        floor = (
            floor_node.value
            if isinstance(floor_node, ast.Constant) and isinstance(floor_node.value, str)
            else None
        )
        tools.append(Tool(path, codes, floor))
    return tools


def discover_floors(root: Path) -> set[Path]:
    """Every floor: a # FLOOR-marked file, or a tests/test_*.py file."""
    floors: set[Path] = set()
    for path in root.rglob("*.py"):
        if EXCLUDED_DIRS.intersection(path.parts):
            continue
        if is_floor(path) or (path.name.startswith("test_") and "tests" in path.parts):
            floors.add(path.resolve())
    return floors


def floor_string_literals(floor_path: Path) -> list[str]:
    tree = ast.parse(floor_path.read_text(encoding="utf-8"))
    return [
        node.value
        for node in ast.walk(tree)
        if isinstance(node, ast.Constant) and isinstance(node.value, str)
    ]


def _exercised(code: str, literals: list[str]) -> bool:
    """True iff `code` appears as a word-bounded token in some literal."""
    pat = re.compile(r"(?<!\w)" + re.escape(code) + r"(?!\w)")
    return any(pat.search(lit) for lit in literals)


def audit(root: Path) -> tuple[list[Tool], list[Finding]]:
    tools = discover_tools(root)
    findings: list[Finding] = []
    claimed: set[Path] = set()

    # Resolve every declared FLOOR first (so empty-CODES tools still claim theirs).
    for tool in tools:
        if tool.floor:
            resolved = (tool.path.parent / tool.floor).resolve()
            if resolved.is_file():
                tool.floor_path = resolved
                claimed.add(resolved)
            else:
                findings.append(Finding("F2", tool.path, f"FLOOR not found: {tool.floor}"))

    # F1 / F3 on code-emitting tools.
    for tool in tools:
        if not tool.codes:
            continue
        if not tool.floor:
            findings.append(Finding("F1", tool.path, "non-empty CODES but no FLOOR declared"))
            continue
        if tool.floor_path is None:
            continue  # already F2'd above
        literals = floor_string_literals(tool.floor_path)
        for code in sorted(tool.codes):
            if not _exercised(code, literals):
                findings.append(
                    Finding("F3", tool.path, f"code {code!r} never exercised in {tool.floor}")
                )

    # F4: a discovered floor that no tool claims = an un-audited tool.
    for floor in sorted(discover_floors(root)):
        if floor not in claimed:
            findings.append(
                Finding("F4", floor, "floor claimed by no tool's FLOOR (missing registry)")
            )

    return tools, findings


def main(argv: list[str] | None = None) -> int:
    parser = argparse.ArgumentParser(
        description="Prove every declared code (CODES) is exercised by its FLOOR."
    )
    parser.add_argument("root", nargs="?", default=".", help="Root to scan (default: cwd).")
    args = parser.parse_args(argv)
    root = Path(args.root).resolve()

    tools, findings = audit(root)
    emitting = [t for t in tools if t.codes]
    silent = [t for t in tools if not t.codes]

    print(f"Floor coverage : {len(tools)} tool(s) with a CODES registry under {root}")
    for tool in emitting:
        print(
            f"  [tool]  {tool.path.relative_to(root)}  ({len(tool.codes)} code(s) -> {tool.floor})"
        )
    for tool in silent:
        print(f"  [tool]  {tool.path.relative_to(root)}  (no vocabulary -> {tool.floor})")

    if not findings:
        total = sum(len(t.codes) for t in emitting)
        print(f"\nRESULT : PASS (exit 0) - {total} declared code(s) exercised, every floor claimed")
        return 0

    print()
    for f in sorted(findings, key=lambda x: (x.code, str(x.where))):
        try:
            where = f.where.relative_to(root)
        except ValueError:
            where = f.where
        print(f"  [{f.code}] {where}: {f.detail}")
    print(f"\nRESULT : FAIL (exit 1) - {len(findings)} coverage gap(s)")
    return 1


if __name__ == "__main__":
    sys.exit(main())