@optave/codegraph 2.5.1 → 2.6.0

package/README.md

@@ -55,7 +55,7 @@ cd your-project
 codegraph build
 ```
 
-That's it. No config files, no Docker, no JVM, no API keys, no accounts. The graph is ready to query. Add `codegraph mcp` to your AI agent's config and it has full access to your dependency graph through 24 MCP tools (25 in multi-repo mode).
+That's it. No config files, no Docker, no JVM, no API keys, no accounts. The graph is ready to query. Add `codegraph mcp` to your AI agent's config and it has full access to your dependency graph through 30 MCP tools (31 in multi-repo mode).
 
 ### Why it matters
 
@@ -69,25 +69,33 @@ That's it. No config files, no Docker, no JVM, no API keys, no accounts. The gra
 
 ### Feature comparison
 
-<sub>Comparison last verified: February 2026</sub>
+<sub>Comparison last verified: March 2026. Full analysis: <a href="generated/COMPETITIVE_ANALYSIS.md">COMPETITIVE_ANALYSIS.md</a></sub>
 
 | Capability | codegraph | [joern](https://github.com/joernio/joern) | [narsil-mcp](https://github.com/postrv/narsil-mcp) | [code-graph-rag](https://github.com/vitali87/code-graph-rag) | [cpg](https://github.com/Fraunhofer-AISEC/cpg) | [GitNexus](https://github.com/abhigyanpatwari/GitNexus) | [CodeMCP](https://github.com/SimplyLiz/CodeMCP) | [axon](https://github.com/harshkedia177/axon) |
 |---|:---:|:---:|:---:|:---:|:---:|:---:|:---:|:---:|
 | Function-level analysis | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** |
-| Multi-language | **11** | **14** | **32** | Multi | **~10** | **9** | SCIP langs | Few |
-| Semantic search | **Yes** | — | **Yes** | **Yes** | — | **Yes** | — | — |
-| MCP / AI agent support | **Yes** | — | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | — |
-| Git diff impact | **Yes** | — | — | — | — | **Yes** | — | **Yes** |
-| Git co-change analysis | **Yes** | — | — | — | — | — | **Yes** | **Yes** |
-| Watch mode | **Yes** | — | **Yes** | — | — | — | — | — |
-| Dead code / role classification | **Yes** | — | **Yes** | — | — | — | — | **Yes** |
-| Cycle detection | **Yes** | — | **Yes** | — | — | — | — | **Yes** |
-| Incremental rebuilds | **O(changed)** | — | O(n) Merkle | — | — | — | — | — |
-| Zero config | **Yes** | — | **Yes** | — | — | — | — | — |
+| Multi-language | **11** | **14** | **32** | **11** | **~10** | **12** | **12** | **3** |
+| Semantic search | **Yes** | — | **Yes** | **Yes** | — | **Yes** | — | **Yes** |
+| Hybrid BM25 + semantic | **Yes** | — | — | — | — | **Yes** | — | **Yes** |
+| CODEOWNERS integration | **Yes** | — | — | — | — | — | — | — |
+| Architecture boundary rules | **Yes** | — | — | — | — | — | — | — |
+| CI validation predicates | **Yes** | — | — | — | — | — | — | — |
+| Composite audit command | **Yes** | — | — | — | — | — | — | — |
+| Batch querying | **Yes** | — | — | — | — | — | — | — |
+| Graph snapshots | **Yes** | — | — | — | — | — | — | — |
+| MCP / AI agent support | **Yes** | — | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** |
+| Git diff impact | **Yes** | — | — | — | — | **Yes** | **Yes** | **Yes** |
+| Branch structural diff | **Yes** | — | — | — | — | — | — | **Yes** |
+| Git co-change analysis | **Yes** | — | — | — | — | — | — | **Yes** |
+| Watch mode | **Yes** | — | **Yes** | **Yes** | — | — | **Yes** | **Yes** |
+| Dead code / role classification | **Yes** | — | **Yes** | — | — | — | **Yes** | **Yes** |
+| Cycle detection | **Yes** | — | — | — | — | — | — | — |
+| Incremental rebuilds | **O(changed)** | — | O(n) Merkle | — | — | — | Go only | **Yes** |
+| Zero config | **Yes** | — | **Yes** | — | — | **Yes** | — | **Yes** |
 | Embeddable JS library (`npm install`) | **Yes** | — | — | — | — | — | — | — |
-| LLM-optional (works without API keys) | **Yes** | **Yes** | **Yes** | — | **Yes** | **Yes** | **Yes** | **Yes** |
-| Commercial use allowed | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | — | — | — |
-| Open source | **Yes** | Yes | Yes | Yes | Yes | Yes | Custom | — |
+| LLM-optional (works without API keys) | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** |
+| Commercial use allowed | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | No | Paid | **Yes** |
+| Open source | **Yes** | Yes | Yes | Yes | Yes | No | No | Yes |
 
 ### What makes codegraph different
 
@@ -97,10 +105,10 @@ That's it. No config files, no Docker, no JVM, no API keys, no accounts. The gra
 | **🔓** | **Zero-cost core, LLM-enhanced when you want** | Full graph analysis with no API keys, no accounts, no cost. Optionally bring your own LLM provider — your code only goes where you choose |
 | **🔬** | **Function-level, not just files** | Traces `handleAuth()` → `validateToken()` → `decryptJWT()` and shows 14 callers across 9 files break if `decryptJWT` changes |
 | **🏷️** | **Role classification** | Every symbol auto-tagged as `entry`/`core`/`utility`/`adapter`/`dead`/`leaf` — agents instantly know what they're looking at |
-| **🤖** | **Built for AI agents** | 24-tool [MCP server](https://modelcontextprotocol.io/) — AI assistants query your graph directly. Single-repo by default |
+| **🤖** | **Built for AI agents** | 30-tool [MCP server](https://modelcontextprotocol.io/) — AI assistants query your graph directly. Single-repo by default |
 | **🌐** | **Multi-language, one CLI** | JS/TS + Python + Go + Rust + Java + C# + PHP + Ruby + HCL in a single graph |
 | **💥** | **Git diff impact** | `codegraph diff-impact` shows changed functions, their callers, and full blast radius — enriched with historically coupled files from git co-change analysis. Ships with a GitHub Actions workflow |
-| **🧠** | **Semantic search** | Local embeddings by default, LLM-powered when opted in — multi-query with RRF ranking via `"auth; token; JWT"` |
+| **🧠** | **Hybrid search** | BM25 keyword + semantic embeddings fused via RRF — `hybrid` (default), `semantic`, or `keyword` mode; multi-query via `"auth; token; JWT"` |
 
 ---
 
@@ -127,6 +135,8 @@ git clone https://github.com/optave/codegraph.git
 cd codegraph && npm install && npm link
 ```
 
