vigil-codeintel 0.1.0__py3-none-any.whl

vigil_forensic/gate_checks/export_completeness_checks.py

@@ -0,0 +1,156 @@
+from __future__ import annotations
+
+import ast
+import logging
+
+from vigil_forensic._shared import EvidenceReference, GateCategory, GateImpact, GateSeverity, RepairKind
+from vigil_forensic.gate_models import PostExecGateContext
+from vigil_forensic.gate_checks.common import build_check_result, build_finding, normalize_path
+
+_log = logging.getLogger(__name__)
+
+
+def _extract_all_names(tree: ast.Module) -> list[str] | None:
+    """Return the list of names declared in a top-level ``__all__`` assignment.
+
+    Handles ``__all__ = [...]`` and ``__all__ = (...)``.
+    Returns None if no ``__all__`` assignment is found at module level.
+    Returns an empty list if ``__all__`` is found but contains no string constants.
+    """
+    for node in tree.body:
+        if not isinstance(node, ast.Assign):
+            continue
+        for target in node.targets:
+            if not (isinstance(target, ast.Name) and target.id == "__all__"):
+                continue
+            # Found an __all__ assignment — extract string elements
+            names: list[str] = []
+            value = node.value
+            if isinstance(value, (ast.List, ast.Tuple)):
+                for elt in value.elts:
+                    if isinstance(elt, ast.Constant) and isinstance(elt.value, str):
+                        names.append(elt.value)
+            return names
+    return None
+
+
+def _extract_defined_names(tree: ast.Module) -> set[str]:
+    """Return all names defined or imported at the top level of a module.
+
+    Covers:
+    - Top-level ``def`` and ``class`` declarations
+    - Top-level simple assignments: ``Name = ...`` (catches re-assignments like
+      ``MyClass = _impl.MyClass``)
+    - ``import X`` → ``X``
+    - ``import X as Z`` → ``Z``
+    - ``from X import Y`` → ``Y``
+    - ``from X import Y as Z`` → ``Z``
+    """
+    defined: set[str] = set()
+    for node in tree.body:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)):
+            defined.add(node.name)
+        elif isinstance(node, ast.Assign):
+            for target in node.targets:
+                if isinstance(target, ast.Name):
+                    defined.add(target.id)
+        elif isinstance(node, ast.AnnAssign):
+            if isinstance(node.target, ast.Name):
+                defined.add(node.target.id)
+        elif isinstance(node, ast.Import):
+            for alias in node.names:
+                # ``import X.Y`` → top-level name is ``X``
+                # ``import X.Y as Z`` → name is ``Z``
+                name = alias.asname if alias.asname else alias.name.split(".")[0]
+                defined.add(name)
+        elif isinstance(node, ast.ImportFrom):
+            for alias in node.names:
+                name = alias.asname if alias.asname else alias.name
+                # Wildcard imports: skip (cannot statically determine what they add)
+                if name != "*":
+                    defined.add(name)
+    return defined
+
+
+def run_export_completeness_checks(ctx: PostExecGateContext):
+    """Detect symbols in ``__all__`` that are not defined or imported in the same file.
+
+    Catches the "class extracted to new file but re-export not added" pattern
+    where a developer moves a class/function to a new module and forgets to
+    add ``from <new_module> import <symbol>`` back to the original file.
+    """
+    findings = []
+
+    for raw_path in ctx.changed_files_reported:
+        normalized = normalize_path(raw_path)
+
+        # Skip non-Python files and vendor/libs directory
+        if not normalized.endswith(".py"):
+            continue
+        if "SYSTEM/libs/" in normalized or normalized.startswith("SYSTEM/libs"):
+            continue
+
+        abs_path = ctx.project_dir / normalized
+        if not abs_path.exists():
+            continue
+
+        try:
+            source = abs_path.read_text(encoding="utf-8", errors="replace")
+        except OSError as exc:
+            _log.debug("export_completeness: cannot read %s: %s", normalized, exc)
+            continue
+
+        # Fail-open: skip unparseable files without crashing
+        try:
+            tree = ast.parse(source, filename=normalized)
+        except Exception as exc:  # noqa: BLE001 — FX-V6-EC1 / intentional fail-open
+            _log.debug("export_completeness: cannot parse %s: %s", normalized, exc)
+            continue
+
+        all_names = _extract_all_names(tree)
+        if all_names is None:
+            # No __all__ in this file — nothing to check
+            continue
+
+        defined_names = _extract_defined_names(tree)
+        rel_path = normalized
+
+        for name in all_names:
+            if name in defined_names:
+                continue
+            findings.append(
+                build_finding(
+                    check_id="export_completeness.missing_symbol",
+                    category=GateCategory.CONTRACT,
+                    title=f"__all__ declares '{name}' but it is not defined or imported",
+                    severity=GateSeverity.HIGH,
+                    impact=GateImpact.BLOCK,
+                    summary=(
+                        f"Module {rel_path!r} has __all__ = [..., {name!r}, ...] but "
+                        f"'{name}' is neither defined nor imported in this file. "
+                        "Likely a class/function was extracted to a new module and "
+                        "the re-export was forgotten."
+                    ),
+                    recommendation=(
+                        f"Add 'from <new_module> import {name}' to {rel_path}, "
+                        f"or remove '{name}' from __all__"
+                    ),
+                    evidence=[
+                        EvidenceReference(
+                            kind="file",
+                            path=rel_path,
+                            detail=f"__all__ declares '{name}' but symbol absent",
+                        )
+                    ],
+                    repair_kind=RepairKind.FIX_CONTRACT.value,
+                    executor_action="Add missing re-export or remove from __all__",
+                    proof_required="ImportError resolved; __all__ consistent with module contents",
+                    allowlist_allowed=True,
+                )
+            )
+
+    return build_check_result(
+        check_id="export_completeness",
+        category=GateCategory.CONTRACT,
+        findings=findings,
+    )

