vigil-codeintel 0.1.0__py3-none-any.whl

vigil_forensic/gate_checks/authority_checks.py

@@ -0,0 +1,95 @@
+"""Authority-related forensic checks (Finding 6.1).
+
+illegal_authority_writer: flag new writer functions appearing in modules that
+previously had none -- signals unauthorized authority expansion.
+"""
+from __future__ import annotations
+
+import logging
+
+from vigil_forensic._shared import EvidenceReference, GateCategory, GateImpact, GateSeverity, RepairKind
+from vigil_forensic.gate_models import PostExecGateContext
+from ..source_analysis import is_source_file
+from .common import build_check_result, build_finding, normalize_path
+from vigil_forensic._git_utils import git_show as _git_show
+
+_log = logging.getLogger(__name__)
+
+WRITER_PREFIXES = ("def write_", "def save_", "def commit_", "def delete_", "def persist_")
+
+
+def _count_writers(content: str) -> int:
+    """Count writer-named function definitions in source content."""
+    return sum(content.count(prefix) for prefix in WRITER_PREFIXES)
+
+
+def run_authority_checks(ctx: PostExecGateContext):
+    """Emit findings for NEW writer functions in previously-read-only modules.
+
+    For each changed .py file observed in the gate context:
+    - If prior content (HEAD~1) has ZERO writer-named defs
+    - And current content has >=1 writer-named def
+    - Then emit a warning finding.
+
+    Missing files (newly added) are NOT flagged -- new files are new authority
+    by definition and should be reviewed separately.
+
+    Fails open: git unavailable or any I/O error -> skip that file, never crash.
+    """
+    findings = []
+
+    for raw_path in ctx.changed_files_observed:
+        normalized = normalize_path(raw_path)
+        if not is_source_file(normalized):
+            continue
+
+        prior = _git_show(normalized)
+        if prior is None:
+            # File didn't exist before OR git unavailable — skip, not a violation
+            continue
+
+        abs_path = ctx.project_dir / normalized
+        try:
+            current = abs_path.read_text(encoding="utf-8")
+        except (OSError, UnicodeDecodeError) as exc:
+            _log.debug("authority_checks: cannot read current file %s: %s", normalized, exc)
+            continue
+
+        if _count_writers(prior) == 0 and _count_writers(current) > 0:
+            findings.append(
+                build_finding(
+                    check_id="illegal_authority_writer.new_writer_in_readonly_module",
+                    category=GateCategory.CONTRACT,
+                    title="Illegal authority expansion: new writer function in previously read-only module",
+                    severity=GateSeverity.MEDIUM,
+                    impact=GateImpact.REVISE,
+                    summary=(
+                        f"{normalized} introduced new writer function(s) "
+                        f"(write_/save_/commit_/delete_/persist_) where none existed "
+                        f"previously. Verify authority expansion is intentional and "
+                        f"covered by authority map."
+                    ),
+                    recommendation=(
+                        "If the writer function is intentional, update the project authority map "
+                        "to document the new write authority. "
+                        "If unintentional, remove or relocate the function."
+                    ),
+                    evidence=[
+                        EvidenceReference(
+                            kind="file",
+                            path=normalized,
+                            detail="new_writer_in_previously_readonly_module",
+                        )
+                    ],
+                    repair_kind=RepairKind.VALIDATE_BOUNDARY.value,
+                    executor_action="Validate authority boundaries",
+                    proof_required="Authority respected",
+                    allowlist_allowed=False,
+                )
+            )
+
+    return build_check_result(
+        check_id="authority_checks",
+        category=GateCategory.CONTRACT,
+        findings=findings,
+    )

vigil_forensic/gate_checks/boundary_breach_checks.py

