policy.py

Go to the documentation of this file.

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
# oct/git/policy.py
 
"""
Purpose
-------
Encode the Phase 4B profile-aware enforcement rules for the ``oct git``
quality gate. Maps a combination of profile (``proto`` / ``compact`` /
``strict``), branch context, and raw check findings to a semantic exit
code in the range 0..5 defined by blueprint §5.3.
 
Responsibilities
----------------
- Resolve the effective lint profile from CLI / octrc / branch context,
  honouring the protected-branch override (blueprint §7.2).
- Restrict the protected-branch opt-out to nested-repo subprojects
  (Plan 209): an ordinary subproject's ``git.protected_branches`` can
  add a branch but never remove ``main``/``master`` from protection.
- Apply the profile enforcement matrix (blueprint §5.3 / §7.1) to a
  :class:`~oct.git.quality_gate.QualityGateResult` and return the
  matching exit code.
- Enforce the invariant "secrets always blocks" regardless of profile
  (blueprint §5.3 final clause).
- Manage the OCT-managed block in ``.gitignore`` - add/remove/list
  patterns inside the fenced block, leaving user-managed lines alone.
 
Diagnostics
-----------
Domain: GIT
Levels:
    L1 - workspace-manifest lookup failures (degrading to the
         octrc-only chain rather than breaking the gate)
    L2 - (none) pure decision helpers; callers own lifecycle logging
    L3 - profile resolution and policy decisions
    L4 - per-field raw counts during exit-code derivation
 
Contracts
---------
- No subprocess, no Click. Profile *decisions* are pure; the two
  functions that read config off disk (``resolve_manifest_profile`` and
  the ``.gitignore`` block helpers) are the documented exceptions.
- ``resolve_effective_profile`` never raises; unknown values collapse
  to the documented default. It is the SINGLE resolver - the workspace
  fan-out path (``oct.git.oct_git._resolve_subproject_profile``)
  delegates to it, so the two paths cannot drift apart (Plan 197).
- ``resolve_manifest_profile`` never raises: a missing, unreadable or
  malformed manifest yields ``None``, which degrades to the pre-197
  octrc-only behaviour.
- ``apply_profile_policy`` depends only on the ``QualityGateResult``
  dataclass defined in :mod:`oct.git.quality_gate`.
- Precedence for the exit code is strictly: 5 > 4 > 3 > 2 > 1 > 0.
- Plan 209: protected-branch opt-out (an explicit
  ``git.protected_branches`` list) is a ``nested_git``-only privilege -
  every other subproject may ADD to but never REMOVE the workspace
  defaults from its protected set. ``resolve_manifest_nested_git``
  never raises, mirroring ``resolve_manifest_profile``'s degrade-to-
  safe-default contract (it returns ``False``, meaning "not exempt",
  rather than crashing or guessing).
 
Dependencies
------------
- oct.core.diagnostics (_dbg structured logger)
- oct.core.workspace (lazy; manifest lookup of the owning subproject's profile and nested_git flag)
- oct.git.conventional (lazy; parse_commit_message - type, scope and subject for branch names)
- oct.git.quality_gate (lazy; QualityGateResult annotation, imported only for type checking)
"""
 
from __future__ import annotations
 
import re
import sys
from pathlib import Path
from typing import TYPE_CHECKING, Literal
 
from oct.core.diagnostics import _dbg
 
 
if TYPE_CHECKING:  # pragma: no cover - avoid import cycle at runtime
    from oct.git.quality_gate import QualityGateResult
 
 
# ---------------------------------------------------------------------
# Constants
# ---------------------------------------------------------------------
 
Profile = Literal["proto", "compact", "strict"]
 
#: The three canonical profile names. Anything else resolves to
#: ``DEFAULT_PROFILE``.
VALID_PROFILES: tuple[Profile, ...] = ("proto", "compact", "strict")
 
#: Fallback profile used when no other source (CLI, config, branch
#: override) selects one. Blueprint §7 names "compact" as the project
#: default.
DEFAULT_PROFILE: Profile = "compact"
 
#: Default protected branches written into ``.octrc.json`` when a
#: project does not override them (blueprint §7.2). Branches listed
#: here force the profile to ``strict`` regardless of CLI or config.
DEFAULT_PROTECTED_BRANCHES: tuple[str, ...] = ("main", "master")
 
