graphite-code 0.3.0__py3-none-any.whl

graphite/graph_io.py

@@ -0,0 +1,188 @@
+"""Bounded, validated reads for untrusted Graphite graph artifacts."""
+from __future__ import annotations
+
+import json
+import os
+import stat
+from pathlib import Path
+from typing import Any, Final
+
+from .graph import graph_from_json
+from .validation import validate_graph_bundle
+
+MAX_GRAPH_BYTES: Final = 128 * 1024 * 1024
+_REPARSE_POINT = getattr(stat, "FILE_ATTRIBUTE_REPARSE_POINT", 0x400)
+_ERROR_CODES = frozenset(
+    {
+        "graph_root_invalid",
+        "graph_outside_root",
+        "graph_missing",
+        "graph_reparse",
+        "graph_not_regular",
+        "graph_too_large",
+        "graph_changed",
+        "graph_unreadable",
+        "graph_invalid_utf8",
+        "graph_invalid_json",
+        "graph_invalid",
+    }
+)
+
+
+class GraphReadError(RuntimeError):
+    """A stable, path-free graph-read failure."""
+
+    def __init__(self, code: str) -> None:
+        if code not in _ERROR_CODES:
+            code = "graph_unreadable"
+        self.code = code
+        super().__init__(code)
+
+
+def _is_reparse_point(metadata: os.stat_result) -> bool:
+    return bool(getattr(metadata, "st_file_attributes", 0) & _REPARSE_POINT)
+
+
+def _stable_signature(metadata: os.stat_result) -> tuple[int, int, int, int]:
+    return (
+        int(metadata.st_dev),
+        int(metadata.st_ino),
+        int(metadata.st_size),
+        int(metadata.st_mtime_ns),
+    )
+
+
+def _resolve_root(root: Path) -> Path:
+    try:
+        metadata = root.lstat()
+    except OSError as exc:
+        raise GraphReadError("graph_root_invalid") from exc
+    if stat.S_ISLNK(metadata.st_mode) or _is_reparse_point(metadata):
+        raise GraphReadError("graph_root_invalid")
+    if not stat.S_ISDIR(metadata.st_mode):
+        raise GraphReadError("graph_root_invalid")
+    try:
+        return root.resolve(strict=True)
+    except OSError as exc:
+        raise GraphReadError("graph_root_invalid") from exc
+
+
+def _resolve_candidate(path: Path, root: Path) -> Path:
+    candidate = path if path.is_absolute() else root / path
+    try:
+        lexical_relative = candidate.absolute().relative_to(root)
+    except ValueError as exc:
+        raise GraphReadError("graph_outside_root") from exc
+    if ".." in lexical_relative.parts:
+        raise GraphReadError("graph_outside_root")
+    current = root
+    for part in lexical_relative.parts[:-1]:
+        current /= part
+        try:
+            parent_metadata = current.lstat()
+        except FileNotFoundError as exc:
+            raise GraphReadError("graph_missing") from exc
+        except OSError as exc:
+            raise GraphReadError("graph_unreadable") from exc
+        if stat.S_ISLNK(parent_metadata.st_mode) or _is_reparse_point(parent_metadata):
+            raise GraphReadError("graph_reparse")
+    try:
+        lexical_metadata = candidate.lstat()
+    except FileNotFoundError as exc:
+        raise GraphReadError("graph_missing") from exc
+    except OSError as exc:
+        raise GraphReadError("graph_unreadable") from exc
+    if stat.S_ISLNK(lexical_metadata.st_mode) or _is_reparse_point(lexical_metadata):
+        raise GraphReadError("graph_reparse")
+    try:
+        resolved = candidate.resolve(strict=True)
+        resolved.relative_to(root)
+    except ValueError as exc:
+        raise GraphReadError("graph_outside_root") from exc
+    except FileNotFoundError as exc:
+        raise GraphReadError("graph_missing") from exc
+    except OSError as exc:
+        raise GraphReadError("graph_unreadable") from exc
+    return resolved
+
+
+def _read_stable_bytes(path: Path, *, max_bytes: int) -> bytes:
+    try:
+        before = path.lstat()
+    except FileNotFoundError as exc:
+        raise GraphReadError("graph_missing") from exc
+    except OSError as exc:
+        raise GraphReadError("graph_unreadable") from exc
+    if stat.S_ISLNK(before.st_mode) or _is_reparse_point(before):
+        raise GraphReadError("graph_reparse")
+    if not stat.S_ISREG(before.st_mode):
+        raise GraphReadError("graph_not_regular")
+    if before.st_size > max_bytes:
+        raise GraphReadError("graph_too_large")
+
+    flags = os.O_RDONLY | getattr(os, "O_BINARY", 0)
+    try:
+        descriptor = os.open(path, flags)
+        try:
+            opened = os.fstat(descriptor)
+            if _stable_signature(opened) != _stable_signature(before):
+                raise GraphReadError("graph_changed")
+            chunks: list[bytes] = []
+            remaining = max_bytes + 1
+            while remaining > 0:
+                chunk = os.read(descriptor, min(64 * 1024, remaining))
+                if not chunk:
+                    break
+                chunks.append(chunk)
+                remaining -= len(chunk)
+            after = os.fstat(descriptor)
+        finally:
+            os.close(descriptor)
+    except GraphReadError:
+        raise
+    except FileNotFoundError as exc:
+        raise GraphReadError("graph_missing") from exc
+    except OSError as exc:
+        raise GraphReadError("graph_unreadable") from exc
+
+    data = b"".join(chunks)
+    if len(data) > max_bytes:
+        raise GraphReadError("graph_too_large")
+    if _stable_signature(after) != _stable_signature(opened):
+        raise GraphReadError("graph_changed")
+    return data
+
+
+def load_validated_graph_bundle(
+    path: Path,
+    *,
+    root: Path,
+    max_bytes: int = MAX_GRAPH_BYTES,
+) -> tuple[dict[str, Any], Any]:
+    """Read, validate, and construct a graph inside the selected root."""
+    if isinstance(max_bytes, bool) or max_bytes <= 0 or max_bytes > MAX_GRAPH_BYTES:
+        raise GraphReadError("graph_too_large")
+    selected_root = _resolve_root(root)
+    graph_path = _resolve_candidate(path, selected_root)
+    raw = _read_stable_bytes(graph_path, max_bytes=max_bytes)
+    try:
+        text = raw.decode("utf-8")
+    except UnicodeDecodeError as exc:
+        raise GraphReadError("graph_invalid_utf8") from exc
+    try:
+        bundle = json.loads(text)
+    except (json.JSONDecodeError, RecursionError) as exc:
+        raise GraphReadError("graph_invalid_json") from exc
+    if not isinstance(bundle, dict):
+        raise GraphReadError("graph_invalid")
+    try:
+        report = validate_graph_bundle(bundle)
+    except (AttributeError, KeyError, RecursionError, TypeError, ValueError) as exc:
+        raise GraphReadError("graph_invalid") from exc
+    if not report.get("ok"):
+        raise GraphReadError("graph_invalid")
+    try:
+        graph = graph_from_json(bundle)
+    except (AttributeError, KeyError, RecursionError, TypeError, ValueError) as exc:
+        raise GraphReadError("graph_invalid") from exc
+    return bundle, graph

