quality_gate.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/git/quality_gate.py
 
"""
Purpose
-------
Orchestrate the Phase 4B unified quality gate: lint + format dry-run +
secrets detection on a scoped set of files. Returns a structured
:class:`QualityGateResult` that downstream consumers (``oct git check``,
``oct git commit``, hooks, MCP) can inspect and render.
 
Responsibilities
----------------
- Resolve file scope (staged / changed / all) via :mod:`oct.core.git`.
- Run the linter on Python files via :func:`oct.linter.oct_lint._lint_single_file`.
- Run the formatter in dry-run mode via :func:`oct.formatter.oct_format.format_file`.
- Run secrets detection (content + filename pattern) via
  :func:`oct.linter.oct_lint.check_no_hardcoded_secrets` and
  :data:`oct.core.exclusions.NEVER_EXPORT_FILE_PATTERNS`.
- Expose the secrets pass alone, configured exactly as the gate runs it,
  as :func:`run_secrets_scan_on_files` (``oct git commit``'s plan-208
  full-index check uses it instead of the whole gate).
- Optionally run pytest via subprocess (``--include-tests``).
- Support ``--fix`` two-pass mode: detect → fix → re-verify.
 
Diagnostics
-----------
Domain: GIT
Levels:
    L2 - lifecycle: gate start/end, scope resolution
    L3 - details: per-pass summary counts
    L4 - deep trace: per-file check outcomes
 
Contracts
---------
- This module does not import ``click``. It is a pure orchestrator.
- It calls existing library functions (linter, formatter, exclusions)
  directly; it never shells out to ``oct lint`` or ``oct format``.
- The only subprocess call is for pytest (``--include-tests``), which is
  a distinct tool boundary.
- :func:`run_quality_gate` never raises on check failures; it returns
  a :class:`QualityGateResult` with the findings. Only infrastructure
  errors (missing git repo, broken imports) may propagate.
 
Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)
- oct.core.paths (to_project_relative - project-relative paths in secrets findings and for the format pass's path-rule lookup)
- oct.core.exclusions (lazy; excluded directories and never-export file patterns for the all scope and the secrets pass)
- oct.core.git (lazy; git_staged_files, git_changed_files and git_staged_deletions - the scoped file sets)
- oct.core.octrc (lazy; load_octrc_safe - each subproject's linter rules and secret-scanner settings)
- oct.core.option_c_dir (lazy; resolve_debug_config - the diagnostics directory for the linter and formatter contexts)
- oct.core.waivers (lazy; inline waivers applied to secrets findings and to the format pass)
- oct.core.workspace (lazy; the workspace manifest, for merging each subproject's entropy exclusions)
- oct.formatter.oct_format (lazy; FormatterContext and format_file - the format pass)
- oct.git.conventional (lazy; commit message and AI-Model trailer validation in the pre-commit checks)
- oct.git.policy (lazy; the protected-branch check, profile resolution and PROFILE_MATRIX)
- oct.linter.oct_lint (lazy; _lint_single_file, the lint profiles and path rules - the lint pass)
- oct.mcp.sandbox (lazy; SandboxExecutor - the sanitised pytest run when sandbox is set)
- oct.tools.secret_scanner (lazy; check_no_hardcoded_secrets - the always-on secrets pass)
- pytest (not imported; run as python -m pytest for the --include-tests test pass)
"""
 
from __future__ import annotations
 
import dataclasses
import fnmatch
import subprocess
import sys
import time
from dataclasses import dataclass, field
from pathlib import Path
from typing import Literal
 
from oct.core.diagnostics import _dbg
from oct.core.paths import to_project_relative
 
 
# ---------------------------------------------------------------------
# Data model
# ---------------------------------------------------------------------
 
 
@dataclass
class QualityGateResult:
    """Structured output from a quality-gate run.
 
    Every field is JSON-serialisable (primitives, lists of tuples/dicts).
    Field names must match the attribute access in
    :func:`oct.git.policy.apply_profile_policy`.
    """
 
    files_checked: int = 0
    lint_violations: int = 0
    format_violations: int = 0
    secrets_findings: list = field(default_factory=list)
    """List of ``(path_str, line, reason)`` tuples."""
    test_failures: int = 0
    duration_ms: int = 0
    exit_code: int = 0
    per_file: list = field(default_factory=list)
    """Per-file dicts suitable for ``--json`` rendering."""
 
 
@dataclass(frozen=True)
class PreCommitResult:
    """OI-527: structured outcome of the three pre-gate checks that run
    before ``oct git commit`` executes the quality gate.
 
    When :attr:`ok` is True the caller proceeds to the quality gate using
    :attr:`staged_files`; the other fields carry context the command
    needs regardless (branch, effective_profile). When :attr:`ok` is
    False the caller emits :attr:`errors` on stderr (or as JSON) and
    exits with :attr:`exit_code`.
 
    :attr:`pb_advisory` is a protected-branch advisory string that must
    be echoed *whether or not* the check blocked the commit; callers
    treat it as a side-channel warning.
    """
 
    ok: bool
    exit_code: int
    errors: list
    branch: str
    effective_profile: str
    staged_files: list
    pb_advisory: str = ""
 
 
