@optave/codegraph 3.3.1 → 3.4.1

package/src/domain/graph/builder/stages/finalize.ts

@@ -0,0 +1,196 @@
+/**
+ * Stage: finalize
+ *
+ * WASM cleanup, stats logging, drift detection, build metadata, registry, journal.
+ */
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { performance } from 'node:perf_hooks';
+import { closeDb, closeDbDeferred, getBuildMeta, setBuildMeta } from '../../../../db/index.js';
+import { debug, info, warn } from '../../../../infrastructure/logger.js';
+import { CODEGRAPH_VERSION } from '../../../../shared/version.js';
+import { writeJournalHeader } from '../../journal.js';
+import type { PipelineContext } from '../context.js';
+
+export async function finalize(ctx: PipelineContext): Promise<void> {
+  const { db, allSymbols, rootDir, isFullBuild, hasEmbeddings, config, opts, schemaVersion } = ctx;
+
+  const t0 = performance.now();
+
+  // Release cached WASM trees
+  for (const [, symbols] of allSymbols) {
+    const tree = symbols._tree as { delete?: () => void } | undefined;
+    if (tree && typeof tree.delete === 'function') {
+      try {
+        tree.delete();
+      } catch {
+        /* ignore cleanup errors */
+      }
+    }
+    symbols._tree = undefined;
+    symbols._langId = undefined;
+  }
+
+  // Capture a single wall-clock timestamp for the current build — used for
+  // both the stale-embeddings comparison and the persisted built_at metadata.
+  const buildNow = new Date();
+
+  const nodeCount = (db.prepare('SELECT COUNT(*) as c FROM nodes').get() as { c: number }).c;
+  const actualEdgeCount = (db.prepare('SELECT COUNT(*) as c FROM edges').get() as { c: number }).c;
+  info(`Graph built: ${nodeCount} nodes, ${actualEdgeCount} edges`);
+  info(`Stored in ${ctx.dbPath}`);
+
+  // Incremental drift detection — skip for small incremental changes where
+  // count fluctuation is expected (reverse-dep edge churn).
+  if (!isFullBuild && allSymbols.size > 3) {
+    const prevNodes = getBuildMeta(db, 'node_count');
+    const prevEdges = getBuildMeta(db, 'edge_count');
+    if (prevNodes && prevEdges) {
+      const prevN = Number(prevNodes);
+      const prevE = Number(prevEdges);
+      if (prevN > 0) {
+        const nodeDrift = Math.abs(nodeCount - prevN) / prevN;
+        const edgeDrift = prevE > 0 ? Math.abs(actualEdgeCount - prevE) / prevE : 0;
+        const driftThreshold =
+          (config as { build?: { driftThreshold?: number } }).build?.driftThreshold ?? 0.2;
+        if (nodeDrift > driftThreshold || edgeDrift > driftThreshold) {
+          warn(
+            `Incremental build diverged significantly from previous counts (nodes: ${prevN}\u2192${nodeCount} [${(nodeDrift * 100).toFixed(1)}%], edges: ${prevE}\u2192${actualEdgeCount} [${(edgeDrift * 100).toFixed(1)}%], threshold: ${(driftThreshold * 100).toFixed(0)}%). Consider rebuilding with --no-incremental.`,
+          );
+        }
+      }
+    }
+  }
+
+  // For small incremental builds, skip persisting build metadata — the
+  // engine/version/schema haven't changed (would have triggered a full rebuild),
+  // built_at is only used by stale-embeddings check (skipped for incremental),
+  // and counts are only used by drift detection (skipped for ≤3 files).
+  // This avoids a transaction commit + WAL fsync (~15-30ms).
+  if (isFullBuild || allSymbols.size > 5) {
+    try {
+      setBuildMeta(db, {
+        engine: ctx.engineName,
+        engine_version: ctx.engineVersion || '',
+        codegraph_version: CODEGRAPH_VERSION,
+        schema_version: String(schemaVersion),
+        built_at: buildNow.toISOString(),
+        node_count: nodeCount,
+        edge_count: actualEdgeCount,
+      });
+    } catch (err) {
+      warn(`Failed to write build metadata: ${(err as Error).message}`);
+    }
+  }
+
+  // Skip expensive advisory queries for incremental builds — these are
+  // informational warnings that don't affect correctness and cost ~40-60ms.
+  if (!isFullBuild) {
+    debug(
+      'Finalize: skipping advisory queries (orphaned/stale embeddings, unused exports) for incremental build',
+    );
+  } else {
+    // Orphaned embeddings warning
+    if (hasEmbeddings) {
+      try {
+        const orphaned = (
+          db
+            .prepare(
+              'SELECT COUNT(*) as c FROM embeddings WHERE node_id NOT IN (SELECT id FROM nodes)',
+            )
+            .get() as { c: number }
+        ).c;
+        if (orphaned > 0) {
+          warn(
+            `${orphaned} embeddings are orphaned (nodes changed). Run "codegraph embed" to refresh.`,
+          );
+        }
+      } catch {
+        /* ignore - embeddings table may have been dropped */
+      }
+    }
+
+    // Stale embeddings warning (built before current graph rebuild)
+    if (hasEmbeddings) {
+      try {
+        const embedBuiltAt = (
+          db.prepare("SELECT value FROM embedding_meta WHERE key = 'built_at'").get() as
+            | { value: string }
+            | undefined
+        )?.value;
+        if (embedBuiltAt) {
+          const embedTime = new Date(embedBuiltAt).getTime();
+          if (!Number.isNaN(embedTime) && embedTime < buildNow.getTime()) {
+            warn(
+              'Embeddings were built before the last graph rebuild. Run "codegraph embed" to update.',
+            );
+          }
+        }
+      } catch {
+        /* ignore - embedding_meta table may not exist */
+      }
+    }
+
+    // Unused exports warning
+    try {
+      const unusedCount = (
+        db
+          .prepare(
+            `SELECT COUNT(*) as c FROM nodes
+         WHERE exported = 1 AND kind != 'file'
+           AND id NOT IN (
+             SELECT DISTINCT e.target_id FROM edges e
+             JOIN nodes caller ON e.source_id = caller.id
+             JOIN nodes target ON e.target_id = target.id
+             WHERE e.kind = 'calls' AND caller.file != target.file
+           )`,
+          )
+          .get() as { c: number }
+      ).c;
+      if (unusedCount > 0) {
+        warn(
+          `${unusedCount} exported symbol${unusedCount > 1 ? 's have' : ' has'} zero cross-file consumers. Run "codegraph exports <file> --unused" to inspect.`,
+        );
+      }
+    } catch {
+      /* exported column may not exist on older DBs */
+    }
+  }
+
+  ctx.timing.finalizeMs = performance.now() - t0;
+
+  // For small incremental builds, defer db.close() to the next event loop tick.
+  // The WAL checkpoint in db.close() costs ~250ms on Windows NTFS due to fsync.
+  // Deferring lets buildGraph() return immediately; the checkpoint runs after.
+  // Skip for temp directories (tests) — they rmSync immediately after build.
+  const isTempDir = path.resolve(rootDir).startsWith(path.resolve(tmpdir()));
+  if (!isFullBuild && allSymbols.size <= 5 && !isTempDir) {
+    closeDbDeferred(db);
+  } else {
+    closeDb(db);
+  }
+
+  // Write journal header after successful build
+  writeJournalHeader(rootDir, Date.now());
+
+  // Skip auto-registration for incremental builds — the repo was already
+  // registered during the initial full build. The dynamic import + file I/O
+  // costs ~100ms which dominates incremental finalize time.
+  if (!opts.skipRegistry && isFullBuild) {
+    const { tmpdir } = await import('node:os');
+    const tmpDir = path.resolve(tmpdir());
+    const resolvedRoot = path.resolve(rootDir);
+    if (resolvedRoot.startsWith(tmpDir)) {
+      debug(`Skipping auto-registration for temp directory: ${resolvedRoot}`);
+    } else {
+      try {
+        const { registerRepo } = (await import('../../../../infrastructure/registry.js')) as {
+          registerRepo: (rootDir: string) => void;
+        };
+        registerRepo(rootDir);
+      } catch (err) {
+        debug(`Auto-registration failed: ${(err as Error).message}`);
+      }
+    }
+  }
+}