#: Profile enforcement matrix (blueprint §5.3 / §7.1, verbatim).
#:
#: ``lint`` / ``format`` / ``tests`` values are one of:
#:   - ``"blocking"``: a violation produces a non-zero exit code.
#:   - ``"optional"``: the check runs and reports, but failures are
#:     advisory - exit code is unaffected (OI-531).
#:   - ``"warn"``: violations are reported but do not affect exit code.
#:   - ``"skip"``: the check is not run at all.
#: ``secrets`` is always ``"blocking"`` - see :data:`SECRETS_ALWAYS_BLOCKS`.
PROFILE_MATRIX: dict[Profile, dict[str, str]] = {
    "proto": {
        "lint": "warn",
        "format": "skip",
        "secrets": "blocking",  # OCT-LINT: disable=no_hardcoded_secrets reason="Profile enforcement matrix; 'secrets' is a check name, not a credential"
        "tests": "skip",
    },
    "compact": {
        "lint": "blocking",
        "format": "blocking",
        "secrets": "blocking",  # OCT-LINT: disable=no_hardcoded_secrets reason="Profile enforcement matrix; 'secrets' is a check name, not a credential"
        "tests": "optional",
    },
    "strict": {
        "lint": "blocking",
        "format": "blocking",
        "secrets": "blocking",  # OCT-LINT: disable=no_hardcoded_secrets reason="Profile enforcement matrix; 'secrets' is a check name, not a credential"
        "tests": "blocking",
    },
}
 
#: Invariant: secrets findings are always blocking. This is asserted as
#: a unit test so any accidental weakening of :data:`PROFILE_MATRIX`
#: produces a CI failure rather than a silent security regression.
SECRETS_ALWAYS_BLOCKS: bool = True
 
#: Default branch naming patterns (Phase 4E - G-E3, blueprint §7.1).
#: Matches main/master/develop as exact names and common prefix-based
#: patterns. Projects may override via ``git.branch_naming.patterns``.
DEFAULT_BRANCH_PATTERNS: tuple[str, ...] = (
    r"^(main|master|develop)$",
    r"^(release|hotfix|feature|bugfix|docs|chore)/.+$",
)
 
#: Auto-profile mapping (Phase 4E - G-E4, blueprint §7.3). Maps branch
#: name prefixes to profiles. Exact matches are tried first, then
#: prefix matches. Unrecognised branches fall back to DEFAULT_PROFILE.
_AUTO_PROFILE_MAP: dict[str, Profile] = {
    "main": "strict",
    "master": "strict",
    "release/": "strict",
    "hotfix/": "strict",
    "feature/": "compact",
    "bugfix/": "compact",
    "docs/": "compact",
    "chore/": "compact",
}
 
#: Maps Conventional Commit types to branch-name prefixes for auto-
#: branching on protected branches (Phase 4F - G-F2).
_COMMIT_TYPE_TO_PREFIX: dict[str, str] = {
    "feat": "feature",
    "fix": "bugfix",
    "docs": "docs",
    "style": "chore",
    "refactor": "chore",
    "perf": "feature",
    "test": "chore",
    "chore": "chore",
    "sec": "hotfix",
}
 
#: Maximum slug length for auto-generated branch names.
_BRANCH_SLUG_MAX_LEN: int = 50
 
 
# ---------------------------------------------------------------------
# Branch name generation (Phase 4F - G-F2)
# ---------------------------------------------------------------------
 
 
def generate_branch_name_from_message(message: str) -> str | None:
    """Derive a valid branch name from a Conventional Commits *message*.
 
    Returns a branch name like ``feature/auth-add-jwt-tokens`` or
    ``None`` when the message cannot be parsed.
 
    The generated name is guaranteed to pass
    :func:`validate_branch_name` against the default patterns.
    """
    func = "generate_branch_name_from_message"
    _dbg("GIT", func, f"message={message[:60]!r}", 3)
 
    from oct.git.conventional import parse_commit_message
 
    parsed = parse_commit_message(message)
    if parsed is None:
        _dbg("GIT", func, "parse failed - returning None", 4)
        return None
 
    prefix = _COMMIT_TYPE_TO_PREFIX.get(parsed.type, "chore")
 
    # Build slug from optional scope + subject.
    parts: list[str] = []
    if parsed.scope:
        parts.append(parsed.scope)
    parts.append(parsed.subject)
    raw_slug = "-".join(parts).lower()
 
    # Slugify: keep only alphanumeric + hyphens.
    slug = re.sub(r"[^a-z0-9-]", "-", raw_slug)
    slug = re.sub(r"-{2,}", "-", slug)
    slug = slug.strip("-")
 
    if not slug:
        _dbg("GIT", func, "empty slug - returning None", 4)
        return None
 
    # Truncate to max length.
    if len(slug) > _BRANCH_SLUG_MAX_LEN:
        slug = slug[:_BRANCH_SLUG_MAX_LEN].rstrip("-")
 
    name = f"{prefix}/{slug}"
 
    # Sanity-check against default patterns.
    valid, _ = validate_branch_name(name, None)
    if not valid:
        _dbg("GIT", func, f"generated name {name!r} invalid - returning None", 3)
        return None
 
    _dbg("GIT", func, f"result={name!r}", 4)
    return name
 
 