def pre_commit_checks(
    project_root: Path,
    branch: str,
    message: str,
    force_commit: bool,
    profile: str,
    octrc: dict,
) -> PreCommitResult:
    """OI-527: run the three pre-gate checks and collapse their outcomes
    into a single :class:`PreCommitResult`.
 
    The helper replaces the four sequential early-return blocks that
    previously lived in ``git_commit_cmd`` (commit-message validation,
    staged-files presence, protected-branch guard). Exit codes and side
    effects match the original CLI behaviour byte-for-byte:
      * ``exit_code == 3`` - invalid commit message (skipped when
        ``force_commit`` is True).
      * ``exit_code == 4`` - nothing staged at all. A staged set of pure
        deletions is NOT nothing: it returns ``ok`` with an empty
        :attr:`~PreCommitResult.staged_files`, because the gate has no content
        to inspect in files that are being removed.
      * ``exit_code == 1`` - protected-branch block.
    """
    from oct.core.git import git_staged_deletions, git_staged_files
    from oct.git.conventional import (
        validate_ai_model_trailer,
        validate_commit_message,
    )
    from oct.git.policy import (
        check_protected_branch_commit,
        resolve_profile_for_project,
    )
 
    # Plan 197: manifest-aware resolution. This is the single-project
    # commit path - how every worker commits from inside a subproject -
    # so before 197 it gated `oc_chat` at `compact` despite the
    # workspace manifest declaring `strict`.
    effective_profile = resolve_profile_for_project(
        project_root, branch, octrc, profile,
    )
 
    if not force_commit:
        msg_errors = list(validate_commit_message(message))
        # Option C commit-forensics convention (Plan 151 T6, inventory
        # item 4): when ``git.require_ai_model_trailer`` is enabled in
        # ``.octrc.json``, the commit body must carry an AI-Model trailer.
        # Default off - general oct users and the oct suite are unaffected.
        if (octrc or {}).get("git", {}).get("require_ai_model_trailer", False):
            msg_errors.extend(validate_ai_model_trailer(message))
        if msg_errors:
            return PreCommitResult(
                ok=False,
                exit_code=3,
                errors=list(msg_errors),
                branch=branch,
                effective_profile=effective_profile,
                staged_files=[],
            )
 
    staged = git_staged_files(project_root)
    # A staged set of pure deletions has nothing for the gate to inspect, but it
    # is emphatically something to commit. ``git_staged_files`` filters to ACMR
    # because its result is what gets linted, formatted and secret-scanned, so it
    # cannot answer "is anything staged" on its own - and using it for both
    # questions made every deletion-only commit impossible through ``oct git
    # commit`` (untracking a generated artefact, removing a dead module). Asking
    # for deletions separately leaves the gate's input byte-identical: on this
    # path ``staged`` stays empty, so the gate inspects nothing, which is the
    # correct amount of content to inspect in a commit that removes files.
    if not staged and not git_staged_deletions(project_root):
        return PreCommitResult(
            ok=False,
            exit_code=4,
            errors=["Nothing to commit."],
            branch=branch,
            effective_profile=effective_profile,
            staged_files=[],
        )
 
    blocked, pb_message = check_protected_branch_commit(
        branch, octrc, effective_profile,
    )
    if blocked:
        return PreCommitResult(
            ok=False,
            exit_code=1,
            errors=[pb_message] if pb_message else [],
            branch=branch,
            effective_profile=effective_profile,
            staged_files=list(staged),
            pb_advisory=pb_message or "",
        )
 
    return PreCommitResult(
        ok=True,
        exit_code=0,
        errors=[],
        branch=branch,
        effective_profile=effective_profile,
        staged_files=list(staged),
        pb_advisory=pb_message or "",
    )
 
 
# ---------------------------------------------------------------------
# Scope resolution
# ---------------------------------------------------------------------
 
 
def _resolve_scope(
    project_root: Path,
    scope: Literal["staged", "changed", "all"],
) -> list[Path]:
    """Return the list of files to check based on *scope*.
 
    For ``"staged"`` and ``"changed"`` we return **all** file types so
    that filename-pattern secrets detection can flag non-Python files
    like ``.env`` or ``*.pem``. The caller filters to ``.py`` for the
    lint and format passes.
 
    For ``"all"`` we use the linter's own ``find_python_files`` for the
    Python set, but also walk the tree for non-Python secret-filename
    checks.
    """
    func = "_resolve_scope"
    _dbg("GIT", func, f"scope={scope} root={project_root}", 2)
 
    if scope == "staged":
        from oct.core.git import git_staged_files
        files = git_staged_files(project_root)
        _dbg("GIT", func, f"staged files={len(files)}", 3)
        return files
 
    if scope == "changed":
        from oct.core.git import git_changed_files
        files = git_changed_files(project_root)
        _dbg("GIT", func, f"changed files={len(files)}", 3)
        return files
 
    # scope == "all"
    from oct.core.exclusions import (
        LINTER_EXCLUDE_DIRS,
        NEVER_EXPORT_FILE_PATTERNS,
        WILDCARD_EXCLUDE_DIRS,
    )
    from oct.linter.oct_lint import find_python_files
    py_files = list(find_python_files(
        project_root,
        exclude_dirs=LINTER_EXCLUDE_DIRS,
        wildcard_exclude_dirs=WILDCARD_EXCLUDE_DIRS,
    ))
    # OI-505: the secrets pass uses filename-pattern matching to catch
    # ``.env``, ``*.pem``, etc. At ``scope="all"`` we previously only
    # returned ``.py`` files, so those files were invisible to the gate.
    # Walk the tree once more for any filename that matches the secret
    # patterns, honouring the same exclusion lists as the linter.
    secret_files = list(_walk_secret_filenames(
        project_root,
        exclude_dirs=LINTER_EXCLUDE_DIRS,
        wildcard_exclude_dirs=WILDCARD_EXCLUDE_DIRS,
        patterns=NEVER_EXPORT_FILE_PATTERNS,
    ))
    _dbg(
        "GIT", func,
        f"all python files={len(py_files)} secret filename candidates="
        f"{len(secret_files)}",
        3,
    )
    return py_files + secret_files
 
 
def _walk_secret_filenames(
    project_root: Path,
    *,
    exclude_dirs,
    wildcard_exclude_dirs,
    patterns,
) -> list[Path]:
    """Yield non-Python files whose name matches any ``patterns`` glob.
 
    Uses ``os.walk`` with in-place pruning of ``dirnames`` so excluded
    trees are never descended into. Mirrors the exclusion semantics of
    :func:`oct.linter.oct_lint.find_python_files` - if a directory name
    is in ``exclude_dirs`` (exact) or matches one of the wildcard entries
    (prefix/suffix/glob), it is pruned from the walk.
    """
    import os
 
    exact = set(exclude_dirs or ())
    wildcards = tuple(wildcard_exclude_dirs or ())
    results: list[Path] = []
 
    def _should_exclude_dir(name: str) -> bool:
        if name in exact:
            return True
        for pat in wildcards:
            if fnmatch.fnmatch(name, pat):
                return True
        return False
 
    for dirpath, dirnames, filenames in os.walk(project_root):
        dirnames[:] = [d for d in dirnames if not _should_exclude_dir(d)]
        for name in filenames:
            if name.endswith(".py"):
                continue  # Already captured by find_python_files.
            for pat in patterns:
                if fnmatch.fnmatch(name, pat):
                    results.append(Path(dirpath) / name)
                    break
    return results
 
 