vigil_forensic/gate_checks/fallback_checks.py

@@ -0,0 +1,41 @@
+from __future__ import annotations
+
+from vigil_forensic._shared import EvidenceReference, GateCategory, GateImpact, GateSeverity, RepairKind
+from vigil_forensic.gate_models import PostExecGateContext
+from .common import build_check_result, build_finding, iter_touched_snapshots
+import logging
+_log = logging.getLogger(__name__)
+
+
+def run_fallback_checks(ctx: PostExecGateContext):
+    findings = []
+    profile = ctx.repo_profile
+    if profile is None:
+        return build_check_result(check_id="fallback", category=GateCategory.FALLBACK)
+    for snapshot in iter_touched_snapshots(ctx):
+        if not snapshot.exists or profile.is_generated_or_vendored(snapshot.path):
+            continue
+        text_lower = snapshot.text.lower()
+        for pattern, impact in profile.forbidden_fallback_patterns.items():
+            if pattern.lower() not in text_lower:
+                continue
+            severity = GateSeverity.CRITICAL if impact is GateImpact.BLOCK else GateSeverity.MEDIUM
+            if profile.is_critical(snapshot.path) and impact is GateImpact.REVISE:
+                severity = GateSeverity.HIGH
+            findings.append(
+                build_finding(
+                    check_id="fallback.pattern",
+                    category=GateCategory.FALLBACK,
+                    title=f"Forbidden fallback or workaround marker in touched code: {pattern}",
+                    severity=severity,
+                    impact=impact,
+                    summary=f"Touched file {snapshot.path} contains '{pattern}', which is disallowed or suspicious in this repo profile.",
+                    recommendation="Remove the fallback/workaround or document and relocate it under an explicit owned policy path.",
+                    evidence=[EvidenceReference(kind="file", path=snapshot.path, detail=pattern)],
+                    repair_kind=RepairKind.REMOVE_FALLBACK.value,
+                    executor_action="Remove/narrow fallback pattern",
+                    proof_required="No fallback in file",
+                    allowlist_allowed=False,
+                )
+            )
+    return build_check_result(check_id="fallback", category=GateCategory.FALLBACK, findings=findings)

vigil_forensic/gate_checks/file_proliferation_checks.py

