fix(resolution): stream node-kind scans in synthesis to fix OOM on dense files (#610) (#653)

The callback/observer synthesizers loaded every function and method node into
memory at once (getNodesByKind('function'/'method')) before scanning them down
to a tiny matched subset. On a symbol-dense project that array is gigabytes, so
indexing spiked the JS heap and aborted with "JavaScript heap out of memory".

Add QueryBuilder.iterateNodesByKind (a lazy node:sqlite cursor) and stream the
synthesizer scans instead of materializing them. Parsing and reference
resolution were already bounded; only the synthesis enumeration wasn't.

Measured on 80 files x 14k functions (~1.1M nodes): peak RSS 3717 MB -> 1318 MB,
no OOM. Full suite green; synthesized edges unchanged.

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

CHANGELOG.md

@@ -12,6 +12,7 @@ and adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 ### Fixes
 
 - The background file watcher no longer exhausts your machine's file-descriptor budget. On macOS it previously kept **one open file handle per watched file**, so on a large project the running MCP server could pile up tens of thousands of handles and blow past the system-wide limit — at which point *unrelated* apps (your shell, editor, Docker, browser) started failing with "too many open files" until the codegraph process was killed. The watcher now uses a single recursive watch on macOS and Windows, and bounded per-directory watches on Linux, so its cost stays flat no matter how large the project is. (#644, #496, #555, #628, #579)
+- Indexing a project with very symbol-dense files (tens of thousands of functions or methods in a single file) no longer runs out of memory. The step that links dynamic call relationships used to load every function and method into memory at once, which could exhaust the heap and abort indexing with "JavaScript heap out of memory" on large or generated codebases; it now streams them, so memory stays flat no matter how many symbols the project has. (#610)
 
 ## [0.9.9] - 2026-06-02
 

__tests__/iterate-nodes-by-kind.test.ts

@@ -0,0 +1,62 @@
+/**
+ * `QueryBuilder.iterateNodesByKind` — the streaming scan that fixes the #610
+ * OOM. The dynamic-edge synthesizers used to `getNodesByKind('function')` /
+ * `('method')`, materializing every symbol into one array (gigabytes on a
+ * symbol-dense project → JS-heap OOM). They now iterate. These tests pin the
+ * two properties that refactor relies on: the streamed set equals the eager
+ * set, and an open iterator cursor coexists with other queries on the same
+ * connection.
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as os from 'os';
+import CodeGraph from '../src/index';
+
+describe('iterateNodesByKind (#610 streaming)', () => {
+  let dir: string;
+  let cg: CodeGraph;
+
+  beforeEach(async () => {
+    dir = fs.mkdtempSync(path.join(os.tmpdir(), 'cg-iter-'));
+    fs.mkdirSync(path.join(dir, 'src'));
+    fs.writeFileSync(
+      path.join(dir, 'src', 'a.ts'),
+      'export function foo() { return 1; }\n' +
+      'export function bar() { return 2; }\n' +
+      'export class C { m() { return 3; } n() { return 4; } }\n'
+    );
+    cg = CodeGraph.initSync(dir, { config: { include: ['**/*.ts'], exclude: [] } });
+    await cg.indexAll();
+  });
+
+  afterEach(() => {
+    try { cg.close(); } catch { /* ignore */ }
+    fs.rmSync(dir, { recursive: true, force: true });
+  });
+
+  it('yields exactly the same nodes as the eager getNodesByKind', () => {
+    const q = (cg as unknown as { queries: any }).queries;
+    for (const kind of ['function', 'method', 'class'] as const) {
+      const eager = q.getNodesByKind(kind).map((n: any) => n.id).sort();
+      const streamed = [...q.iterateNodesByKind(kind)].map((n: any) => n.id).sort();
+      expect(streamed).toEqual(eager);
+    }
+    // sanity: the fixture actually produced functions + methods to stream
+    expect([...q.iterateNodesByKind('function')].length).toBeGreaterThan(0);
+    expect([...q.iterateNodesByKind('method')].length).toBeGreaterThan(0);
+  });
+
+  it('keeps the cursor valid while other queries run mid-iteration', () => {
+    const q = (cg as unknown as { queries: any }).queries;
+    let seen = 0;
+    for (const n of q.iterateNodesByKind('function')) {
+      // A different prepared statement stepped on the same connection while the
+      // iterator's cursor is open must not corrupt it.
+      const again = q.getNodeById(n.id);
+      expect(again?.id).toBe(n.id);
+      seen++;
+    }
+    expect(seen).toBe(q.getNodesByKind('function').length);
+  });
+});

src/db/queries.ts

@@ -681,6 +681,22 @@ export class QueryBuilder {
     return rows.map(rowToNode);
   }
 
+  /**
+   * Stream every node of a kind one at a time (lazy) instead of materializing
+   * them all like {@link getNodesByKind}. For unbounded kinds (`function`,
+   * `method`) on a symbol-dense project the full array is gigabytes; the
+   * dynamic-edge synthesizers only scan-and-filter, so they iterate to keep
+   * memory O(1) in the node count rather than O(nodes) (#610).
+   */
+  *iterateNodesByKind(kind: NodeKind): IterableIterator<Node> {
+    // Fresh statement per call (not a cached one): an iterator holds an open
+    // cursor, so a shared statement would conflict across overlapping scans.
+    const stmt = this.db.prepare('SELECT * FROM nodes WHERE kind = ?');
+    for (const row of stmt.iterate(kind)) {
+      yield rowToNode(row as NodeRow);
+    }
+  }
+
   /**
    * Get all nodes in the database
    */

