graphora-kg 0.2.0__py3-none-any.whl

graphora/__init__.py

@@ -0,0 +1,36 @@
+"""Graphora: a deterministic code knowledge-graph tool.
+
+Index a repository into FalkorDB with tree-sitter (no LLM), query blast
+radius for any change, mine git history into a risk memory, and review
+diffs grounded in real structure. Usable as a library, CLI, or MCP server.
+"""
+
+from __future__ import annotations
+
+import importlib
+
+__version__ = "0.2.0"
+
+_LAZY = {
+    "parse_code_file": "graphora.parser",
+    "extract_symbols_from_diff": "graphora.parser",
+    "ParsedFile": "graphora.parser",
+    "GraphStore": "graphora.store",
+    "open_store": "graphora.store",
+    "EmbeddedGraphStore": "graphora.embedded",
+    "index_repository": "graphora.indexer",
+    "update_files": "graphora.indexer",
+    "blast_radius": "graphora.blast",
+    "BlastRadius": "graphora.blast",
+    "mine_risk_memory": "graphora.risk",
+    "risk_report": "graphora.risk",
+}
+
+__all__ = list(_LAZY) + ["__version__"]
+
+
+def __getattr__(name: str):
+    module_name = _LAZY.get(name)
+    if module_name is None:
+        raise AttributeError(f"module 'graphora' has no attribute {name!r}")
+    return getattr(importlib.import_module(module_name), name)

graphora/benchmark.py

