@optave/codegraph 3.1.3 → 3.1.5

package/README.md

@@ -31,13 +31,11 @@
 
 ## The Problem
 
-AI agents are the primary interface to large codebases — and they're flying blind.
+AI agents face an impossible trade-off. They either spend thousands of tokens reading files to understand a codebase's structure — blowing up their context window until quality degrades — or they assume how things work, and the assumptions are often wrong. Either way, things break. The larger the codebase, the worse it gets.
 
-An agent burns a great portion of its token budget on `grep`, `find`, `cat` — re-discovering the same structure every session. It modifies `parseConfig()` without knowing 9 files import it. It hallucinates a function signature because it never saw the real one. Multiply that by every session, every developer, every repo.
+An agent modifies a function without knowing 9 files import it. It misreads what a helper does and builds logic on top of that misunderstanding. It leaves dead code behind after a refactor. The PR gets opened, and your reviewer — human or automated — flags the same structural issues again and again: _"this breaks 14 callers,"_ _"that function already exists,"_ _"this export is now dead."_ If the reviewer catches it, that's multiple rounds of back-and-forth. If they don't, it can ship to production. Multiply that by every PR, every developer, every repo.
 
-Developers aren't much better off. They inherit projects and spend days grepping to understand what calls what. Architects draw boundary rules that erode within weeks because nothing enforces them. CI catches test failures but can't tell you _"this change silently affects 14 callers across 9 files."_
-
-The information exists — it's in the code itself. But without a structured map, agents hallucinate, developers guess, and architecture degrades one unreviewed change at a time.
+The information to prevent these issues exists — it's in the code itself. But without a structured map, agents lack the context to get it right consistently, reviewers waste cycles on preventable issues, and architecture degrades one unreviewed change at a time.
 
 ## What Codegraph Does
 
