@monoes/monograph 1.0.0 → 1.2.0

package/src/pipeline/phases/tools.ts

@@ -0,0 +1,170 @@
+import { readFileSync, statSync } from 'fs';
+import { extname } from 'path';
+import type { PipelinePhase } from '../types.js';
+import type { MonographNode, MonographEdge } from '../../types.js';
+import { makeId, toNormLabel } from '../../types.js';
+import { insertNodes } from '../../storage/node-store.js';
+import { insertEdges } from '../../storage/edge-store.js';
+import type { StructureOutput } from './structure.js';
+
+// ── Constants ─────────────────────────────────────────────────────────────────
+
+const CODE_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs']);
+
+// ── Output types ──────────────────────────────────────────────────────────────
+
+export interface ToolDef {
+  name: string;
+  filePath: string;
+  description?: string;
+  handlerNodeId?: string;
+  toolNodeId: string;
+}
+
+export interface ToolsOutput {
+  toolDefs: ToolDef[];
+}
+
+// ── Detection regexes ─────────────────────────────────────────────────────────
+
+/** server.tool('name', ...) or server.tool("name", ...) */
+const SERVER_TOOL_RE = /server\.tool\(\s*['"]([^'"]+)['"]/g;
+
+/** export const FOO_TOOL = { name: 'foo', description: '...' } */
+const EXPORTED_TOOL_CONST_RE = /export\s+const\s+\w+[Tt][Oo][Oo][Ll]\w*\s*=\s*\{[^}]*name:\s*['"]([^'"]+)['"]/g;
+
+/** Array variable name pattern: TOOLS, tools, MY_TOOLS, toolsList, etc. (case-insensitive on 'tools') */
+const TOOLS_ARRAY_VAR_RE = /(?:export\s+)?(?:const|let|var)\s+(\w*[Tt][Oo][Oo][Ll][Ss]?\w*)\s*(?::\s*\w+\[\])?\s*=\s*\[/g;
+
+// ── Phase ─────────────────────────────────────────────────────────────────────
+
+export const toolsPhase: PipelinePhase<ToolsOutput> = {
+  name: 'tools',
+  deps: ['parse', 'structure'],
+  async execute(ctx, deps) {
+    const { fileNodes } = deps.get('structure') as StructureOutput;
+    const toolDefs: ToolDef[] = [];
+    const toolNodes: MonographNode[] = [];
+    const handlesEdges: MonographEdge[] = [];
+
+    for (const fileNode of fileNodes) {
+      const relPath = fileNode.filePath ?? '';
+      const ext = extname(relPath).toLowerCase();
+
+      if (!CODE_EXTENSIONS.has(ext)) continue;
+
+      const source = safeReadSource(`${ctx.repoPath}/${relPath}`, ctx.options.maxFileSizeBytes);
+      if (!source) continue;
+
+      const detectedNames = new Set<string>();
+
+      // ── 1. server.tool('name', ...) pattern ───────────────────────────────
+      const serverToolRe = new RegExp(SERVER_TOOL_RE.source, 'g');
+      let m: RegExpExecArray | null;
+      while ((m = serverToolRe.exec(source)) !== null) {
+        detectedNames.add(m[1]);
+      }
+
+      // ── 2. Exported constant tool pattern ─────────────────────────────────
+      const exportedToolRe = new RegExp(EXPORTED_TOOL_CONST_RE.source, 'g');
+      while ((m = exportedToolRe.exec(source)) !== null) {
+        detectedNames.add(m[1]);
+      }
+
+      // ── 3. TOOLS array pattern ────────────────────────────────────────────
+      const toolsArrayRe = new RegExp(TOOLS_ARRAY_VAR_RE.source, 'g');
+      while ((m = toolsArrayRe.exec(source)) !== null) {
+        const arrayStart = m.index + m[0].length;
+        // Extract the array block (up to 4000 chars to avoid huge allocations)
+        const block = source.slice(arrayStart, arrayStart + 4000);
+        // Only match if array contains a description property (reduces false positives)
+        if (!block.includes('description')) continue;
+        // Find all name: 'foo' entries in the block
+        const nameRe = /name:\s*['"]([^'"]+)['"]/g;
+        let nm: RegExpExecArray | null;
+        while ((nm = nameRe.exec(block)) !== null) {
+          detectedNames.add(nm[1]);
+        }
+      }
+
+      // ── Create nodes & edges for each detected tool ───────────────────────
+      for (const toolName of detectedNames) {
+        const toolNodeId = makeId('tool', toolName, relPath);
+
+        const toolNode: MonographNode = {
+          id: toolNodeId,
+          label: 'Tool',
+          name: toolName,
+          normLabel: toNormLabel(toolName),
+          filePath: relPath,
+          startLine: 0,
+          endLine: 0,
+          isExported: true,
+          language: langFromExt(ext),
+        };
+        toolNodes.push(toolNode);
+
+        const def: ToolDef = { name: toolName, filePath: relPath, toolNodeId };
+
+        // Attempt handler lookup in the DB
+        if (ctx.db) {
+          const lowerTool = toolName.toLowerCase().replace(/[_-]/g, '');
+          // Query Function/Method nodes in the same file
+          const rows = ctx.db
+            .prepare(
+              `SELECT id, name FROM nodes
+               WHERE file_path = ?
+               AND label IN ('Function', 'Method')`,
+            )
+            .all(relPath) as { id: string; name: string }[];
+
+          // Find nodes whose name contains the tool name (case-insensitive, stripped)
+          const matches = rows.filter(row => {
+            const n = row.name.toLowerCase().replace(/[_-]/g, '');
+            return n.includes(lowerTool) || (n.length > 0 && lowerTool.includes(n));
+          });
+
+          if (matches.length === 1) {
+            const edgeId = makeId(toolNodeId, matches[0].id, 'handles_tool');
+            handlesEdges.push({
+              id: edgeId,
+              sourceId: toolNodeId,
+              targetId: matches[0].id,
+              relation: 'HANDLES_TOOL',
+              confidence: 'EXTRACTED',
+              confidenceScore: 0.85,
+            });
+            def.handlerNodeId = matches[0].id;
+          }
+        }
+
+        toolDefs.push(def);
+      }
+    }
+
+    if (ctx.db) {
+      insertNodes(ctx.db, toolNodes);
+      insertEdges(ctx.db, handlesEdges);
+    }
+
+    return { toolDefs };
+  },
+};
+
+// ── Utilities ─────────────────────────────────────────────────────────────────
+
+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;
+  }
+}
+
+function langFromExt(ext: string): string {
+  if (ext === '.ts' || ext === '.tsx') return 'typescript';
+  if (ext === '.js' || ext === '.jsx' || ext === '.mjs' || ext === '.cjs') return 'javascript';
+  return 'unknown';
+}

