rule_registry.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/linter/rule_registry.py
 
"""
Purpose
-------
Provide a structured registry of all lint rules with human-readable
documentation for each rule: rationale, correct pattern, common mistake,
spec reference, and severity tier.  Powers ``oct lint --explain <rule>``
and the linter's three-tier failure classification.
 
Responsibilities
----------------
- Define the ``RuleInfo`` dataclass that carries rule metadata.
- Populate ``RULE_REGISTRY`` with one entry per rule in ``_DEFAULT_RULES``.
- Expose ``get_rule_info()`` and ``list_rules()`` for lookup / enumeration.
- Expose :func:`get_severity` so the linter and quality gate can decide
  whether a finding blocks the build or is reported as advisory.
 
Diagnostics
-----------
Domain: OCT-LINTER
Levels:
    L2 - (none) module-load-time registry construction
    L3 - rule registry queries
    L4 - (none)
 
Contracts
---------
- Every key in ``_DEFAULT_RULES`` must have a corresponding ``RuleInfo``.
- ``RuleInfo`` is frozen - registry is immutable after module load.
- ``severity`` is one of ``"blocking"``, ``"advisory"``, or ``"info"``.
  ``blocking`` means a violation flips the run to non-zero exit;
  ``advisory`` is reported but does not affect exit code; ``info`` is
  reserved for future low-priority hints.
 
Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)
"""
 
from __future__ import annotations
 
from dataclasses import dataclass, field
from oct.core.diagnostics import _dbg
 
 
# FS-C4 / Drift item C4 - three-tier severity classification.
SEVERITY_BLOCKING = "blocking"
SEVERITY_ADVISORY = "advisory"
SEVERITY_INFO = "info"
_VALID_SEVERITIES = frozenset({SEVERITY_BLOCKING, SEVERITY_ADVISORY, SEVERITY_INFO})
 
 
@dataclass(frozen=True)
class RuleInfo:
    """Immutable documentation record for a single lint rule.
 
    The ``severity`` field (FS-C4) classifies each rule's failure mode:
 
    - ``"blocking"`` (default) - a violation flips the linter exit code
      to 1 and the quality gate to non-zero.
    - ``"advisory"`` - a violation is reported in JSON output and logs
      but does not affect exit codes. AI agents and CI can use this tier
      to surface improvement opportunities without blocking merges.
    - ``"info"`` - reserved for low-priority hints (future use).
 
    The ``severity_per_profile`` map allows a rule to be ``advisory`` at
    one profile and ``blocking`` at another (e.g. ``tests_exist`` is
    advisory at compact, blocking at strict).
    """
 
    name: str
    label: str
    rationale: str
    correct_pattern: str
    common_mistake: str
    spec_reference: str
    fixable: bool
    profiles: list[str]
    severity: str = SEVERITY_BLOCKING
    severity_per_profile: dict[str, str] = field(default_factory=dict)
 
 