graphite/health.py

@@ -0,0 +1,147 @@
+"""Resolution-health ("trust") signal computed from the canonical graph.
+
+Pure arithmetic over the loaded graph — no inference, no I/O in
+resolution_health itself. persisted_resolution is the fail-open reader for
+consumers that must not pay a full graph load (check, strict hook).
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path, PurePosixPath
+from typing import Any, Callable, Final
+
+import networkx as nx
+
+from .graph import edge_relations
+
+RESOLUTION_HEALTHY_RATIO: Final = 0.8
+
+_COUNTED_RELATIONS: Final = ("calls", "imports")
+
+# Per-relation marker for "this edge leaves the repo". An edge counts as
+# external ONLY when it also failed to bind -- externality excuses an unbound
+# edge, it never removes a bound one (spec §5).
+_EXTERNAL_CONFIDENCE: Final = {
+    "imports": "EXTERNAL_IMPORT",
+    "calls": "EXTERNAL_CALL",
+}
+
+_EXTENSION_LANGUAGES: Final = {
+    ".py": "python",
+    ".ts": "typescript",
+    ".tsx": "typescript",
+    ".mts": "typescript",
+    ".cts": "typescript",
+    ".js": "javascript",
+    ".jsx": "javascript",
+    ".mjs": "javascript",
+    ".cjs": "javascript",
+    ".go": "go",
+    ".rs": "rust",
+}
+
+_MAX_ANALYSIS_BYTES: Final = 64 * 1024 * 1024
+
+
+def _edge_language(source_file: object) -> str:
+    if not isinstance(source_file, str) or not source_file:
+        return "other"
+    suffix = PurePosixPath(source_file).suffix.lower()
+    return _EXTENSION_LANGUAGES.get(suffix, "other")
+
+
+def _cell(bound: int, total: int, external: int) -> dict[str, Any]:
+    return {
+        "total": total,
+        "bound": bound,
+        "ratio": None if total == 0 else round(bound / total, 3),
+        "external": external,
+    }
+
+
+def resolution_health(g: nx.DiGraph) -> dict[str, Any]:
+    """Measured resolver health: bound-edge ratios per relation and language."""
+    node_total = g.number_of_nodes()
+    unknown_nodes = sum(
+        1 for _n, data in g.nodes(data=True) if data.get("kind", "unknown") == "unknown"
+    )
+    relation_counts = {rel: [0, 0, 0] for rel in _COUNTED_RELATIONS}  # [bound, total, external]
+    language_counts: dict[str, dict[str, list[int]]] = {}
+    for _u, v, data in g.edges(data=True):
+        # A merged edge carries every relation of its node pair; counting only
+        # `relation` would drop a measured relation that collided with an
+        # earlier-sorting one (#1).
+        for relation in edge_relations(data):
+            counts = relation_counts.get(relation)
+            if counts is None:
+                continue
+            language = _edge_language(data.get("source_file"))
+            buckets = language_counts.setdefault(
+                language, {rel: [0, 0, 0] for rel in _COUNTED_RELATIONS}
+            )
+            bound = int(g.nodes[v].get("kind", "unknown") != "unknown")
+            if not bound and data.get("confidence") == _EXTERNAL_CONFIDENCE.get(relation):
+                counts[2] += 1
+                buckets[relation][2] += 1
+                continue
+            counts[0] += bound
+            counts[1] += 1
+            buckets[relation][0] += bound
+            buckets[relation][1] += 1
+    by_relation = {rel: _cell(c[0], c[1], c[2]) for rel, c in relation_counts.items()}
+    by_language = {
+        language: {rel: _cell(c[0], c[1], c[2]) for rel, c in buckets.items()}
+        for language, buckets in sorted(language_counts.items())
+    }
+    ratios = [cell["ratio"] for cell in by_relation.values() if cell["ratio"] is not None]
+    return {
+        "schema": 3,
+        "placeholder_nodes": {
+            "total": node_total,
+            "unknown": unknown_nodes,
+            "share": None if node_total == 0 else round(unknown_nodes / node_total, 3),
+        },
+        "by_relation": by_relation,
+        "by_language": by_language,
+        "healthy": all(ratio >= RESOLUTION_HEALTHY_RATIO for ratio in ratios),
+        "threshold": RESOLUTION_HEALTHY_RATIO,
+    }
+
+
+def ratio_percent(block: dict[str, Any], relation: str) -> str:
+    """Human rendering of one relation's bound ratio: '4.6%' or 'n/a'."""
+    try:
+        ratio = block["by_relation"][relation]["ratio"]
+    except (KeyError, TypeError):
+        return "n/a"
+    if not isinstance(ratio, (int, float)):
+        return "n/a"
+    return f"{ratio * 100:.1f}%"
+
+
+def persisted_resolution(
+    root: Path, on_error: Callable[[Exception], None] | None = None
+) -> dict[str, Any] | None:
+    """Fail-open read of the persisted block from graph-out/.graphite_analysis.json.
+
+    ``on_error`` fires only for MALFORMED content (ValueError/RecursionError) —
+    absence or unreadability is not malformation and stays silent.
+    """
+    path = root / "graph-out" / ".graphite_analysis.json"
+    try:
+        if not path.is_file() or path.stat().st_size > _MAX_ANALYSIS_BYTES:
+            return None
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except OSError:
+        return None
+    except (ValueError, RecursionError) as exc:
+        if on_error is not None:
+            try:
+                on_error(exc)
+            except Exception:
+                pass
+        return None
+    if not isinstance(data, dict):
+        return None
+    block = data.get("resolution_health")
+    return block if isinstance(block, dict) else None