# ---------------------------------------------------------------------
# Individual check passes
# ---------------------------------------------------------------------
 
 
def _gate_diagnostics_dir(project_root: Path) -> Path:
    """Return the diagnostics directory the gate's contexts should carry.
 
    Plan 213 / T0: derived from the ONE resolver,
    :func:`oct.core.option_c_dir.resolve_debug_config`, instead of the
    hard-coded ``<root>/oc_diagnostics``. On a project with no config
    anywhere the resolver returns the ``oc_diagnostics/`` path, so this
    is byte-identical to the old expression; on a migrated project it
    correctly yields ``.option_c``, and on a pre-v0.17 project the legacy
    ``diagnostics/`` directory - which is what the linter's deprecation
    warning keys off.
    """
    from oct.core.option_c_dir import resolve_debug_config
 
    return resolve_debug_config(project_root).parent
 
 
def _build_linter_context(project_root: Path):
    """Build a minimal ``LinterContext`` for the quality gate.
 
    We import lazily to avoid pulling Click and the full linter on
    import of this module.
    """
    from oct.linter.oct_lint import LinterContext
 
    project_name = project_root.name
    return LinterContext(
        project_root=project_root,
        project_name=project_name,
        diagnostics_dir=_gate_diagnostics_dir(project_root),
        tests_dir=project_root / "tests",
        docs_dir=project_root / "docs",
    )
 
 
def _build_formatter_context(project_root: Path, *, fix_mode: bool = False):
    """Build a ``FormatterContext`` for dry-run (or fix) mode."""
    from oct.formatter.oct_format import FormatterContext
 
    return FormatterContext(
        project_root=project_root,
        project_name=project_root.name,
        diagnostics_dir=_gate_diagnostics_dir(project_root),
        tests_dir=project_root / "tests",
        docs_dir=project_root / "docs",
        fix_mode=fix_mode,
        dry_run_mode=not fix_mode,
        json_mode=False,
        verbose=False,
    )
 
 
#: Fixed names for what a secret-scanner finding is, matched against its
#: message. Only these names are ever logged, never the message itself.
_FINDING_KINDS: tuple[tuple[str, str], ...] = (
    ("high-entropy string", "high-entropy string"),
    (" assigned ", "secret-named assignment"),
    ("dict key", "secret-named dict key"),
    ("parameter", "secret-named parameter default"),
    ("unparseable", "unparseable file"),
)
 
 
def _finding_kinds(message: str) -> list[str]:
    """The kinds of finding in a scanner message, as fixed names only.
 
    The message itself can quote part of the flagged value, so a log record
    carries this instead. A finding matching no known kind is ``other``.
    """
    kinds: set[str] = set()
    for part in message.split("; "):
        kinds.add(next((name for marker, name in _FINDING_KINDS if marker in part), "other"))
    return sorted(kinds)
 
 
# OCT-LINT: disable=no_hardcoded_secrets reason="Param documents the matcher mode, not a credential"
def _run_secrets_pass(
    all_files: list[Path],
    project_root: Path,
    *,
    code_entropy_threshold: float = 4.5,
    docstring_entropy_threshold: float = 5.0,
    comment_entropy_threshold: float = 5.0,
    secret_match_mode: str = "substring",
    entropy_exclusions: list[dict] | None = None,
    excluded_field_patterns: list[str] | None = None,
) -> list[tuple[str, int, str]]:
    """Check files for hardcoded secrets (content) and secret filenames.
 
    Returns a list of ``(relative_path, line, reason)`` tuples.
    """
    func = "_run_secrets_pass"
    from oct.core.exclusions import NEVER_EXPORT_FILE_PATTERNS
    # OI-514: call the standalone scanner directly - no detour through the
    # linter module just to reach these helpers.
    from oct.tools.secret_scanner import check_no_hardcoded_secrets
 
    findings: list[tuple[str, int, str]] = []
    scanned: list[str] = []
 
    for path in all_files:
        rel = to_project_relative(path, project_root)
        scanned.append(rel)
 
        # Filename-pattern check (catches .env, *.pem, *.key, etc.).
        name = path.name
        for pattern in NEVER_EXPORT_FILE_PATTERNS:
            if fnmatch.fnmatch(name, pattern):
                findings.append((rel, 0, f"secret file pattern: {pattern}"))
                _dbg("GIT", func, f"secret filename {rel} ~ {pattern}", 4)
                break
 
        # Content check (Python files only - AST-based detection).
        if path.suffix == ".py" and path.is_file():
            try:
                text = path.read_text(encoding="utf-8")
 
                # OI-540: path-based entropy exclusions. Both
                # ``test_directory`` and ``module_self_doc`` contexts
                # honour the same ``exempt_entropy_only`` /
                # ``require_waiver_for_secret_patterns`` restriction
                # semantics. ``module_self_doc`` is for source files
                # whose code is dominated by help-text / template /
                # scaffold string constants.
                file_entropy = code_entropy_threshold
                require_waiver = False
                for excl in (entropy_exclusions or []):
                    if excl.get("context") in ("test_directory", "module_self_doc"):
                        pattern_str = excl.get("path_pattern", "")
                        restrictions = excl.get("restrictions", {})
                        if pattern_str and rel.replace("\\", "/").startswith(pattern_str):
                            if restrictions.get("exempt_entropy_only"):
                                file_entropy = 0
                            if restrictions.get("require_waiver_for_secret_patterns"):
                                require_waiver = True
                            break
 
                passed, message = check_no_hardcoded_secrets(
                    text,
                    mode=secret_match_mode,
                    code_entropy_threshold=file_entropy,
                    docstring_entropy_threshold=docstring_entropy_threshold,
                    comment_entropy_threshold=comment_entropy_threshold,
                    excluded_field_patterns=excluded_field_patterns,
                )
                if not passed:
                    # OI-540: honour inline waivers universally in the
                    # quality gate, matching the linter's existing
                    # behaviour.  Previously waivers were only checked
                    # when ``require_waiver`` was set by a test_directory
                    # exclusion - a gap exposed when the waiver regex
                    # was extracted to oct.core.waivers (its own pattern
                    # string legitimately exceeds the entropy threshold).
                    #
                    # Plan 193 (sec): that universal honouring was
                    # WHOLE-FILE - one waiver anywhere blinded this pass
                    # to every other finding in the file, so a real
                    # credential in any waived file committed clean.
                    # ``apply_waivers`` scopes each waiver to its own
                    # line and the next; only findings it does not reach
                    # survive, and they still block (G-D4 unchanged -
                    # this pass detects exactly what it detected before,
                    # and now reports strictly more of it).
                    from oct.core.waivers import apply_waivers, parse_inline_waivers
                    waivers = parse_inline_waivers(text)
                    outcome = apply_waivers(message, waivers, "no_hardcoded_secrets")
                    if not outcome.blocked:
                        _dbg("GIT", func, f"waiver accepted {rel}", 4)
                        continue
                    findings.append((rel, outcome.first_line, outcome.message))
                    # The record names the KINDS of finding, never the
                    # message: an entropy finding's message quotes the
                    # first 24 characters of the flagged value, and
                    # redaction runs only in production mode, so it reached
                    # dev log files whenever GIT was at level 4 or higher
                    # (operator ruling 2026-09-28).
                    _dbg(
                        "GIT", func,
                        f"secret content {rel}:{outcome.first_line} "
                        f"kinds={_finding_kinds(outcome.message)}", 4,
                    )
            except (OSError, UnicodeDecodeError) as exc:
                _dbg("GIT", func, f"read error {rel}: {exc}", 1)
 
    # One L3 record per scanned file, with its finding COUNT only: a
    # finding's message can quote the matched text. The scan logged
    # nothing per file (found by the chart C runtime trace, 2026-09-27).
    per_file: dict[str, int] = {}
    for found_rel, _line, _reason in findings:
        per_file[found_rel] = per_file.get(found_rel, 0) + 1
    for scanned_rel in scanned:
        _dbg("GIT", func, f"scanned {scanned_rel}: {per_file.get(scanned_rel, 0)} finding(s)", 3)
 
    _dbg("GIT", func, f"total findings={len(findings)}", 3)
    return findings
 
 