RULE_REGISTRY: dict[str, RuleInfo] = {
    "syntax_error": RuleInfo(
        name="syntax_error",
        label="Source must parse (no SyntaxError)",
        rationale=(
            "A file that fails to parse is unparseable and unimportable. "
            "Every other check that relies on the parsed tree is "
            "meaningless on such a file and must not report a pass. "
            "This rule blocks at every profile so a broken file can never "
            "reach the commit gate looking compliant."
        ),
        correct_pattern=(
            "Ensure the file parses: `python -m py_compile path/to/file.py` "
            "(or `ast.parse(open(path).read())`) must not raise."
        ),
        common_mistake=(
            "An unterminated string literal, mismatched bracket, or bad "
            "indentation introduced by a manual/scripted edit that was "
            "never compiled or imported before being staged."
        ),
        spec_reference="Spec S14 - Linter Specification (workflow §11 R2)",
        fixable=False,
        profiles=["proto", "compact", "strict"],
    ),
    "header": RuleInfo(
        name="header",
        label="File header block",
        rationale=(
            "Every Python file must start with a 4-line header: shebang, "
            "encoding declaration, file-identity comment, and a blank line. "
            "This makes files self-locating and ensures consistent encoding."
        ),
        correct_pattern=(
            "#!/usr/bin/env python3\n"
            "# -*- coding: utf-8 -*-\n"
            "# path/to/module.py\n"
            ""
        ),
        common_mistake=(
            "Missing shebang, wrong encoding line, or file-identity path "
            "that does not match the file's actual location in the project."
        ),
        spec_reference="Spec S7 - File Identity and Self-Location",
        fixable=True,
        profiles=["proto", "compact", "strict"],
    ),
    "docstring": RuleInfo(
        name="docstring",
        label="Module docstring structure",
        rationale=(
            "Module docstrings must contain Purpose, Responsibilities, "
            "Diagnostics, and Contracts sections so that both humans and "
            "AI assistants can understand the module's role at a glance."
        ),
        correct_pattern=(
            '"""\n'
            "Purpose\n"
            "-------\n"
            "Brief description of what this module does.\n\n"
            "Responsibilities\n"
            "----------------\n"
            "- Bullet list of responsibilities.\n\n"
            "Diagnostics\n"
            "-----------\n"
            "Domain: MY-DOMAIN\n\n"
            "Contracts\n"
            "---------\n"
            "- Invariants and guarantees.\n"
            '"""'
        ),
        common_mistake=(
            "Missing one or more required sections (Purpose, "
            "Responsibilities, Diagnostics, Contracts) or using "
            "non-standard section headers."
        ),
        spec_reference="Spec S8 - Module Docstring Specification",
        fixable=False,
        profiles=["proto", "compact", "strict"],
    ),
    "dependencies_section": RuleInfo(
        name="dependencies_section",
        label="Module Dependencies docstring section",
        rationale=(
            "At strict profile, every module docstring must include a "
            "Dependencies section listing project-internal and notable "
            "third-party imports as ``- module_name (purpose)``. The "
            "machine-parsable form is what ``oct deps`` consumes to build "
            "the project-wide dependency graph and Sphinx documentation."
        ),
        correct_pattern=(
            "Dependencies\n"
            "------------\n"
            "- oct.core.exclusions (directory exclusion lists)\n"
            "- oc_diagnostics (structured debug logger)"
        ),
        common_mistake=(
            "Omitting the Dependencies section, missing the underline, or "
            "writing free-form bullets without the ``(purpose)`` parenthetical."
        ),
        spec_reference="Spec Appendix C - Dependencies Docstring Format",
        fixable=False,
        profiles=["strict"],
        # FS-C4: advisory at strict - surface missing sections without
        # blocking the build until the project's modules are fully
        # annotated. Promote to "blocking" once dog-fooding is complete.
        severity=SEVERITY_ADVISORY,
    ),
    "dependencies_match": RuleInfo(
        name="dependencies_match",
        label="Dependencies section matches the imports",
        rationale=(
            # OCT-LINT: disable=no_hardcoded_secrets reason="Prose rationale of the dependencies_match rule; no credential material (operator-ruled 2026-09-28)"
            "The Dependencies section is the module's declared coupling, so "
            "it must say what the module really imports: every first-party "
            "(any workspace package) and third-party import, standard "
            "library optional, and nothing it no longer imports. An import "
            "made only inside a function or under TYPE_CHECKING is declared "
            "with a purpose starting 'lazy'; oct deps leaves lazy entries out "
            "of cycle detection, because lazy imports are how the code breaks "
            "cycles. A dependency used without an import (a CLI, a subprocess, "
            "a plugin, a module loaded by name) starts its purpose with 'not "
            "imported'. Operator rulings of 2026-09-28."
        ),
        correct_pattern=(
            "Dependencies\n"
            "------------\n"
            "- click (command-line parsing)\n"
            "- oct.core.diagnostics (_dbg structured logger)\n"
            "- oct.git.quality_gate (lazy; the commit gate, imported on use)\n"
            "- uv (not imported; runs 'uv venv' for the worktree)"
        ),
        common_mistake=(
            "Declaring a package (oct.core) where the import names a module "
            "(oct.core.git); a lazy import without the 'lazy' marker; a "
            "distribution name (pyyaml) instead of the import name (yaml); "
            "an entry left behind after its import was removed."
        ),
        spec_reference="Spec Appendix C - Dependencies Docstring Format",
        fixable=False,
        profiles=["proto", "compact", "strict"],
        # Advisory at every profile: reported, never blocking. Test modules
        # are exempt inside the check itself.
        severity=SEVERITY_ADVISORY,
    ),
    "diagnostics_profile": RuleInfo(
        name="diagnostics_profile",
        label="Diagnostics profile block",
        rationale=(
            "The Diagnostics section in the module docstring must declare "
            "a Domain and at least L2/L3/L4 level descriptions so that "
            "debug output is traceable to a specific subsystem and severity."
        ),
        correct_pattern=(
            "Diagnostics\n"
            "-----------\n"
            "Domain: MY-DOMAIN\n"
            "Levels:\n"
            "    L2 - lifecycle events\n"
            "    L3 - semantic details\n"
            "    L4 - deep tracing"
        ),
        common_mistake=(
            "Omitting the Domain line, missing level descriptions, or "
            "placing the Diagnostics block outside the module docstring."
        ),
        spec_reference="Spec S11 - Diagnostics System",
        fixable=False,
        profiles=["compact", "strict"],
    ),
    "dbg_usage": RuleInfo(
        name="dbg_usage",
        label="_dbg() usage in non-trivial modules",
        rationale=(
            "Non-trivial modules (>= 20 lines) must call _dbg() at least "
            "once to ensure runtime diagnostics coverage. Silent modules "
            "are invisible to the diagnostics system."
        ),
        correct_pattern=(
            'from oc_diagnostics import _dbg\n\n'
            'func = "my_function"\n'
            '_dbg("MY-DOMAIN", func, "starting processing", 2)'
        ),
        common_mistake=(
            "Using print() instead of _dbg(), or having a non-trivial "
            "module with no diagnostics calls at all."
        ),
        spec_reference="Spec S11 - Diagnostics System, S14 - Linter Specification",
        fixable=False,
        profiles=["compact", "strict"],
    ),
    "dbg_import": RuleInfo(
        name="dbg_import",
        label="_dbg import source",
        rationale=(
            "The _dbg function must be imported from oc_diagnostics, not "
            "defined locally or imported from another location. This "
            "ensures a single canonical diagnostics pipeline."
        ),
        correct_pattern='from oc_diagnostics import _dbg',
        common_mistake=(
            "Importing _dbg from a local module, aliasing it "
            "(import _dbg as dbg), or defining a local _dbg function."
        ),
        spec_reference="Spec S11 - Diagnostics System",
        fixable=False,
        profiles=["compact", "strict"],
    ),
    "func_pattern": RuleInfo(
        name="func_pattern",
        label='func = "..." variable pattern',
        rationale=(
            "Functions that call _dbg() must define a local "
            'func = "function_name" variable so that diagnostics output '
            "includes the originating function name without relying on "
            "stack introspection."
        ),
        correct_pattern=(
            'def process_data(items: list) -> None:\n'
            '    func = "process_data"\n'
            '    _dbg("MY-DOMAIN", func, "processing", 2)'
        ),
        common_mistake=(
            "Calling _dbg() without defining func first, or defining func "
            "with a name that doesn't match the enclosing function."
        ),
        spec_reference="Spec S9 - Function Structure and Helper Extraction",
        fixable=False,
        profiles=["compact", "strict"],
    ),
    "tests_exist": RuleInfo(
        name="tests_exist",
        label="Regression test exists",
        rationale=(
            "Every module must have a corresponding test file. Testing is "
            "non-negotiable in Option C - no untested code reaches production."
        ),
        correct_pattern=(
            "Module: src/my_module.py\n"
            "Test:   tests/test_my_module.py"
        ),
        common_mistake=(
            "Creating a module without a companion test_<name>.py file, "
            "or placing the test in the wrong directory."
        ),
        spec_reference="Spec S3 - Testing Philosophy and Regression Requirements",
        fixable=False,
        profiles=["strict"],
        # FS-C4: advisory at strict. Missing tests should be visible but
        # not block routine development; use `oct git commit` with strict
        # profile to escalate to a blocking gate.
        severity=SEVERITY_ADVISORY,
    ),
    "type_hints": RuleInfo(
        name="type_hints",
        label="Type hint annotations",
        rationale=(
            "All public functions must have full type annotations on "
            "parameters and return values. This enables static analysis, "
            "improves documentation, and supports AI-assisted development."
        ),
        correct_pattern=(
            "def calculate_total(items: list[dict], tax_rate: float = 0.0) -> float:\n"
            "    ..."
        ),
        common_mistake=(
            "Missing return type annotation (use -> None for void), "
            "omitting parameter types, or using bare 'list' instead of "
            "'list[T]'."
        ),
        spec_reference="Spec S14 - Type hints enforcement",
        fixable=False,
        profiles=["compact", "strict"],
    ),
    "no_hardcoded_secrets": RuleInfo(
        name="no_hardcoded_secrets",
        label="No hardcoded secrets",
        rationale=(
            "String literals assigned to variables whose names suggest "
            "secrets (password, token, api_key, etc.) must not contain "
            "hardcoded values. Secrets belong in environment variables or "
            "secure vaults."
        ),
        correct_pattern=(
            'import os\n'
            'api_key = os.environ["API_KEY"]'
        ),
        common_mistake=(
            'Assigning a literal string to a variable named api_key, '
            'password, secret, or token: api_key = "sk-abc123..."'
        ),
        spec_reference="Spec S6b - Secret Hygiene",
        fixable=False,
        profiles=["compact", "strict"],
    ),
    "dbg_assert_safety": RuleInfo(
        name="dbg_assert_safety",
        label="_dbg assert safety",
        rationale=(
            "Calls to _dbg() must not have side effects that would change "
            "program behaviour if diagnostics are disabled. The level "
            "argument must be a literal integer, and the message must not "
            "contain function calls with side effects."
        ),
        correct_pattern=(
            '_dbg("DOMAIN", func, f"count={len(items)}", 3)'
        ),
        common_mistake=(
            "Passing a function call with side effects as the message "
            "argument, or using a variable instead of a literal for the "
            "level parameter."
        ),
        spec_reference="Spec S6a - Safety Rules",
        fixable=False,
        profiles=["strict"],
    ),
    "prompt_invariants": RuleInfo(
        name="prompt_invariants",
        label="OC Chat prompt invariants",
        rationale=(
            "The Plan 135 prompt-composition invariants (no raw tool-schema "
            "dump into the system prompt, model switches routed through "
            "ChatSession.set_model, declarative composition modes, no retired "
            "composition symbols, cache-hit vs context-saturation kept "
            "distinct) protect provider prompt-cache stability and prompt "
            "ownership. Lifted from the OC Chat pytest wrapper (Plan 140) into "
            "the strict profile at the Plan 151 monorepo migration."
        ),
        correct_pattern=(
            "Route runtime model switches through ChatSession.set_model; keep "
            "full tool schemas in the API tools parameter; use declarative "
            "mode profiles; use build_system_prompt / CANONICAL_POLICY; keep "
            "cache_hit_pct and context_used_pct on separate computations."
        ),
        common_mistake=(
            "json.dumps(tool_schemas) inside prompt construction; raw "
            "session.model assignment; if mode == 'option-c' branches; "
            "reintroducing retired composition symbols; sharing one "
            "computation for cache-hit and context-window saturation."
        ),
        spec_reference=(
            "Plan 135 section 4.7; inner-loop.md section 8; Plan 140 "
            "(invariant lint rules)"
        ),
        fixable=False,
        profiles=["strict"],
        # Plan 151 T6: enters strict as ADVISORY (matching dependencies_section
        # and tests_exist) - findings are surfaced without flipping the build
        # red, so the aggregated per-subproject strict-lint baseline is not
        # regressed. Promote to blocking once the OC Chat runtime tree is
        # confirmed clean under the migrated layout and dog-fooding completes.
        severity=SEVERITY_ADVISORY,
    ),
    "legacy_file_scoped_waiver": RuleInfo(
        name="legacy_file_scoped_waiver",
        label="Secret waiver relies on legacy whole-file scope",
        rationale=(
            "Plan 193 made secret waivers LINE-scoped: a "
            "`# OCT-LINT: disable=no_hardcoded_secrets` comment excuses "
            "its own line and the next one. Before 193 a single waiver "
            "anywhere blinded the scanner to the WHOLE file, so a real "
            "credential pasted into any waived file committed clean. "
            "Files written under the old semantics keep working - a bare "
            "waiver adjacent to none of the findings it excuses still "
            "suppresses file-wide - but each one is counted here so the "
            "migration has a visible burn-down. When this rule reports "
            "zero across the tree, the legacy fallback can be deleted "
            "as a behavioural no-op."
        ),
        # Belt-and-braces (193 R1): the example uses the ``<rule>``
        # placeholder rather than a literal rule name. ``_WAIVER_RE``'s
        # rule group is ``[a-z_]+``, so ``<rule>`` cannot match and this
        # illustration stays inert even to a line-based reader that has
        # not been taught to skip string literals.
        correct_pattern=(
            'PATTERN = "..."  # OCT-LINT: disable=<rule> reason="regex, not a credential"\n'
            "\n"
            "# ...or, for deliberate and greppable whole-file scope:\n"
            '# OCT-LINT: disable-file=<rule> reason="generated fixture module"'
        ),
        common_mistake=(
            "Parking a bare `# OCT-LINT: disable=no_hardcoded_secrets` "
            "header at the top of a file to silence one false positive "
            "further down - which also silences every real secret the "
            "file may later acquire."
        ),
        spec_reference="Spec S6b - Secret Hygiene; Plan 193 (line-scoped waivers)",
        fixable=False,
        profiles=["compact", "strict"],
        # Advisory by construction: this rule exists to make a migration
        # visible, not to block one. Promoting it to blocking would
        # storm every file it is meant to count.
        severity=SEVERITY_ADVISORY,
    ),
}
 
 
def get_rule_info(name: str) -> RuleInfo | None:
    """Return the ``RuleInfo`` for *name*, or ``None`` if unknown."""
    func = "get_rule_info"
    _dbg("OCT-LINTER", func, f"rule lookup: {name}", 4)
    return RULE_REGISTRY.get(name)
 
 
def list_rules() -> list[RuleInfo]:
    """Return all registered rules in registry order."""
    func = "list_rules"
    _dbg("OCT-LINTER", func, "listing every registered rule", 4)
    return list(RULE_REGISTRY.values())
 
 
def get_severity(rule_name: str, profile: str = "strict") -> str:
    """Return the severity tier (``blocking`` / ``advisory`` / ``info``)
    for *rule_name* under *profile* (FS-C4).
 
    Resolution order: profile-specific override → rule's default severity
    → ``"blocking"`` for unknown rules (fail-safe).
    """
    info = RULE_REGISTRY.get(rule_name)
    if info is None:
        return SEVERITY_BLOCKING
    if info.severity_per_profile and profile in info.severity_per_profile:
        candidate = info.severity_per_profile[profile]
        if candidate in _VALID_SEVERITIES:
            return candidate
    return info.severity if info.severity in _VALID_SEVERITIES else SEVERITY_BLOCKING
 
 
def is_blocking(rule_name: str, profile: str = "strict") -> bool:
    """Convenience predicate: return True iff a violation of *rule_name*
    should flip the linter / quality-gate exit code at *profile*.
    """
    return get_severity(rule_name, profile) == SEVERITY_BLOCKING