orchestrata_ultimate.core.gate_waivers

Reference › orchestrata_ultimate › core › gate_waivers

The single reader of the # gate-ok: per-line waiver convention. Several checkers honour the marker, and each used to carry its own regular expression and its own idea of which lines a marker covers; the Prolog gate's fact extractor (fact_extractor) and the secret-leak and parallel-safety scripts now share this module instead.

A marker waives a line only when a reason follows the colon (WAIVER_RE), so an unexplained marker waives nothing. A marker covers its own line and the one below it (WAIVER_REACH is 1). waived_lines(text) returns the covered 1-based line numbers, waiver_reasons(text) maps each covered line to its reason, and is_waived(path, lineno) reads a file and answers for one line.

At a glance

Class diagram

No classes; see Functions.

Dependency diagram

API

Functions

Source

Permalink: https://gitlab.com/MSamy/orchestrata-ultimate-architecture/-/blob/a4cbc2bdf/src/orchestrata_ultimate/core/gate_waivers.py

"""The ``# gate-ok:`` waiver convention, read from one place by everything.

This project has declared a reasoned per-line waiver since long before the
Prolog gate existed, and SIX checkers honour it: ``gate_parallel_safety.py``,
``check_graph_write_swallow.py``, ``graph_test_preflight.py``, ``test-review.py``
(T5), ``test_isolation_audit.py``, and now the Prolog gate. Each of the first
five carried its own copy of the regex and its own idea of which lines a marker
covers — the same hardcoded-copy defect measured twice already in this phase
(``_FORBIDDEN_IMPORTS = {"pyswip"}``; the codemod's ban tuple), so the reader
lives here once.

WHY A WAIVER EXISTS AT ALL. A rule states a property that is USUALLY a defect.
A handful of sites are the exception on the merits — a fixture that saves and
restores an env var around a subprocess it must configure, a test whose SUBJECT
is the env-precedence behaviour itself. Those need a decision recorded AT the
line, in review, by a person. That is what the marker is: not a mute button but
a signed statement, which is why a bare ``# gate-ok:`` with no reason does not
waive anything.

WHY THE PROLOG GATE NEEDS IT. ``bare_os_environ`` and ``env_mutation`` replace
``test_isolation_audit``'s ``OS_ENVIRON_MUTATION``, and that checker honours
this convention (its ``_WAIVER_RE`` and the ``continue  # explicit gate-ok``
branch). A replacement that ignores it does not find MORE, it finds WRONG: on
2026-08-08, the first run over the widened snapshot reported 47 env mutations of
which 37 carried a reasoned waiver written by whoever last audited them.
Comments are not in the AST, so the fact base has to carry them explicitly —
the same way it carries the ban registry and the ruff catalogue (REQ-GATE-010).
"""

from __future__ import annotations

import re
from pathlib import Path

#: A marker with no reason after the colon does NOT waive. Every existing
#: checker spells it this way, and the ``\S`` is the whole point: an unexplained
#: waiver is indistinguishable from a mute button.
WAIVER_RE = re.compile(r"#\s*gate-ok:\s*\S")

#: How far below a marker its declaration reaches. One line, so a marker sitting
#: on its own above the flagged statement works — which is the form the repo
#: uses whenever the statement is too long to carry a trailing comment. Stated
#: from the marker's side; the equivalent phrasing used by the older checkers
#: ("the flagged line or the line directly above it") describes the same span.
WAIVER_REACH = 1


def waived_lines(text: str) -> set[int]:
    """The 1-based line numbers a file's ``# gate-ok:`` markers cover."""
    covered: set[int] = set()
    for lineno, line in enumerate(text.splitlines(), start=1):
        if WAIVER_RE.search(line):
            covered.update(range(lineno, lineno + WAIVER_REACH + 1))
    return covered


def waiver_reasons(text: str) -> dict[int, str]:
    """``line -> reason`` for every line a marker covers.

    The reason travels with the fact so a report can say WHY a finding was
    waived and by what wording, rather than leaving the reader to open the file
    to find out whether the waiver is still true.
    """
    reasons: dict[int, str] = {}
    for lineno, line in enumerate(text.splitlines(), start=1):
        match = WAIVER_RE.search(line)
        if not match:
            continue
        reason = line[match.start() :].split("gate-ok:", 1)[1].strip()
        for covered in range(lineno, lineno + WAIVER_REACH + 1):
            reasons.setdefault(covered, reason)
    return reasons


def is_waived(path: Path, lineno: int) -> bool:
    """Is *lineno* of *path* covered by a reasoned waiver?

    An unreadable file waives nothing: a checker that cannot read the source is
    in no position to accept a declaration written in it.
    """
    try:
        text = Path(path).read_text(encoding="utf-8")
    except OSError, UnicodeDecodeError:
        return False
    return lineno in waived_lines(text)