code-review-graph 1.8.2__tar.gz → 2.0.0__tar.gz

{code_review_graph-1.8.2 → code_review_graph-2.0.0}/.claude-plugin/marketplace.json

@@ -6,14 +6,14 @@
   },
   "metadata": {
     "description": "Persistent incremental knowledge graph for token-efficient, context-aware code reviews with Claude Code",
-    "version": "1.7.2"
+    "version": "2.0.0"
   },
   "plugins": [
     {
       "name": "code-review-graph",
       "source": "./",
       "description": "Persistent incremental knowledge graph for token-efficient, context-aware code reviews with Claude Code",
-      "version": "1.7.2",
+      "version": "2.0.0",
       "category": "development",
       "keywords": ["code-review", "knowledge-graph", "incremental", "tree-sitter", "mcp", "claude-code"]
     }

{code_review_graph-1.8.2 → code_review_graph-2.0.0}/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "code-review-graph",
   "description": "Persistent incremental knowledge graph for token-efficient, context-aware code reviews with Claude Code",
-  "version": "1.7.2",
+  "version": "2.0.0",
   "author": {
     "name": "Tirth Kanani",
     "email": "tirthkanani18@gmail.com",

{code_review_graph-1.8.2 → code_review_graph-2.0.0}/.gitignore

@@ -54,14 +54,16 @@ medium/
 
 # Superpowers brainstorm
 .superpowers/
+docs/superpowers/plans/
+docs/superpowers/specs/
 
-# Diagrams source files (PNGs are tracked, sources are not)
+# Diagrams (PNGs + script tracked, excalidraw sources gitignored)
 diagrams/*.excalidraw
 diagrams/export_pngs.mjs
-diagrams/generate_diagrams.py
 *.excalidraw
 
+# Evaluation test repos (third-party checkouts)
+evaluate/test_repos/
+
 # Draft/duplicate files
-evaluate/results?2.csv
-evaluate/results?3.csv
 docs/assets/marketing-diagram*

code_review_graph-2.0.0/PKG-INFO

@@ -0,0 +1,384 @@
+Metadata-Version: 2.4
+Name: code-review-graph
+Version: 2.0.0
+Summary: Persistent incremental knowledge graph for token-efficient, context-aware code reviews with Claude Code
+Project-URL: Homepage, https://github.com/tirth8205/code-review-graph
+Project-URL: Repository, https://github.com/tirth8205/code-review-graph
+Project-URL: Documentation, https://github.com/tirth8205/code-review-graph/blob/main/docs/INDEX.md
+Project-URL: Changelog, https://github.com/tirth8205/code-review-graph/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/tirth8205/code-review-graph/issues
+Author: Tirth
+License-Expression: MIT
+License-File: LICENSE
+Keywords: claude-code,code-review,knowledge-graph,mcp,tree-sitter
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: fastmcp<2,>=0.1.0
+Requires-Dist: mcp<2,>=1.0.0
+Requires-Dist: networkx<4,>=3.2
+Requires-Dist: tree-sitter-language-pack<1,>=0.3.0
+Requires-Dist: tree-sitter<1,>=0.23.0
+Requires-Dist: watchdog<6,>=4.0.0
+Provides-Extra: all
+Requires-Dist: igraph>=0.11.0; extra == 'all'
+Requires-Dist: matplotlib>=3.7.0; extra == 'all'
+Requires-Dist: numpy<3,>=1.26; extra == 'all'
+Requires-Dist: ollama>=0.1.0; extra == 'all'
+Requires-Dist: pyyaml>=6.0; extra == 'all'
+Requires-Dist: sentence-transformers<4,>=3.0.0; extra == 'all'
+Provides-Extra: communities
+Requires-Dist: igraph>=0.11.0; extra == 'communities'
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio<1,>=0.23; extra == 'dev'
+Requires-Dist: pytest<9,>=8.0; extra == 'dev'
+Requires-Dist: ruff<1,>=0.3.0; extra == 'dev'
+Provides-Extra: embeddings
+Requires-Dist: numpy<3,>=1.26; extra == 'embeddings'
+Requires-Dist: sentence-transformers<4,>=3.0.0; extra == 'embeddings'
+Provides-Extra: eval
+Requires-Dist: matplotlib>=3.7.0; extra == 'eval'
+Requires-Dist: pyyaml>=6.0; extra == 'eval'
+Provides-Extra: google-embeddings
+Requires-Dist: google-generativeai<1,>=0.8.0; extra == 'google-embeddings'
+Provides-Extra: wiki
+Requires-Dist: ollama>=0.1.0; extra == 'wiki'
+Description-Content-Type: text/markdown
+
+<h1 align="center">code-review-graph</h1>
+
+<p align="center">
+  <strong>Stop burning tokens. Start reviewing smarter.</strong>
+</p>
+
+<p align="center">
+  <a href="https://github.com/tirth8205/code-review-graph/stargazers"><img src="https://img.shields.io/github/stars/tirth8205/code-review-graph?style=flat-square" alt="Stars"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="MIT Licence"></a>
+  <a href="https://github.com/tirth8205/code-review-graph/actions/workflows/ci.yml"><img src="https://github.com/tirth8205/code-review-graph/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/python-3.10%2B-blue.svg?style=flat-square" alt="Python 3.10+"></a>
+  <a href="https://modelcontextprotocol.io/"><img src="https://img.shields.io/badge/MCP-compatible-green.svg?style=flat-square" alt="MCP"></a>
+  <a href="#"><img src="https://img.shields.io/badge/version-2.0.0-purple.svg?style=flat-square" alt="v2.0.0"></a>
+</p>
+
+<br>
+
+Claude Code re-reads your entire codebase on every task. `code-review-graph` fixes that. It builds a structural map of your code with [Tree-sitter](https://tree-sitter.github.io/tree-sitter/), tracks changes incrementally, and gives Claude precise context so it reads only what matters.
+
+<p align="center">
+  <img src="diagrams/diagram1_before_vs_after.png" alt="The Token Problem: 8.2x average token reduction across 6 real repositories" width="85%" />
+</p>
+
+---
+
+## Quick Start
+
+```bash
+pip install code-review-graph
+code-review-graph install          # auto-detects and configures all supported platforms
+code-review-graph build            # parse your codebase
+```
+
+One command sets up everything. `install` detects which AI coding tools you have and writes the correct MCP configuration for each one. Restart your editor/tool after installing.
+
+To target a specific platform:
+
+```bash
+code-review-graph install --platform cursor      # configure only Cursor
+code-review-graph install --platform claude-code  # configure only Claude Code
+```
+
+Requires Python 3.10+ and [uv](https://docs.astral.sh/uv/).
+
+### Supported Platforms
+
+| Platform | Config file | Auto-detected |
+|----------|-------------|:---:|
+| **Claude Code** | `.mcp.json` | Yes |
+| **Cursor** | `.cursor/mcp.json` | Yes |
+| **Windsurf** | `.windsurf/mcp.json` | Yes |
+| **Zed** | `.zed/settings.json` | Yes |
+| **Continue** | `.continue/config.json` | Yes |
+| **OpenCode** | `.opencode/config.json` | Yes |
+
+Then open your project and ask your AI assistant:
+
+```
+Build the code review graph for this project
+```
+
+The initial build takes ~10 seconds for a 500-file project. After that, the graph updates automatically on every file edit and git commit.
+
+---
+
+## How It Works
+
+Your repository is parsed into an AST with Tree-sitter, stored as a graph of nodes (functions, classes, imports) and edges (calls, inheritance, test coverage), then queried at review time to compute the minimal set of files Claude needs to read.
+
+<p align="center">
+  <img src="diagrams/diagram2_architecture_pipeline.png" alt="Architecture pipeline: Repository to Tree-sitter Parser to SQLite Graph to Blast Radius to Minimal Review Set" width="100%" />
+</p>
+
+<details>
+<summary><strong>Blast-radius analysis</strong></summary>
+<br>
+
+When a file changes, the graph traces every caller, dependent, and test that could be affected. This is the "blast radius" of the change. Claude reads only these files instead of scanning the whole project.
+
+<p align="center">
+  <img src="diagrams/diagram3_blast_radius.png" alt="Blast radius visualization showing how a change to login() propagates to callers, dependents, and tests" width="70%" />
+</p>
+
+</details>
+
+<details>
+<summary><strong>Incremental updates in &lt; 2 seconds</strong></summary>
+<br>
+
+On every git commit or file save, a hook fires. The graph diffs changed files, finds their dependents via SHA-256 hash checks, and re-parses only what changed. A 2,900-file project re-indexes in under 2 seconds.
+
+<p align="center">
+  <img src="diagrams/diagram4_incremental_update.png" alt="Incremental update flow: git commit triggers diff, finds dependents, re-parses only 5 files while 2,910 are skipped" width="90%" />
+</p>
+
+</details>
+
+<details>
+<summary><strong>18 supported languages</strong></summary>
+<br>
+
+Python, TypeScript/TSX, JavaScript, Vue, Go, Rust, Java, Scala, C#, Ruby, Kotlin, Swift, PHP, Solidity, C/C++, Dart, R, Perl
+
+Each language has full Tree-sitter grammar support for functions, classes, imports, call sites, inheritance, and test detection.
+
+</details>
+
+---
+
+## Benchmarks
+
+All numbers come from the automated evaluation runner against 6 real open-source repositories (13 commits total). Reproduce with `code-review-graph eval --all`. Raw data in [`evaluate/reports/summary.md`](evaluate/reports/summary.md).
+
+<details>
+<summary><strong>Token efficiency: 8.2x average reduction (naive vs graph)</strong></summary>
+<br>
+
+The graph replaces reading entire source files with a compact structural context covering blast radius, dependency chains, and test coverage gaps.
+
+| Repo | Commits | Avg Naive Tokens | Avg Graph Tokens | Reduction |
+|------|--------:|-----------------:|----------------:|----------:|
+| express | 2 | 693 | 983 | 0.7x |
+| fastapi | 2 | 4,944 | 614 | 8.1x |
+| flask | 2 | 44,751 | 4,252 | 9.1x |
+| gin | 3 | 21,972 | 1,153 | 16.4x |
+| httpx | 2 | 12,044 | 1,728 | 6.9x |
+| nextjs | 2 | 9,882 | 1,249 | 8.0x |
+| **Average** | **13** | | | **8.2x** |
+
+**Why express shows <1x:** For single-file changes in small packages, the graph context (metadata, edges, review guidance) can exceed the raw file size. The graph approach pays off on multi-file changes where it prunes irrelevant code.
+
+</details>
+
+<details>
+<summary><strong>Impact accuracy: 100% recall, 0.54 average F1</strong></summary>
+<br>
+
+The blast-radius analysis never misses an actually impacted file (perfect recall). It over-predicts in some cases, which is a conservative trade-off — better to flag too many files than miss a broken dependency.
+
+| Repo | Commits | Avg F1 | Avg Precision | Recall |
+|------|--------:|-------:|--------------:|-------:|
+| express | 2 | 0.667 | 0.50 | 1.0 |
+| fastapi | 2 | 0.584 | 0.42 | 1.0 |
+| flask | 2 | 0.475 | 0.34 | 1.0 |
+| gin | 3 | 0.429 | 0.29 | 1.0 |
+| httpx | 2 | 0.762 | 0.63 | 1.0 |
+| nextjs | 2 | 0.331 | 0.20 | 1.0 |
+| **Average** | **13** | **0.54** | **0.38** | **1.0** |
+
+</details>
+
+<details>
+<summary><strong>Build performance</strong></summary>
+<br>
+
+| Repo | Files | Nodes | Edges | Flow Detection | Search Latency |
+|------|------:|------:|------:|---------------:|---------------:|
+| express | 141 | 1,910 | 17,553 | 106ms | 0.7ms |
+| fastapi | 1,122 | 6,285 | 27,117 | 128ms | 1.5ms |
+| flask | 83 | 1,446 | 7,974 | 95ms | 0.7ms |
+| gin | 99 | 1,286 | 16,762 | 111ms | 0.5ms |
+| httpx | 60 | 1,253 | 7,896 | 96ms | 0.4ms |
+
+</details>
+
+<details>
+<summary><strong>Limitations and known weaknesses</strong></summary>
+<br>
+
+- **Small single-file changes:** Graph context can exceed naive file reads for trivial edits (see express results above). The overhead is the structural metadata that enables multi-file analysis.
+- **Search quality (MRR 0.35):** Keyword search finds the right result in the top-4 for most queries, but ranking needs improvement. Express queries return 0 hits due to module-pattern naming.
+- **Flow detection (33% recall):** Only reliably detects entry points in Python repos (fastapi, httpx) where framework patterns are recognized. JavaScript and Go flow detection needs work.
+- **Precision vs recall trade-off:** Impact analysis is deliberately conservative. It flags files that *might* be affected, which means some false positives in large dependency graphs.
+
+</details>
+
+---
+
+## Usage
+
+<details>
+<summary><strong>Slash commands</strong></summary>
+<br>
+
+| Command | Description |
+|---------|-------------|
+| `/code-review-graph:build-graph` | Build or rebuild the code graph |
+| `/code-review-graph:review-delta` | Review changes since last commit |
+| `/code-review-graph:review-pr` | Full PR review with blast-radius analysis |
+
+</details>
+
+<details>
+<summary><strong>CLI reference</strong></summary>
+<br>
+
+```bash
+code-review-graph install          # Auto-detect and configure all platforms
+code-review-graph install --platform <name>  # Target a specific platform
+code-review-graph build            # Parse entire codebase
+code-review-graph update           # Incremental update (changed files only)
+code-review-graph status           # Graph statistics
+code-review-graph watch            # Auto-update on file changes
+code-review-graph visualize        # Generate interactive HTML graph
+code-review-graph wiki             # Generate markdown wiki from communities
+code-review-graph detect-changes   # Risk-scored change impact analysis
+code-review-graph register <path>  # Register repo in multi-repo registry
+code-review-graph unregister <id>  # Remove repo from registry
+code-review-graph repos            # List registered repositories
+code-review-graph eval             # Run evaluation benchmarks
+code-review-graph serve            # Start MCP server
+```
+
+</details>
+
+<details>
+<summary><strong>MCP tools</strong></summary>
+<br>
+
+Claude uses these automatically once the graph is built.
+
+| Tool | Description |
+|------|-------------|
+| `build_or_update_graph_tool` | Build or incrementally update the graph |
+| `get_impact_radius_tool` | Blast radius of changed files |
+| `get_review_context_tool` | Token-optimised review context with structural summary |
+| `query_graph_tool` | Callers, callees, tests, imports, inheritance queries |
+| `semantic_search_nodes_tool` | Search code entities by name or meaning |
+| `embed_graph_tool` | Compute vector embeddings for semantic search |
+| `list_graph_stats_tool` | Graph size and health |
+| `get_docs_section_tool` | Retrieve documentation sections |
+| `find_large_functions_tool` | Find functions/classes exceeding a line-count threshold |
+| `list_flows_tool` | List execution flows sorted by criticality |
+| `get_flow_tool` | Get details of a single execution flow |
+| `get_affected_flows_tool` | Find flows affected by changed files |
+| `list_communities_tool` | List detected code communities |
+| `get_community_tool` | Get details of a single community |
+| `get_architecture_overview_tool` | Architecture overview from community structure |
+| `detect_changes_tool` | Risk-scored change impact analysis for code review |
+| `refactor_tool` | Rename preview, dead code detection, suggestions |
+| `apply_refactor_tool` | Apply a previously previewed refactoring |
+| `generate_wiki_tool` | Generate markdown wiki from communities |
+| `get_wiki_page_tool` | Retrieve a specific wiki page |
+| `list_repos_tool` | List registered repositories |
+| `cross_repo_search_tool` | Search across all registered repositories |
+
+**MCP Prompts** (5 workflow templates):
+`review_changes`, `architecture_map`, `debug_issue`, `onboard_developer`, `pre_merge_check`
+
+</details>
+
+---
+
+## Features
+
+| Feature | Details |
+|---------|---------|
+| **Incremental updates** | Re-parses only changed files. Subsequent updates complete in under 2 seconds. |
+| **18 languages** | Python, TypeScript/TSX, JavaScript, Vue, Go, Rust, Java, Scala, C#, Ruby, Kotlin, Swift, PHP, Solidity, C/C++, Dart, R, Perl |
+| **Blast-radius analysis** | Shows exactly which functions, classes, and files are affected by any change |
+| **Auto-update hooks** | Graph updates on every file edit and git commit without manual intervention |
+| **Semantic search** | Optional vector embeddings via sentence-transformers, Google Gemini, or MiniMax |
+| **Interactive visualisation** | D3.js force-directed graph with edge-type toggles and search |
+| **Local storage** | SQLite file in `.code-review-graph/`. No external database, no cloud dependency. |
+| **Watch mode** | Continuous graph updates as you work |
+| **Execution flows** | Trace call chains from entry points, sorted by criticality |
+| **Community detection** | Cluster related code via Leiden algorithm or file grouping |
+| **Architecture overview** | Auto-generated architecture map with coupling warnings |
+| **Risk-scored reviews** | `detect_changes` maps diffs to affected functions, flows, and test gaps |
+| **Refactoring tools** | Rename preview, dead code detection, community-driven suggestions |
+| **Wiki generation** | Auto-generate markdown wiki from community structure |
+| **Multi-repo registry** | Register multiple repos, search across all of them |
+| **MCP prompts** | 5 workflow templates: review, architecture, debug, onboard, pre-merge |
+| **Full-text search** | FTS5-powered hybrid search combining keyword and vector similarity |
+
+<details>
+<summary><strong>Configuration</strong></summary>
+<br>
+
+To exclude paths from indexing, create a `.code-review-graphignore` file in your repository root:
+
+```
+generated/**
+*.generated.ts
+vendor/**
+node_modules/**
+```
+
+Optional dependency groups:
+
+```bash
+pip install code-review-graph[embeddings]          # Local vector embeddings (sentence-transformers)
+pip install code-review-graph[google-embeddings]   # Google Gemini embeddings
+pip install code-review-graph[communities]         # Community detection (igraph)
+pip install code-review-graph[eval]                # Evaluation benchmarks (matplotlib)
+pip install code-review-graph[wiki]                # Wiki generation with LLM summaries (ollama)
+pip install code-review-graph[all]                 # All optional dependencies
+```
+
+</details>
+
+---
+
+## Contributing
+
+```bash
+git clone https://github.com/tirth8205/code-review-graph.git
+cd code-review-graph
+python3 -m venv .venv && source .venv/bin/activate
+pip install -e ".[dev]"
+pytest
+```
+
+<details>
+<summary><strong>Adding a new language</strong></summary>
+<br>
+
+Edit `code_review_graph/parser.py` and add your extension to `EXTENSION_TO_LANGUAGE` along with node type mappings in `_CLASS_TYPES`, `_FUNCTION_TYPES`, `_IMPORT_TYPES`, and `_CALL_TYPES`. Include a test fixture and open a PR.
+
+</details>
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).
+
+<p align="center">
+<br>
+<code>pip install code-review-graph && code-review-graph install</code><br>
+<sub>Works with Claude Code, Cursor, Windsurf, Zed, Continue, and OpenCode</sub>
+</p>