vigil-codeintel 0.1.0__py3-none-any.whl

vigil_forensic/language_profiles.py

@@ -0,0 +1,219 @@
+"""Per-language forensics metadata for autoforensics analysis.
+
+Provides frozen LanguageProfile dataclasses that carry forensics-relevant
+metadata (test patterns, generic stems, flow markers, etc.) for each supported
+language.  These profiles are NOT concerned with structural map-building —
+for that, see source_adapters.  Profiles complement source_adapters by
+covering the forensic/analytical layer.
+
+Public API:
+    LanguageProfile              -- frozen dataclass with per-language metadata
+    PYTHON_PROFILE               -- Python profile
+    JAVASCRIPT_PROFILE           -- JavaScript profile
+    TYPESCRIPT_PROFILE           -- TypeScript profile
+    GO_PROFILE                   -- Go profile
+    JAVA_PROFILE                 -- Java profile
+    get_profile_for_extension    -- lookup by file extension (e.g. ".py")
+    get_profile_for_lang         -- lookup by language_id (e.g. "python")
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import logging
+_log = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class LanguageProfile:
+    """Forensics metadata for a single programming language.
+
+    Attributes:
+        language_id:                    Canonical language identifier (e.g. "python").
+        source_extensions:              File extensions belonging to this language.
+        test_file_patterns:             Prefix/suffix patterns for test file detection.
+        generic_helper_stems:           Stems commonly used for utility/helper modules.
+        shared_layer_families:          Canonical shared-layer module name families.
+        flow_marker_patterns:           Regex patterns identifying orchestration steps.
+        comment_line_prefixes:          Comment start sequences (e.g. "#", "//").
+        function_extraction_supported:  True when AST-based extraction is available.
+        exclude_dir_hints:              Vendor/generated directories to skip during analysis.
+    """
+
+    language_id: str
+    source_extensions: frozenset[str]
+    test_file_patterns: tuple[str, ...]
+    generic_helper_stems: frozenset[str]
+    shared_layer_families: frozenset[str]
+    flow_marker_patterns: tuple[str, ...]
+    comment_line_prefixes: tuple[str, ...]
+    function_extraction_supported: bool
+    exclude_dir_hints: frozenset[str]
+
+
+# ---------------------------------------------------------------------------
+# Profiles
+# ---------------------------------------------------------------------------
+
+PYTHON_PROFILE = LanguageProfile(
+    language_id="python",
+    source_extensions=frozenset({".py"}),
+    test_file_patterns=("test_", "_test.py"),
+    generic_helper_stems=frozenset({
+        "utils", "helpers", "common", "shared", "misc",
+        "tools", "util", "helper", "support", "base",
+    }),
+    shared_layer_families=frozenset({
+        "shared", "utils", "common", "helpers", "base", "lib", "core",
+    }),
+    flow_marker_patterns=(
+        r"def build_",
+        r"def create_",
+        r"def run_",
+        r"def execute_",
+        r"subprocess",
+        r"json\.loads",
+        r"json\.dumps",
+    ),
+    comment_line_prefixes=("#",),
+    function_extraction_supported=True,
+    exclude_dir_hints=frozenset({
+        "__pycache__", ".venv", "venv", "node_modules", "libs",
+        ".git", "migrations", "__generated__", "dist", "build",
+    }),
+)
+
+JAVASCRIPT_PROFILE = LanguageProfile(
+    language_id="javascript",
+    source_extensions=frozenset({".js", ".mjs", ".cjs"}),
+    test_file_patterns=(".test.js", ".spec.js", "__tests__/"),
+    generic_helper_stems=frozenset({
+        "utils", "helpers", "common", "shared", "base",
+        "lib", "index", "constants",
+    }),
+    shared_layer_families=frozenset({
+        "shared", "utils", "common", "helpers", "base",
+        "lib", "core", "services",
+    }),
+    flow_marker_patterns=(
+        r"function build",
+        r"function create",
+        r"async function",
+        r"fetch\(",
+        r"JSON\.parse",
+        r"JSON\.stringify",
+    ),
+    comment_line_prefixes=("//", "/*"),
+    function_extraction_supported=False,
+    exclude_dir_hints=frozenset({
+        "node_modules", "dist", "build", ".cache",
+        "coverage", "__generated__",
+    }),
+)
+
+TYPESCRIPT_PROFILE = LanguageProfile(
+    language_id="typescript",
+    source_extensions=frozenset({".ts", ".tsx"}),
+    test_file_patterns=(".test.ts", ".spec.ts", "__tests__/"),
+    # Inherit generic_helper_stems, shared_layer_families, flow_marker_patterns,
+    # comment_line_prefixes, function_extraction_supported, exclude_dir_hints
+    # from JAVASCRIPT_PROFILE — TypeScript is a strict superset for forensics purposes.
+    generic_helper_stems=JAVASCRIPT_PROFILE.generic_helper_stems,
+    shared_layer_families=JAVASCRIPT_PROFILE.shared_layer_families,
+    flow_marker_patterns=JAVASCRIPT_PROFILE.flow_marker_patterns,
+    comment_line_prefixes=JAVASCRIPT_PROFILE.comment_line_prefixes,
+    function_extraction_supported=False,
+    exclude_dir_hints=JAVASCRIPT_PROFILE.exclude_dir_hints,
+)
+
+GO_PROFILE = LanguageProfile(
+    language_id="go",
+    source_extensions=frozenset({".go"}),
+    test_file_patterns=("_test.go",),
+    generic_helper_stems=frozenset({
+        "utils", "helpers", "common", "internal", "util",
+    }),
+    shared_layer_families=frozenset({
+        "internal", "common", "shared", "helpers", "util",
+    }),
+    flow_marker_patterns=(
+        r"func Build",
+        r"func Create",
+        r"func Run",
+        r"func Execute",
+    ),
+    comment_line_prefixes=("//",),
+    function_extraction_supported=False,
+    exclude_dir_hints=frozenset({
+        "vendor", "testdata", "node_modules",
+    }),
+)
+
+JAVA_PROFILE = LanguageProfile(
+    language_id="java",
+    source_extensions=frozenset({".java"}),
+    test_file_patterns=("Test.java", "Tests.java", "/test/"),
+    generic_helper_stems=frozenset({
+        "Utils", "Helper", "Common", "Shared", "Base",
+        "Util", "Helpers",
+    }),
+    shared_layer_families=frozenset({
+        "utils", "common", "shared", "base", "helper",
+    }),
+    flow_marker_patterns=(
+        r"void build",
+        r"void create",
+        r"void run",
+        r"void execute",
+        r"new ObjectMapper\(",
+        r"objectMapper\.",
+    ),
+    comment_line_prefixes=("//", "/*"),
+    function_extraction_supported=False,
+    exclude_dir_hints=frozenset({
+        "target", "build", ".gradle", "node_modules", "generated",
+    }),
+)
+
+# ---------------------------------------------------------------------------
+# Lookup indices
+# ---------------------------------------------------------------------------
+
+_PROFILES_BY_EXTENSION: dict[str, LanguageProfile] = {
+    ext: profile
+    for profile in [
+        PYTHON_PROFILE,
+        JAVASCRIPT_PROFILE,
+        TYPESCRIPT_PROFILE,
+        GO_PROFILE,
+        JAVA_PROFILE,
+    ]
+    for ext in profile.source_extensions
+}
+
+_PROFILES_BY_LANG: dict[str, LanguageProfile] = {
+    p.language_id: p
+    for p in [
+        PYTHON_PROFILE,
+        JAVASCRIPT_PROFILE,
+        TYPESCRIPT_PROFILE,
+        GO_PROFILE,
+        JAVA_PROFILE,
+    ]
+}
+
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def get_profile_for_extension(ext: str) -> LanguageProfile | None:
+    """Return the LanguageProfile for *ext* (e.g. ``".py"``), or None.
+
+    Lookup is case-insensitive: ``".PY"`` resolves to the same profile as ``".py"``.
+    """
+    return _PROFILES_BY_EXTENSION.get(ext.lower())
+
+
+def get_profile_for_lang(lang_id: str) -> LanguageProfile | None:
+    """Return the LanguageProfile for *lang_id* (e.g. ``"python"``), or None."""
+    return _PROFILES_BY_LANG.get(lang_id)

vigil_forensic/meta_findings.py

@@ -0,0 +1,207 @@
+"""Defensive meta-integrity findings collector for vigil_forensic.
+
+Adapted from the Vigil autoforensics meta_findings.
+All cluster gate_models imports rewritten to vigil_forensic._shared.
+"""
+from __future__ import annotations
+
+import logging
+import threading
+from collections import deque
+from typing import Any, Optional
+
+from vigil_forensic._shared import (
+    EvidenceReference,
+    GateCategory,
+    GateCheckResult,
+    GateFinding,
+    GateImpact,
+    GateSeverity,
+)
+
+_log = logging.getLogger(__name__)
+
+_pending: deque[GateFinding] = deque()
+_lock = threading.Lock()
+
+META_CHECK_SPECS: dict[str, dict[str, Any]] = {
+    "meta.profile_load_failed": {
+        "severity": GateSeverity.HIGH,
+        "impact": GateImpact.WARN,
+        "title": "Gate profile failed to load",
+        "recommendation": (
+            "Inspect the referenced profile/config file for JSON syntax errors or "
+            "missing keys. Gates were executed WITHOUT profile context and may "
+            "produce incomplete or misleading results."
+        ),
+    },
+    "meta.git_unavailable": {
+        "severity": GateSeverity.LOW,
+        "impact": GateImpact.WARN,
+        "title": "Git unavailable for --with-git audit",
+        "recommendation": (
+            "Install git and ensure the project directory is a git repository, "
+            "or rerun the audit without --with-git. Git-dependent gates were "
+            "skipped or produced incomplete findings."
+        ),
+    },
+    "meta.artifact_corrupted": {
+        "severity": GateSeverity.HIGH,
+        "impact": GateImpact.WARN,
+        "title": "Forensic artifact is corrupted (JSON decode failed)",
+        "recommendation": (
+            "The referenced .cortex artifact exists but could not be parsed. "
+            "Inspect, repair or delete and rerun."
+        ),
+    },
+    "meta.artifact_unreadable": {
+        "severity": GateSeverity.HIGH,
+        "impact": GateImpact.WARN,
+        "title": "Forensic artifact is unreadable (OS error)",
+        "recommendation": (
+            "The referenced .cortex artifact exists but could not be opened "
+            "due to a filesystem/permission error. Check file permissions and disk health."
+        ),
+    },
+    "meta.syntax_parse_error": {
+        "severity": GateSeverity.HIGH,
+        "impact": GateImpact.REVISE,
+        "title": "Python syntax error blocked gate from parsing file",
+        "recommendation": (
+            "Fix the Python syntax error in the referenced file so gates can parse and audit it."
+        ),
+    },
+    "meta.file_unreadable": {
+        "severity": GateSeverity.MEDIUM,
+        "impact": GateImpact.WARN,
+        "title": "Source file exists but is unreadable",
+        "recommendation": (
+            "Investigate the filesystem/permission error on the referenced path."
+        ),
+    },
+    "meta.allowlist_corrupted": {
+        "severity": GateSeverity.HIGH,
+        "impact": GateImpact.WARN,
+        "title": "False-positive allowlist JSON is corrupted",
+        "recommendation": (
+            "Repair or delete .prompt-engineer/forensic_gates/false_positive_allowlist.json."
+        ),
+    },
+    "context_health.empty_file_snapshots": {
+        "severity": GateSeverity.HIGH,
+        "impact": GateImpact.WARN,
+        "title": "Audit context has no file snapshots",
+        "recommendation": (
+            "Write-safety gates rely on ctx.file_snapshots. An empty snapshots map means "
+            "every such gate trivially PASSes."
+        ),
+    },
+    "context_health.git_state_unavailable": {
+        "severity": GateSeverity.MEDIUM,
+        "impact": GateImpact.WARN,
+        "title": "Audit context is missing git state",
+        "recommendation": (
+            "Diff / blame / authorship-sensitive gates will be inconclusive."
+        ),
+    },
+    "context_health.session_artifacts_missing": {
+        "severity": GateSeverity.MEDIUM,
+        "impact": GateImpact.WARN,
+        "title": "Session artifacts directory is missing",
+        "recommendation": (
+            "session_number was set but the expected .cortex/sessions/<N>/ directory "
+            "does not exist on disk."
+        ),
+    },
+    "context_health.touched_files_empty": {
+        "severity": GateSeverity.LOW,
+        "impact": GateImpact.WARN,
+        "title": "Audit context reports zero touched files",
+        "recommendation": (
+            "ctx.touched_files is empty outside static-scan mode."
+        ),
+    },
+}
+
+
+def emit_meta_finding(
+    check_id: str,
+    *,
+    path: str = "",
+    detail: str = "",
+    summary: Optional[str] = None,
+    severity: Optional[GateSeverity] = None,
+    impact: Optional[GateImpact] = None,
+) -> GateFinding:
+    spec = META_CHECK_SPECS.get(check_id)
+    if spec is None:
+        _log.warning("emit_meta_finding: unregistered check_id=%r — using HIGH/WARN defaults", check_id)
+        title = check_id
+        recommendation = "(unregistered meta finding — extend META_CHECK_SPECS)"
+        eff_severity = severity or GateSeverity.HIGH
+        eff_impact = impact or GateImpact.WARN
+    else:
+        title = spec["title"]
+        recommendation = spec["recommendation"]
+        eff_severity = severity or spec["severity"]
+        eff_impact = impact or spec["impact"]
+
+    if summary is None:
+        parts = [title]
+        if path:
+            parts.append(f"path={path}")
+        if detail:
+            parts.append(detail)
+        summary = " | ".join(parts)
+
+    evidence = (EvidenceReference(kind="meta_finding", path=path, detail=detail, ok=False),)
+
+    finding = GateFinding(
+        check_id=check_id,
+        category=GateCategory.META,
+        title=title,
+        severity=eff_severity,
+        impact=eff_impact,
+        summary=summary,
+        recommendation=recommendation,
+        evidence=evidence,
+        fingerprint=f"meta:{check_id}:{path}:{detail}"[:200],
+    )
+
+    with _lock:
+        _pending.append(finding)
+    _log.warning("[meta-finding] %s severity=%s path=%r detail=%r", check_id, eff_severity.value, path, detail)
+    return finding
+
+
+def drain_meta_findings() -> list[GateFinding]:
+    with _lock:
+        raw = list(_pending)
+        _pending.clear()
+    # Dedup by fingerprint: two gates emitting the same parse-error for the same
+    # (file, line) produce identical fingerprints — collapse to one finding.
+    seen: set[str] = set()
+    out: list[GateFinding] = []
+    for f in raw:
+        fp = getattr(f, "fingerprint", None) or ""
+        if fp and fp in seen:
+            continue
+        if fp:
+            seen.add(fp)
+        out.append(f)
+    return out
+
+
+def peek_meta_findings() -> list[GateFinding]:
+    with _lock:
+        return list(_pending)
+
+
+def reset_meta_findings() -> None:
+    with _lock:
+        _pending.clear()
+
+
+def meta_runner_stub(ctx: Any) -> GateCheckResult:
+    """No-op runner for meta.* gate registrations."""
+    return GateCheckResult(check_id="meta", category=GateCategory.META, findings=(), notes=())