def _apply_octrc_to_lint(
    project_root: Path,
    ctx,
    active_rules: dict,
    *,
    profile: str | None = None,
) -> dict:
    """Honor the owning subproject's ``.octrc.json`` in the gate lint pass.
 
    Plan 177 - ``_run_lint_pass`` previously built its rule set and linter
    context from the PROFILE only, so an octrc-waived rule (e.g. ``oct``'s
    ``dbg_import: false``) re-fired and false-blocked the workspace-root
    fan-out. This mirrors the mechanism the standalone linter already uses
    (:func:`oct.linter.oct_lint.run_linter`), reusing its exact semantics:
 
    - ``linter.profile`` names the profile per-rule SEVERITY is resolved at
      (plan 269). Without this the context kept its ``"strict"`` default, so
      :func:`~oct.linter.rule_registry.get_severity` answered at strict
      severities in the gate and at the project's own profile in
      ``oct lint`` - the same divergence class plans 177 and 262 closed for
      the rule SET. *profile* is the profile the gate was called with and
      is used when the octrc names no valid one; a name outside
      ``_PROFILES`` is refused on both sides rather than passed through,
      since ``get_severity`` would silently answer at rule defaults for it;
    - ``linter.rules`` overrides merge on top of the profile defaults
      (explicit ``false`` disables, ``true`` enables; bool values only);
    - ``linter.path_rules`` (plan 268) populate ``ctx.path_rules``, which
      ``_lint_single_file`` applies per file after both of the above, so
      the gate and ``oct lint`` reach the same verdict on a file a path
      entry names. Line-scoped rules are refused by the parser;
    - ``secret_scanner`` entropy thresholds + ``entropy_exclusions``
      populate the linter context so the lint-pass ``no_hardcoded_secrets``
      check honors the same ``exempt_entropy_only`` path exclusions.
 
    The SECRETS pass (:func:`_run_secrets_pass`) is a separate, ALWAYS-ON
    pass and is NOT touched here - octrc can never disable secret scanning
    (G-D4). ``exempt_entropy_only`` exempts entropy MAGNITUDE only; a
    name/pattern-matched secret still fires in both passes.
 
    *ctx* is mutated in place; the (possibly) updated *active_rules* dict is
    returned. The fan-out passes each slice's own subproject as
    ``project_root``, so the octrc loaded here is that subproject's.
    """
    func = "_apply_octrc_to_lint"
    from oct.core.octrc import load_octrc_safe
    from oct.linter.oct_lint import _PROFILES
 
    # Plan 269 / P2: the fallback is applied BEFORE the octrc is read, so a
    # project with no octrc at all is still judged at the profile the gate
    # is running rather than at the context's ``strict`` default.
    if isinstance(profile, str) and profile in _PROFILES:
        ctx.profile_name = profile
 
    octrc = load_octrc_safe(project_root)
    if not isinstance(octrc, dict) or not octrc:
        return active_rules
 
    linter_cfg = octrc.get("linter", {})
    if isinstance(linter_cfg, dict):
        octrc_profile = linter_cfg.get("profile")
        if isinstance(octrc_profile, str) and octrc_profile in _PROFILES:
            ctx.profile_name = octrc_profile
        rule_overrides = linter_cfg.get("rules", {}) or {}
        if isinstance(rule_overrides, dict):
            active_rules.update(
                {k: v for k, v in rule_overrides.items() if isinstance(v, bool)}
            )
        # Plan 268: the per-path overrides ride the context rather than
        # the rule dict, because ``_lint_single_file`` resolves them per
        # file. ``parse_path_rules`` refuses every line-scoped rule, so
        # nothing reachable from here can touch the always-on secrets
        # pass below (G-D4).
        from oct.linter.oct_lint import parse_path_rules
 
        ctx.path_rules = parse_path_rules(linter_cfg)
 
    scanner_cfg = octrc.get("secret_scanner", {})
    if isinstance(scanner_cfg, dict):
        octrc_threshold = scanner_cfg.get("code_entropy_threshold")
        if isinstance(octrc_threshold, (int, float)) and not isinstance(
            octrc_threshold, bool
        ):
            ctx.code_entropy_threshold = float(octrc_threshold)
        for key in ("docstring_entropy_threshold", "comment_entropy_threshold"):
            val = scanner_cfg.get(key)
            if isinstance(val, (int, float)) and not isinstance(val, bool):
                setattr(ctx, key, float(val))
        exclusions = scanner_cfg.get("entropy_exclusions", [])
        if isinstance(exclusions, list):
            ctx.entropy_exclusions = exclusions
            ctx.excluded_field_patterns = [
                e["field_name_pattern"] for e in exclusions
                if isinstance(e, dict)
                and e.get("context") == "namedtuple_field"
                and isinstance(e.get("field_name_pattern"), str)
            ]
 
    _dbg(
        "GIT", func,
        f"applied octrc lint overrides from {project_root} "
        f"at profile={ctx.profile_name}",
        4,
    )
    return active_rules
 
 
