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:
    L3 — rule registry queries
 
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
------------
"""
 
from __future__ import annotations
 
from dataclasses import dataclass, field
 
 
# 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] = {
    "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,
    ),
    "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"],
    ),
}
 
 
def get_rule_info(name: str) -> RuleInfo | None:
    """Return the ``RuleInfo`` for *name*, or ``None`` if unknown."""
    return RULE_REGISTRY.get(name)
 
 
def list_rules() -> list[RuleInfo]:
    """Return all registered rules in registry order."""
    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