waivers.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/core/waivers.py
 
"""
Purpose
-------
OI-540 — shared inline-waiver parsing for OCT-LINT comments.
 
Extracted from :mod:`oct.linter.oct_lint` so that both the linter and
the quality gate (:mod:`oct.git.quality_gate`) can import the same
parser without the quality gate depending on the linter.
 
Responsibilities
----------------
- Host :data:`_WAIVER_RE` — the canonical regex for
  ``# OCT-LINT: disable=<rule> [reason="..."]`` comments.
- Provide :func:`parse_inline_waivers` — returns a mapping of
  line numbers to ``{"rule": str, "reason": str|None}`` dicts.
 
Diagnostics
-----------
Domain: OCT-CORE
Levels:
    (No diagnostics emitted — pure parsing helper.)
 
Contracts
---------
- Must not import :mod:`oct.linter.oct_lint` (no circular dependency).
- Return shape is stable — both linter and quality gate depend on it.
 
Dependencies
------------
"""
 
from __future__ import annotations
 
import re
 
 
_WAIVER_RE = re.compile(  # OCT-LINT: disable=no_hardcoded_secrets reason="Waiver regex pattern, not a secret"
    r'#\s*OCT-LINT:\s*disable\s*=\s*(?P<rule>[a-z_]+)(?:\s+(?P<reason>.*))?',
    re.IGNORECASE,
)
 
 
def parse_inline_waivers(text: str) -> dict[int, dict]:
    """Parse ``# OCT-LINT: disable=<rule> [reason]`` comments from source.
 
    Returns a dict mapping line numbers (1-based) to
    ``{"rule": str, "reason": str|None}``.
    """
    waivers: dict[int, dict] = {}
    for lineno, line in enumerate(text.splitlines(), 1):
        m = _WAIVER_RE.search(line)
        if m:
            reason = (m.group("reason") or "").strip() or None
            waivers[lineno] = {"rule": m.group("rule").lower(), "reason": reason}
    return waivers