# ---------------------------------------------------------------------
# Profile resolution
# ---------------------------------------------------------------------
 
 
def is_protected_branch(
    branch: str | None,
    octrc: dict | None,
    *,
    allow_optout: bool = False,
) -> bool:
    """Return True if ``branch`` is listed in ``git.protected_branches``.
 
    A missing ``octrc`` or a missing ``git.protected_branches`` key
    falls back to :data:`DEFAULT_PROTECTED_BRANCHES`. Detached HEAD
    (``branch is None``) is never considered protected - detached
    workflows are per-definition outside branch policy.
 
    Plan 209: an explicit ``protected_branches`` list is a PRIVILEGE,
    not an open door. When the octrc sets one:
 
    - ``allow_optout=False`` (the safe default, every ordinary
      subproject): the effective protected set is the UNION of the
      configured list and :data:`DEFAULT_PROTECTED_BRANCHES` - a
      subproject may ADD a protected branch but can never REMOVE
      ``main``/``master`` from protection by omitting them.
    - ``allow_optout=True`` (reserved for a ``nested_git`` subproject -
      a foreign nested repo that owns its own branch policy, e.g.
      ``oc_explorer``): the configured list is honored verbatim, so an
      explicit empty list means genuinely no protected branches.
 
    An unset or malformed (non-list) ``protected_branches`` always
    falls back to :data:`DEFAULT_PROTECTED_BRANCHES`, regardless of
    *allow_optout* - opting out requires an explicit list.
    """
    func = "is_protected_branch"
    _dbg("GIT", func, f"branch={branch!r} allow_optout={allow_optout}", 3)
    if branch is None or not branch:
        return False
    if branch == "HEAD":
        # :func:`oct.core.git.current_branch` returns the literal "HEAD"
        # when detached. Treat it the same as ``None``.
        return False
    configured: list[str] | None = None
    if isinstance(octrc, dict):
        git_cfg = octrc.get("git")
        if isinstance(git_cfg, dict):
            candidate = git_cfg.get("protected_branches")
            if isinstance(candidate, list):
                # Only accept strings; ignore junk entries silently so a
                # malformed config cannot downgrade the gate.
                configured = [b for b in candidate if isinstance(b, str)]
    protected: set[str]
    if configured is None:
        protected = set(DEFAULT_PROTECTED_BRANCHES)
    elif allow_optout:
        protected = set(configured)
    else:
        protected = set(configured) | set(DEFAULT_PROTECTED_BRANCHES)
    result = branch in protected
    _dbg("GIT", func, f"result={result} protected={sorted(protected)}", 4)
    return result
 
 
# ---------------------------------------------------------------------
# Branch naming validation (Phase 4E - G-E3)
# ---------------------------------------------------------------------
 
 
def validate_branch_name(
    branch: str | None,
    octrc: dict | None,
) -> tuple[bool, str]:
    """Validate *branch* against the configured naming patterns.
 
    Returns ``(valid, message)``:
 
    - ``git.branch_naming.enabled`` is ``False`` → ``(True, "")``
    - ``branch`` is ``None`` (detached HEAD) → ``(True, "")``
    - Branch matches at least one pattern → ``(True, "")``
    - No pattern matches → ``(False, "Branch name '...' does not ...")``
 
    Patterns default to :data:`DEFAULT_BRANCH_PATTERNS` when not
    overridden in ``.octrc.json``.
    """
    func = "validate_branch_name"
    _dbg("GIT", func, f"branch={branch!r}", 3)
 
    if branch is None or branch == "HEAD":
        return True, ""
 
    # Read config.
    enabled = True
    patterns: list[str] = list(DEFAULT_BRANCH_PATTERNS)
 
    if isinstance(octrc, dict):
        git_cfg = octrc.get("git")
        if isinstance(git_cfg, dict):
            naming_cfg = git_cfg.get("branch_naming")
            if isinstance(naming_cfg, dict):
                raw_enabled = naming_cfg.get("enabled")
                if isinstance(raw_enabled, bool):
                    enabled = raw_enabled
                raw_patterns = naming_cfg.get("patterns")
                if isinstance(raw_patterns, list):
                    patterns = [p for p in raw_patterns if isinstance(p, str)]
 
    if not enabled:
        _dbg("GIT", func, "branch naming disabled", 4)
        return True, ""
 
    if not patterns:
        # No patterns → everything is valid.
        return True, ""
 
    for pattern in patterns:
        try:
            if re.match(pattern, branch):
                _dbg("GIT", func, f"matched: {pattern!r}", 4)
                return True, ""
        except re.error:
            continue
 
    msg = (
        f"Branch name '{branch}' does not match any allowed pattern. "
        f"Expected patterns: {', '.join(patterns)}"
    )
    _dbg("GIT", func, f"invalid: {msg}", 3)
    return False, msg
 
 
