@optave/codegraph 3.5.0 → 3.7.0

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

@@ -17,12 +17,8 @@ import { CODEGRAPH_VERSION } from '../../../../shared/version.js';
 import { writeJournalHeader } from '../../journal.js';
 import type { PipelineContext } from '../context.js';
 
-export async function finalize(ctx: PipelineContext): Promise<void> {
-  const { db, allSymbols, rootDir, isFullBuild, hasEmbeddings, config, opts, schemaVersion } = ctx;
-
-  const t0 = performance.now();
-
-  // Release cached WASM trees
+/** Release cached WASM parse trees to free memory. */
+function releaseWasmTrees(allSymbols: PipelineContext['allSymbols']): void {
   for (const [, symbols] of allSymbols) {
     const tree = symbols._tree as { delete?: () => void } | undefined;
     if (tree && typeof tree.delete === 'function') {
@@ -35,133 +31,141 @@ export async function finalize(ctx: PipelineContext): Promise<void> {
     symbols._tree = undefined;
     symbols._langId = undefined;
   }
+}
 
-  // Capture a single wall-clock timestamp for the current build — used for
-  // both the stale-embeddings comparison and the persisted built_at metadata.
-  const buildNow = new Date();
+/**
+ * Detect significant drift between current and previous node/edge counts.
+ * Skipped for small incremental changes where count fluctuation is expected.
+ */
+function detectIncrementalDrift(
+  ctx: PipelineContext,
+  nodeCount: number,
+  actualEdgeCount: number,
+): void {
+  const { db, allSymbols, config } = ctx;
+  const useNativeDb = ctx.engineName === 'native' && !!ctx.nativeDb;
+  if (ctx.isFullBuild || allSymbols.size <= 3) return;
 
-  const nodeCount = (db.prepare('SELECT COUNT(*) as c FROM nodes').get() as { c: number }).c;
-  const actualEdgeCount = (db.prepare('SELECT COUNT(*) as c FROM edges').get() as { c: number }).c;
-  info(`Graph built: ${nodeCount} nodes, ${actualEdgeCount} edges`);
-  info(`Stored in ${ctx.dbPath}`);
+  const prevNodes = useNativeDb
+    ? ctx.nativeDb!.getBuildMeta('node_count')
+    : getBuildMeta(db, 'node_count');
+  const prevEdges = useNativeDb
+    ? ctx.nativeDb!.getBuildMeta('edge_count')
+    : getBuildMeta(db, 'edge_count');
+  if (!prevNodes || !prevEdges) return;
 
-  // Incremental drift detection — skip for small incremental changes where
-  // count fluctuation is expected (reverse-dep edge churn).
-  if (!isFullBuild && allSymbols.size > 3) {
-    const prevNodes = ctx.nativeDb
-      ? ctx.nativeDb.getBuildMeta('node_count')
-      : getBuildMeta(db, 'node_count');
-    const prevEdges = ctx.nativeDb
-      ? ctx.nativeDb.getBuildMeta('edge_count')
-      : getBuildMeta(db, 'edge_count');
-    if (prevNodes && prevEdges) {
-      const prevN = Number(prevNodes);
-      const prevE = Number(prevEdges);
-      if (prevN > 0) {
-        const nodeDrift = Math.abs(nodeCount - prevN) / prevN;
-        const edgeDrift = prevE > 0 ? Math.abs(actualEdgeCount - prevE) / prevE : 0;
-        const driftThreshold =
-          (config as { build?: { driftThreshold?: number } }).build?.driftThreshold ?? 0.2;
-        if (nodeDrift > driftThreshold || edgeDrift > driftThreshold) {
-          warn(
-            `Incremental build diverged significantly from previous counts (nodes: ${prevN}\u2192${nodeCount} [${(nodeDrift * 100).toFixed(1)}%], edges: ${prevE}\u2192${actualEdgeCount} [${(edgeDrift * 100).toFixed(1)}%], threshold: ${(driftThreshold * 100).toFixed(0)}%). Consider rebuilding with --no-incremental.`,
-          );
-        }
-      }
-    }
+  const prevN = Number(prevNodes);
+  const prevE = Number(prevEdges);
+  if (prevN <= 0) return;
+
+  const nodeDrift = Math.abs(nodeCount - prevN) / prevN;
+  const edgeDrift = prevE > 0 ? Math.abs(actualEdgeCount - prevE) / prevE : 0;
+  const driftThreshold =
+    (config as { build?: { driftThreshold?: number } }).build?.driftThreshold ?? 0.2;
+  if (nodeDrift > driftThreshold || edgeDrift > driftThreshold) {
+    warn(
+      `Incremental build diverged significantly from previous counts (nodes: ${prevN}\u2192${nodeCount} [${(nodeDrift * 100).toFixed(1)}%], edges: ${prevE}\u2192${actualEdgeCount} [${(edgeDrift * 100).toFixed(1)}%], threshold: ${(driftThreshold * 100).toFixed(0)}%). Consider rebuilding with --no-incremental.`,
+    );
   }
+}
 
-  // For small incremental builds, skip persisting build metadata — the
-  // engine/version/schema haven't changed (would have triggered a full rebuild),
-  // built_at is only used by stale-embeddings check (skipped for incremental),
-  // and counts are only used by drift detection (skipped for ≤3 files).
-  // This avoids a transaction commit + WAL fsync (~15-30ms).
-  // Threshold aligned with drift detection gate (allSymbols.size > 3) so stored
-  // counts stay fresh whenever drift detection reads them.
-  if (isFullBuild || allSymbols.size > 3) {
-    try {
-      if (ctx.nativeDb) {
-        ctx.nativeDb.setBuildMeta(
-          Object.entries({
-            engine: ctx.engineName,
-            engine_version: ctx.engineVersion || '',
-            codegraph_version: CODEGRAPH_VERSION,
-            schema_version: String(schemaVersion),
-            built_at: buildNow.toISOString(),
-            node_count: String(nodeCount),
-            edge_count: String(actualEdgeCount),
-          }).map(([key, value]) => ({ key, value: String(value) })),
-        );
-      } else {
-        setBuildMeta(db, {
+/**
+ * Persist build metadata (engine, version, counts, timestamp).
+ * Skipped for small incremental builds to avoid WAL fsync cost.
+ */
+function persistBuildMetadata(
+  ctx: PipelineContext,
+  nodeCount: number,
+  actualEdgeCount: number,
+  buildNow: Date,
+): void {
+  const useNativeDb = ctx.engineName === 'native' && !!ctx.nativeDb;
+  if (!ctx.isFullBuild && ctx.allSymbols.size <= 3) return;
+  try {
+    if (useNativeDb) {
+      ctx.nativeDb!.setBuildMeta(
+        Object.entries({
           engine: ctx.engineName,
           engine_version: ctx.engineVersion || '',
           codegraph_version: CODEGRAPH_VERSION,
-          schema_version: String(schemaVersion),
+          schema_version: String(ctx.schemaVersion),
           built_at: buildNow.toISOString(),
-          node_count: nodeCount,
-          edge_count: actualEdgeCount,
-        });
-      }
-    } catch (err) {
-      warn(`Failed to write build metadata: ${(err as Error).message}`);
+          node_count: String(nodeCount),
+          edge_count: String(actualEdgeCount),
+        }).map(([key, value]) => ({ key, value: String(value) })),
+      );
+    } else {
+      setBuildMeta(ctx.db, {
+        engine: ctx.engineName,
+        engine_version: ctx.engineVersion || '',
+        codegraph_version: CODEGRAPH_VERSION,
+        schema_version: String(ctx.schemaVersion),
+        built_at: buildNow.toISOString(),
+        node_count: nodeCount,
+        edge_count: actualEdgeCount,
+      });
     }
+  } catch (err) {
+    warn(`Failed to write build metadata: ${(err as Error).message}`);
   }
+}
 
-  // Skip expensive advisory queries for incremental builds — these are
-  // informational warnings that don't affect correctness and cost ~40-60ms.
-  if (!isFullBuild) {
-    debug(
-      'Finalize: skipping advisory queries (orphaned/stale embeddings, unused exports) for incremental build',
-    );
-  } else {
-    // Orphaned embeddings warning
-    if (hasEmbeddings) {
-      try {
-        const orphaned = (
-          db
-            .prepare(
-              'SELECT COUNT(*) as c FROM embeddings WHERE node_id NOT IN (SELECT id FROM nodes)',
-            )
-            .get() as { c: number }
-        ).c;
-        if (orphaned > 0) {
-          warn(
-            `${orphaned} embeddings are orphaned (nodes changed). Run "codegraph embed" to refresh.`,
-          );
-        }
-      } catch {
-        /* ignore - embeddings table may have been dropped */
+/**
+ * Run advisory checks on full builds: orphaned embeddings, stale embeddings,
+ * and unused exports. Informational only — does not affect correctness.
+ */
+function runAdvisoryChecks(
+  db: PipelineContext['db'],
+  hasEmbeddings: boolean,
+  buildNow: Date,
+): void {
+  // Orphaned embeddings warning
+  if (hasEmbeddings) {
+    try {
+      const orphaned = (
+        db
+          .prepare(
+            'SELECT COUNT(*) as c FROM embeddings WHERE node_id NOT IN (SELECT id FROM nodes)',
+          )
+          .get() as { c: number }
+      ).c;
+      if (orphaned > 0) {
+        warn(
+          `${orphaned} embeddings are orphaned (nodes changed). Run "codegraph embed" to refresh.`,
+        );
       }
+    } catch {
+      /* ignore - embeddings table may have been dropped */
     }
+  }
 
-    // Stale embeddings warning (built before current graph rebuild)
-    if (hasEmbeddings) {
-      try {
-        const embedBuiltAt = (
-          db.prepare("SELECT value FROM embedding_meta WHERE key = 'built_at'").get() as
-            | { value: string }
-            | undefined
-        )?.value;
-        if (embedBuiltAt) {
-          const embedTime = new Date(embedBuiltAt).getTime();
-          if (!Number.isNaN(embedTime) && embedTime < buildNow.getTime()) {
-            warn(
-              'Embeddings were built before the last graph rebuild. Run "codegraph embed" to update.',
-            );
-          }
+  // Stale embeddings warning (built before current graph rebuild)
+  if (hasEmbeddings) {
+    try {
+      const embedBuiltAt = (
+        db.prepare("SELECT value FROM embedding_meta WHERE key = 'built_at'").get() as
+          | { value: string }
+          | undefined
+      )?.value;
+      if (embedBuiltAt) {
+        const embedTime = new Date(embedBuiltAt).getTime();
+        if (!Number.isNaN(embedTime) && embedTime < buildNow.getTime()) {
+          warn(
+            'Embeddings were built before the last graph rebuild. Run "codegraph embed" to update.',
+          );
         }
-      } catch {
-        /* ignore - embedding_meta table may not exist */
       }
+    } catch {
+      /* ignore - embedding_meta table may not exist */
     }
+  }
 
-    // Unused exports warning
-    try {
-      const unusedCount = (
-        db
-          .prepare(
-            `SELECT COUNT(*) as c FROM nodes
+  // Unused exports warning
+  try {
+    const unusedCount = (
+      db
+        .prepare(
+          `SELECT COUNT(*) as c FROM nodes
          WHERE exported = 1 AND kind != 'file'
            AND id NOT IN (
              SELECT DISTINCT e.target_id FROM edges e
@@ -169,17 +173,47 @@ export async function finalize(ctx: PipelineContext): Promise<void> {
              JOIN nodes target ON e.target_id = target.id
              WHERE e.kind = 'calls' AND caller.file != target.file
            )`,
-          )
-          .get() as { c: number }
-      ).c;
-      if (unusedCount > 0) {
-        warn(
-          `${unusedCount} exported symbol${unusedCount > 1 ? 's have' : ' has'} zero cross-file consumers. Run "codegraph exports <file> --unused" to inspect.`,
-        );
-      }
-    } catch {
-      /* exported column may not exist on older DBs */
+        )
+        .get() as { c: number }
+    ).c;
+    if (unusedCount > 0) {
+      warn(
+        `${unusedCount} exported symbol${unusedCount > 1 ? 's have' : ' has'} zero cross-file consumers. Run "codegraph exports <file> --unused" to inspect.`,
+      );
     }
+  } catch {
+    /* exported column may not exist on older DBs */
+  }
+}
+
+export async function finalize(ctx: PipelineContext): Promise<void> {
+  const { allSymbols, rootDir, isFullBuild, hasEmbeddings, opts } = ctx;
+
+  const t0 = performance.now();
+
+  releaseWasmTrees(allSymbols);
+
+  // Capture a single wall-clock timestamp for the current build — used for
+  // both the stale-embeddings comparison and the persisted built_at metadata.
+  const buildNow = new Date();
+
+  const nodeCount = (ctx.db.prepare('SELECT COUNT(*) as c FROM nodes').get() as { c: number }).c;
+  const actualEdgeCount = (ctx.db.prepare('SELECT COUNT(*) as c FROM edges').get() as { c: number })
+    .c;
+  info(`Graph built: ${nodeCount} nodes, ${actualEdgeCount} edges`);
+  info(`Stored in ${ctx.dbPath}`);
+
+  detectIncrementalDrift(ctx, nodeCount, actualEdgeCount);
+  persistBuildMetadata(ctx, nodeCount, actualEdgeCount, buildNow);
+
+  // Skip expensive advisory queries for incremental builds — these are
+  // informational warnings that don't affect correctness and cost ~40-60ms.
+  if (!isFullBuild) {
+    debug(
+      'Finalize: skipping advisory queries (orphaned/stale embeddings, unused exports) for incremental build',
+    );
+  } else {
+    runAdvisoryChecks(ctx.db, hasEmbeddings, buildNow);
   }
 
   // Intentionally measured before closeDb / writeJournalHeader / auto-registration:
@@ -192,7 +226,7 @@ export async function finalize(ctx: PipelineContext): Promise<void> {
   // For small incremental builds, defer the expensive WAL checkpoint to the
   // next event loop tick. Skip for temp directories (tests) — they rmSync
   // immediately after build.
-  const pair = { db, nativeDb: ctx.nativeDb };
+  const pair = { db: ctx.db, nativeDb: ctx.nativeDb };
   const isTempDir = path.resolve(rootDir).startsWith(path.resolve(tmpdir()));
   if (!isFullBuild && allSymbols.size <= 5 && !isTempDir) {
     closeDbPairDeferred(pair);

package/src/domain/graph/builder/stages/insert-nodes.ts

@@ -39,6 +39,12 @@ interface PrecomputedFileData {
 // ── Native fast-path ─────────────────────────────────────────────────
 
 function tryNativeInsert(ctx: PipelineContext): boolean {
+  // Disabled: bulkInsertNodes corrupts the DB when both the JS (better-sqlite3)
+  // and Rust (rusqlite) connections are open to the same WAL-mode file.
+  // The native path was never operational before — it always crashed on null
+  // visibility serialisation. See #696 for the dual-connection fix.
+  if (ctx.db) return false;
+
   // Use NativeDatabase persistent connection (Phase 6.15+).
   // Standalone napi functions were removed in 6.17 — falls through to JS if nativeDb unavailable.
   if (!ctx.nativeDb?.bulkInsertNodes) return false;
@@ -52,14 +58,14 @@ function tryNativeInsert(ctx: PipelineContext): boolean {
       name: string;
       kind: string;
       line: number;
-      endLine?: number | null;
-      visibility?: string | null;
+      endLine?: number;
+      visibility?: string;
       children: Array<{
         name: string;
         kind: string;
         line: number;
-        endLine?: number | null;
-        visibility?: string | null;
+        endLine?: number;
+        visibility?: string;
       }>;
     }>;
     exports: Array<{ name: string; kind: string; line: number }>;
@@ -72,14 +78,14 @@ function tryNativeInsert(ctx: PipelineContext): boolean {
         name: def.name,
         kind: def.kind,
         line: def.line,
-        endLine: def.endLine ?? null,
-        visibility: def.visibility ?? null,
+        endLine: def.endLine ?? undefined,
+        visibility: def.visibility ?? undefined,
         children: (def.children ?? []).map((c) => ({
           name: c.name,
           kind: c.kind,
           line: c.line,
-          endLine: c.endLine ?? null,
-          visibility: c.visibility ?? null,
+          endLine: c.endLine ?? undefined,
+          visibility: c.visibility ?? undefined,
         })),
       })),
       exports: symbols.exports.map((exp) => ({
@@ -138,7 +144,7 @@ function tryNativeInsert(ctx: PipelineContext): boolean {
     fileHashes.push({ file: item.relPath, hash: item.hash, mtime, size });
   }
 
-  return ctx.nativeDb.bulkInsertNodes(batches, fileHashes, removed);
+  return ctx.nativeDb!.bulkInsertNodes(batches, fileHashes, removed);
 }
 
 // ── JS fallback: Phase 1 ────────────────────────────────────────────
@@ -330,7 +336,7 @@ function updateFileHashes(
 // ── Main entry point ────────────────────────────────────────────────
 
 export async function insertNodes(ctx: PipelineContext): Promise<void> {
-  const { db, allSymbols, filesToParse, metadataUpdates, rootDir, removed } = ctx;
+  const { allSymbols, filesToParse, metadataUpdates, rootDir, removed } = ctx;
 
   // Populate fileSymbols before any DB writes (used by later stages)
   for (const [relPath, symbols] of allSymbols) {
@@ -340,11 +346,16 @@ export async function insertNodes(ctx: PipelineContext): Promise<void> {
   const t0 = performance.now();
 
   // Try native Rust path first — single transaction, no JS↔C overhead
-  if (ctx.engineName === 'native' && tryNativeInsert(ctx)) {
-    ctx.timing.insertMs = performance.now() - t0;
-
-    // Removed-file hash cleanup is handled inside the native call
-    return;
+  if (ctx.engineName === 'native') {
+    try {
+      if (tryNativeInsert(ctx)) {
+        ctx.timing.insertMs = performance.now() - t0;
+        // Removed-file hash cleanup is handled inside the native call
+        return;
+      }
+    } catch {
+      // Native insert failed — fall through to JS implementation
+    }
   }
 
   // JS fallback
@@ -355,17 +366,17 @@ export async function insertNodes(ctx: PipelineContext): Promise<void> {
 
   let upsertHash: SqliteStatement | null;
   try {
-    upsertHash = db.prepare(
+    upsertHash = ctx.db.prepare(
       'INSERT OR REPLACE INTO file_hashes (file, hash, mtime, size) VALUES (?, ?, ?, ?)',
     );
   } catch {
     upsertHash = null;
   }
 
-  const insertAll = db.transaction(() => {
-    insertDefinitionsAndExports(db, allSymbols);
-    insertChildrenAndEdges(db, allSymbols);
-    updateFileHashes(db, allSymbols, precomputedData, metadataUpdates, rootDir, upsertHash);
+  const insertAll = ctx.db.transaction(() => {
+    insertDefinitionsAndExports(ctx.db, allSymbols);
+    insertChildrenAndEdges(ctx.db, allSymbols);
+    updateFileHashes(ctx.db, allSymbols, precomputedData, metadataUpdates, rootDir, upsertHash);
   });
 
   insertAll();
@@ -373,7 +384,7 @@ export async function insertNodes(ctx: PipelineContext): Promise<void> {
 
   // Clean up removed file hashes
   if (upsertHash && removed.length > 0) {
-    const deleteHash = db.prepare('DELETE FROM file_hashes WHERE file = ?');
+    const deleteHash = ctx.db.prepare('DELETE FROM file_hashes WHERE file = ?');
     for (const relPath of removed) {
       deleteHash.run(relPath);
     }

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

@@ -1,5 +1,6 @@
 import path from 'node:path';
 import { performance } from 'node:perf_hooks';
+import { debug } from '../../../../infrastructure/logger.js';
 import type { Import } from '../../../../types.js';
 import { parseFilesAuto } from '../../../parser.js';
 import { resolveImportPath, resolveImportsBatch } from '../../resolve.js';
@@ -132,8 +133,8 @@ export async function resolveImports(ctx: PipelineContext): Promise<void> {
             );
           }
         }
-      } catch {
-        /* skip if unreadable */
+      } catch (e: unknown) {
+        debug(`Barrel re-parse failed (non-fatal): ${(e as Error).message}`);
       }
     }
   }

package/src/domain/graph/resolve.ts

@@ -117,6 +117,35 @@ function matchSubpathPattern(pattern: string, subpath: string): string | null {
  * Resolve a bare specifier through the package.json exports field.
  * Returns an absolute path or null.
  */
+/** Try to resolve a condition target to a file path in packageDir. */
+function tryResolveTarget(target: string | null, packageDir: string): string | null {
+  if (!target) return null;
+  const resolved = path.resolve(packageDir, target);
+  return fs.existsSync(resolved) ? resolved : null;
+}
+
+/** Resolve subpath against a subpath map (object with "." keys). */
+function resolveSubpathMap(
+  exports: Record<string, unknown>,
+  subpath: string,
+  packageDir: string,
+): string | null {
+  // Exact match first
+  if (subpath in exports) {
+    return tryResolveTarget(resolveCondition(exports[subpath]), packageDir);
+  }
+  // Pattern matching (keys with *)
+  for (const [pattern, value] of Object.entries(exports)) {
+    if (!pattern.includes('*')) continue;
+    const matched = matchSubpathPattern(pattern, subpath);
+    if (matched == null) continue;
+    const rawTarget = resolveCondition(value);
+    if (!rawTarget) continue;
+    return tryResolveTarget(rawTarget.replace(/\*/g, matched), packageDir);
+  }
+  return null;
+}
+
 export function resolveViaExports(specifier: string, rootDir: string): string | null {
   const parsed = parseBareSpecifier(specifier);
   if (!parsed) return null;
@@ -131,66 +160,25 @@ export function resolveViaExports(specifier: string, rootDir: string): string |
 
   // Simple string exports: "exports": "./index.js"
   if (typeof exports === 'string') {
-    if (subpath === '.') {
-      const resolved = path.resolve(packageDir, exports);
-      return fs.existsSync(resolved) ? resolved : null;
-    }
-    return null;
+    return subpath === '.' ? tryResolveTarget(exports, packageDir) : null;
   }
 
   // Array form at top level
   if (Array.isArray(exports)) {
-    if (subpath === '.') {
-      const target = resolveCondition(exports);
-      if (target) {
-        const resolved = path.resolve(packageDir, target);
-        return fs.existsSync(resolved) ? resolved : null;
-      }
-    }
-    return null;
+    return subpath === '.' ? tryResolveTarget(resolveCondition(exports), packageDir) : null;
   }
 
   if (typeof exports !== 'object') return null;
 
-  // Determine if exports is a conditions object (no keys start with ".")
-  // or a subpath map (keys start with ".")
+  // Determine if exports is a conditions object or a subpath map
   const keys = Object.keys(exports);
   const isSubpathMap = keys.length > 0 && keys.some((k) => k.startsWith('.'));
 
   if (!isSubpathMap) {
-    // Conditions object at top level → applies to "." subpath only
-    if (subpath === '.') {
-      const target = resolveCondition(exports);
-      if (target) {
-        const resolved = path.resolve(packageDir, target);
-        return fs.existsSync(resolved) ? resolved : null;
-      }
-    }
-    return null;
+    return subpath === '.' ? tryResolveTarget(resolveCondition(exports), packageDir) : null;
   }
 
-  // Subpath map: try exact match first, then pattern match
-  if (subpath in exports) {
-    const target = resolveCondition(exports[subpath]);
-    if (target) {
-      const resolved = path.resolve(packageDir, target);
-      return fs.existsSync(resolved) ? resolved : null;
-    }
-  }
-
-  // Pattern matching (keys with *)
-  for (const [pattern, value] of Object.entries(exports)) {
-    if (!pattern.includes('*')) continue;
-    const matched = matchSubpathPattern(pattern, subpath);
-    if (matched == null) continue;
-    const rawTarget = resolveCondition(value);
-    if (!rawTarget) continue;
-    const target = rawTarget.replace(/\*/g, matched);
-    const resolved = path.resolve(packageDir, target);
-    if (fs.existsSync(resolved)) return resolved;
-  }
-
-  return null;
+  return resolveSubpathMap(exports as Record<string, unknown>, subpath, packageDir);
 }
 
 /** Clear the exports cache (for testing). */

package/src/domain/graph/watcher.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { closeDb, getNodeId as getNodeIdQuery, initSchema, openDb } from '../../db/index.js';
-import { info } from '../../infrastructure/logger.js';
+import { debug, info } from '../../infrastructure/logger.js';
 import { EXTENSIONS, IGNORE_DIRS, normalizePath } from '../../shared/constants.js';
 import { DbError } from '../../shared/errors.js';
 import { createParseTreeCache, getActiveEngine } from '../parser.js';
@@ -32,12 +32,10 @@ export async function watchProject(rootDir: string, opts: { engine?: string } =
     ast: false,
   };
   const { name: engineName, version: engineVersion } = getActiveEngine(engineOpts);
-  console.log(
-    `Watch mode using ${engineName} engine${engineVersion ? ` (v${engineVersion})` : ''}`,
-  );
+  info(`Watch mode using ${engineName} engine${engineVersion ? ` (v${engineVersion})` : ''}`);
 
   const cache = createParseTreeCache();
-  console.log(
+  info(
     cache
       ? 'Incremental parsing enabled (native tree cache)'
       : 'Incremental parsing unavailable (full re-parse)',
@@ -124,8 +122,8 @@ export async function watchProject(rootDir: string, opts: { engine?: string } =
       }));
       try {
         appendJournalEntries(rootDir, entries);
-      } catch {
-        /* journal write failure is non-fatal */
+      } catch (e: unknown) {
+        debug(`Journal write failed (non-fatal): ${(e as Error).message}`);
       }
 
       const changeEvents = updates.map((r) =>
@@ -137,8 +135,8 @@ export async function watchProject(rootDir: string, opts: { engine?: string } =
       );
       try {
         appendChangeEvents(rootDir, changeEvents);
-      } catch {
-        /* change event write failure is non-fatal */
+      } catch (e: unknown) {
+        debug(`Change event write failed (non-fatal): ${(e as Error).message}`);
       }
     }
 
@@ -153,8 +151,8 @@ export async function watchProject(rootDir: string, opts: { engine?: string } =
     }
   }
 
-  console.log(`Watching ${rootDir} for changes...`);
-  console.log('Press Ctrl+C to stop.\n');
+  info(`Watching ${rootDir} for changes...`);
+  info('Press Ctrl+C to stop.');
 
   const watcher = fs.watch(rootDir, { recursive: true }, (_eventType, filename) => {
     if (!filename) return;
@@ -169,7 +167,7 @@ export async function watchProject(rootDir: string, opts: { engine?: string } =
   });
 
   process.on('SIGINT', () => {
-    console.log('\nStopping watcher...');
+    info('Stopping watcher...');
     watcher.close();
     // Flush any pending file paths to journal before exit
     if (pending.size > 0) {
@@ -178,8 +176,8 @@ export async function watchProject(rootDir: string, opts: { engine?: string } =
       }));
       try {
         appendJournalEntries(rootDir, entries);
-      } catch {
-        /* best-effort */
+      } catch (e: unknown) {
+        debug(`Journal flush on exit failed (non-fatal): ${(e as Error).message}`);
       }
     }
     if (cache) cache.clear();