+> **Dev builds:** Pre-release tarballs are attached to [GitHub Releases](https://github.com/optave/codegraph/releases). Install with `npm install -g <path-to-tarball>`. Note that `npm install -g <tarball-url>` does not work because npm cannot resolve optional platform-specific dependencies from a URL — download the `.tgz` first, then install from the local file.
+
 ### For AI agents
 
 Add codegraph to your agent's instructions (e.g. `CLAUDE.md`):
@@ -144,7 +154,7 @@ After modifying code:
 Or connect directly via MCP:
 
 ```bash
-codegraph mcp          # 24-tool MCP server — AI queries the graph directly
+codegraph mcp          # 30-tool MCP server — AI queries the graph directly
 ```
 
 Full agent setup: [AI Agent Guide](docs/guides/ai-agent-guide.md) &middot; [CLAUDE.md template](docs/guides/ai-agent-guide.md#claudemd-template)
@@ -170,11 +180,21 @@ Full agent setup: [AI Agent Guide](docs/guides/ai-agent-guide.md) &middot; [CLAU
 | 📤 | **Export** | DOT (Graphviz), Mermaid, and JSON graph export |
 | 🧠 | **Semantic search** | Embeddings-powered natural language search with multi-query RRF ranking |
 | 👀 | **Watch mode** | Incrementally update the graph as files change |
-| 🤖 | **MCP server** | 24-tool MCP server for AI assistants; single-repo by default, opt-in multi-repo |
+| 🤖 | **MCP server** | 30-tool MCP server for AI assistants; single-repo by default, opt-in multi-repo |
 | ⚡ | **Always fresh** | Three-tier incremental detection — sub-second rebuilds even on large codebases |
 | 🧮 | **Complexity metrics** | Cognitive, cyclomatic, nesting depth, Halstead, and Maintainability Index per function |
 | 🏘️ | **Community detection** | Louvain clustering to discover natural module boundaries and architectural drift |
 | 📜 | **Manifesto rule engine** | Configurable pass/fail rules with warn/fail thresholds for CI gates (exit code 1 on fail) |
+| 👥 | **CODEOWNERS integration** | Map graph nodes to CODEOWNERS entries — see who owns each function, ownership boundaries in `diff-impact` |
+| 💾 | **Graph snapshots** | `snapshot save`/`restore` for instant DB backup and rollback — checkpoint before refactoring, restore without rebuilding |
+| 🔎 | **Hybrid BM25 + semantic search** | FTS5 keyword search + embedding-based semantic search fused via Reciprocal Rank Fusion — `hybrid`, `semantic`, or `keyword` modes |
+| 📄 | **Pagination & NDJSON streaming** | Universal `--limit`/`--offset` pagination on all MCP tools and CLI commands; `--ndjson` for newline-delimited JSON streaming |
+| 🔀 | **Branch structural diff** | Compare code structure between two git refs — added/removed/changed symbols with transitive caller impact |
+| 🛡️ | **Architecture boundaries** | User-defined dependency rules between modules with onion architecture preset — violations flagged in manifesto and CI |
+| ✅ | **CI validation predicates** | `check` command with configurable gates: complexity, blast radius, cycles, boundary violations — exit code 0/1 for CI |
+| 📋 | **Composite audit** | Single `audit` command combining explain + impact + health metrics per function — one call instead of 3-4 |
+| 🚦 | **Triage queue** | `triage` merges connectivity, hotspots, roles, and complexity into a ranked audit priority queue |
+| 📦 | **Batch querying** | Accept a list of targets and return all results in one JSON payload — enables multi-agent parallel dispatch |
 
 See [docs/examples](docs/examples) for real-world CLI and MCP usage examples.
 
@@ -227,6 +247,10 @@ codegraph diff-impact          # Impact of unstaged git changes
 codegraph diff-impact --staged # Impact of staged changes
 codegraph diff-impact HEAD~3   # Impact vs a specific ref
 codegraph diff-impact main --format mermaid -T  # Mermaid flowchart of blast radius
+codegraph branch-compare main feature-branch    # Structural diff between two refs
+codegraph branch-compare main HEAD --no-tests   # Symbols added/removed/changed vs main
+codegraph branch-compare v2.4.0 v2.5.0 --json   # JSON output for programmatic use
+codegraph branch-compare main HEAD --format mermaid  # Mermaid diagram of structural changes
 ```
 
 ### Co-Change Analysis
@@ -267,6 +291,56 @@ codegraph manifesto               # Pass/fail rule engine (exit code 1 on fail)
 codegraph manifesto -T            # Exclude test files from rule evaluation
 ```
 
+### Audit, Triage & Batch
+
+Composite commands for risk-driven workflows and multi-agent dispatch.
+
+```bash
+codegraph audit <file-or-function>    # Combined explain + impact + health in one report
+codegraph audit src/queries.js -T     # Audit all functions in a file
+codegraph triage                      # Ranked audit priority queue (connectivity + hotspots + roles)
+codegraph triage -T --limit 20        # Top 20 riskiest functions, excluding tests
+codegraph batch target1 target2 ...   # Batch query multiple targets in one call
+codegraph batch --json targets.json   # Batch from a JSON file
+```
+
+### CI Validation
+
+`codegraph check` provides configurable pass/fail predicates for CI gates and state machines. Exit code 0 = pass, 1 = fail.
+
+```bash
+codegraph check --staged                    # Check staged changes
+codegraph check --no-new-cycles             # Fail if staged changes introduce cycles
+codegraph check --max-complexity 30         # Fail if any function exceeds complexity threshold
+codegraph check --max-blast-radius 50       # Fail if blast radius exceeds limit
+codegraph check --no-boundary-violations    # Fail on architecture boundary violations
+codegraph check main                        # Check current branch vs main
+```
+
+### CODEOWNERS
+
+Map graph symbols to CODEOWNERS entries. Shows who owns each function and surfaces ownership boundaries.
+
+```bash
+codegraph owners                   # Show ownership for all symbols
+codegraph owners src/queries.js    # Ownership for symbols in a specific file
+codegraph owners --boundary        # Show ownership boundaries between modules
+codegraph owners --owner @backend  # Filter by owner
+```
+
+Ownership data also enriches `diff-impact` — affected owners and suggested reviewers appear alongside the static dependency analysis.
+
+### Snapshots
+
+Lightweight SQLite DB backup and restore — checkpoint before refactoring, instantly rollback without rebuilding.
+
+```bash
+codegraph snapshot save before-refactor   # Save a named snapshot
+codegraph snapshot list                   # List all snapshots
+codegraph snapshot restore before-refactor  # Restore a snapshot
+codegraph snapshot delete before-refactor   # Delete a snapshot
+```
+
 ### Export & Visualization
 
 ```bash
@@ -287,6 +361,9 @@ codegraph embed                # Build embeddings (default: nomic-v1.5)
 codegraph embed --model nomic  # Use a different model
 codegraph search "handle authentication"
 codegraph search "parse config" --min-score 0.4 -n 10
+codegraph search "parseConfig" --mode keyword   # BM25 keyword-only (exact names)
+codegraph search "auth flow" --mode semantic    # Embedding-only (conceptual)
+codegraph search "auth flow" --mode hybrid      # BM25 + semantic RRF fusion (default)
 codegraph models               # List available models
 ```
 
@@ -336,13 +413,17 @@ codegraph registry remove <name>  # Unregister
 | Flag | Description |
 |---|---|
 | `-d, --db <path>` | Custom path to `graph.db` |
-| `-T, --no-tests` | Exclude `.test.`, `.spec.`, `__test__` files (available on `fn`, `fn-impact`, `path`, `context`, `explain`, `where`, `diff-impact`, `search`, `map`, `hotspots`, `roles`, `co-change`, `deps`, `impact`, `complexity`, `communities`, `manifesto`) |
+| `-T, --no-tests` | Exclude `.test.`, `.spec.`, `__test__` files (available on `fn`, `fn-impact`, `path`, `context`, `explain`, `where`, `diff-impact`, `search`, `map`, `hotspots`, `roles`, `co-change`, `deps`, `impact`, `complexity`, `communities`, `manifesto`, `branch-compare`, `audit`, `triage`, `check`) |
 | `--depth <n>` | Transitive trace depth (default varies by command) |
 | `-j, --json` | Output as JSON |
 | `-v, --verbose` | Enable debug output |
 | `--engine <engine>` | Parser engine: `native`, `wasm`, or `auto` (default: `auto`) |
 | `-k, --kind <kind>` | Filter by kind: `function`, `method`, `class`, `struct`, `enum`, `trait`, `record`, `module` (`fn`, `context`, `search`) |
 | `-f, --file <path>` | Scope to a specific file (`fn`, `context`, `where`) |
+| `--mode <mode>` | Search mode: `hybrid` (default), `semantic`, or `keyword` (`search`) |
+| `--ndjson` | Output as newline-delimited JSON (one object per line) |
+| `--limit <n>` | Limit number of results |
+| `--offset <n>` | Skip first N results (pagination) |
 | `--rrf-k <n>` | RRF smoothing constant for multi-query search (default 60) |
 
 ## 🌐 Language Support
@@ -419,18 +500,18 @@ Codegraph also extracts symbols from common callback patterns: Commander `.comma
 
 ## 📊 Performance
 
-Self-measured on every release via CI ([build benchmarks](generated/BUILD-BENCHMARKS.md) | [embedding benchmarks](generated/EMBEDDING-BENCHMARKS.md)):
+Self-measured on every release via CI ([build benchmarks](generated/benchmarks/BUILD-BENCHMARKS.md) | [embedding benchmarks](generated/benchmarks/EMBEDDING-BENCHMARKS.md)):
 
 | Metric | Latest |
 |---|---|
-| Build speed (native) | **2 ms/file** |
-| Build speed (WASM) | **8.4 ms/file** |
+| Build speed (native) | **1.9 ms/file** |
+| Build speed (WASM) | **7.8 ms/file** |
 | Query time | **2ms** |
-| No-op rebuild (native) | **4ms** |
-| 1-file rebuild (native) | **97ms** |
-| Query: fn-deps | **2.1ms** |
-| Query: path | **1.2ms** |
-| ~50,000 files (est.) | **~100.0s build** |
+| No-op rebuild (native) | **3ms** |
+| 1-file rebuild (native) | **93ms** |
+| Query: fn-deps | **1.8ms** |
+| Query: path | **1ms** |
+| ~50,000 files (est.) | **~95.0s build** |
 
 Metrics are normalized per file for cross-version comparability. Times above are for a full initial build — incremental rebuilds only re-parse changed files.
 
@@ -452,7 +533,7 @@ Optional: `@huggingface/transformers` (semantic search), `@modelcontextprotocol/
 
 ### MCP Server
 
-Codegraph includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) server with 24 tools (25 in multi-repo mode), so AI assistants can query your dependency graph directly:
+Codegraph includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) server with 30 tools (31 in multi-repo mode), so AI assistants can query your dependency graph directly:
 
 ```bash
 codegraph mcp                  # Single-repo mode (default) — only local project
@@ -494,7 +575,15 @@ This project uses codegraph. The database is at `.codegraph/graph.db`.
 - `codegraph complexity -T` — per-function complexity metrics (cognitive, cyclomatic, MI)
 - `codegraph communities --drift -T` — module boundary drift analysis
 - `codegraph manifesto -T` — pass/fail rule check (CI gate, exit code 1 on fail)
-- `codegraph search "<query>"` — semantic search (requires `codegraph embed`)
+- `codegraph audit <target> -T` — combined explain + impact + health in one report
+- `codegraph triage -T` — ranked audit priority queue
+- `codegraph check --staged` — CI validation predicates (exit code 0/1)
+- `codegraph batch target1 target2` — batch query multiple targets at once
+- `codegraph owners [target]` — CODEOWNERS mapping for symbols
+- `codegraph snapshot save <name>` — checkpoint the graph DB before refactoring
+- `codegraph branch-compare main HEAD -T` — structural diff between two refs (added/removed/changed symbols)
+- `codegraph search "<query>"` — hybrid search (requires `codegraph embed`)
+- `codegraph search "<query>" --mode keyword` — BM25 keyword search
 - `codegraph cycles` — check for circular dependencies
 
 ### Flags
@@ -660,25 +749,6 @@ const { results: fused } = await multiSearchData(
 - **Dynamic calls are best-effort** — complex computed property access and `eval` patterns are not resolved
 - **Python imports** — resolves relative imports but doesn't follow `sys.path` or virtual environment packages
 
-## 🔍 How Codegraph Compares
-
-<sub>Last verified: February 2026. Full analysis: <a href="generated/COMPETITIVE_ANALYSIS.md">COMPETITIVE_ANALYSIS.md</a></sub>
-
-| Capability | codegraph | [joern](https://github.com/joernio/joern) | [narsil-mcp](https://github.com/postrv/narsil-mcp) | [code-graph-rag](https://github.com/vitali87/code-graph-rag) | [cpg](https://github.com/Fraunhofer-AISEC/cpg) | [GitNexus](https://github.com/abhigyanpatwari/GitNexus) |
-|---|:---:|:---:|:---:|:---:|:---:|:---:|
-| Function-level analysis | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** |
-| Multi-language | **11** | **14** | **32** | Multi | **~10** | **9** |
-| Incremental rebuilds | **O(changed)** | — | O(n) Merkle | — | — | — |
-| MCP / AI agent support | **Yes** | — | **Yes** | **Yes** | **Yes** | **Yes** |
-| Git diff impact | **Yes** | — | — | — | — | **Yes** |
-| Git co-change analysis | **Yes** | — | — | — | — | — |
-| Dead code / role classification | **Yes** | — | **Yes** | — | — | — |
-| Semantic search | **Yes** | — | **Yes** | **Yes** | — | **Yes** |
-| Watch mode | **Yes** | — | **Yes** | — | — | — |
-| Zero config, no Docker/JVM | **Yes** | — | **Yes** | — | — | — |
-| Works without API keys | **Yes** | **Yes** | **Yes** | — | **Yes** | **Yes** |
-| Commercial use (Apache/MIT) | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | — |
-
 ## 🗺️ Roadmap
 
 See **[ROADMAP.md](docs/roadmap/ROADMAP.md)** for the full development roadmap and **[STABILITY.md](STABILITY.md)** for the stability policy and versioning guarantees. Current plan:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optave/codegraph",
-  "version": "2.5.1",
+  "version": "2.6.0",
   "description": "Local code graph CLI — parse codebases with tree-sitter, build dependency graphs, query them",
   "type": "module",
   "main": "src/index.js",
@@ -71,15 +71,16 @@
   },
   "optionalDependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@optave/codegraph-darwin-arm64": "2.5.1",
-    "@optave/codegraph-darwin-x64": "2.5.1",
-    "@optave/codegraph-linux-x64-gnu": "2.5.1",
-    "@optave/codegraph-win32-x64-msvc": "2.5.1"
+    "@optave/codegraph-darwin-arm64": "2.6.0",
+    "@optave/codegraph-darwin-x64": "2.6.0",
+    "@optave/codegraph-linux-x64-gnu": "2.6.0",
+    "@optave/codegraph-win32-x64-msvc": "2.6.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.4",
-    "@commitlint/cli": "^19.8",
-    "@commitlint/config-conventional": "^19.8",
+    "@commitlint/cli": "^20.4",
+    "@commitlint/config-conventional": "^20.0",
+    "@huggingface/transformers": "^3.8.1",
     "@tree-sitter-grammars/tree-sitter-hcl": "^1.2.0",
     "@vitest/coverage-v8": "^4.0.18",
     "commit-and-tag-version": "^12.5",