@optave/codegraph 2.4.0 → 2.5.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 19 MCP tools.
+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).
 
 ### Why it matters
 
@@ -97,7 +97,7 @@ 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** | 19-tool [MCP server](https://modelcontextprotocol.io/) — AI assistants query your graph directly. Single-repo by default |
+| **🤖** | **Built for AI agents** | 24-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"` |
@@ -144,7 +144,7 @@ After modifying code:
 Or connect directly via MCP:
 
 ```bash
-codegraph mcp          # 19-tool MCP server — AI queries the graph directly
+codegraph mcp          # 24-tool MCP server — AI queries the graph directly
 ```
 
 Full agent setup: [AI Agent Guide](docs/guides/ai-agent-guide.md) · [CLAUDE.md template](docs/guides/ai-agent-guide.md#claudemd-template)
@@ -158,7 +158,7 @@ Full agent setup: [AI Agent Guide](docs/guides/ai-agent-guide.md) · [CLAU
 | 🔍 | **Symbol search** | Find any function, class, or method by name — exact match priority, relevance scoring, `--file` and `--kind` filters |
 | 📁 | **File dependencies** | See what a file imports and what imports it |
 | 💥 | **Impact analysis** | Trace every file affected by a change (transitive) |
-| 🧬 | **Function-level tracing** | Call chains, caller trees, and function-level impact with qualified call resolution |
+| 🧬 | **Function-level tracing** | Call chains, caller trees, function-level impact, and A→B pathfinding with qualified call resolution |
 | 🎯 | **Deep context** | `context` gives AI agents source, deps, callers, signature, and tests for a function in one call; `explain` gives structural summaries of files or functions |
 | 📍 | **Fast lookup** | `where` shows exactly where a symbol is defined and used — minimal, fast |
 | 📊 | **Diff impact** | Parse `git diff`, find overlapping functions, trace their callers |
@@ -170,8 +170,11 @@ Full agent setup: [AI Agent Guide](docs/guides/ai-agent-guide.md) · [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** | 19-tool MCP server for AI assistants; single-repo by default, opt-in multi-repo |
+| 🤖 | **MCP server** | 24-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) |
 
 See [docs/examples](docs/examples) for real-world CLI and MCP usage examples.
 
@@ -217,6 +220,9 @@ codegraph impact <file>        # Transitive reverse dependency trace
 codegraph fn <name>            # Function-level: callers, callees, call chain
 codegraph fn <name> --no-tests --depth 5
 codegraph fn-impact <name>     # What functions break if this one changes
+codegraph path <from> <to>     # Shortest path between two symbols (A calls...calls B)
+codegraph path <from> <to> --reverse  # Follow edges backward
+codegraph path <from> <to> --max-depth 5 --kinds calls,imports
 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
@@ -247,6 +253,20 @@ codegraph hotspots             # Files with extreme fan-in, fan-out, or density
 codegraph hotspots --metric coupling --level directory --no-tests
 ```
 
+### Code Health & Architecture
+
+```bash
+codegraph complexity              # Per-function cognitive, cyclomatic, nesting, MI
+codegraph complexity --health -T  # Full Halstead health view (volume, effort, bugs, MI)
+codegraph complexity --sort mi -T # Sort by worst maintainability index
+codegraph complexity --above-threshold -T  # Only functions exceeding warn thresholds
+codegraph communities             # Louvain community detection — natural module boundaries
+codegraph communities --drift -T  # Drift analysis only — split/merge candidates
+codegraph communities --functions # Function-level community detection
+codegraph manifesto               # Pass/fail rule engine (exit code 1 on fail)
+codegraph manifesto -T            # Exclude test files from rule evaluation
+```
+
 ### Export & Visualization
 
 ```bash
@@ -316,7 +336,7 @@ 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`, `context`, `explain`, `where`, `diff-impact`, `search`, `map`, `hotspots`, `deps`, `impact`) |
+| `-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`) |
 | `--depth <n>` | Transitive trace depth (default varies by command) |
 | `-j, --json` | Output as JSON |
 | `-v, --verbose` | Enable debug output |
@@ -403,10 +423,12 @@ Self-measured on every release via CI ([build benchmarks](generated/BUILD-BENCHM
 
 | Metric | Latest |
 |---|---|
-| Build speed (native) | **1.9 ms/file** |
-| Build speed (WASM) | **6.6 ms/file** |
+| Build speed | **5.1 ms/file** |
 | Query time | **2ms** |
-| ~50,000 files (est.) | **~95.0s build** |
+| No-op rebuild | **5ms** |
+| 1-file rebuild | **192ms** |
+| Query: fn-deps | **0.5ms** |
+| ~50,000 files (est.) | **~255.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.
 
@@ -428,7 +450,7 @@ Optional: `@huggingface/transformers` (semantic search), `@modelcontextprotocol/
 
 ### MCP Server
 
-Codegraph includes a built-in [Model Context Protocol](https://modelcontextprotocol.io/) server with 19 tools, so AI assistants can query your dependency graph directly:
+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:
 
 ```bash
 codegraph mcp                  # Single-repo mode (default) — only local project
@@ -462,7 +484,14 @@ This project uses codegraph. The database is at `.codegraph/graph.db`.
 - `codegraph build .` — rebuild the graph (incremental by default)
 - `codegraph map` — module overview
 - `codegraph fn <name> -T` — function call chain
+- `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 manifesto -T` — pass/fail rule check (CI gate, exit code 1 on fail)
 - `codegraph search "<query>"` — semantic search (requires `codegraph embed`)
 - `codegraph cycles` — check for circular dependencies
 
@@ -534,10 +563,35 @@ Create a `.codegraphrc.json` in your project root to customize behavior:
   },
   "build": {
     "incremental": true
+  },
+  "query": {
+    "excludeTests": true
   }
 }
 ```
 
+> **Tip:** `excludeTests` can also be set at the top level as a shorthand — `{ "excludeTests": true }` is equivalent to nesting it under `query`. If both are present, the nested `query.excludeTests` takes precedence.
+
+### Manifesto rules
+
+Configure pass/fail thresholds for `codegraph manifesto`:
+
+```json
+{
+  "manifesto": {
+    "rules": {
+      "cognitive_complexity": { "warn": 15, "fail": 30 },
+      "cyclomatic_complexity": { "warn": 10, "fail": 20 },
+      "nesting_depth": { "warn": 4, "fail": 6 },
+      "maintainability_index": { "warn": 40, "fail": 20 },
+      "halstead_bugs": { "warn": 0.5, "fail": 1.0 }
+    }
+  }
+}
+```
+
+When any function exceeds a `fail` threshold, `codegraph manifesto` exits with code 1 — perfect for CI gates.
+
 ### LLM credentials
 
 Codegraph supports an `apiKeyCommand` field for secure credential management. Instead of storing API keys in config files or environment variables, you can shell out to a secret manager at runtime:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@optave/codegraph",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "Local code graph CLI — parse codebases with tree-sitter, build dependency graphs, query them",
   "type": "module",
   "main": "src/index.js",
@@ -57,14 +57,24 @@
   "dependencies": {
     "better-sqlite3": "^12.6.2",
     "commander": "^14.0.3",
+    "graphology": "^0.25.4",
+    "graphology-communities-louvain": "^2.0.2",
     "web-tree-sitter": "^0.26.5"
   },
+  "peerDependencies": {
+    "@huggingface/transformers": "^3.8.1"
+  },
+  "peerDependenciesMeta": {
+    "@huggingface/transformers": {
+      "optional": true
+    }
+  },
   "optionalDependencies": {
-    "@huggingface/transformers": "^3.8.1",
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "@optave/codegraph-darwin-arm64": "2.4.0",
-    "@optave/codegraph-darwin-x64": "2.4.0",
-    "@optave/codegraph-linux-x64-gnu": "2.4.0"
+    "@optave/codegraph-darwin-arm64": "2.5.0",
+    "@optave/codegraph-darwin-x64": "2.5.0",
+    "@optave/codegraph-linux-x64-gnu": "2.5.0",
+    "@optave/codegraph-win32-x64-msvc": "2.5.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.4",

package/src/builder.js

@@ -1,9 +1,10 @@
 import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import { performance } from 'node:perf_hooks';
 import { loadConfig } from './config.js';
 import { EXTENSIONS, IGNORE_DIRS, normalizePath } from './constants.js';
-import { initSchema, openDb } from './db.js';
+import { closeDb, getBuildMeta, initSchema, openDb, setBuildMeta } from './db.js';
 import { readJournal, writeJournalHeader } from './journal.js';
 import { debug, info, warn } from './logger.js';
 import { getActiveEngine, parseFilesAuto } from './parser.js';
@@ -11,6 +12,11 @@ import { computeConfidence, resolveImportPath, resolveImportsBatch } from './res
 
 export { resolveImportPath } from './resolve.js';
 
+const __builderDir = path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Z]:)/i, '$1'));
+const CODEGRAPH_VERSION = JSON.parse(
+  fs.readFileSync(path.join(__builderDir, '..', 'package.json'), 'utf-8'),
+).version;
+
 const BUILTIN_RECEIVERS = new Set([
   'console',
   'Math',
@@ -346,6 +352,22 @@ export async function buildGraph(rootDir, opts = {}) {
   const { name: engineName, version: engineVersion } = getActiveEngine(engineOpts);
   info(`Using ${engineName} engine${engineVersion ? ` (v${engineVersion})` : ''}`);
 
+  // Check for engine/version mismatch on incremental builds
+  if (incremental) {
+    const prevEngine = getBuildMeta(db, 'engine');
+    const prevVersion = getBuildMeta(db, 'codegraph_version');
+    if (prevEngine && prevEngine !== engineName) {
+      warn(
+        `Engine changed (${prevEngine} → ${engineName}). Consider rebuilding with --no-incremental for consistency.`,
+      );
+    }
+    if (prevVersion && prevVersion !== CODEGRAPH_VERSION) {
+      warn(
+        `Codegraph version changed (${prevVersion} → ${CODEGRAPH_VERSION}). Consider rebuilding with --no-incremental for consistency.`,
+      );
+    }
+  }
+
   const aliases = loadPathAliases(rootDir);
   // Merge config aliases
   if (config.aliases) {
@@ -397,7 +419,7 @@ export async function buildGraph(rootDir, opts = {}) {
       }
     }
     info('No changes detected. Graph is up to date.');
-    db.close();
+    closeDb(db);
     writeJournalHeader(rootDir, Date.now());
     return;
   }
@@ -420,7 +442,45 @@ export async function buildGraph(rootDir, opts = {}) {
         : deletions,
     );
   } else {
-    info(`Incremental: ${parseChanges.length} changed, ${removed.length} removed`);
+    // ── Reverse-dependency cascade (issue #116) ─────────────────────
+    // Find files with edges pointing TO changed/removed files.
+    // Their nodes stay intact (preserving IDs), but outgoing edges are
+    // deleted so they can be rebuilt during the edge-building pass.
+    const changedRelPaths = new Set();
+    for (const item of parseChanges) {
+      changedRelPaths.add(item.relPath || normalizePath(path.relative(rootDir, item.file)));
+    }
+    for (const relPath of removed) {
+      changedRelPaths.add(relPath);
+    }
+
+    const reverseDeps = new Set();
+    if (changedRelPaths.size > 0) {
+      const findReverseDeps = db.prepare(`
+        SELECT DISTINCT n_src.file FROM edges e
+        JOIN nodes n_src ON e.source_id = n_src.id
+        JOIN nodes n_tgt ON e.target_id = n_tgt.id
+        WHERE n_tgt.file = ? AND n_src.file != n_tgt.file
+      `);
+      for (const relPath of changedRelPaths) {
+        for (const row of findReverseDeps.all(relPath)) {
+          if (!changedRelPaths.has(row.file) && !reverseDeps.has(row.file)) {
+            // Verify the file still exists on disk
+            const absPath = path.join(rootDir, row.file);
+            if (fs.existsSync(absPath)) {
+              reverseDeps.add(row.file);
+            }
+          }
+        }
+      }
+    }
+
+    info(
+      `Incremental: ${parseChanges.length} changed, ${removed.length} removed${reverseDeps.size > 0 ? `, ${reverseDeps.size} reverse-deps` : ''}`,
+    );
+    if (parseChanges.length > 0)
+      debug(`Changed files: ${parseChanges.map((c) => c.relPath).join(', ')}`);
+    if (removed.length > 0) debug(`Removed files: ${removed.join(', ')}`);
     // Remove embeddings/metrics/edges/nodes for changed and removed files
     // Embeddings must be deleted BEFORE nodes (we need node IDs to find them)
     const deleteEmbeddingsForFile = hasEmbeddings
@@ -431,13 +491,25 @@ export async function buildGraph(rootDir, opts = {}) {
       DELETE FROM edges WHERE source_id IN (SELECT id FROM nodes WHERE file = @f)
       OR target_id IN (SELECT id FROM nodes WHERE file = @f)
     `);
+    const deleteOutgoingEdgesForFile = db.prepare(
+      'DELETE FROM edges WHERE source_id IN (SELECT id FROM nodes WHERE file = ?)',
+    );
     const deleteMetricsForFile = db.prepare(
       'DELETE FROM node_metrics WHERE node_id IN (SELECT id FROM nodes WHERE file = ?)',
     );
+    let deleteComplexityForFile;
+    try {
+      deleteComplexityForFile = db.prepare(
+        'DELETE FROM function_complexity WHERE node_id IN (SELECT id FROM nodes WHERE file = ?)',
+      );
+    } catch {
+      deleteComplexityForFile = null;
+    }
     for (const relPath of removed) {
       deleteEmbeddingsForFile?.run(relPath);
       deleteEdgesForFile.run({ f: relPath });
       deleteMetricsForFile.run(relPath);
+      deleteComplexityForFile?.run(relPath);
       deleteNodesForFile.run(relPath);
     }
     for (const item of parseChanges) {
@@ -445,8 +517,19 @@ export async function buildGraph(rootDir, opts = {}) {
       deleteEmbeddingsForFile?.run(relPath);
       deleteEdgesForFile.run({ f: relPath });
       deleteMetricsForFile.run(relPath);
+      deleteComplexityForFile?.run(relPath);
       deleteNodesForFile.run(relPath);
     }
+
+    // Process reverse deps: delete only outgoing edges (nodes/IDs preserved)
+    // then add them to the parse list so they participate in edge building
+    for (const relPath of reverseDeps) {
+      deleteOutgoingEdgesForFile.run(relPath);
+    }
+    for (const relPath of reverseDeps) {
+      const absPath = path.join(rootDir, relPath);
+      parseChanges.push({ file: absPath, relPath, _reverseDepOnly: true });
+    }
   }
 
   const insertNode = db.prepare(
@@ -483,9 +566,14 @@ export async function buildGraph(rootDir, opts = {}) {
 
   const filesToParse = isFullBuild ? files.map((f) => ({ file: f })) : parseChanges;
 
+  // ── Phase timing ────────────────────────────────────────────────────
+  const _t = {};
+
   // ── Unified parse via parseFilesAuto ───────────────────────────────
   const filePaths = filesToParse.map((item) => item.file);
+  _t.parse0 = performance.now();
   const allSymbols = await parseFilesAuto(filePaths, rootDir, engineOpts);
+  _t.parseMs = performance.now() - _t.parse0;
 
   // Build a lookup from incremental data (changed items may carry pre-computed hashes + stats)
   const precomputedData = new Map();
@@ -508,9 +596,12 @@ export async function buildGraph(rootDir, opts = {}) {
       }
 
       // Update file hash with real mtime+size for incremental builds
+      // Skip for reverse-dep files — they didn't actually change
       if (upsertHash) {
         const precomputed = precomputedData.get(relPath);
-        if (precomputed?.hash) {
+        if (precomputed?._reverseDepOnly) {
+          // no-op: file unchanged, hash already correct
+        } else if (precomputed?.hash) {
           const stat = precomputed.stat || fileStat(path.join(rootDir, relPath));
           const mtime = stat ? Math.floor(stat.mtimeMs) : 0;
           const size = stat ? stat.size : 0;
@@ -542,7 +633,9 @@ export async function buildGraph(rootDir, opts = {}) {
       }
     }
   });
+  _t.insert0 = performance.now();
   insertAll();
+  _t.insertMs = performance.now() - _t.insert0;
 
   const parsed = allSymbols.size;
   const skipped = filesToParse.length - parsed;
@@ -558,6 +651,7 @@ export async function buildGraph(rootDir, opts = {}) {
 
   // ── Batch import resolution ────────────────────────────────────────
   // Collect all (fromFile, importSource) pairs and resolve in one native call
+  _t.resolve0 = performance.now();
   const batchInputs = [];
   for (const [relPath, symbols] of fileSymbols) {
     const absFile = path.join(rootDir, relPath);
@@ -566,6 +660,7 @@ export async function buildGraph(rootDir, opts = {}) {
     }
   }
   const batchResolved = resolveImportsBatch(batchInputs, rootDir, aliases);
+  _t.resolveMs = performance.now() - _t.resolve0;
 
   function getResolved(absFile, importSource) {
     if (batchResolved) {
@@ -653,6 +748,7 @@ export async function buildGraph(rootDir, opts = {}) {
   }
 
   // Second pass: build edges
+  _t.edges0 = performance.now();
   let edgeCount = 0;
   const buildEdges = db.transaction(() => {
     for (const [relPath, symbols] of fileSymbols) {
@@ -712,10 +808,26 @@ export async function buildGraph(rootDir, opts = {}) {
       for (const call of symbols.calls) {
         if (call.receiver && BUILTIN_RECEIVERS.has(call.receiver)) continue;
         let caller = null;
+        let callerSpan = Infinity;
         for (const def of symbols.definitions) {
           if (def.line <= call.line) {
-            const row = getNodeId.get(def.name, def.kind, relPath, def.line);
-            if (row) caller = row;
+            const end = def.endLine || Infinity;
+            if (call.line <= end) {
+              // Call is inside this definition's range — pick narrowest
+              const span = end - def.line;
+              if (span < callerSpan) {
+                const row = getNodeId.get(def.name, def.kind, relPath, def.line);
+                if (row) {
+                  caller = row;
+                  callerSpan = span;
+                }
+              }
+            } else if (!caller) {
+              // Fallback: def starts before call but call is past end
+              // Only use if we haven't found an enclosing scope yet
+              const row = getNodeId.get(def.name, def.kind, relPath, def.line);
+              if (row) caller = row;
+            }
           }
         }
         if (!caller) caller = fileNodeRow;
@@ -779,12 +891,12 @@ export async function buildGraph(rootDir, opts = {}) {
         }
       }
 
-      // Class extends edges
+      // Class extends edges (use pre-loaded maps instead of inline DB queries)
       for (const cls of symbols.classes) {
         if (cls.extends) {
-          const sourceRow = db
-            .prepare('SELECT id FROM nodes WHERE name = ? AND kind = ? AND file = ?')
-            .get(cls.name, 'class', relPath);
+          const sourceRow = (nodesByNameAndFile.get(`${cls.name}|${relPath}`) || []).find(
+            (n) => n.kind === 'class',
+          );
           const targetCandidates = nodesByName.get(cls.extends) || [];
           const targetRows = targetCandidates.filter((n) => n.kind === 'class');
           if (sourceRow) {
@@ -796,9 +908,9 @@ export async function buildGraph(rootDir, opts = {}) {
         }
 
         if (cls.implements) {
-          const sourceRow = db
-            .prepare('SELECT id FROM nodes WHERE name = ? AND kind = ? AND file = ?')
-            .get(cls.name, 'class', relPath);
+          const sourceRow = (nodesByNameAndFile.get(`${cls.name}|${relPath}`) || []).find(
+            (n) => n.kind === 'class',
+          );
           const targetCandidates = nodesByName.get(cls.implements) || [];
           const targetRows = targetCandidates.filter(
             (n) => n.kind === 'interface' || n.kind === 'class',
@@ -814,16 +926,21 @@ export async function buildGraph(rootDir, opts = {}) {
     }
   });
   buildEdges();
+  _t.edgesMs = performance.now() - _t.edges0;
 
-  // Build line count map for structure metrics
+  // Build line count map for structure metrics (prefer cached _lineCount from parser)
   const lineCountMap = new Map();
-  for (const [relPath] of fileSymbols) {
-    const absPath = path.join(rootDir, relPath);
-    try {
-      const content = fs.readFileSync(absPath, 'utf-8');
-      lineCountMap.set(relPath, content.split('\n').length);
-    } catch {
-      lineCountMap.set(relPath, 0);
+  for (const [relPath, symbols] of fileSymbols) {
+    if (symbols._lineCount) {
+      lineCountMap.set(relPath, symbols._lineCount);
+    } else {
+      const absPath = path.join(rootDir, relPath);
+      try {
+        const content = fs.readFileSync(absPath, 'utf-8');
+        lineCountMap.set(relPath, content.split('\n').length);
+      } catch {
+        lineCountMap.set(relPath, 0);
+      }
     }
   }
 
@@ -881,6 +998,7 @@ export async function buildGraph(rootDir, opts = {}) {
   }
 
   // Build directory structure, containment edges, and metrics
+  _t.structure0 = performance.now();
   const relDirs = new Set();
   for (const absDir of discoveredDirs) {
     relDirs.add(normalizePath(path.relative(rootDir, absDir)));
@@ -891,8 +1009,10 @@ export async function buildGraph(rootDir, opts = {}) {
   } catch (err) {
     debug(`Structure analysis failed: ${err.message}`);
   }
+  _t.structureMs = performance.now() - _t.structure0;
 
   // Classify node roles (entry, core, utility, adapter, dead, leaf)
+  _t.roles0 = performance.now();
   try {
     const { classifyNodeRoles } = await import('./structure.js');
     const roleSummary = classifyNodeRoles(db);
@@ -904,6 +1024,23 @@ export async function buildGraph(rootDir, opts = {}) {
   } catch (err) {
     debug(`Role classification failed: ${err.message}`);
   }
+  _t.rolesMs = performance.now() - _t.roles0;
+
+  // Compute per-function complexity metrics (cognitive, cyclomatic, nesting)
+  _t.complexity0 = performance.now();
+  try {
+    const { buildComplexityMetrics } = await import('./complexity.js');
+    await buildComplexityMetrics(db, allSymbols, rootDir, engineOpts);
+  } catch (err) {
+    debug(`Complexity analysis failed: ${err.message}`);
+  }
+  _t.complexityMs = performance.now() - _t.complexity0;
+
+  // Release any remaining cached WASM trees for GC
+  for (const [, symbols] of allSymbols) {
+    symbols._tree = null;
+    symbols._langId = null;
+  }
 
   const nodeCount = db.prepare('SELECT COUNT(*) as c FROM nodes').get().c;
   info(`Graph built: ${nodeCount} nodes, ${edgeCount} edges`);
@@ -925,7 +1062,19 @@ export async function buildGraph(rootDir, opts = {}) {
     }
   }
 
-  db.close();
+  // Persist build metadata for mismatch detection
+  try {
+    setBuildMeta(db, {
+      engine: engineName,
+      engine_version: engineVersion || '',
+      codegraph_version: CODEGRAPH_VERSION,
+      built_at: new Date().toISOString(),
+    });
+  } catch (err) {
+    warn(`Failed to write build metadata: ${err.message}`);
+  }
+
+  closeDb(db);
 
   // Write journal header after successful build
   writeJournalHeader(rootDir, Date.now());
@@ -945,4 +1094,16 @@ export async function buildGraph(rootDir, opts = {}) {
       }
     }
   }
+
+  return {
+    phases: {
+      parseMs: +_t.parseMs.toFixed(1),
+      insertMs: +_t.insertMs.toFixed(1),
+      resolveMs: +_t.resolveMs.toFixed(1),
+      edgesMs: +_t.edgesMs.toFixed(1),
+      structureMs: +_t.structureMs.toFixed(1),
+      rolesMs: +_t.rolesMs.toFixed(1),
+      complexityMs: +_t.complexityMs.toFixed(1),
+    },
+  };
 }