@@ -0,0 +1,202 @@
+"""Boundary breach forensic gate (Finding 6.5).
+
+boundary_breach: detect when a PR touches files that fall outside every
+declared refactor boundary listed in .cortex/maps/70_refactor_boundaries.json.
+
+Primary path: use ctx.maps.refactor_boundary when hydrated.
+Fallback: read JSON file directly (legacy callers / maps not loaded).
+
+Fail-open: map missing, unreadable, or malformed -> return empty findings.
+"""
+from __future__ import annotations
+
+import fnmatch
+import json
+import logging
+from pathlib import Path
+from typing import Any
+
+from vigil_forensic._shared import EvidenceReference, GateCategory, GateCheckResult, GateImpact, GateSeverity, RepairKind
+from vigil_forensic.gate_models import PostExecGateContext
+
+_CATEGORY = GateCategory.CONTRACT
+from .common import build_check_result, build_finding, normalize_path
+
+_log = logging.getLogger(__name__)
+
+_MAP_REL_PATH = ".cortex/maps/70_refactor_boundaries.json"
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _file_in_boundary(file_path: str, includes: list[str]) -> bool:
+    """Return True if *file_path* matches any include glob."""
+    for pattern in includes:
+        if fnmatch.fnmatch(file_path, pattern):
+            return True
+    return False
+
+
+def _load_boundaries(project_dir: Path) -> list[dict[str, Any]] | None:
+    """Load boundary entries from the map file.
+
+    Returns a list of entry dicts on success, or None on any failure
+    (missing file, JSON error, unexpected top-level shape).
+    """
+    map_path = project_dir / _MAP_REL_PATH
+    try:
+        raw = map_path.read_text(encoding="utf-8")
+    except OSError as exc:
+        _log.debug("boundary_breach: map not found at %s: %s", map_path, exc)
+        return None
+
+    try:
+        data = json.loads(raw)
+    except json.JSONDecodeError as exc:
+        _log.debug("boundary_breach: map JSON malformed: %s", exc)
+        return None
+
+    if not isinstance(data, dict):
+        _log.debug("boundary_breach: map root is not a dict")
+        return None
+
+    # Support both top-level keys used across spec versions.
+    entries_raw = data.get("entries") or data.get("boundaries")
+    if not isinstance(entries_raw, list):
+        _log.debug("boundary_breach: map has no 'entries' or 'boundaries' list")
+        return None
+
+    return [e for e in entries_raw if isinstance(e, dict)]
+
+
+def _build_includes(entry: dict[str, Any]) -> list[str]:
+    """Extract glob patterns from an entry regardless of which key is used.
+
+    Supported keys (in order of preference):
+      - ``includes``     (spec-documented key)
+      - ``allowed_files`` (map_builder key, exact paths treated as globs)
+    """
+    includes_raw = entry.get("includes") or entry.get("allowed_files")
+    if isinstance(includes_raw, list):
+        return [str(p) for p in includes_raw if p]
+    return []
+
+
+def _entry_from_boundary(b: Any) -> dict[str, Any]:
+    """Convert a RefactorBoundary dataclass instance to the dict format used internally."""
+    return {
+        "boundary_id": b.boundary_id,
+        "allowed_files": list(b.allowed_files),
+        "watch_files": list(b.watch_files),
+        "forbidden_files": list(b.forbidden_files),
+        # no "active" key → _is_boundary_active returns True (all are active)
+    }
+
+
+def _is_boundary_active(entry: dict[str, Any]) -> bool:
+    """Return True if the boundary should be checked.
+
+    When no ``active`` flag is present all boundaries are considered active.
+    When the flag is present it must be truthy to be active.
+    """
+    if "active" not in entry:
+        return True
+    return bool(entry["active"])
+
+
+# ---------------------------------------------------------------------------
+# Public gate function
+# ---------------------------------------------------------------------------
+
+
+def run_boundary_breach_checks(ctx: PostExecGateContext) -> GateCheckResult:
+    """Emit a finding for every changed file that matches no active boundary.
+
+    Primary path: use ctx.maps.refactor_boundary when hydrated and not missing.
+    Fallback: read map JSON file from disk (legacy callers / maps not loaded).
+
+    Fail-open: if the map is missing or malformed, return empty findings.
+    """
+    # --- Primary: ctx.maps ---------------------------------------------------
+    boundaries: list[dict[str, Any]] | None = None
+    if ctx.maps is not None and not getattr(ctx.maps, "missing", False):
+        rb = getattr(ctx.maps, "refactor_boundary", None)
+        if rb:
+            boundaries = [_entry_from_boundary(b) for b in rb]
+            _log.debug("boundary_breach: using %d entries from ctx.maps", len(boundaries))
+
+    # --- Fallback: file read --------------------------------------------------
+    if boundaries is None:
+        boundaries = _load_boundaries(ctx.project_dir)
+
+    if boundaries is None:
+        return build_check_result(
+            check_id="boundary_breach",
+            category=_CATEGORY,
+            notes=["boundary_breach: map missing or malformed -- skipped (fail-open)"],
+        )
+
+    active_include_lists: list[tuple[str, list[str]]] = []
+    for entry in boundaries:
+        if not _is_boundary_active(entry):
+            continue
+        includes = _build_includes(entry)
+        if not includes:
+            continue
+        name = str(entry.get("boundary_id") or entry.get("name") or "unnamed")
+        active_include_lists.append((name, includes))
+
+    if not active_include_lists:
+        return build_check_result(
+            check_id="boundary_breach",
+            category=_CATEGORY,
+            notes=["boundary_breach: no active boundaries with include patterns -- skipped"],
+        )
+
+    findings = []
+    for raw_path in ctx.changed_files_observed:
+        normalized = normalize_path(raw_path)
+        in_any = any(
+            _file_in_boundary(normalized, includes)
+            for _name, includes in active_include_lists
+        )
+        if not in_any:
+            boundary_names = [name for name, _ in active_include_lists]
+            findings.append(
+                build_finding(
+                    check_id="boundary_breach.file_outside_all_boundaries",
+                    category=_CATEGORY,
+                    title="Changed file is outside all declared refactor boundaries",
+                    severity=GateSeverity.MEDIUM,
+                    impact=GateImpact.REVISE,
+                    summary=(
+                        f"File '{normalized}' was changed but does not match any active "
+                        f"boundary ({', '.join(boundary_names)})."
+                    ),
+                    recommendation=(
+                        "Confirm that this change is intentional.  If it is part of the "
+                        "current refactor, update the boundary definition in "
+                        f"{_MAP_REL_PATH} to include this file."
+                    ),
+                    evidence=[
+                        EvidenceReference(
+                            kind="changed_file",
+                            path=normalized,
+                            detail=f"not matched by boundaries: {boundary_names}",
+                        )
+                    ],
+                    repair_kind=RepairKind.VALIDATE_BOUNDARY.value,
+                    executor_action="Address finding details",
+                    proof_required="Authority respected",
+                    allowlist_allowed=False,
+                )
+            )
+
+    return build_check_result(
+        check_id="boundary_breach",
+        category=_CATEGORY,
+        findings=findings,
+    )