# ---------------------------------------------------------------------
# Auto-profile resolution (Phase 4E - G-E4)
# ---------------------------------------------------------------------
 
 
def _resolve_auto_profile(branch: str | None) -> Profile:
    """Map *branch* to a profile using :data:`_AUTO_PROFILE_MAP`.
 
    Exact matches (``main``, ``master``) are tried first, then prefix
    matches (``feature/``, ``release/``). Returns :data:`DEFAULT_PROFILE`
    for unrecognised patterns or ``None`` / ``"HEAD"`` branch.
    """
    func = "_resolve_auto_profile"
    if branch is None or branch == "HEAD":
        return DEFAULT_PROFILE
 
    # Exact match first.
    exact = _AUTO_PROFILE_MAP.get(branch)
    if exact is not None:
        _dbg("GIT", func, f"exact match: {branch!r} -> {exact}", 4)
        return exact
 
    # Prefix match.
    for prefix, profile in _AUTO_PROFILE_MAP.items():
        if prefix.endswith("/") and branch.startswith(prefix):
            _dbg("GIT", func, f"prefix match: {prefix!r} -> {profile}", 4)
            return profile
 
    _dbg("GIT", func, f"no match for {branch!r}, fallback -> {DEFAULT_PROFILE}", 4)
    return DEFAULT_PROFILE
 
 
def resolve_effective_profile(
    branch: str | None,
    octrc: dict | None,
    cli_override: str | None,
    manifest_profile: str | None = None,
    *,
    allow_optout: bool = False,
) -> Profile:
    """Return the profile that should be applied for the current run.
 
    Precedence (highest wins):
 
    1. **Protected-branch override** - if ``branch`` is listed in the
       project's protected-branches set, the result is always
       ``"strict"``. This cannot be overridden by CLI or config.
    2. **CLI ``--profile``** - explicit user override from the command
       line. Must be one of :data:`VALID_PROFILES`.
    3. **Workspace manifest ``subprojects[].profile``** - the profile
       the workspace declares for the owning subproject, supplied by
       the caller via *manifest_profile* (Plan 197). ``None`` means
       "no workspace, or the workspace declares nothing", which
       degrades to the pre-197 octrc-only chain below.
    4. **``.octrc.json → git.pre_commit_profile``** - the persistent
       per-project default.
    5. **``.octrc.json → linter.profile``** - if the git-specific key
       is absent, fall back to the linter-wide profile.
    6. **:data:`DEFAULT_PROFILE`** - final fallback if nothing above
       is set.
 
    Unknown profile strings (from any source) are silently discarded in
    favour of the next lower level of precedence. Malformed ``octrc``
    values are also ignored - never raise.
 
    Plan 197: this is the ONE resolver. Both the single-project path
    (``oct git check`` / ``oct git commit`` run from inside a
    subproject) and the workspace fan-out path
    (``oct.git.oct_git._resolve_subproject_profile``) call it, so a
    file's effective profile cannot depend on the directory the gate
    was invoked from. Callers that have a project root but not a
    manifest profile should use :func:`resolve_profile_for_project`,
    which does the lookup for them.
 
    Plan 209: *allow_optout* is forwarded verbatim to
    :func:`is_protected_branch` - pass ``True`` only when the caller
    has verified the owning subproject is ``nested_git``. Defaults
    False, the safe choice for every ordinary subproject.
    """
    func = "resolve_effective_profile"
    _dbg(
        "GIT", func,
        f"branch={branch!r} cli_override={cli_override!r} "
        f"manifest_profile={manifest_profile!r} allow_optout={allow_optout!r}",
        3,
    )
 
    # 1. Protected branch override (unconditional).
    if is_protected_branch(branch, octrc, allow_optout=allow_optout):
        _dbg("GIT", func, "protected branch -> strict", 4)
        return "strict"
 
    # 2. CLI override.
    if cli_override and cli_override in VALID_PROFILES:
        _dbg("GIT", func, f"cli override -> {cli_override}", 4)
        return cli_override  # type: ignore[return-value]
 
    # 3. Workspace manifest declaration for the owning subproject.
    if manifest_profile and manifest_profile in VALID_PROFILES:
        _dbg("GIT", func, f"manifest -> {manifest_profile}", 4)
        return manifest_profile  # type: ignore[return-value]
 
    # 4 & 5. octrc config.
    if isinstance(octrc, dict):
        git_cfg = octrc.get("git")
        if isinstance(git_cfg, dict):
            candidate = git_cfg.get("pre_commit_profile")
            if isinstance(candidate, str):
                if candidate == "auto":
                    resolved = _resolve_auto_profile(branch)
                    print(
                        f"Auto-selected profile: {resolved} (branch: {branch})",
                        file=sys.stderr,
                    )
                    _dbg("GIT", func, f"auto -> {resolved}", 4)
                    return resolved
                if candidate in VALID_PROFILES:
                    _dbg("GIT", func, f"git.pre_commit_profile -> {candidate}", 4)
                    return candidate  # type: ignore[return-value]
        linter_cfg = octrc.get("linter")
        if isinstance(linter_cfg, dict):
            candidate = linter_cfg.get("profile")
            if isinstance(candidate, str) and candidate in VALID_PROFILES:
                _dbg("GIT", func, f"linter.profile -> {candidate}", 4)
                return candidate  # type: ignore[return-value]
 
    # 6. Final fallback.
    _dbg("GIT", func, f"fallback -> {DEFAULT_PROFILE}", 4)
    return DEFAULT_PROFILE
 
 