src/db/sqlite-adapter.ts

@@ -14,6 +14,13 @@ export interface SqliteStatement {
   run(...params: any[]): { changes: number; lastInsertRowid: number | bigint };
   get(...params: any[]): any;
   all(...params: any[]): any[];
+  /**
+   * Lazily yield result rows one at a time instead of materializing the whole
+   * set with `all()`. Use for unbounded scans (e.g. every function/method node)
+   * so memory stays O(1) in the row count rather than O(rows) — see #610, where
+   * `all()`-ing every symbol on a dense project spiked the heap into an OOM.
+   */
+  iterate(...params: any[]): IterableIterator<any>;
 }
 
 export interface SqliteDatabase {
@@ -72,6 +79,9 @@ class NodeSqliteAdapter implements SqliteDatabase {
       all(...params: any[]) {
         return stmt.all(...params);
       },
+      iterate(...params: any[]) {
+        return stmt.iterate(...params);
+      },
     };
   }
 

src/resolution/callback-synthesizer.ts

@@ -97,13 +97,23 @@ function enclosingFn(nodesInFile: Node[], line: number): Node | null {
   return best;
 }
 
+/**
+ * Stream method + function nodes lazily. The synthesizers only scan-and-filter
+ * down to a tiny matched subset, so materializing every function/method (which
+ * is gigabytes on a symbol-dense project) just to iterate it once is what OOM'd
+ * #610. Iterating keeps memory O(1) in the node count.
+ */
+function* methodAndFunctionNodes(queries: QueryBuilder): IterableIterator<Node> {
+  yield* queries.iterateNodesByKind('method');
+  yield* queries.iterateNodesByKind('function');
+}
+
 /** Phase 1: field-backed observer channels (registrar/dispatcher share a store). */
 function fieldChannelEdges(queries: QueryBuilder, ctx: ResolutionContext): Edge[] {
-  const candidates = [...queries.getNodesByKind('method'), ...queries.getNodesByKind('function')];
   const registrars: Array<{ node: Node; field: string }> = [];
   const dispatchers: Array<{ node: Node; field: string }> = [];
 
-  for (const m of candidates) {
+  for (const m of methodAndFunctionNodes(queries)) {
     const isReg = REGISTRAR_NAME.test(m.name);
     const isDisp = DISPATCHER_NAME.test(m.name);
     if (!isReg && !isDisp) continue;
@@ -171,7 +181,6 @@ function fieldChannelEdges(queries: QueryBuilder, ctx: ResolutionContext): Edge[
  * name shared across unrelated classes can't fan out into noise.
  */
 function closureCollectionEdges(queries: QueryBuilder, ctx: ResolutionContext): Edge[] {
-  const candidates = [...queries.getNodesByKind('method'), ...queries.getNodesByKind('function')];
   const dispatchers = new Map<string, Array<{ node: Node; line: number }>>(); // field → dispatcher methods + forEach line
   const registrars = new Map<string, Array<{ node: Node; line: number }>>();   // field → registrar methods + append line
 
@@ -182,7 +191,7 @@ function closureCollectionEdges(queries: QueryBuilder, ctx: ResolutionContext):
     registrars.set(field, arr);
   };
 
-  for (const m of candidates) {
+  for (const m of methodAndFunctionNodes(queries)) {
     const content = ctx.readFile(m.filePath);
     const src = content && sliceLines(content, m.startLine, m.endLine);
     if (!src) continue;
@@ -1009,7 +1018,7 @@ function mybatisJavaXmlEdges(queries: QueryBuilder): Edge[] {
   const seen = new Set<string>();
   // Index Java methods by `<ClassName>::<methodName>` for O(1) lookup.
   const javaIndex = new Map<string, Node[]>();
-  for (const m of queries.getNodesByKind('method')) {
+  for (const m of queries.iterateNodesByKind('method')) {
     if (m.language !== 'java' && m.language !== 'kotlin') continue;
     const parts = m.qualifiedName.split('::');
     const last = parts[parts.length - 1];
@@ -1020,7 +1029,7 @@ function mybatisJavaXmlEdges(queries: QueryBuilder): Edge[] {
     if (arr) arr.push(m); else javaIndex.set(key, [m]);
   }
 
-  for (const xml of queries.getNodesByKind('method')) {
+  for (const xml of queries.iterateNodesByKind('method')) {
     if (xml.language !== 'xml') continue;
     // Qualified name: `<namespace>::<id>`. Extract the simple class name.
     const colonIdx = xml.qualifiedName.lastIndexOf('::');
@@ -1116,12 +1125,13 @@ function goHandlerIdent(expr: string): string | null {
 
 function ginMiddlewareChainEdges(queries: QueryBuilder, ctx: ResolutionContext): Edge[] {
   // 1. Find the chain dispatcher(s): a Go method that invokes a `handlers` slice by index.
-  const dispatchers = queries.getNodesByKind('method').filter((n) => {
-    if (n.language !== 'go') return false;
+  const dispatchers: Node[] = [];
+  for (const n of queries.iterateNodesByKind('method')) {
+    if (n.language !== 'go') continue;
     const content = ctx.readFile(n.filePath);
     const src = content && sliceLines(content, n.startLine, n.endLine);
-    return !!src && GIN_DISPATCH_RE.test(src);
-  });
+    if (src && GIN_DISPATCH_RE.test(src)) dispatchers.push(n);
+  }
   if (dispatchers.length === 0) return [];                              // not a gin repo — bail
 
   // 2. Collect handler identifiers registered via gin registration calls