def _run_lint_pass(
    py_files: list[Path],
    project_root: Path,
    profile: str,
    fix_mode: bool = False,
) -> tuple[int, list[dict]]:
    """Run the linter on *py_files* and return (violation_count, per_file).
 
    Uses ``_lint_single_file`` directly, bypassing the CLI. The profile
    selects which rules are active via ``_PROFILES``; the owning
    subproject's ``.octrc.json`` then merges its ``linter.rules`` disables
    and ``secret_scanner`` entropy exclusions on top (Plan 177), mirroring
    the standalone linter. The SECRETS pass is unaffected.
    """
    func = "_run_lint_pass"
    from oct.linter.oct_lint import _PROFILES, _lint_single_file
 
    ctx = _build_linter_context(project_root)
    active_rules = dict(_PROFILES.get(profile, _PROFILES.get("compact", {})))
    active_rules = _apply_octrc_to_lint(
        project_root, ctx, active_rules, profile=profile,
    )
 
    violations = 0
    per_file: list[dict] = []
 
    for path in py_files:
        if not path.is_file():
            continue
        try:
            result = _lint_single_file(path, ctx, active_rules, fix_mode)
            if not result.get("compliant", True):
                violations += 1
            per_file.append(result)
            _dbg(
                "GIT", func,
                f"lint {result.get('rel', '?')} compliant={result.get('compliant')}",
                4,
            )
        except Exception as exc:  # pragma: no cover - defensive
            _dbg("GIT", func, f"lint error {path}: {exc}", 1)
 
    _dbg("GIT", func, f"violations={violations} files={len(py_files)}", 3)
    return violations, per_file
 
 
#: Formatter fixers whose auto-fix mirrors a lint rule an octrc
#: ``linter.rules`` disable can suppress (Plan 177 - the format-pass twin
#: of the lint-pass merge). A format "change" produced solely by one of
#: these fixers is NOT a violation when the owning subproject disables the
#: corresponding rule - otherwise the gate re-flags oct's own
#: octrc-waived ``oct.core.diagnostics`` shim imports (``dbg_import``).
_FORMAT_FIXER_RULES = {
    "header": "header",
    "docstring": "docstring",
    "dbg_import": "dbg_import",
    "func_pattern": "func_pattern",
}
 
 
def _octrc_disabled_lint_rules(project_root: Path) -> set[str]:
    """Return the lint rules the subproject's ``.octrc.json`` disables.
 
    Plan 177 - a rule with an explicit ``false`` under ``linter.rules`` is
    honored by the gate's lint pass (via :func:`_apply_octrc_to_lint`) and,
    for the fixers listed in :data:`_FORMAT_FIXER_RULES`, by the format
    pass. The SECRETS pass is never consulted here - octrc can't disable it.
    """
    from oct.core.octrc import load_octrc_safe
 
    disabled: set[str] = set()
    octrc = load_octrc_safe(project_root)
    if isinstance(octrc, dict):
        linter_cfg = octrc.get("linter", {})
        if isinstance(linter_cfg, dict):
            rules = linter_cfg.get("rules", {}) or {}
            if isinstance(rules, dict):
                disabled = {k for k, v in rules.items() if v is False}
    return disabled
 
 
def _disabled_fixer_rules_for(
    rel_posix: str,
    run_disabled: set[str],
    path_rules: list,
) -> set[str]:
    """Return the lint rules disabled FOR ONE FILE, the per-path answer.
 
    Plan 269 - the format-pass twin of what plan 268 gave the lint pass.
    :func:`_octrc_disabled_lint_rules` answers for the whole run, which is
    the wrong grain for a config whose whole purpose is that a test tree
    and its package answer differently: a module a ``tests/`` path entry
    excused from ``dbg_import`` passed the gate's lint pass and was still
    refused by its format pass, on the same rule, in the same commit.
 
    The run-wide set is the starting point and every matching path entry
    then moves what it names: a rule the entry sets ``False`` joins the
    set, one it sets ``True`` leaves it - including a rule ``linter.rules``
    disabled run-wide, which is the only way a project can keep a fixer
    where it wants it and drop it everywhere else. Entry order and the
    refusals (line-scoped rules, ``_``-prefixed mode markers) are
    :func:`~oct.linter.oct_lint.effective_rules`'s, not restated here, so
    the gate's format pass and ``oct lint`` cannot drift apart on what a
    path entry means.
 
    G-D4 is untouched by construction and by test: the secrets pass never
    consults this, and no key of :data:`_FORMAT_FIXER_RULES` names a
    secret rule - ``effective_rules`` would refuse it in any case.
 
    Parameters
    ----------
    rel_posix
        The file's project-relative POSIX path, as
        :func:`~oct.core.paths.to_project_relative` renders it.
    run_disabled
        The run-wide disables from :func:`_octrc_disabled_lint_rules`.
        Never mutated - one set is shared across the whole pass.
    path_rules
        Validated ``(prefix, {rule: bool})`` pairs from
        :func:`~oct.linter.oct_lint.parse_path_rules`.
    """
    func = "_disabled_fixer_rules_for"
    if not path_rules:
        return run_disabled
 
    from oct.linter.oct_lint import effective_rules
 
    # An empty base means the returned dict names ONLY what a matching
    # entry set, which is exactly the delta to apply to the run-wide set.
    overrides, _changed = effective_rules({}, rel_posix, path_rules)
    if not overrides:
        return run_disabled
 
    disabled = set(run_disabled)
    for rule, active in overrides.items():
        if active:
            disabled.discard(rule)
        else:
            disabled.add(rule)
    _dbg("GIT", func, f"{rel_posix} disables {sorted(disabled)}", 4)
    return disabled
 
 
