graphkeeper-cli 0.1.0__py3-none-any.whl

graphkeeper/__init__.py

@@ -0,0 +1,71 @@
+"""
+GraphKeeper library API.
+
+    from graphkeeper import build, query_co_change
+
+    result = build(".")
+    print(f"{result.store.commits_analyzed} commit(s) analyzed")
+
+    co_change = query_co_change(result.store, "src/git.py")
+    for row in co_change.results:
+        print(row.count, row.file)
+
+This is the Python port of the graphkeeper-cli npm package
+(https://www.npmjs.com/package/graphkeeper-cli). Both distributions mine
+`git log` for the same file-level co-change signal and, when graphify
+(https://github.com/Graphify-Labs/graphify) is installed, enrich the same
+store with its symbol/call-graph output; see
+https://github.com/RudrenduPaul/GraphKeeper for the canonical
+documentation and the original TypeScript source. `graphkeeper.cli` is a
+thin argument-parsing wrapper over the same functions exported here, so
+anything scriptable from the command line is also usable directly from
+Python.
+"""
+from .build import build
+from .git import GitError, mine_co_change, unquote_git_path
+from .graphify import detect_graphify, run_graphify_enrichment
+from .query import find_graphify_node, normalize_file_arg, query_calls, query_co_change
+from .store import PathSafetyError, graph_file_path, read_store, resolve_repo_root, write_store
+from .types import (
+    BuildOptions,
+    BuildResult,
+    CallsQueryResult,
+    CoChangeEdge,
+    CoChangeQueryResult,
+    CoChangeResultRow,
+    GraphifyEnrichment,
+    GraphifyEdge,
+    GraphifyNode,
+    GraphKeeperStore,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "build",
+    "query_co_change",
+    "query_calls",
+    "find_graphify_node",
+    "normalize_file_arg",
+    "detect_graphify",
+    "run_graphify_enrichment",
+    "mine_co_change",
+    "unquote_git_path",
+    "GitError",
+    "resolve_repo_root",
+    "read_store",
+    "write_store",
+    "graph_file_path",
+    "PathSafetyError",
+    "GraphKeeperStore",
+    "CoChangeEdge",
+    "GraphifyNode",
+    "GraphifyEdge",
+    "GraphifyEnrichment",
+    "BuildOptions",
+    "BuildResult",
+    "CoChangeQueryResult",
+    "CoChangeResultRow",
+    "CallsQueryResult",
+    "__version__",
+]

graphkeeper/build.py

@@ -0,0 +1,48 @@
+"""
+Builds (or rebuilds) the GraphKeeper store for a repo.
+
+Ported from src/build.ts.
+"""
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from typing import Optional
+
+from .git import mine_co_change
+from .graphify import run_graphify_enrichment
+from .store import resolve_repo_root, write_store
+from .types import BuildOptions, BuildResult, GraphifyEnrichment, GraphKeeperStore
+
+
+def build(target_path: str, options: Optional[BuildOptions] = None) -> BuildResult:
+    """Builds (or rebuilds) the GraphKeeper store for a repo: mines `git
+    log` for file-level co-change, optionally enriches it with graphify's
+    symbol/call graph if graphify is installed, and writes the merged
+    result to `.graphkeeper/graph.json`."""
+    opts = options or BuildOptions()
+    repo_root = resolve_repo_root(target_path)
+
+    mined = mine_co_change(repo_root, opts.max_files_per_commit)
+
+    if opts.skip_graphify:
+        graphify = GraphifyEnrichment(
+            enriched=False,
+            version=None,
+            skipped_reason="graphify enrichment skipped via --no-graphify.",
+        )
+    else:
+        graphify = run_graphify_enrichment(repo_root)
+
+    store = GraphKeeperStore(
+        version=1,
+        generated_at=datetime.now(timezone.utc).isoformat().replace("+00:00", "Z"),
+        repo_path=repo_root,
+        commits_analyzed=mined.commits_analyzed,
+        commits_skipped=mined.commits_skipped,
+        co_change=mined.co_change,
+        file_commit_counts=mined.file_commit_counts,
+        graphify=graphify,
+    )
+
+    output_path = write_store(repo_root, store)
+    return BuildResult(store=store, output_path=output_path)

graphkeeper/cli.py

