graphite-code 0.3.0__py3-none-any.whl

graphite/agent_settings.py

@@ -0,0 +1,226 @@
+"""Idempotent Claude Code settings wiring for graphite agent hooks.
+
+Graphite owns exactly the hook commands whose command string starts with
+``HOOK_COMMAND_PREFIX``; those are stripped and re-written on every install.
+Everything else in ``.claude/settings.json`` is preserved untouched, and a file
+that fails to parse is never modified.
+"""
+from __future__ import annotations
+
+import json
+import re
+import shlex
+from pathlib import Path
+from typing import Any
+
+from .io import atomic_write_text
+
+# `-P` omits the working directory from `sys.path` (3.11+). Without it,
+# `python -m graphite` puts the CWD at `sys.path[0]`, so a `graphite.py` -- or a
+# `graphite/` directory -- in a managed repo's root wins over the installed
+# package and the hook executes it. The pre-tool-use hook fires on EVERY tool
+# use, so such a file never has to be invoked by anyone: it runs on the next
+# agent action after it lands. `.claude/settings.json` is tracked in consumer
+# repos, so it would arrive through an ordinary reviewed commit, and `init`
+# ships this identical command line to every managed repo.
+#
+# Reported by aramid-agent (channel round 49) and reproduced here: with a
+# `graphite.py` in the CWD, bare `python -m graphite --version` ran the shadow
+# file; `python -P -m graphite --version` ran graphite.
+#
+# `-P` over PYTHONSAFEPATH=1 because it is visible in the command string itself,
+# which matters for a generated file an operator audits by reading.
+HOOK_COMMAND_PREFIX = "python -P -m graphite agent-hook"
+# Every prefix graphite has ever written. Load-bearing, not history: this string
+# is both what we WRITE and what we MATCH to find our own hooks. A matcher that
+# knew only the current spelling would fail to strip the legacy hook from an
+# already-onboarded repo (leaving two, the vulnerable one still firing) and
+# would make `existing_mode` return None, silently downgrading every strict repo
+# to DEFAULT_MODE on its next `init`. Never drop an entry; only ever append.
+_OWNED_COMMAND_PREFIXES = (HOOK_COMMAND_PREFIX, "python -m graphite agent-hook")
+DEFAULT_MODE = "remind"
+_MODES = ("remind", "strict")
+_SESSION_START_COMMAND = f"{HOOK_COMMAND_PREFIX} session-start"
+_STOP_COMMAND = f"{HOOK_COMMAND_PREFIX} stop"
+
+
+def _pre_tool_use_command(mode: str) -> str:
+    return f"{HOOK_COMMAND_PREFIX} pre-tool-use --mode {mode}"
+
+
+def _is_graphite_command(hook: Any) -> bool:
+    return isinstance(hook, dict) and str(hook.get("command", "")).startswith(_OWNED_COMMAND_PREFIXES)
+
+
+def _strip_graphite(groups: Any) -> list[Any]:
+    """Drop graphite-owned commands; keep foreign groups byte-identical."""
+    if not isinstance(groups, list):
+        return []
+    kept: list[Any] = []
+    for entry in groups:
+        if not isinstance(entry, dict) or not isinstance(entry.get("hooks"), list):
+            kept.append(entry)
+            continue
+        remaining = [hook for hook in entry["hooks"] if not _is_graphite_command(hook)]
+        if remaining == entry["hooks"]:
+            kept.append(entry)
+        elif remaining:
+            kept.append({**entry, "hooks": remaining})
+    return kept
+
+
+def _load_settings(path: Path) -> dict[str, Any] | None:
+    """Parsed settings dict, {} when absent, None when malformed."""
+    if not path.exists():
+        return {}
+    try:
+        loaded = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError, UnicodeDecodeError):
+        return None
+    return loaded if isinstance(loaded, dict) else None
+
+
+def read_settings(root: Path) -> dict[str, Any] | None:
+    """A repo's parsed settings: `{}` when absent, `None` when malformed.
+
+    The tri-state matters to callers that report rather than write: "absent"
+    and "unreadable" are different answers, and collapsing them lets a corrupt
+    file read as a clean one.
+    """
+    return _load_settings(root / ".claude" / "settings.json")
+
+
+#: Head tokens that mean the command runs graphite's own console-script entry
+#: point. Measured 2026-08-03: this form is shadowed exactly like `python -m`
+#: -- an installed console script does NOT put its own directory on
+#: `sys.path[0]`, contrary to the obvious assumption -- and it cannot express
+#: the fix, because there is no `-P` to add. It has to change form.
+_CONSOLE_SCRIPT_STEMS = frozenset({"graphite"})
+_INTERPRETER_STEMS = frozenset({"python", "python3", "py", "pythonw"})
+
+#: Split on BOTH separators rather than using `PurePath`, whose `.name` follows
+#: the HOST's flavour: on POSIX, `PurePath(r"C:\Python314\python.exe").name` is
+#: the whole string, so a Windows-spelled hook command went unclassified on any
+#: non-Windows host. A hook command is data read out of a file, not a path on
+#: the machine reading it, so host semantics are the wrong tool entirely.
+#: Caught by the portability matrix on macOS; never observable on Windows.
+_PATH_SEPARATORS = re.compile(r"[\\/]")
+
+
+def _executable_stem(token: str) -> str:
+    """`C:\\Python314\\python.exe` and `/usr/bin/python3` -> `python`, `python3`.
+
+    Identical on every host by construction.
+    """
+    return _PATH_SEPARATORS.split(token.strip('"'))[-1].lower().removesuffix(".exe")
+
+
+def classify_hook_command(command: Any) -> str | None:
+    """Which shadowable invocation form this hook uses, else `None`.
+
+    `None` covers three different "not a finding" cases on purpose: the command
+    is one of ours (`graphite init` maintains those), it does not resolve to the
+    graphite package at all, or it cannot be parsed. Only the invocation HEAD is
+    examined -- a command that merely mentions graphite in an argument, like a
+    path or an `echo`, is not our business and must not be reported, because a
+    check that cries wolf is one nobody reads.
+
+    Never returns the command text. Callers report the form; these commands are
+    mostly absolute path.
+    """
+    if not isinstance(command, str) or not command.strip():
+        return None
+    if command.startswith(_OWNED_COMMAND_PREFIXES):
+        return None
+    try:
+        # posix=False keeps Windows backslashes intact; the POSIX lexer eats
+        # them as escapes and would mangle every real consumer command.
+        tokens = shlex.split(command, posix=False)
+    except ValueError:
+        return None  # unbalanced quotes: decline to guess
+    if not tokens:
+        return None
+    stem = _executable_stem(tokens[0])
+    if stem in _CONSOLE_SCRIPT_STEMS:
+        return "console_script"
+    if stem not in _INTERPRETER_STEMS:
+        return None
+    flags = tokens[1:]
+    if "-m" not in flags:
+        return None
+    marker = flags.index("-m")
+    module = flags[marker + 1].strip('"') if marker + 1 < len(flags) else ""
+    if module.split(".")[0] != "graphite":
+        return None
+    return None if "-P" in flags[:marker] else "python_m_without_P"
+
+
+def existing_mode(root: Path) -> str | None:
+    settings = _load_settings(root / ".claude" / "settings.json")
+    if not settings:
+        return None
+    hooks = settings.get("hooks")
+    groups = hooks.get("PreToolUse") if isinstance(hooks, dict) else None
+    for entry in groups if isinstance(groups, list) else []:
+        if not isinstance(entry, dict):
+            continue
+        for hook in entry.get("hooks", []) if isinstance(entry.get("hooks"), list) else []:
+            command = str(hook.get("command", "")) if isinstance(hook, dict) else ""
+            if command.startswith(_OWNED_COMMAND_PREFIXES) and "pre-tool-use" in command:
+                return "strict" if "--mode strict" in command else "remind"
+    return None
+
+
+def ensure_claude_settings(root: Path, *, mode: str | None = None) -> dict[str, Any]:
+    path = root / ".claude" / "settings.json"
+    resolved = mode or existing_mode(root) or DEFAULT_MODE
+    if resolved not in _MODES:
+        raise ValueError(f"unknown agent-hook mode: {resolved}")
+    existed = path.exists()
+    original = _load_settings(path)
+    if original is None:
+        return {"path": str(path), "changed": False, "action": "malformed settings", "mode": resolved}
+
+    hooks_value = original.get("hooks")
+    if "hooks" in original and not isinstance(hooks_value, dict):
+        # A non-dict "hooks" value is foreign malformed content we must not
+        # silently overwrite with {} — treat it like unparseable JSON: no-op.
+        return {"path": str(path), "changed": False, "action": "malformed settings", "mode": resolved}
+    hooks = dict(hooks_value) if isinstance(hooks_value, dict) else {}
+    desired = {
+        "PreToolUse": {
+            # The shells are matched because the previous matcher, "Grep|Glob",
+            # named TOOLS rather than behaviour: `grep -rn ...` through the Bash
+            # tool and `Select-String` through the PowerShell tool never reached
+            # the hook at all, and consumer agents reported taking exactly those
+            # routes for cross-file work. Enforcing on the Grep tool alone
+            # enforces a naming convention, not a rule.
+            #
+            # `agent_hooks.handle_pre_tool_use` returns None for every shell
+            # command that is not a repo-wide search, so matching the shells
+            # here costs one fail-open hook invocation per command and never
+            # interferes with ordinary work.
+            "matcher": "Grep|Glob|Bash|PowerShell",
+            "hooks": [{"type": "command", "command": _pre_tool_use_command(resolved)}],
+        },
+        "SessionStart": {
+            "hooks": [{"type": "command", "command": _SESSION_START_COMMAND}],
+        },
+        "Stop": {
+            "hooks": [{"type": "command", "command": _STOP_COMMAND}],
+        },
+    }
+    changed = False
+    for event, entry in desired.items():
+        groups = _strip_graphite(hooks.get(event))
+        groups.append(entry)
+        if hooks.get(event) != groups:
+            changed = True
+        hooks[event] = groups
+
+    if not changed:
+        return {"path": str(path), "changed": False, "action": "already current", "mode": resolved}
+    updated = {**original, "hooks": hooks}
+    atomic_write_text(path, json.dumps(updated, ensure_ascii=False, indent=2) + "\n")
+    action = "updated" if existed else "created"
+    return {"path": str(path), "changed": True, "action": action, "mode": resolved}