@@ -50,7 +48,7 @@ It parses your code with [tree-sitter](https://tree-sitter.github.io/) (native R
 - **CI gates** — `check` and `manifesto` commands enforce quality thresholds with exit codes
 - **Programmatic API** — embed codegraph in your own tools via `npm install`
 
-Instead of an agent burning 30 tool calls to maybe discover half your dependencies, it gets _"this function has 14 callers across 9 files"_ in one MCP call. Instead of hoping architecture rules are followed, you enforce them. Instead of finding breakage in production, `diff-impact --staged` catches it before you commit.
+Instead of an agent editing code without structural context and letting reviewers catch the fallout, it knows _"this function has 14 callers across 9 files"_ before it touches anything. Dead exports, circular dependencies, and boundary violations surface during development — not during review. The result: PRs that need fewer review rounds.
 
 **Free. Open source. Fully local.** Zero network calls, zero telemetry. Your code stays on your machine. When you want deeper intelligence, bring your own LLM provider — your code only goes where you choose to send it.
 
@@ -62,18 +60,18 @@ cd your-project
 codegraph build
 ```
 
-No config files, no Docker, no JVM, no API keys, no accounts. Point your agent at the MCP server and it has full structural awareness of your codebase.
+No config files, no Docker, no JVM, no API keys, no accounts. Point your agent at the MCP server and it has structural awareness of your codebase.
 
 ### Why it matters
 
 | | Without codegraph | With codegraph |
 |---|---|---|
-| **AI agents** | Spend 20+ tool calls per session re-discovering code structure | Get full dependency context in one MCP call |
-| **AI agents** | Modify `parseConfig()` without knowing 9 files import it | `fn-impact parseConfig` shows every caller before the edit |
-| **AI agents** | Hallucinate function signatures and miss callers | `context <name> -T` returns source, deps, callers, and tests — no guessing |
+| **Code review** | Reviewers flag broken callers, dead code, and boundary violations round after round | Structural issues are caught during development — PRs pass review with fewer rounds |
+| **AI agents** | Modify `parseConfig()` without knowing 9 files import it — reviewer catches it | `fn-impact parseConfig` shows every caller before the edit — agent fixes it proactively |
+| **AI agents** | Leave dead exports and duplicate helpers behind after refactors | Dead code, cycles, and duplicates surface in real time via hooks and MCP queries |
+| **AI agents** | Produce code that works but doesn't fit the codebase structure | `context <name> -T` returns source, deps, callers, and tests — the agent writes code that fits |
 | **CI pipelines** | Catch test failures but miss structural degradation | `check --staged` fails the build when blast radius or complexity thresholds are exceeded |
 | **Developers** | Inherit a codebase and grep for hours to understand what calls what | `context handleAuth -T` gives the same structured view agents use |
-| **Developers** | Rename a function, break 14 call sites silently | `diff-impact --staged` catches breakage before you commit |
 | **Architects** | Draw boundary rules that erode within weeks | `manifesto` and `boundaries` enforce architecture rules on every commit |
 
 ### Feature comparison
@@ -117,9 +115,9 @@ No config files, no Docker, no JVM, no API keys, no accounts. Point your agent a
 | | Differentiator | In practice |
 |---|---|---|
 | **🤖** | **AI-first architecture** | 30-tool [MCP server](https://modelcontextprotocol.io/) — agents query the graph directly instead of scraping the filesystem. One call replaces 20+ grep/find/cat invocations |
-| **🏷️** | **Role classification** | Every symbol auto-tagged as `entry`/`core`/`utility`/`adapter`/`dead`/`leaf` — agents instantly know what they're looking at without reading the code |
+| **🏷️** | **Role classification** | Every symbol auto-tagged as `entry`/`core`/`utility`/`adapter`/`dead`/`leaf` — agents understand a symbol's architectural role without reading surrounding code |
 | **🔬** | **Function-level, not just files** | Traces `handleAuth()` → `validateToken()` → `decryptJWT()` and shows 14 callers across 9 files break if `decryptJWT` changes |
-| **⚡** | **Always-fresh graph** | Three-tier change detection: journal (O(changed)) → mtime+size (O(n) stats) → hash (O(changed) reads). Sub-second rebuilds — agents always work with current data |
+| **⚡** | **Always-fresh graph** | Three-tier change detection: journal (O(changed)) → mtime+size (O(n) stats) → hash (O(changed) reads). Sub-second rebuilds — agents work with current data |
 | **💥** | **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 |
 | **🌐** | **Multi-language, one graph** | JS/TS + Python + Go + Rust + Java + C# + PHP + Ruby + HCL in a single graph — agents don't need per-language tools |
 | **🧠** | **Hybrid search** | BM25 keyword + semantic embeddings fused via RRF — `hybrid` (default), `semantic`, or `keyword` mode; multi-query via `"auth; token; JWT"` |
@@ -479,6 +477,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) |
@@ -562,14 +562,14 @@ Self-measured on every release via CI ([build benchmarks](generated/benchmarks/B
 
 | Metric | Latest |
 |---|---|
-| Build speed (native) | **5.2 ms/file** |
-| Build speed (WASM) | **15 ms/file** |
-| Query time | **4ms** |
-| No-op rebuild (native) | **6ms** |
-| 1-file rebuild (native) | **296ms** |
-| Query: fn-deps | **0.8ms** |
-| Query: path | **0.8ms** |
-| ~50,000 files (est.) | **~260.0s build** |
+| 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.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.
 
@@ -605,16 +605,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
 
@@ -622,65 +622,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
@@ -823,7 +777,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** — parser plugin system, repository pattern, pipeline builder, engine strategy, domain errors, curated API
+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,17 @@
 {
   "name": "@optave/codegraph",
-  "version": "3.1.3",
+  "version": "3.1.5",
   "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"
     },
     "./package.json": "./package.json"
   },
@@ -71,12 +76,12 @@
   },
   "optionalDependencies": {
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@optave/codegraph-darwin-arm64": "3.1.3",
-    "@optave/codegraph-darwin-x64": "3.1.3",
-    "@optave/codegraph-linux-arm64-gnu": "3.1.3",
-    "@optave/codegraph-linux-x64-gnu": "3.1.3",
-    "@optave/codegraph-linux-x64-musl": "3.1.3",
-    "@optave/codegraph-win32-x64-msvc": "3.1.3"
+    "@optave/codegraph-darwin-arm64": "3.1.5",
+    "@optave/codegraph-darwin-x64": "3.1.5",
+    "@optave/codegraph-linux-arm64-gnu": "3.1.5",
+    "@optave/codegraph-linux-x64-gnu": "3.1.5",
+    "@optave/codegraph-linux-x64-musl": "3.1.5",
+    "@optave/codegraph-win32-x64-msvc": "3.1.5"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.4",

package/src/ast-analysis/engine.js

@@ -17,8 +17,8 @@
 
 import path from 'node:path';
 import { performance } from 'node:perf_hooks';
-import { bulkNodeIdsByFile } from '../db.js';
-import { debug } from '../logger.js';
+import { bulkNodeIdsByFile } from '../db/index.js';
+import { debug } from '../infrastructure/logger.js';
 import { computeLOCMetrics, computeMaintainabilityIndex } from './metrics.js';
 import {
   AST_TYPE_MAPS,
@@ -38,6 +38,7 @@ import { createDataflowVisitor } from './visitors/dataflow-visitor.js';
 // ─── Extension sets for quick language-support checks ────────────────────
 
 const CFG_EXTENSIONS = buildExtensionSet(CFG_RULES);
+const COMPLEXITY_EXTENSIONS = buildExtensionSet(COMPLEXITY_RULES);
 const DATAFLOW_EXTENSIONS = buildExtensionSet(DATAFLOW_RULES);
 const WALK_EXTENSIONS = buildExtensionSet(AST_TYPE_MAPS);
 
@@ -45,7 +46,7 @@ const WALK_EXTENSIONS = buildExtensionSet(AST_TYPE_MAPS);
 
 let _parserModule = null;
 async function getParserModule() {
-  if (!_parserModule) _parserModule = await import('../parser.js');
+  if (!_parserModule) _parserModule = await import('../domain/parser.js');
   return _parserModule;
 }
 
@@ -74,15 +75,34 @@ export async function runAnalyses(db, fileSymbols, rootDir, opts, engineOpts) {
   const extToLang = buildExtToLangMap();
 
   // ── WASM pre-parse for files that need it ───────────────────────────
-  // CFG now runs as a visitor in the unified walk, so only dataflow
-  // triggers WASM pre-parse when no tree exists.
-  if (doDataflow) {
+  // The native engine only handles parsing (symbols, calls, imports).
+  // Complexity, CFG, and dataflow all require a WASM tree-sitter tree
+  // for their visitor walks. Without this, incremental rebuilds on the
+  // native engine silently lose these analyses for changed files (#468).
+  if (doComplexity || doCfg || doDataflow) {
     let needsWasmTrees = false;
     for (const [relPath, symbols] of fileSymbols) {
       if (symbols._tree) continue;
       const ext = path.extname(relPath).toLowerCase();
-
-      if (!symbols.dataflow && DATAFLOW_EXTENSIONS.has(ext)) {
+      const defs = symbols.definitions || [];
+
+      const needsComplexity =
+        doComplexity &&
+        COMPLEXITY_EXTENSIONS.has(ext) &&
+        defs.some((d) => (d.kind === 'function' || d.kind === 'method') && d.line && !d.complexity);
+      const needsCfg =
+        doCfg &&
+        CFG_EXTENSIONS.has(ext) &&
+        defs.some(
+          (d) =>
+            (d.kind === 'function' || d.kind === 'method') &&
+            d.line &&
+            d.cfg !== null &&
+            !Array.isArray(d.cfg?.blocks),
+        );
+      const needsDataflow = doDataflow && !symbols.dataflow && DATAFLOW_EXTENSIONS.has(ext);
+
+      if (needsComplexity || needsCfg || needsDataflow) {
         needsWasmTrees = true;
         break;
       }
@@ -320,7 +340,7 @@ export async function runAnalyses(db, fileSymbols, rootDir, opts, engineOpts) {
   if (doAst) {
     const t0 = performance.now();
     try {
-      const { buildAstNodes } = await import('../ast.js');
+      const { buildAstNodes } = await import('../features/ast.js');
       await buildAstNodes(db, fileSymbols, rootDir, engineOpts);
     } catch (err) {
       debug(`buildAstNodes failed: ${err.message}`);
@@ -331,7 +351,7 @@ export async function runAnalyses(db, fileSymbols, rootDir, opts, engineOpts) {
   if (doComplexity) {
     const t0 = performance.now();
     try {
-      const { buildComplexityMetrics } = await import('../complexity.js');
+      const { buildComplexityMetrics } = await import('../features/complexity.js');
       await buildComplexityMetrics(db, fileSymbols, rootDir, engineOpts);
     } catch (err) {
       debug(`buildComplexityMetrics failed: ${err.message}`);
@@ -342,7 +362,7 @@ export async function runAnalyses(db, fileSymbols, rootDir, opts, engineOpts) {
   if (doCfg) {
     const t0 = performance.now();
     try {
-      const { buildCFGData } = await import('../cfg.js');
+      const { buildCFGData } = await import('../features/cfg.js');
       await buildCFGData(db, fileSymbols, rootDir, engineOpts);
     } catch (err) {
       debug(`buildCFGData failed: ${err.message}`);
@@ -353,7 +373,7 @@ export async function runAnalyses(db, fileSymbols, rootDir, opts, engineOpts) {
   if (doDataflow) {
     const t0 = performance.now();
     try {
-      const { buildDataflowEdges } = await import('../dataflow.js');
+      const { buildDataflowEdges } = await import('../features/dataflow.js');
       await buildDataflowEdges(db, fileSymbols, rootDir, engineOpts);
     } catch (err) {
       debug(`buildDataflowEdges failed: ${err.message}`);

package/src/ast-analysis/shared.js

@@ -2,7 +2,8 @@
  * Shared utilities for AST analysis modules (complexity, CFG, dataflow, AST nodes).
  */
 
-import { LANGUAGE_REGISTRY } from '../parser.js';
+import { LANGUAGE_REGISTRY } from '../domain/parser.js';
+import { ConfigError } from '../shared/errors.js';
 
 // ─── Generic Rule Factory ─────────────────────────────────────────────────
 
@@ -18,7 +19,7 @@ export function makeRules(defaults, overrides, label) {
   const validKeys = new Set(Object.keys(defaults));
   for (const key of Object.keys(overrides)) {
     if (!validKeys.has(key)) {
-      throw new Error(`${label} rules: unknown key "${key}"`);
+      throw new ConfigError(`${label} rules: unknown key "${key}"`);
     }
   }
   return { ...defaults, ...overrides };
@@ -61,10 +62,10 @@ export const CFG_DEFAULTS = {
 export function makeCfgRules(overrides) {
   const rules = makeRules(CFG_DEFAULTS, overrides, 'CFG');
   if (!(rules.functionNodes instanceof Set) || rules.functionNodes.size === 0) {
-    throw new Error('CFG rules: functionNodes must be a non-empty Set');
+    throw new ConfigError('CFG rules: functionNodes must be a non-empty Set');
   }
   if (!(rules.forNodes instanceof Set)) {
-    throw new Error('CFG rules: forNodes must be a Set');
+    throw new ConfigError('CFG rules: forNodes must be a Set');
   }
   return rules;
 }
@@ -136,7 +137,7 @@ export const DATAFLOW_DEFAULTS = {
 export function makeDataflowRules(overrides) {
   const rules = makeRules(DATAFLOW_DEFAULTS, overrides, 'Dataflow');
   if (!(rules.functionNodes instanceof Set) || rules.functionNodes.size === 0) {
-    throw new Error('Dataflow rules: functionNodes must be a non-empty Set');
+    throw new ConfigError('Dataflow rules: functionNodes must be a non-empty Set');
   }
   return rules;
 }

package/src/cli/commands/ast.js

@@ -0,0 +1,22 @@
+import { ConfigError } from '../../shared/errors.js';
+
+export const command = {
+  name: 'ast [pattern]',
+  description: 'Search stored AST nodes (calls, new, string, regex, throw, await) by pattern',
+  queryOpts: true,
+  options: [
+    ['-k, --kind <kind>', 'Filter by AST node kind (call, new, string, regex, throw, await)'],
+    ['-f, --file <path>', 'Scope to file (partial match)'],
+  ],
+  async execute([pattern], opts, ctx) {
+    const { AST_NODE_KINDS, astQuery } = await import('../../ast.js');
+    if (opts.kind && !AST_NODE_KINDS.includes(opts.kind)) {
+      throw new ConfigError(`Invalid AST kind "${opts.kind}". Valid: ${AST_NODE_KINDS.join(', ')}`);
+    }
+    astQuery(pattern, opts.db, {
+      kind: opts.kind,
+      file: opts.file,
+      ...ctx.resolveQueryOpts(opts),
+    });
+  },
+};

package/src/cli/commands/audit.js

@@ -0,0 +1,45 @@
+import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
+import { audit } from '../../presentation/audit.js';
+import { explain } from '../../presentation/queries-cli.js';
+import { config } from '../shared/options.js';
+
+export const command = {
+  name: 'audit <target>',
+  description: 'Composite report: explain + impact + health metrics per function',
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['--quick', 'Structural summary only (skip impact analysis and health metrics)'],
+    ['--depth <n>', 'Impact/explain depth', '3'],
+    ['-f, --file <path>', 'Scope to file (partial match)'],
+    ['-k, --kind <kind>', 'Filter by symbol kind'],
+    ['-T, --no-tests', 'Exclude test/spec files from results'],
+    ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
+    ['-j, --json', 'Output as JSON'],
+    ['--limit <number>', 'Max results to return (quick mode)'],
+    ['--offset <number>', 'Skip N results (quick mode)'],
+    ['--ndjson', 'Newline-delimited JSON output (quick mode)'],
+  ],
+  validate([_target], opts) {
+    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+      return `Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`;
+    }
+  },
+  execute([target], opts, ctx) {
+    const qOpts = ctx.resolveQueryOpts(opts);
+    if (opts.quick) {
+      explain(target, opts.db, {
+        depth: parseInt(opts.depth, 10),
+        ...qOpts,
+      });
+      return;
+    }
+    audit(target, opts.db, {
+      depth: parseInt(opts.depth, 10),
+      file: opts.file,
+      kind: opts.kind,
+      noTests: qOpts.noTests,
+      json: qOpts.json,
+      config,
+    });
+  },
+};

package/src/cli/commands/batch.js

@@ -0,0 +1,68 @@
+import fs from 'node:fs';
+import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
+import { BATCH_COMMANDS, multiBatchData, splitTargets } from '../../features/batch.js';
+import { batch } from '../../presentation/batch.js';
+import { ConfigError } from '../../shared/errors.js';
+
+export const command = {
+  name: 'batch <command> [targets...]',
+  description: `Run a query against multiple targets in one call. Output is always JSON.\nValid commands: ${Object.keys(BATCH_COMMANDS).join(', ')}`,
+  options: [
+    ['-d, --db <path>', 'Path to graph.db'],
+    ['--from-file <path>', 'Read targets from file (JSON array or newline-delimited)'],
+    ['--stdin', 'Read targets from stdin (JSON array)'],
+    ['--depth <n>', 'Traversal depth passed to underlying command'],
+    ['-f, --file <path>', 'Scope to file (partial match)'],
+    ['-k, --kind <kind>', 'Filter by symbol kind'],
+    ['-T, --no-tests', 'Exclude test/spec files from results'],
+    ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
+  ],
+  validate([_command, _targets], opts) {
+    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+      return `Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`;
+    }
+  },
+  async execute([command, positionalTargets], opts, ctx) {
+    let targets;
+    try {
+      if (opts.fromFile) {
+        const raw = fs.readFileSync(opts.fromFile, 'utf-8').trim();
+        if (raw.startsWith('[')) {
+          targets = JSON.parse(raw);
+        } else {
+          targets = raw.split(/\r?\n/).filter(Boolean);
+        }
+      } else if (opts.stdin) {
+        const chunks = [];
+        for await (const chunk of process.stdin) chunks.push(chunk);
+        const raw = Buffer.concat(chunks).toString('utf-8').trim();
+        targets = raw.startsWith('[') ? JSON.parse(raw) : raw.split(/\r?\n/).filter(Boolean);
+      } else {
+        targets = splitTargets(positionalTargets);
+      }
+    } catch (err) {
+      throw new ConfigError(`Failed to parse targets: ${err.message}`, { cause: err });
+    }
+
+    if (!targets || targets.length === 0) {
+      throw new ConfigError(
+        'No targets provided. Pass targets as arguments, --from-file, or --stdin.',
+      );
+    }
+
+    const batchOpts = {
+      depth: opts.depth ? parseInt(opts.depth, 10) : undefined,
+      file: opts.file,
+      kind: opts.kind,
+      noTests: ctx.resolveNoTests(opts),
+    };
+
+    const isMulti = targets.length > 0 && typeof targets[0] === 'object' && targets[0].command;
+    if (isMulti) {
+      const data = multiBatchData(targets, opts.db, batchOpts);
+      console.log(JSON.stringify(data, null, 2));
+    } else {
+      batch(command, targets, opts.db, batchOpts);
+    }
+  },
+};

package/src/cli/commands/branch-compare.js

@@ -0,0 +1,21 @@
+export const command = {
+  name: 'branch-compare <base> <target>',
+  description: 'Compare code structure between two branches/refs',
+  options: [
+    ['--depth <n>', 'Max transitive caller depth', '3'],
+    ['-T, --no-tests', 'Exclude test/spec files'],
+    ['--include-tests', 'Include test/spec files (overrides excludeTests config)'],
+    ['-j, --json', 'Output as JSON'],
+    ['-f, --format <format>', 'Output format: text, mermaid, json', 'text'],
+  ],
+  async execute([base, target], opts, ctx) {
+    const { branchCompare } = await import('../../presentation/branch-compare.js');
+    await branchCompare(base, target, {
+      engine: ctx.program.opts().engine,
+      depth: parseInt(opts.depth, 10),
+      noTests: ctx.resolveNoTests(opts),
+      json: opts.json,
+      format: opts.format,
+    });
+  },
+};

package/src/cli/commands/build.js

@@ -0,0 +1,26 @@
+import path from 'node:path';
+import { buildGraph } from '../../domain/graph/builder.js';
+
+export const command = {
+  name: 'build [dir]',
+  description: 'Parse repo and build graph in .codegraph/graph.db',
+  options: [
+    ['--no-incremental', 'Force full rebuild (ignore file hashes)'],
+    ['--no-ast', 'Skip AST node extraction (calls, new, string, regex, throw, await)'],
+    ['--no-complexity', 'Skip complexity metrics computation'],
+    ['--no-dataflow', 'Skip data flow edge extraction'],
+    ['--no-cfg', 'Skip control flow graph building'],
+  ],
+  async execute([dir], opts, ctx) {
+    const root = path.resolve(dir || '.');
+    const engine = ctx.program.opts().engine;
+    await buildGraph(root, {
+      incremental: opts.incremental,
+      ast: opts.ast,
+      complexity: opts.complexity,
+      engine,
+      dataflow: opts.dataflow,
+      cfg: opts.cfg,
+    });
+  },
+};

package/src/cli/commands/cfg.js

@@ -0,0 +1,26 @@
+import { EVERY_SYMBOL_KIND } from '../../domain/queries.js';
+
+export const command = {
+  name: 'cfg <name>',
+  description: 'Show control flow graph for a function',
+  queryOpts: true,
+  options: [
+    ['--format <fmt>', 'Output format: text, dot, mermaid', 'text'],
+    ['-f, --file <path>', 'Scope to file (partial match)'],
+    ['-k, --kind <kind>', 'Filter by symbol kind'],
+  ],
+  validate([_name], opts) {
+    if (opts.kind && !EVERY_SYMBOL_KIND.includes(opts.kind)) {
+      return `Invalid kind "${opts.kind}". Valid: ${EVERY_SYMBOL_KIND.join(', ')}`;
+    }
+  },
+  async execute([name], opts, ctx) {
+    const { cfg } = await import('../../presentation/cfg.js');
+    cfg(name, opts.db, {
+      format: opts.format,
+      file: opts.file,
+      kind: opts.kind,
+      ...ctx.resolveQueryOpts(opts),
+    });
+  },
+};