@@ -0,0 +1,171 @@
+from __future__ import annotations
+
+import os
+import re
+
+from vigil_forensic._shared import EvidenceReference, GateCategory, GateImpact, GateSeverity, RepairKind
+from vigil_forensic.gate_models import PostExecGateContext
+from ..source_analysis import get_generic_stems, is_source_file
+from .common import build_check_result, build_finding, normalize_path
+import logging
+_log = logging.getLogger(__name__)
+
+
+# Suffixes that suggest a "v2" clone rather than a proper edit.
+_CLONE_PATTERNS = re.compile(
+    r'_v\d+|_new|_copy|_backup|_old|_fixed|_updated|_refactored|_alt'
+    r'|\.bak|\.orig|\.copy',
+    re.IGNORECASE,
+)
+
+
+def run_file_proliferation_checks(ctx: PostExecGateContext):
+    """Detect new files that duplicate or shadow existing project files.
+
+    Catches three patterns:
+    1. Clone naming: executor creates foo_v2.py when foo.py exists
+    2. Generic helper proliferation: executor creates new utils.py / helpers.py
+       in a directory that already has one nearby
+    3. Shadow file: executor creates a file with the SAME basename in a
+       different directory when one already exists in the project
+    """
+    findings = []
+    if not ctx.changed_files_observed:
+        return build_check_result(check_id="file_proliferation", category=GateCategory.DUPLICATION)
+
+    # Build a set of pre-existing project file basenames for shadow detection.
+    # Only scan known source roots to keep it fast.
+    existing_basenames: dict[str, list[str]] = {}
+    for root_name in ctx.source_package_roots:
+        root = ctx.project_dir / root_name
+        if not root.is_dir():
+            continue
+        file_count = 0
+        for src_file in root.rglob("*"):
+            if not src_file.is_file():
+                continue
+            rel = str(src_file.relative_to(ctx.project_dir)).replace("\\", "/")
+            if not is_source_file(rel):
+                continue
+            file_count += 1
+            if file_count > 2000:
+                break
+            existing_basenames.setdefault(src_file.name, []).append(rel)
+
+    for raw_path in ctx.changed_files_observed:
+        normalized = normalize_path(raw_path)
+        if not is_source_file(normalized):
+            continue
+        # Only check NEW files (created by executor, not pre-existing edits)
+        if normalized not in set(normalize_path(p) for p in ctx.changed_files_reported):
+            continue
+
+        basename = os.path.basename(normalized)
+        stem = basename.rsplit(".", 1)[0] if "." in basename else basename
+
+        # Check 1: Clone naming (_v2, _new, _copy, etc.)
+        if _CLONE_PATTERNS.search(stem):
+            base_stem = _CLONE_PATTERNS.sub("", stem)
+            ext = basename.rsplit(".", 1)[1] if "." in basename else ""
+            base_name = f"{base_stem}.{ext}" if ext else base_stem
+            if base_name in existing_basenames:
+                base_paths = existing_basenames[base_name]
+                findings.append(
+                    build_finding(
+                        check_id="file_proliferation.clone_naming",
+                        category=GateCategory.DUPLICATION,
+                        title=f"Clone-named file created: {normalized}",
+                        severity=GateSeverity.HIGH,
+                        impact=GateImpact.REVISE,
+                        summary=(
+                            f"Executor created {normalized} which looks like a clone of "
+                            f"existing {base_paths[0]}. Edit the original file instead "
+                            "of creating a copy with a version suffix."
+                        ),
+                        recommendation=(
+                            f"Modify {base_paths[0]} directly. If a new module is truly "
+                            "needed, give it a distinct semantic name, not a version suffix."
+                        ),
+                        evidence=[
+                            EvidenceReference(kind="file", path=normalized, detail="clone"),
+                            EvidenceReference(kind="file", path=base_paths[0], detail="original"),
+                        ],
+                        repair_kind=RepairKind.EDIT_CANONICAL.value,
+                        executor_action=f"Delete {normalized}; apply changes to canonical {base_paths[0]} instead",
+                        proof_required="clone file deleted; canonical file contains the intended change",
+                        allowlist_allowed=False,
+                    )
+                )
+
+        # Check 2: Generic helper proliferation
+        stems_for_lang = get_generic_stems(normalized)
+        if stem.lower() in stems_for_lang:
+            dir_path = os.path.dirname(normalized)
+            siblings = [
+                path for bname, paths in existing_basenames.items()
+                for path in paths
+                if bname.rsplit(".", 1)[0].lower() in stems_for_lang
+                and os.path.dirname(path) == dir_path
+                and path != normalized
+            ]
+            if siblings:
+                findings.append(
+                    build_finding(
+                        check_id="file_proliferation.generic_helper",
+                        category=GateCategory.DUPLICATION,
+                        title=f"Generic helper file created alongside existing: {normalized}",
+                        severity=GateSeverity.MEDIUM,
+                        impact=GateImpact.REVISE,
+                        summary=(
+                            f"Executor created {normalized} but {siblings[0]} already "
+                            "exists in the same directory. Adding another generic helper "
+                            "file suggests logic should be added to the existing one."
+                        ),
+                        recommendation=f"Add the new functions to {siblings[0]} instead.",
+                        evidence=[
+                            EvidenceReference(kind="file", path=normalized, detail="new_generic"),
+                            EvidenceReference(kind="file", path=siblings[0], detail="existing_generic"),
+                        ],
+                        repair_kind=RepairKind.EDIT_CANONICAL.value,
+                        executor_action=f"Move content from {normalized} into {siblings[0]}; delete {normalized}",
+                        proof_required="new file deleted; functions accessible from existing helper",
+                    )
+                )
+
+        # Check 3: Shadow file (same basename, different directory)
+        if basename in existing_basenames:
+            other_locations = [
+                p for p in existing_basenames[basename]
+                if p != normalized and os.path.dirname(p) != os.path.dirname(normalized)
+            ]
+            if other_locations and not basename.startswith("__"):
+                findings.append(
+                    build_finding(
+                        check_id="file_proliferation.shadow_file",
+                        category=GateCategory.DUPLICATION,
+                        title=f"File with same name exists elsewhere: {basename}",
+                        severity=GateSeverity.MEDIUM,
+                        impact=GateImpact.REVISE,
+                        summary=(
+                            f"Executor created {normalized} but {other_locations[0]} "
+                            "already exists with the same filename in a different directory. "
+                            "This may cause import confusion or indicate a copy-paste."
+                        ),
+                        recommendation=(
+                            "Verify this is intentional. If both files serve the same purpose, "
+                            "consolidate into one and import from the canonical location."
+                        ),
+                        evidence=[
+                            EvidenceReference(kind="file", path=normalized, detail="new"),
+                            EvidenceReference(kind="file", path=other_locations[0], detail="existing"),
+                        ],
+                        repair_kind=RepairKind.EDIT_CANONICAL.value,
+                        executor_action=f"Verify {normalized} vs {other_locations[0]} — if same purpose, consolidate and import from canonical",
+                    )
+                )
+
+    return build_check_result(
+        check_id="file_proliferation",
+        category=GateCategory.DUPLICATION,
+        findings=findings,
+    )