package/src/domain/graph/builder/stages/{insert-nodes.js → insert-nodes.ts}

@@ -7,6 +7,13 @@
 import path from 'node:path';
 import { performance } from 'node:perf_hooks';
 import { bulkNodeIdsByFile } from '../../../../db/index.js';
+import type {
+  BetterSqlite3Database,
+  ExtractorOutput,
+  MetadataUpdate,
+  SqliteStatement,
+} from '../../../../types.js';
+import type { PipelineContext } from '../context.js';
 import {
   batchInsertEdges,
   batchInsertNodes,
@@ -15,10 +22,24 @@ import {
   readFileSafe,
 } from '../helpers.js';
 
+/** Shape of precomputed file data gathered from filesToParse entries. */
+interface PrecomputedFileData {
+  file: string;
+  relPath?: string;
+  content?: string;
+  hash?: string;
+  stat?: { mtime: number; size: number } | null;
+  _reverseDepOnly?: boolean;
+}
+
 // ── Phase 1: Insert file nodes, definitions, exports ────────────────────
 
-function insertDefinitionsAndExports(db, allSymbols) {
-  const phase1Rows = [];
+function insertDefinitionsAndExports(
+  db: BetterSqlite3Database,
+  allSymbols: Map<string, ExtractorOutput>,
+): void {
+  const phase1Rows: unknown[][] = [];
+  const exportKeys: unknown[][] = [];
   for (const [relPath, symbols] of allSymbols) {
     phase1Rows.push([relPath, 'file', relPath, 0, null, null, null, null, null]);
     for (const def of symbols.definitions) {
@@ -38,35 +59,68 @@ function insertDefinitionsAndExports(db, allSymbols) {
     }
     for (const exp of symbols.exports) {
       phase1Rows.push([exp.name, exp.kind, relPath, exp.line, null, null, exp.name, null, null]);
+      exportKeys.push([exp.name, exp.kind, relPath, exp.line]);
     }
   }
   batchInsertNodes(db, phase1Rows);
 
-  // Mark exported symbols
-  const markExported = db.prepare(
-    'UPDATE nodes SET exported = 1 WHERE name = ? AND kind = ? AND file = ? AND line = ?',
-  );
-  for (const [relPath, symbols] of allSymbols) {
-    for (const exp of symbols.exports) {
-      markExported.run(exp.name, exp.kind, relPath, exp.line);
+  // Mark exported symbols in batches (cache prepared statements by chunk size)
+  if (exportKeys.length > 0) {
+    const EXPORT_CHUNK = 500;
+    const exportStmtCache = new Map<number, SqliteStatement>();
+    for (let i = 0; i < exportKeys.length; i += EXPORT_CHUNK) {
+      const end = Math.min(i + EXPORT_CHUNK, exportKeys.length);
+      const chunkSize = end - i;
+      let updateStmt = exportStmtCache.get(chunkSize);
+      if (!updateStmt) {
+        const conditions = Array.from(
+          { length: chunkSize },
+          () => '(name = ? AND kind = ? AND file = ? AND line = ?)',
+        ).join(' OR ');
+        updateStmt = db.prepare(`UPDATE nodes SET exported = 1 WHERE ${conditions}`);
+        exportStmtCache.set(chunkSize, updateStmt);
+      }
+      const vals: unknown[] = [];
+      for (let j = i; j < end; j++) {
+        const k = exportKeys[j] as unknown[];
+        vals.push(k[0], k[1], k[2], k[3]);
+      }
+      updateStmt.run(...vals);
     }
   }
 }
 
-// ── Phase 2: Insert children (needs parent IDs) ────────────────────────
+// ── Phase 2+3: Insert children and containment edges (two nodeIdMap passes) ──
+
+function insertChildrenAndEdges(
+  db: BetterSqlite3Database,
+  allSymbols: Map<string, ExtractorOutput>,
+): void {
+  const childRows: unknown[][] = [];
+  const edgeRows: unknown[][] = [];
 
-function insertChildren(db, allSymbols) {
-  const childRows = [];
   for (const [relPath, symbols] of allSymbols) {
-    const nodeIdMap = new Map();
+    // First pass: collect file→def edges and child rows
+    const nodeIdMap = new Map<string, number>();
     for (const row of bulkNodeIdsByFile(db, relPath)) {
       nodeIdMap.set(`${row.name}|${row.kind}|${row.line}`, row.id);
     }
+
+    const fileId = nodeIdMap.get(`${relPath}|file|0`);
+
     for (const def of symbols.definitions) {
-      if (!def.children?.length) continue;
       const defId = nodeIdMap.get(`${def.name}|${def.kind}|${def.line}`);
+
+      // Containment edge: file -> definition
+      if (fileId && defId) {
+        edgeRows.push([fileId, defId, 'contains', 1.0, 0]);
+      }
+
+      if (!def.children?.length) continue;
       if (!defId) continue;
+
       for (const child of def.children) {
+        // Child node
         const qualifiedName = `${def.name}.${child.name}`;
         childRows.push([
           child.name,
@@ -82,43 +136,45 @@ function insertChildren(db, allSymbols) {
       }
     }
   }
-  batchInsertNodes(db, childRows);
-}
 
-// ── Phase 3: Insert containment + parameter_of edges ────────────────────
+  // Insert children first (so they exist for edge lookup)
+  batchInsertNodes(db, childRows);
 
-function insertContainmentEdges(db, allSymbols) {
-  const edgeRows = [];
+  // Now re-fetch IDs to include newly-inserted children, then add child edges
   for (const [relPath, symbols] of allSymbols) {
-    const nodeIdMap = new Map();
+    const nodeIdMap = new Map<string, number>();
     for (const row of bulkNodeIdsByFile(db, relPath)) {
       nodeIdMap.set(`${row.name}|${row.kind}|${row.line}`, row.id);
     }
-    const fileId = nodeIdMap.get(`${relPath}|file|0`);
     for (const def of symbols.definitions) {
+      if (!def.children?.length) continue;
       const defId = nodeIdMap.get(`${def.name}|${def.kind}|${def.line}`);
-      if (fileId && defId) {
-        edgeRows.push([fileId, defId, 'contains', 1.0, 0]);
-      }
-      if (def.children?.length && defId) {
-        for (const child of def.children) {
-          const childId = nodeIdMap.get(`${child.name}|${child.kind}|${child.line}`);
-          if (childId) {
-            edgeRows.push([defId, childId, 'contains', 1.0, 0]);
-            if (child.kind === 'parameter') {
-              edgeRows.push([childId, defId, 'parameter_of', 1.0, 0]);
-            }
+      if (!defId) continue;
+      for (const child of def.children) {
+        const childId = nodeIdMap.get(`${child.name}|${child.kind}|${child.line}`);
+        if (childId) {
+          edgeRows.push([defId, childId, 'contains', 1.0, 0]);
+          if (child.kind === 'parameter') {
+            edgeRows.push([childId, defId, 'parameter_of', 1.0, 0]);
           }
         }
       }
     }
   }
+
   batchInsertEdges(db, edgeRows);
 }
 
 // ── Phase 4: Update file hashes ─────────────────────────────────────────
 
-function updateFileHashes(_db, allSymbols, precomputedData, metadataUpdates, rootDir, upsertHash) {
+function updateFileHashes(
+  _db: BetterSqlite3Database,
+  allSymbols: Map<string, ExtractorOutput>,
+  precomputedData: Map<string, PrecomputedFileData>,
+  metadataUpdates: MetadataUpdate[],
+  rootDir: string,
+  upsertHash: SqliteStatement | null,
+): void {
   if (!upsertHash) return;
 
   for (const [relPath] of allSymbols) {
@@ -126,13 +182,20 @@ function updateFileHashes(_db, allSymbols, precomputedData, metadataUpdates, roo
     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;
+      let mtime: number;
+      let size: number;
+      if (precomputed.stat) {
+        mtime = precomputed.stat.mtime;
+        size = precomputed.stat.size;
+      } else {
+        const rawStat = fileStat(path.join(rootDir, relPath));
+        mtime = rawStat ? Math.floor(rawStat.mtimeMs) : 0;
+        size = rawStat ? rawStat.size : 0;
+      }
       upsertHash.run(relPath, precomputed.hash, mtime, size);
     } else {
       const absPath = path.join(rootDir, relPath);
-      let code;
+      let code: string | null;
       try {
         code = readFileSafe(absPath);
       } catch {
@@ -149,7 +212,7 @@ function updateFileHashes(_db, allSymbols, precomputedData, metadataUpdates, roo
 
   // Also update metadata-only entries (self-heal mtime/size without re-parse)
   for (const item of metadataUpdates) {
-    const mtime = item.stat ? Math.floor(item.stat.mtimeMs) : 0;
+    const mtime = item.stat ? Math.floor(item.stat.mtime) : 0;
     const size = item.stat ? item.stat.size : 0;
     upsertHash.run(item.relPath, item.hash, mtime, size);
   }
@@ -157,18 +220,15 @@ function updateFileHashes(_db, allSymbols, precomputedData, metadataUpdates, roo
 
 // ── Main entry point ────────────────────────────────────────────────────
 
-/**
- * @param {import('../context.js').PipelineContext} ctx
- */
-export async function insertNodes(ctx) {
+export async function insertNodes(ctx: PipelineContext): Promise<void> {
   const { db, allSymbols, filesToParse, metadataUpdates, rootDir, removed } = ctx;
 
-  const precomputedData = new Map();
+  const precomputedData = new Map<string, PrecomputedFileData>();
   for (const item of filesToParse) {
-    if (item.relPath) precomputedData.set(item.relPath, item);
+    if (item.relPath) precomputedData.set(item.relPath, item as PrecomputedFileData);
   }
 
-  let upsertHash;
+  let upsertHash: SqliteStatement | null;
   try {
     upsertHash = db.prepare(
       'INSERT OR REPLACE INTO file_hashes (file, hash, mtime, size) VALUES (?, ?, ?, ?)',
@@ -184,8 +244,7 @@ export async function insertNodes(ctx) {
 
   const insertAll = db.transaction(() => {
     insertDefinitionsAndExports(db, allSymbols);
-    insertChildren(db, allSymbols);
-    insertContainmentEdges(db, allSymbols);
+    insertChildrenAndEdges(db, allSymbols);
     updateFileHashes(db, allSymbols, precomputedData, metadataUpdates, rootDir, upsertHash);
   });
 

package/src/domain/graph/builder/stages/{parse-files.js → parse-files.ts}

@@ -7,11 +7,9 @@
 import { performance } from 'node:perf_hooks';
 import { info } from '../../../../infrastructure/logger.js';
 import { parseFilesAuto } from '../../../parser.js';
+import type { PipelineContext } from '../context.js';
 
-/**
- * @param {import('../context.js').PipelineContext} ctx
- */
-export async function parseFiles(ctx) {
+export async function parseFiles(ctx: PipelineContext): Promise<void> {
   const { allFiles, parseChanges, isFullBuild, engineOpts, rootDir } = ctx;
 
   ctx.filesToParse = isFullBuild ? allFiles.map((f) => ({ file: f })) : parseChanges;

package/src/domain/graph/builder/stages/resolve-imports.ts

@@ -0,0 +1,195 @@
+import path from 'node:path';
+import { performance } from 'node:perf_hooks';
+import type { Import } from '../../../../types.js';
+import { parseFilesAuto } from '../../../parser.js';
+import { resolveImportPath, resolveImportsBatch } from '../../resolve.js';
+import type { PipelineContext } from '../context.js';
+
+interface ReexportEntry {
+  source: string;
+  names: string[];
+  wildcardReexport: boolean;
+}
+
+export async function resolveImports(ctx: PipelineContext): Promise<void> {
+  const { db, fileSymbols, rootDir, aliases, allFiles, isFullBuild, engineOpts } = ctx;
+  const t0 = performance.now();
+  const batchInputs: Array<{ fromFile: string; importSource: string }> = [];
+  for (const [relPath, symbols] of fileSymbols) {
+    const absFile = path.join(rootDir, relPath);
+    for (const imp of symbols.imports) {
+      batchInputs.push({ fromFile: absFile, importSource: imp.source });
+    }
+  }
+  ctx.batchResolved = resolveImportsBatch(batchInputs, rootDir, aliases, allFiles);
+  ctx.timing.resolveMs = performance.now() - t0;
+
+  ctx.reexportMap = new Map<string, ReexportEntry[]>();
+  for (const [relPath, symbols] of fileSymbols) {
+    const reexports = symbols.imports.filter((imp) => imp.reexport);
+    if (reexports.length > 0) {
+      ctx.reexportMap.set(
+        relPath,
+        reexports.map((imp) => ({
+          source: getResolved(ctx, path.join(rootDir, relPath), imp.source),
+          names: imp.names,
+          wildcardReexport: imp.wildcardReexport || false,
+        })),
+      );
+    }
+  }
+
+  ctx.barrelOnlyFiles = new Set<string>();
+  if (!isFullBuild) {
+    // Collect the set of changed file paths to scope barrel re-parsing.
+    const changedRelPaths = new Set<string>(fileSymbols.keys());
+
+    // For small incremental builds (≤5 files), only re-parse barrel files
+    // that are related to the changed files — either re-exporting from them
+    // or imported by them. For larger changes, re-parse all barrels.
+    let barrelCandidates: Array<{ file: string }>;
+    if (changedRelPaths.size <= 5) {
+      // All known barrel files (has at least one reexport edge)
+      const allBarrelFiles = new Set(
+        (
+          db
+            .prepare(
+              `SELECT DISTINCT n1.file FROM edges e
+               JOIN nodes n1 ON e.source_id = n1.id
+               WHERE e.kind = 'reexports' AND n1.kind = 'file'`,
+            )
+            .all() as Array<{ file: string }>
+        ).map((r) => r.file),
+      );
+
+      const barrels = new Set<string>();
+
+      // Find barrels imported by changed files using parsed import data
+      // (can't query DB edges — they were purged for the changed files).
+      for (const relPath of changedRelPaths) {
+        const symbols = fileSymbols.get(relPath);
+        if (!symbols) continue;
+        for (const imp of symbols.imports) {
+          const resolved = ctx.batchResolved?.get(`${path.join(rootDir, relPath)}|${imp.source}`);
+          const target =
+            resolved ??
+            resolveImportPath(path.join(rootDir, relPath), imp.source, rootDir, aliases);
+          if (allBarrelFiles.has(target)) barrels.add(target);
+        }
+      }
+
+      // Also find barrels that re-export from the changed files
+      const reexportSourceStmt = db.prepare(
+        `SELECT DISTINCT n1.file FROM edges e
+         JOIN nodes n1 ON e.source_id = n1.id
+         JOIN nodes n2 ON e.target_id = n2.id
+         WHERE e.kind = 'reexports' AND n1.kind = 'file' AND n2.file = ?`,
+      );
+      for (const relPath of changedRelPaths) {
+        for (const row of reexportSourceStmt.all(relPath) as Array<{ file: string }>) {
+          barrels.add(row.file);
+        }
+      }
+      barrelCandidates = [...barrels].map((file) => ({ file }));
+    } else {
+      barrelCandidates = db
+        .prepare(
+          `SELECT DISTINCT n1.file FROM edges e
+           JOIN nodes n1 ON e.source_id = n1.id
+           WHERE e.kind = 'reexports' AND n1.kind = 'file'`,
+        )
+        .all() as Array<{ file: string }>;
+    }
+
+    // Batch-parse all barrel candidates at once instead of one-by-one
+    const barrelPaths: string[] = [];
+    for (const { file: relPath } of barrelCandidates) {
+      if (!fileSymbols.has(relPath)) {
+        barrelPaths.push(path.join(rootDir, relPath));
+      }
+    }
+
+    if (barrelPaths.length > 0) {
+      const deleteOutgoingEdges = db.prepare(
+        'DELETE FROM edges WHERE source_id IN (SELECT id FROM nodes WHERE file = ?)',
+      );
+
+      try {
+        const barrelSymbols = await parseFilesAuto(barrelPaths, rootDir, engineOpts);
+        for (const [relPath, fileSym] of barrelSymbols) {
+          deleteOutgoingEdges.run(relPath);
+          fileSymbols.set(relPath, fileSym);
+          ctx.barrelOnlyFiles.add(relPath);
+          const reexports = fileSym.imports.filter((imp: Import) => imp.reexport);
+          if (reexports.length > 0) {
+            ctx.reexportMap.set(
+              relPath,
+              reexports.map((imp: Import) => ({
+                source: getResolved(ctx, path.join(rootDir, relPath), imp.source),
+                names: imp.names,
+                wildcardReexport: imp.wildcardReexport || false,
+              })),
+            );
+          }
+        }
+      } catch {
+        /* skip if unreadable */
+      }
+    }
+  }
+}
+
+export function getResolved(ctx: PipelineContext, absFile: string, importSource: string): string {
+  if (ctx.batchResolved) {
+    const key = `${absFile}|${importSource}`;
+    const hit = ctx.batchResolved.get(key);
+    if (hit !== undefined) return hit;
+  }
+  return resolveImportPath(absFile, importSource, ctx.rootDir, ctx.aliases);
+}
+
+export function isBarrelFile(ctx: PipelineContext, relPath: string): boolean {
+  const symbols = ctx.fileSymbols.get(relPath);
+  if (!symbols) return false;
+  const reexports = symbols.imports.filter((imp) => imp.reexport);
+  if (reexports.length === 0) return false;
+  const ownDefs = symbols.definitions.length;
+  return reexports.length >= ownDefs;
+}
+
+export function resolveBarrelExport(
+  ctx: PipelineContext,
+  barrelPath: string,
+  symbolName: string,
+  visited: Set<string> = new Set<string>(),
+): string | null {
+  if (visited.has(barrelPath)) return null;
+  visited.add(barrelPath);
+  const reexports = ctx.reexportMap.get(barrelPath) as ReexportEntry[] | undefined;
+  if (!reexports) return null;
+  for (const re of reexports) {
+    if (re.names.length > 0 && !re.wildcardReexport) {
+      if (re.names.includes(symbolName)) {
+        const targetSymbols = ctx.fileSymbols.get(re.source);
+        if (targetSymbols) {
+          const hasDef = targetSymbols.definitions.some((d) => d.name === symbolName);
+          if (hasDef) return re.source;
+          const deeper = resolveBarrelExport(ctx, re.source, symbolName, visited);
+          if (deeper) return deeper;
+        }
+        return re.source;
+      }
+      continue;
+    }
+    if (re.wildcardReexport || re.names.length === 0) {
+      const targetSymbols = ctx.fileSymbols.get(re.source);
+      if (targetSymbols) {
+        const hasDef = targetSymbols.definitions.some((d) => d.name === symbolName);
+        if (hasDef) return re.source;
+        const deeper = resolveBarrelExport(ctx, re.source, symbolName, visited);
+        if (deeper) return deeper;
+      }
+    }
+  }
+  return null;
+}