vigil-codeintel 0.1.0__py3-none-any.whl

vigil_mapper/_file_count_guard.py

@@ -0,0 +1,129 @@
+"""Shared file-count guard (anti-hang on huge repos).
+
+Both the forensic auditor and the code-map builder do per-file work that scales
+with the number of source files (forensic averages ~0.4 s/file across its gate
+AST walks). On a real repo with thousands of files this turns into hours and
+effectively hangs the machine. A per-file *size* guard already exists but does
+nothing against thousands of *small* files — only a guard on the file COUNT can.
+
+This module is pure stdlib (no project imports) so it is safe to import from
+either package without circular-import risk. It lives in ``vigil_mapper``
+because the dependency arrow is forensic -> map (forensic may import map; map
+never imports forensic), so this is the one place both sides can share.
+
+Helpers
+-------
+summarize_top_subdirs(rel_paths, limit)
+    Group relative paths by their top-level directory component and return the
+    ``limit`` biggest as ``[{"dir": str, "files": int}, ...]`` (descending).
+    Files directly under the project root are grouped under ``"."``.
+build_too_many_files_meta(rel_paths, max_files, *, entry_call=...)
+    Build the structured ``too_many_files`` meta dict returned by both tools
+    when ``len(rel_paths) > max_files``.
+
+Default ceiling
+---------------
+``DEFAULT_MAX_FILES = 800``. Forensic averages ~0.4 s/file, so ~800 files is a
+~5-minute ceiling — a sane upper bound for an interactive tool. Callers can pass
+a larger ``max_files`` to force a full scan.
+"""
+from __future__ import annotations
+
+from collections import Counter
+
+__all__ = [
+    "DEFAULT_MAX_FILES",
+    "summarize_top_subdirs",
+    "build_too_many_files_meta",
+]
+
+# Forensic averages ~0.4 s/file -> ~800 files is a ~5 min ceiling.
+DEFAULT_MAX_FILES = 800
+
+# How many top sub-directories to report in the skip result.
+_TOP_SUBDIRS = 8
+
+
+def _top_component(rel_path: str) -> str:
+    """Return the first path component of a posix-ish relative path.
+
+    Files directly under the project root (no separator) are grouped under
+    ``"."`` so the caller always gets a stable bucket name. Leading ``"./"`` is
+    stripped, but a leading-dot directory name (e.g. ``.claude``) is preserved.
+    """
+    norm = rel_path.replace("\\", "/")
+    while norm.startswith("./"):
+        norm = norm[2:]
+    norm = norm.lstrip("/")
+    if not norm:
+        return "."
+    head, sep, _tail = norm.partition("/")
+    if not sep:
+        return "."
+    return head
+
+
+def summarize_top_subdirs(
+    rel_paths: list[str] | tuple[str, ...],
+    limit: int = _TOP_SUBDIRS,
+) -> list[dict[str, int]]:
+    """Group *rel_paths* by top-level dir; return the *limit* biggest buckets.
+
+    Args:
+        rel_paths: Relative source-file paths (``"/"`` or ``"\\"`` separated).
+        limit: Max number of buckets to return.
+
+    Returns:
+        ``[{"dir": str, "files": int}, ...]`` sorted by ``files`` descending,
+        ties broken by directory name for determinism.
+    """
+    counter: Counter[str] = Counter(_top_component(p) for p in rel_paths)
+    # Sort by count desc, then dir name asc (deterministic).
+    ordered = sorted(counter.items(), key=lambda kv: (-kv[1], kv[0]))
+    return [{"dir": d, "files": n} for d, n in ordered[:limit]]
+
+
+def build_too_many_files_meta(
+    rel_paths: list[str] | tuple[str, ...],
+    max_files: int,
+    *,
+    entry_call: str = "start_forensic_audit",
+) -> dict:
+    """Build the structured ``too_many_files`` meta payload.
+
+    Args:
+        rel_paths: The collected relative source-file paths (the over-limit set).
+        max_files: The ceiling that was exceeded.
+        entry_call: Name of the MCP entry the suggestion should reference, e.g.
+            ``"start_forensic_audit"`` or ``"start_code_map"``.
+
+    Returns:
+        A dict with ``skipped_reason``, ``file_count``, ``max_files``,
+        ``top_subdirs`` and a human ``suggestion`` naming the biggest subdir.
+    """
+    top_subdirs = summarize_top_subdirs(rel_paths)
+    # Pick the biggest *named* subdir (skip the root "." bucket) for the example.
+    example_dir = None
+    for entry in top_subdirs:
+        if entry["dir"] != ".":
+            example_dir = entry["dir"]
+            break
+
+    if example_dir is not None:
+        suggestion = (
+            f"Scan a submodule, e.g. {entry_call}(path='<dir>/{example_dir}'), "
+            f"or raise max_files to force a full scan."
+        )
+    else:
+        suggestion = (
+            f"Scan a submodule, e.g. {entry_call}(path='<dir>/<subdir>'), "
+            f"or raise max_files to force a full scan."
+        )
+
+    return {
+        "skipped_reason": "too_many_files",
+        "file_count": len(rel_paths),
+        "max_files": max_files,
+        "top_subdirs": top_subdirs,
+        "suggestion": suggestion,
+    }

