@optave/codegraph 3.1.4 → 3.2.0

package/README.md

@@ -141,7 +141,7 @@ That's it. The graph is ready. Now connect your AI agent.
 Connect directly via MCP — your agent gets 30 tools to query the graph:
 
 ```bash
-codegraph mcp          # 30-tool MCP server — AI queries the graph directly
+codegraph mcp          # 33-tool MCP server — AI queries the graph directly
 ```
 
 Or add codegraph to your agent's instructions (e.g. `CLAUDE.md`):
@@ -183,7 +183,7 @@ cd codegraph && npm install && npm link
 
 | | Feature | Description |
 |---|---|---|
-| 🤖 | **MCP server** | 30-tool MCP server for AI assistants; single-repo by default, opt-in multi-repo |
+| 🤖 | **MCP server** | 33-tool MCP server for AI assistants; single-repo by default, opt-in multi-repo |
 | 🎯 | **Deep context** | `context` gives agents source, deps, callers, signature, and tests for a function in one call; `audit --quick` gives structural summaries |
 | 🏷️ | **Node role classification** | Every symbol auto-tagged as `entry`/`core`/`utility`/`adapter`/`dead`/`leaf` based on connectivity — agents instantly know architectural role |
 | 📦 | **Batch querying** | Accept a list of targets and return all results in one JSON payload — enables multi-agent parallel dispatch |
@@ -258,6 +258,7 @@ codegraph children <name>         # List parameters, properties, constants of a
 ```bash
 codegraph context <name>       # Full context: source, deps, callers, signature, tests
 codegraph context <name> --depth 2 --no-tests  # Include callee source 2 levels deep
+codegraph brief <file>            # Token-efficient file summary: symbols, roles, risk tiers
 codegraph audit <file> --quick    # Structural summary: public API, internals, data flow
 codegraph audit <function> --quick  # Function summary: signature, calls, callers, tests
 ```
@@ -477,6 +478,8 @@ codegraph registry remove <name>  # Unregister
 | `-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) |
+| `--table` | Output as auto-column aligned table |
+| `--csv` | Output as CSV (RFC 4180, nested objects flattened) |
 | `--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) |