package/src/pipeline/phases/variables-phase.ts

@@ -0,0 +1,36 @@
+import type { PipelinePhase, PipelineContext } from '../types.js';
+import type { ParseOutput } from './parse.js';
+import { extractVariables, variableToNode } from './variables.js';
+
+export interface VariablesOutput {
+  variableCount: number;
+}
+
+export const variablesPhase: PipelinePhase<VariablesOutput> = {
+  name: 'variables',
+  deps: ['parse'],
+  async execute(ctx: PipelineContext, deps: Map<string, unknown>): Promise<VariablesOutput> {
+    const { fileContents } = deps.get('parse') as ParseOutput;
+
+    const stmt = ctx.db.prepare(`
+      INSERT OR IGNORE INTO nodes (id, label, name, norm_label, file_path, start_line, end_line, is_exported)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    `);
+
+    let variableCount = 0;
+    for (const [filePath, source] of fileContents) {
+      const vars = extractVariables(source, filePath);
+      for (const v of vars) {
+        const node = variableToNode(v);
+        stmt.run(
+          node.id, node.label, node.name, node.normLabel ?? node.name.toLowerCase(),
+          node.filePath ?? null, node.startLine ?? null, node.endLine ?? null,
+          node.isExported ? 1 : 0,
+        );
+        variableCount++;
+      }
+    }
+
+    return { variableCount };
+  },
+};

package/src/pipeline/phases/variables.ts