def _disabled_fixers_for(disabled_rules: set) -> frozenset:
    """Translate disabled LINT RULES into the FIXER names to skip.
 
    :data:`_FORMAT_FIXER_RULES` maps fixer name to lint rule; this reads
    it in the other direction, which is the direction the formatter needs
    - :func:`~oct.formatter.oct_format.format_file` knows fixers, and
    everything upstream of it speaks rules.
 
    The map is an identity today, so the translation is a filter; it is
    written as a translation anyway so that a fixer whose name ever
    differs from its rule cannot quietly disable the wrong one. A rule
    with no fixer (``dbg_usage``, every line-scoped rule) simply names no
    fixer and disappears here, which is the second reason G-D4 cannot be
    reached from this path.
    """
    return frozenset(
        name for name, rule in _FORMAT_FIXER_RULES.items()
        if rule in disabled_rules
    )
 
 
def _run_format_pass(
    py_files: list[Path],
    project_root: Path,
    fix_mode: bool = False,
) -> int:
    """Run the formatter in dry-run (or fix) mode, return violation count.
 
    A "violation" is a file where ``format_file`` reports a change from a
    fixer whose lint rule is NOT disabled for THAT FILE by the owning
    subproject's octrc. Plan 177 (format-pass twin): a change produced
    solely by an octrc-disabled fixer (e.g. ``dbg_import`` on oct's
    ``oct.core`` diagnostics shim) is suppressed, mirroring the lint pass.
    Plan 269: ``linter.path_rules`` are resolved per file by
    :func:`_disabled_fixer_rules_for`, so this pass and the lint pass
    reach the same verdict on a file a path entry names - before, a path
    entry reached the lint pass only and the format pass refused the file
    the lint pass had just cleared. The SECRETS pass is unaffected.
 
    Plan 277 closes the last of the three: the file's OWN inline
    ``# OCT-LINT: disable[-file]=<rule>`` waivers join the per-file
    disabled set, on exactly the linter's terms
    (:func:`~oct.core.waivers.inline_disabled_rules`). The file text is
    read here to parse them, as the secrets pass already reads it, and a
    file that cannot be read yields no waivers - ``format_file`` reads it
    again and reports the failure through its own error channel.
    :data:`~oct.core.waivers.LINE_SCOPED_RULES` cannot enter the set, so
    a ``no_hardcoded_secrets`` waiver disables no fixer here and G-D4 is
    untouched by construction as well as by test.
 
    The octrc is read once per pass, not once per file: the run-wide
    disables and the parsed path rules are both resolved before the loop.
    """
    func = "_run_format_pass"
    from oct.core.octrc import load_octrc_safe
    from oct.core.waivers import inline_disabled_rules
    from oct.formatter.oct_format import format_file
    from oct.linter.oct_lint import parse_path_rules
 
    ctx = _build_formatter_context(project_root, fix_mode=fix_mode)
    run_disabled = _octrc_disabled_lint_rules(project_root)
    octrc = load_octrc_safe(project_root)
    path_rules = parse_path_rules(
        octrc.get("linter", {}) if isinstance(octrc, dict) else {},
    )
    violations = 0
 
    for path in py_files:
        if not path.is_file():
            continue
        try:
            disabled = _disabled_fixer_rules_for(
                to_project_relative(path, project_root),
                run_disabled,
                path_rules,
            )
            try:
                text = path.read_text(encoding="utf-8")
            except (OSError, UnicodeDecodeError) as read_exc:
                _dbg("GIT", func, f"read error {path}: {read_exc}", 1)
                text = ""
            waived = inline_disabled_rules(text)
            if waived:
                # A NEW set every time: with no path rules
                # ``_disabled_fixer_rules_for`` hands back the run-wide
                # set itself, which is shared across the whole pass.
                disabled = set(disabled) | waived
            # Plan 277 P2 - the formatter is told what NOT to run, in
            # check and fix mode alike, so a disabled fixer can no longer
            # rewrite the file and be filtered out afterwards. A fresh
            # context per file rather than a mutated one: the class calls
            # itself an immutable per-run context, and one shared object
            # carrying the previous file's answer is precisely the bug
            # class this plan is closing.
            file_ctx = dataclasses.replace(
                ctx, disabled_fixers=_disabled_fixers_for(disabled),
            )
            result = format_file(path, file_ctx)
            fixes = result.get("fixes") or {}
            changed_fixers = {
                name for name, info in fixes.items()
                if isinstance(info, dict) and info.get("changed")
            }
            # A change counts only when it comes from a fixer whose lint
            # rule the subproject did NOT disable (fixers with no rule
            # analogue map to themselves and are always counted).
            effective = {
                name for name in changed_fixers
                if _FORMAT_FIXER_RULES.get(name, name) not in disabled
            }
            if effective:
                violations += 1
                _dbg(
                    "GIT", func,
                    f"format change {result.get('path', '?')}: {sorted(effective)}",
                    4,
                )
            elif result.get("changed", False) and not changed_fixers:
                # Defensive: reported changed without per-fixer detail.
                violations += 1
                _dbg("GIT", func, f"format change {result.get('path', '?')}", 4)
        except Exception as exc:  # pragma: no cover - defensive
            _dbg("GIT", func, f"format error {path}: {exc}", 1)
 
    _dbg("GIT", func, f"violations={violations} files={len(py_files)}", 3)
    return violations
 
 