vigil_forensic/gate_checks/fix_without_test_checks.py

@@ -0,0 +1,69 @@
+from __future__ import annotations
+
+from vigil_forensic._shared import SOURCE_EXTENSIONS as _SOURCE_EXTENSIONS
+from vigil_forensic._shared import EvidenceReference, GateCategory, GateImpact, GateSeverity
+from vigil_forensic.gate_models import PostExecGateContext
+from .common import build_check_result, build_finding, normalize_path
+import logging
+_log = logging.getLogger(__name__)
+
+_FIX_KEYWORDS = frozenset({"fix", "repair", "bug", "patch", "hotfix", "bugfix"})
+# Sprint C3 (2026-04-23): _SOURCE_EXTENSIONS imported above from
+# SYSTEM.shared_helpers.file_extensions. Keep the private alias so existing
+# call sites resolve without having to rewrite the suffix lookup.
+
+
+def _intent_has_fix_keyword(task_intent: str) -> bool:
+    """Check if task_intent contains a fix-related keyword as a word token."""
+    tokens = set(task_intent.lower().replace("-", "_").split("_"))
+    # Also split on spaces for natural language intents
+    for word in task_intent.lower().split():
+        tokens.update(word.replace("-", "_").split("_"))
+    return bool(tokens & _FIX_KEYWORDS)
+
+
+def run_fix_without_test_checks(ctx: PostExecGateContext):
+    findings = []
+    if ctx.task_intent == "metadata_only":
+        return build_check_result(check_id="fix_without_test", category=GateCategory.TESTING)
+    if not _intent_has_fix_keyword(ctx.task_intent):
+        return build_check_result(check_id="fix_without_test", category=GateCategory.TESTING)
+
+    has_source_changes = False
+    source_files = []
+    for raw_path in ctx.changed_files_observed:
+        normalized = normalize_path(raw_path)
+        suffix = "." + normalized.rsplit(".", 1)[-1] if "." in normalized else ""
+        if suffix.lower() in _SOURCE_EXTENSIONS:
+            has_source_changes = True
+            source_files.append(normalized)
+
+    if not has_source_changes:
+        return build_check_result(check_id="fix_without_test", category=GateCategory.TESTING)
+
+    if not ctx.tests_touched:
+        findings.append(
+            build_finding(
+                check_id="fix_without_test.no_tests",
+                category=GateCategory.TESTING,
+                title="Fix/repair task changed source files but no tests",
+                severity=GateSeverity.MEDIUM,
+                impact=GateImpact.REVISE,
+                summary=(
+                    f"Task intent '{ctx.task_intent}' indicates a fix/repair, and "
+                    f"{len(source_files)} source file(s) were changed, but no test files "
+                    "were touched. Consider adding a regression test."
+                ),
+                recommendation="Add a test that reproduces the bug and verifies the fix.",
+                evidence=[
+                    EvidenceReference(kind="file", path=source_files[0], detail="source_changed_no_test")
+                ],
+            
+                repair_kind='add_regression_test',
+                executor_action='Add tests for coverage',
+                proof_required='Tests added/passing',
+                allowlist_allowed=True,
+            )
+        )
+
+    return build_check_result(check_id="fix_without_test", category=GateCategory.TESTING, findings=findings)