@@ -0,0 +1,135 @@
+"""Reproducible token-cost benchmark. Deterministic, zero LLM, zero network.
+
+For a set of query symbols (auto-picked highest-connectivity functions by
+default), compares the prompt context an AI reviewer would need under three
+strategies:
+
+1. whole-repo dump (the context-stuffing anti-pattern)
+2. equivalent-information file set: the changed files plus every file
+   containing a caller or covering test (what a reviewer must actually
+   read to learn what the blast radius states directly)
+3. graphora blast radius (facts read from the graph)
+
+Token counts use a fixed 4-chars-per-token heuristic so runs are
+reproducible on any machine with no tokenizer dependency.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from graphora.blast import blast_radius
+from graphora.indexer import collect_source_files
+from graphora.review import estimate_tokens
+from graphora.store import GraphStore
+
+
+@dataclass(frozen=True)
+class BenchmarkResult:
+    project: str
+    symbols: list[str]
+    file_count: int
+    repo_tokens: int
+    changed_files_tokens: int
+    blast_tokens: int
+    grounded_facts: dict[str, int]
+
+    @property
+    def saving_vs_repo(self) -> float:
+        if self.repo_tokens == 0:
+            return 0.0
+        return 100.0 * (1 - self.blast_tokens / self.repo_tokens)
+
+    @property
+    def saving_vs_changed_files(self) -> float:
+        if self.changed_files_tokens == 0:
+            return 0.0
+        return 100.0 * (1 - self.blast_tokens / self.changed_files_tokens)
+
+    def render(self) -> str:
+        lines = [
+            "# Graphora token-cost benchmark",
+            "",
+            f"Project: `{self.project}` ({self.file_count} indexed source files)",
+            f"Query symbols: {', '.join(f'`{s}`' for s in self.symbols)}",
+            "",
+            "| Context strategy | Prompt tokens | Relative |",
+            "| --- | ---: | ---: |",
+            f"| Whole-repo dump | {self.repo_tokens:,} | 100% |",
+            f"| Relevant files (changed + callers + tests) | {self.changed_files_tokens:,} |"
+            f" {100.0 * self.changed_files_tokens / max(1, self.repo_tokens):.1f}% |",
+            f"| **Graphora blast radius** | **{self.blast_tokens:,}** |"
+            f" **{100.0 * self.blast_tokens / max(1, self.repo_tokens):.2f}%** |",
+            "",
+            f"Savings: **{self.saving_vs_repo:.1f}%** vs whole-repo dump,"
+            f" **{self.saving_vs_changed_files:.1f}%** vs reading the relevant files.",
+            "",
+            "Grounded facts included in the blast-radius context (a repo dump has these",
+            "only implicitly, buried in the noise):",
+            "",
+            f"- caller relationships: {self.grounded_facts['callers']}",
+            f"- callee relationships: {self.grounded_facts['callees']}",
+            f"- covering tests identified: {self.grounded_facts['tests']}",
+            f"- risk-memory annotations: {self.grounded_facts['risk_annotations']}",
+            "",
+            "_Token counts use a fixed 4 chars/token heuristic; the benchmark is fully",
+            "deterministic (no LLM, no network) and reproducible with:_",
+            "`graphora benchmark <path> --symbols " + ",".join(self.symbols) + "`",
+        ]
+        return "\n".join(lines)
+
+
+def pick_symbols(store: GraphStore, count: int = 3) -> list[str]:
+    """Deterministically pick the most-connected non-test functions."""
+    return store.top_connected_symbols(count)
+
+
+def run_benchmark(
+    store: GraphStore,
+    root: str | Path,
+    symbols: list[str] | None = None,
+) -> BenchmarkResult:
+    root = Path(root).resolve()
+    files = collect_source_files(root)
+    repo_tokens = 0
+    contents: dict[str, str] = {}
+    for path in files:
+        text = path.read_text(encoding="utf-8", errors="replace")
+        rel = str(path.relative_to(root))
+        contents[rel] = text
+        repo_tokens += estimate_tokens(text)
+
+    symbols = symbols or pick_symbols(store)
+    if not symbols:
+        raise RuntimeError("No symbols to benchmark; index the repository first.")
+
+    radius = blast_radius(store, symbols)
+    blast_tokens = estimate_tokens(radius.to_context())
+
+    # Fair baseline: to learn what the blast radius states, a reviewer must
+    # read the changed files plus every file holding a caller or covering test.
+    changed_paths = {impact.path for impact in radius.symbols}
+    for impact in radius.symbols:
+        changed_paths.update(path for _, path, _ in impact.callers)
+        changed_paths.update(path for _, path, _ in impact.tests)
+    changed_files_tokens = sum(
+        estimate_tokens(contents[p]) for p in changed_paths if p in contents
+    )
+
+    grounded = {
+        "callers": sum(len(i.callers) for i in radius.symbols),
+        "callees": sum(len(i.callees) for i in radius.symbols),
+        "tests": sum(len(i.tests) for i in radius.symbols),
+        "risk_annotations": sum(1 for i in radius.symbols if i.fix_count > 0),
+    }
+
+    return BenchmarkResult(
+        project=store.project,
+        symbols=symbols,
+        file_count=len(files),
+        repo_tokens=repo_tokens,
+        changed_files_tokens=changed_files_tokens,
+        blast_tokens=blast_tokens,
+        grounded_facts=grounded,
+    )

graphora/blast.py

@@ -0,0 +1,142 @@
+"""Deterministic blast radius: pure Cypher, zero LLM.
+
+This replaces the old GraphRAG chat-based context building. For every
+changed symbol we read its definition, callers, callees, importers, and
+covering tests straight from the graph, each fact tagged with the edge
+confidence it came from.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+from graphora.parser import extract_files_from_diff, extract_symbols_from_diff
+from graphora.store import GraphStore
+
+
+@dataclass(frozen=True)
+class SymbolImpact:
+    name: str
+    kind: str
+    path: str
+    line: int
+    signature: str
+    risk_score: float
+    fix_count: int
+    last_broke_at: str
+    callers: list[tuple[str, str, str]] = field(default_factory=list)  # (name, path, confidence)
+    callees: list[tuple[str, str, str]] = field(default_factory=list)
+    tests: list[tuple[str, str, str]] = field(default_factory=list)
+    importers: list[str] = field(default_factory=list)
+
+
+@dataclass(frozen=True)
+class BlastRadius:
+    symbols: list[SymbolImpact]
+    changed_files: list[str]
+    unresolved: list[str]
+
+    def to_context(self) -> str:
+        """Compact, LLM-ready textual context (a few hundred tokens, not a repo dump)."""
+        lines: list[str] = ["Blast radius (from code graph, deterministic):"]
+        for impact in self.symbols:
+            lines.append(f"\n### {impact.name} ({impact.kind})")
+            lines.append(f"- defined at {impact.path}:{impact.line} `{impact.signature}`")
+            lines.append(_relation_line("callers", impact.callers))
+            lines.append(_relation_line("calls", impact.callees))
+            lines.append(_relation_line("tests", impact.tests))
+            if impact.importers:
+                lines.append(f"- imported by ({len(impact.importers)}): {', '.join(impact.importers)}")
+            if impact.fix_count:
+                lines.append(
+                    f"- RISK MEMORY: involved in {impact.fix_count} fix/revert commits"
+                    f" (last: {impact.last_broke_at}), risk score {impact.risk_score:.2f}"
+                )
+        if self.unresolved:
+            lines.append(f"\nSymbols not found in graph: {', '.join(self.unresolved)}")
+        return "\n".join(lines)
+
+    def to_dict(self) -> dict:
+        return {
+            "changed_files": self.changed_files,
+            "unresolved": self.unresolved,
+            "symbols": [
+                {
+                    "name": s.name,
+                    "kind": s.kind,
+                    "path": s.path,
+                    "line": s.line,
+                    "signature": s.signature,
+                    "risk_score": s.risk_score,
+                    "fix_count": s.fix_count,
+                    "last_broke_at": s.last_broke_at,
+                    "callers": [{"name": n, "path": p, "confidence": c} for n, p, c in s.callers],
+                    "callees": [{"name": n, "path": p, "confidence": c} for n, p, c in s.callees],
+                    "tests": [{"name": n, "path": p, "confidence": c} for n, p, c in s.tests],
+                    "importers": s.importers,
+                }
+                for s in self.symbols
+            ],
+        }
+
+
+def _relation_line(label: str, rows: list[tuple[str, str, str]]) -> str:
+    if not rows:
+        return f"- {label} (0): none"
+    rendered = ", ".join(f"{name} [{path}] ({confidence})" for name, path, confidence in rows)
+    return f"- {label} ({len(rows)}): {rendered}"
+
+
+def blast_radius(store: GraphStore, symbol_names: list[str]) -> BlastRadius:
+    """Compute the blast radius for a list of symbol names."""
+    impacts: list[SymbolImpact] = []
+    unresolved: list[str] = []
+    for name in symbol_names:
+        definitions = store.find_definitions(name)
+        if not definitions:
+            unresolved.append(name)
+            continue
+        for row in definitions:
+            impacts.append(_impact_for(store, row))
+    return BlastRadius(symbols=impacts, changed_files=[], unresolved=unresolved)
+
+
+def blast_radius_for_diff(store: GraphStore, diff: str) -> BlastRadius:
+    """Compute the blast radius for a unified diff."""
+    symbols = extract_symbols_from_diff(diff)
+    radius = blast_radius(store, symbols)
+    return BlastRadius(
+        symbols=radius.symbols,
+        changed_files=extract_files_from_diff(diff),
+        unresolved=radius.unresolved,
+    )
+
+
+def _impact_for(store: GraphStore, row: list) -> SymbolImpact:
+    name, kind, path, line, signature, risk_score, fix_count, last_broke_at = row
+    callers = sorted(store.callers_of(name, path))
+    callees = sorted(store.callees_of(name, path))
+    tests = sorted(store.tests_covering(name, path))
+    importers = sorted(store.importers_of_module(_module_hint(path), path))
+    return SymbolImpact(
+        name=name,
+        kind=kind,
+        path=path,
+        line=int(line),
+        signature=signature or "",
+        risk_score=float(risk_score or 0.0),
+        fix_count=int(fix_count or 0),
+        last_broke_at=str(last_broke_at or ""),
+        callers=callers,
+        callees=callees,
+        tests=tests,
+        importers=importers,
+    )
+
+
+def _module_hint(path: str) -> str:
+    stem = path.rsplit("/", 1)[-1]
+    for suffix in (".py", ".ts", ".tsx", ".js", ".jsx", ".go", ".java"):
+        if stem.endswith(suffix):
+            return stem[: -len(suffix)]
+    return stem

