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).
- 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:
    L3 — profile resolution and policy decisions
    L4 — per-field raw counts during exit-code derivation
 
Contracts
---------
- This module is pure: no filesystem, no subprocess, no Click.
- ``resolve_effective_profile`` never raises; unknown values collapse
  to the documented default.
- ``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.
"""
 
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",
        "tests": "skip",
    },
    "compact": {
        "lint": "blocking",
        "format": "blocking",
        "secrets": "blocking",
        "tests": "optional",
    },
    "strict": {
        "lint": "blocking",
        "format": "blocking",
        "secrets": "blocking",
        "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) -> 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.
    """
    func = "is_protected_branch"
    _dbg("GIT", func, f"branch={branch!r}", 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
    protected: list[str] | tuple[str, ...] = DEFAULT_PROTECTED_BRANCHES
    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.
                protected = [b for b in candidate if isinstance(b, str)]
    result = branch in protected
    _dbg("GIT", func, f"result={result} protected={list(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,
) -> 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. **``.octrc.json → git.pre_commit_profile``** — the persistent
       per-project default.
    4. **``.octrc.json → linter.profile``** — if the git-specific key
       is absent, fall back to the linter-wide profile.
    5. **: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.
    """
    func = "resolve_effective_profile"
    _dbg(
        "GIT", func,
        f"branch={branch!r} cli_override={cli_override!r}",
        3,
    )
 
    # 1. Protected branch override (unconditional).
    if is_protected_branch(branch, octrc):
        _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 & 4. 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]
 
    # 5. Final fallback.
    _dbg("GIT", func, f"fallback -> {DEFAULT_PROFILE}", 4)
    return DEFAULT_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, ""