graphite/analyze.py

@@ -0,0 +1,146 @@
+"""Graph analysis: god nodes, orphans, entry points, cycles."""
+from __future__ import annotations
+
+from typing import Any
+
+import networkx as nx
+
+from .health import resolution_health
+
+_PROJECT_NODE_KINDS = frozenset({"file", "function", "class"})
+
+
+def _is_project_node(g: nx.DiGraph, node: str) -> bool:
+    """Return true for nodes extracted from repository-owned source files."""
+    return g.nodes[node].get("kind") in _PROJECT_NODE_KINDS
+
+
+def _project_nodes(g: nx.DiGraph) -> list[str]:
+    return [n for n in g.nodes() if _is_project_node(g, n)]
+
+
+def _stable_cycles(g: nx.DiGraph, top_n: int) -> list[list[str]]:
+    """Cycles in a fixed order, each rotated to start at its smallest node.
+
+    `nx.simple_cycles` yields in an order that follows set iteration, which
+    `PYTHONHASHSEED` randomizes per process. That is not a cosmetic difference
+    once `[:top_n]` truncates the result: two builds of one commit reported a
+    *different set* of cycles and so disagreed about which cycles the repository
+    contains. Measured on this repository -- `nodes`, `edges` and `metadata`
+    were byte-identical between builds while `analysis.cycles` was not.
+
+    A cycle is also the same cycle under rotation, so one spelling has to be
+    chosen or `[a, b, c]` and `[b, c, a]` both appear depending on where the
+    traversal entered. Nodes within a simple cycle are distinct, so the minimum
+    is unique and rotating to it is canonical. Shortest first, then
+    lexicographic, so the truncation keeps the tightest cycles.
+    """
+    canonical: list[list[str]] = []
+    for cycle in nx.simple_cycles(g):
+        pivot = cycle.index(min(cycle))
+        canonical.append(cycle[pivot:] + cycle[:pivot])
+    canonical.sort(key=lambda cycle: (len(cycle), cycle))
+    return canonical[:top_n]
+
+
+def analyze(g: nx.DiGraph, top_n: int = 20) -> dict[str, Any]:
+    """Run the full analysis suite."""
+    project_subgraph = g.subgraph(_project_nodes(g)).copy()
+    return {
+        "god_nodes": god_nodes(g, top_n),
+        "orphans": orphan_nodes(g, top_n),
+        "entry_points": entry_points(g, top_n),
+        "surprising_connections": surprising_connections(g, top_n),
+        "cycles": _stable_cycles(project_subgraph, top_n),
+        "top_files_by_links": top_files_by_links(g, top_n),
+        "resolution_health": resolution_health(g),
+    }
+
+
+def god_nodes(g: nx.DiGraph, top_n: int = 20) -> list[dict[str, Any]]:
+    """Project-owned nodes with the highest total degree (in + out)."""
+    degrees = [(n, g.degree(n)) for n in _project_nodes(g)]
+    degrees.sort(key=lambda x: x[1], reverse=True)
+    return [
+        {
+            "id": n,
+            "name": g.nodes[n].get("name", n),
+            "kind": g.nodes[n].get("kind", "unknown"),
+            "degree": deg,
+            "in_degree": g.in_degree(n),
+            "out_degree": g.out_degree(n),
+        }
+        for n, deg in degrees[:top_n]
+    ]
+
+
+def orphan_nodes(g: nx.DiGraph, top_n: int = 20) -> list[dict[str, Any]]:
+    """Project-owned nodes with zero connections."""
+    orphans = [n for n in _project_nodes(g) if g.degree(n) == 0]
+    return [
+        {
+            "id": n,
+            "name": g.nodes[n].get("name", n),
+            "kind": g.nodes[n].get("kind", "unknown"),
+        }
+        for n in orphans[:top_n]
+    ]
+
+
+def entry_points(g: nx.DiGraph, top_n: int = 20) -> list[dict[str, Any]]:
+    """File nodes with many outgoing edges and few incoming edges."""
+    file_nodes = [n for n in g.nodes() if g.nodes[n].get("kind") == "file"]
+    scored = []
+    for n in file_nodes:
+        out_deg = g.out_degree(n)
+        in_deg = g.in_degree(n)
+        if out_deg > 0:
+            scored.append((n, out_deg, in_deg, out_deg / max(in_deg, 1)))
+    scored.sort(key=lambda x: x[3], reverse=True)
+    return [
+        {
+            "id": n,
+            "name": g.nodes[n].get("name", n),
+            "out_degree": out_deg,
+            "in_degree": in_deg,
+            "ratio": ratio,
+        }
+        for n, out_deg, in_deg, ratio in scored[:top_n]
+    ]
+
+
+def surprising_connections(g: nx.DiGraph, top_n: int = 20) -> list[dict[str, Any]]:
+    """Project-owned edges between nodes that share no common neighbours."""
+    scored = []
+    for u, v in g.edges():
+        if not (_is_project_node(g, u) and _is_project_node(g, v)):
+            continue
+        common = len(set(g.predecessors(u)).intersection(g.predecessors(v))) + len(
+            set(g.successors(u)).intersection(g.successors(v))
+        )
+        if common == 0:
+            scored.append(
+                {
+                    "source": u,
+                    "target": v,
+                    "source_kind": g.nodes[u].get("kind", "unknown"),
+                    "target_kind": g.nodes[v].get("kind", "unknown"),
+                    "relation": g[u][v].get("relation", "unknown"),
+                }
+            )
+    return scored[:top_n]
+
+
+def top_files_by_links(g: nx.DiGraph, top_n: int = 20) -> list[dict[str, Any]]:
+    """File nodes ranked by total degree."""
+    file_nodes = [n for n in g.nodes() if g.nodes[n].get("kind") == "file"]
+    ranked = sorted(file_nodes, key=lambda n: g.degree(n), reverse=True)
+    return [
+        {
+            "id": n,
+            "name": g.nodes[n].get("name", n),
+            "degree": g.degree(n),
+            "source_file": g.nodes[n].get("source_file"),
+        }
+        for n in ranked[:top_n]
+    ]