graphite-code 0.3.0__py3-none-any.whl

graphite/hookshim.py

@@ -0,0 +1,86 @@
+"""Pure rendering of graphite's git-hook trampolines.
+
+Deliberately has NO filesystem or git side effects -- installation lives in
+`hookinstall`. Every Windows correctness rule below was taken from aramid's
+`src/aramid/hooks.py`, which had already paid for them; keeping rendering pure
+is what makes them cheaply testable.
+"""
+from __future__ import annotations
+
+from pathlib import Path
+
+MARKER_START = "# >>> graphite managed >>>"
+MARKER_END = "# <<< graphite managed <<<"
+
+# The events that change committed code. `post-checkout` is excluded on
+# purpose: branch switching is frequent and transient, and hooking it makes
+# `git bisect` expensive.
+TRIGGERS: tuple[str, ...] = ("post-commit", "post-merge", "post-rewrite")
+
+# The relocated original hook, invoked before graphite's own body. `.local`
+# rather than a graphite-specific suffix so a human reading `.githooks/` can
+# tell at a glance which file is theirs.
+CHAINED_SUFFIX = ".local"
+
+
+def sh_interpreter_path(interpreter: Path) -> str:
+    """`C:\\Python314\\python.exe` -> `/c/Python314/python.exe`.
+
+    Git-for-Windows' `sh` cannot exec a drive-letter path. A POSIX path is
+    returned unchanged.
+    """
+    resolved = interpreter.resolve()
+    drive = resolved.drive.rstrip(":").lower()
+    if not drive:
+        return resolved.as_posix()
+    rest = resolved.as_posix()[len(resolved.drive):].lstrip("/")
+    return f"/{drive}/{rest}"
+
+
+def render_trigger_shim(hook: str, interpreter: Path) -> bytes:
+    """The trampoline graphite installs for one of its triggers.
+
+    Three rules, each load-bearing:
+
+    * **`if`/`fi`, never `[ -f "$C" ] && { ...; }`.** As a script's *final*
+      command the latter exits 1 when `$C` is absent -- the test fails, `&&`
+      short-circuits, and that status becomes the script's -- so a trampoline
+      with nothing to chain to would block every commit on a fresh clone.
+      Measured, and independently reproduced by aramid's agent.
+    * **The chain-check is always emitted**, whether or not a `.local` exists.
+      Baking that state into the bytes is what breaks idempotent regeneration.
+    * **Never a bare `python`.** This machine exposes several interpreters to
+      hook `sh`, including the WindowsApps store stub, so the absolute path is
+      baked in with `py -3` as the only fallback.
+    * **`-P` on both arms, always** (graphite#43). `python -m X` puts the CWD at
+      `sys.path[0]` and git runs hooks from the top of the working tree, so a
+      `graphite.py` or `graphite/` at a managed repo's root otherwise wins over
+      the installed package. The redirect and `|| true` below make that hijack
+      invisible, and the module-shaped shadow *executes* on the way to its
+      `ModuleNotFoundError` -- so erroring out is not a mitigation. Both arms
+      need it independently; one flagless arm is the whole way in.
+
+    All three triggers are `post-*`, where git ignores the exit code, so the
+    chained hook's failure is swallowed with `|| true` and the shim ends with
+    an explicit `exit 0`: a graph refresh must never fail a developer's commit.
+    """
+    interp = sh_interpreter_path(interpreter)
+    lines = [
+        "#!/bin/sh",
+        MARKER_START,
+        'DIR=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd)',
+        f'CHAINED="$DIR/{hook}{CHAINED_SUFFIX}"',
+        'if [ -f "$CHAINED" ]; then',
+        '    "$CHAINED" "$@" || true',
+        "fi",
+        f'INTERP="{interp}"',
+        'if [ -x "$INTERP" ]; then',
+        '    "$INTERP" -P -m graphite.hook_entry >/dev/null 2>&1 || true',
+        "elif command -v py >/dev/null 2>&1; then",
+        "    py -3 -P -m graphite.hook_entry >/dev/null 2>&1 || true",
+        "fi",
+        MARKER_END,
+        "exit 0",
+        "",
+    ]
+    return "\n".join(lines).encode("utf-8")

graphite/incident_ledger.py

