@optave/codegraph 3.1.3 → 3.1.4

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"` |
@@ -562,14 +560,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** |
+| 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) | **296ms** |
-| Query: fn-deps | **0.8ms** |
+| 1-file rebuild (native) | **282ms** |
+| Query: fn-deps | **0.9ms** |
 | Query: path | **0.8ms** |
-| ~50,000 files (est.) | **~260.0s build** |
+| ~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.
 
@@ -823,7 +821,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** — **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)
 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,6 +1,6 @@
 {
   "name": "@optave/codegraph",
-  "version": "3.1.3",
+  "version": "3.1.4",
   "description": "Local code graph CLI — parse codebases with tree-sitter, build dependency graphs, query them",
   "type": "module",
   "main": "src/index.js",
@@ -8,6 +8,9 @@
     ".": {
       "import": "./src/index.js"
     },
+    "./cli": {
+      "import": "./src/cli.js"
+    },
     "./package.json": "./package.json"
   },
   "bin": {
@@ -71,12 +74,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.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"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.4",

package/src/analysis/context.js

@@ -0,0 +1,408 @@
+import path from 'node:path';
+import {
+  findCallees,
+  findCallers,
+  findCrossFileCallTargets,
+  findDbPath,
+  findFileNodes,
+  findImportSources,
+  findImportTargets,
+  findIntraFileCallEdges,
+  findNodeChildren,
+  findNodesByFile,
+  getComplexityForNode,
+  openReadonlyOrFail,
+} from '../db.js';
+import { isTestFile } from '../infrastructure/test-filter.js';
+import { paginateResult } from '../paginate.js';
+import {
+  createFileLinesReader,
+  extractSignature,
+  extractSummary,
+  isFileLikeTarget,
+  readSourceRange,
+} from '../shared/file-utils.js';
+import { resolveMethodViaHierarchy } from '../shared/hierarchy.js';
+import { normalizeSymbol } from '../shared/normalize.js';
+import { findMatchingNodes } from './symbol-lookup.js';
+
+function explainFileImpl(db, target, getFileLines) {
+  const fileNodes = findFileNodes(db, `%${target}%`);
+  if (fileNodes.length === 0) return [];
+
+  return fileNodes.map((fn) => {
+    const symbols = findNodesByFile(db, fn.file);
+
+    // IDs of symbols that have incoming calls from other files (public)
+    const publicIds = findCrossFileCallTargets(db, fn.file);
+
+    const fileLines = getFileLines(fn.file);
+    const mapSymbol = (s) => ({
+      name: s.name,
+      kind: s.kind,
+      line: s.line,
+      role: s.role || null,
+      summary: fileLines ? extractSummary(fileLines, s.line) : null,
+      signature: fileLines ? extractSignature(fileLines, s.line) : null,
+    });
+
+    const publicApi = symbols.filter((s) => publicIds.has(s.id)).map(mapSymbol);
+    const internal = symbols.filter((s) => !publicIds.has(s.id)).map(mapSymbol);
+
+    // Imports / importedBy
+    const imports = findImportTargets(db, fn.id).map((r) => ({ file: r.file }));
+
+    const importedBy = findImportSources(db, fn.id).map((r) => ({ file: r.file }));
+
+    // Intra-file data flow
+    const intraEdges = findIntraFileCallEdges(db, fn.file);
+
+    const dataFlowMap = new Map();
+    for (const edge of intraEdges) {
+      if (!dataFlowMap.has(edge.caller_name)) dataFlowMap.set(edge.caller_name, []);
+      dataFlowMap.get(edge.caller_name).push(edge.callee_name);
+    }
+    const dataFlow = [...dataFlowMap.entries()].map(([caller, callees]) => ({
+      caller,
+      callees,
+    }));
+
+    // Line count: prefer node_metrics (actual), fall back to MAX(end_line)
+    const metric = db
+      .prepare(`SELECT nm.line_count FROM node_metrics nm WHERE nm.node_id = ?`)
+      .get(fn.id);
+    let lineCount = metric?.line_count || null;
+    if (!lineCount) {
+      const maxLine = db
+        .prepare(`SELECT MAX(end_line) as max_end FROM nodes WHERE file = ?`)
+        .get(fn.file);
+      lineCount = maxLine?.max_end || null;
+    }
+
+    return {
+      file: fn.file,
+      lineCount,
+      symbolCount: symbols.length,
+      publicApi,
+      internal,
+      imports,
+      importedBy,
+      dataFlow,
+    };
+  });
+}
+
+function explainFunctionImpl(db, target, noTests, getFileLines) {
+  let nodes = db
+    .prepare(
+      `SELECT * FROM nodes WHERE name LIKE ? AND kind IN ('function','method','class','interface','type','struct','enum','trait','record','module') ORDER BY file, line`,
+    )
+    .all(`%${target}%`);
+  if (noTests) nodes = nodes.filter((n) => !isTestFile(n.file));
+  if (nodes.length === 0) return [];
+
+  const hc = new Map();
+  return nodes.slice(0, 10).map((node) => {
+    const fileLines = getFileLines(node.file);
+    const lineCount = node.end_line ? node.end_line - node.line + 1 : null;
+    const summary = fileLines ? extractSummary(fileLines, node.line) : null;
+    const signature = fileLines ? extractSignature(fileLines, node.line) : null;
+
+    const callees = findCallees(db, node.id).map((c) => ({
+      name: c.name,
+      kind: c.kind,
+      file: c.file,
+      line: c.line,
+    }));
+
+    let callers = findCallers(db, node.id).map((c) => ({
+      name: c.name,
+      kind: c.kind,
+      file: c.file,
+      line: c.line,
+    }));
+    if (noTests) callers = callers.filter((c) => !isTestFile(c.file));
+
+    const testCallerRows = findCallers(db, node.id);
+    const seenFiles = new Set();
+    const relatedTests = testCallerRows
+      .filter((r) => isTestFile(r.file) && !seenFiles.has(r.file) && seenFiles.add(r.file))
+      .map((r) => ({ file: r.file }));
+
+    // Complexity metrics
+    let complexityMetrics = null;
+    try {
+      const cRow = getComplexityForNode(db, node.id);
+      if (cRow) {
+        complexityMetrics = {
+          cognitive: cRow.cognitive,
+          cyclomatic: cRow.cyclomatic,
+          maxNesting: cRow.max_nesting,
+          maintainabilityIndex: cRow.maintainability_index || 0,
+          halsteadVolume: cRow.halstead_volume || 0,
+        };
+      }
+    } catch {
+      /* table may not exist */
+    }
+
+    return {
+      ...normalizeSymbol(node, db, hc),
+      lineCount,
+      summary,
+      signature,
+      complexity: complexityMetrics,
+      callees,
+      callers,
+      relatedTests,
+    };
+  });
+}
+
+// ─── Exported functions ──────────────────────────────────────────────────
+
+export function contextData(name, customDbPath, opts = {}) {
+  const db = openReadonlyOrFail(customDbPath);
+  try {
+    const depth = opts.depth || 0;
+    const noSource = opts.noSource || false;
+    const noTests = opts.noTests || false;
+    const includeTests = opts.includeTests || false;
+
+    const dbPath = findDbPath(customDbPath);
+    const repoRoot = path.resolve(path.dirname(dbPath), '..');
+
+    const nodes = findMatchingNodes(db, name, { noTests, file: opts.file, kind: opts.kind });
+    if (nodes.length === 0) {
+      return { name, results: [] };
+    }
+
+    // No hardcoded slice — pagination handles bounding via limit/offset
+
+    const getFileLines = createFileLinesReader(repoRoot);
+
+    const results = nodes.map((node) => {
+      const fileLines = getFileLines(node.file);
+
+      // Source
+      const source = noSource
+        ? null
+        : readSourceRange(repoRoot, node.file, node.line, node.end_line);
+
+      // Signature
+      const signature = fileLines ? extractSignature(fileLines, node.line) : null;
+
+      // Callees
+      const calleeRows = findCallees(db, node.id);
+      const filteredCallees = noTests ? calleeRows.filter((c) => !isTestFile(c.file)) : calleeRows;
+
+      const callees = filteredCallees.map((c) => {
+        const cLines = getFileLines(c.file);
+        const summary = cLines ? extractSummary(cLines, c.line) : null;
+        let calleeSource = null;
+        if (depth >= 1) {
+          calleeSource = readSourceRange(repoRoot, c.file, c.line, c.end_line);
+        }
+        return {
+          name: c.name,
+          kind: c.kind,
+          file: c.file,
+          line: c.line,
+          endLine: c.end_line || null,
+          summary,
+          source: calleeSource,
+        };
+      });
+
+      // Deep callee expansion via BFS (depth > 1, capped at 5)
+      if (depth > 1) {
+        const visited = new Set(filteredCallees.map((c) => c.id));
+        visited.add(node.id);
+        let frontier = filteredCallees.map((c) => c.id);
+        const maxDepth = Math.min(depth, 5);
+        for (let d = 2; d <= maxDepth; d++) {
+          const nextFrontier = [];
+          for (const fid of frontier) {
+            const deeper = findCallees(db, fid);
+            for (const c of deeper) {
+              if (!visited.has(c.id) && (!noTests || !isTestFile(c.file))) {
+                visited.add(c.id);
+                nextFrontier.push(c.id);
+                const cLines = getFileLines(c.file);
+                callees.push({
+                  name: c.name,
+                  kind: c.kind,
+                  file: c.file,
+                  line: c.line,
+                  endLine: c.end_line || null,
+                  summary: cLines ? extractSummary(cLines, c.line) : null,
+                  source: readSourceRange(repoRoot, c.file, c.line, c.end_line),
+                });
+              }
+            }
+          }
+          frontier = nextFrontier;
+          if (frontier.length === 0) break;
+        }
+      }
+
+      // Callers
+      let callerRows = findCallers(db, node.id);
+
+      // Method hierarchy resolution
+      if (node.kind === 'method' && node.name.includes('.')) {
+        const methodName = node.name.split('.').pop();
+        const relatedMethods = resolveMethodViaHierarchy(db, methodName);
+        for (const rm of relatedMethods) {
+          if (rm.id === node.id) continue;
+          const extraCallers = findCallers(db, rm.id);
+          callerRows.push(...extraCallers.map((c) => ({ ...c, viaHierarchy: rm.name })));
+        }
+      }
+      if (noTests) callerRows = callerRows.filter((c) => !isTestFile(c.file));
+
+      const callers = callerRows.map((c) => ({
+        name: c.name,
+        kind: c.kind,
+        file: c.file,
+        line: c.line,
+        viaHierarchy: c.viaHierarchy || undefined,
+      }));
+
+      // Related tests: callers that live in test files
+      const testCallerRows = findCallers(db, node.id);
+      const testCallers = testCallerRows.filter((c) => isTestFile(c.file));
+
+      const testsByFile = new Map();
+      for (const tc of testCallers) {
+        if (!testsByFile.has(tc.file)) testsByFile.set(tc.file, []);
+        testsByFile.get(tc.file).push(tc);
+      }
+
+      const relatedTests = [];
+      for (const [file] of testsByFile) {
+        const tLines = getFileLines(file);
+        const testNames = [];
+        if (tLines) {
+          for (const tl of tLines) {
+            const tm = tl.match(/(?:it|test|describe)\s*\(\s*['"`]([^'"`]+)['"`]/);
+            if (tm) testNames.push(tm[1]);
+          }
+        }
+        const testSource = includeTests && tLines ? tLines.join('\n') : undefined;
+        relatedTests.push({
+          file,
+          testCount: testNames.length,
+          testNames,
+          source: testSource,
+        });
+      }
+
+      // Complexity metrics
+      let complexityMetrics = null;
+      try {
+        const cRow = getComplexityForNode(db, node.id);
+        if (cRow) {
+          complexityMetrics = {
+            cognitive: cRow.cognitive,
+            cyclomatic: cRow.cyclomatic,
+            maxNesting: cRow.max_nesting,
+            maintainabilityIndex: cRow.maintainability_index || 0,
+            halsteadVolume: cRow.halstead_volume || 0,
+          };
+        }
+      } catch {
+        /* table may not exist */
+      }
+
+      // Children (parameters, properties, constants)
+      let nodeChildren = [];
+      try {
+        nodeChildren = findNodeChildren(db, node.id).map((c) => ({
+          name: c.name,
+          kind: c.kind,
+          line: c.line,
+          endLine: c.end_line || null,
+        }));
+      } catch {
+        /* parent_id column may not exist */
+      }
+
+      return {
+        name: node.name,
+        kind: node.kind,
+        file: node.file,
+        line: node.line,
+        role: node.role || null,
+        endLine: node.end_line || null,
+        source,
+        signature,
+        complexity: complexityMetrics,
+        children: nodeChildren.length > 0 ? nodeChildren : undefined,
+        callees,
+        callers,
+        relatedTests,
+      };
+    });
+
+    const base = { name, results };
+    return paginateResult(base, 'results', { limit: opts.limit, offset: opts.offset });
+  } finally {
+    db.close();
+  }
+}
+
+export function explainData(target, customDbPath, opts = {}) {
+  const db = openReadonlyOrFail(customDbPath);
+  try {
+    const noTests = opts.noTests || false;
+    const depth = opts.depth || 0;
+    const kind = isFileLikeTarget(target) ? 'file' : 'function';
+
+    const dbPath = findDbPath(customDbPath);
+    const repoRoot = path.resolve(path.dirname(dbPath), '..');
+
+    const getFileLines = createFileLinesReader(repoRoot);
+
+    const results =
+      kind === 'file'
+        ? explainFileImpl(db, target, getFileLines)
+        : explainFunctionImpl(db, target, noTests, getFileLines);
+
+    // Recursive dependency explanation for function targets
+    if (kind === 'function' && depth > 0 && results.length > 0) {
+      const visited = new Set(results.map((r) => `${r.name}:${r.file}:${r.line}`));
+
+      function explainCallees(parentResults, currentDepth) {
+        if (currentDepth <= 0) return;
+        for (const r of parentResults) {
+          const newCallees = [];
+          for (const callee of r.callees) {
+            const key = `${callee.name}:${callee.file}:${callee.line}`;
+            if (visited.has(key)) continue;
+            visited.add(key);
+            const calleeResults = explainFunctionImpl(db, callee.name, noTests, getFileLines);
+            const exact = calleeResults.find(
+              (cr) => cr.file === callee.file && cr.line === callee.line,
+            );
+            if (exact) {
+              exact._depth = (r._depth || 0) + 1;
+              newCallees.push(exact);
+            }
+          }
+          if (newCallees.length > 0) {
+            r.depDetails = newCallees;
+            explainCallees(newCallees, currentDepth - 1);
+          }
+        }
+      }
+
+      explainCallees(results, depth);
+    }
+
+    const base = { target, kind, results };
+    return paginateResult(base, 'results', { limit: opts.limit, offset: opts.offset });
+  } finally {
+    db.close();
+  }
+}