forge-server 0.1.0

package/src/ingestion/indexer.ts

@@ -0,0 +1,984 @@
+/**
+ * Indexer - orchestrates the full ingestion pipeline.
+ * Pipeline: file -> hash check -> AST parse -> chunk -> embed -> store (Qdrant + FalkorDB)
+ * Handles both initial full indexing and incremental re-indexing.
+ *
+ * Phase 2 additions:
+ *   - Populate full graph edges: IMPORTS, EXPORTS, EXTENDS, IMPLEMENTS, CALLS
+ *   - Create FalkorDB indexes on startup
+ *   - Run git analysis (CO_MODIFIED, TESTS edges) after full index
+ *   - Static CALLS edge discovery via identifier matching
+ *
+ * Note: routing-engine.ts is not merged from forge-graph-rag (it is replaced by the
+ * pipeline server's own knowledge/ modules). Ownership routing is inlined here instead.
+ */
+
+import { readFile, stat, readdir } from 'fs/promises';
+import { resolve, extname, join, dirname, isAbsolute } from 'path';
+import { createHash } from 'crypto';
+import type { GraphStore, VectorStore, FileContentCache } from '../storage/interfaces.js';
+import type { RepoConfig, ParseResult, ParsedEntity, ParsedImport } from '../util/types.js';
+import { parseFile, getLanguage } from './parser.js';
+import { chunkFromEntities, chunkFixed } from './chunker.js';
+import { chunkMarkdown } from './markdown-chunker.js';
+import { extractKnowledge } from './markdown-knowledge.js';
+import { embedBatch, embedText } from './embedder.js';
+import { hashContent } from '../storage/file-cache.js';
+import { logger } from '../util/logger.js';
+import { runGitAnalysis, analyzeFileStats, extractCommitRecords } from './git-analyzer.js';
+import { MARK_SYMBOL_OBSERVATIONS_STALE } from '../query/graph-queries.js';
+
+// ============================================================
+// Inline routing helpers (replaces knowledge/routing-engine.js import)
+// ============================================================
+
+interface IndexingRoute {
+  writeGraphNode: boolean;
+  writeEntityNodes: boolean;
+  writeVectorChunks: boolean;
+  writeFileCache: boolean;
+  parseAst: boolean;
+  watchForChanges: boolean;
+}
+
+function isOwnedRepo(repoId: string, repos: RepoConfig[]): boolean {
+  const repo = repos.find(r => r.id === repoId);
+  return repo?.ownership === 'owned';
+}
+
+function getIndexingRoute(repoId: string, repos: RepoConfig[]): IndexingRoute {
+  const owned = isOwnedRepo(repoId, repos);
+  return {
+    writeGraphNode: owned,
+    writeEntityNodes: owned,
+    writeVectorChunks: true,   // Always write vectors
+    writeFileCache: owned,     // Cache only owned repo files
+    parseAst: owned,           // Full AST parse only for owned repos
+    watchForChanges: owned,    // Watch only owned repos
+  };
+}
+
+// ============================================================
+// Module state
+// ============================================================
+
+// Track which files are indexed and their content hashes
+const indexedFiles = new Map<string, { contentHash: string; indexedAt: number }>();
+
+// Track indexing stats per repo
+const repoStats = new Map<string, {
+  filesIndexed: number;
+  filesTotal: number;
+  lastIndexedAt: number;
+}>();
+
+// Track all entities discovered per repo for CALLS edge analysis
+// Map<repoId, Map<entityName, filePath>>
+const repoEntityRegistry = new Map<string, Map<string, string>>();
+
+const NON_CODE_EXTENSIONS = new Set([
+  '.json', '.yaml', '.yml', '.toml', '.md', '.mdx',
+  '.graphql', '.gql', '.sql', '.txt', '.csv',
+]);
+
+const CODE_EXTENSIONS = new Set([
+  '.ts', '.tsx', '.js', '.jsx', '.mts', '.cts', '.mjs', '.cjs',
+]);
+
+const SKIP_EXTENSIONS = new Set([
+  '.png', '.jpg', '.jpeg', '.gif', '.svg', '.ico', '.webp',
+  '.ttf', '.woff', '.woff2', '.eot',
+  '.pdf', '.docx', '.xlsx',
+  '.zip', '.tar', '.gz',
+  '.exe', '.dll', '.so', '.dylib',
+  '.lock',
+]);
+
+export interface IndexerOptions {
+  repoConfig: RepoConfig;
+  graphStore: GraphStore;
+  vectorStore: VectorStore;
+  fileCache: FileContentCache;
+  maxFileSizeKb?: number;
+  /**
+   * Full list of repos from config. Required for routing decisions.
+   * If omitted, the indexer falls back to treating the repo as owned
+   * (safe backward-compatible default — single-repo setups are always owned).
+   */
+  allRepos?: RepoConfig[];
+}
+
+export interface IndexResult {
+  repoId: string;
+  filesProcessed: number;
+  filesSkipped: number;
+  filesErrored: number;
+  chunksCreated: number;
+  knowledgeItemsExtracted: number;
+  errors: string[];
+  durationMs: number;
+}
+
+// Patterns to skip during directory walk
+const SKIP_DIRS = new Set([
+  'node_modules', '.git', 'dist', 'build', '.cache', '.next', 'coverage',
+  '__pycache__', '.pytest_cache', 'vendor', 'target',
+]);
+
+/**
+ * Walk a directory tree and collect all file paths.
+ * Respects SKIP_DIRS and file extension filters.
+ */
+async function walkDir(dirPath: string, results: string[] = []): Promise<string[]> {
+  let entries;
+  try {
+    entries = await readdir(dirPath, { withFileTypes: true });
+  } catch {
+    return results;
+  }
+
+  for (const entry of entries) {
+    const fullPath = join(dirPath, entry.name);
+
+    if (entry.isDirectory()) {
+      if (!SKIP_DIRS.has(entry.name) && !entry.name.startsWith('.')) {
+        await walkDir(fullPath, results);
+      }
+    } else if (entry.isFile()) {
+      const ext = extname(entry.name).toLowerCase();
+      if (!SKIP_EXTENSIONS.has(ext) && (CODE_EXTENSIONS.has(ext) || NON_CODE_EXTENSIONS.has(ext))) {
+        results.push(fullPath);
+      }
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Perform a full index of a repository.
+ * Walks all files, computes content hashes, skips unchanged, indexes new/changed.
+ * Phase 2: also creates FalkorDB indexes and runs git analysis afterward.
+ */
+export async function fullIndex(opts: IndexerOptions): Promise<IndexResult> {
+  const { repoConfig, graphStore } = opts;
+  const { id: repoId, path: repoPath } = repoConfig;
+  const startTime = Date.now();
+
+  const result: IndexResult = {
+    repoId,
+    filesProcessed: 0,
+    filesSkipped: 0,
+    filesErrored: 0,
+    chunksCreated: 0,
+    knowledgeItemsExtracted: 0,
+    errors: [],
+    durationMs: 0,
+  };
+
+  logger.info('Starting full index', { repoId, path: repoPath });
+
+  // Phase 2: Ensure FalkorDB indexes exist before indexing
+  try {
+    await graphStore.ensureIndexes();
+  } catch (err) {
+    logger.warn('Failed to ensure graph indexes', { error: String(err) });
+  }
+
+  // Initialize entity registry for this repo
+  repoEntityRegistry.set(repoId, new Map());
+
+  // Walk the directory tree
+  let allFiles: string[];
+  try {
+    allFiles = await walkDir(resolve(repoPath));
+  } catch (err) {
+    const msg = `Failed to walk repo directory: ${String(err)}`;
+    result.errors.push(msg);
+    result.durationMs = Date.now() - startTime;
+    logger.error(msg, { repoId, path: repoPath });
+    return result;
+  }
+
+  // Update total file count in stats
+  repoStats.set(repoId, {
+    filesIndexed: repoStats.get(repoId)?.filesIndexed ?? 0,
+    filesTotal: allFiles.length,
+    lastIndexedAt: repoStats.get(repoId)?.lastIndexedAt ?? 0,
+  });
+
+  // Process files in batches to avoid overwhelming memory
+  const BATCH_SIZE = 20;
+  for (let i = 0; i < allFiles.length; i += BATCH_SIZE) {
+    const batch = allFiles.slice(i, i + BATCH_SIZE);
+
+    await Promise.all(batch.map(async (filePath) => {
+      try {
+        const { indexed, chunksCreated, knowledgeItemsExtracted } = await indexFile(filePath, repoId, opts);
+        if (indexed) {
+          result.filesProcessed++;
+          result.chunksCreated += chunksCreated;
+          result.knowledgeItemsExtracted += knowledgeItemsExtracted;
+        } else {
+          result.filesSkipped++;
+        }
+      } catch (err) {
+        result.filesErrored++;
+        result.errors.push(`${filePath}: ${String(err)}`);
+        logger.error('Error indexing file', { filePath, error: String(err) });
+      }
+    }));
+  }
+
+  // Phase 2: Build CALLS edges across the repo using the entity registry.
+  const allReposForFullIndex = opts.allRepos ?? [opts.repoConfig];
+  const fullIndexRoute = getIndexingRoute(repoId, allReposForFullIndex);
+  if (fullIndexRoute.writeEntityNodes) {
+    await buildCallsEdges(repoId, opts);
+  }
+
+  // Phase 2: Run git analysis for CO_MODIFIED and TESTS edges
+  try {
+    await runGitAnalysis(
+      resolve(repoPath),
+      repoId,
+      allFiles,
+      opts.graphStore
+    );
+  } catch (err) {
+    const msg = `Git analysis failed: ${String(err)}`;
+    result.errors.push(msg);
+    logger.warn(msg, { repoId });
+  }
+
+  // Phase 3: Git history enrichment — file stats + commit record embeddings
+  try {
+    const resolvedRepoPath = resolve(repoPath);
+
+    // 3a. Analyze per-file stats and write to FalkorDB File nodes
+    const fileStats = await analyzeFileStats(resolvedRepoPath);
+
+    if (fileStats.size > 0 && fullIndexRoute.writeGraphNode) {
+      let statsWritten = 0;
+      for (const [filePath, stats] of fileStats) {
+        try {
+          await opts.graphStore.upsertNode(
+            'File',
+            { path: filePath, repo_id: repoId },
+            {
+              commit_count: stats.commitCount,
+              stability_score: stats.stabilityScore,
+              change_velocity: stats.changeVelocity,
+              last_commit_hash: stats.lastCommitHash,
+              last_commit_ts: stats.lastCommitTs,
+            }
+          );
+          statsWritten++;
+        } catch {
+          // Non-fatal: file node may not exist if it was filtered during indexing
+        }
+      }
+      logger.info('Git file stats written to graph', { repoId, statsWritten, totalFiles: fileStats.size });
+    }
+
+    // 3b. Extract commit records and embed messages into git_commits collection
+    const commits = await extractCommitRecords(resolvedRepoPath);
+
+    if (commits.length > 0) {
+      // Check if vectorStore supports git commit operations (QdrantVectorStore does)
+      const store = opts.vectorStore as typeof opts.vectorStore & {
+        upsertGitCommits?: (commits: Array<{ id: string; vector: number[]; payload: Record<string, unknown> }>) => Promise<void>;
+        deleteGitCommitsByRepo?: (repoId: string) => Promise<void>;
+      };
+
+      if (typeof store.upsertGitCommits === 'function') {
+        // Delete existing git commits for this repo before re-indexing
+        if (typeof store.deleteGitCommitsByRepo === 'function') {
+          await store.deleteGitCommitsByRepo(repoId);
+        }
+
+        // Embed commit messages in batches
+        const COMMIT_BATCH = 50;
+        let totalUpserted = 0;
+
+        for (let i = 0; i < commits.length; i += COMMIT_BATCH) {
+          const batch = commits.slice(i, i + COMMIT_BATCH);
+          const texts = batch.map(c => c.message);
+          const vectors = await embedBatch(texts);
+          const ZERO_VEC = new Array(384).fill(0) as number[];
+
+          const points = batch.map((commit, idx) => {
+            // Generate a deterministic ID from repo_id + commit hash
+            const idSource = `${repoId}:${commit.hash}`;
+            const id = createHash('sha256').update(idSource).digest('hex').slice(0, 32);
+            const uuid = `${id.slice(0, 8)}-${id.slice(8, 12)}-4${id.slice(13, 16)}-8${id.slice(17, 20)}-${id.slice(20, 32)}`;
+
+            return {
+              id: uuid,
+              vector: vectors[idx] ?? ZERO_VEC,
+              payload: {
+                repo_id: repoId,
+                commit_hash: commit.hash,
+                message: commit.message,
+                author: commit.author,
+                timestamp: commit.timestamp,
+                file_paths: commit.files,
+              },
+            };
+          });
+
+          await store.upsertGitCommits(points);
+          totalUpserted += points.length;
+        }
+
+        logger.info('Git commit messages embedded', { repoId, commitsEmbedded: totalUpserted });
+      }
+    }
+  } catch (err) {
+    const msg = `Git enrichment (Phase 3) failed: ${String(err)}`;
+    result.errors.push(msg);
+    logger.warn(msg, { repoId });
+  }
+
+  // Update stats
+  const now = Date.now();
+  repoStats.set(repoId, {
+    filesIndexed: result.filesProcessed,
+    filesTotal: allFiles.length,
+    lastIndexedAt: now,
+  });
+
+  result.durationMs = now - startTime;
+  logger.info('Full index complete', {
+    repoId,
+    filesProcessed: result.filesProcessed,
+    filesSkipped: result.filesSkipped,
+    filesErrored: result.filesErrored,
+    chunksCreated: result.chunksCreated,
+    knowledgeItemsExtracted: result.knowledgeItemsExtracted,
+    errors: result.errors.length,
+    durationMs: result.durationMs,
+  });
+
+  return result;
+}
+
+/**
+ * Re-index a single file after a change event (incremental update).
+ * Deletes old data, re-indexes with fresh content.
+ */
+export async function incrementalIndex(
+  filePath: string,
+  repoId: string,
+  opts: IndexerOptions
+): Promise<void> {
+  logger.debug('Incremental re-index', { filePath, repoId });
+
+  // Delete old vectors and graph nodes first
+  await opts.vectorStore.deleteFileChunks(filePath, repoId);
+  await opts.graphStore.deleteFile(filePath, repoId);
+  opts.fileCache.invalidate(repoId, filePath);
+
+  // Remove from in-memory tracking so indexFile doesn't skip it
+  indexedFiles.delete(`${repoId}:${filePath}`);
+
+  // Re-index
+  const { indexed, chunksCreated } = await indexFile(filePath, repoId, opts);
+  if (indexed) {
+    logger.debug('Incremental re-index complete', { filePath, repoId, chunksCreated });
+  }
+}
+
+/**
+ * Remove all data for a repo from vector store and graph.
+ */
+export async function removeRepoIndex(repoId: string, opts: IndexerOptions): Promise<void> {
+  logger.info('Removing repo index', { repoId });
+  await opts.vectorStore.deleteRepoChunks(repoId);
+  await opts.graphStore.deleteRepo(repoId);
+  opts.fileCache.invalidateRepo(repoId);
+
+  // Clear in-memory tracking for this repo
+  const prefix = `${repoId}:`;
+  for (const key of indexedFiles.keys()) {
+    if (key.startsWith(prefix)) {
+      indexedFiles.delete(key);
+    }
+  }
+  repoStats.delete(repoId);
+  repoEntityRegistry.delete(repoId);
+}
+
+/**
+ * Index a single file (full pipeline).
+ * Returns true if indexed, false if skipped.
+ *
+ * Phase 2: also populates IMPORTS, EXPORTS, EXTENDS, IMPLEMENTS edges.
+ * Phase 5: added forceReindex flag (bypasses hash check) and debug logging for skips.
+ */
+export async function indexFile(
+  filePath: string,
+  repoId: string,
+  opts: IndexerOptions,
+  forceReindex = false
+): Promise<{ indexed: boolean; chunksCreated: number; knowledgeItemsExtracted: number }> {
+  const { graphStore, vectorStore, fileCache, maxFileSizeKb = 500 } = opts;
+
+  const allRepos = opts.allRepos ?? [opts.repoConfig];
+  const route = getIndexingRoute(repoId, allRepos);
+
+  logger.debug('Indexing route determined', {
+    repoId,
+    filePath,
+    writeGraphNode: route.writeGraphNode,
+    writeEntityNodes: route.writeEntityNodes,
+    parseAst: route.parseAst,
+    writeFileCache: route.writeFileCache,
+  });
+
+  try {
+    // Check file size
+    const fileStat = await stat(filePath);
+    if (fileStat.size > maxFileSizeKb * 1024) {
+      logger.debug('Skipping large file', { filePath, sizeKb: Math.round(fileStat.size / 1024) });
+      return { indexed: false, chunksCreated: 0, knowledgeItemsExtracted: 0 };
+    }
+
+    // Read file content
+    const content = await readFile(filePath, 'utf8');
+    const contentHash = hashContent(content);
+
+    // Check if already indexed with same hash (skip unless forceReindex is set)
+    const existing = indexedFiles.get(`${repoId}:${filePath}`);
+    if (existing && existing.contentHash === contentHash && !forceReindex) {
+      logger.debug('Skipping unchanged file', { filePath, repoId, contentHash });
+      return { indexed: false, chunksCreated: 0, knowledgeItemsExtracted: 0 };
+    }
+
+    if (forceReindex && existing) {
+      logger.debug('Force re-indexing file (bypassing hash check)', { filePath, repoId });
+    }
+
+    // Remove old data for this file
+    if (existing) {
+      await vectorStore.deleteFileChunks(filePath, repoId);
+
+      // Phase 3: Mark observations stale for changed symbols before deleting graph nodes.
+      // Re-parse the old file's entities to find symbols that may have changed.
+      if (route.writeEntityNodes) {
+        try {
+          const oldParseResult = await parseFile(filePath, repoId);
+          if (oldParseResult.success) {
+            for (const entity of oldParseResult.entities) {
+              try {
+                await graphStore.query(
+                  MARK_SYMBOL_OBSERVATIONS_STALE(entity.name, repoId)
+                );
+              } catch {
+                // Non-fatal: observation staleness marking is best-effort
+              }
+            }
+          }
+        } catch {
+          // Non-fatal: if we can't re-parse, skip staleness marking
+        }
+      }
+
+      if (route.writeGraphNode) {
+        await graphStore.deleteFile(filePath, repoId);
+      }
+      if (route.writeFileCache) {
+        fileCache.invalidate(repoId, filePath);
+      }
+    }
+
+    const ext = extname(filePath).toLowerCase();
+    const language = getLanguage(filePath) ?? ext.slice(1) ?? 'unknown';
+    const now = Date.now();
+
+    let chunks;
+
+    if (SKIP_EXTENSIONS.has(ext)) {
+      return { indexed: false, chunksCreated: 0, knowledgeItemsExtracted: 0 };
+    }
+
+    if (CODE_EXTENSIONS.has(ext)) {
+      if (route.parseAst) {
+        // Full AST parse pipeline — owned repos get graph nodes + entity extraction
+        const parseResult = await parseFile(filePath, repoId);
+
+        // Store file node in graph only for owned repos
+        if (route.writeGraphNode) {
+          await upsertFileNode(graphStore, filePath, repoId, contentHash, language, now);
+        }
+
+        // Phase 2: Store entity nodes and all graph edges (owned repos only)
+        if (route.writeEntityNodes && parseResult.success) {
+          await upsertEntitiesWithEdges(graphStore, parseResult, content, repoId, filePath);
+        }
+
+        // Generate chunks from AST entities
+        if (parseResult.success && parseResult.entities.length > 0) {
+          chunks = chunkFromEntities(
+            parseResult.entities,
+            parseResult.imports,
+            content,
+            filePath,
+            repoId,
+            language,
+            now
+          );
+        } else {
+          // Fallback to fixed chunking if AST parse failed or no entities
+          chunks = chunkFixed(content, filePath, repoId, language, now);
+        }
+      } else {
+        // External repo: skip AST parse entirely, use fixed chunking only.
+        // This keeps vectors (semantic search) without polluting the graph.
+        chunks = chunkFixed(content, filePath, repoId, language, now);
+        logger.debug('External repo — skipping AST parse, using fixed chunking', { filePath, repoId });
+      }
+    } else if (NON_CODE_EXTENSIONS.has(ext)) {
+      // Smart markdown chunking for .md/.mdx, fixed chunking for other non-code
+      if (ext === '.md' || ext === '.mdx') {
+        chunks = chunkMarkdown(content, filePath, repoId, now);
+      } else {
+        chunks = chunkFixed(content, filePath, repoId, language, now);
+      }
+
+      // Store a File node only for owned repos
+      if (route.writeGraphNode) {
+        await upsertFileNode(graphStore, filePath, repoId, contentHash, language, now);
+      }
+    } else {
+      return { indexed: false, chunksCreated: 0, knowledgeItemsExtracted: 0 };
+    }
+
+    if (chunks.length === 0) {
+      return { indexed: false, chunksCreated: 0, knowledgeItemsExtracted: 0 };
+    }
+
+    // Embed all chunks in batches (always — vectors written for all repos)
+    const chunkTexts = chunks.map(c => c.content);
+    const vectors = await embedBatch(chunkTexts);
+
+    // Upsert to Qdrant (route.writeVectorChunks is always true per routing logic)
+    const ZERO_VECTOR = new Array(384).fill(0) as number[];
+    const qdrantPoints = chunks.map((chunk, i) => ({
+      id: chunk.id,
+      vector: vectors[i] ?? ZERO_VECTOR,
+      payload: {
+        repo_id: chunk.repoId,
+        file_path: chunk.filePath,
+        entity_name: chunk.entityName,
+        entity_type: chunk.entityType,
+        start_line: chunk.startLine,
+        end_line: chunk.endLine,
+        language: chunk.language,
+        content_hash: chunk.contentHash,
+        content_preview: chunk.contentPreview,
+        indexed_at: chunk.indexedAt,
+      } as const,
+    }));
+
+    await vectorStore.upsertCodeChunks(qdrantPoints);
+
+    // Extract and upsert knowledge items from markdown files
+    let knowledgeCount = 0;
+    if (ext === '.md' || ext === '.mdx') {
+      try {
+        // Resolve stack tags from repo config for knowledge items
+        const repoManifestStack = opts.repoConfig.languages ?? [];
+        const knowledgeItems = extractKnowledge(content, filePath, repoId, repoManifestStack);
+
+        if (knowledgeItems.length > 0) {
+          // Check if vectorStore has upsertKnowledge (QdrantVectorStore does)
+          const store = vectorStore as typeof vectorStore & {
+            upsertKnowledge?: (id: string, vector: number[], payload: Record<string, unknown>) => Promise<void>;
+          };
+
+          if (typeof store.upsertKnowledge === 'function') {
+            for (const item of knowledgeItems) {
+              try {
+                const text = `${item.title} ${item.content}`;
+                const [vector] = await embedBatch([text]);
+                const ZERO_VEC = new Array(384).fill(0) as number[];
+                await store.upsertKnowledge(item.id, vector ?? ZERO_VEC, {
+                  id: item.id,
+                  repo_id: repoId,
+                  category: item.id.split('-')[0] ?? 'pattern',
+                  title: item.title,
+                  content: item.content,
+                  stack_tags: item.stack_tags,
+                  confidence: item.confidence,
+                  source: item.source,
+                  source_phase: item.source_phase,
+                  source_agent: item.source_agent,
+                  sharing: opts.repoConfig.ownership === 'owned' ? 'team' : 'private',
+                  created_at: item.created_at,
+                  updated_at: item.updated_at,
+                  accessed_at: now,
+                  access_count: 0,
+                });
+                knowledgeCount++;
+              } catch (kErr) {
+                logger.warn('Failed to upsert knowledge item from markdown', {
+                  id: item.id,
+                  filePath,
+                  error: String(kErr),
+                });
+              }
+            }
+            if (knowledgeCount > 0) {
+              logger.debug('Knowledge items extracted from markdown', {
+                filePath, repoId, count: knowledgeCount,
+              });
+            }
+          }
+        }
+      } catch (kErr) {
+        logger.warn('Knowledge extraction failed for markdown file', {
+          filePath, error: String(kErr),
+        });
+      }
+    }
+
+    // Cache file content only for owned repos (RAM budget control)
+    if (route.writeFileCache) {
+      fileCache.set(repoId, filePath, content, contentHash);
+    }
+
+    // Update indexed files tracking
+    indexedFiles.set(`${repoId}:${filePath}`, { contentHash, indexedAt: now });
+
+    logger.debug('File indexed', {
+      filePath,
+      repoId,
+      chunks: chunks.length,
+      knowledgeItems: knowledgeCount,
+      language,
+      owned: route.writeGraphNode,
+    });
+
+    return { indexed: true, chunksCreated: chunks.length, knowledgeItemsExtracted: knowledgeCount };
+  } catch (err) {
+    logger.error('Failed to index file', { filePath, error: String(err) });
+    return { indexed: false, chunksCreated: 0, knowledgeItemsExtracted: 0 };
+  }
+}
+
+/**
+ * Get repo index stats.
+ */
+export function getRepoStats(repoId: string) {
+  return repoStats.get(repoId) ?? {
+    filesIndexed: 0,
+    filesTotal: 0,
+    lastIndexedAt: 0,
+  };
+}
+
+/**
+ * Get all indexed files for a repo.
+ */
+export function getIndexedFiles(repoId: string): string[] {
+  const prefix = `${repoId}:`;
+  return Array.from(indexedFiles.keys())
+    .filter(k => k.startsWith(prefix))
+    .map(k => k.slice(prefix.length));
+}
+
+// ============================================================
+// Phase 2: Graph population helpers
+// ============================================================
+
+async function upsertFileNode(
+  graphStore: GraphStore,
+  filePath: string,
+  repoId: string,
+  contentHash: string,
+  language: string,
+  now: number
+): Promise<void> {
+  try {
+    await graphStore.upsertNode(
+      'File',
+      { path: filePath, repo_id: repoId },
+      {
+        content_hash: contentHash,
+        language,
+        last_indexed: now,
+        size_bytes: 0,
+      }
+    );
+  } catch (err) {
+    logger.warn('Failed to upsert file node', { filePath, error: String(err) });
+  }
+}
+
+/**
+ * Upsert all entities for a file and create the full set of edges:
+ *   CONTAINS (File -> entity)
+ *   EXPORTS  (File -> entity, for exported symbols)
+ *   IMPORTS  (File -> File, from import statements)
+ *   EXTENDS  (Class -> Class, when extends clause is present)
+ *   IMPLEMENTS (Class -> Interface, when implements clause is present)
+ *
+ * Also registers entity names in the repo entity registry for later CALLS analysis.
+ */
+async function upsertEntitiesWithEdges(
+  graphStore: GraphStore,
+  parseResult: ParseResult,
+  _content: string,
+  repoId: string,
+  filePath: string
+): Promise<void> {
+  const entityRegistry = repoEntityRegistry.get(repoId) ?? new Map<string, string>();
+  repoEntityRegistry.set(repoId, entityRegistry);
+
+  // 1. Upsert entity nodes + CONTAINS + EXPORTS edges
+  for (const entity of parseResult.entities) {
+    await upsertEntityNode(graphStore, entity);
+
+    // Register in entity registry for CALLS edge discovery
+    entityRegistry.set(entity.name, filePath);
+
+    // Create CONTAINS edge
+    await safeUpsertEdge(
+      graphStore,
+      'File', { path: filePath, repo_id: repoId },
+      'CONTAINS', {},
+      entityLabel(entity.type), { name: entity.name, file_path: filePath, repo_id: repoId }
+    );
+
+    // Create EXPORTS edge for exported symbols
+    if (entity.isExported) {
+      await safeUpsertEdge(
+        graphStore,
+        'File', { path: filePath, repo_id: repoId },
+        'EXPORTS', { is_default: entity.isDefault ?? false },
+        entityLabel(entity.type), { name: entity.name, file_path: filePath, repo_id: repoId }
+      );
+    }
+
+    // Phase 2: EXTENDS and IMPLEMENTS edges (extracted from sourceText heuristics)
+    if (entity.type === 'class' && entity.sourceText) {
+      await createClassRelationshipEdges(graphStore, entity, repoId);
+    }
+  }
+
+  // 2. Create IMPORTS edges from import declarations
+  for (const imp of parseResult.imports) {
+    const resolvedPath = resolveImportPath(filePath, imp.fromPath, repoId);
+    if (resolvedPath) {
+      await safeUpsertEdge(
+        graphStore,
+        'File', { path: filePath, repo_id: repoId },
+        'IMPORTS', { specifiers: imp.specifiers },
+        'File', { path: resolvedPath, repo_id: repoId }
+      );
+    }
+  }
+}
+
+/**
+ * Create EXTENDS and IMPLEMENTS edges for class declarations.
+ * Uses simple regex-based heuristics on the class source text since we
+ * don't have full type resolution. Handles:
+ *   class Foo extends Bar { ... }
+ *   class Foo implements IFoo, IBar { ... }
+ *   class Foo extends Bar implements IFoo { ... }
+ */
+async function createClassRelationshipEdges(
+  graphStore: GraphStore,
+  classEntity: ParsedEntity,
+  repoId: string
+): Promise<void> {
+  const src = classEntity.sourceText;
+
+  // Extract extends clause: class Foo extends BarName
+  const extendsMatch = src.match(/\bextends\s+([A-Za-z_$][A-Za-z0-9_$]*)/);
+  if (extendsMatch) {
+    const parentName = extendsMatch[1];
+    // Create EXTENDS edge — target Class node may or may not exist yet
+    await safeUpsertEdge(
+      graphStore,
+      'Class', { name: classEntity.name, file_path: classEntity.filePath, repo_id: repoId },
+      'EXTENDS', {},
+      'Class', { name: parentName, repo_id: repoId }
+    );
+  }
+
+  // Extract implements clause: implements IFoo, IBar<T>
+  const implementsMatch = src.match(/\bimplements\s+([A-Za-z_$][A-Za-z0-9_$<>,\s]*?)(?:\s*\{|extends|implements|$)/);
+  if (implementsMatch) {
+    // Split on comma, strip generic type params
+    const interfaces = implementsMatch[1]!
+      .split(',')
+      .map(s => s.replace(/<[^>]*>/g, '').trim())
+      .filter(s => /^[A-Za-z_$]/.test(s));
+
+    for (const ifaceName of interfaces) {
+      await safeUpsertEdge(
+        graphStore,
+        'Class', { name: classEntity.name, file_path: classEntity.filePath, repo_id: repoId },
+        'IMPLEMENTS', {},
+        'Interface', { name: ifaceName, repo_id: repoId }
+      );
+    }
+  }
+}
+
+/**
+ * Upsert a single entity node in FalkorDB.
+ */
+async function upsertEntityNode(graphStore: GraphStore, entity: ParsedEntity): Promise<void> {
+  const label = entityLabel(entity.type);
+  if (!label) return;
+
+  try {
+    await graphStore.upsertNode(
+      label,
+      { name: entity.name, file_path: entity.filePath, repo_id: entity.repoId },
+      {
+        start_line: entity.startLine,
+        end_line: entity.endLine,
+        is_exported: entity.isExported,
+        is_async: entity.isAsync ?? false,
+        params: entity.params ?? '',
+        is_const: entity.isConst ?? false,
+      }
+    );
+  } catch (err) {
+    logger.warn('Failed to upsert entity node', { name: entity.name, error: String(err) });
+  }
+}
+
+/**
+ * Build CALLS edges across the entire repo using static identifier matching.
+ * Algorithm: for each function entity, scan its sourceText for identifiers that
+ * match other known function names in the same repo. If found, create CALLS edge.
+ *
+ * This is Phase 2 static analysis — no type resolution required.
+ */
+async function buildCallsEdges(repoId: string, opts: IndexerOptions): Promise<void> {
+  const entityRegistry = repoEntityRegistry.get(repoId);
+  if (!entityRegistry || entityRegistry.size === 0) return;
+
+  logger.debug('Building CALLS edges via static analysis', {
+    repoId,
+    knownEntities: entityRegistry.size,
+  });
+
+  // We need to re-read parse results to get sourceText.
+  // We iterate over all indexed files for this repo.
+  const allIndexedFiles = getIndexedFiles(repoId);
+
+  for (const filePath of allIndexedFiles) {
+    const ext = extname(filePath).toLowerCase();
+    if (!CODE_EXTENSIONS.has(ext)) continue;
+
+    try {
+      const parseResult = await parseFile(filePath, repoId);
+      if (!parseResult.success) continue;
+
+      for (const entity of parseResult.entities) {
+        if (entity.type !== 'function') continue;
+        if (!entity.sourceText) continue;
+
+        // Find all identifiers in the function body that match known entity names
+        // Skip the entity's own name to avoid self-references
+        for (const [calleeName, calleePath] of entityRegistry) {
+          if (calleeName === entity.name) continue;
+          if (!isIdentifierReferenced(entity.sourceText, calleeName)) continue;
+
+          // Create CALLS edge
+          await safeUpsertEdge(
+            opts.graphStore,
+            'Function', { name: entity.name, file_path: filePath, repo_id: repoId },
+            'CALLS', { call_count: 1 },
+            'Function', { name: calleeName, file_path: calleePath, repo_id: repoId }
+          );
+        }
+      }
+    } catch (err) {
+      logger.warn('CALLS edge analysis failed for file', { filePath, error: String(err) });
+    }
+  }
+
+  logger.debug('CALLS edge construction complete', { repoId });
+}
+
+/**
+ * Check if an identifier name appears as a standalone word in source text.
+ * Uses word boundary matching to avoid matching substrings.
+ */
+function isIdentifierReferenced(sourceText: string, identifierName: string): boolean {
+  // Escape any regex special chars in the name
+  const escaped = identifierName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const pattern = new RegExp(`\\b${escaped}\\b`);
+  return pattern.test(sourceText);
+}
+
+/**
+ * Resolve an import path specifier to an absolute file path.
+ * Only resolves relative imports (./foo, ../bar). Skips node_modules imports.
+ */
+function resolveImportPath(
+  fromFile: string,
+  importPath: string,
+  _repoId: string
+): string | null {
+  // Skip non-relative imports (node_modules, absolute)
+  if (!importPath.startsWith('.')) return null;
+  if (isAbsolute(importPath)) return null;
+
+  const fromDir = dirname(fromFile);
+  const resolved = join(fromDir, importPath);
+
+  // Return the first candidate without extension check (graph allows forward references)
+  // The .ts extension is most common in TS projects
+  const withExt = resolved.endsWith('.js') || resolved.endsWith('.ts') ||
+    resolved.endsWith('.tsx') || resolved.endsWith('.jsx');
+
+  if (withExt) return resolved;
+  return `${resolved}.ts`; // Default assumption for TS projects
+}
+
+/**
+ * Map entity type string to FalkorDB graph label.
+ */
+function entityLabel(type: string): string {
+  const labelMap: Record<string, string> = {
+    function: 'Function',
+    class: 'Class',
+    interface: 'Interface',
+    type_alias: 'TypeAlias',
+    variable: 'Variable',
+    module: 'Module',
+  };
+  return labelMap[type] ?? '';
+}
+
+/**
+ * Wrapper around graphStore.upsertEdge that catches and logs errors.
+ */
+async function safeUpsertEdge(
+  graphStore: GraphStore,
+  fromLabel: string,
+  fromProps: Record<string, unknown>,
+  edgeType: string,
+  edgeProps: Record<string, unknown>,
+  toLabel: string,
+  toProps: Record<string, unknown>
+): Promise<void> {
+  try {
+    await graphStore.upsertEdge(fromLabel, fromProps, edgeType, edgeProps, toLabel, toProps);
+  } catch (err) {
+    logger.warn(`Failed to upsert ${edgeType} edge`, {
+      from: JSON.stringify(fromProps),
+      to: JSON.stringify(toProps),
+      error: String(err),
+    });
+  }
+}