@@ -0,0 +1,67 @@
+import type { MonographNode } from '../../types.js';
+
+export interface VariableInfo {
+  name: string;
+  isExported: boolean;
+  line: number;
+  filePath: string;
+}
+
+// Regex for top-level variable declarations.
+// We detect nesting depth by counting braces before the match.
+const TOP_LEVEL_VAR = /^(export\s+)?(const|let|var)\s+(\w+)\s*[=:]/gm;
+
+/**
+ * Strip string literals, template literals, and comments from source text before
+ * brace-depth counting, so braces inside those constructs don't skew the depth.
+ */
+function stripNonCodeBraces(src: string): string {
+  // Replace content inside single/double-quoted strings and block comments with
+  // equal-length spaces (preserving offsets/line numbers), then strip line comments.
+  return src
+    .replace(/`[^`\\]*(?:\\[\s\S][^`\\]*)*`/g, m => ' '.repeat(m.length))
+    .replace(/"(?:[^"\\]|\\.)*"/g, m => ' '.repeat(m.length))
+    .replace(/'(?:[^'\\]|\\.)*'/g, m => ' '.repeat(m.length))
+    .replace(/\/\*[\s\S]*?\*\//g, m => ' '.repeat(m.length))
+    .replace(/\/\/[^\n]*/g, m => ' '.repeat(m.length));
+}
+
+export function extractVariables(source: string, filePath: string): VariableInfo[] {
+  const results: VariableInfo[] = [];
+  let match: RegExpExecArray | null;
+  TOP_LEVEL_VAR.lastIndex = 0;
+
+  // Pre-process: strip string/comment content so braces inside them don't count
+  const stripped = stripNonCodeBraces(source);
+
+  while ((match = TOP_LEVEL_VAR.exec(source)) !== null) {
+    const before = stripped.slice(0, match.index);
+    // Count brace depth — top-level means depth == 0
+    let depth = 0;
+    for (const ch of before) {
+      if (ch === '{') depth++;
+      else if (ch === '}') depth--;
+    }
+    if (depth !== 0) continue;
+
+    const isExported = !!match[1];
+    const name = match[3];
+    const line = before.split('\n').length;
+    results.push({ name, isExported, line, filePath });
+  }
+
+  return results;
+}
+
+export function variableToNode(v: VariableInfo): MonographNode {
+  return {
+    id: `var:${v.filePath}:${v.name}`,
+    label: 'Variable',
+    name: v.name,
+    normLabel: v.name.toLowerCase(),
+    filePath: v.filePath,
+    startLine: v.line,
+    endLine: v.line,
+    isExported: v.isExported,
+  };
+}

package/src/pipeline/phases/wildcard-phase.ts

@@ -0,0 +1,45 @@
+import type { PipelinePhase, PipelineContext } from '../types.js';
+import type { ParseOutput } from './parse.js';
+import type { CrossFileOutput } from './cross-file.js';
+import { synthesizeWildcardImports } from './wildcard-synthesis.js';
+import type { MonographNode, MonographEdge } from '../../types.js';
+
+export interface WildcardSynthesisOutput {
+  synthesizedCount: number;
+}
+
+export const wildcardSynthesisPhase: PipelinePhase<WildcardSynthesisOutput> = {
+  name: 'wildcard-synthesis',
+  deps: ['parse', 'cross-file'],
+  async execute(ctx: PipelineContext, deps: Map<string, unknown>): Promise<WildcardSynthesisOutput> {
+    const { symbolNodes: allNodes, allEdges, fileContents } = deps.get('parse') as ParseOutput;
+    const { resolvedEdges } = deps.get('cross-file') as CrossFileOutput;
+
+    const allKnownEdges: MonographEdge[] = [...allEdges, ...resolvedEdges];
+    const allKnownNodes: MonographNode[] = allNodes;
+
+    let synthesizedCount = 0;
+
+    const fileNodeIndex = new Map<string, string>();
+    for (const node of allKnownNodes) {
+      if (node.filePath) fileNodeIndex.set(node.filePath, node.id);
+    }
+
+    const stmt = ctx.db.prepare(`
+      INSERT OR IGNORE INTO edges (id, source_id, target_id, relation, confidence, confidence_score)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `);
+
+    for (const [filePath, source] of fileContents) {
+      const fileNodeId = fileNodeIndex.get(filePath) ?? `file:${filePath}`;
+      const { synthesizedEdges } = synthesizeWildcardImports(fileNodeId, source, allKnownNodes, allKnownEdges);
+
+      for (const edge of synthesizedEdges) {
+        stmt.run(edge.id, edge.sourceId, edge.targetId, edge.relation, edge.confidence, edge.confidenceScore);
+        synthesizedCount++;
+      }
+    }
+
+    return { synthesizedCount };
+  },
+};

package/src/pipeline/phases/wildcard-synthesis.ts