graphite/hook_entry.py

@@ -0,0 +1,68 @@
+"""The fast path a git-hook trampoline execs.
+
+**This module MUST NOT import `graphite.cli`.** Measured on Windows, best of 3:
+
+    bare python                              79 ms
+    import graphite                          86 ms   (__init__ is nearly free)
+    import graphite.detach                  137 ms
+    import graphite.cli                    1281 ms
+
+A trampoline that reached the CLI would put ~1.2s on *every commit* purely to
+spawn a background build. The cost is specifically `cli.py`, not "importing
+graphite at all", which is what makes a Python hook entry viable in the first
+place. `tests/test_hook_entry.py` enforces this from a subprocess -- an
+in-process check would false-pass, since pytest imports the CLI elsewhere.
+
+Deliberately does NOT take the build lock. `cmd_build` already acquires it in
+the child; holding it here would mean the detached child finds the lock held by
+its own parent and exits with "build skipped", so no build would ever run.
+"""
+import sys
+from pathlib import Path
+
+from .detach import spawn_detached
+
+# The committed marker that means "this repo is onboarded to graphite". Chosen
+# over `.git` on purpose: the machine-wide `init.templateDir` shim runs in every
+# new clone on the machine, so the guard must be something a repo opts into.
+MARKER = "GRAPHITE.md"
+
+
+def find_repo_root(start: Path) -> Path | None:
+    """Nearest ancestor of `start` (inclusive) carrying the marker."""
+    for directory in (start, *start.parents):
+        if (directory / MARKER).exists():
+            return directory
+    return None
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Spawn a detached graph build for the repo containing `argv[0]`.
+
+    Always returns 0. Git ignores `post-*` exit codes anyway, but the shim also
+    ends with an explicit `exit 0`, and a graph refresh must never be able to
+    fail a developer's commit.
+    """
+    args = list(sys.argv[1:] if argv is None else argv)
+    start = Path(args[0]) if args else Path.cwd()
+    try:
+        start = start.resolve()
+    except OSError:
+        return 0
+
+    root = find_repo_root(start)
+    if root is None:
+        return 0  # not an onboarded repo -- fail open, silently
+
+    # The root is passed explicitly AND used as cwd. Both are load-bearing:
+    # `Config.output_dir` / `cache_dir` default to RELATIVE paths that
+    # `cmd_build` resolves against the process CWD, so a child launched from
+    # elsewhere would write the graph into the wrong directory.
+    spawn_detached(
+        [sys.executable, "-B", "-P", "-m", "graphite", "build", str(root)], root
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

graphite/hookinstall.py

@@ -0,0 +1,224 @@
+"""Installing, migrating and removing graphite's git hooks.
+
+All filesystem and git side effects live here; `hookshim` stays pure.
+
+**The interop rule this module exists to honour:** a hook graphite does not
+trigger on is *relocated byte-identically* -- moved, unchanged, with no
+graphite marker and no `.local` sibling. It is never wrapped in a pass-through
+trampoline.
+
+An earlier design did wrap them. aramid's `install()` treats any hook carrying
+another tool's `# >>> <tool> managed >>>` marker as foreign-managed and refuses
+it outright (aramid `0f24609`), skipping its own gate for that hook. Since the
+old design stamped graphite's marker onto *every* migrated hook including
+`pre-commit`/`pre-push`, `graphite init` would have left aramid's gates
+un-refreshable in every repo it touched. Relocation avoids this entirely:
+aramid's shim keeps its own marker, so `_is_aramid_shim` is true, its
+foreign-hook branch never runs, and it regenerates in place. aramid's agent
+independently confirmed this against `hooks.py:333,338-342` and
+`init.py:198-206` before it shipped.
+"""
+from __future__ import annotations
+
+import stat
+import subprocess
+from pathlib import Path
+
+from .config import default_projects_root
+from .hookshim import CHAINED_SUFFIX, MARKER_START, TRIGGERS, render_trigger_shim
+
+DEFAULT_HOOKS_DIRNAME = ".githooks"
+
+# Distinct from the unrelated "template" used for GRAPHITE.md/instruction-doc
+# versioning (`init.py`'s DOC_VERSION) -- "hooks" is spelled out so the two
+# concepts never look like the same thing on disk.
+DEFAULT_TEMPLATE_DIRNAME = ".graphite-hooks-template"
+
+
+def _git(root: Path, *args: str) -> subprocess.CompletedProcess[str]:
+    # Explicit codec and error handler: `text=True` alone decodes with the
+    # locale codec, and git echoes repository paths and branch names that are
+    # not required to be Latin-1. A failure decodes on subprocess's reader
+    # thread, so it yields `stdout is None` rather than raising.
+    return subprocess.run(
+        ["git", "-C", str(root), *args],
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+
+
+def hooks_dir(root: Path) -> Path:
+    """Where hooks live for this repo.
+
+    Honours an existing `core.hooksPath` rather than taking it over: if husky
+    (or anything else) already owns hook policy here, graphite installs into
+    *their* directory. Relative values resolve against the repo root, matching
+    git's own rule and aramid's `hooks_dir`.
+    """
+    configured = _git(root, "config", "--get", "core.hooksPath").stdout.strip()
+    if not configured:
+        return root / DEFAULT_HOOKS_DIRNAME
+    candidate = Path(configured)
+    return candidate if candidate.is_absolute() else root / candidate
+
+
+def hook_shim_present(path: Path) -> bool:
+    """Did graphite write this hook file? Decided by the in-file marker.
+
+    The single marker predicate for the whole codebase. It lived in `doctor`
+    until 2026-07-31; two copies in two modules is how the relocated-hook rule
+    below drifts apart from the code that enforces it.
+    """
+    if not path.is_file():
+        return False
+    try:
+        return MARKER_START.encode() in path.read_bytes()
+    except OSError:
+        return False
+
+
+def _make_executable(path: Path) -> None:
+    """Best-effort on a bare Windows filesystem, but it matters the moment the
+    repo is cloned onto WSL or a Linux CI runner."""
+    try:
+        path.chmod(path.stat().st_mode | stat.S_IXUSR | stat.S_IXGRP | stat.S_IXOTH)
+    except OSError:
+        pass
+
+
+def _is_graphite_shim(path: Path) -> bool:
+    if not path.exists():
+        return False
+    try:
+        return MARKER_START.encode() in path.read_bytes()
+    except OSError:
+        return False
+
+
+def _legacy_hooks(root: Path) -> list[Path]:
+    legacy = root / ".git" / "hooks"
+    if not legacy.is_dir():
+        return []
+    return [p for p in sorted(legacy.iterdir()) if p.is_file() and p.suffix != ".sample"]
+
+
+def install_hooks(root: Path, interpreter: Path) -> list[str]:
+    """Install graphite's trampolines, migrating whatever was already there.
+
+    Returns the names of hooks that were relocated (not chained), so callers
+    can report them -- a silent migration of someone else's hook is exactly the
+    kind of surprise this design is trying to avoid.
+
+    Ordering is load-bearing: `core.hooksPath` is written **last**, so no
+    window exists in which it redirects to a directory that has no hooks yet.
+    """
+    hdir = hooks_dir(root)
+    hdir.mkdir(parents=True, exist_ok=True)
+    already_configured = bool(
+        _git(root, "config", "--get", "core.hooksPath").stdout.strip()
+    )
+
+    relocated: list[str] = []
+    for legacy in _legacy_hooks(root):
+        name = legacy.name
+        target = hdir / (f"{name}{CHAINED_SUFFIX}" if name in TRIGGERS else name)
+        if target.exists() or (name not in TRIGGERS and (hdir / name).exists()):
+            # Already migrated by a previous run; leave both copies alone
+            # rather than clobbering a live hook.
+            continue
+        target.write_bytes(legacy.read_bytes())
+        _make_executable(target)
+        legacy.unlink()
+        if name not in TRIGGERS:
+            relocated.append(name)
+
+    for hook in TRIGGERS:
+        slot = hdir / hook
+        # A pre-existing NON-graphite file in a trigger slot (e.g. one written
+        # straight into .githooks/) becomes the chained original. A graphite
+        # shim is simply regenerated -- never chained to itself.
+        if slot.exists() and not _is_graphite_shim(slot):
+            chained = hdir / f"{hook}{CHAINED_SUFFIX}"
+            if not chained.exists():
+                slot.replace(chained)
+                _make_executable(chained)
+            else:
+                slot.unlink()
+        slot.write_bytes(render_trigger_shim(hook, interpreter))
+        _make_executable(slot)
+
+    if not already_configured:
+        _git(root, "config", "core.hooksPath", DEFAULT_HOOKS_DIRNAME)
+    return relocated
+
+
+def uninstall_hooks(root: Path) -> list[str]:
+    """Remove graphite's trampolines, restoring anything they chained.
+
+    Only graphite's own shims are touched. A relocated foreign hook is left
+    exactly where it is: graphite moved it but never owned it, and deleting it
+    would take out another tool's live gate.
+    """
+    hdir = hooks_dir(root)
+    removed: list[str] = []
+    for hook in TRIGGERS:
+        slot = hdir / hook
+        if not _is_graphite_shim(slot):
+            continue
+        chained = hdir / f"{hook}{CHAINED_SUFFIX}"
+        slot.unlink()
+        if chained.exists():
+            chained.replace(slot)
+            _make_executable(slot)
+        removed.append(hook)
+    return removed
+
+
+def default_template_root() -> Path:
+    """Where `graphite hooks --install-template` writes by default.
+
+    Mirrors the machine-state convention already used for daemon state --
+    `<default_projects_root>/.graphite-daemon` (see `config.default_projects_root`,
+    `cli._incidents_ledger_dir`) -- rather than inventing a new location.
+    Never reads or writes real global git config; that stays the human's step.
+    """
+    return default_projects_root() / DEFAULT_TEMPLATE_DIRNAME
+
+
+def install_template(template_root: Path, interpreter: Path) -> list[Path]:
+    """Write graphite's trigger shims into a git `init.templateDir` layout.
+
+    Git copies `<templateDir>/hooks/<name>` into `.git/hooks/<name>` on every
+    future `git init`/`git clone` on this machine once a human points
+    `init.templateDir` at `template_root` -- the `hooks/` subdirectory is
+    required, since that is what git actually copies from. This function
+    itself never touches git config, real or otherwise, and only ever writes
+    under `template_root`.
+
+    Unlike `install_hooks`, there is no relocation, no `.local` chaining and
+    no `core.hooksPath` write: there is nothing pre-existing to migrate in a
+    template directory, and git's own template-copy mechanism is what wires a
+    fresh repo up. The written bytes are exactly `render_trigger_shim`'s --
+    no separate rendering path for the template case.
+
+    This shim runs in *every* new clone on the machine, onboarded with
+    `GRAPHITE.md` or not, so it must fail open. `hook_entry.main()` already
+    does: it returns 0 silently when no `GRAPHITE.md` is found walking up
+    from cwd. That existing behaviour is what makes reusing the same shim
+    here safe -- a machine-wide template hook that errors would break every
+    unrelated repo on the machine.
+
+    Regeneration is idempotent for the same `(template_root, interpreter)`:
+    `render_trigger_shim` is pure and there is no chaining state to disturb.
+    """
+    hooks_subdir = template_root / "hooks"
+    hooks_subdir.mkdir(parents=True, exist_ok=True)
+    written: list[Path] = []
+    for hook in TRIGGERS:
+        path = hooks_subdir / hook
+        path.write_bytes(render_trigger_shim(hook, interpreter))
+        _make_executable(path)
+        written.append(path)
+    return written