@@ -560,14 +563,14 @@ Self-measured on every release via CI ([build benchmarks](generated/benchmarks/B
 
 | Metric | Latest |
 |---|---|
-| Build speed (native) | **5.1 ms/file** |
-| Build speed (WASM) | **14.6 ms/file** |
-| Query time | **4ms** |
-| No-op rebuild (native) | **6ms** |
-| 1-file rebuild (native) | **282ms** |
+| Build speed (native) | **3.5 ms/file** |
+| Build speed (WASM) | **9.6 ms/file** |
+| Query time | **3ms** |
+| No-op rebuild (native) | **9ms** |
+| 1-file rebuild (native) | **265ms** |
 | Query: fn-deps | **0.9ms** |
-| Query: path | **0.8ms** |
-| ~50,000 files (est.) | **~255.0s build** |
+| Query: path | **0.9ms** |
+| ~50,000 files (est.) | **~175.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.
 
@@ -603,16 +606,16 @@ codegraph mcp --repos a,b      # Restrict to specific repos (implies --multi-rep
 
 ### CLAUDE.md / Agent Instructions
 
-Add this to your project's `CLAUDE.md` to help AI agents use codegraph (full template in the [AI Agent Guide](docs/guides/ai-agent-guide.md#claudemd-template)):
+Add this to your project's `CLAUDE.md` to help AI agents use codegraph. Full template with all commands in the [AI Agent Guide](docs/guides/ai-agent-guide.md#claudemd-template).
 
 ```markdown
-## Code Navigation
+## Codegraph
 
-This project uses codegraph. The database is at `.codegraph/graph.db`.
+This project uses codegraph for dependency analysis. The graph is at `.codegraph/graph.db`.
 
-### Before modifying code, always:
+### Before modifying code:
 1. `codegraph where <name>` — find where the symbol lives
-2. `codegraph audit <file-or-function> --quick` — understand the structure
+2. `codegraph audit --quick <target>` — understand the structure
 3. `codegraph context <name> -T` — get full context (source, deps, callers)
 4. `codegraph fn-impact <name> -T` — check blast radius before editing
 
@@ -620,65 +623,19 @@ This project uses codegraph. The database is at `.codegraph/graph.db`.
 5. `codegraph diff-impact --staged -T` — verify impact before committing
 
 ### Other useful commands
-- `codegraph build .` — rebuild the graph (incremental by default)
-- `codegraph map` — module overview
-- `codegraph query <name> -T` — function call chain (callers + callees)
-- `codegraph path <from> <to> -T` — shortest call path between two symbols
-- `codegraph deps <file>` — file-level dependencies
-- `codegraph roles --role dead -T` — find dead code (unreferenced symbols)
-- `codegraph roles --role core -T` — find core symbols (high fan-in)
-- `codegraph co-change <file>` — files that historically change together
-- `codegraph complexity -T` — per-function complexity metrics (cognitive, cyclomatic, MI)
-- `codegraph communities --drift -T` — module boundary drift analysis
-- `codegraph check -T` — pass/fail rule check (CI gate, exit code 1 on fail)
-- `codegraph audit <target> -T` — combined structural summary + impact + health in one report
-- `codegraph triage -T` — ranked audit priority queue
-- `codegraph triage --level file -T` — file-level hotspot analysis
-- `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 exports <file>` — per-symbol consumer analysis (who calls each export)
-- `codegraph children <name>` — list parameters, properties, constants of a symbol
-- `codegraph dataflow <name>` — data flow edges (flows_to, returns, mutates)
-- `codegraph cfg <name>` — intraprocedural control flow graph
-- `codegraph ast <pattern>` — search stored AST nodes (calls, new, string, regex, throw, await)
-- `codegraph plot` — interactive HTML dependency graph viewer
-- `codegraph search "<query>"` — hybrid search (requires `codegraph embed`)
-- `codegraph search "<query>" --mode keyword` — BM25 keyword search
-- `codegraph cycles` — check for circular dependencies
+- `codegraph build .` — rebuild graph (incremental by default)
+- `codegraph map` — module overview · `codegraph stats` — graph health
+- `codegraph query <name> -T` — call chain · `codegraph path <from> <to> -T` — shortest path
+- `codegraph deps <file>` — file deps · `codegraph exports <file> -T` — export consumers
+- `codegraph audit <target> -T` — full risk report · `codegraph triage -T` — priority queue
+- `codegraph check --staged` — CI gate · `codegraph batch t1 t2 -T --json` — batch query
+- `codegraph search "<query>"` — semantic search · `codegraph cycles` — cycle detection
+- `codegraph roles --role dead -T` — dead code · `codegraph complexity -T` — metrics
+- `codegraph dataflow <name> -T` — data flow · `codegraph cfg <name> -T` — control flow
 
 ### Flags
-- `-T` / `--no-tests` — exclude test files (use by default)
-- `-j` / `--json` — JSON output for programmatic use
-- `-f, --file <path>` — scope to a specific file
-- `-k, --kind <kind>` — filter by symbol kind
-
-### Semantic search
-
-Use `codegraph search` to find functions by intent rather than exact name.
-When a single query might miss results, combine multiple angles with `;`:
-
-  codegraph search "validate auth; check token; verify JWT"
-  codegraph search "parse config; load settings" --kind function
-
-Multi-query search uses Reciprocal Rank Fusion — functions that rank
-highly across several queries surface first. This is especially useful
-when you're not sure what naming convention the codebase uses.
-
-When writing multi-queries, use 2-4 sub-queries (2-4 words each) that
-attack the problem from different angles. Pick from these strategies:
-- **Naming variants**: cover synonyms the author might have used
-  ("send email; notify user; deliver message")
-- **Abstraction levels**: pair high-level intent with low-level operation
-  ("handle payment; charge credit card")
-- **Input/output sides**: cover the read half and write half
-  ("parse config; apply settings")
-- **Domain + technical**: bridge business language and implementation
-  ("onboard tenant; create organization; provision workspace")
-
-Use `--kind function` to cut noise. Use `--file <pattern>` to scope.
+- `-T` — exclude test files (use by default) · `-j` — JSON output
+- `-f, --file <path>` — scope to file · `-k, --kind <kind>` — filter kind
 ```
 
 ## 📋 Recommended Practices
@@ -821,7 +778,7 @@ See **[ROADMAP.md](docs/roadmap/ROADMAP.md)** for the full development roadmap a
 1. ~~**Rust Core**~~ — **Complete** (v1.3.0) — native tree-sitter parsing via napi-rs, parallel multi-core parsing, incremental re-parsing, import resolution & cycle detection in Rust
 2. ~~**Foundation Hardening**~~ — **Complete** (v1.4.0) — parser registry, 12-tool MCP server with multi-repo support, test coverage 62%→75%, `apiKeyCommand` secret resolution, global repo registry
 3. ~~**Deep Analysis**~~ — **Complete** (v3.0.0) — dataflow analysis (flows_to, returns, mutates), intraprocedural CFG for all 11 languages, stored AST nodes, expanded node/edge types (parameter, property, constant, contains, parameter_of, receiver), GraphML/GraphSON/Neo4j CSV export, interactive HTML viewer, CLI consolidation, stable JSON schema
-4. **Architectural Refactoring** — **In Progress** (v3.1.4) — unified AST analysis, composable MCP, domain errors, builder pipeline, embedder subsystem, graph model, qualified names, presentation layer, InMemoryRepository (11/14 tasks complete)
+4. ~~**Architectural Refactoring**~~ — **Complete** (v3.1.5) — unified AST analysis, composable MCP, domain errors, builder pipeline, embedder subsystem, graph model, qualified names, presentation layer, InMemoryRepository, domain directory grouping, CLI composability
 5. **Natural Language Queries** — `codegraph ask` command, conversational sessions
 6. **Expanded Language Support** — 8 new languages (12 → 20)
 7. **GitHub Integration & CI** — reusable GitHub Action, PR review, SARIF output

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "@optave/codegraph",
-  "version": "3.1.4",
+  "version": "3.2.0",
   "description": "Local code graph CLI — parse codebases with tree-sitter, build dependency graphs, query them",
   "type": "module",
   "main": "src/index.js",
   "exports": {
     ".": {
-      "import": "./src/index.js"
+      "import": "./src/index.js",
+      "require": "./src/index.cjs",
+      "default": "./src/index.cjs"
     },
     "./cli": {
       "import": "./src/cli.js"
@@ -74,12 +76,12 @@
   },
   "optionalDependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@optave/codegraph-darwin-arm64": "3.1.4",
-    "@optave/codegraph-darwin-x64": "3.1.4",
-    "@optave/codegraph-linux-arm64-gnu": "3.1.4",
-    "@optave/codegraph-linux-x64-gnu": "3.1.4",
-    "@optave/codegraph-linux-x64-musl": "3.1.4",
-    "@optave/codegraph-win32-x64-msvc": "3.1.4"
+    "@optave/codegraph-darwin-arm64": "3.2.0",
+    "@optave/codegraph-darwin-x64": "3.2.0",
+    "@optave/codegraph-linux-arm64-gnu": "3.2.0",
+    "@optave/codegraph-linux-x64-gnu": "3.2.0",
+    "@optave/codegraph-linux-x64-musl": "3.2.0",
+    "@optave/codegraph-win32-x64-msvc": "3.2.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.4",