def _run_test_pass(project_root: Path, sandbox: bool = False) -> int:
    """Run ``python -m pytest tests/`` and return the failure count.
 
    Returns 0 if all tests pass (exit code 0), or 1 if any test fails
    (non-zero exit code). This is a subprocess boundary - tests are a
    distinct tool and their execution is not inline.
 
    When ``sandbox=True`` (OI-517), the pytest subprocess runs under a
    sanitised environment via :class:`oct.mcp.sandbox.SandboxExecutor`:
    secret-named env vars are stripped, ``PYTHONPATH`` is dropped, and a
    600s wall-clock ceiling is enforced. Output is capped at 1 MiB so a
    runaway test cannot flood stderr.
    """
    func = "_run_test_pass"
    _dbg("GIT", func, f"starting test pass sandbox={sandbox}", 2)
 
    cmd = [sys.executable, "-m", "pytest", "tests/", "-x", "--tb=no", "-q"]
    try:
        if sandbox:
            from oct.mcp.sandbox import NativeBackend, SandboxExecutor
            executor = SandboxExecutor(backend=NativeBackend())
            sandbox_result = executor.run(cmd, cwd=project_root, timeout=600)
            returncode = sandbox_result.exit_code
            if sandbox_result.timed_out:
                _dbg("GIT", func, "sandbox pytest timed out", 1)
        else:
            result = subprocess.run(
                cmd,
                cwd=project_root,
                capture_output=True,
                text=True,
                timeout=300,
            )
            returncode = result.returncode
        failures = 0 if returncode == 0 else 1
        _dbg("GIT", func, f"test exit_code={returncode}", 3)
        return failures
    except (subprocess.TimeoutExpired, FileNotFoundError, OSError) as exc:
        _dbg("GIT", func, f"test pass error: {exc}", 1)
        return 1
 
 
# ---------------------------------------------------------------------
# Main orchestrator
# ---------------------------------------------------------------------
 
 
def run_quality_gate(
    project_root: Path,
    scope: Literal["staged", "changed", "all"],
    profile: Literal["proto", "compact", "strict"],
    include_tests: bool = False,
    fix: bool = False,
    sandbox: bool = False,
) -> QualityGateResult:
    """Orchestrate lint + format-dry-run + secrets on the scoped files.
 
    When ``fix=True``, runs in two passes:
 
    1. **Detect pass:** run the gate with ``fix=False`` to record the
       initial state.
    2. **Fix pass:** run lint and format with ``fix_mode=True`` to apply
       auto-fixes.
    3. **Re-verify pass:** run the gate again with ``fix=False``. The
       returned result reflects the post-fix state.
 
    Secrets are **never** auto-fixed (no safe auto-fix for a hardcoded
    password). The ``--fix`` flag does not bypass the always-blocking
    secrets rule.
 
    Parameters
    ----------
    project_root
        Resolved project root containing ``.octrc.json``, ``tests/``, etc.
    scope
        ``"staged"`` checks only the git index; ``"changed"`` checks
        staged + unstaged + untracked; ``"all"`` checks every Python file.
    profile
        Lint profile: ``"proto"`` / ``"compact"`` / ``"strict"``.
    include_tests
        If True, also run ``pytest`` as a subprocess (exit code 4 on fail).
    fix
        If True, attempt auto-fix of lint/format violations, then re-check.
    sandbox
        OI-517: when True and ``include_tests`` is True, the pytest
        subprocess runs under the MCP sandbox environment - sanitised
        env, no network side-channels via PYTHONPATH, output capped.
    """
    func = "run_quality_gate"
    _dbg("GIT", func, f"start scope={scope} profile={profile} fix={fix}", 2)
 
    # F1.3: scope-resolution is the only step that differs between this
    # entry point and run_quality_gate_on_files. After resolving the
    # scope we delegate to the file-list variant so per-subproject
    # fan-out can call the same machinery without re-discovering files.
    all_files = _resolve_scope(project_root, scope)
    return run_quality_gate_on_files(
        project_root=project_root,
        files=all_files,
        profile=profile,
        include_tests=include_tests,
        fix=fix,
        sandbox=sandbox,
    )
 
 