graphora/cli.py

@@ -0,0 +1,227 @@
+"""Graphora CLI: the code graph as a tool, not a GitHub App.
+
+Usage:
+  graphora index PATH [--project NAME]
+  graphora stats [--project NAME]
+  graphora blast SYMBOL [SYMBOL...] [--project NAME] [--json]
+  graphora review [--diff FILE | --git-range RANGE --repo PATH] [--project NAME] [--llm]
+  graphora risk mine PATH [--project NAME] [--since DATE]
+  graphora risk top [--project NAME] [--limit N]
+  graphora benchmark PATH [--project NAME] [--symbols A,B]
+  graphora serve-mcp [--project NAME]
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+from graphora import __version__
+from graphora.store import open_store
+
+
+def _store(args: argparse.Namespace):
+    return open_store(args.project, backend=args.backend, host=args.host, port=args.port)
+
+
+def cmd_index(args: argparse.Namespace) -> int:
+    from graphora.indexer import index_repository
+
+    def progress(stage: str, current: int, total: int, path: str) -> None:
+        sys.stderr.write(f"\r{stage}: {current}/{total} {path[:60]:<60}")
+        sys.stderr.flush()
+
+    root = Path(args.path).resolve()
+    project = args.project or root.name
+    store = open_store(project, backend=args.backend, host=args.host, port=args.port)
+    index_repository(root, project=project, store=store, on_progress=progress)
+    sys.stderr.write("\n")
+    print(json.dumps({"project": project, "graph": store.graph_name, "backend": store.backend, **store.stats()}, indent=2))
+    return 0
+
+
+def cmd_stats(args: argparse.Namespace) -> int:
+    print(json.dumps(_store(args).stats(), indent=2))
+    return 0
+
+
+def cmd_blast(args: argparse.Namespace) -> int:
+    from graphora.blast import blast_radius
+
+    radius = blast_radius(_store(args), args.symbols)
+    print(json.dumps(radius.to_dict(), indent=2) if args.json else radius.to_context())
+    return 0
+
+
+def cmd_review(args: argparse.Namespace) -> int:
+    from graphora.review import review_diff
+
+    if args.diff:
+        diff = Path(args.diff).read_text()
+    elif args.git_range:
+        repo = Path(args.repo or ".").resolve()
+        diff = subprocess.run(
+            ["git", "--no-pager", "diff", args.git_range],
+            cwd=repo, capture_output=True, text=True, check=True,
+        ).stdout
+    else:
+        diff = sys.stdin.read()
+    if not diff.strip():
+        print("No diff provided (use --diff FILE, --git-range RANGE, or stdin).", file=sys.stderr)
+        return 1
+    review = review_diff(_store(args), diff, model=args.model, use_llm=args.llm)
+    print(review.render())
+    return 0
+
+
+def cmd_risk_mine(args: argparse.Namespace) -> int:
+    from graphora.risk import mine_risk_memory
+
+    root = Path(args.path).resolve()
+    project = args.project or root.name
+    store = open_store(project, backend=args.backend, host=args.host, port=args.port)
+    stats = mine_risk_memory(store, root, since=args.since, max_commits=args.max_commits)
+    print(json.dumps(stats.__dict__, indent=2))
+    return 0
+
+
+def cmd_risk_top(args: argparse.Namespace) -> int:
+    from graphora.risk import risk_report
+
+    report = risk_report(_store(args), limit=args.limit)
+    if args.json:
+        print(json.dumps(report, indent=2))
+        return 0
+    if not report:
+        print("No risk memory yet. Run: graphora risk mine <repo-path>")
+        return 0
+    print(f"{'RISK':>6}  {'FIXES':>5}  {'CALLERS':>7}  {'LAST BROKE':<12} SYMBOL")
+    for row in report:
+        print(
+            f"{row['risk_score']:>6.2f}  {row['fix_count']:>5}  {row['caller_count']:>7}  "
+            f"{row['last_broke_at'][:10]:<12} {row['name']}  ({row['path']}:{row['line']})"
+        )
+    return 0
+
+
+def cmd_benchmark(args: argparse.Namespace) -> int:
+    from graphora.benchmark import run_benchmark
+
+    root = Path(args.path).resolve()
+    project = args.project or root.name
+    store = open_store(project, backend=args.backend, host=args.host, port=args.port)
+    symbols = [s for s in (args.symbols or "").split(",") if s] or None
+    result = run_benchmark(store, root, symbols=symbols)
+    print(result.render())
+    if args.output:
+        Path(args.output).write_text(result.render() + "\n")
+    return 0
+
+
+def cmd_serve_mcp(args: argparse.Namespace) -> int:
+    from graphora.mcp_server import serve
+
+    serve(project=args.project, host=args.host, port=args.port, backend=args.backend)
+    return 0
+
+
+def cmd_install_skill(args: argparse.Namespace) -> int:
+    from graphora.skills import install_skill, list_agents
+
+    if args.list:
+        print("\n".join(list_agents()))
+        return 0
+    agents = None if not args.agents or args.agents == ["all"] else args.agents
+    try:
+        written = install_skill(args.repo, agents)
+    except ValueError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+    print(json.dumps({"repo": str(Path(args.repo).resolve()), "written": written}, indent=2))
+    return 0
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="graphora", description="Deterministic code knowledge graph tool")
+    parser.add_argument("--version", action="version", version=f"graphora {__version__}")
+
+    common = argparse.ArgumentParser(add_help=False)
+    common.add_argument("--project", default=None, help="Graph project name (default: directory name)")
+    common.add_argument("--host", default="localhost", help="FalkorDB host")
+    common.add_argument("--port", type=int, default=6379, help="FalkorDB port")
+    common.add_argument(
+        "--backend",
+        choices=["auto", "falkordb", "embedded"],
+        default="auto",
+        help="Graph storage: FalkorDB server, embedded JSON (no Docker), or auto-detect (default)",
+    )
+
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    p_index = sub.add_parser("index", parents=[common], help="Index a repository into the graph (no LLM)")
+    p_index.add_argument("path")
+    p_index.set_defaults(func=cmd_index)
+
+    p_stats = sub.add_parser("stats", parents=[common], help="Show graph stats")
+    p_stats.set_defaults(func=cmd_stats, project_required=True)
+
+    p_blast = sub.add_parser("blast", parents=[common], help="Blast radius for symbols")
+    p_blast.add_argument("symbols", nargs="+")
+    p_blast.add_argument("--json", action="store_true")
+    p_blast.set_defaults(func=cmd_blast)
+
+    p_review = sub.add_parser("review", parents=[common], help="Review a diff grounded in the graph")
+    p_review.add_argument("--diff", help="Path to a unified diff file")
+    p_review.add_argument("--git-range", help="Git range, e.g. main...HEAD")
+    p_review.add_argument("--repo", help="Repo path for --git-range (default: cwd)")
+    p_review.add_argument("--llm", action="store_true", help="Use an LLM (REVIEW_MODEL env or --model)")
+    p_review.add_argument("--model", default=None)
+    p_review.set_defaults(func=cmd_review)
+
+    p_risk = sub.add_parser("risk", parents=[common], help="Risk memory commands")
+    risk_sub = p_risk.add_subparsers(dest="risk_command", required=True)
+    p_mine = risk_sub.add_parser("mine", parents=[common], help="Mine git fix/revert history into the graph")
+    p_mine.add_argument("path")
+    p_mine.add_argument("--since", default=None, help="e.g. '2 years ago'")
+    p_mine.add_argument("--max-commits", type=int, default=2000)
+    p_mine.set_defaults(func=cmd_risk_mine)
+    p_top = risk_sub.add_parser("top", parents=[common], help="Riskiest symbols")
+    p_top.add_argument("--limit", type=int, default=15)
+    p_top.add_argument("--json", action="store_true")
+    p_top.set_defaults(func=cmd_risk_top)
+
+    p_bench = sub.add_parser("benchmark", parents=[common], help="Reproducible token-cost benchmark")
+    p_bench.add_argument("path")
+    p_bench.add_argument("--symbols", help="Comma-separated symbols to query (default: auto-pick)")
+    p_bench.add_argument("--output", help="Write the report to a file")
+    p_bench.set_defaults(func=cmd_benchmark)
+
+    p_mcp = sub.add_parser("serve-mcp", parents=[common], help="Serve the graph as an MCP stdio server")
+    p_mcp.set_defaults(func=cmd_serve_mcp)
+
+    p_skill = sub.add_parser("install-skill", help="Install the Graphora skill/rule for AI coding agents")
+    p_skill.add_argument("agents", nargs="*", help="Agent names, or 'all' (default: all)")
+    p_skill.add_argument("--repo", default=".", help="Repository root to install into (default: cwd)")
+    p_skill.add_argument("--list", action="store_true", help="List supported agents")
+    p_skill.set_defaults(func=cmd_install_skill)
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if getattr(args, "project", None) is None and args.command not in {"index", "benchmark"}:
+        if args.command == "review" and args.repo:
+            args.project = Path(args.repo).resolve().name
+        elif args.command == "risk" and getattr(args, "path", None):
+            args.project = Path(args.path).resolve().name
+        else:
+            args.project = Path.cwd().name
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())