@@ -0,0 +1,214 @@
+import { dirname, resolve, basename } from 'path';
+import type { MonographNode, MonographEdge } from '../../types.js';
+import { makeId, CONFIDENCE_SCORE } from '../../types.js';
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+export interface WildcardBinding {
+  /** The namespace alias, e.g. `X` in `import * as X from './module'` */
+  alias: string;
+  /** The module specifier, e.g. `./module` */
+  moduleSpecifier: string;
+}
+
+export interface WildcardMemberAccess {
+  alias: string;
+  member: string;
+  line: number;
+}
+
+export interface WildcardSynthesisResult {
+  /** New edges synthesized from wildcard member accesses */
+  synthesizedEdges: MonographEdge[];
+}
+
+// ── Regex patterns ────────────────────────────────────────────────────────────
+
+/** Matches: import * as X from './path' or import * as X from "../path" */
+const WILDCARD_IMPORT_RE = /import\s+\*\s+as\s+(\w+)\s+from\s+['"]([^'"]+)['"]/g;
+
+// ── Core functions ────────────────────────────────────────────────────────────
+
+/**
+ * Extracts all wildcard import bindings from a TypeScript/JavaScript source file.
+ *
+ * @param source - Raw source code content
+ * @returns Array of wildcard bindings found in the source
+ */
+export function extractWildcardBindings(source: string): WildcardBinding[] {
+  const results: WildcardBinding[] = [];
+  WILDCARD_IMPORT_RE.lastIndex = 0;
+
+  let match: RegExpExecArray | null;
+  while ((match = WILDCARD_IMPORT_RE.exec(source)) !== null) {
+    results.push({ alias: match[1], moduleSpecifier: match[2] });
+  }
+
+  return results;
+}
+
+/**
+ * Extracts all member accesses for a given namespace alias from source code.
+ * e.g. for alias `ns`, detects `ns.foo`, `ns.bar`, etc.
+ *
+ * @param source - Raw source code content
+ * @param alias - The namespace alias to scan for
+ * @returns Array of member accesses with line numbers
+ */
+export function extractWildcardMemberAccesses(
+  source: string,
+  alias: string,
+): WildcardMemberAccess[] {
+  const results: WildcardMemberAccess[] = [];
+  const memberRe = new RegExp(`\\b${alias}\\.(\\w+)`, 'g');
+  const lines = source.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    memberRe.lastIndex = 0;
+    let m: RegExpExecArray | null;
+    const seen = new Set<string>();
+    while ((m = memberRe.exec(line)) !== null) {
+      const member = m[1];
+      if (!seen.has(member)) {
+        seen.add(member);
+        results.push({ alias, member, line: i + 1 });
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Resolve a relative module specifier to an absolute file path (without extension).
+ * Returns null when `sourceFilePath` is unavailable or the specifier is non-relative.
+ */
+function resolveSpecifierPath(
+  sourceFilePath: string | undefined | null,
+  moduleSpecifier: string,
+): string | null {
+  if (!sourceFilePath) return null;
+  if (!moduleSpecifier.startsWith('.')) return null;
+  const dir = dirname(sourceFilePath);
+  const resolved = resolve(dir, moduleSpecifier);
+  // Strip extension so we can match .ts, .js, .tsx, .mjs, etc.
+  return resolved.replace(/\.[^./\\]+$/, '');
+}
+
+/**
+ * Return true when a candidate file path matches the resolved specifier path.
+ *
+ * Handles:
+ * - Exact basename-without-extension match (resolvedPath is a bare module path)
+ * - Index file: `resolvedPath/index` matches `candidatePath` ending in `/index.<ext>`
+ */
+function specifierMatchesFilePath(
+  resolvedPath: string,
+  candidateFilePath: string,
+): boolean {
+  // Strip extension from candidate for comparison
+  const candidateBase = candidateFilePath.replace(/\.[^./\\]+$/, '');
+  if (candidateBase === resolvedPath) return true;
+  // Handle implicit /index
+  if (candidateBase === resolvedPath + '/index') return true;
+  return false;
+}
+
+/**
+ * Synthesizes direct symbol edges from wildcard namespace member accesses.
+ *
+ * Given source code that has `import * as X from './module'` and uses `X.foo`,
+ * this function creates IMPORTS edges from the source file node to the `foo`
+ * export node in `./module`.
+ *
+ * @param sourceFileId - The node ID of the file containing the wildcard import
+ * @param source - Raw source code of the file
+ * @param nodes - All known nodes in the graph
+ * @param edges - All known edges (used to avoid duplicates)
+ * @returns Synthesized edges that directly link callers to target exports
+ */
+export function synthesizeWildcardImports(
+  sourceFileId: string,
+  source: string,
+  nodes: MonographNode[],
+  edges: MonographEdge[],
+): WildcardSynthesisResult {
+  const bindings = extractWildcardBindings(source);
+  if (bindings.length === 0) return { synthesizedEdges: [] };
+
+  // Build an index of existing edge IDs to avoid duplicates
+  const existingEdgeIds = new Set(edges.map(e => e.id));
+
+  // Build id→node map for path-based filtering and name→nodes index
+  const nodeById = new Map<string, MonographNode>(nodes.map(n => [n.id, n]));
+  const sourceNode = nodeById.get(sourceFileId);
+
+  // Build a name→node[] index restricted to exported nodes
+  const nameIndex = new Map<string, MonographNode[]>();
+  for (const node of nodes) {
+    if (!node.isExported) continue;
+    const existing = nameIndex.get(node.name) ?? [];
+    existing.push(node);
+    nameIndex.set(node.name, existing);
+    // Also index by normLabel if different
+    if (node.normLabel && node.normLabel !== node.name) {
+      const byNorm = nameIndex.get(node.normLabel) ?? [];
+      byNorm.push(node);
+      nameIndex.set(node.normLabel, byNorm);
+    }
+  }
+
+  const synthesizedEdges: MonographEdge[] = [];
+
+  for (const binding of bindings) {
+    // Resolve the module specifier to an absolute path (extension-stripped)
+    const resolvedPath = resolveSpecifierPath(sourceNode?.filePath, binding.moduleSpecifier);
+
+    // Basename of the specifier for fallback matching
+    const specBase = basename(binding.moduleSpecifier).replace(/\.[^.]+$/, '').toLowerCase();
+
+    const accesses = extractWildcardMemberAccesses(source, binding.alias);
+
+    for (const access of accesses) {
+      const candidateNodes: MonographNode[] =
+        nameIndex.get(access.member) ?? nameIndex.get(access.member.toLowerCase()) ?? [];
+
+      // Filter candidates to only those belonging to the target module
+      let filtered: MonographNode[];
+      if (resolvedPath !== null) {
+        // Strong filter: match by resolved absolute path
+        filtered = candidateNodes.filter(
+          n => n.filePath != null && specifierMatchesFilePath(resolvedPath, n.filePath),
+        );
+      } else {
+        // Fallback: match by basename (mirrors cross-file.ts resolution)
+        filtered = candidateNodes.filter(
+          n => n.filePath != null &&
+            basename(n.filePath).replace(/\.[^.]+$/, '').toLowerCase() === specBase,
+        );
+      }
+
+      // If still no match with basename fallback, skip — no cross-module edge
+      if (filtered.length === 0) continue;
+
+      for (const target of filtered) {
+        const edgeId = makeId(sourceFileId, target.id, 'wildcard', access.member);
+        if (existingEdgeIds.has(edgeId)) continue;
+
+        synthesizedEdges.push({
+          id: edgeId,
+          sourceId: sourceFileId,
+          targetId: target.id,
+          relation: 'IMPORTS',
+          confidence: 'INFERRED',
+          confidenceScore: CONFIDENCE_SCORE.INFERRED,
+        });
+
+        existingEdgeIds.add(edgeId);
+      }
+    }
+  }
+
+  return { synthesizedEdges };
+}

package/src/pipeline/progress.ts

@@ -0,0 +1,58 @@
+export type ProgressPhase =
+  | 'discovery' | 'parse' | 'churn' | 'complexity'
+  | 'duplication' | 'scoring' | 'render' | 'complete';
+
+export interface ProgressEvent {
+  phase: ProgressPhase;
+  filesProcessed?: number;
+  totalFiles?: number;
+  message?: string;
+  elapsedMs?: number;
+}
+
+export type ProgressCallback = (event: ProgressEvent) => void;
+
+export class ProgressReporter {
+  private callbacks: ProgressCallback[] = [];
+  private startTime = Date.now();
+  private counts = new Map<ProgressPhase, number>();
+
+  subscribe(cb: ProgressCallback): () => void {
+    this.callbacks.push(cb);
+    return () => {
+      const idx = this.callbacks.indexOf(cb);
+      if (idx !== -1) this.callbacks.splice(idx, 1);
+    };
+  }
+
+  emit(phase: ProgressPhase, opts?: Omit<ProgressEvent, 'phase' | 'elapsedMs'>): void {
+    const event: ProgressEvent = {
+      phase,
+      elapsedMs: Date.now() - this.startTime,
+      ...opts,
+    };
+    for (const cb of this.callbacks) {
+      try { cb(event); } catch { /* don't let progress errors crash the pipeline */ }
+    }
+  }
+
+  increment(phase: ProgressPhase): void {
+    this.counts.set(phase, (this.counts.get(phase) ?? 0) + 1);
+  }
+
+  getCount(phase: ProgressPhase): number {
+    return this.counts.get(phase) ?? 0;
+  }
+}
+
+export function consoleProgressReporter(enabled: boolean): ProgressCallback {
+  return (event) => {
+    if (!enabled) return;
+    const pct = event.totalFiles && event.filesProcessed
+      ? ` (${Math.round(event.filesProcessed / event.totalFiles * 100)}%)`
+      : '';
+    const msg = event.message ?? `phase: ${event.phase}`;
+    process.stderr.write(`\r  ${msg}${pct}   `);
+    if (event.phase === 'complete') process.stderr.write('\n');
+  };
+}

package/src/pipeline/runner.ts

@@ -2,23 +2,37 @@ import type { PipelinePhase, PipelineContext } from './types.js';
 import { MonographError } from '../types.js';
 
 export class PipelineRunner {
-  private readonly order: string[];
+  private readonly phases: PipelinePhase<unknown>[];
 
-  constructor(private readonly phases: PipelinePhase<unknown>[]) {
-    this.order = topoSort(phases);
+  constructor(phases: PipelinePhase<unknown>[]) {
+    this.phases = phases;
+    // Validate: detect cycles and unknown deps
+    topoSort(phases);
   }
 
   async run(ctx: PipelineContext): Promise<Map<string, unknown>> {
     const outputs = new Map<string, unknown>();
     const phaseMap = new Map(this.phases.map(p => [p.name, p]));
 
-    for (const name of this.order) {
+    // Lazily-created promise per phase — ensures dep promises exist before they are awaited
+    const promises = new Map<string, Promise<void>>();
+
+    const getOrCreatePromise = (name: string): Promise<void> => {
+      if (promises.has(name)) return promises.get(name)!;
       const phase = phaseMap.get(name)!;
-      ctx.onProgress?.({ phase: name });
-      const output = await phase.execute(ctx, outputs);
-      outputs.set(name, output);
-    }
+      const p = (async () => {
+        // Wait for all dep phases to finish
+        await Promise.all(phase.deps.map(dep => getOrCreatePromise(dep)));
+        ctx.onProgress?.({ phase: phase.name });
+        const output = await phase.execute(ctx, outputs);
+        outputs.set(phase.name, output);
+      })();
+      promises.set(name, p);
+      return p;
+    };
 
+    // Kick off all phases — each self-manages its dep wait via lazy promise creation
+    await Promise.all(this.phases.map(phase => getOrCreatePromise(phase.name)));
     return outputs;
   }
 }
@@ -59,3 +73,39 @@ function topoSort(phases: PipelinePhase<unknown>[]): string[] {
 
   return result;
 }
+
+export interface IncrementalAstOptions {
+  /** If true, preserve INFERRED and AMBIGUOUS edges during code-only rebuild. Default true. */
+  preserveInferred?: boolean;
+}
+
+/**
+ * Incremental AST-only rebuild: clears EXTRACTED edges (re-parsed from code)
+ * while preserving INFERRED and AMBIGUOUS edges (derived by reasoning).
+ * Accepts a list of changed file paths; if empty, clears all EXTRACTED edges.
+ */
+export async function runIncrementalAst(
+  db: import('better-sqlite3').Database,
+  changedFiles: string[],
+  options: IncrementalAstOptions = {},
+): Promise<void> {
+  const { preserveInferred = true } = options;
+
+  if (preserveInferred) {
+    if (changedFiles.length > 0) {
+      const placeholders = changedFiles.map(() => '?').join(',');
+      db.prepare(`
+        DELETE FROM edges
+        WHERE confidence = 'EXTRACTED'
+        AND (
+          source_id IN (SELECT id FROM nodes WHERE file_path IN (${placeholders}))
+          OR target_id IN (SELECT id FROM nodes WHERE file_path IN (${placeholders}))
+        )
+      `).run(...changedFiles, ...changedFiles);
+    } else {
+      db.prepare(`DELETE FROM edges WHERE confidence = 'EXTRACTED'`).run();
+    }
+  } else {
+    db.prepare(`DELETE FROM edges`).run();
+  }
+}