vigil_mapper/_git_utils.py

@@ -0,0 +1,178 @@
+"""Neutral shared git helpers. Depends only on stdlib.
+
+Used by map_builder (churn) and gate_checks (diff-based checks).
+Never imports from gate_checks or map_builder (correct dependency direction).
+
+Public API:
+    git_show(path, ref, project_dir)        -- file content at git ref
+    git_log_numstat(project_dir, since)     -- churn line counts per file
+    git_has_repo(project_dir)               -- is inside a git work tree?
+    git_head_sha(project_dir)               -- current HEAD SHA
+"""
+from __future__ import annotations
+
+import logging
+import subprocess
+from pathlib import Path
+
+_log = logging.getLogger(__name__)
+
+__all__ = [
+    "git_show",
+    "git_log_numstat",
+    "git_has_repo",
+    "git_head_sha",
+]
+
+
+def git_show(
+    path: str,
+    ref: str = "HEAD~1",
+    project_dir: Path | None = None,
+) -> str | None:
+    """Return file content at git ref or None on failure.
+
+    Args:
+        path: Relative file path (as stored in git, e.g. "BRAIN/foo.py").
+        ref: Git ref to read from. Defaults to "HEAD~1".
+        project_dir: If given, passes ``-C project_dir`` to git so the command
+            runs in the correct working directory regardless of the caller's cwd.
+
+    Returns:
+        File content as a string, or None if the file didn't exist at that ref,
+        git is unavailable, or any other error occurs (fail-open).
+    """
+    args = ["git"]
+    if project_dir is not None:
+        args += ["-C", str(project_dir)]
+    args += ["show", "%s:%s" % (ref, path)]
+
+    try:
+        r = subprocess.run(
+            args,
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=10,
+            shell=False,
+        )
+        if r.returncode != 0:
+            return None
+        return r.stdout
+    except (subprocess.SubprocessError, FileNotFoundError, OSError) as exc:
+        _log.debug("git_show failed for %s@%s: %s", path, ref, type(exc).__name__)
+        return None
+
+
+def git_log_numstat(
+    project_dir: Path,
+    since: str = "90.days",
+) -> dict[str, int]:
+    """Return ``{relative_path: churn_line_count}`` for commits since *since*.
+
+    Churn is defined as added + deleted lines across all commits in the window.
+    Binary files (where git outputs ``-`` for line counts) are skipped.
+
+    Args:
+        project_dir: Absolute path to the project root (must be inside a git repo).
+        since: ``--since`` value passed to ``git log``, e.g. ``"90.days"`` or
+            ``"2025-01-01"``.
+
+    Returns:
+        Dict mapping each file path to total churn line count. Returns an empty
+        dict if the directory is not a git repo, git is unavailable, or any
+        subprocess error occurs (fail-open).
+    """
+    try:
+        r = subprocess.run(
+            [
+                "git",
+                "-C", str(project_dir),
+                "log",
+                "--numstat",
+                "--since=%s" % since,
+                "--pretty=format:",
+            ],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=30,
+            shell=False,
+        )
+        if r.returncode != 0:
+            return {}
+        result: dict[str, int] = {}
+        for line in r.stdout.splitlines():
+            parts = line.split("\t")
+            if len(parts) != 3:
+                continue
+            added, deleted, path = parts
+            # Binary files have "-" for line counts — skip them
+            if added == "-" or deleted == "-":
+                continue
+            try:
+                churn = int(added) + int(deleted)
+            except ValueError:
+                continue
+            result[path] = result.get(path, 0) + churn
+        return result
+    except (subprocess.SubprocessError, FileNotFoundError, OSError) as exc:
+        _log.debug("git_log_numstat failed in %s: %s", project_dir, type(exc).__name__)
+        return {}
+
+
+def git_has_repo(project_dir: Path) -> bool:
+    """Return True if *project_dir* is inside a git work tree.
+
+    Uses ``git rev-parse --is-inside-work-tree``. Returns False on any error,
+    including git not installed or directory not being a repo (fail-open).
+    """
+    try:
+        r = subprocess.run(
+            [
+                "git",
+                "-C", str(project_dir),
+                "rev-parse",
+                "--is-inside-work-tree",
+            ],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=5,
+            shell=False,
+        )
+        return r.returncode == 0 and r.stdout.strip() == "true"
+    except (subprocess.SubprocessError, FileNotFoundError, OSError):
+        return False
+
+
+def git_head_sha(project_dir: Path) -> str | None:
+    """Return current HEAD SHA or None on non-git / error.
+
+    Returns:
+        40-character hex SHA string, or None if git is unavailable, the
+        directory is not a repo, or any other error occurs (fail-open).
+    """
+    try:
+        r = subprocess.run(
+            [
+                "git",
+                "-C", str(project_dir),
+                "rev-parse",
+                "HEAD",
+            ],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=5,
+            shell=False,
+        )
+        if r.returncode != 0:
+            return None
+        return r.stdout.strip() or None
+    except (subprocess.SubprocessError, FileNotFoundError, OSError):
+        return None