def resolve_manifest_profile(project_root: Path) -> str | None:
    """Return the workspace-declared profile for *project_root*.
 
    Walks upward from *project_root* to the nearest
    ``.option_c_workspace.json``, loads it, and returns the ``profile``
    the manifest declares for the subproject that OWNS *project_root*
    (deepest match wins for nested subprojects).
 
    Returns ``None`` - never raises - when any of the following holds,
    so callers degrade cleanly to the pre-197 octrc-only chain:
 
    - *project_root* is not inside a workspace (plain single project);
    - the manifest is unreadable or malformed;
    - *project_root* is the workspace root itself, or otherwise falls
      outside every declared subproject;
    - the owning subproject declares no profile, or declares a value
      outside :data:`VALID_PROFILES`.
 
    Plan 197: this closes the gap that let ``oc_chat`` declare
    ``strict`` and be gated at ``compact`` on every feature branch.
    """
    func = "resolve_manifest_profile"
    _dbg("GIT", func, f"project_root={project_root}", 3)
 
    try:
        from oct.core.workspace import (
            assign_to_subproject,
            find_workspace_root,
            load_workspace,
        )
    except ImportError:  # pragma: no cover - defensive
        _dbg("GIT", func, "workspace module unavailable", 4)
        return None
 
    try:
        ws_root = find_workspace_root(Path(project_root))
        if ws_root is None:
            _dbg("GIT", func, "no workspace manifest above root", 4)
            return None
        workspace = load_workspace(ws_root)
        subproject = assign_to_subproject(Path(project_root), workspace)
    except Exception as exc:
        # A broken manifest must never break the gate - degrade to the
        # octrc-only chain rather than crashing or, worse, guessing.
        _dbg(
            "GIT", func,
            f"manifest lookup failed: {exc!r}; degrading to octrc",
            1, override=True,
        )
        return None
 
    if subproject is None:
        _dbg("GIT", func, "root owned by no subproject", 4)
        return None
 
    profile = getattr(subproject, "profile", None)
    if isinstance(profile, str) and profile in VALID_PROFILES:
        _dbg(
            "GIT", func,
            f"{subproject.name!r} declares {profile}",
            4,
        )
        return profile
 
    _dbg("GIT", func, f"{subproject.name!r} declares nothing usable", 4)
    return None
 
 
