graphkeeper-cli 0.1.0__py3-none-any.whl

graphkeeper/graphify.py

@@ -0,0 +1,176 @@
+"""
+Optional enrichment from graphify (https://github.com/Graphify-Labs/graphify,
+PyPI package `graphifyy`)'s symbol/import/call-graph extraction.
+
+Ported from src/graphify.ts. Every `graphify` invocation uses an argv list
+passed directly to the OS (`subprocess.run`, `shell=False`), never a shell
+string, for the same reason as `git.py`. Detection and extraction failures
+never raise -- every failure mode is reported back via `skipped_reason` so
+`build()` can proceed in co-change-only mode, matching the TypeScript
+source's "never throws" contract.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import subprocess
+from pathlib import PurePosixPath
+
+from .store import GRAPHIFY_RAW_DIR_NAME, PathSafetyError, assert_path_inside, ensure_graphkeeper_subdir
+from .types import GraphifyEnrichment
+
+DEFAULT_TIMEOUT_S = 5 * 60
+
+_VERSION_RE = re.compile(r"graphify\s+([\w.-]+)", re.IGNORECASE)
+
+
+def detect_graphify() -> dict:
+    """Detects whether graphify is installed and on PATH, by running
+    `graphify --version`. Returns `{"installed": bool, "version": str |
+    None}`."""
+    try:
+        result = subprocess.run(
+            ["graphify", "--version"],
+            capture_output=True,
+            text=True,
+            timeout=10,
+            check=False,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        return {"installed": False, "version": None}
+
+    if result.returncode != 0:
+        return {"installed": False, "version": None}
+
+    match = _VERSION_RE.search(result.stdout or "")
+    if match:
+        version = match.group(1)
+    else:
+        version = (result.stdout or "").strip() or "unknown"
+    return {"installed": True, "version": version}
+
+
+def run_graphify_enrichment(repo_root: str) -> GraphifyEnrichment:
+    """Runs `graphify extract <repo_root> --code-only --no-cluster --out
+    <dir>` (graphify's own headless, no-LLM, no-API-key CLI path for local
+    AST-based symbol/import/call-graph extraction) and merges its
+    `graph.json` output into a GraphifyEnrichment. Never raises: any failure
+    is reported back via `skipped_reason` so `build()` can proceed in
+    co-change-only mode.
+
+    `--out` is pointed at a directory inside the caller-managed
+    `.graphkeeper/` tree, so graphify's own output never lands outside it.
+    """
+    detected = detect_graphify()
+    if not detected["installed"]:
+        return GraphifyEnrichment(
+            enriched=False,
+            version=None,
+            skipped_reason=(
+                "graphify was not found on PATH. Install it with `uv tool install graphifyy` "
+                "(or `pipx install graphifyy`) for symbol/call-graph enrichment; GraphKeeper "
+                "works fine without it, in co-change-only mode."
+            ),
+        )
+
+    try:
+        raw_dir = ensure_graphkeeper_subdir(repo_root, GRAPHIFY_RAW_DIR_NAME)
+    except PathSafetyError as err:
+        return GraphifyEnrichment(
+            enriched=False,
+            version=detected["version"],
+            skipped_reason=f"Could not prepare a safe output directory for graphify: {err}",
+        )
+
+    try:
+        extract_result = subprocess.run(
+            ["graphify", "extract", repo_root, "--code-only", "--no-cluster", "--out", raw_dir],
+            cwd=repo_root,
+            capture_output=True,
+            text=True,
+            timeout=DEFAULT_TIMEOUT_S,
+            check=False,
+        )
+    except (FileNotFoundError, OSError) as err:
+        return GraphifyEnrichment(
+            enriched=False,
+            version=detected["version"],
+            skipped_reason=f"graphify extract failed to run: {err}",
+        )
+    except subprocess.TimeoutExpired as err:
+        return GraphifyEnrichment(
+            enriched=False,
+            version=detected["version"],
+            skipped_reason=f"graphify extract failed to run: {err}",
+        )
+
+    if extract_result.returncode != 0:
+        stderr_tail = " ".join((extract_result.stderr or "").strip().split("\n")[-3:]).strip()
+        suffix = f": {stderr_tail}" if stderr_tail else ""
+        return GraphifyEnrichment(
+            enriched=False,
+            version=detected["version"],
+            skipped_reason=f"graphify extract exited with status {extract_result.returncode}{suffix}",
+        )
+
+    graph_json_path = os.path.join(raw_dir, "graphify-out", "graph.json")
+    try:
+        assert_path_inside(graph_json_path, repo_root)
+    except PathSafetyError as err:
+        return GraphifyEnrichment(
+            enriched=False,
+            version=detected["version"],
+            skipped_reason=f"graphify's output path failed a safety check: {err}",
+        )
+
+    if not os.path.exists(graph_json_path):
+        return GraphifyEnrichment(
+            enriched=False,
+            version=detected["version"],
+            skipped_reason=f'graphify extract completed but did not produce a graph.json at "{graph_json_path}".',
+        )
+
+    try:
+        with open(graph_json_path, "r", encoding="utf-8") as fh:
+            raw = fh.read()
+        parsed = json.loads(raw)
+    except (OSError, json.JSONDecodeError) as err:
+        return GraphifyEnrichment(
+            enriched=False,
+            version=detected["version"],
+            skipped_reason=f"Could not parse graphify's graph.json: {err}",
+        )
+
+    nodes = parsed.get("nodes") if isinstance(parsed, dict) else None
+    edges = parsed.get("edges") if isinstance(parsed, dict) else None
+    if not isinstance(nodes, list) or not isinstance(edges, list):
+        return GraphifyEnrichment(
+            enriched=False,
+            version=detected["version"],
+            skipped_reason="graphify's graph.json did not have the expected {nodes, edges} shape.",
+        )
+
+    # graphify reports `source_file` relative to its own --out directory,
+    # not the scanned target. Because that --out directory lives nested
+    # inside .graphkeeper/ (so graphify's own output never escapes it, per
+    # this project's path-safety guard), those paths come back as
+    # "../../src/a.py" instead of "src/a.py". Rewrite them relative to
+    # repo_root so they line up with the co-change paths GraphKeeper mines
+    # from git log.
+    def rewrite_source_file(item: dict) -> dict:
+        source_file = item.get("source_file")
+        if not source_file:
+            return item
+        absolute = os.path.normpath(os.path.join(raw_dir, source_file))
+        rewritten = os.path.relpath(absolute, repo_root)
+        rewritten = str(PurePosixPath(*rewritten.split(os.sep)))
+        return {**item, "source_file": rewritten}
+
+    return GraphifyEnrichment(
+        enriched=True,
+        version=detected["version"],
+        skipped_reason=None,
+        nodes=[rewrite_source_file(n) for n in nodes],
+        edges=[rewrite_source_file(e) for e in edges],
+    )

graphkeeper/query.py

@@ -0,0 +1,114 @@
+"""
+Query logic against a built GraphKeeper store: co-change lookups and
+graphify-backed call-graph lookups.
+
+Ported from src/query.ts.
+"""
+from __future__ import annotations
+
+import os
+import re
+from typing import List, Optional
+
+from .types import CallsQueryResult, CoChangeQueryResult, CoChangeResultRow, GraphKeeperStore, GraphifyNode
+
+
+def normalize_file_arg(store: GraphKeeperStore, file: str) -> str:
+    """Normalizes a user-supplied file argument to the repo-relative form
+    GraphKeeper stores paths in."""
+    normalized = file
+    if os.path.isabs(normalized):
+        rel = os.path.relpath(normalized, store.repo_path)
+        if not rel.startswith(".."):
+            normalized = rel
+    normalized = re.sub(r"^\./", "", normalized)
+    return normalized.replace(os.sep, "/")
+
+
+def query_co_change(store: GraphKeeperStore, file: str, limit: Optional[int] = None) -> CoChangeQueryResult:
+    """Finds files that historically changed alongside `file`, ranked by
+    co-change frequency (how many commits touched both)."""
+    target = normalize_file_arg(store, file)
+    results: List[CoChangeResultRow] = []
+    for edge in store.co_change:
+        if edge.a == target:
+            results.append(CoChangeResultRow(file=edge.b, count=edge.count))
+        elif edge.b == target:
+            results.append(CoChangeResultRow(file=edge.a, count=edge.count))
+    results.sort(key=lambda r: r.count, reverse=True)
+    limited = results[:limit] if limit and limit > 0 else results
+    return CoChangeQueryResult(file=target, results=limited)
+
+
+def _normalize_symbol(s: str) -> str:
+    return re.sub(r"\(\)\s*$", "", s.strip()).lower()
+
+
+def find_graphify_node(nodes: List[GraphifyNode], symbol: str) -> Optional[GraphifyNode]:
+    """Finds a graphify node whose label best matches `symbol` (exact match
+    preferred, then case-insensitive)."""
+    for n in nodes:
+        if n.get("label") == symbol or n.get("label") == f"{symbol}()":
+            return n
+    target = _normalize_symbol(symbol)
+    for n in nodes:
+        if _normalize_symbol(str(n.get("label", ""))) == target:
+            return n
+    for n in nodes:
+        node_id = n.get("id", "")
+        if node_id == symbol or str(node_id).endswith(f"_{symbol}"):
+            return n
+    return None
+
+
+def query_calls(store: GraphKeeperStore, symbol: str) -> CallsQueryResult:
+    """Finds callers/callees of `symbol` using graphify's `calls` edges.
+    Only meaningful when the build included graphify enrichment; otherwise
+    reports why (never a silent empty result or a crash)."""
+    if not store.graphify.enriched:
+        return CallsQueryResult(
+            symbol=symbol,
+            available=False,
+            unavailable_reason=(
+                store.graphify.skipped_reason
+                or "This build did not include graphify enrichment, so call-graph queries aren't "
+                "available. Install graphify (`uv tool install graphifyy`) and re-run "
+                "`graphkeeper build` to enable them."
+            ),
+            node=None,
+            calls=[],
+            called_by=[],
+        )
+
+    nodes_by_id = {n.get("id"): n for n in store.graphify.nodes}
+    node = find_graphify_node(store.graphify.nodes, symbol)
+
+    if not node:
+        return CallsQueryResult(
+            symbol=symbol,
+            available=True,
+            unavailable_reason=None,
+            node=None,
+            calls=[],
+            called_by=[],
+        )
+
+    calls = [
+        {"node": nodes_by_id.get(e.get("target")), "edge": e}
+        for e in store.graphify.edges
+        if e.get("relation") == "calls" and e.get("source") == node.get("id")
+    ]
+    called_by = [
+        {"node": nodes_by_id.get(e.get("source")), "edge": e}
+        for e in store.graphify.edges
+        if e.get("relation") == "calls" and e.get("target") == node.get("id")
+    ]
+
+    return CallsQueryResult(
+        symbol=symbol,
+        available=True,
+        unavailable_reason=None,
+        node=node,
+        calls=calls,
+        called_by=called_by,
+    )

graphkeeper/store.py

@@ -0,0 +1,121 @@
+"""
+Path-safety-checked local storage for the GraphKeeper store.
+
+Ported from src/store.ts. Every write and every directory GraphKeeper
+creates is verified, after resolving symlinks, to be nested inside the
+target repo's own `.graphkeeper/` directory -- so a maliciously crafted
+repo (e.g. `.graphkeeper` itself replaced with a symlink to `/etc`, or a
+target path containing `..`) can never redirect GraphKeeper's writes
+somewhere unexpected.
+"""
+from __future__ import annotations
+
+import json
+import os
+from typing import Optional
+
+from .types import GraphKeeperStore
+
+GRAPHKEEPER_DIR_NAME = ".graphkeeper"
+GRAPH_FILE_NAME = "graph.json"
+GRAPHIFY_RAW_DIR_NAME = "graphify-raw"
+
+
+class PathSafetyError(Exception):
+    pass
+
+
+def resolve_repo_root(target_path: str) -> str:
+    """Resolves `target_path` to a real, existing directory. Follows
+    symlinks (`os.path.realpath`) so a malicious repo cannot point
+    GraphKeeper's notion of "repo root" somewhere unexpected via a crafted
+    symlink at the entry point."""
+    resolved = os.path.abspath(target_path)
+    if not os.path.exists(resolved):
+        raise PathSafetyError(f'Path "{target_path}" does not exist.')
+    real = os.path.realpath(resolved)
+    if not os.path.isdir(real):
+        raise PathSafetyError(f'Path "{target_path}" is not a directory.')
+    return real
+
+
+def assert_path_inside(child_path: str, parent_path: str) -> None:
+    """Confirms that `child_path`, once symlinks are resolved, is the same
+    as or nested inside `parent_path`. This is the core guard against a
+    crafted repo causing GraphKeeper to read or write outside the intended
+    output directory."""
+    real_parent = os.path.realpath(parent_path)
+
+    # child_path may not exist yet (e.g. before mkdir); resolve its nearest
+    # existing ancestor and re-attach the remaining, not-yet-created
+    # segments, mirroring src/store.ts's own walk-up loop.
+    to_resolve = os.path.abspath(child_path)
+    remainder = []
+    while not os.path.exists(to_resolve):
+        remainder.insert(0, os.path.basename(to_resolve))
+        parent_of_to_resolve = os.path.dirname(to_resolve)
+        if parent_of_to_resolve == to_resolve:
+            # Reached filesystem root without finding an existing ancestor.
+            break
+        to_resolve = parent_of_to_resolve
+
+    real_existing_ancestor = os.path.realpath(to_resolve) if os.path.exists(to_resolve) else to_resolve
+    real_child = os.path.join(real_existing_ancestor, *remainder) if remainder else real_existing_ancestor
+
+    is_inside = real_child == real_parent or real_child.startswith(real_parent + os.sep)
+    if not is_inside:
+        raise PathSafetyError(
+            f"Refusing to write outside the target repo's {GRAPHKEEPER_DIR_NAME}/ directory "
+            f'(resolved "{child_path}" -> "{real_child}", expected it under "{real_parent}").'
+        )
+
+
+def ensure_graphkeeper_subdir(repo_root: str, *subdir_segments: str) -> str:
+    """Creates (or reuses) `.graphkeeper/<subdir...>` under `repo_root`,
+    verifying containment at every step."""
+    gk_dir = os.path.join(repo_root, GRAPHKEEPER_DIR_NAME)
+    os.makedirs(gk_dir, exist_ok=True)
+    assert_path_inside(gk_dir, repo_root)
+
+    directory = gk_dir
+    for segment in subdir_segments:
+        directory = os.path.join(directory, segment)
+    os.makedirs(directory, exist_ok=True)
+    assert_path_inside(directory, repo_root)
+    return directory
+
+
+def graph_file_path(repo_root: str) -> str:
+    """Path to the merged GraphKeeper store file, `.graphkeeper/graph.json`,
+    under `repo_root`."""
+    return os.path.join(repo_root, GRAPHKEEPER_DIR_NAME, GRAPH_FILE_NAME)
+
+
+def write_store(repo_root: str, store: GraphKeeperStore) -> str:
+    """Writes the store atomically (write to temp file, then rename) inside
+    `.graphkeeper/`."""
+    gk_dir = ensure_graphkeeper_subdir(repo_root)
+    final_path = os.path.join(gk_dir, GRAPH_FILE_NAME)
+    tmp_path = f"{final_path}.tmp-{os.getpid()}"
+    assert_path_inside(tmp_path, repo_root)
+    with open(tmp_path, "w", encoding="utf-8") as fh:
+        json.dump(store.to_dict(), fh, indent=2)
+    os.replace(tmp_path, final_path)
+    return final_path
+
+
+def read_store(repo_root: str, override_path: Optional[str] = None) -> GraphKeeperStore:
+    """Reads and parses `.graphkeeper/graph.json`, or a caller-supplied path
+    override."""
+    target = os.path.abspath(override_path) if override_path else graph_file_path(repo_root)
+    if not os.path.exists(target):
+        raise PathSafetyError(f'No graph found at "{target}". Run "graphkeeper build" first.')
+    with open(target, "r", encoding="utf-8") as fh:
+        raw = fh.read()
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError as err:
+        raise PathSafetyError(f'"{target}" does not contain a valid GraphKeeper store.') from err
+    if not isinstance(parsed, dict):
+        raise PathSafetyError(f'"{target}" does not contain a valid GraphKeeper store.')
+    return GraphKeeperStore.from_dict(parsed)

graphkeeper/types.py

@@ -0,0 +1,149 @@
+"""
+Shared types for GraphKeeper's local knowledge-graph store.
+
+The store is a single JSON file, `.graphkeeper/graph.json`, containing:
+ - co-change data mined from `git log` (GraphKeeper's own contribution)
+ - optionally, symbol/call-graph data merged in from graphify, if graphify
+   is installed and enrichment succeeded (see graphkeeper/graphify.py)
+
+Ported from src/types.ts. Field names here are snake_case (Python
+convention); `GraphKeeperStore.to_dict()` / `.from_dict()` translate to and
+from the camelCase JSON schema the npm CLI also reads and writes, so a
+`.graphkeeper/graph.json` built by either distribution can be read by the
+other.
+
+graphify node/edge shapes are kept as plain `Dict[str, Any]` rather than a
+fixed dataclass, matching the TypeScript source's own `[key: string]:
+unknown` index signature -- graphify's own `graph.json` output can carry
+fields this project doesn't know about in advance, and round-tripping them
+through a fixed schema would silently drop them.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
+
+GraphifyNode = Dict[str, Any]
+GraphifyEdge = Dict[str, Any]
+
+
+@dataclass
+class CoChangeEdge:
+    """One unordered pair of files that changed together in one or more commits."""
+
+    a: str
+    b: str
+    count: int
+
+
+@dataclass
+class GraphifyEnrichment:
+    """Result of attempting graphify enrichment during a build."""
+
+    enriched: bool
+    version: Optional[str]
+    skipped_reason: Optional[str]
+    nodes: List[GraphifyNode] = field(default_factory=list)
+    edges: List[GraphifyEdge] = field(default_factory=list)
+
+
+@dataclass
+class GraphKeeperStore:
+    """The full on-disk store written to `.graphkeeper/graph.json`."""
+
+    version: int
+    generated_at: str
+    repo_path: str
+    commits_analyzed: int
+    commits_skipped: int
+    co_change: List[CoChangeEdge]
+    file_commit_counts: Dict[str, int]
+    graphify: GraphifyEnrichment
+
+    def to_dict(self) -> Dict[str, Any]:
+        return {
+            "version": self.version,
+            "generatedAt": self.generated_at,
+            "repoPath": self.repo_path,
+            "commitsAnalyzed": self.commits_analyzed,
+            "commitsSkipped": self.commits_skipped,
+            "coChange": [{"a": e.a, "b": e.b, "count": e.count} for e in self.co_change],
+            "fileCommitCounts": self.file_commit_counts,
+            "graphify": {
+                "enriched": self.graphify.enriched,
+                "version": self.graphify.version,
+                "skippedReason": self.graphify.skipped_reason,
+                "nodes": self.graphify.nodes,
+                "edges": self.graphify.edges,
+            },
+        }
+
+    @staticmethod
+    def from_dict(data: Dict[str, Any]) -> "GraphKeeperStore":
+        graphify_raw = data.get("graphify") or {}
+        graphify = GraphifyEnrichment(
+            enriched=bool(graphify_raw.get("enriched", False)),
+            version=graphify_raw.get("version"),
+            skipped_reason=graphify_raw.get("skippedReason"),
+            nodes=list(graphify_raw.get("nodes") or []),
+            edges=list(graphify_raw.get("edges") or []),
+        )
+        co_change = [
+            CoChangeEdge(a=e["a"], b=e["b"], count=e["count"]) for e in (data.get("coChange") or [])
+        ]
+        return GraphKeeperStore(
+            version=data.get("version", 1),
+            generated_at=data.get("generatedAt", ""),
+            repo_path=data.get("repoPath", ""),
+            commits_analyzed=data.get("commitsAnalyzed", 0),
+            commits_skipped=data.get("commitsSkipped", 0),
+            co_change=co_change,
+            file_commit_counts=dict(data.get("fileCommitCounts") or {}),
+            graphify=graphify,
+        )
+
+
+@dataclass
+class BuildOptions:
+    """Options for `build()`. Mirrors src/types.ts's `BuildOptions`."""
+
+    max_files_per_commit: Optional[int] = None
+    """Skip commits touching more than this many files (default: 100)."""
+
+    skip_graphify: bool = False
+    """Skip graphify enrichment even if graphify is installed."""
+
+    graphify_timeout_ms: Optional[int] = None
+    """Present for parity with the TypeScript `BuildOptions` type. Not
+    currently wired to a real timeout override in either the TypeScript
+    source or this port -- `graphify.py`'s enrichment timeout is a fixed
+    constant, same as upstream. Kept here rather than silently dropped, so a
+    future fix lands in one obvious place."""
+
+
+@dataclass
+class BuildResult:
+    store: GraphKeeperStore
+    output_path: str
+
+
+@dataclass
+class CoChangeResultRow:
+    file: str
+    count: int
+
+
+@dataclass
+class CoChangeQueryResult:
+    file: str
+    results: List[CoChangeResultRow]
+
+
+@dataclass
+class CallsQueryResult:
+    symbol: str
+    available: bool
+    unavailable_reason: Optional[str]
+    node: Optional[GraphifyNode]
+    calls: List[Dict[str, Any]]
+    called_by: List[Dict[str, Any]]