def run_secrets_scan_on_files(
    project_root: Path,
    files: list[Path],
) -> list[tuple[str, int, str]]:
    """The gate's secrets pass alone, configured exactly as the gate runs it.
 
    Reads the scanner settings from *project_root*'s octrc, merges every
    workspace subproject's ``entropy_exclusions`` when *project_root* is a
    workspace root, and scans *files* (all file types). This is the one
    place that configuration is assembled: :func:`run_quality_gate_on_files`
    calls it for its secrets pass, and ``oct git commit``'s plan-208
    full-index check calls it directly, so the two scans cannot drift apart
    and the full-index check no longer re-runs lint and format only to
    discard them (found by the chart C runtime trace, 2026-09-27).
 
    Returns
    -------
    list of ``(relative_path, line, reason)`` tuples, as
    :func:`_run_secrets_pass` does.
    """
    func = "run_secrets_scan_on_files"
    all_files = list(files)
    from oct.core.octrc import load_octrc_safe
    octrc = load_octrc_safe(project_root)
    scanner_cfg = octrc.get("secret_scanner", {}) if isinstance(octrc.get("secret_scanner"), dict) else {}
    exclusions = scanner_cfg.get("entropy_exclusions", []) or []
    if not isinstance(exclusions, list):
        exclusions = []
 
    # F1 fan-out: when invoked from a workspace root, the workspace-root
    # `.octrc.json` typically does not exist; the per-subproject configs
    # at `<sp>/.option_c/octrc.json` carry the exclusions. Merge each
    # subproject's `entropy_exclusions` into the active list so the
    # operator's explicit allow-listing applies. `field_name_pattern`
    # entries are global; `path_pattern` entries are prefixed with the
    # subproject's workspace-relative path so they match against
    # workspace-relative file paths used by `_run_secrets_pass`.
    from oct.core.workspace import (
        WORKSPACE_MANIFEST,
        WorkspaceError,
        load_workspace,
    )
    ws_manifest_path = project_root / WORKSPACE_MANIFEST
    if ws_manifest_path.is_file():
        try:
            ws = load_workspace(project_root)
        except WorkspaceError:
            ws = None
        if ws is not None:
            for sp in ws.subprojects:
                try:
                    sp_rel = sp.path.relative_to(project_root).as_posix()
                except ValueError:
                    continue
                sub_octrc = load_octrc_safe(sp.path)
                sub_scanner = sub_octrc.get("secret_scanner", {})
                if not isinstance(sub_scanner, dict):
                    continue
                sub_excl = sub_scanner.get("entropy_exclusions", []) or []
                if not isinstance(sub_excl, list):
                    continue
                for excl in sub_excl:
                    if not isinstance(excl, dict):
                        continue
                    merged = dict(excl)
                    pp = merged.get("path_pattern")
                    if isinstance(pp, str) and pp:
                        merged["path_pattern"] = f"{sp_rel}/{pp.lstrip('/')}"
                    exclusions.append(merged)
 
    field_patterns = [
        e["field_name_pattern"] for e in exclusions
        if isinstance(e, dict)
        and e.get("context") == "namedtuple_field"
        and isinstance(e.get("field_name_pattern"), str)
    ]
    secrets_findings = _run_secrets_pass(
        all_files, project_root,
        code_entropy_threshold=scanner_cfg.get("code_entropy_threshold", 4.5),
        docstring_entropy_threshold=scanner_cfg.get("docstring_entropy_threshold", 5.0),
        comment_entropy_threshold=scanner_cfg.get("comment_entropy_threshold", 5.0),
        secret_match_mode=scanner_cfg.get("match_mode", "substring"),
        entropy_exclusions=exclusions if isinstance(exclusions, list) else [],
        excluded_field_patterns=field_patterns,
    )
    _dbg("GIT", func, f"files={len(all_files)} findings={len(secrets_findings)}", 3)
    return secrets_findings
 
 
def run_quality_gate_on_files(
    project_root: Path,
    files: list[Path],
    profile: Literal["proto", "compact", "strict"],
    include_tests: bool = False,
    fix: bool = False,
    sandbox: bool = False,
) -> QualityGateResult:
    """Run the quality gate on an explicit file list.
 
    Identical contract to :func:`run_quality_gate` but accepts a
    pre-resolved list of files instead of computing one from a scope
    string. This is the entry point used by F1.3 per-subproject
    fan-out at workspace-level commit, where the workspace-wide
    staged set is grouped into subproject buckets and each bucket
    runs under its own profile.
 
    Parameters
    ----------
    project_root
        Resolved project root for octrc / linter-context / secrets
        config loading. For a per-subproject call, pass the
        subproject's path; for a workspace-level call, pass the
        workspace root.
    files
        Pre-filtered list of files to lint / format / scan. May
        include non-Python files (passed through to the secrets
        scanner; lint/format ignore them via the suffix filter).
    profile
        Lint profile: ``"proto"`` / ``"compact"`` / ``"strict"``.
    include_tests, fix, sandbox
        Same semantics as :func:`run_quality_gate`.
    """
    func = "run_quality_gate_on_files"
    start = time.monotonic()
    _dbg(
        "GIT", func,
        f"start files={len(files)} profile={profile} fix={fix}",
        2,
    )
 
    from oct.git.policy import PROFILE_MATRIX
 
    all_files = list(files)
    py_files = [f for f in all_files if f.suffix == ".py"]
 
    # -- Secrets pass (always runs, on ALL file types) -------------------
    secrets_findings = run_secrets_scan_on_files(project_root, all_files)
 
    # -- Lint pass -------------------------------------------------------
    matrix = PROFILE_MATRIX.get(profile, PROFILE_MATRIX["compact"])
    lint_violations = 0
    per_file: list[dict] = []
    if matrix["lint"] != "skip":
        lint_violations, per_file = _run_lint_pass(
            py_files, project_root, profile, fix_mode=False,
        )
 
    # -- Format pass -----------------------------------------------------
    format_violations = 0
    if matrix["format"] != "skip":
        format_violations = _run_format_pass(
            py_files, project_root, fix_mode=False,
        )
 
    # -- Test pass (optional) --------------------------------------------
    test_failures = 0
    if include_tests and matrix["tests"] != "skip":
        test_failures = _run_test_pass(project_root, sandbox=sandbox)
 
    # -- Fix mode: two-pass approach ------------------------------------
    if fix and (lint_violations > 0 or format_violations > 0):
        _dbg("GIT", func, "fix mode: applying auto-fixes", 2)
 
        # Fix pass - apply lint and format auto-fixes.
        if lint_violations > 0 and matrix["lint"] != "skip":
            _run_lint_pass(py_files, project_root, profile, fix_mode=True)
        if format_violations > 0 and matrix["format"] != "skip":
            _run_format_pass(py_files, project_root, fix_mode=True)
 
        # Re-verify pass - check again after fixes.
        _dbg("GIT", func, "fix mode: re-verifying", 2)
        lint_violations = 0
        per_file = []
        if matrix["lint"] != "skip":
            lint_violations, per_file = _run_lint_pass(
                py_files, project_root, profile, fix_mode=False,
            )
        format_violations = 0
        if matrix["format"] != "skip":
            format_violations = _run_format_pass(
                py_files, project_root, fix_mode=False,
            )
        # Note: secrets are NOT re-run - they cannot be auto-fixed.
 
    duration_ms = int((time.monotonic() - start) * 1000)
 
    result = QualityGateResult(
        files_checked=len(all_files),
        lint_violations=lint_violations,
        format_violations=format_violations,
        secrets_findings=secrets_findings,
        test_failures=test_failures,
        duration_ms=duration_ms,
        per_file=per_file,
    )
    _dbg(
        "GIT", func,
        f"end lint={lint_violations} fmt={format_violations} "
        f"secrets={len(secrets_findings)} tests={test_failures} "
        f"duration_ms={duration_ms}",
        2,
    )
    return result