@@ -0,0 +1,167 @@
+#!/usr/bin/env python3
+"""
+Argument-parsing wrapper over graphkeeper's build/query library functions.
+Console entry point: `graphkeeper <command> [options]`, installed via the
+`graphkeeper` console-script defined in python/pyproject.toml.
+
+Ported from src/cli.ts (which uses `commander`); this port uses the stdlib
+`argparse` to avoid a CLI-framework dependency. Subcommands, flags,
+defaults, and exit codes are kept identical to the npm CLI's `--help`
+output and behavior: `build [path]`, `query co-change <file>`, and
+`query calls <symbol>`.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import List, NoReturn, Optional
+
+from .build import build
+from .formatters import (
+    format_build_json,
+    format_build_text,
+    format_calls_json,
+    format_calls_text,
+    format_co_change_json,
+    format_co_change_text,
+    parse_positive_int,
+)
+from .query import query_calls, query_co_change
+from .store import read_store, resolve_repo_root
+from .types import BuildOptions
+
+VERSION = "0.1.0"
+
+
+def _report_error(err: Exception, as_json: bool) -> NoReturn:
+    message = str(err)
+    if as_json:
+        sys.stderr.write(json.dumps({"error": message}, indent=2) + "\n")
+    else:
+        sys.stderr.write(f"Error: {message}\n")
+    sys.exit(2)
+
+
+def build_parser() -> "tuple[argparse.ArgumentParser, argparse.ArgumentParser]":
+    parser = argparse.ArgumentParser(
+        prog="graphkeeper",
+        description=(
+            "Local-only CLI that mines git history for file-level co-change patterns and builds a "
+            "queryable knowledge graph for AI coding agents, with optional enrichment from graphify's "
+            "symbol/call-graph output when it is installed."
+        ),
+    )
+    parser.add_argument("-V", "--version", action="version", version=VERSION)
+
+    subparsers = parser.add_subparsers(dest="command")
+
+    build_cmd = subparsers.add_parser(
+        "build",
+        description="Mine git history for co-change and (if available) merge in graphify's symbol/call graph",
+    )
+    build_cmd.add_argument("path", nargs="?", default=".", help="path to the target repo")
+    build_cmd.add_argument("--json", action="store_true", help="emit machine-readable JSON instead of human-readable text")
+    build_cmd.add_argument(
+        "--max-files-per-commit",
+        default=None,
+        help="skip commits touching more than this many files (default: 100)",
+    )
+    build_cmd.add_argument(
+        "--no-graphify",
+        dest="graphify",
+        action="store_false",
+        default=True,
+        help="skip graphify enrichment even if graphify is installed",
+    )
+
+    query_cmd = subparsers.add_parser("query", description="Query the GraphKeeper store built by `graphkeeper build`")
+    query_subparsers = query_cmd.add_subparsers(dest="query_command")
+
+    co_change_cmd = query_subparsers.add_parser(
+        "co-change",
+        description="List files that historically change alongside <file>, ranked by co-change frequency",
+    )
+    co_change_cmd.add_argument("file", help="repo-relative file path, e.g. src/git.py")
+    co_change_cmd.add_argument("--json", action="store_true", help="emit machine-readable JSON instead of human-readable text")
+    co_change_cmd.add_argument("--limit", default=None, help="cap the number of results")
+    co_change_cmd.add_argument(
+        "--graph", default=None, help="path to a specific graph.json (default: <cwd>/.graphkeeper/graph.json)"
+    )
+
+    calls_cmd = query_subparsers.add_parser(
+        "calls",
+        description="Show callers/callees of <symbol> (requires graphify enrichment from `graphkeeper build`)",
+    )
+    calls_cmd.add_argument("symbol", help="symbol name, e.g. parse_config")
+    calls_cmd.add_argument("--json", action="store_true", help="emit machine-readable JSON instead of human-readable text")
+    calls_cmd.add_argument(
+        "--graph", default=None, help="path to a specific graph.json (default: <cwd>/.graphkeeper/graph.json)"
+    )
+
+    return parser, query_cmd
+
+
+def _run_build(args: argparse.Namespace) -> int:
+    try:
+        max_files_per_commit = (
+            parse_positive_int(args.max_files_per_commit, "--max-files-per-commit")
+            if args.max_files_per_commit
+            else None
+        )
+        result = build(
+            args.path,
+            BuildOptions(max_files_per_commit=max_files_per_commit, skip_graphify=not args.graphify),
+        )
+        print(format_build_json(result) if args.json else format_build_text(result))
+        return 0
+    except Exception as err:  # noqa: BLE001 -- mirrors src/cli.ts's catch-all reportError()
+        _report_error(err, bool(args.json))
+
+
+def _run_query_co_change(args: argparse.Namespace) -> int:
+    try:
+        limit = parse_positive_int(args.limit, "--limit") if args.limit else None
+        repo_root = resolve_repo_root(".")
+        store = read_store(repo_root, args.graph)
+        result = query_co_change(store, args.file, limit)
+        print(format_co_change_json(result) if args.json else format_co_change_text(result))
+        return 0 if result.results else 1
+    except Exception as err:  # noqa: BLE001
+        _report_error(err, bool(args.json))
+
+
+def _run_query_calls(args: argparse.Namespace) -> int:
+    try:
+        repo_root = resolve_repo_root(".")
+        store = read_store(repo_root, args.graph)
+        result = query_calls(store, args.symbol)
+        print(format_calls_json(result) if args.json else format_calls_text(result))
+        return 0 if (result.available and result.node) else 1
+    except Exception as err:  # noqa: BLE001
+        _report_error(err, bool(args.json))
+
+
+def run_cli(argv: Optional[List[str]] = None) -> int:
+    parser, query_cmd = build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "build":
+        return _run_build(args)
+    if args.command == "query":
+        if args.query_command == "co-change":
+            return _run_query_co_change(args)
+        if args.query_command == "calls":
+            return _run_query_calls(args)
+        query_cmd.print_help()
+        return 0
+    parser.print_help()
+    return 0
+
+
+def main() -> None:
+    sys.exit(run_cli(sys.argv[1:]))
+
+
+if __name__ == "__main__":
+    main()

graphkeeper/formatters.py

@@ -0,0 +1,125 @@
+"""
+Human-readable and JSON output formatters, plus small CLI argument-parsing
+helpers.
+
+Ported from src/cli-lib.ts.
+"""
+from __future__ import annotations
+
+import json
+
+from .types import BuildResult, CallsQueryResult, CoChangeQueryResult
+
+
+def parse_positive_int(raw: str, flag_name: str) -> int:
+    stripped = raw.strip()
+    try:
+        n = int(stripped)
+    except ValueError:
+        n = None
+    if n is None or n <= 0 or str(n) != stripped:
+        raise ValueError(f'Invalid {flag_name} value "{raw}". Expected a positive integer.')
+    return n
+
+
+def format_build_text(result: BuildResult) -> str:
+    store = result.store
+    lines = [f"GraphKeeper build complete: {store.repo_path}", ""]
+    skipped_note = (
+        f" ({store.commits_skipped} commit(s) skipped: too many files changed)"
+        if store.commits_skipped > 0
+        else ""
+    )
+    lines.append(
+        f"Co-change graph: {store.commits_analyzed} commit(s) analyzed, "
+        f"{len(store.co_change)} file pair(s) found{skipped_note}"
+    )
+    if store.graphify.enriched:
+        version = store.graphify.version or "unknown"
+        lines.append(
+            f"graphify enrichment: included (v{version}) -- "
+            f"{len(store.graphify.nodes)} node(s), {len(store.graphify.edges)} edge(s)"
+        )
+    else:
+        lines.append(f"graphify enrichment: skipped -- {store.graphify.skipped_reason or 'unknown reason'}")
+    lines.append("")
+    lines.append(f"Wrote {result.output_path}")
+    return "\n".join(lines)
+
+
+def format_build_json(result: BuildResult) -> str:
+    store = result.store
+    payload = {
+        "repoPath": store.repo_path,
+        "outputPath": result.output_path,
+        "generatedAt": store.generated_at,
+        "commitsAnalyzed": store.commits_analyzed,
+        "commitsSkipped": store.commits_skipped,
+        "coChangePairs": len(store.co_change),
+        "graphify": {
+            "enriched": store.graphify.enriched,
+            "version": store.graphify.version,
+            "skippedReason": store.graphify.skipped_reason,
+            "nodes": len(store.graphify.nodes),
+            "edges": len(store.graphify.edges),
+        },
+    }
+    return json.dumps(payload, indent=2)
+
+
+def format_co_change_text(result: CoChangeQueryResult) -> str:
+    lines = [f'Files that historically change alongside "{result.file}":', ""]
+    if not result.results:
+        lines.append("  (no co-change data found for this file -- check the path, or run `graphkeeper build` first)")
+    else:
+        for r in result.results:
+            lines.append(f"  {str(r.count).rjust(4)}  {r.file}")
+    return "\n".join(lines)
+
+
+def format_co_change_json(result: CoChangeQueryResult) -> str:
+    payload = {"file": result.file, "results": [{"file": r.file, "count": r.count} for r in result.results]}
+    return json.dumps(payload, indent=2)
+
+
+def format_calls_text(result: CallsQueryResult) -> str:
+    if not result.available:
+        return "\n".join(
+            [
+                f'Call-graph query for "{result.symbol}" is not available.',
+                "",
+                result.unavailable_reason or "graphify enrichment is required for this query type.",
+            ]
+        )
+    if not result.node:
+        return f'No symbol matching "{result.symbol}" was found in the graphify graph.'
+
+    label = result.node.get("label", result.symbol)
+    source_file = result.node.get("source_file") or "unknown location"
+    lines = [f"{label} ({source_file})", ""]
+    lines.append(f"Calls ({len(result.calls)}):")
+    for c in result.calls:
+        node = c.get("node")
+        edge = c.get("edge") or {}
+        target = node.get("label") if node else edge.get("target")
+        lines.append(f"  --> {target}")
+    lines.append("")
+    lines.append(f"Called by ({len(result.called_by)}):")
+    for c in result.called_by:
+        node = c.get("node")
+        edge = c.get("edge") or {}
+        source = node.get("label") if node else edge.get("source")
+        lines.append(f"  <-- {source}")
+    return "\n".join(lines)
+
+
+def format_calls_json(result: CallsQueryResult) -> str:
+    payload = {
+        "symbol": result.symbol,
+        "available": result.available,
+        "unavailableReason": result.unavailable_reason,
+        "node": result.node,
+        "calls": result.calls,
+        "calledBy": result.called_by,
+    }
+    return json.dumps(payload, indent=2)

graphkeeper/git.py

@@ -0,0 +1,207 @@
+"""
+Mines `git log` history for file-level co-change: pairs of files that were
+modified together in the same commit.
+
+Ported from src/git.ts. Every `git` invocation uses an argv list passed
+directly to the OS (`subprocess.run`, `shell=False`), never a shell string,
+so commit messages, file paths, or repo paths can never be interpreted as
+shell syntax.
+"""
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass, field
+from typing import Dict, List, Optional
+
+from .types import CoChangeEdge
+
+# Marker used to split `git log` output into per-commit chunks. Chosen to be
+# extremely unlikely to appear in a commit message or file path.
+COMMIT_MARKER = "@@GK-COMMIT@@"
+
+DEFAULT_MAX_FILES_PER_COMMIT = 100
+
+
+class GitError(Exception):
+    pass
+
+
+def _run_git(repo_path: str, args: List[str]) -> "subprocess.CompletedProcess[str]":
+    try:
+        return subprocess.run(
+            ["git", "-C", repo_path, *args],
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except FileNotFoundError as err:
+        raise GitError("git is not installed or not on PATH.") from err
+    except OSError as err:
+        raise GitError(f"Failed to run git: {err}") from err
+
+
+def assert_is_git_repo(repo_path: str) -> None:
+    """Raises GitError if `repo_path` is not inside a git working tree."""
+    result = _run_git(repo_path, ["rev-parse", "--is-inside-work-tree"])
+    if result.returncode != 0:
+        raise GitError(f'"{repo_path}" is not a git repository. {result.stderr.strip()}'.strip())
+
+
+def unquote_git_path(raw: str) -> str:
+    """Unquotes a git `--name-only` path entry. Git C-quotes paths
+    containing unusual bytes (non-ASCII when core.quotePath is on, quotes,
+    backslashes, control characters) by wrapping them in double quotes with
+    backslash/octal escapes. Plain paths are returned unchanged."""
+    if len(raw) < 2 or raw[0] != '"' or raw[-1] != '"':
+        return raw
+    inner = raw[1:-1]
+    # Octal escapes are individual *bytes* of a (possibly multi-byte UTF-8)
+    # sequence, so this must accumulate raw bytes and UTF-8-decode once at
+    # the end -- decoding each escaped byte independently would mangle any
+    # non-ASCII character spanning more than one byte.
+    byte_values: List[int] = []
+    i = 0
+    n = len(inner)
+    while i < n:
+        ch = inner[i]
+        if ch != "\\":
+            # core.quotePath=true escapes every byte >= 0x80, so an
+            # unescaped character here is always plain ASCII.
+            byte_values.append(ord(ch))
+            i += 1
+            continue
+        nxt = inner[i + 1] if i + 1 < n else None
+        if nxt is None:
+            byte_values.append(ord(ch))
+            i += 1
+            continue
+        if "0" <= nxt <= "7":
+            octal = inner[i + 1 : i + 4]
+            try:
+                code = int(octal, 8)
+            except ValueError:
+                code = ord(nxt)
+            byte_values.append(code)
+            i += 4
+            continue
+        if nxt == "n":
+            byte_values.append(0x0A)
+        elif nxt == "t":
+            byte_values.append(0x09)
+        elif nxt == "\\":
+            byte_values.append(0x5C)
+        elif nxt == '"':
+            byte_values.append(0x22)
+        else:
+            byte_values.append(ord(nxt))
+        i += 2
+    return bytes(byte_values).decode("utf-8")
+
+
+def _has_no_nul_byte(p: str) -> bool:
+    """True if every character code in `p` is non-zero (i.e. no embedded
+    NUL bytes)."""
+    return "\0" not in p
+
+
+def _is_safe_tracked_path(p: str) -> bool:
+    """Rejects path entries that could escape the repo tree or aren't real
+    tracked files."""
+    if not p:
+        return False
+    if not _has_no_nul_byte(p):
+        return False
+    if p.startswith("/") or p.startswith("~"):
+        return False
+    segments = p.split("/")
+    if any(s == ".." for s in segments):
+        return False
+    return True
+
+
+@dataclass
+class CoChangeMiningResult:
+    co_change: List[CoChangeEdge] = field(default_factory=list)
+    file_commit_counts: Dict[str, int] = field(default_factory=dict)
+    commits_analyzed: int = 0
+    commits_skipped: int = 0
+
+
+def mine_co_change(repo_path: str, max_files_per_commit: Optional[int] = None) -> CoChangeMiningResult:
+    """Mines `git log` history for file-level co-change: pairs of files that
+    were modified together in the same commit. This is GraphKeeper's own
+    signal, distinct from (and complementary to) symbol/call-graph
+    extraction."""
+    effective_max = max_files_per_commit if max_files_per_commit is not None else DEFAULT_MAX_FILES_PER_COMMIT
+    assert_is_git_repo(repo_path)
+
+    result = _run_git(
+        repo_path,
+        [
+            "-c",
+            "core.quotePath=true",
+            "log",
+            "--no-merges",
+            f"--pretty=format:{COMMIT_MARKER}%H",
+            "--name-only",
+        ],
+    )
+    if result.returncode != 0:
+        raise GitError(f"git log failed: {result.stderr.strip()}")
+
+    stdout = result.stdout or ""
+    if stdout.strip() == "":
+        return CoChangeMiningResult()
+
+    # Keyed by (a, b) tuples -- each commit's own file list is sorted before
+    # pairing, so a < b lexicographically within every pair, making the
+    # tuple an unambiguous key across all commits (no JSON-stringify trick
+    # needed, unlike the TypeScript original, since Python tuples are
+    # natively hashable).
+    pair_counts: Dict[tuple, int] = {}
+    file_commit_counts: Dict[str, int] = {}
+    commits_analyzed = 0
+    commits_skipped = 0
+
+    chunks = stdout.split(COMMIT_MARKER)[1:]
+    for chunk in chunks:
+        newline_index = chunk.find("\n")
+        files_raw = "" if newline_index == -1 else chunk[newline_index + 1 :]
+        seen = []
+        seen_set = set()
+        for line in files_raw.split("\n"):
+            candidate = line.strip()
+            if not candidate:
+                continue
+            unquoted = unquote_git_path(candidate)
+            if not _is_safe_tracked_path(unquoted):
+                continue
+            if unquoted not in seen_set:
+                seen_set.add(unquoted)
+                seen.append(unquoted)
+        files = sorted(seen)
+
+        if len(files) == 0:
+            continue
+        if len(files) > effective_max:
+            commits_skipped += 1
+            continue
+
+        commits_analyzed += 1
+        for f in files:
+            file_commit_counts[f] = file_commit_counts.get(f, 0) + 1
+        for idx in range(len(files)):
+            for jdx in range(idx + 1, len(files)):
+                a, b = files[idx], files[jdx]
+                key = (a, b)
+                pair_counts[key] = pair_counts.get(key, 0) + 1
+
+    co_change = [CoChangeEdge(a=a, b=b, count=count) for (a, b), count in pair_counts.items()]
+    co_change.sort(key=lambda e: e.count, reverse=True)
+
+    return CoChangeMiningResult(
+        co_change=co_change,
+        file_commit_counts=file_commit_counts,
+        commits_analyzed=commits_analyzed,
+        commits_skipped=commits_skipped,
+    )