def resolve_manifest_nested_git(project_root: Path) -> bool:
    """Return whether *project_root* is declared ``nested_git`` in the manifest.
 
    Mirrors :func:`resolve_manifest_profile`'s walk-up-and-load shape so
    the two lookups can never disagree about WHICH subproject owns
    *project_root*. Returns ``False`` - never raises - for every
    degenerate case (no workspace above *project_root*, an unreadable
    or malformed manifest, or *project_root* falling outside every
    declared subproject): the safe default is "not exempt", i.e. the
    protected-branch opt-out restriction applies.
 
    Plan 209: this is what lets :func:`resolve_profile_for_project`
    pass the correct ``allow_optout`` to :func:`is_protected_branch`
    without every caller having to look up the manifest itself.
    """
    func = "resolve_manifest_nested_git"
    _dbg("GIT", func, f"project_root={project_root}", 3)
 
    try:
        from oct.core.workspace import (
            assign_to_subproject,
            find_workspace_root,
            load_workspace,
        )
    except ImportError:  # pragma: no cover - defensive
        _dbg("GIT", func, "workspace module unavailable", 4)
        return False
 
    try:
        ws_root = find_workspace_root(Path(project_root))
        if ws_root is None:
            _dbg("GIT", func, "no workspace manifest above root", 4)
            return False
        workspace = load_workspace(ws_root)
        subproject = assign_to_subproject(Path(project_root), workspace)
    except Exception as exc:
        # A broken manifest must never break the gate, and must never
        # grant an opt-out by accident - degrade to "not exempt".
        _dbg(
            "GIT", func,
            f"manifest lookup failed: {exc!r}; degrading to False",
            1, override=True,
        )
        return False
 
    if subproject is None:
        _dbg("GIT", func, "root owned by no subproject", 4)
        return False
 
    nested_git = bool(getattr(subproject, "nested_git", False))
    _dbg("GIT", func, f"{subproject.name!r} nested_git={nested_git}", 4)
    return nested_git
 
 
def resolve_profile_for_project(
    project_root: Path,
    branch: str | None,
    octrc: dict | None,
    cli_override: str | None,
) -> Profile:
    """Resolve the effective profile for a project on disk.
 
    Thin composition of :func:`resolve_manifest_profile`,
    :func:`resolve_manifest_nested_git`, and
    :func:`resolve_effective_profile`: the single entry point for
    callers that hold a project root. Using it instead of calling
    :func:`resolve_effective_profile` directly is what makes the
    single-project path agree with the workspace fan-out path
    (Plan 197) - including, since Plan 209, on the protected-branch
    opt-out restriction.
    """
    func = "resolve_profile_for_project"
    manifest_profile = resolve_manifest_profile(project_root)
    allow_optout = resolve_manifest_nested_git(project_root)
    profile = resolve_effective_profile(
        branch, octrc, cli_override, manifest_profile=manifest_profile,
        allow_optout=allow_optout,
    )
    _dbg("GIT", func, f"root={project_root} -> {profile}", 3)
    return profile
 
 
# ---------------------------------------------------------------------
# Exit code derivation
# ---------------------------------------------------------------------
 
 
def apply_profile_policy(profile: str, result: "QualityGateResult") -> int:
    """Derive the semantic exit code for a quality-gate result.
 
    Exit code table (blueprint §5.3, verbatim):
 
    ==== ==========================================================
    Code Meaning
    ==== ==========================================================
       0 all checks pass
       1 lint violations (blocking under this profile)
       2 format violations (blocking under this profile)
       3 both lint and format violations
       4 test failures (when ``--include-tests``)
       5 secrets detected - always blocking
    ==== ==========================================================
 
    Precedence: ``5 > 4 > 3 > 2 > 1 > 0``. The first rule that matches
    wins. Because secrets takes precedence, a profile that would
    otherwise return 0 (e.g. ``proto`` with warnings-only lint) still
    returns 5 if secrets are present. This is the "secrets always
    blocks" invariant.
 
    For profiles where a check is not blocking (``proto`` lint is
    ``warn``; ``proto`` format is ``skip``), the corresponding violation
    counter never contributes to the exit code even if non-zero.
 
    Parameters
    ----------
    profile
        One of ``"proto"``, ``"compact"``, ``"strict"``. Unknown values
        degrade to :data:`DEFAULT_PROFILE`.
    result
        A :class:`~oct.git.quality_gate.QualityGateResult` with the raw
        counts from a completed gate run.
    """
    func = "apply_profile_policy"
    if profile not in PROFILE_MATRIX:
        profile = DEFAULT_PROFILE
    matrix = PROFILE_MATRIX[profile]
 
    lint_blocking = matrix["lint"] == "blocking"
    format_blocking = matrix["format"] == "blocking"
    # OI-531: 'optional' is truly non-blocking - test failures under the
    # compact profile surface as a warning, never an exit code. Only
    # 'blocking' drives the exit.
    tests_blocking = matrix["tests"] == "blocking"
 
    has_secrets = bool(result.secrets_findings)
    has_lint = result.lint_violations > 0 and lint_blocking
    has_format = result.format_violations > 0 and format_blocking
    has_tests = result.test_failures > 0 and tests_blocking
 
    _dbg(
        "GIT", func,
        f"profile={profile} secrets={has_secrets} lint={has_lint} "
        f"format={has_format} tests={has_tests}",
        4,
    )
 
    # Precedence 5 > 4 > 3 > 2 > 1 > 0.
    if has_secrets:
        return 5
    if has_tests:
        return 4
    if has_lint and has_format:
        return 3
    if has_format:
        return 2
    if has_lint:
        return 1
    return 0
 
 