@@ -0,0 +1,247 @@
+"""Machine-local incident ledger: durable capture of graphite failures.
+
+Append-only JSONL, one file per repo (``.graphite/local/incidents.jsonl``,
+the usage-ledger idiom) plus one for the daemon's own state dir. Dedup is a
+READ-time concern: occurrences append freely and ``fold_incidents`` groups
+them by fingerprint. Triage is event-sourced: ``ack``/``resolve`` are
+appended entries, never mutations; a new occurrence strictly newer than a
+resolve reopens the incident. Recording is best-effort by contract — a
+ledger write failure must never break the operation being recorded.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+MAX_LEDGER_BYTES = 5 * 1024 * 1024
+MAX_SUBJECT_CHARS = 512
+MAX_DETAIL_CHARS = 2048
+MAX_LINE_BYTES = 8192
+# "doctor" covers deep-probe failures (#29). It is a class of its own rather
+# than folded into "build" because doctor incidents must not inflate build
+# failure counts -- daemon_health reads those, and a probe that could not reach
+# an MCP server says nothing about whether the graph builds.
+_CLASSES = frozenset({"build", "query", "daemon", "doctor"})
+_LIFECYCLE_KINDS = frozenset({"ack", "resolve"})
+_KINDS = frozenset({"occurrence"}) | _LIFECYCLE_KINDS
+_STATE_ORDER = {"open": 0, "acked": 1, "resolved": 2}
+
+
+def repo_ledger_dir(root: Path) -> Path:
+    from .usage_ledger import local_dir
+
+    return local_dir(root)
+
+
+def ledger_path(ledger_dir: Path) -> Path:
+    return ledger_dir / "incidents.jsonl"
+
+
+def rotated_ledger_path(ledger_dir: Path) -> Path:
+    return ledger_dir / "incidents.jsonl.1"
+
+
+def incident_fingerprint(klass: str, code: str, subject: str) -> str:
+    digest = hashlib.sha256(f"{klass}|{code}|{subject}".encode("utf-8")).hexdigest()
+    return digest[:16]
+
+
+def _now() -> str:
+    return datetime.now(timezone.utc).isoformat(timespec="seconds").replace("+00:00", "Z")
+
+
+def _append(ledger_dir: Path, entry: dict[str, Any]) -> None:
+    path = ledger_path(ledger_dir)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    if path.exists() and path.stat().st_size > MAX_LEDGER_BYTES:
+        os.replace(path, rotated_ledger_path(ledger_dir))
+    line = json.dumps(entry, ensure_ascii=False)
+    overshoot = len(line.encode("utf-8")) - MAX_LINE_BYTES
+    if overshoot > 0:
+        for key in ("detail", "note"):
+            if key in entry:
+                text = str(entry[key])
+                entry = {**entry, key: text[: max(0, len(text) - overshoot)]}
+                line = json.dumps(entry, ensure_ascii=False)
+                break
+    with open(path, "a", encoding="utf-8") as handle:
+        handle.write(line + "\n")
+
+
+def record_incident(ledger_dir: Path, *, klass: str, code: str, subject: str, detail: str) -> None:
+    """Append one occurrence; never raise."""
+    try:
+        if klass not in _CLASSES:
+            return
+        subject = str(subject)[:MAX_SUBJECT_CHARS]
+        _append(
+            ledger_dir,
+            {
+                "schema": 1,
+                "kind": "occurrence",
+                "fingerprint": incident_fingerprint(klass, str(code), subject),
+                "ts": _now(),
+                "class": klass,
+                "code": str(code),
+                "subject": subject,
+                "detail": str(detail)[:MAX_DETAIL_CHARS],
+            },
+        )
+    except Exception:
+        return
+
+
+def append_lifecycle(ledger_dir: Path, fingerprint: str, kind: str, note: str | None = None) -> bool:
+    """Append ack/resolve for a known fingerprint; False (no write) if unknown."""
+    if kind not in _LIFECYCLE_KINDS:
+        raise ValueError("kind must be 'ack' or 'resolve'")
+    entries, _skipped = read_incident_entries(ledger_dir)
+    known = any(e.get("kind") == "occurrence" and e.get("fingerprint") == fingerprint for e in entries)
+    if not known:
+        return False
+    entry: dict[str, Any] = {"schema": 1, "kind": kind, "fingerprint": fingerprint, "ts": _now()}
+    if note:
+        entry["note"] = str(note)[:MAX_DETAIL_CHARS]
+    _append(ledger_dir, entry)
+    return True
+
+
+def read_incident_entries(ledger_dir: Path) -> tuple[list[dict[str, Any]], int]:
+    """(entries, skipped): rotated generation first; corrupt lines counted; never raises.
+
+    Each generation file's read is individually guarded: if a file exists
+    but cannot be read or decoded (permissions, path is a directory, etc.),
+    that generation contributes >=1 to ``skipped`` and reading continues
+    with the next generation, instead of the whole read aborting and
+    silently presenting as "no incidents".
+    """
+    entries: list[dict[str, Any]] = []
+    skipped = 0
+    try:
+        for path in (rotated_ledger_path(ledger_dir), ledger_path(ledger_dir)):
+            try:
+                if not path.exists():
+                    continue
+                text = path.read_text(encoding="utf-8", errors="replace")
+            except Exception:
+                skipped += 1
+                continue
+            for line in text.splitlines():
+                if not line.strip():
+                    continue
+                if len(line.encode("utf-8", errors="replace")) > MAX_LINE_BYTES:
+                    skipped += 1
+                    continue
+                try:
+                    entry = json.loads(line)
+                except json.JSONDecodeError:
+                    skipped += 1
+                    continue
+                if (
+                    isinstance(entry, dict)
+                    and isinstance(entry.get("fingerprint"), str)
+                    and entry.get("kind") in _KINDS
+                ):
+                    entries.append(entry)
+                else:
+                    skipped += 1
+    except Exception:
+        return entries, skipped
+    return entries, skipped
+
+
+@dataclass(frozen=True)
+class IncidentView:
+    fingerprint: str
+    klass: str
+    code: str
+    subject: str
+    state: str
+    first_seen: str
+    last_seen: str
+    count: int
+    last_detail: str
+    last_note: str | None
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "fingerprint": self.fingerprint,
+            "class": self.klass,
+            "code": self.code,
+            "subject": self.subject,
+            "state": self.state,
+            "first_seen": self.first_seen,
+            "last_seen": self.last_seen,
+            "count": self.count,
+            "last_detail": self.last_detail,
+            "last_note": self.last_note,
+        }
+
+
+def fold_incidents(entries: list[dict[str, Any]]) -> list[IncidentView]:
+    """Group chronologically-ordered entries into per-fingerprint views."""
+    slots: dict[str, dict[str, Any]] = {}
+    for e in entries:
+        fp = str(e["fingerprint"])
+        slot = slots.setdefault(
+            fp,
+            {
+                "first": None,
+                "last": "",
+                "count": 0,
+                "klass": "",
+                "code": "",
+                "subject": "",
+                "detail": "",
+                "life": None,
+                "life_ts": "",
+                "note": None,
+            },
+        )
+        ts = str(e.get("ts", ""))
+        if e.get("kind") == "occurrence":
+            slot["count"] += 1
+            slot["klass"] = str(e.get("class", ""))
+            slot["code"] = str(e.get("code", ""))
+            slot["subject"] = str(e.get("subject", ""))
+            slot["detail"] = str(e.get("detail", ""))
+            if slot["first"] is None:
+                slot["first"] = ts
+            slot["last"] = ts
+        else:
+            slot["life"] = e["kind"]
+            slot["life_ts"] = ts
+            if e.get("note") is not None:
+                slot["note"] = str(e["note"])
+    views: list[IncidentView] = []
+    for fp, s in slots.items():
+        if s["count"] == 0:
+            continue
+        if s["life"] is None:
+            state = "open"
+        elif s["life"] == "resolve":
+            state = "open" if s["last"] > s["life_ts"] else "resolved"
+        else:
+            state = "acked"
+        views.append(
+            IncidentView(
+                fingerprint=fp,
+                klass=s["klass"],
+                code=s["code"],
+                subject=s["subject"],
+                state=state,
+                first_seen=s["first"] or "",
+                last_seen=s["last"],
+                count=s["count"],
+                last_detail=s["detail"],
+                last_note=s["note"],
+            )
+        )
+    views.sort(key=lambda v: v.last_seen, reverse=True)
+    views.sort(key=lambda v: _STATE_ORDER[v.state])
+    return views

graphite/ingest.py

@@ -0,0 +1,279 @@
+"""Repository ingestion: discover, classify, and hash files safely."""
+from __future__ import annotations
+
+import os
+from itertools import islice
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath
+from typing import Callable, Iterable
+
+from .cache import file_hash
+from .config import Config
+from .git import GitError, GitRunner
+
+
+MAX_GIT_FILE_RECORDS = 100_000
+
+
+class IngestError(RuntimeError):
+    """Raised when repository files cannot be enumerated safely."""
+
+
+@dataclass(frozen=True)
+class FileEntry:
+    rel_path: str  # posix-style relative path
+    abs_path: Path
+    language: str | None
+    size: int
+    content_hash: str
+
+
+# Extension → language classification.
+LANGUAGE_BY_EXT: dict[str, str] = {
+    ".ts": "typescript",
+    ".tsx": "tsx",
+    ".js": "javascript",
+    ".jsx": "jsx",
+    ".mjs": "javascript",
+    ".cjs": "javascript",
+    ".py": "python",
+    ".go": "go",
+    ".rs": "rust",
+    ".json": "json",
+    ".md": "markdown",
+    ".mdx": "markdown",
+    ".yml": "yaml",
+    ".yaml": "yaml",
+    ".css": "css",
+    ".scss": "scss",
+    ".html": "html",
+    ".sql": "sql",
+}
+
+# Directories and file patterns to skip entirely.
+SKIP_DIRS: frozenset[str] = frozenset({
+    "node_modules", ".git", ".next", ".wrangler", ".open-next", "dist", "build",
+    "out", "coverage", ".cache", ".claude", ".pytest_cache", ".mypy_cache", ".ruff_cache", "__pycache__", "graph-out", "graphify-out", "tools", "vendor", ".venv", "venv",
+    "target",  # Rust/Maven build output
+})
+
+SKIP_SUFFIXES: frozenset[str] = frozenset({
+    ".lock", ".log", ".min.js", ".min.css", ".map", ".svg", ".png", ".jpg",
+    ".jpeg", ".gif", ".ico", ".woff", ".woff2", ".ttf", ".eot", ".mp4",
+    ".webm", ".ogg", ".mp3", ".wav", ".pdf", ".zip", ".tar", ".gz",
+})
+
+# Binary file detection threshold: if a chunk contains this ratio of null bytes, treat as binary.
+_BINARY_NULL_RATIO = 0.001
+
+
+def _is_binary(path: Path) -> bool:
+    try:
+        with open(path, "rb") as f:
+            chunk = f.read(8192)
+    except OSError:
+        return True
+    if not chunk:
+        return False
+    if b"\x00" in chunk:
+        return True
+    return chunk.count(b"\x00") / len(chunk) > _BINARY_NULL_RATIO
+
+
+def _classify_language(rel_path: str) -> str | None:
+    lower = rel_path.lower()
+    # package.json is json, tsconfig.json is json, etc.
+    ext = Path(lower).suffix
+    if ext in LANGUAGE_BY_EXT:
+        return LANGUAGE_BY_EXT[ext]
+    # Shebang detection for extensionless scripts.
+    if ext == "":
+        return None
+    return None
+
+
+def _has_component_prefix(parts: tuple[str, ...], prefix: tuple[str, ...]) -> bool:
+    if len(parts) < len(prefix):
+        return False
+    return all(
+        os.path.normcase(part) == os.path.normcase(expected)
+        for part, expected in zip(parts, prefix)
+    )
+
+
+def _dynamic_exclusions(root: Path, cfg: Config) -> tuple[tuple[str, ...], ...]:
+    exclusions: set[tuple[str, ...]] = set()
+    for configured in (cfg.output_dir, cfg.cache_dir):
+        try:
+            relative = configured.resolve().relative_to(root)
+        except (OSError, ValueError):
+            continue
+        if relative != Path("."):
+            exclusions.add(relative.parts)
+    return tuple(sorted(exclusions))
+
+
+def _should_skip(
+    rel_path: str,
+    cfg: Config,
+    dynamic_exclusions: tuple[tuple[str, ...], ...] = (),
+) -> bool:
+    parts = Path(rel_path).parts
+    if any(part in SKIP_DIRS for part in parts):
+        return True
+    if any(_has_component_prefix(parts, prefix) for prefix in dynamic_exclusions):
+        return True
+    lower = rel_path.lower()
+    if any(lower.endswith(s) for s in SKIP_SUFFIXES):
+        return True
+    if not cfg.include_dotfiles:
+        if any(part.startswith(".") for part in parts):
+            return True
+    return False
+
+
+def _resolve_contained_path(root: Path, candidate: Path) -> Path | None:
+    """Resolve *candidate* and return it only when strictly below *root*."""
+    try:
+        resolved = candidate.resolve()
+        relative = resolved.relative_to(root)
+    except (OSError, ValueError):
+        return None
+    if relative == Path("."):
+        return None
+    return resolved
+
+
+def _normalize_git_path(root: Path, value: str) -> str | None:
+    posix_path = PurePosixPath(value)
+    if not value or value == "." or posix_path.is_absolute() or ".." in posix_path.parts:
+        return None
+    native_path = Path(value)
+    if native_path.is_absolute():
+        return None
+    resolved = _resolve_contained_path(root, root / native_path)
+    if resolved is None:
+        return None
+    return native_path.as_posix()
+
+
+def _git_ls_files(
+    root: Path,
+    *,
+    max_files: int | None = None,
+    is_eligible: Callable[[str], bool] | None = None,
+) -> list[str] | None:
+    """Return bounded Git files, or None only when *root* is not a Git repository."""
+    git_dir = root / ".git"
+    if not os.path.lexists(git_dir):
+        if any(os.path.lexists(ancestor / ".git") for ancestor in root.parents):
+            raise IngestError("nested Git roots are unsupported")
+        return None
+    try:
+        result = GitRunner(root).run(
+            ["ls-files", "-z", "--cached", "--others", "--exclude-standard"],
+            timeout_seconds=30,
+        )
+    except GitError as exc:
+        raise IngestError("unable to enumerate Git repository safely") from exc
+    if result.returncode != 0:
+        raise IngestError("unable to enumerate Git repository safely")
+    try:
+        output = result.stdout.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise IngestError("unable to enumerate Git repository safely") from exc
+    if not output:
+        return []
+    if not output.endswith("\x00"):
+        raise IngestError("unable to enumerate Git repository safely")
+
+    selected: list[str] = []
+    start = 0
+    record_count = 0
+    while start < len(output) and (
+        max_files is None or len(selected) < max_files
+    ):
+        end = output.find("\x00", start)
+        if end < 0:
+            raise IngestError("unable to enumerate Git repository safely")
+        record_count += 1
+        if record_count > MAX_GIT_FILE_RECORDS:
+            raise IngestError("unable to enumerate Git repository safely")
+        normalized = _normalize_git_path(root, output[start:end])
+        if normalized is None:
+            raise IngestError("unable to enumerate Git repository safely")
+        if is_eligible is None or is_eligible(normalized):
+            selected.append(normalized)
+        start = end + 1
+    return selected
+
+
+def _walk_files(
+    root: Path,
+    cfg: Config,
+    dynamic_exclusions: tuple[tuple[str, ...], ...],
+) -> Iterable[str]:
+    """Fallback filesystem walk respecting SKIP_DIRS."""
+    for dirpath, dirnames, filenames in os.walk(root):
+        # Prune skip dirs in-place.
+        current_parts = Path(dirpath).relative_to(root).parts
+        dirnames[:] = [
+            name
+            for name in dirnames
+            if name not in SKIP_DIRS
+            and not any(
+                _has_component_prefix((*current_parts, name), prefix)
+                for prefix in dynamic_exclusions
+            )
+        ]
+        for filename in filenames:
+            full = Path(dirpath) / filename
+            rel = full.relative_to(root).as_posix()
+            if _should_skip(rel, cfg, dynamic_exclusions):
+                continue
+            yield rel
+
+
+def collect_files(root: Path, cfg: Config) -> list[FileEntry]:
+    """Collect files under root, bounded by cfg.max_files as an ingestion cap."""
+    root = root.resolve()
+    dynamic_exclusions = _dynamic_exclusions(root, cfg)
+    tracked = _git_ls_files(
+        root,
+        max_files=cfg.max_files,
+        is_eligible=lambda path: not _should_skip(path, cfg, dynamic_exclusions),
+    )
+    if tracked is not None:
+        rel_paths = tracked
+    else:
+        walked = _walk_files(root, cfg, dynamic_exclusions)
+        rel_paths = list(
+            islice(walked, cfg.max_files)
+            if cfg.max_files is not None
+            else walked
+        )
+
+    entries: list[FileEntry] = []
+    for rel in rel_paths:
+        abs_path = _resolve_contained_path(root, root / Path(rel))
+        if abs_path is None:
+            continue
+        try:
+            size = abs_path.stat().st_size
+        except OSError:
+            continue
+        if size > cfg.max_file_size:
+            continue
+        if _is_binary(abs_path):
+            continue
+        entries.append(
+            FileEntry(
+                rel_path=rel,
+                abs_path=abs_path,
+                language=_classify_language(rel),
+                size=size,
+                content_hash=file_hash(abs_path),
+            )
+        )
+
+    return sorted(entries, key=lambda e: e.rel_path)