codegraph-engine 3.0.0__tar.gz → 3.0.1__tar.gz

{codegraph_engine-3.0.0/src/codegraph_engine.egg-info → codegraph_engine-3.0.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codegraph-engine
-Version: 3.0.0
+Version: 3.0.1
 Summary: Deep deterministic repository intelligence for AI coding agents (code, dependencies, databases, and runtime observations)
 Author: CodeGraph contributors
 License-Expression: MIT
@@ -38,35 +38,36 @@ Dynamic: license-file
 <h1 align="center">CodeGraph MCP: Full-Stack Knowledge Graph & Semantic Intelligence for AI Coding Agents</h1>
 
 <p align="center">
-  <strong>Zero-Hallucination, AST-Verified Codebase Intelligence • Sub-15ms Live Watcher • 75% Context Token Reduction</strong><br>
-  <em>The ultimate Model Context Protocol (MCP) server for Cursor, Claude Code, GitHub Copilot, Antigravity, Cline, Windsurf & Codex.</em>
+  <strong>Deterministic AST-Verified Codebase Intelligence • Sub-15ms Live Watcher • Context Window Optimization</strong><br>
+  <em>Deterministic Model Context Protocol (MCP) server for Cursor, Claude Code, GitHub Copilot, Antigravity, Cline, Windsurf & Codex.</em>
 </p>
 
 <p align="center">
-  <a href="https://github.com/raghuram/CODE_GRAPH_MCP"><img src="https://img.shields.io/github/stars/raghuram/CODE_GRAPH_MCP?style=for-the-badge&logo=github&color=gold" alt="GitHub Stars" /></a>
+  <a href="https://github.com/raghurammrsd/CODE_GRAPH_MCP"><img src="https://img.shields.io/github/stars/raghurammrsd/CODE_GRAPH_MCP?style=for-the-badge&logo=github&color=gold" alt="GitHub Stars" /></a>
   <a href="https://pypi.org/project/codegraph-engine/"><img src="https://img.shields.io/badge/pypi-codegraph--engine-3776AB.svg?style=for-the-badge&logo=pypi" alt="PyPI: codegraph-engine" /></a>
-  <a href="src/codegraph/mcp/server.py"><img src="https://img.shields.io/badge/MCP-70%20Verified%20Tools-2ea043.svg?style=for-the-badge" alt="MCP Tools: 70 verified" /></a>
-  <a href="tests/"><img src="https://img.shields.io/badge/pytest-980%2B%20passed%20(100%25)-brightgreen.svg?style=for-the-badge&logo=pytest" alt="Tests: 980+ passed" /></a>
+  <a href="src/codegraph/mcp/server.py"><img src="https://img.shields.io/badge/MCP-97%20Verified%20Tools-2ea043.svg?style=for-the-badge" alt="MCP Tools: 97 verified" /></a>
+  <a href="tests/"><img src="https://img.shields.io/badge/pytest-1062%20passed%20(100%25)-brightgreen.svg?style=for-the-badge&logo=pytest" alt="Tests: 1062 passed" /></a>
   <a href="pyproject.toml"><img src="https://img.shields.io/badge/ruff-0%20errors-success.svg?style=for-the-badge" alt="Ruff: 0 errors" /></a>
-  <a href="src/codegraph/"><img src="https://img.shields.io/badge/mypy-strict%20(120%20files)-blue.svg?style=for-the-badge" alt="Mypy: strict" /></a>
-  <a href="https://github.com/raghuram/CODE_GRAPH_MCP/stargazers"><img src="https://img.shields.io/badge/Star%20on%20GitHub-loved%20by%20agents-yellow?style=for-the-badge" alt="Star us on GitHub" /></a>
+  <a href="src/codegraph/"><img src="https://img.shields.io/badge/mypy-strict%20(134%20files)-blue.svg?style=for-the-badge" alt="Mypy: strict" /></a>
 </p>
 
-> **Love CodeGraph MCP?** Please consider giving us a **Star on GitHub**! It helps AI developers discover deterministic, hallucination-free code intelligence for their pair programming agents.
+> CodeGraph MCP provides deterministic, evidence-backed repository intelligence through Abstract Syntax Trees, framework router hierarchies, database lineage, and runtime observation across 25 production pillars and 97 FastMCP tools.
 
 <p align="center">
   <a href="https://raghurammrsd.github.io/CODE_GRAPH_MCP/"><strong>Documentation Site</strong></a> •
-  <a href="https://pypi.org/project/codegraph-engine/3.0.0/"><strong>PyPI Package</strong></a> •
+  <a href="https://pypi.org/project/codegraph-engine/3.0.1/"><strong>PyPI Package (v3.0.1)</strong></a> •
   <a href="#overview"><strong>Overview</strong></a> •
+  <a href="#the-25-production-pillars-of-codegraph-mcp"><strong>25 Pillars</strong></a> •
   <a href="#interactive-web-dashboard--vs-code-extension"><strong>Web Dashboard & VS Code</strong></a> •
-  <a href="#the-three-pillars-of-codegraph-mcp"><strong>The Three Pillars</strong></a> •
+  <a href="#multi-language-real-world-benchmark-results"><strong>Multi-Language Benchmarks</strong></a> •
+  <a href="#roblox--luau-intelligence-codegraph-roblox"><strong>Roblox & Luau</strong></a> •
   <a href="#2-quickstart-30-second-setup"><strong>Quickstart</strong></a> •
   <a href="#4-real-world-cli-outputs"><strong>CLI Outputs</strong></a> •
   <a href="#6-database-intelligence"><strong>Database Intelligence</strong></a> •
   <a href="#7-zero-friction-runtime-intelligence--static-reconciliation"><strong>Runtime Evidence</strong></a> •
   <a href="#8-git-aware-repository-intelligence"><strong>Git Intelligence</strong></a> •
   <a href="#measured-performance--real-metrics-benchmark"><strong>Benchmarks</strong></a> •
-  <a href="docs/agent-brain.md"><strong>70-Tool Reference</strong></a> •
+  <a href="docs/agent-brain.md"><strong>97-Tool Reference</strong></a> •
   <a href="https://github.com/raghurammrsd/CODE_GRAPH_MCP"><strong>GitHub</strong></a>
 </p>
 
@@ -92,10 +93,10 @@ When AI coding agents (such as Claude Code, Cursor, or Antigravity) explore comp
        ┌─────────────────────────────────────────────────────────────┐
        │                   CODEGRAPH MCP ENGINE                      │
        ├──────────────────────────────┬──────────────────────────────┤
-       │  AST Code Relationships      │  Framework Route Hierarchy   │
-       │  (Callers, Callees, DI)      │  (FastAPI, Django, Express)  │
+       │  AST Code Relationships      │  Framework & Network Graph   │
+       │  (Callers, Callees, DI)      │  (FastAPI, Django, Roblox)   │
        ├──────────────────────────────┼──────────────────────────────┤
-       │  Database Lineage & Schemas  │  Non-Invasive Dev Tracing    │
+       │  Database & DataStore Graph  │  Non-Invasive Dev Tracing    │
        │  (SQLAlchemy, Prisma, ORM)   │  (HTTP metrics, exceptions)  │
        └──────────────────────────────┴──────────────────────────────┘
                                       │
@@ -105,13 +106,13 @@ When AI coding agents (such as Claude Code, Cursor, or Antigravity) explore comp
 
 ### Core Architecture Capabilities
 
-- **Deterministic Evidence Guarantee**: Every returned entity and relationship is statically verified via Abstract Syntax Trees or explicitly flagged as `UNKNOWN` / `POSSIBLE`. CodeGraph MCP provides deterministic, evidence-backed repository intelligence across application code, databases, runtime behavior, and Git history.
+- **Deterministic Evidence Guarantee**: Every returned entity and relationship is statically verified via Abstract Syntax Trees (`AST_VERIFIED`, `FRAMEWORK_VERIFIED`, `ROJO_VERIFIED`) or explicitly flagged as `UNKNOWN` / `POSSIBLE`. CodeGraph MCP provides deterministic, evidence-backed repository intelligence across application code, databases, runtime behavior, and Git history.
 - **Sub-5ms Freshness Verification**: Monotonic commit tracking validates `git rev-parse HEAD` and porcelain status instantly, avoiding full-tree re-indexing on unchanged codebases.
 - **Context Window Optimization**: Yields 65% to 85% token reduction by returning structured, bounded source slices rather than entire file dumps.
 - **Zero-Friction Dev Interception (`codegraph run`)**: Wraps local development servers (e.g., `codegraph run npm run dev`, `codegraph run uvicorn main:app`) to capture real HTTP routes, latencies, and stack traces without application code changes.
 - **Multi-Agent Setup (`codegraph install`)**: Automatically detects, configures, and verifies integrations for Claude Code, Cursor, Antigravity, and Cline.
 
-> **Supported Languages & Frameworks:** Python (`FastAPI`, `Flask`, `Django`, `SQLAlchemy`, `PyTorch`, `Celery`, `LangChain`, `LlamaIndex`, `Ray`, `pytest`) and TypeScript / JavaScript (`.ts`, `.tsx`, `.js`, `.jsx`, `React`, `Next.js`, `NestJS`, `Express.js`, `Prisma`, `Drizzle`, `Mongoose`).
+> **Supported Languages & Frameworks:** Python (`FastAPI`, `Flask`, `Django`, `SQLAlchemy`, `PyTorch`, `Celery`, `LangChain`, `LlamaIndex`, `Ray`, `pytest`), TypeScript / JavaScript (`.ts`, `.tsx`, `.js`, `.jsx`, `React`, `Next.js`, `NestJS`, `Express.js`, `Prisma`, `Drizzle`, `Mongoose`), and Roblox / Luau (`.lua`, `.luau`, `Rojo`, `Knit`, `Flamework / roblox-ts`, `DataStoreService`, `ProfileService`).
 
 <p align="center">
   <img src="docs/assets/codegraph_full_architecture.svg" alt="CodeGraph MCP Comprehensive Full-Stack Architecture Pipeline" width="950" />
@@ -123,25 +124,27 @@ When AI coding agents (such as Claude Code, Cursor, or Antigravity) explore comp
 
 ## Measured Performance & Real Metrics Benchmark
 
-CodeGraph MCP has been systematically benchmarked across 50 real-world engineering tasks and enterprise repositories to quantify token consumption, hallucination suppression, and investigation latency:
-
-| Performance Metric | Unassisted AI Agents (Raw Grep / File Dumps) | CodeGraph MCP Engine | Real Improvement |
-| :--- | :---: | :---: | :---: |
-| **Hallucination / Unsupported Claims** | 18.5% – 34.0% false assumptions | **0.0%** (AST / Framework verified) | **100% eliminated** |
-| **Context Window Consumption** | 4,500 – 18,200 tokens / task | **350 – 620 tokens / task** | **72% – 85% token savings** |
-| **Exploration Tool Calls** | 164 total tool calls | **71 tool calls** | **57% fewer tool calls** |
-| **Investigation Latency** | 14.8s average exploration | **4.8s total exploration** | **68% faster investigation** |
-| **Incremental File Reindexing** | Full scan required (1.2s – 6.5s) | **< 15ms per file (`codegraph watch`)** | **98% faster live sync** |
-| **Repository Freshness Check** | 450ms – 2,100ms disk stat checks | **< 5ms (Git commit fast path)** | **99% faster checks** |
-| **Symbol Grounding & Resolution** | Manual file scanning | **< 2ms in-memory SQLite** | **Sub-millisecond resolution** |
-| **Automated Test Suite Quality** | — | **980+ passed tests (100% pass rate)** | **Zero regressions** |
+Performance and retrieval accuracy are verified across two empirical evaluation suites: a **32-task agent navigation simulation** ([`src/codegraph/tool_selection_eval.py`](src/codegraph/tool_selection_eval.py)) measuring agent trajectory efficiency, and a **50-task diagnostic benchmark** ([`benchmarks/run_v21_eval.py`](benchmarks/run_v21_eval.py)) evaluating multi-file recall, coverage, and context boundaries:
+
+| Performance Metric | Unassisted AI Agents (Raw Grep / File Dumps) | CodeGraph MCP Engine | Measured Result | Evaluation Suite |
+| :--- | :---: | :---: | :---: | :---: |
+| **Unsupported Relationship Claims** | 18.5% – 34.0% false edges | **0.0%** (AST / Framework verified) | **100% eliminated** | 32-Task Navigation Eval |
+| **Exploration Tool Calls** | 164 total tool calls (~5.1 / task) | **71 tool calls** (~2.2 / task) | **56.7% fewer tool calls** | 32-Task Navigation Eval |
+| **Context Consumption (Prompt Tokens)** | 3,000 – 12,000+ tokens / task | **~510 tokens** avg payload | **72% – 85% token savings** | 32-Task Navigation Eval |
+| **Direct File Token Reduction** | Full file reads required | Bounded slices via `get_file` | **41.8% token reduction** | 50-Task Retrieval Benchmark |
+| **Task Coverage & Symbol Recall** | Baseline lexical match | **88.0% coverage / 61.9% recall** | **Verified ground truth** | 50-Task Retrieval Benchmark |
+| **Incremental File Reindexing (Live)** | Full rescan required (1.2s – 6.5s) | **< 15ms per file (`codegraph watch`)** | **In-memory cache patch** | Live OS Kernel Watcher |
+| **Single-File Full Re-index (Cold CLI)** | Full rescan required (4.4s) | **3.665s** (2,504 files) | **16.9% faster** | 4-Tier Stress Benchmark |
+| **Repository Freshness Check** | 450ms – 2,100ms disk stat checks | **< 5ms (Git commit fast path)** | **99% faster checks** | Git Fast Path Check |
+| **Symbol Grounding & Resolution** | Manual file scanning | **< 2ms in-memory SQLite** | **Sub-millisecond resolution** | SQLite Indexed Lookup |
+| **Automated Test Suite Quality** | — | **980+ passed tests (100% pass rate)** | **Zero regressions** | Pytest CI/CD Suite |
 
 <p align="center">
   <img src="docs/assets/performance_comparison.svg" alt="CodeGraph MCP — Measured Context & Exploration Efficiency" width="850" />
 </p>
 
 <p align="center">
-  <img src="docs/assets/large_repo_scaling.svg" alt="CodeGraph MCP — Large Repository Scaling Across 100k, 500k, 1M LOC" width="850" />
+  <img src="docs/assets/large_repo_scaling.svg" alt="CodeGraph MCP — Large Repository Scaling up to 2,504 Files / ~120k LOC" width="850" />
 </p>
 
 ---
@@ -198,6 +201,14 @@ CodeGraph MCP natively parses AI/ML architectures and agent pipelines into deter
 - **LangChain LCEL Pipelines**: Tracks pipe syntax (`prompt | model | parser`) as executable pipeline dataflow (`CHAINS_TO`).
 - **Distributed Ray Tasks**: Detects `@ray.remote` actor decorators and `task.remote()` invocations (`DISPATCHES_RAY_TASK`).
 
+### Roblox & Luau Intelligence (`codegraph roblox`)
+First-class repository intelligence for Roblox game architectures (`.lua`, `.luau`, and `roblox-ts`):
+- **Native Luau Parser**: Extracts local/global functions, colon methods (`function Service:Init()`), dot methods (`function Module.Func()`), table-assigned methods (`Service.Method = function(...)`), module table returns, `return table.freeze(Module)`, and Luau `type` / `export type` declarations.
+- **Rojo DataModel Mapping (`default.project.json`)**: Maps virtual Roblox paths (`ReplicatedStorage`, `ServerScriptService`, `StarterPlayerScripts`, `Packages`, `script.Parent`) to physical files on disk with `ROJO_VERIFIED` provenance (`REQUIRES_MODULE`).
+- **Client $\leftrightarrow$ Server Network Graph**: Traces `RemoteEvent:FireServer(...)` $\to$ `OnServerEvent:Connect(handler)` and `RemoteFunction:InvokeServer(...)` $\to$ `OnServerInvoke = handler` through canonical Remote nodes via `CLIENT_DISPATCHES_REMOTE` and `SERVER_HANDLES_REMOTE`.
+- **Knit, Flamework & Persistence**: Tracks `Knit.CreateService` / `Knit.GetService`, Flamework `@Service` / `@Controller` / `Dependency<T>`, and `DataStoreService:GetDataStore` (`GetAsync`, `SetAsync`, `UpdateAsync`) + `ProfileService` (`CONFIGURES_PERSISTENCE`, `READS_PERSISTENCE`, `WRITES_PERSISTENCE`).
+- **Dedicated CLI Inspection**: `codegraph roblox remotes`, `codegraph roblox modules`, and `codegraph roblox routes`.
+
 ### Pillar 1: The Unified Full-Stack Bridge (`codegraph api-drift`)
 Bridges frontend client fetchers and backend API handlers across languages without manual tracing:
 - **Client Route Extraction**: Statically parses React / Next.js / Vue / Nuxt `fetch<T>()`, `axios.get<T>()`, `useSWR<T>()`, `useQuery<T>()`, and `$fetch<T>()` alongside TypeScript request/response interfaces.
@@ -218,32 +229,165 @@ Zero-heat, real-time file system monitoring with sub-15ms incremental reindexing
 - **Sub-15ms Incremental Reindexing**: Bypasses full-disk traversal; only re-indexes modified files (`Indexer.reindex_paths`) and advances generation counters.
 - **Instant In-Memory Cache Busting**: Automatically purges LRU memory caches (`_PARSE_CACHE`, `_GRAPH_CACHE`) and SQLite context caches upon file mutation.
 
-## 1. What's New in v3.0.0 (Git-Aware Intelligence)
+## 1. What's New in v3.0.1: 25 Production Pillars & 97 Verified FastMCP Tools
+
+Version `3.0.1` represents the definitive production release of CodeGraph MCP, bringing together **25 architectural pillars**, **97 verified FastMCP tools** (100% audit pass rate), **sub-millisecond Compressed Sparse Row (CSR) binary traversal**, and **deep multi-language intelligence** across Python, TypeScript/JavaScript, Roblox/Luau, Go, Rust, Java, and C/C++.
+
+```mermaid
+flowchart TD
+    subgraph ClientLayer["AI Coding Agents & Editors"]
+        Agent["Claude Code / Cursor / Antigravity / Cline"]
+        VSCode["VS Code Extension / CodeLens"]
+        WebUI["Web UI Dashboard (127.0.0.1:8765)"]
+    end
+
+    subgraph ProtocolLayer["Protocol & Interception Layer"]
+        FastMCP["FastMCP Server (97 Tools, stdio & SSE)"]
+        LSP["LSP JSON-RPC Bridge (:codegraph lsp)"]
+        DevInterceptor["Runtime Interceptor (codegraph run)"]
+        OTLP["OTLP HTTP Trace Receiver (:4318)"]
+    end
+
+    subgraph CoreEngine["CodeGraph v3.0.1 Engine Core (25 Pillars)"]
+        CSR["Compressed Sparse Row (CSR) Graph"]
+        AST["Multi-Language AST Scanner (7 Languages)"]
+        DI["Dependency Injection & Route Composer"]
+        DB["Database Lineage & ORM Schema Engine"]
+        Impact["PR Blast Radius & Impact Analyzer"]
+        Patch["Semantic Patch & Safe Refactoring"]
+        Security["Interprocedural Taint & CVE Engine"]
+        MultiAgent["Agent Memory (FTS5) & File Lease Locks"]
+    end
+
+    subgraph StorageLayer["Deterministic Storage (Zero-Vector, Sub-5ms)"]
+        SQLite[".codegraph.sqlite3 (WAL Mode, Normalized Schema)"]
+        MemoryDB[".codegraph/memory.sqlite3 (Agent Experience FTS5)"]
+        RuntimeDB[".codegraph/runtime.sqlite3 (Live Traces)"]
+    end
+
+    Agent -->|JSON-RPC Tools| FastMCP
+    VSCode -->|stdio LSP| LSP
+    WebUI -->|REST / SSE| FastMCP
+    FastMCP --> CSR
+    FastMCP --> AST
+    FastMCP --> DI
+    FastMCP --> DB
+    FastMCP --> Impact
+    FastMCP --> Patch
+    FastMCP --> Security
+    FastMCP --> MultiAgent
+    DevInterceptor --> RuntimeDB
+    OTLP --> RuntimeDB
+    CoreEngine --> SQLite
+    MultiAgent --> MemoryDB
+```
+
+---
+
+### The 25 Production Pillars of CodeGraph MCP
+
+CodeGraph is organized into 25 purpose-built architectural pillars designed to eliminate hallucinations, prevent broken contracts, and optimize LLM context:
 
-Version `3.0.0` introduces compiler-grade **Git-Aware Repository Intelligence**, allowing AI agents and CI/CD pipelines to understand how code evolves across branches, commits, and working tree edits:
+```mermaid
+flowchart LR
+    subgraph Intelligence["Static & Dynamic Intelligence"]
+        P1["1. Multi-Lang AST"]
+        P2["2. CSR Binary Graph"]
+        P3["3. 97 FastMCP Tools"]
+        P4["4. HTTP & RPC Routes"]
+        P5["5. API Contract Drift"]
+        P6["6. Dependency Injection"]
+        P7["7. Database Lineage"]
+        P8["8. Blast Radius Impact"]
+        P9["9. Live Watcher"]
+    end
+    subgraph Safety["Safety & Refactoring"]
+        P10["10. Safe Refactoring"]
+        P11["11. Agent Leases"]
+        P12["12. Dead Code Reachability"]
+        P13["13. Taint Security"]
+        P14["14. CVE Supply Chain"]
+        P15["15. Repo Federation"]
+        P16["16. Test Scaffolding"]
+        P17["17. LSP Bridge"]
+    end
+    subgraph Operations["Lifecycle & Operations"]
+        P18["18. Agent Memory"]
+        P19["19. Git Diff Freshness"]
+        P20["20. Self-Healing Index"]
+        P21["21. SWE-bench Sandbox"]
+        P22["22. PR Review Bot"]
+        P23["23. Web UI Dashboard"]
+        P24["24. Windows Portability"]
+        P25["25. Universal Installer"]
+    end
+```
 
-| Capability | CLI Command | MCP Tool | How It Solves Agent Failure Modes |
-| :--- | :--- | :--- | :--- |
-| **Working-Tree Freshness** | `codegraph git-state` | `get_git_state` | Tracks branch, HEAD vs indexed commit, modified/staged files with sub-millisecond status caching. Surfaces `CLEAN`, `DIRTY`, `STALE`, `REINDEXING`, `ERROR`. |
-| **Structural AST Diff** | `codegraph git-diff [base] [head]` | `compare_git` | Semantic diff across Git revisions: identifies added/removed/modified functions, changed parameter signatures, and affected routes—not merely raw line diffs. |
-| **Deep Impact & Visual Tree** | `codegraph git-impact --tree` | `get_change_impact` | Traverses downstream callers, callees, framework routes, DB writers, and affected test suites with token-bounded ranking and terminal ASCII tree visualization. |
-| **Semantic Merge Conflicts** | `codegraph git-conflicts [base] [head]` | `detect_semantic_conflicts` | Detects silent contract breaks before merge: invoking functions or route handlers that were deleted or modified on the target branch. |
-| **Context Freshness Gate** | `codegraph check-freshness [task]` | `check_context_freshness` | Determines whether previously compiled context remains `VALID`, `PARTIALLY_STALE`, or `STALE` without re-running full graph queries if unrelated files changed. |
-| **Deterministic Symbol History** | `codegraph symbol-history <sym>` | `trace_symbol_history` | Reconstructs the exact commit lifecycle of any symbol (introduced, modified, moved, renamed, or deleted) with confidence labels. |
+| # | Pillar Name | Primary MCP Tools | Key Capabilities & Architecture |
+|---|---|---|---|
+| **1** | **Multi-Language AST Engine** | `resolve_symbol`, `get_symbol`, `batch_get_symbols` | Native Tree-Sitter & Python AST parsers for 7 languages (Python, TS/JS, Roblox/Luau, Go, Rust, Java, C/C++). Sub-60ms parse speed. |
+| **2** | **CSR Binary Graph Traversal** | `fast_graph_path`, `get_call_graph` | Compressed Sparse Row (`graph_csr.py`) in-memory binary format enabling microsecond BFS/DFS pathfinding across 100,000+ edges. |
+| **3** | **97-Tool FastMCP Registry** | 97 registered FastMCP endpoints | 100% verified tool suite spanning symbols, callers, routes, databases, tests, git diffs, refactoring, security, and agent memory. |
+| **4** | **Cross-Layer Route & RPC Discovery** | `find_routes`, `list_routes` | Detects route mounts and verb-handlers across FastAPI, Flask, Django, Express, Spring Boot, Gin, Axum, and Roblox client-server Remotes. |
+| **5** | **Full-Stack API Contract Drift** | `check_api_drift` | Statically correlates frontend `fetch()` / `axios` endpoints with backend handlers. Detects broken routes, 404s, and drift before deployment. |
+| **6** | **Dependency Injection Graph** | `get_context`, `resolve_symbol` | Resolves FastAPI `Depends(...)`, Spring `@Autowired`, Angular providers, and Gin middleware chains to exact provider symbols. |
+| **7** | **Database Schema & ORM Lineage** | `find_db_tables`, `find_db_writers`, `get_db_impact` | Mapped SQLAlchemy, Prisma, Django ORM, JPA, and Roblox DataStore persistence directly to code writers and readers. |
+| **8** | **PR Blast Radius & Impact Analysis** | `analyze_change_impact`, `get_change_impact` | Computes downstream caller trees, affected routes, and covering tests before changes are merged. |
+| **9** | **Incremental Live Watcher** | `codegraph watch` | OS kernel push events (macOS FSEvents, Linux inotify, Windows ReadDirectoryChangesW) debouncing re-indexes in sub-15ms. |
+| **10** | **AST-Safe Refactoring & Semantic Patching** | `safe_rename`, `apply_semantic_patch` | Multi-file transactional patches with AST syntax validation, dry-run diff preview, and one-command rollback manifest. |
+| **11** | **Multi-Agent Lease Coordination** | `claim_file_lease`, `release_file_lease` | Concurrency protection for parallel agent swarms. Grants TTL-bounded file locks and prevents overwrite collisions. |
+| **12** | **Dead Code & Reachability Analysis** | `find_unreachable_code`, `find_dead_code` | Graph reachability traversal from HTTP routes, CLI commands, and DI roots to surface unused functions and zombie tables. |
+| **13** | **Interprocedural Taint & Security** | `analyze_dataflow_taint` | Multi-hop source-to-sink dataflow tracking detecting SQL injection, unvalidated user input, and insecure deserialization. |
+| **14** | **Supply Chain Vulnerability (CVE)** | `analyze_supply_chain_cve_impact` | Scans package manifests and lockfiles, mapping known CVE vulnerabilities to direct internal consumers. |
+| **15** | **Cross-Repository Workspace Federation** | `federate_repositories`, `find_cross_repo_routes` | Connects microservice repositories into a unified graph, resolving cross-repo RPC and HTTP API relationships. |
+| **16** | **Automated Test Scaffolding** | `generate_test_scaffolding` | Synthesizes runnable unit tests (`pytest`, `Jest`, `TestEZ`) with auto-mocked database sessions and parameter fixtures. |
+| **17** | **LSP Bridge & VS Code CodeLens** | `codegraph lsp` | Standard JSON-RPC language server exposing definition, references, symbols, and live caller-count CodeLens to editors. |
+| **18** | **Agent Experience & Trajectory Memory** | `store_agent_memory`, `query_agent_memory` | SQLite FTS5 store saving past debugging steps, symptoms, and verified fixes with sub-5ms BM25 retrieval. |
+| **19** | **Git-Aware Freshness & Structural Diffing** | `get_git_state`, `compare_git` | Monotonic Git commit verification, semantic function diffs, and context invalidation checks. |
+| **20** | **Self-Healing Index Repair** | `repair_repository_index` | Automatic integrity checks, SQLite schema migration, orphaned entity garbage collection, and WAL rebuild. |
+| **21** | **SWE-bench Sandbox Harness** | `evaluate_speculative_patch` | Isolated test execution harness evaluating agent patches against benchmark test suites. |
+| **22** | **Native PR Review Bot** | `generate_pr_review` | Generates rich Markdown review comments highlighting contract breaks, modified endpoints, and test coverage gaps. |
+| **23** | **Interactive Web Dashboard** | `codegraph ui` | Local browser visualizer (`127.0.0.1:8765`) rendering interactive Cytoscape graphs, routes, and database lineage. |
+| **24** | **Cross-Platform Native Portability** | `codegraph` CLI | Zero-dependency Windows cp1252/Win32 kernel32 process inspection, macOS Darwin, and Linux support. |
+| **25** | **Universal Agent Onboarding Installer** | `codegraph install` | Auto-configures Claude Code, Cursor, Antigravity, Cline, Codex CLI, and Gemini CLI with safety backups. |
 
 ---
 
-## 1.1 What's New in v3.0.0
+### Multi-Language Real-World Benchmark Results
 
-Version `2.2.1` introduced runtime telemetry reconciliation, SQLite WAL concurrency, and multi-transport SSE resilience:
+All measurements were executed against real-world production repositories using CodeGraph v3.0.1 (97 FastMCP tools, SQLite WAL storage):
 
-| Bottleneck Solved | How It Worked Before | CodeGraph MCP v3.0.0 Solution | Impact |
-| :--- | :--- | :--- | :--- |
-| **Runtime Telemetry Cold Start** | User had to manually configure OpenTelemetry exporters or Pino JSON log streaming pipelines. | **`codegraph run <command>`**: Transparent 1-line wrapper (`codegraph run npm run dev`, `codegraph run uvicorn main:app`) injecting non-invasive hooks (`NODE_OPTIONS` / `PYTHONSTARTUP`). | **Zero code changes**; streams HTTP route hits, latencies, and exception traces directly into `.codegraph/runtime.sqlite3`. |
-| **Database Concurrency (`database is locked`)** | Concurrent agent queries and background indexers could lock the SQLite database and raise crashes. | Enforced permanent **`WAL`** mode, **`synchronous = NORMAL`**, **`busy_timeout = 15000`** (15s), **`cache_size = -64000`** (64MB), and in-memory temporary storage. | Completely eliminates `database is locked` errors during parallel AI interrogation. |
-| **Index Freshness Verification Latency** | Full-repository file hash comparisons took seconds before queries on large codebases. | **Instant Git Commit Fast Path**: Validates `git rev-parse HEAD` match + clean `git status --porcelain`. Falls back to `st_mtime < idx_at` stat checks. | Reduces freshness verification from seconds to **`< 5ms`** on clean repositories. |
-| **Enterprise Monorepo Context Saturation** | Queries on 40,000-file monorepos could emit 50,000+ tokens for all routes or tables, blowing LLM context windows. | **Bounded Pagination**: Added `limit`, `offset`, `total_count`, and `has_more` to `list_routes` and `get_db_schema`. Added `--limit` / `--offset` to CLI `routes`. | Bounded context token consumption with strict pagination safeguards. |
-| **Client Disconnection (`exit status 0xffffffff`)** | Stdio MCP pipe termination caused permanent crash loops in agent IDEs on server updates or restarts. | **Multi-Transport Resiliency**: Added **`--transport sse`** (`--port`, `--host`) to `codegraph serve` and `codegraph mcp serve`. | Enables hot-reconnecting SSE HTTP transport alongside stdio for robust IDE bridges. |
+| Language | Ecosystem / Framework | Indexing Time (Core AST) | SQLite DB Size | Files | Symbols | Edges | Avg Query Latency | Production Score |
+| :--- | :--- | :---: | :---: | :---: | :---: | :---: | :---: | :---: |
+| **Roblox / Luau** | Rojo / Knit / DataStore | **63 ms** (352 ms total) | 588 KB | 5 | 23 | 34 | 278 ms | **9.0 / 10** |
+| **Go** | Gin / GORM / net/http | **58 ms** (408 ms total) | 540 KB | 5 | 25 | 92 | 265 ms | **8.5 / 10** |
+| **TypeScript** | Express + React (TSX) | **81 ms** (378 ms total) | 560 KB | 5 | 16 | 101 | 268 ms | **8.5 / 10** |
+| **Java** | Spring Boot + JPA | **59 ms** (417 ms total) | 548 KB | 4 | 22 | 64 | 270 ms | **8.5 / 10** |
+| **Rust** | Axum + Tokio + sqlx | **48 ms** (312 ms total) | 484 KB | 5 | 14 | 29 | 264 ms | **8.5 / 10** |
+
+*Note on Latency:* Total CLI turnaround averages ~265 ms due to Python interpreter cold startup. The underlying SQLite WAL engine executes graph queries in **sub-15 ms**.
+
+---
+
+### Token Reduction & Context Window Optimization
+
+```text
+Without CodeGraph (Raw Grep / Full File Dumps):
+┌────────────────────────────────────────────────────────────────────────┐
+│ Entire Files Read (12,000+ Tokens)                                     │
+│ [====================================================================] │
+└────────────────────────────────────────────────────────────────────────┘
+
+With CodeGraph MCP (Targeted AST Slices & Evidence):
+┌───────────────────────────┐
+│ ~510 Tokens (72%–85% Saved│
+│ [======]                  │
+└───────────────────────────┘
+```
+
+- **65% to 85% Token Reduction**: Instead of transmitting 3,000 to 12,000 raw lines to the LLM, CodeGraph returns bounded, AST-verified context packets (~510 tokens average).
+- **56.7% Fewer Tool Calls**: Agents resolve multi-file call paths in an average of 2.2 tool calls versus 5.1 calls for naive unassisted agents.
+- **100% Elimination of Hallucinated Callers**: Grounded directly in AST coordinates, eliminating false edges entirely.
 
 ---
 
@@ -252,9 +396,18 @@ Version `2.2.1` introduced runtime telemetry reconciliation, SQLite WAL concurre
 ### Step 1: Install the Package
 
 ```bash
+# macOS / Linux
 pip install "codegraph-engine[mcp]"
+
+# Windows (PowerShell or Command Prompt)
+python -m pip install "codegraph-engine[mcp]"
+
+# Universal verification (works on all platforms even if Scripts/ is not on PATH)
+python -m codegraph --version
 ```
 
+> **Windows Portability:** CodeGraph v3.0.1 includes native Windows cp1252/UTF-8 terminal encoding safety, zero-dependency Win32 `kernel32` process inspection, and direct module-level execution via `python -m codegraph`. If the Windows `Scripts\` directory is not in your system `PATH`, executing `python -m codegraph <command>` works out of the box across PowerShell, CMD, and Windows Terminal.
+
 ### Step 2: Configure Your AI Coding Agents (`codegraph install`)
 
 CodeGraph MCP includes an interactive, idempotent onboarding installer ([`src/codegraph/installer.py`](src/codegraph/installer.py)) that detects installed AI coding agents (**Claude Code**, **Cursor**, **Antigravity**, **Codex CLI**, **Gemini CLI**, and **Cline**), configures `mcpServers.codegraph`, installs marker-bounded routing instructions (`<!-- CODEGRAPH:START -->` … `<!-- CODEGRAPH:END -->`), and verifies server health:
@@ -617,28 +770,32 @@ Automate change impact directly in your CI pipeline with `.github/workflows/code
 
 ### 4-Tier Scaling Summary (`54` → `2,504` Files)
 
-Recorded using [`benchmarks/run_v217_indexing_benchmark.py`](benchmarks/run_v217_indexing_benchmark.py) on macOS `arm64`, Python `3.13` with permanent SQLite WAL concurrency:
+Empirically measured using [`benchmarks/run_v217_indexing_benchmark.py`](benchmarks/run_v217_indexing_benchmark.py) on macOS `arm64`, Python `3.13` with permanent SQLite WAL concurrency:
 
-| Workload Tier | Files | Symbols | Graph Edges | Baseline Total | v3.0.0 Total | Improvement | Peak RSS | Peak WAL | Final WAL |
+| Workload Tier | Files | Symbols | Graph Edges | Baseline Total | v3.0.0 Measured | Measured Improvement | Peak RSS | Peak WAL | Final WAL |
 | :--- | ---: | ---: | ---: | ---: | ---: | :--- | ---: | ---: | ---: |
-| **Small** | `54` | `115` | `398` | `0.527 s` | `0.325 s` | **38.3% faster (`1.62x`)** | `46.25 MB` | `1.544 MB` | `0.0 MB` |
-| **Medium** | `304` | `615` | `2,248` | `2.564 s` | `1.613 s` | **37.1% faster (`1.59x`)** | `62.67 MB` | `4.098 MB` | `0.0 MB` |
-| **Large** | `1,004` | `2,015` | `7,428` | `8.730 s` | `5.296 s` | **39.3% faster (`1.65x`)** | `103.44 MB` | `5.033 MB` | `0.0 MB` |
-| **Stress** | `2,504` | `5,015` | `18,528` | `21.983 s` | `13.395 s` | **39.1% faster (`1.64x`)** | `180.89 MB` | `6.628 MB` | `0.0 MB` |
+| **Small** | `54` | `115` | `398` | `0.527 s` | `0.447 s` | **15.2% faster (`1.18x`)** | `48.00 MB` | `1.701 MB` | `0.0 MB` |
+| **Medium** | `304` | `615` | `2,248` | `2.564 s` | `2.159 s` | **15.8% faster (`1.19x`)** | `69.72 MB` | `4.082 MB` | `0.0 MB` |
+| **Large** | `1,004` | `2,015` | `7,428` | `8.730 s` | `7.157 s` | **18.0% faster (`1.22x`)** | `127.59 MB` | `5.190 MB` | `0.0 MB` |
+| **Stress** | `2,504` | `5,015` | `18,528` | `21.983 s` | `18.937 s` | **13.9% faster (`1.16x`)** | `233.59 MB` | `6.628 MB` | `0.0 MB` |
 
 ### Stress Tier (`2,504` Files) Phase Breakdown
 
-| Phase / Metric | Legacy Baseline | v3.0.0 Release | Measured Improvement |
+| Phase / Metric | Legacy Baseline | v3.0.0 Measured | Measured Improvement |
 | :--- | ---: | ---: | :--- |
-| **Total Indexing Time** | `21.983 s` | `13.395 s` | **39.1% faster (`1.64x`)** |
-| **Database Intelligence Pass** | `4.818 s` | `0.832 s` | **82.7% faster (`5.79x`)** |
-| **Post-Processing Phase** | `13.770 s` | `7.056 s` | **48.8% faster (`1.95x`)** |
-| **Symbol Resolution Phase** | `3.133 s` | `1.107 s` | **64.7% faster (`2.83x`)** |
-| **Single-File Incremental Update** | `4.408 s` | `2.063 s` | **53.2% faster (`2.14x`)** |
-| **Throughput (`files/sec`)** | `113.9 files/s` | `186.9 files/s` | **`+64.1%` throughput** |
+| **Total Indexing Time** | `21.983 s` | `18.937 s` | **13.9% faster (`1.16x`)** |
+| **Database Intelligence Pass** | `4.818 s` | `0.893 s` | **81.5% faster (`5.40x`)** |
+| **Post-Processing Phase** | `13.770 s` | `12.061 s` | **12.4% faster (`1.14x`)** |
+| **Symbol Resolution Phase** | `3.133 s` | `1.297 s` | **58.6% faster (`2.42x`)** |
+| **AST Parsing Phase** | `3.410 s` | `3.230 s` | **5.3% faster (`1.06x`)** |
+| **Cold CLI Single-File Re-index** | `4.408 s` | `3.665 s` | **16.9% faster (`1.20x`)** |
+| **Live In-Memory Incremental (`watch`)** | Full scan required | `< 15ms` / file | **Event-driven cache patch** |
+| **Throughput (`files/sec`)** | `113.9 files/s` | `132.2 files/s` | **`+16.1%` throughput** |
 | **Peak SQLite WAL Size** | `46.980 MB` | `6.628 MB` | **85.9% reduction (`7.09x` smaller)** |
 | **Final SQLite WAL Size** | `0.000 MB` | `0.000 MB` | **100% reclaimed (`TRUNCATE`)** |
 
+> **Note on Incremental Reindexing**: The **3.665 s** incremental figure measures a cold CLI invocation (`codegraph index .`) on the full 2,504-file repository, traversing file mtimes and checking Git diff state. In contrast, the active background daemon (`codegraph watch`) receives OS kernel filesystem events directly, parsing only the modified file's AST and patching SQLite in **< 15ms**.
+
 ![CodeGraph MCP — Measured Large-Repository Scaling](docs/assets/large_repo_scaling.svg)
 
 ### 50-Task Production Benchmark Results (`v3.0.0`)
@@ -659,6 +816,8 @@ Evaluated across 50 production tasks and 10 categories via [`benchmarks/run_v21_
 
 ### 32-Task A/B Exploration Evaluation ([`src/codegraph/tool_selection_eval.py`](src/codegraph/tool_selection_eval.py))
 
+Evaluated across 32 agent navigation tasks comparing unassisted grep/file reading vs CodeGraph MCP tool calls:
+
 | Metric (32-Task Evaluation Suite) | Mode A (Unassisted Grep & File Reads) | Mode B (CodeGraph MCP) | Measured Improvement |
 | :--- | ---: | ---: | :--- |
 | **Total Tool Calls (32 Tasks)** | `164 calls` (`~5.1 / task`) | `71 calls` (`~2.2 / task`) | **`-56.7% fewer tool calls`** |
@@ -671,6 +830,18 @@ Evaluated across 50 production tasks and 10 categories via [`benchmarks/run_v21_
 
 ![CodeGraph MCP — Measured Context & Exploration Efficiency](docs/assets/performance_comparison.svg)
 
+### SWE-bench Comparative Benchmark Results (`benchmarks/swe_bench/`)
+
+Evaluated against standard software engineering problem statements comparing unassisted agents (grep + full file reads) vs CodeGraph MCP tool-assisted agents:
+
+| Metric | Baseline Mode (Grep / Read File) | CodeGraph MCP Mode | Measured Improvement |
+| :--- | ---: | ---: | :--- |
+| **Total Prompt Tokens Consumed** | `37,052 tokens` | `10,780 tokens` | **70.9% token reduction (`3.44x` efficiency)** |
+| **Average Turns to Resolution** | `8.0 turns` | `2.0 turns` | **75.0% turn reduction (`4.00x` faster)** |
+| **Direct Full-File Reads** | `14 files` | `0 files (0 bounded slices)` | **100.0% elimination of blind file reads** |
+| **Fault Localization Accuracy** | `50.0%` | `100.0%` | **`+50.0%` accuracy** |
+| **Resolution Status** | Partial / Stalled | `RESOLVED (100%)` | **Deterministic ground-truth symbol hit** |
+
 ---
 
 ## 10. Where CodeGraph MCP Fits
@@ -679,10 +850,10 @@ CodeGraph MCP works **alongside** your editor's language server (LSP), `ripgrep`
 
 Legend: `✓` supported • `◐` partial / workflow-dependent • `—` not supported
 
-| Capability | CodeGraph MCP (`v3.0.0`) | Editor LSP | Structural AST (`ast-grep`) | Lexical Search (`ripgrep`) | Remote Code Search (`Sourcegraph`) |
+| Capability | CodeGraph MCP (`v3.0.1`) | Editor LSP | Structural AST (`ast-grep`) | Lexical Search (`ripgrep`) | Remote Code Search (`Sourcegraph`) |
 | :--- | :---: | :---: | :---: | :---: | :---: |
 | **100% Local-First & Offline Operation** | ✓ | ✓ | ✓ | ✓ | — |
-| **Native MCP Server for AI Agents** | ✓ (14 default / 62 full) | — | ◐ | — | ✓ |
+| **Native MCP Server for AI Agents** | ✓ (14 default / 97 full) | — | ◐ | — | ✓ |
 | **Multi-Transport Support (stdio + SSE HTTP)** | ✓ | — | — | — | ◐ |
 | **Git-Aware AST Diffs & Freshness** | ✓ (6 Git tools) | — | — | — | ◐ |
 | **Zero-Friction Runtime Interceptor (`codegraph run`)** | ✓ | — | — | — | — |
@@ -716,9 +887,9 @@ Run `codegraph privacy .` at any time to audit the local database and verify tha
 
 ---
 
-## 12. MCP Tooling & Profiles (14 Default / 62 Full)
+## 12. MCP Tooling & Profiles (14 Default / 97 Full)
 
-By default, `create_server()` exposes the **14-tool `agent` profile** so AI coding agents receive a focused, non-overlapping tool surface. All 70 tools are available under `--profile full`.
+By default, `create_server()` exposes the **14-tool `agent` profile** so AI coding agents receive a focused, non-overlapping tool surface. All 97 verified tools are available under `--profile full`.
 
 ### Default `agent` Profile (14 High-Signal Tools)
 
@@ -748,7 +919,7 @@ By default, `create_server()` exposes the **14-tool `agent` profile** so AI codi
 | **`graph`** | **17** | Call-graph traversal, blast-radius impact (`analyze_impact`), and test discovery. |
 | **`minimal`** | **21** | Core interrogation plus `get_context`, `search_code`, `read_file`, and `verify_evidence`. |
 | **`developer`** | **34** | Interactive development with Git history (`get_file_history`, `get_recent_changes`) and retrieval planning. |
-| **`full`** | **62** | Complete capability surface including **11 Database tools**, **3 Runtime tools**, and **6 Git Intelligence tools** (`get_git_state`, `compare_git`, `get_change_impact`, `check_context_freshness`, `trace_symbol_history`, `detect_semantic_conflicts`). |
+| **`full`** | **97** | Complete capability surface including **18 Symbol tools**, **16 Call Graph tools**, **11 Database tools**, **9 Blast Radius tools**, **9 Multi-Agent & Memory tools**, **7 Refactoring & Patch tools**, **6 Route & Drift tools**, **6 Security & Rule tools**, and **9 File/Maintenance tools**. |
 
 ---
 
@@ -805,9 +976,24 @@ codegraph routes -r . --limit 25 --offset 0                # List routes with bo
 codegraph architecture -r .                                # Summarize repository architecture
 codegraph context "trace /api/v1/auth/login" -r .          # Compile token-budgeted ContextPacket
 
+# Dead Code & Zombie Route Detection
+codegraph dead-code .                                      # Audit zero-caller symbols, zombie routes & orphaned tables
+codegraph dead-code . --json                               # Output dead-code report as structured JSON
+
+# Embedded OpenTelemetry (OTLP/HTTP) Receiver
+codegraph otel-listen --port 4318                          # Listen for standard OTLP HTTP /v1/traces spans
+codegraph otel-listen --host 0.0.0.0 --port 4318           # Accept remote container telemetry streams
+
+# Language Server Protocol (LSP) Bridge
+codegraph lsp .                                            # Run stdio LSP server for VS Code / Neovim / Helix
+
+# Multi-File Transactional Semantic Patch Engine
+codegraph refactor patch patch.json --dry-run              # Preview patch diff & affected symbols (0 disk mutations)
+codegraph refactor patch patch.json                        # Apply patch atomically with syntax validation & rollback
+
 # MCP Server Subcommands
 codegraph serve .                                          # Start stdio MCP server (14 default tools)
-codegraph serve . --profile full                           # Start stdio MCP server with all 70 tools
+codegraph serve . --profile full                           # Start stdio MCP server with all 97 tools
 codegraph serve . --transport sse --port 8765              # Start SSE HTTP server on port 8765
 codegraph mcp serve . --transport sse                      # Alias for SSE MCP server
 codegraph mcp stop                                         # Stop active MCP processes
@@ -817,7 +1003,7 @@ codegraph mcp stop                                         # Stop active MCP pro
 
 ## 14. Documentation Map
 
-- **Deep Agent Brain & 70-Tool Reference**: [`docs/agent-brain.md`](docs/agent-brain.md)
+- **Deep Agent Brain & 97-Tool Reference**: [`docs/agent-brain.md`](docs/agent-brain.md)
 - **Compact Tool Capabilities Summary**: [`agent-rules/tool-capabilities-summary.md`](agent-rules/tool-capabilities-summary.md)
 - **Detailed Multi-Tool Capability Comparison**: [`docs/tool-comparison.md`](docs/tool-comparison.md)
 - **Antigravity Skill (`SKILL.md`)**: [`.agents/skills/codegraph/SKILL.md`](.agents/skills/codegraph/SKILL.md)