# ---------------------------------------------------------------------
# Protected-branch commit guard (Phase 4D - G-D7)
# ---------------------------------------------------------------------
 
 
def check_protected_branch_commit(
    branch: str | None,
    octrc: dict | None,
    profile: str,
) -> tuple[bool, str]:
    """Check if committing directly to a protected branch.
 
    Returns ``(blocked, message)``:
 
    - On a **non-protected branch**: ``(False, "")``.
    - On a protected branch in ``strict`` profile: ``(True, error_msg)``.
    - On a protected branch in other profiles: ``(False, warning_msg)``.
 
    The caller is responsible for printing the message and aborting if
    ``blocked`` is ``True``.
    """
    func = "check_protected_branch_commit"
    if not is_protected_branch(branch, octrc):
        return False, ""
 
    msg = (
        f"Warning: committing directly to protected branch '{branch}'."
    )
    _dbg("GIT", func, f"branch={branch!r} profile={profile}", 3)
 
    if profile == "strict":
        return True, (
            f"Blocked: direct commit to protected branch '{branch}' "
            f"is not allowed under strict profile."
        )
    return False, msg
 
 
# ---------------------------------------------------------------------
# .gitignore - OCT-managed block helpers (Phase 4G)
# ---------------------------------------------------------------------
 
#: Marker comments that delimit the OCT-managed block in ``.gitignore``.
#: The literals are kept stable for backwards compatibility with files
#: created by older versions of ``oct git init``.
OC_GITIGNORE_MARKER_START: str = "# --- Option C defaults ---"
OC_GITIGNORE_MARKER_END: str = "# --- end Option C ---"
 
#: Characters that are legal in gitignore patterns. Anything else is
#: refused by :func:`validate_ignore_pattern` to keep the block
#: hand-readable and to prevent accidental injection.
_VALID_PATTERN_RE: re.Pattern[str] = re.compile(r"^[A-Za-z0-9_./*?\‍[\‍]\-]+$")
 
 
def validate_ignore_pattern(pattern: str) -> tuple[bool, str]:
    """Return ``(valid, message)`` for a candidate gitignore pattern.
 
    Rejects empty strings, patterns containing newlines, leading ``!``
    (negation - too easy to weaponise via ``oct git ignore``), absolute
    paths (leading ``/`` is interpreted as anchored to repo root which
    is allowed by gitignore but our policy is to require relative
    patterns), and any character outside :data:`_VALID_PATTERN_RE`.
    """
    func = "validate_ignore_pattern"
    if not isinstance(pattern, str):
        return False, f"pattern must be a string, got {type(pattern).__name__}"
    if not pattern.strip():
        return False, "pattern is empty"
    if "\n" in pattern or "\r" in pattern:
        return False, "pattern contains a newline"
    if pattern.startswith("!"):
        return False, "negation patterns ('!...') are not allowed"
    if pattern.startswith("/"):
        return False, "absolute patterns (leading '/') are not allowed"
    if not _VALID_PATTERN_RE.match(pattern):
        return False, (
            "pattern contains characters outside the safe set "
            "[A-Za-z0-9_./*?[]-]"
        )
    _dbg("GIT", func, f"pattern={pattern!r} ok", 4)
    return True, ""
 
 
def _read_gitignore(repo_root: Path) -> list[str]:
    """Return the lines of ``.gitignore`` (no trailing newlines)."""
    path = Path(repo_root) / ".gitignore"
    if not path.is_file():
        return []
    return path.read_text(encoding="utf-8").splitlines()
 
 
def _write_gitignore(repo_root: Path, lines: list[str]) -> None:
    """Write *lines* back to ``.gitignore`` with trailing newline."""
    path = Path(repo_root) / ".gitignore"
    body = "\n".join(lines)
    if body and not body.endswith("\n"):
        body += "\n"
    path.write_text(body, encoding="utf-8")
 
 