vigil_forensic/gate_checks/broad_except_checks.py

@@ -0,0 +1,301 @@
+from __future__ import annotations
+
+import ast
+import re
+
+from vigil_forensic._shared import EvidenceReference, GateCategory, GateImpact, GateSeverity, RepairKind
+from vigil_forensic.gate_models import PostExecGateContext
+from ..source_analysis import is_source_file
+from .common import build_check_result, build_finding, iter_touched_snapshots
+import logging
+_log = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Pattern: except Exception: \n    pass  (also except Exception as e: \n    pass)
+# ---------------------------------------------------------------------------
+_BROAD_EXCEPT_RE = re.compile(
+    r'^(\s*)except\s+Exception\s*(?:as\s+\w+)?\s*:\s*\n\1\s+pass\b',
+    re.MULTILINE,
+)
+
+# NOTE: bare ``except:`` and ``except BaseException:`` are detected via AST in
+# _check_bare_and_base_handlers (not regex) so the handler BODY can be inspected
+# for a re-raise. A line-only regex cannot tell a swallow from the correct
+# cancel-cleanup idiom (``except BaseException: <cleanup>; raise``).
+
+# _EXCEPT_RETURN_SENTINEL_RE was removed (fix 3): the regex matched ANY exception
+# type including narrow ones (OSError, ValueError) causing false positives.
+# Replaced by AST-based _check_broad_return_sentinel below.
+
+_BROAD_EXCEPTION_NAMES: frozenset[str] = frozenset({"Exception", "BaseException"})
+_SENTINEL_CONSTS: frozenset[object] = frozenset({None})
+
+
+def _is_broad_handler(handler: ast.ExceptHandler) -> bool:
+    """Return True for bare except: or except Exception/BaseException: — mirrors _is_narrow_catch."""
+    if handler.type is None:
+        return True
+    if isinstance(handler.type, ast.Name) and handler.type.id in _BROAD_EXCEPTION_NAMES:
+        return True
+    if isinstance(handler.type, ast.Tuple):
+        for elt in handler.type.elts:
+            if isinstance(elt, ast.Name) and elt.id in _BROAD_EXCEPTION_NAMES:
+                return True
+    return False
+
+
+def _reraises(handler: ast.ExceptHandler) -> bool:
+    """Return True if the handler body re-raises the exception.
+
+    A ``raise`` statement at the TOP LEVEL of the handler body — either a bare
+    ``raise`` (re-raise current exception) or ``raise <something>`` (chain /
+    translate) — means the error propagates. This is the cancel-cleanup idiom::
+
+        except BaseException:
+            <cleanup>
+            raise
+
+    which is correct and must NOT be flagged as a swallow. Verified against
+    filelock/_api.py:513-517.
+
+    Only top-level statements of the handler body are considered: a ``raise``
+    nested inside an inner ``try``/``if`` that the broad handler could still
+    swallow does not count as a guaranteed re-raise.
+    """
+    return any(isinstance(stmt, ast.Raise) for stmt in handler.body)
+
+
+def _check_bare_and_base_handlers(text: str, snapshot_path: str, findings: list) -> None:
+    """AST-based bare-except / except-BaseException detector.
+
+    Replaces the line-only regex checks (_BARE_EXCEPT_RE / _BASE_EXCEPTION_RE)
+    so the handler BODY can be inspected: a handler that re-raises
+    (``except BaseException: ...; raise``) is the correct cancel-cleanup idiom
+    and is NOT flagged. Genuine swallows (bare/BaseException with no re-raise)
+    are still flagged.
+    """
+    try:
+        tree = ast.parse(text)
+    except SyntaxError:
+        return
+    for node in ast.walk(tree):
+        if not isinstance(node, ast.Try):
+            continue
+        for handler in node.handlers:
+            is_bare = handler.type is None
+            is_base = (
+                isinstance(handler.type, ast.Name)
+                and handler.type.id == "BaseException"
+            )
+            if not (is_bare or is_base):
+                continue
+            if _reraises(handler):
+                # Cancel-cleanup idiom — re-raises, does not swallow.
+                continue
+            line_no = getattr(handler, "lineno", 0) or 0
+            if is_bare:
+                _emit(
+                    findings,
+                    check_id="broad_except.bare",
+                    snapshot_path=snapshot_path,
+                    line_no=line_no,
+                    title=f"Bare 'except:' in {snapshot_path}:{line_no}",
+                    summary=(
+                        f"File {snapshot_path} line {line_no} uses a bare 'except:' clause which "
+                        "catches all exceptions including SystemExit and KeyboardInterrupt. "
+                        "This prevents clean process shutdown and hides all errors."
+                    ),
+                    repair_kind=RepairKind.REMOVE_FALLBACK.value,
+                    executor_action="Narrow exception to specific type",
+                    proof_required="No broad except in file",
+                    allowlist_allowed=False,
+                )
+            else:
+                _emit(
+                    findings,
+                    check_id="broad_except.base_exception",
+                    snapshot_path=snapshot_path,
+                    line_no=line_no,
+                    title=f"'except BaseException' in {snapshot_path}:{line_no}",
+                    summary=(
+                        f"File {snapshot_path} line {line_no} catches BaseException, which includes "
+                        "SystemExit and KeyboardInterrupt. This is equivalent to a bare except and "
+                        "prevents clean process shutdown."
+                    ),
+                    repair_kind=RepairKind.REMOVE_FALLBACK.value,
+                    executor_action="Narrow exception to specific type",
+                    proof_required="No broad except in file",
+                    allowlist_allowed=False,
+                )
+
+
+def _handler_returns_sentinel(handler: ast.ExceptHandler) -> tuple[bool, str]:
+    """Return (True, sentinel_str) if handler body contains a return of None/{}/[].
+
+    Checks ALL return statements in the body (not just the last line), so this
+    catches both single-line and multi-line handler bodies.
+    """
+    _SENTINEL_STRS = {"None": "None", "{}": "{}", "[]": "[]"}
+    for node in ast.walk(ast.Module(body=handler.body, type_ignores=[])):
+        if isinstance(node, ast.Return):
+            val = node.value
+            if val is None:
+                return True, "None"
+            if isinstance(val, ast.Constant) and val.value is None:
+                return True, "None"
+            if isinstance(val, ast.Dict) and not val.keys:
+                return True, "{}"
+            if isinstance(val, ast.List) and not val.elts:
+                return True, "[]"
+    return False, ""
+
+
+def _check_broad_return_sentinel(text: str, snapshot_path: str, findings: list) -> None:
+    """AST-based replacement for the old _EXCEPT_RETURN_SENTINEL_RE check.
+
+    Only flags broad catches (bare except / except Exception / except BaseException)
+    that return a sentinel (None, {}, []). Narrow types (OSError, ValueError, etc.)
+    are explicitly excluded — they represent intentional, type-scoped fallbacks.
+    """
+    try:
+        tree = ast.parse(text)
+    except SyntaxError:
+        return
+    for node in ast.walk(tree):
+        if not isinstance(node, (ast.Try,)):
+            continue
+        for handler in getattr(node, "handlers", []):
+            if not _is_broad_handler(handler):
+                continue
+            is_sentinel, sentinel_str = _handler_returns_sentinel(handler)
+            if not is_sentinel:
+                continue
+            line_no = getattr(handler, "lineno", 0) or 0
+            findings.append(
+                build_finding(
+                    check_id="broad_except.return_none",
+                    category=GateCategory.FALLBACK,
+                    title=f"Silent sentinel return '{sentinel_str}' after broad except in {snapshot_path}:{line_no}",
+                    severity=GateSeverity.MEDIUM,
+                    impact=GateImpact.REVISE,
+                    summary=(
+                        f"File {snapshot_path} line {line_no} catches an exception and returns a "
+                        f"sentinel value ({sentinel_str}). The caller cannot distinguish success from "
+                        "failure — errors are silently swallowed."
+                    ),
+                    recommendation=(
+                        "Narrow the exception to specific types (e.g. OSError, ValueError) "
+                        "and surface the error via logging or re-raise. "
+                        "Never silently drop exceptions that cross a function boundary."
+                    ),
+                    evidence=[EvidenceReference(kind="file", path=snapshot_path, detail=f"line:{line_no}")],
+                    repair_kind=RepairKind.REMOVE_FALLBACK.value,
+                    executor_action="Narrow exception to specific type",
+                    proof_required="No broad except in file",
+                    allowlist_allowed=False,
+                )
+            )
+
+# ---------------------------------------------------------------------------
+# Pattern: except <anything>: \n    log.warning(...) \n    pass  (log-then-swallow)
+# ---------------------------------------------------------------------------
+_EXCEPT_LOG_SWALLOW_RE = re.compile(
+    r'except\s+\w[^:]*:\s*\n(\s+)(?:_log|log|logger|logging)\.\w+\([^)]*\)\s*\n\1pass\b',
+    re.MULTILINE,
+)
+
+
+def _emit(
+    findings: list,
+    *,
+    check_id: str,
+    snapshot_path: str,
+    line_no: int,
+    title: str,
+    summary: str,
+    repair_kind: str = "",
+    executor_action: str = "",
+    proof_required: str = "",
+    allowlist_allowed: bool = False,
+) -> None:
+    findings.append(
+        build_finding(
+            check_id=check_id,
+            category=GateCategory.FALLBACK,
+            title=title,
+            severity=GateSeverity.MEDIUM,
+            impact=GateImpact.REVISE,
+            summary=summary,
+            recommendation=(
+                "Narrow the exception to specific types (e.g. OSError, ValueError) "
+                "and surface the error via logging or re-raise. "
+                "Never silently drop exceptions that cross a function boundary."
+            ),
+            evidence=[EvidenceReference(kind="file", path=snapshot_path, detail=f"line:{line_no}")],
+            repair_kind=repair_kind,
+            executor_action=executor_action,
+            proof_required=proof_required,
+            allowlist_allowed=allowlist_allowed,
+        )
+    )
+
+
+def run_broad_except_checks(ctx: PostExecGateContext):
+    findings: list = []
+
+    for snapshot in iter_touched_snapshots(ctx):
+        if not snapshot.exists or not is_source_file(snapshot.path):
+            continue
+
+        text = snapshot.text
+        normalized = snapshot.path
+
+        # --- broad_except.swallow: except Exception: pass ---
+        for match in _BROAD_EXCEPT_RE.finditer(text):
+            line_no = text[:match.start()].count("\n") + 1
+            _emit(
+                findings,
+                check_id="broad_except.swallow",
+                snapshot_path=normalized,
+                line_no=line_no,
+                title=f"Broad 'except Exception: pass' in {normalized}:{line_no}",
+                summary=(
+                    f"File {normalized} line {line_no} catches all exceptions and "
+                    "silently passes. This can hide real errors including filesystem "
+                    "failures, type errors, and logic bugs."
+                ),
+                repair_kind=RepairKind.REMOVE_FALLBACK.value,
+                executor_action="Narrow exception to specific type",
+                proof_required="No broad except in file",
+                allowlist_allowed=False,
+            )
+
+        # --- broad_except.bare + broad_except.base_exception: AST-based ---
+        # Re-raising handlers (cancel-cleanup idiom) are skipped — see
+        # _check_bare_and_base_handlers / _reraises.
+        _check_bare_and_base_handlers(text, normalized, findings)
+
+        # --- broad_except.return_none: AST-based check (only broad catches) ---
+        _check_broad_return_sentinel(text, normalized, findings)
+
+        # --- broad_except.log_swallow: except ...: log.X(...); pass ---
+        for match in _EXCEPT_LOG_SWALLOW_RE.finditer(text):
+            line_no = text[:match.start()].count("\n") + 1
+            _emit(
+                findings,
+                check_id="broad_except.log_swallow",
+                snapshot_path=normalized,
+                line_no=line_no,
+                title=f"Log-then-swallow pattern in {normalized}:{line_no}",
+                summary=(
+                    f"File {normalized} line {line_no} logs the exception then passes. "
+                    "The error is silently consumed — callers receive no signal that the "
+                    "operation failed."
+                ),
+                repair_kind=RepairKind.REMOVE_FALLBACK.value,
+                executor_action="Narrow exception to specific type",
+                proof_required="No broad except in file",
+                allowlist_allowed=False,
+            )
+
+    return build_check_result(check_id="broad_except", category=GateCategory.FALLBACK, findings=findings)