vigil_forensic/gate_checks/forensic_cluster_runners/__init__.py

@@ -0,0 +1,9 @@
+"""forensic_cluster_runners -- package API.
+
+Public surface: run_forensic_cluster_checks
+Private symbols re-exported for test compatibility: _check_js_surface_coverage
+"""
+from .core import run_forensic_cluster_checks
+from .quality_checks import _check_js_surface_coverage
+
+__all__ = ["run_forensic_cluster_checks", "_check_js_surface_coverage"]

vigil_forensic/gate_checks/forensic_cluster_runners/_helpers.py

@@ -0,0 +1,71 @@
+"""Shared helpers for forensic cluster runner sub-modules."""
+from __future__ import annotations
+
+import logging
+from typing import List
+
+from ...gate_models import (
+    EvidenceReference,
+    GateCategory,
+    GateFinding,
+    GateImpact,
+    GateSeverity,
+    RepairKind,
+)
+from ..common import build_finding
+
+_log = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Global cap: each per-file scanner returns at most this many findings total
+# ---------------------------------------------------------------------------
+
+_MAX_FINDINGS_PER_CLUSTER = 30
+
+
+# ---------------------------------------------------------------------------
+# Internal helpers
+# ---------------------------------------------------------------------------
+
+
+def _safe_run(label: str, fn, findings: List[GateFinding], notes: List[str]) -> None:
+    """Run *fn*, extending *findings* with results; on error append error finding + note."""
+    try:
+        result = fn()
+        if isinstance(result, list):
+            if result:
+                findings.extend(result)
+            else:
+                notes.append(f"[forensic_clusters] {label}: not applicable")
+        elif result is not None:
+            # Fail-loud: unexpected return type is a runner bug, not a skip
+            _log.error("forensic_clusters: %s returned unexpected type %s", label, type(result).__name__)
+            findings.append(build_finding(
+                check_id=f"internal_failure.{label}",
+                category=GateCategory.CONTRACT,
+                title=f"[internal_failure] {label} — unexpected return type",
+                severity=GateSeverity.HIGH,
+                impact=GateImpact.REVISE,
+                summary=f"Cluster runner {label!r} returned {type(result).__name__} instead of list[GateFinding]",
+                recommendation="Fix the cluster runner to return list[GateFinding] or empty list.",
+                evidence=(EvidenceReference(kind="probe", detail=f"Unexpected return: {type(result)}", ok=False),),
+                repair_kind=RepairKind.INVESTIGATE_GATE_FAILURE.value,
+                executor_action=f"Fix return type in cluster runner {label!r}",
+            ))
+            notes.append(f"[forensic_clusters] {label} unexpected return type: {type(result).__name__}")
+    except Exception as exc:  # noqa: BLE001
+        _log.error("forensic_clusters: %s internal error: %s", label, exc, exc_info=True)
+        detail = f"Cluster runner {label!r} raised {type(exc).__name__}: {exc}"
+        findings.append(build_finding(
+            check_id=f"internal_failure.{label}",
+            category=GateCategory.CONTRACT,
+            title=f"[internal_failure] {label}",
+            severity=GateSeverity.HIGH,
+            impact=GateImpact.REVISE,
+            summary=detail,
+            recommendation="Fix the internal error in the forensic cluster runner.",
+            evidence=(EvidenceReference(kind="probe", detail=detail, ok=False),),
+            repair_kind=RepairKind.INVESTIGATE_GATE_FAILURE.value,
+            executor_action=f"Fix internal failure in cluster runner {label!r}",
+        ))
+        notes.append(f"[forensic_clusters] {label} internal error: {exc}")