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`.
- 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.
"""
 
from __future__ import annotations
 
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`` — no staged files.
      * ``exit_code == 1`` — protected-branch block.
    """
    from oct.core.git import git_staged_files
    from oct.git.conventional import validate_commit_message
    from oct.git.policy import (
        check_protected_branch_commit,
        resolve_effective_profile,
    )
 
    effective_profile = resolve_effective_profile(branch, octrc, profile)
 
    if not force_commit:
        msg_errors = validate_commit_message(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)
    if not staged:
        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 _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=project_root / "oc_diagnostics",
        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=project_root / "oc_diagnostics",
        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,
    )
 
 
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",  # OCT-LINT: disable=no_hardcoded_secrets reason="Param documents the matcher mode, not a credential"
    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]] = []
 
    for path in all_files:
        rel = to_project_relative(path, project_root)
 
        # 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).
                    from oct.core.waivers import parse_inline_waivers
                    waivers = parse_inline_waivers(text)
                    waived = any(
                        w["rule"] == "no_hardcoded_secrets" and w["reason"]
                        for w in waivers.values()
                    )
                    if waived:
                        _dbg("GIT", func, f"waiver accepted {rel}", 4)
                        continue
                    findings.append((rel, 0, message))
                    _dbg("GIT", func, f"secret content {rel}: {message}", 4)
            except (OSError, UnicodeDecodeError) as exc:
                _dbg("GIT", func, f"read error {rel}: {exc}", 1)
 
    _dbg("GIT", func, f"total findings={len(findings)}", 3)
    return findings
 
 
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``.
    """
    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", {})))
 
    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
 
 
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 ``changed=True``
    (i.e. the formatter would modify it).
    """
    func = "_run_format_pass"
    from oct.formatter.oct_format import format_file
 
    ctx = _build_formatter_context(project_root, fix_mode=fix_mode)
    violations = 0
 
    for path in py_files:
        if not path.is_file():
            continue
        try:
            result = format_file(path, ctx)
            if result.get("changed", False):
                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_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) -------------------
    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,
    )
 
    # -- 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