def _find_oct_block(lines: list[str]) -> tuple[int, int]:
    """Return ``(start, end)`` line indices of the OCT block in *lines*.
 
    ``start`` is the index of the start marker, ``end`` the index of
    the end marker (inclusive). Returns ``(-1, -1)`` if the block is
    absent or malformed (start without end).
    """
    start = -1
    end = -1
    for idx, line in enumerate(lines):
        stripped = line.strip()
        if stripped == OC_GITIGNORE_MARKER_START:
            start = idx
        elif stripped == OC_GITIGNORE_MARKER_END and start != -1:
            end = idx
            break
    if start == -1 or end == -1:
        return -1, -1
    return start, end
 
 
def list_ignore_patterns(repo_root: Path) -> tuple[list[str], list[str]]:
    """Return ``(oct_managed, other)`` patterns from ``.gitignore``.
 
    Patterns inside the OCT-managed block are returned in the first
    list; everything else (user-managed) is returned in the second.
    Comment lines and blank lines are excluded from both.
    """
    func = "list_ignore_patterns"
    _dbg("GIT", func, f"repo_root={repo_root}", 3)
    lines = _read_gitignore(repo_root)
    if not lines:
        return [], []
    start, end = _find_oct_block(lines)
    oct_managed: list[str] = []
    other: list[str] = []
    for idx, line in enumerate(lines):
        stripped = line.strip()
        if not stripped or stripped.startswith("#"):
            continue
        if start != -1 and start < idx < end:
            oct_managed.append(stripped)
        else:
            other.append(stripped)
    _dbg(
        "GIT", func,
        f"oct={len(oct_managed)} other={len(other)}",
        4,
    )
    return oct_managed, other
 
 
def add_ignore_patterns(
    repo_root: Path,
    patterns: list[str],
) -> list[str]:
    """Append *patterns* to the OCT-managed block of ``.gitignore``.
 
    Creates the block (with markers) if it does not exist. Patterns
    already present anywhere in the file are skipped. Returns the list
    of patterns actually added (in input order, after dedup).
 
    Caller is responsible for validating each pattern via
    :func:`validate_ignore_pattern` first.
    """
    func = "add_ignore_patterns"
    _dbg("GIT", func, f"repo_root={repo_root} patterns={len(patterns)}", 3)
    lines = _read_gitignore(repo_root)
    existing: set[str] = {
        line.strip() for line in lines
        if line.strip() and not line.strip().startswith("#")
    }
    to_add = [p for p in patterns if p not in existing]
    if not to_add:
        _dbg("GIT", func, "no new patterns to add", 4)
        return []
 
    start, end = _find_oct_block(lines)
    if start == -1:
        # Block does not exist - append a fresh one.
        new_lines = list(lines)
        if new_lines and new_lines[-1].strip() != "":
            new_lines.append("")
        new_lines.append(OC_GITIGNORE_MARKER_START)
        new_lines.extend(to_add)
        new_lines.append(OC_GITIGNORE_MARKER_END)
    else:
        # Insert before the end marker.
        new_lines = list(lines[:end]) + to_add + list(lines[end:])
 
    _write_gitignore(repo_root, new_lines)
    _dbg("GIT", func, f"added {len(to_add)} pattern(s)", 4)
    return to_add
 
 
def remove_ignore_pattern(
    repo_root: Path,
    pattern: str,
) -> tuple[bool, str]:
    """Remove *pattern* from the OCT-managed block.
 
    Returns ``(removed, message)``. Refuses to touch patterns located
    outside the OCT block (those are user-managed); the caller should
    surface the message to the user.
    """
    func = "remove_ignore_pattern"
    _dbg("GIT", func, f"repo_root={repo_root} pattern={pattern!r}", 3)
    lines = _read_gitignore(repo_root)
    if not lines:
        return False, ".gitignore does not exist"
    start, end = _find_oct_block(lines)
    if start == -1:
        return False, "OCT-managed block not found in .gitignore"
 
    target_idx = -1
    for idx in range(start + 1, end):
        if lines[idx].strip() == pattern:
            target_idx = idx
            break
 
    if target_idx == -1:
        # Check whether it's outside the block - give a helpful error.
        for idx, line in enumerate(lines):
            if line.strip() == pattern and not (start < idx < end):
                return False, (
                    f"pattern '{pattern}' is outside the OCT-managed "
                    f"block; remove it manually with a text editor"
                )
        return False, f"pattern '{pattern}' not found in OCT-managed block"
 
    new_lines = list(lines[:target_idx]) + list(lines[target_idx + 1:])
    _write_gitignore(repo_root, new_lines)
    _dbg("GIT", func, f"removed pattern at line {target_idx}", 4)
    return True, ""