@optave/codegraph 3.3.1 → 3.4.0

package/src/domain/graph/builder/stages/{detect-changes.js → detect-changes.ts}

@@ -1,27 +1,65 @@
 /**
  * Stage: detectChanges
  *
- * Three-tier change detection cascade + incremental reverse-dependency handling.
- * Sets ctx.parseChanges, ctx.metadataUpdates, ctx.removed, ctx.isFullBuild, ctx.earlyExit.
+ * Determines which files have changed since the last build using a tiered
+ * strategy: journal → mtime+size → content hash.  Handles full, incremental,
+ * and scoped rebuilds.
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import type BetterSqlite3 from 'better-sqlite3';
 import { closeDb } from '../../../../db/index.js';
 import { debug, info } from '../../../../infrastructure/logger.js';
 import { normalizePath } from '../../../../shared/constants.js';
+import type { EngineOpts, ExtractorOutput } from '../../../../types.js';
 import { parseFilesAuto } from '../../../parser.js';
 import { readJournal, writeJournalHeader } from '../../journal.js';
+import type { PipelineContext } from '../context.js';
 import { fileHash, fileStat, purgeFilesFromGraph, readFileSafe } from '../helpers.js';
 
-// ── Three-tier change detection ─────────────────────────────────────────
+// ── Local types ────────────────────────────────────────────────────────
 
-/**
- * Determine which files have changed since last build.
- * Tier 0 — Journal: O(changed) when watcher was running
- * Tier 1 — mtime+size: O(n) stats, O(changed) reads
- * Tier 2 — Hash comparison: O(changed) reads (fallback from Tier 1)
- */
-function getChangedFiles(db, allFiles, rootDir) {
+interface FileHashRow {
+  file: string;
+  hash: string;
+  mtime: number;
+  size: number;
+}
+
+interface FileStat {
+  mtimeMs: number;
+  size: number;
+}
+
+interface ChangedFile {
+  file: string;
+  relPath?: string;
+  content?: string;
+  hash?: string;
+  stat?: FileStat;
+  metadataOnly?: boolean;
+  _reverseDepOnly?: boolean;
+}
+
+interface ChangeResult {
+  changed: ChangedFile[];
+  removed: string[];
+  isFullBuild: boolean;
+}
+
+interface NeedsHashItem {
+  file: string;
+  relPath: string;
+  stat?: FileStat;
+}
+
+// ── Helpers ────────────────────────────────────────────────────────────
+
+function getChangedFiles(
+  db: BetterSqlite3.Database,
+  allFiles: string[],
+  rootDir: string,
+): ChangeResult {
   let hasTable = false;
   try {
     db.prepare('SELECT 1 FROM file_hashes LIMIT 1').get();
@@ -38,30 +76,28 @@ function getChangedFiles(db, allFiles, rootDir) {
     };
   }
 
-  const existing = new Map(
-    db
-      .prepare('SELECT file, hash, mtime, size FROM file_hashes')
-      .all()
-      .map((r) => [r.file, r]),
+  const existing = new Map<string, FileHashRow>(
+    (db.prepare('SELECT file, hash, mtime, size FROM file_hashes').all() as FileHashRow[]).map(
+      (r) => [r.file, r],
+    ),
   );
 
   const removed = detectRemovedFiles(existing, allFiles, rootDir);
-
-  // Tier 0: Journal
   const journalResult = tryJournalTier(db, existing, rootDir, removed);
   if (journalResult) return journalResult;
-
-  // Tier 1 + 2: mtime/size fast-path → hash comparison
   return mtimeAndHashTiers(existing, allFiles, rootDir, removed);
 }
 
-function detectRemovedFiles(existing, allFiles, rootDir) {
-  const currentFiles = new Set();
+function detectRemovedFiles(
+  existing: Map<string, FileHashRow>,
+  allFiles: string[],
+  rootDir: string,
+): string[] {
+  const currentFiles = new Set<string>();
   for (const file of allFiles) {
     currentFiles.add(normalizePath(path.relative(rootDir, file)));
   }
-
-  const removed = [];
+  const removed: string[] = [];
   for (const existingFile of existing.keys()) {
     if (!currentFiles.has(existingFile)) {
       removed.push(existingFile);
@@ -70,15 +106,22 @@ function detectRemovedFiles(existing, allFiles, rootDir) {
   return removed;
 }
 
-function tryJournalTier(db, existing, rootDir, removed) {
+function tryJournalTier(
+  db: BetterSqlite3.Database,
+  existing: Map<string, FileHashRow>,
+  rootDir: string,
+  removed: string[],
+): ChangeResult | null {
   const journal = readJournal(rootDir);
   if (!journal.valid) return null;
 
-  const dbMtimes = db.prepare('SELECT MAX(mtime) as latest FROM file_hashes').get();
+  const dbMtimes = db.prepare('SELECT MAX(mtime) as latest FROM file_hashes').get() as
+    | { latest: number | null }
+    | undefined;
   const latestDbMtime = dbMtimes?.latest || 0;
-  const hasJournalEntries = journal.changed.length > 0 || journal.removed.length > 0;
+  const hasJournalEntries = journal.changed!.length > 0 || journal.removed!.length > 0;
 
-  if (!hasJournalEntries || journal.timestamp < latestDbMtime) {
+  if (!hasJournalEntries || journal.timestamp! < latestDbMtime) {
     debug(
       `Tier 0: skipped (${hasJournalEntries ? 'timestamp stale' : 'no entries'}), falling to Tier 1`,
     );
@@ -86,16 +129,15 @@ function tryJournalTier(db, existing, rootDir, removed) {
   }
 
   debug(
-    `Tier 0: journal valid, ${journal.changed.length} changed, ${journal.removed.length} removed`,
+    `Tier 0: journal valid, ${journal.changed!.length} changed, ${journal.removed!.length} removed`,
   );
-  const changed = [];
+  const changed: ChangedFile[] = [];
 
-  for (const relPath of journal.changed) {
+  for (const relPath of journal.changed!) {
     const absPath = path.join(rootDir, relPath);
-    const stat = fileStat(absPath);
+    const stat = fileStat(absPath) as FileStat | undefined;
     if (!stat) continue;
-
-    let content;
+    let content: string | undefined;
     try {
       content = readFileSafe(absPath);
     } catch {
@@ -109,38 +151,37 @@ function tryJournalTier(db, existing, rootDir, removed) {
   }
 
   const removedSet = new Set(removed);
-  for (const relPath of journal.removed) {
+  for (const relPath of journal.removed!) {
     if (existing.has(relPath)) removedSet.add(relPath);
   }
 
   return { changed, removed: [...removedSet], isFullBuild: false };
 }
 
-function mtimeAndHashTiers(existing, allFiles, rootDir, removed) {
-  // Tier 1: mtime+size fast-path
-  const needsHash = [];
-  const skipped = [];
+function mtimeAndHashTiers(
+  existing: Map<string, FileHashRow>,
+  allFiles: string[],
+  rootDir: string,
+  removed: string[],
+): ChangeResult {
+  const needsHash: NeedsHashItem[] = [];
+  const skipped: string[] = [];
 
   for (const file of allFiles) {
     const relPath = normalizePath(path.relative(rootDir, file));
     const record = existing.get(relPath);
-
     if (!record) {
       needsHash.push({ file, relPath });
       continue;
     }
-
-    const stat = fileStat(file);
+    const stat = fileStat(file) as FileStat | undefined;
     if (!stat) continue;
-
     const storedMtime = record.mtime || 0;
     const storedSize = record.size || 0;
-
     if (storedSize > 0 && Math.floor(stat.mtimeMs) === storedMtime && stat.size === storedSize) {
       skipped.push(relPath);
       continue;
     }
-
     needsHash.push({ file, relPath, stat });
   }
 
@@ -148,20 +189,17 @@ function mtimeAndHashTiers(existing, allFiles, rootDir, removed) {
     debug(`Tier 1: ${skipped.length} skipped by mtime+size, ${needsHash.length} need hash check`);
   }
 
-  // Tier 2: Hash comparison
-  const changed = [];
-
+  const changed: ChangedFile[] = [];
   for (const item of needsHash) {
-    let content;
+    let content: string | undefined;
     try {
       content = readFileSafe(item.file);
     } catch {
       continue;
     }
     const hash = fileHash(content);
-    const stat = item.stat || fileStat(item.file);
+    const stat = item.stat || (fileStat(item.file) as FileStat | undefined);
     const record = existing.get(item.relPath);
-
     if (!record || record.hash !== hash) {
       changed.push({ file: item.file, content, hash, relPath: item.relPath, stat });
     } else if (stat) {
@@ -186,41 +224,44 @@ function mtimeAndHashTiers(existing, allFiles, rootDir, removed) {
   return { changed, removed, isFullBuild: false };
 }
 
-// ── Pending analysis ────────────────────────────────────────────────────
-
-/**
- * Run pending analysis pass when no file changes but analysis tables are empty.
- */
-async function runPendingAnalysis(ctx) {
+async function runPendingAnalysis(ctx: PipelineContext): Promise<boolean> {
   const { db, opts, engineOpts, allFiles, rootDir } = ctx;
-
   const needsCfg =
-    opts.cfg !== false &&
+    (opts as Record<string, unknown>)['cfg'] !== false &&
     (() => {
       try {
-        return db.prepare('SELECT COUNT(*) as c FROM cfg_blocks').get().c === 0;
+        return (
+          (db.prepare('SELECT COUNT(*) as c FROM cfg_blocks').get() as { c: number } | undefined)
+            ?.c === 0
+        );
       } catch {
         return true;
       }
     })();
   const needsDataflow =
-    opts.dataflow !== false &&
+    (opts as Record<string, unknown>)['dataflow'] !== false &&
     (() => {
       try {
-        return db.prepare('SELECT COUNT(*) as c FROM dataflow').get().c === 0;
+        return (
+          (db.prepare('SELECT COUNT(*) as c FROM dataflow').get() as { c: number } | undefined)
+            ?.c === 0
+        );
       } catch {
         return true;
       }
     })();
-
   if (!needsCfg && !needsDataflow) return false;
 
   info('No file changes. Running pending analysis pass...');
   const analysisOpts = {
     ...engineOpts,
-    dataflow: needsDataflow && opts.dataflow !== false,
+    dataflow: needsDataflow && (opts as Record<string, unknown>)['dataflow'] !== false,
   };
-  const analysisSymbols = await parseFilesAuto(allFiles, rootDir, analysisOpts);
+  const analysisSymbols: Map<string, ExtractorOutput> = await parseFilesAuto(
+    allFiles,
+    rootDir,
+    analysisOpts,
+  );
   if (needsCfg) {
     const { buildCFGData } = await import('../../../../features/cfg.js');
     await buildCFGData(db, analysisSymbols, rootDir, engineOpts);
@@ -232,9 +273,7 @@ async function runPendingAnalysis(ctx) {
   return true;
 }
 
-// ── Metadata self-heal ──────────────────────────────────────────────────
-
-function healMetadata(ctx) {
+function healMetadata(ctx: PipelineContext): void {
   const { db, metadataUpdates } = ctx;
   if (!metadataUpdates || metadataUpdates.length === 0) return;
   try {
@@ -243,7 +282,7 @@ function healMetadata(ctx) {
     );
     const healTx = db.transaction(() => {
       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;
         healHash.run(item.relPath, item.hash, mtime, size);
       }
@@ -255,12 +294,13 @@ function healMetadata(ctx) {
   }
 }
 
-// ── Reverse-dependency cascade ──────────────────────────────────────────
-
-function findReverseDependencies(db, changedRelPaths, rootDir) {
-  const reverseDeps = new Set();
+function findReverseDependencies(
+  db: BetterSqlite3.Database,
+  changedRelPaths: Set<string>,
+  rootDir: string,
+): Set<string> {
+  const reverseDeps = new Set<string>();
   if (changedRelPaths.size === 0) return reverseDeps;
-
   const findReverseDepsStmt = db.prepare(`
     SELECT DISTINCT n_src.file FROM edges e
     JOIN nodes n_src ON e.source_id = n_src.id
@@ -268,7 +308,7 @@ function findReverseDependencies(db, changedRelPaths, rootDir) {
     WHERE n_tgt.file = ? AND n_src.file != n_tgt.file AND n_src.kind != 'directory'
   `);
   for (const relPath of changedRelPaths) {
-    for (const row of findReverseDepsStmt.all(relPath)) {
+    for (const row of findReverseDepsStmt.all(relPath) as Array<{ file: string }>) {
       if (!changedRelPaths.has(row.file) && !reverseDeps.has(row.file)) {
         const absPath = path.join(rootDir, row.file);
         if (fs.existsSync(absPath)) {
@@ -280,13 +320,15 @@ function findReverseDependencies(db, changedRelPaths, rootDir) {
   return reverseDeps;
 }
 
-function purgeAndAddReverseDeps(ctx, changePaths, reverseDeps) {
+function purgeAndAddReverseDeps(
+  ctx: PipelineContext,
+  changePaths: string[],
+  reverseDeps: Set<string>,
+): void {
   const { db, rootDir } = ctx;
-
   if (changePaths.length > 0 || ctx.removed.length > 0) {
     purgeFilesFromGraph(db, [...ctx.removed, ...changePaths], { purgeHashes: false });
   }
-
   if (reverseDeps.size > 0) {
     const deleteOutgoingEdgesForFile = db.prepare(
       'DELETE FROM edges WHERE source_id IN (SELECT id FROM nodes WHERE file = ?)',
@@ -301,9 +343,7 @@ function purgeAndAddReverseDeps(ctx, changePaths, reverseDeps) {
   }
 }
 
-// ── Shared helpers ───────────────────────────────────────────────────────
-
-function detectHasEmbeddings(db) {
+function detectHasEmbeddings(db: BetterSqlite3.Database): boolean {
   try {
     db.prepare('SELECT 1 FROM embeddings LIMIT 1').get();
     return true;
@@ -312,39 +352,27 @@ function detectHasEmbeddings(db) {
   }
 }
 
-// ── Scoped build path ───────────────────────────────────────────────────
-
-function handleScopedBuild(ctx) {
+function handleScopedBuild(ctx: PipelineContext): void {
   const { db, rootDir, opts } = ctx;
-
   ctx.hasEmbeddings = detectHasEmbeddings(db);
-
   const changePaths = ctx.parseChanges.map(
     (item) => item.relPath || normalizePath(path.relative(rootDir, item.file)),
   );
-
-  let reverseDeps = new Set();
-  if (!opts.noReverseDeps) {
-    const changedRelPaths = new Set([...changePaths, ...ctx.removed]);
+  let reverseDeps = new Set<string>();
+  if (!(opts as Record<string, unknown>)['noReverseDeps']) {
+    const changedRelPaths = new Set<string>([...changePaths, ...ctx.removed]);
     reverseDeps = findReverseDependencies(db, changedRelPaths, rootDir);
   }
-
-  // Purge changed + removed files, then add reverse-deps
   purgeAndAddReverseDeps(ctx, changePaths, reverseDeps);
-
   info(
     `Scoped rebuild: ${changePaths.length} changed, ${ctx.removed.length} removed, ${reverseDeps.size} reverse-deps`,
   );
 }
 
-// ── Full/incremental build path ─────────────────────────────────────────
-
-function handleFullBuild(ctx) {
+function handleFullBuild(ctx: PipelineContext): void {
   const { db } = ctx;
-
   const hasEmbeddings = detectHasEmbeddings(db);
   ctx.hasEmbeddings = hasEmbeddings;
-
   const deletions =
     'PRAGMA foreign_keys = OFF; DELETE FROM cfg_edges; DELETE FROM cfg_blocks; DELETE FROM node_metrics; DELETE FROM edges; DELETE FROM function_complexity; DELETE FROM dataflow; DELETE FROM ast_nodes; DELETE FROM nodes; PRAGMA foreign_keys = ON;';
   db.exec(
@@ -354,14 +382,12 @@ function handleFullBuild(ctx) {
   );
 }
 
-function handleIncrementalBuild(ctx) {
+function handleIncrementalBuild(ctx: PipelineContext): void {
   const { db, rootDir, opts } = ctx;
-
   ctx.hasEmbeddings = detectHasEmbeddings(db);
-
-  let reverseDeps = new Set();
-  if (!opts.noReverseDeps) {
-    const changedRelPaths = new Set();
+  let reverseDeps = new Set<string>();
+  if (!(opts as Record<string, unknown>)['noReverseDeps']) {
+    const changedRelPaths = new Set<string>();
     for (const item of ctx.parseChanges) {
       changedRelPaths.add(item.relPath || normalizePath(path.relative(rootDir, item.file)));
     }
@@ -370,45 +396,54 @@ function handleIncrementalBuild(ctx) {
     }
     reverseDeps = findReverseDependencies(db, changedRelPaths, rootDir);
   }
-
   info(
     `Incremental: ${ctx.parseChanges.length} changed, ${ctx.removed.length} removed${reverseDeps.size > 0 ? `, ${reverseDeps.size} reverse-deps` : ''}`,
   );
   if (ctx.parseChanges.length > 0)
     debug(`Changed files: ${ctx.parseChanges.map((c) => c.relPath).join(', ')}`);
   if (ctx.removed.length > 0) debug(`Removed files: ${ctx.removed.join(', ')}`);
-
   const changePaths = ctx.parseChanges.map(
     (item) => item.relPath || normalizePath(path.relative(rootDir, item.file)),
   );
   purgeAndAddReverseDeps(ctx, changePaths, reverseDeps);
 }
 
-// ── Main entry point ────────────────────────────────────────────────────
-
-/**
- * @param {import('../context.js').PipelineContext} ctx
- */
-export async function detectChanges(ctx) {
+export async function detectChanges(ctx: PipelineContext): Promise<void> {
   const { db, allFiles, rootDir, incremental, forceFullRebuild, opts } = ctx;
-
-  // Scoped builds already set parseChanges in collectFiles
-  if (opts.scope) {
+  if ((opts as Record<string, unknown>)['scope']) {
     handleScopedBuild(ctx);
     return;
   }
-
   const increResult =
     incremental && !forceFullRebuild
       ? getChangedFiles(db, allFiles, rootDir)
-      : { changed: allFiles.map((f) => ({ file: f })), removed: [], isFullBuild: true };
-
+      : {
+          changed: allFiles.map((f): ChangedFile => ({ file: f })),
+          removed: [] as string[],
+          isFullBuild: true,
+        };
   ctx.removed = increResult.removed;
   ctx.isFullBuild = increResult.isFullBuild;
-  ctx.parseChanges = increResult.changed.filter((c) => !c.metadataOnly);
-  ctx.metadataUpdates = increResult.changed.filter((c) => c.metadataOnly);
-
-  // Early exit: no changes detected
+  ctx.parseChanges = increResult.changed
+    .filter((c) => !c.metadataOnly)
+    .map((c) => ({
+      file: c.file,
+      relPath: c.relPath,
+      content: c.content,
+      hash: c.hash,
+      stat: c.stat ? { mtime: Math.floor(c.stat.mtimeMs), size: c.stat.size } : undefined,
+      _reverseDepOnly: c._reverseDepOnly,
+    }));
+  ctx.metadataUpdates = increResult.changed
+    .filter(
+      (c): c is ChangedFile & { relPath: string; hash: string; stat: FileStat } =>
+        !!c.metadataOnly && !!c.relPath && !!c.hash && !!c.stat,
+    )
+    .map((c) => ({
+      relPath: c.relPath,
+      hash: c.hash,
+      stat: { mtime: Math.floor(c.stat.mtimeMs), size: c.stat.size },
+    }));
   if (!ctx.isFullBuild && ctx.parseChanges.length === 0 && ctx.removed.length === 0) {
     const ranAnalysis = await runPendingAnalysis(ctx);
     if (ranAnalysis) {
@@ -417,7 +452,6 @@ export async function detectChanges(ctx) {
       ctx.earlyExit = true;
       return;
     }
-
     healMetadata(ctx);
     info('No changes detected. Graph is up to date.');
     closeDb(db);
@@ -425,7 +459,6 @@ export async function detectChanges(ctx) {
     ctx.earlyExit = true;
     return;
   }
-
   if (ctx.isFullBuild) {
     handleFullBuild(ctx);
   } else {