@monoes/monograph 1.4.0 → 1.4.1

package/src/pipeline/phases/bridge-adapters/tauri.ts

@@ -0,0 +1,103 @@
+import { statSync, readFileSync } from 'fs';
+import { join, extname } from 'path';
+import type { PipelineContext } from '../../types.js';
+import type { BridgeAdapter, BridgeEndpoint } from './types.js';
+
+const RUST_EXT = new Set(['.rs']);
+const JS_TS_EXT = new Set(['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs']);
+
+/** `#[tauri::command]` (with or without args) directly above an fn declaration. */
+const TAURI_COMMAND_RE = /#\[tauri::command(?:\([^)]*\))?\]\s*(?:pub(?:\([^)]*\))?\s+)?(?:async\s+)?fn\s+(\w+)/g;
+
+/**
+ * Tauri's `invoke(...)` call from the JS/TS side, e.g.
+ * `import { invoke } from '@tauri-apps/api/core'; invoke('my_command', {...})`.
+ * We don't verify the import — matching the call shape is enough signal here,
+ * same tradeoff extractor.ts already makes for plain call-site regexes.
+ */
+const TAURI_INVOKE_RE = /\binvoke\(\s*['"]([^'"]+)['"]/g;
+
+function safeReadSource(absPath: string, maxBytes: number): string | undefined {
+  try {
+    const stat = statSync(absPath);
+    if (stat.size > maxBytes) return undefined;
+    return readFileSync(absPath, 'utf-8');
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Tauri (Rust <-> JS/TS): a `#[tauri::command]`-annotated Rust fn is invoked
+ * from the frontend by name via `invoke("name", ...)` — a string-literal
+ * match, not a generated file. The Rust side already has a real Function
+ * node (from the Rust extractor); the JS/TS call site does not, so it's
+ * attached to its containing File node.
+ */
+export const tauriAdapter: BridgeAdapter = {
+  name: 'tauri',
+
+  // A bare .rs file isn't a Tauri signal by itself (a repo can have unrelated
+  // Rust code alongside a JS/TS frontend) — require an actual
+  // #[tauri::command] annotation before this adapter runs at all.
+  detect(ctx, filePaths) {
+    for (const relPath of filePaths) {
+      if (!RUST_EXT.has(extname(relPath))) continue;
+      const source = safeReadSource(join(ctx.repoPath, relPath), ctx.options.maxFileSizeBytes);
+      if (!source) continue;
+      TAURI_COMMAND_RE.lastIndex = 0;
+      if (TAURI_COMMAND_RE.test(source)) return true;
+    }
+    return false;
+  },
+
+  findDefinitions(ctx, filePaths) {
+    const endpoints: BridgeEndpoint[] = [];
+    for (const relPath of filePaths) {
+      if (!RUST_EXT.has(extname(relPath))) continue;
+      const source = safeReadSource(join(ctx.repoPath, relPath), ctx.options.maxFileSizeBytes);
+      if (!source) continue;
+
+      TAURI_COMMAND_RE.lastIndex = 0;
+      let m: RegExpExecArray | null;
+      const names: string[] = [];
+      while ((m = TAURI_COMMAND_RE.exec(source)) !== null) names.push(m[1]!);
+      if (names.length === 0) continue;
+
+      const rows = ctx.db
+        .prepare(`SELECT id, name FROM nodes WHERE label = 'Function' AND language = 'rust' AND file_path = ?`)
+        .all(relPath) as { id: string; name: string }[];
+      const byName = new Map(rows.map((r) => [r.name, r.id]));
+      for (const name of names) {
+        const nodeId = byName.get(name);
+        if (nodeId) endpoints.push({ key: name, nodeId, language: 'rust' });
+      }
+    }
+    return endpoints;
+  },
+
+  findCallSites(ctx, filePaths) {
+    const endpoints: BridgeEndpoint[] = [];
+    for (const relPath of filePaths) {
+      if (!JS_TS_EXT.has(extname(relPath))) continue;
+      const source = safeReadSource(join(ctx.repoPath, relPath), ctx.options.maxFileSizeBytes);
+      if (!source) continue;
+
+      TAURI_INVOKE_RE.lastIndex = 0;
+      let m: RegExpExecArray | null;
+      const commandNames: string[] = [];
+      while ((m = TAURI_INVOKE_RE.exec(source)) !== null) commandNames.push(m[1]!);
+      if (commandNames.length === 0) continue;
+
+      const fileRow = ctx.db
+        .prepare(`SELECT id FROM nodes WHERE label = 'File' AND file_path = ?`)
+        .get(relPath) as { id: string } | undefined;
+      if (!fileRow) continue;
+
+      for (const name of commandNames) {
+        endpoints.push({ key: name, nodeId: fileRow.id, language: 'javascript' });
+      }
+    }
+    return endpoints;
+  },
+};

package/src/pipeline/phases/bridge-adapters/types.ts

@@ -0,0 +1,31 @@
+import type { PipelineContext } from '../../types.js';
+
+/**
+ * One side of a cross-language bridge boundary — a definition (the thing being
+ * exposed across the boundary) or a call site (the thing invoking across it).
+ * `key` is the string both sides are matched on: an exact symbol name for
+ * codegen-based bridges (Wails, wasm-bindgen), or a string-literal channel/
+ * command name for registration-based bridges (Tauri, Electron IPC).
+ */
+export interface BridgeEndpoint {
+  key: string;
+  nodeId: string;
+  language: string;
+}
+
+/**
+ * A cross-language bridge adapter. Each adapter independently extracts
+ * (key, nodeId) pairs from both sides of one specific FFI/IPC/RPC boundary;
+ * the bridge-resolver phase matches them by key and emits CALLS edges.
+ *
+ * `detect` must be cheap — it runs for every adapter on every build, so an
+ * adapter whose framework isn't present in the repo should bail out fast
+ * (e.g. checking file paths already collected by the scan phase) rather than
+ * re-reading the filesystem.
+ */
+export interface BridgeAdapter {
+  name: string;
+  detect(ctx: PipelineContext, filePaths: string[]): boolean;
+  findDefinitions(ctx: PipelineContext, filePaths: string[]): BridgeEndpoint[];
+  findCallSites(ctx: PipelineContext, filePaths: string[]): BridgeEndpoint[];
+}

package/src/pipeline/phases/bridge-adapters/wails.ts

@@ -0,0 +1,33 @@
+import type { PipelineContext } from '../../types.js';
+import type { BridgeAdapter, BridgeEndpoint } from './types.js';
+
+const WAILS_BINDING_RE = /wailsjs\/go\//i;
+
+/**
+ * Wails (Go <-> JS/TS): `wails` generates a JS/TS binding file per bound Go
+ * struct at `frontend/**\/wailsjs/go/<package>/<Struct>.js`, exporting one
+ * function per Go method with the exact same name. Both sides are already
+ * parsed into real Function/Method nodes by the Go and TS/JS extractors —
+ * this adapter just links them by name across the language boundary.
+ */
+export const wailsAdapter: BridgeAdapter = {
+  name: 'wails',
+
+  detect(_ctx, filePaths) {
+    return filePaths.some((p) => WAILS_BINDING_RE.test(p));
+  },
+
+  findDefinitions(ctx) {
+    const rows = ctx.db
+      .prepare(`SELECT id, name, language FROM nodes WHERE label = 'Method' AND language = 'go' AND file_path IS NOT NULL`)
+      .all() as { id: string; name: string; language: string }[];
+    return rows.map((r): BridgeEndpoint => ({ key: r.name, nodeId: r.id, language: r.language }));
+  },
+
+  findCallSites(ctx) {
+    const rows = ctx.db
+      .prepare(`SELECT id, name, language, file_path FROM nodes WHERE label = 'Function' AND file_path LIKE '%wailsjs/go/%'`)
+      .all() as { id: string; name: string; language: string; file_path: string }[];
+    return rows.map((r): BridgeEndpoint => ({ key: r.name, nodeId: r.id, language: r.language ?? 'javascript' }));
+  },
+};

package/src/pipeline/phases/bridge-resolver.ts

@@ -0,0 +1,77 @@
+import type { PipelinePhase } from '../types.js';
+import type { MonographEdge } from '../../types.js';
+import { makeId, CONFIDENCE_SCORE } from '../../types.js';
+import { insertEdges } from '../../storage/edge-store.js';
+import type { ScanOutput } from './scan.js';
+import { BUILTIN_BRIDGE_ADAPTERS } from './bridge-adapters/registry.js';
+import type { BridgeEndpoint } from './bridge-adapters/types.js';
+
+export interface BridgeResolverOutput {
+  edgesCreated: number;
+}
+
+/**
+ * Cross-language bridge resolution — links calls across an FFI/IPC boundary
+ * that no single language's own import/call resolution can see (Wails'
+ * generated Go<->JS bindings, Tauri's invoke() commands, Electron's IPC
+ * channels, ...). Each adapter in bridge-adapters/ extracts (key, nodeId)
+ * pairs from both sides; here they're matched by key and turned into CALLS
+ * edges — reusing the existing relation so every existing consumer
+ * (monograph_impact, monograph_neighbors, community detection) picks them up
+ * with no changes on their end.
+ *
+ * Confidence is always INFERRED: a bridge edge is a name/key match, not an
+ * AST-verified call. A key with more than one matching definition is
+ * dropped rather than guessed at — the call site can't know which one was
+ * meant, and a wrong edge is worse than a missing one. Multiple call sites
+ * sharing one definition (the common case: several UI files calling the
+ * same bound method) is normal and always kept.
+ */
+export const bridgeResolverPhase: PipelinePhase<BridgeResolverOutput> = {
+  name: 'bridge-resolver',
+  deps: ['scan', 'structure', 'parse'],
+  async execute(ctx, deps) {
+    if (ctx.allFilesCached) return { edgesCreated: 0 };
+
+    const { filePaths } = deps.get('scan') as ScanOutput;
+    const edges: MonographEdge[] = [];
+
+    for (const adapter of BUILTIN_BRIDGE_ADAPTERS) {
+      if (!adapter.detect(ctx, filePaths)) continue;
+
+      const definitions = adapter.findDefinitions(ctx, filePaths);
+      const callSites = adapter.findCallSites(ctx, filePaths);
+      if (definitions.length === 0 || callSites.length === 0) continue;
+
+      const definitionsByKey = new Map<string, BridgeEndpoint[]>();
+      for (const def of definitions) {
+        const arr = definitionsByKey.get(def.key);
+        if (arr) arr.push(def);
+        else definitionsByKey.set(def.key, [def]);
+      }
+
+      for (const callSite of callSites) {
+        const matches = definitionsByKey.get(callSite.key);
+        if (!matches || matches.length !== 1) continue; // 0 or ambiguous — drop, don't guess
+        const target = matches[0]!;
+        if (target.nodeId === callSite.nodeId) continue; // same node on both sides — nothing to link
+
+        const id = makeId('bridge', adapter.name, callSite.nodeId, target.nodeId);
+        const languagePair = `${callSite.language} -> ${target.language}`;
+        edges.push({
+          id,
+          sourceId: callSite.nodeId,
+          targetId: target.nodeId,
+          relation: 'CALLS',
+          confidence: 'INFERRED',
+          confidenceScore: CONFIDENCE_SCORE.INFERRED,
+          reason: `${adapter.name} bridge (${languagePair}): "${callSite.key}"`,
+          evidence: [{ kind: 'bridge', weight: CONFIDENCE_SCORE.INFERRED, note: `${adapter.name}: ${languagePair}` }],
+        });
+      }
+    }
+
+    if (edges.length > 0) insertEdges(ctx.db, edges);
+    return { edgesCreated: edges.length };
+  },
+};

package/src/pipeline/phases/cross-file.ts

@@ -1,53 +1,101 @@
+import { readFileSync } from 'fs';
+import { join } from 'path';
 import type { PipelinePhase } from '../types.js';
 import type { MonographEdge } from '../../types.js';
 import { makeId, CONFIDENCE_SCORE } from '../../types.js';
 import { insertEdges } from '../../storage/edge-store.js';
 import type { ParseOutput } from './parse.js';
 import type { StructureOutput } from './structure.js';
+import { resolveModuleSpecifier, buildWorkspacePackageMap } from './scope-resolution.js';
 
 export interface CrossFileOutput {
   resolvedEdges: MonographEdge[];
 }
 
+// Mirrors parsers/extractor.ts's re-export detection regex — used here to recover
+// the ORIGINAL specifier string behind a RE_EXPORTS edge's mangled placeholder id
+// (makeId('import', specifier) is lossy: '/' and '.' are collapsed to '_', so the
+// placeholder can't be reversed directly — we re-derive it from source instead).
+const RE_EXPORT_RE = /export\s+(?:\*|\{[^}]*\})\s+from\s+['"]([^'"]+)['"]/g;
+
 // monolean: IMPORTS name-matching removed — it matched import names against a
 // global symbol index (e.g. `import fs` → random Variable named `fs` in wrong file).
 // scope-resolution.ts now handles cross-file CALLS via source-parsed import maps.
 export const crossFilePhase: PipelinePhase<CrossFileOutput> = {
   name: 'cross-file',
   deps: ['parse', 'structure'],
-  async execute(_ctx, deps) {
+  async execute(ctx, deps) {
     const { allEdges } = deps.get('parse') as ParseOutput;
     const { fileNodes } = deps.get('structure') as StructureOutput;
 
-    function lastSegment(s: string): string {
-      const idx = s.lastIndexOf('/');
-      return idx === -1 ? s : s.slice(idx + 1);
-    }
+    const reExportEdges = allEdges.filter((e) => e.relation === 'RE_EXPORTS');
+    const resolvedEdges: MonographEdge[] = [];
 
-    function targetBasename(rawId: string): string {
-      const stripped = rawId.startsWith('import_') ? rawId.slice(7) : rawId;
-      return lastSegment(stripped);
-    }
+    if (reExportEdges.length > 0) {
+      // fileId <-> filePath maps for resolving edge endpoints to real file nodes.
+      const fileIdToPath = new Map<string, string>();
+      const knownFiles = new Set<string>();
+      for (const fileNode of fileNodes) {
+        if (fileNode.filePath) {
+          fileIdToPath.set(fileNode.id, fileNode.filePath);
+          knownFiles.add(fileNode.filePath);
+        }
+      }
+      const filePathToId = new Map<string, string>();
+      for (const [id, path] of fileIdToPath) filePathToId.set(path, id);
 
-    const fileBasenameIndex = new Map<string, string>();
-    for (const fileNode of fileNodes) {
-      const basename = lastSegment(fileNode.filePath ?? '').toLowerCase();
-      const dotIdx = basename.lastIndexOf('.');
-      const noExt = dotIdx === -1 ? basename : basename.slice(0, dotIdx);
-      fileBasenameIndex.set(basename, fileNode.id);
-      if (noExt !== basename) fileBasenameIndex.set(noExt, fileNode.id);
-    }
+      const workspaceMap = buildWorkspacePackageMap(ctx.repoPath);
 
-    const resolvedEdges: MonographEdge[] = [];
+      // Group by importing file so each source file is read at most once.
+      const edgesBySource = new Map<string, MonographEdge[]>();
+      for (const edge of reExportEdges) {
+        const arr = edgesBySource.get(edge.sourceId);
+        if (arr) arr.push(edge);
+        else edgesBySource.set(edge.sourceId, [edge]);
+      }
+
+      for (const [sourceId, edges] of edgesBySource) {
+        const filePath = fileIdToPath.get(sourceId);
+        if (!filePath) continue;
+
+        let source: string;
+        try {
+          source = readFileSync(join(ctx.repoPath, filePath), 'utf-8');
+        } catch {
+          continue;
+        }
+
+        // Recover each `export * / { ... } from '<specifier>'` string, keyed by the
+        // same mangled placeholder id the extractor used (makeId('import', specifier))
+        // so it can be matched back to the corresponding edge.
+        const specifierByPlaceholder = new Map<string, string>();
+        RE_EXPORT_RE.lastIndex = 0;
+        let m: RegExpExecArray | null;
+        while ((m = RE_EXPORT_RE.exec(source)) !== null) {
+          const specifier = m[1]!;
+          specifierByPlaceholder.set(makeId('import', specifier), specifier);
+        }
+
+        for (const edge of edges) {
+          const specifier = specifierByPlaceholder.get(edge.targetId);
+          if (!specifier) continue;
+
+          // Resolve relative to THIS importing file's own directory (reusing the
+          // same resolver scope-resolution.ts uses for IMPORTS) instead of an
+          // ambiguous global basename lookup that collides on repeated basenames
+          // like index.ts / utils.ts across the repo.
+          const resolvedPath = resolveModuleSpecifier(
+            filePath,
+            specifier,
+            ctx.repoPath,
+            knownFiles,
+            workspaceMap,
+          );
+          if (!resolvedPath) continue;
 
-    for (const edge of allEdges) {
-      if (edge.relation === 'RE_EXPORTS') {
-        const basename = targetBasename(edge.targetId).toLowerCase();
-        const dotIdx = basename.lastIndexOf('.');
-        const noExt = dotIdx === -1 ? basename : basename.slice(0, dotIdx);
-        const resolvedId = fileBasenameIndex.get(basename) ?? fileBasenameIndex.get(noExt);
+          const resolvedId = filePathToId.get(resolvedPath);
+          if (!resolvedId || resolvedId === edge.targetId) continue;
 
-        if (resolvedId && resolvedId !== edge.targetId) {
           resolvedEdges.push({
             ...edge,
             id: makeId(edge.sourceId, resolvedId, 'reexports_resolved'),
@@ -59,8 +107,8 @@ export const crossFilePhase: PipelinePhase<CrossFileOutput> = {
       }
     }
 
-    if (_ctx.db && resolvedEdges.length > 0) {
-      insertEdges(_ctx.db, resolvedEdges);
+    if (ctx.db && resolvedEdges.length > 0) {
+      insertEdges(ctx.db, resolvedEdges);
     }
 
     return { resolvedEdges };

package/src/pipeline/phases/parse.ts

@@ -3,8 +3,8 @@ import { extname, join } from 'path';
 import type { PipelinePhase, PipelineContext } from '../types.js';
 import type { MonographNode, MonographEdge } from '../../types.js';
 import { parseFile } from '../../parsers/loader.js';
-import { insertNodes } from '../../storage/node-store.js';
-import { insertEdges } from '../../storage/edge-store.js';
+import { insertNodes, deleteNodesForFile } from '../../storage/node-store.js';
+import { insertEdges, deleteEdgesForFile } from '../../storage/edge-store.js';
 import type { StructureOutput } from './structure.js';
 import { extractVariables, variableToNode } from './variables.js';
 import { ExtractionCache } from '../../cache/extraction-cache.js';
@@ -24,8 +24,18 @@ export const parsePhase: PipelinePhase<ParseOutput> = {
     const { fileNodes } = deps.get('structure') as StructureOutput;
     const symbolNodes: MonographNode[] = [];
     const allEdges: MonographEdge[] = [];
-    const freshNodes: MonographNode[] = [];
-    const freshEdges: MonographEdge[] = [];
+    // freshNodes/freshEdges (the cache-miss-only subset) are NOT accumulated in a
+    // parallel array during the loop — that duplicated every fresh node/edge object
+    // in memory for the entire pipeline run. Instead we record the [start, end)
+    // slice of symbolNodes/allEdges that each cache-miss file contributed, and
+    // materialize the fresh subset via a single slice pass at the end, only when
+    // it's actually needed (cacheHits > 0). On a cold build (cacheHits === 0) the
+    // fresh subset is never materialized at all, since nodesToInsert falls back to
+    // symbolNodes/allEdges directly in that case — eliminating the redundant
+    // allocation entirely for the memory-heaviest scenario.
+    const freshNodeRanges: Array<[number, number]> = [];
+    const freshEdgeRanges: Array<[number, number]> = [];
+    const staleFilePaths: string[] = [];
     const parseErrors: string[] = [];
     const fileContents = new Map<string, string>();
     let processed = 0;
@@ -39,8 +49,10 @@ export const parsePhase: PipelinePhase<ParseOutput> = {
       const ext = extname(absPath).toLowerCase();
       if (ext === '.md' || ext === '.markdown') { processed++; continue; }
 
-      // Fast path: mtime+size check avoids reading file content entirely
-      const cached = cache.getWithStat(absPath);
+      // Fast path: mtime+size check avoids reading file content entirely.
+      // Skipped entirely under --force so a force rebuild is a genuine from-scratch
+      // parse, not a replay of whatever extraction the cache happens to hold.
+      const cached = ctx.options.force ? null : cache.getWithStat(absPath);
       if (cached) {
         symbolNodes.push(...cached.nodes);
         allEdges.push(...cached.edges);
@@ -54,7 +66,12 @@ export const parsePhase: PipelinePhase<ParseOutput> = {
             continue;
           }
           source = readFileSync(absPath, 'utf-8');
-        } catch { continue; }
+        } catch (err) {
+          const code = (err as NodeJS.ErrnoException)?.code;
+          const detail = code || (err instanceof Error ? err.message : String(err));
+          parseErrors.push(`${fileNode.filePath}: unreadable (${detail})`);
+          continue;
+        }
         fileContents.set(fileNode.filePath ?? absPath, source);
         const result = await parseFile(absPath, source, fileNode.filePath ?? '');
         const fileSymbols: MonographNode[] = [...result.nodes];
@@ -98,10 +115,16 @@ export const parsePhase: PipelinePhase<ParseOutput> = {
           const fileHash = cache.hashContent(source);
           cache.setDeferred(absPath, fileHash, fileSymbols, fileEdges);
         } catch { /* non-fatal */ }
+        const nodeStart = symbolNodes.length;
+        const edgeStart = allEdges.length;
         symbolNodes.push(...fileSymbols);
         allEdges.push(...fileEdges);
-        freshNodes.push(...fileSymbols);
-        freshEdges.push(...fileEdges);
+        freshNodeRanges.push([nodeStart, symbolNodes.length]);
+        freshEdgeRanges.push([edgeStart, allEdges.length]);
+        // This file was re-parsed (cache miss) — its OLD node/edge set (from the
+        // previous build) must be deleted before the fresh rows are inserted below,
+        // otherwise a renamed/removed symbol's old row survives forever (ghost rows).
+        if (fileNode.filePath) staleFilePaths.push(fileNode.filePath);
         cacheMisses++;
       }
       processed++;
@@ -114,16 +137,35 @@ export const parsePhase: PipelinePhase<ParseOutput> = {
     cache.flush();
 
     if (ctx.db) {
+      const db = ctx.db;
       // Only insert freshly-parsed nodes — cached nodes are already in the DB
       // from the previous build (node IDs are deterministic from file_path + symbol).
-      // On first build (no cache hits), freshNodes === symbolNodes.
-      const nodesToInsert = cacheHits > 0 ? freshNodes : symbolNodes;
-      insertNodes(ctx.db, nodesToInsert);
+      // On first build (no cache hits), freshNodes === symbolNodes, so the fresh
+      // subset is never materialized — symbolNodes/allEdges are used directly.
+      const freshNodes = cacheHits > 0
+        ? freshNodeRanges.flatMap(([s, e]) => symbolNodes.slice(s, e))
+        : symbolNodes;
+      const freshEdges = cacheHits > 0
+        ? freshEdgeRanges.flatMap(([s, e]) => allEdges.slice(s, e))
+        : allEdges;
+      const nodesToInsert = freshNodes;
       const knownIds = new Set(symbolNodes.map(n => n.id));
-      const edgesToInsert = cacheHits > 0
-        ? freshEdges.filter(e => knownIds.has(e.targetId))
-        : allEdges.filter(e => knownIds.has(e.targetId));
-      insertEdges(ctx.db, edgesToInsert);
+      const edgesToInsert = freshEdges.filter(e => knownIds.has(e.targetId));
+
+      // For every cache-miss file, purge its OLD node/edge set BEFORE inserting the
+      // fresh parse results, inside the same transaction — otherwise a renamed or
+      // removed symbol's old row would survive forever (INSERT OR REPLACE only
+      // overwrites rows whose id still matches; it never deletes rows whose id
+      // disappeared because the symbol was renamed).
+      const writeAll = db.transaction(() => {
+        for (const filePath of staleFilePaths) {
+          deleteEdgesForFile(db, filePath);
+          deleteNodesForFile(db, filePath);
+        }
+        insertNodes(db, nodesToInsert);
+        insertEdges(db, edgesToInsert);
+      });
+      writeAll();
     }
 
     if (cacheHits > 0 && cacheMisses === 0) {
@@ -131,8 +173,9 @@ export const parsePhase: PipelinePhase<ParseOutput> = {
     }
 
     if (cacheHits > 0) {
+      const freshNodeCount = freshNodeRanges.reduce((sum, [s, e]) => sum + (e - s), 0);
       ctx.onProgress?.({ phase: 'parse', filesProcessed: processed, totalFiles: fileNodes.length,
-        message: `cache: ${cacheHits} hits, ${cacheMisses} misses (${freshNodes.length} nodes inserted)` } as any);
+        message: `cache: ${cacheHits} hits, ${cacheMisses} misses (${freshNodeCount} nodes inserted)` } as any);
     }
 
     return { symbolNodes, allEdges, parseErrors, fileContents, cacheStats: { hits: cacheHits, misses: cacheMisses } };

package/src/pipeline/phases/scan.ts

@@ -1,4 +1,4 @@
-import { readdirSync, statSync, existsSync, readFileSync } from 'fs';
+import { readdirSync, statSync, lstatSync, existsSync, readFileSync } from 'fs';
 import { join, extname } from 'path';
 import micromatch from 'micromatch';
 import type { PipelinePhase, PipelineContext } from '../types.js';
@@ -50,16 +50,22 @@ export const scanPhase: PipelinePhase<ScanOutput> = {
     }
 
     function walk(dir: string) {
-      let entries: string[];
-      try { entries = readdirSync(dir); } catch { return; }
+      let dirents: import('fs').Dirent[];
+      try { dirents = readdirSync(dir, { withFileTypes: true }); } catch { return; }
 
-      for (const entry of entries) {
+      for (const dirent of dirents) {
+        const entry = dirent.name;
         if (ignoreDirs.has(entry)) continue;
         // Skip macOS AppleDouble resource fork files (._*) — common on ExFAT/network volumes
         if (entry.startsWith('._')) continue;
+        // Never follow symlinks — a symlink to an ancestor directory causes infinite
+        // recursion (stack overflow), and a symlink to a large external tree would
+        // get fully indexed as if it were part of the repo. Matches how most
+        // code-indexing tools behave by default.
+        if (dirent.isSymbolicLink()) continue;
         const fullPath = join(dir, entry);
         let stat: ReturnType<typeof statSync>;
-        try { stat = statSync(fullPath); } catch { continue; }
+        try { stat = lstatSync(fullPath); } catch { continue; }
 
         if (stat.isDirectory()) {
           // Always traverse directories — negation patterns may rescue files inside ignored dirs

package/src/pipeline/phases/scope-resolution.ts

@@ -286,11 +286,25 @@ const GO_RESOLVE_EXTS = ['.go'];
 const JAVA_RESOLVE_EXTS = ['.java'];
 const RUST_RESOLVE_EXTS = ['.rs'];
 
+const workspacePackageMapCache = new Map<string, Map<string, string>>();
+
+/** Invalidate the cached workspace package map for a repo — call at the start
+ * of each build so long-lived processes (watch mode) pick up package.json
+ * additions/removals instead of serving a stale map from a prior build. */
+export function clearWorkspacePackageMapCache(repoPath: string): void {
+  workspacePackageMapCache.delete(repoPath);
+}
+
 /**
  * Build package-name → directory map from workspace package.json files.
  * Scans packages/ for package.json and maps npm name to its relative src path.
+ * Cached per repoPath — multiple pipeline phases (cross-file, scope-resolution,
+ * the latter's own re-export loop) call this per-file/per-edge within the same
+ * build, and the workspace's package.json set doesn't change mid-build.
  */
-function buildWorkspacePackageMap(repoPath: string): Map<string, string> {
+export function buildWorkspacePackageMap(repoPath: string): Map<string, string> {
+  const cached = workspacePackageMapCache.get(repoPath);
+  if (cached) return cached;
   const result = new Map<string, string>();
   const packagesDir = join(repoPath, 'packages');
   try {
@@ -315,10 +329,11 @@ function buildWorkspacePackageMap(repoPath: string): Map<string, string> {
     };
     scanDirs(packagesDir, 0);
   } catch { /* no packages dir */ }
+  workspacePackageMapCache.set(repoPath, result);
   return result;
 }
 
-function resolveModuleSpecifier(
+export function resolveModuleSpecifier(
   importerPath: string,
   specifier: string,
   repoPath: string,
@@ -346,8 +361,8 @@ function resolveModuleSpecifier(
     return null;
   }
 
-  // Workspace package specifier: @monomind/hooks → packages/@monomind/hooks/src/index.ts
-  // Also handles subpath: @monomind/hooks/src/foo → packages/@monomind/hooks/src/foo.ts
+  // Workspace package specifier: @monoes/hooks → packages/@monomind/hooks/src/index.ts
+  // Also handles subpath: @monoes/hooks/src/foo → packages/@monomind/hooks/src/foo.ts
   for (const [pkgName, pkgDir] of workspaceMap) {
     if (specifier === pkgName) {
       // Bare import: resolve to package entry point (src/index.ts)

package/src/pipeline/types.ts

@@ -20,6 +20,8 @@ export interface PipelineOptions {
   ignore: string[];
   /** Max Section nodes to submit to LLM extraction (0 = disabled). Default 0. */
   llmMaxSections: number;
+  /** When true, bypass the on-disk extraction cache entirely and re-parse every file from scratch. Default false. */
+  force?: boolean;
 }
 
 export const DEFAULT_OPTIONS: PipelineOptions = {
@@ -29,6 +31,7 @@ export const DEFAULT_OPTIONS: PipelineOptions = {
   workerChunkBudgetBytes: 20971520,
   ignore: [],
   llmMaxSections: 0,
+  force: false,
 };
 
 export interface PipelinePhase<TOutput> {

package/src/storage/db.ts

@@ -13,7 +13,23 @@ import { MonographError } from '../types.js';
 
 export type MonographDb = Database.Database;
 
-export function openDb(dbPath: string): MonographDb {
+export interface OpenDbOptions {
+  /**
+   * When true, throw a clear error instead of silently creating a fresh,
+   * empty-but-migrated database if `dbPath` doesn't exist yet. Defaults to
+   * false to preserve legacy build-time behavior (the `monograph build`
+   * codepath legitimately creates new DBs). Read-only analysis tools should
+   * pass `true` so pointing them at a repo whose real index lives elsewhere
+   * (e.g. running from a subdirectory) fails loudly instead of reporting
+   * fake-successful-looking empty results.
+   */
+  fileMustExist?: boolean;
+}
+
+export function openDb(dbPath: string, options: OpenDbOptions = {}): MonographDb {
+  if (options.fileMustExist && !existsSync(dbPath)) {
+    throw new MonographError(`Monograph database does not exist at ${dbPath}. Run monograph build first.`);
+  }
   try {
     mkdirSync(dirname(dbPath), { recursive: true });
     const db = new Database(dbPath);
@@ -74,6 +90,16 @@ export function atomicRebuild(dbPath: string, buildFn: (db: MonographDb) => void
     buildFn(db);
     db.close();
     renameSync(tmpPath, dbPath);
+    // The old db's WAL-mode sidecar files belong to the file we just replaced —
+    // if left behind, the next process to open dbPath pairs the NEW db file with
+    // a STALE -wal/-shm whose salt/checkpoint state doesn't match, which can
+    // surface as "file is not a database" or subtle corruption.
+    for (const suffix of ['-wal', '-shm']) {
+      const sidecar = dbPath + suffix;
+      if (existsSync(sidecar)) {
+        try { unlinkSync(sidecar); } catch { /* best-effort cleanup */ }
+      }
+    }
   } catch (err) {
     db.close();
     if (existsSync(tmpPath)) {