@codragraph/cli 2.1.1 → 2.1.5

package/dist/core/group/bridge-db.js

@@ -74,7 +74,7 @@ export function findContractNode(index, repo, role, symbolUid, filePath, symbolN
 export async function openBridgeDb(dbPath) {
     const parentDir = path.dirname(dbPath);
     await fsp.mkdir(parentDir, { recursive: true });
-    const db = new cgdb.Database(dbPath, 0, false, false); // writable
+    const db = new cgdb.Database(dbPath, 0, false, false, BRIDGE_MAX_DB_SIZE_BYTES); // writable
     const conn = new cgdb.Connection(db);
     return { _db: db, _conn: conn, groupDir: parentDir };
 }
@@ -238,6 +238,25 @@ export async function retryRename(src, dst, attempts = 3) {
         }
     }
 }
+async function removeBridgeArtifacts(basePath) {
+    for (const candidate of [basePath, `${basePath}.wal`, `${basePath}.lock`]) {
+        try {
+            await fsp.rm(candidate, { recursive: true, force: true });
+        }
+        catch {
+            /* ignore */
+        }
+    }
+}
+async function renameBridgeArtifactIfExists(src, dst) {
+    try {
+        await fsp.access(src);
+    }
+    catch {
+        return;
+    }
+    await retryRename(src, dst);
+}
 /* ------------------------------------------------------------------ */
 /*  writeBridgeMeta / readBridgeMeta                                  */
 /* ------------------------------------------------------------------ */
@@ -261,6 +280,10 @@ export async function readBridgeMeta(groupDir) {
     }
 }
 const MAX_SAMPLE_ERRORS = 10;
+// LadybugDB defaults maxDBSize to an 8 TiB mmap window on some platforms.
+// Bridge databases are small contract registries, so cap the mapping to keep
+// CI and low-resource user machines from failing before the first query.
+const BRIDGE_MAX_DB_SIZE_BYTES = 512 * 1024 * 1024;
 function errMessage(err) {
     if (err instanceof Error)
         return err.message;
@@ -293,13 +316,9 @@ export async function writeBridge(groupDir, input) {
             report.sampleErrors.push({ kind, id, message: errMessage(err) });
         }
     };
-    // Clean up any leftover tmp
-    try {
-        await fsp.rm(tmpPath, { recursive: true, force: true });
-    }
-    catch {
-        /* ignore */
-    }
+    // Clean up any leftover tmp plus native sidecars. LadybugDB stores WAL/lock
+    // files next to the database path, not inside it.
+    await removeBridgeArtifacts(tmpPath);
     // 1. Create temp DB, insert all data.
     //
     // Everything after `openBridgeDb` must run inside a try/finally so that
@@ -440,16 +459,27 @@ export async function writeBridge(groupDir, input) {
         }
     }
     // 3. Atomic swap: old→.bak, tmp→final, rm .bak
+    // Keep LadybugDB sidecars paired with the path rename. WAL files live next
+    // to the DB path, so renaming only the base path can hide fresh schema/data.
+    await removeBridgeArtifacts(bakPath);
     try {
         await fsp.access(finalPath);
         await retryRename(finalPath, bakPath);
+        await renameBridgeArtifactIfExists(`${finalPath}.wal`, `${bakPath}.wal`);
     }
     catch {
         /* no existing db */
     }
     await retryRename(tmpPath, finalPath);
+    await renameBridgeArtifactIfExists(`${tmpPath}.wal`, `${finalPath}.wal`);
+    try {
+        await fsp.rm(`${tmpPath}.lock`, { force: true });
+    }
+    catch {
+        /* ignore */
+    }
     try {
-        await fsp.rm(bakPath, { recursive: true, force: true });
+        await removeBridgeArtifacts(bakPath);
     }
     catch {
         /* ignore */
@@ -480,6 +510,8 @@ export async function openBridgeDbReadOnly(groupDir) {
         try {
             await fsp.access(bakPath);
             await retryRename(bakPath, dbPath);
+            await renameBridgeArtifactIfExists(`${bakPath}.wal`, `${dbPath}.wal`);
+            await fsp.rm(`${bakPath}.lock`, { force: true });
         }
         catch {
             return null;
@@ -506,7 +538,7 @@ export async function openBridgeDbReadOnly(groupDir) {
         let db;
         let conn;
         try {
-            db = new cgdb.Database(dbPath, 0, false, true); // readOnly
+            db = new cgdb.Database(dbPath, 0, false, true, BRIDGE_MAX_DB_SIZE_BYTES); // readOnly
             conn = new cgdb.Connection(db);
             return { _db: db, _conn: conn, groupDir };
         }

package/dist/core/ingestion/parsing-processor.js

@@ -567,7 +567,13 @@ scopeTreeCache, onFileProgress, workerPool) => {
             return await processParsingWithWorkers(graph, files, symbolTable, astCache, workerPool, onFileProgress);
         }
         catch (err) {
-            console.warn('Worker pool parsing failed, falling back to sequential:', err instanceof Error ? err.message : err);
+            console.warn('Worker pool parsing failed for this chunk, falling back to sequential:', err instanceof Error ? err.message : err);
+            try {
+                await workerPool.terminate();
+            }
+            catch (terminateErr) {
+                console.warn('Worker pool termination after parsing failure failed:', terminateErr instanceof Error ? terminateErr.message : terminateErr);
+            }
         }
     }
     // Fallback: sequential parsing (no pre-extracted data)

package/dist/core/ingestion/pipeline-phases/parse-impl.js

@@ -170,6 +170,7 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
             const chunkFiles = chunkPaths
                 .filter((p) => chunkContents.has(p))
                 .map((p) => ({ path: p, content: chunkContents.get(p) }));
+            const usedWorkerPoolForChunk = workerPool !== undefined;
             const chunkWorkerData = await processParsing(graph, chunkFiles, symbolTable, astCache, scopeTreeCache, (current, _total, filePath) => {
                 const globalCurrent = filesParsedSoFar + current;
                 const parsingProgress = 20 + (globalCurrent / totalParseable) * 62;
@@ -185,6 +186,9 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                     },
                 });
             }, workerPool);
+            if (usedWorkerPoolForChunk && !chunkWorkerData) {
+                workerPool = undefined;
+            }
             const chunkBasePercent = 20 + (filesParsedSoFar / totalParseable) * 62;
             if (chunkWorkerData) {
                 await processImportsFromExtracted(graph, allPathObjects, chunkWorkerData.imports, ctx, (current, total) => {

package/dist/core/ingestion/workers/parse-worker.js

@@ -452,7 +452,7 @@ const processBatch = (files, onProgress) => {
     }
     let totalProcessed = 0;
     let lastReported = 0;
-    const PROGRESS_INTERVAL = 100; // report every 100 files
+    const PROGRESS_INTERVAL = 25; // report often enough to keep worker idle timers fresh
     const onFileProcessed = onProgress
         ? () => {
             totalProcessed++;

package/dist/core/ingestion/workers/worker-pool.d.ts

@@ -10,7 +10,20 @@ export interface WorkerPool {
     /** Number of workers in the pool */
     readonly size: number;
 }
+export interface WorkerPoolOptions {
+    /**
+     * Max files to send to a worker in one postMessage. Lower values reduce
+     * structured-clone memory spikes and give the main thread more chances to
+     * observe progress on large repos.
+     */
+    subBatchSize?: number;
+    /**
+     * Idle timeout while waiting for a worker response. Reset by worker progress
+     * so slow-but-moving chunks do not get retried sequentially.
+     */
+    subBatchIdleTimeoutMs?: number;
+}
 /**
  * Create a pool of worker threads.
  */
-export declare const createWorkerPool: (workerUrl: URL, poolSize?: number) => WorkerPool;
+export declare const createWorkerPool: (workerUrl: URL, poolSize?: number, options?: WorkerPoolOptions) => WorkerPool;

package/dist/core/ingestion/workers/worker-pool.js

@@ -6,14 +6,24 @@ import { fileURLToPath } from 'node:url';
  * Max files to send to a worker in a single postMessage.
  * Keeps structured-clone memory bounded per sub-batch.
  */
-const SUB_BATCH_SIZE = 1500;
-/** Per sub-batch timeout. If a single sub-batch takes longer than this,
- *  likely a pathological file (e.g. minified 50MB JS). Fail fast. */
-const SUB_BATCH_TIMEOUT_MS = 30_000;
+const DEFAULT_SUB_BATCH_SIZE = 250;
+/**
+ * Idle timeout while waiting for a worker response. This is not a wall-clock
+ * limit: worker progress resets it. Large repos can legitimately need more
+ * than 30s for a chunk, but a wedged parser should still fall back.
+ */
+const DEFAULT_SUB_BATCH_IDLE_TIMEOUT_MS = 120_000;
+const positiveIntFromEnv = (name, fallback) => {
+    const raw = process.env[name];
+    if (!raw)
+        return fallback;
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+};
 /**
  * Create a pool of worker threads.
  */
-export const createWorkerPool = (workerUrl, poolSize) => {
+export const createWorkerPool = (workerUrl, poolSize, options = {}) => {
     // Validate worker script exists before spawning to prevent uncaught
     // MODULE_NOT_FOUND crashes in worker threads (e.g. when running from src/ via vitest)
     const workerPath = fileURLToPath(workerUrl);
@@ -21,6 +31,10 @@ export const createWorkerPool = (workerUrl, poolSize) => {
         throw new Error(`Worker script not found: ${workerPath}`);
     }
     const size = poolSize ?? Math.min(8, Math.max(1, os.cpus().length - 1));
+    const subBatchSize = options.subBatchSize ??
+        positiveIntFromEnv('CODRAGRAPH_WORKER_SUB_BATCH_SIZE', DEFAULT_SUB_BATCH_SIZE);
+    const subBatchIdleTimeoutMs = options.subBatchIdleTimeoutMs ??
+        positiveIntFromEnv('CODRAGRAPH_WORKER_IDLE_TIMEOUT_MS', DEFAULT_SUB_BATCH_IDLE_TIMEOUT_MS);
     const workers = [];
     for (let i = 0; i < size; i++) {
         workers.push(new Worker(workerUrl));
@@ -38,41 +52,43 @@ export const createWorkerPool = (workerUrl, poolSize) => {
             const worker = workers[i];
             return new Promise((resolve, reject) => {
                 let settled = false;
-                let subBatchTimer = null;
+                let workerIdleTimer = null;
                 const cleanup = () => {
-                    if (subBatchTimer)
-                        clearTimeout(subBatchTimer);
+                    if (workerIdleTimer)
+                        clearTimeout(workerIdleTimer);
                     worker.removeListener('message', handler);
                     worker.removeListener('error', errorHandler);
                     worker.removeListener('exit', exitHandler);
                 };
-                const resetSubBatchTimer = () => {
-                    if (subBatchTimer)
-                        clearTimeout(subBatchTimer);
-                    subBatchTimer = setTimeout(() => {
+                const resetWorkerIdleTimer = () => {
+                    if (workerIdleTimer)
+                        clearTimeout(workerIdleTimer);
+                    workerIdleTimer = setTimeout(() => {
                         if (!settled) {
                             settled = true;
                             cleanup();
-                            reject(new Error(`Worker ${i} sub-batch timed out after ${SUB_BATCH_TIMEOUT_MS / 1000}s (chunk: ${chunk.length} items).`));
+                            reject(new Error(`Worker ${i} was idle for ${subBatchIdleTimeoutMs / 1000}s while waiting for a response (chunk: ${chunk.length} items).`));
                         }
-                    }, SUB_BATCH_TIMEOUT_MS);
+                    }, subBatchIdleTimeoutMs);
                 };
                 let subBatchIdx = 0;
                 const sendNextSubBatch = () => {
-                    const start = subBatchIdx * SUB_BATCH_SIZE;
+                    const start = subBatchIdx * subBatchSize;
                     if (start >= chunk.length) {
+                        resetWorkerIdleTimer();
                         worker.postMessage({ type: 'flush' });
                         return;
                     }
-                    const subBatch = chunk.slice(start, start + SUB_BATCH_SIZE);
+                    const subBatch = chunk.slice(start, start + subBatchSize);
                     subBatchIdx++;
-                    resetSubBatchTimer();
+                    resetWorkerIdleTimer();
                     worker.postMessage({ type: 'sub-batch', files: subBatch });
                 };
                 const handler = (msg) => {
                     if (settled)
                         return;
                     if (msg.type === 'progress') {
+                        resetWorkerIdleTimer();
                         workerProgress[i] = msg.filesProcessed;
                         if (onProgress) {
                             const total = workerProgress.reduce((a, b) => a + b, 0);

package/dist/core/run-analyze.d.ts

@@ -8,6 +8,7 @@
  * IMPORTANT: This module must NEVER call process.exit(). The caller (CLI
  * wrapper or server worker) is responsible for process lifecycle.
  */
+import { type RepoMeta } from '../storage/repo-manager.js';
 import type { ContentEncoding } from '@codragraph/graphstore';
 export interface AnalyzeCallbacks {
     onProgress: (phase: string, percent: number, message: string) => void;
@@ -68,10 +69,29 @@ export interface AnalyzeResult {
         embeddings?: number;
     };
     alreadyUpToDate?: boolean;
+    /** User-facing explanation for a reused index fast path. */
+    reuseReason?: string;
+    /** True when the git commit advanced but indexed inputs did not. */
+    reusedExistingIndex?: boolean;
     /** The raw pipeline result — only populated when needed by callers (e.g. skill generation). */
     pipelineResult?: any;
 }
+export interface AnalyzeChangedPath {
+    /** Git name-status token, e.g. M, A, D, R100. */
+    status: string;
+    /** Current path for additions/modifications, or deleted path for deletions. */
+    path: string;
+    /** Previous path for renames/copies. */
+    previousPath?: string;
+}
 export declare const PHASE_LABELS: Record<string, string>;
+export declare const parseGitNameStatus: (raw: string) => AnalyzeChangedPath[];
+export declare const listChangedPathsBetweenCommits: (repoPath: string, fromRef: string, toRef: string) => AnalyzeChangedPath[] | null;
+export declare const isGeneratedAgentContextPath: (filePath: string) => boolean;
+export declare const isGraphContentPath: (filePath: string) => boolean;
+export declare const changedPathAffectsGraph: (change: AnalyzeChangedPath) => boolean;
+export declare const getGraphRelevantChangedPaths: (changes: readonly AnalyzeChangedPath[]) => AnalyzeChangedPath[];
+export declare const getAnalyzeConfigRebuildReason: (existingMeta: Pick<RepoMeta, "compress" | "stats">, options: Pick<AnalyzeOptions, "compress" | "embeddings">) => string | null;
 /**
  * Run the full CodraGraph analysis pipeline.
  *

package/dist/core/run-analyze.js

@@ -10,18 +10,52 @@
  */
 import path from 'path';
 import fs from 'fs/promises';
+import { execFileSync } from 'node:child_process';
 import * as fsSync from 'node:fs';
 import * as v8 from 'node:v8';
+import { getLanguageFromFilename } from '../_shared/index.js';
 import { runPipelineFromRepo } from './ingestion/pipeline.js';
 import { initCgdb, loadGraphToCgdb, getCgdbStats, executeQuery, executeWithReusedStatement, closeCgdb, loadCachedEmbeddings, } from './cgdb/cgdb-adapter.js';
 import { getStoragePaths, saveMeta, loadMeta, addToGitignore, registerRepo, cleanupOldKuzuFiles, INDEX_SCHEMA_VERSION, } from '../storage/repo-manager.js';
 import { getCurrentCommit, getRemoteUrl, hasGitDir, getInferredRepoName } from '../storage/git.js';
+import { shouldIgnorePath } from '../config/ignore-service.js';
 import { recordAnalysisSnapshot } from './graphstore/index.js';
 import { generateAIContextFiles } from '../cli/ai-context.js';
 import { EMBEDDING_TABLE_NAME } from './cgdb/schema.js';
 import { STALE_HASH_SENTINEL } from './cgdb/schema.js';
 /** Threshold: auto-skip embeddings for repos with more nodes than this */
 const EMBEDDING_NODE_LIMIT = 50_000;
+const GENERATED_AGENT_CONTEXT_PATHS = new Set(['agents.md', 'claude.md']);
+const GENERATED_AGENT_CONTEXT_PREFIXES = [
+    '.claude/skills/generated/',
+    '.cursor/rules/codragraph-generated/',
+];
+const IGNORE_CONTROL_FILES = new Set(['.gitignore', '.codragraphignore']);
+const GRAPH_CONFIG_BASENAMES = new Set([
+    'package.json',
+    'tsconfig.json',
+    'jsconfig.json',
+    'go.mod',
+    'cargo.toml',
+    'pyproject.toml',
+    'requirements.txt',
+    'composer.json',
+    'gemfile',
+    'pom.xml',
+    'build.gradle',
+    'build.gradle.kts',
+    'settings.gradle',
+    'settings.gradle.kts',
+    'pubspec.yaml',
+    'pubspec.yml',
+    'mix.exs',
+    'rebar.config',
+    'cmakelists.txt',
+    'makefile',
+    'dockerfile',
+]);
+const GRAPH_CONFIG_PATTERNS = [/^tsconfig\..+\.json$/i, /^jsconfig\..+\.json$/i];
+const MARKDOWN_EXTENSIONS = new Set(['.md', '.mdx']);
 export const PHASE_LABELS = {
     extracting: 'Scanning files',
     structure: 'Building structure',
@@ -38,6 +72,129 @@ export const PHASE_LABELS = {
     embeddings: 'Generating embeddings',
     done: 'Done',
 };
+const normalizeGitPath = (filePath) => filePath.replace(/\\/g, '/');
+export const parseGitNameStatus = (raw) => {
+    const tokens = raw.split('\0').filter(Boolean);
+    const changes = [];
+    for (let i = 0; i < tokens.length;) {
+        const status = tokens[i++] ?? '';
+        const code = status[0]?.toUpperCase();
+        if (code === 'R' || code === 'C') {
+            const previousPath = tokens[i++];
+            const nextPath = tokens[i++];
+            if (previousPath && nextPath) {
+                changes.push({
+                    status,
+                    path: normalizeGitPath(nextPath),
+                    previousPath: normalizeGitPath(previousPath),
+                });
+            }
+            continue;
+        }
+        const changedPath = tokens[i++];
+        if (status && changedPath) {
+            changes.push({ status, path: normalizeGitPath(changedPath) });
+        }
+    }
+    return changes;
+};
+export const listChangedPathsBetweenCommits = (repoPath, fromRef, toRef) => {
+    if (!fromRef || !toRef || fromRef === toRef)
+        return [];
+    try {
+        const stdout = execFileSync('git', ['diff', '--name-status', '-z', `${fromRef}..${toRef}`], {
+            cwd: repoPath,
+            encoding: 'utf8',
+            maxBuffer: 20 * 1024 * 1024,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        return parseGitNameStatus(stdout);
+    }
+    catch {
+        return null;
+    }
+};
+export const isGeneratedAgentContextPath = (filePath) => {
+    const normalized = normalizeGitPath(filePath).toLowerCase();
+    const basename = path.posix.basename(normalized);
+    return (GENERATED_AGENT_CONTEXT_PATHS.has(basename) ||
+        GENERATED_AGENT_CONTEXT_PREFIXES.some((prefix) => normalized.startsWith(prefix)));
+};
+export const isGraphContentPath = (filePath) => {
+    const normalized = normalizeGitPath(filePath);
+    const basename = path.posix.basename(normalized);
+    const lowerBasename = basename.toLowerCase();
+    if (isGeneratedAgentContextPath(normalized))
+        return false;
+    if (IGNORE_CONTROL_FILES.has(lowerBasename))
+        return true;
+    if (shouldIgnorePath(normalized))
+        return false;
+    if (getLanguageFromFilename(normalized) !== null)
+        return true;
+    const ext = path.posix.extname(lowerBasename);
+    if (MARKDOWN_EXTENSIONS.has(ext))
+        return true;
+    if (GRAPH_CONFIG_BASENAMES.has(lowerBasename))
+        return true;
+    return GRAPH_CONFIG_PATTERNS.some((pattern) => pattern.test(basename));
+};
+export const changedPathAffectsGraph = (change) => {
+    const statusCode = change.status[0]?.toUpperCase();
+    const paths = [change.path, change.previousPath].filter((p) => Boolean(p));
+    if (paths.some(isGraphContentPath))
+        return true;
+    // Add/delete/rename/copy affect the graph's File/Folder topology even when
+    // the path is not source code. Ignore only generated agent context and
+    // configured ignored paths; staying conservative here prevents stale file
+    // and documentation surfaces after path-only commits.
+    if (statusCode === 'A' || statusCode === 'D' || statusCode === 'R' || statusCode === 'C') {
+        return paths.some((p) => !isGeneratedAgentContextPath(p) && !shouldIgnorePath(p));
+    }
+    // Modified non-code/non-doc files keep the same path and are not read by the
+    // graph pipeline, so the existing graph can be reused.
+    if (statusCode === 'M' || statusCode === 'T')
+        return false;
+    // Unknown git status: rebuild rather than risk stale graph state.
+    return true;
+};
+export const getGraphRelevantChangedPaths = (changes) => changes.filter(changedPathAffectsGraph);
+export const getAnalyzeConfigRebuildReason = (existingMeta, options) => {
+    const existingCompress = existingMeta.compress ?? 'none';
+    if (options.compress && options.compress !== existingCompress) {
+        return `requested compression changed from ${existingCompress} to ${options.compress}`;
+    }
+    if (options.embeddings && (existingMeta.stats?.embeddings ?? 0) === 0) {
+        return 'embeddings were requested but the existing index has no vectors';
+    }
+    return null;
+};
+const formatChangeForLog = (change) => change.previousPath ? `${change.previousPath} -> ${change.path}` : change.path;
+const buildReusedMeta = (existingMeta, repoPath, currentCommit) => ({
+    ...existingMeta,
+    repoPath,
+    lastCommit: currentCommit,
+    indexedAt: new Date().toISOString(),
+    schemaVersion: INDEX_SCHEMA_VERSION,
+    remoteUrl: hasGitDir(repoPath) ? getRemoteUrl(repoPath) : existingMeta.remoteUrl,
+});
+const metaStatsForAIContext = (stats = {}) => ({
+    files: stats.files,
+    nodes: stats.nodes,
+    edges: stats.edges,
+    communities: stats.communities,
+    clusters: stats.featureClusters,
+    processes: stats.processes,
+});
+const pathExists = async (targetPath) => {
+    try {
+        await fs.stat(targetPath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
 // ---------------------------------------------------------------------------
 // Main orchestrator
 // ---------------------------------------------------------------------------
@@ -135,20 +292,87 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     // end-to-end yet, so the supported migration path is re-analyze via a fresh
     // CREATE NODE TABLE.
     const schemaUpToDate = !!existingMeta && (existingMeta.schemaVersion ?? 0) >= INDEX_SCHEMA_VERSION;
+    const existingCgdbPresent = existingMeta ? await pathExists(cgdbPath) : false;
+    const storageRebuildReason = existingMeta && schemaUpToDate && !existingCgdbPresent
+        ? 'graph database files are missing'
+        : null;
+    const configRebuildReason = storageRebuildReason ??
+        (existingMeta && schemaUpToDate && !options.force
+            ? getAnalyzeConfigRebuildReason(existingMeta, options)
+            : null);
     if (existingMeta &&
         schemaUpToDate &&
         !options.force &&
+        !configRebuildReason &&
         existingMeta.lastCommit === currentCommit) {
         // Non-git folders have currentCommit = '' — always rebuild since we can't detect changes
         if (currentCommit !== '') {
+            const repoName = options.registryName ?? getInferredRepoName(repoPath) ?? path.basename(repoPath);
+            try {
+                await generateAIContextFiles(repoPath, storagePath, repoName, metaStatsForAIContext(existingMeta.stats), undefined, { skipAgentsMd: options.skipAgentsMd, noStats: options.noStats });
+            }
+            catch {
+                // Best-effort only.
+            }
             return {
-                repoName: options.registryName ?? getInferredRepoName(repoPath) ?? path.basename(repoPath),
+                repoName,
                 repoPath,
                 stats: existingMeta.stats ?? {},
                 alreadyUpToDate: true,
             };
         }
     }
+    if (existingMeta && schemaUpToDate && !options.force && configRebuildReason) {
+        log(`Re-analyzing: ${configRebuildReason}.`);
+    }
+    if (existingMeta &&
+        schemaUpToDate &&
+        !options.force &&
+        !configRebuildReason &&
+        currentCommit !== '' &&
+        existingMeta.lastCommit !== currentCommit) {
+        const changedPaths = listChangedPathsBetweenCommits(repoPath, existingMeta.lastCommit, currentCommit);
+        if (changedPaths) {
+            const graphRelevantChanges = getGraphRelevantChangedPaths(changedPaths);
+            if (graphRelevantChanges.length === 0) {
+                const reusedMeta = buildReusedMeta(existingMeta, repoPath, currentCommit);
+                await saveMeta(storagePath, reusedMeta);
+                const projectName = await registerRepo(repoPath, reusedMeta, {
+                    name: options.registryName,
+                    allowDuplicateName: options.allowDuplicateName,
+                });
+                if (hasGitDir(repoPath)) {
+                    await addToGitignore(repoPath);
+                }
+                try {
+                    await generateAIContextFiles(repoPath, storagePath, projectName, metaStatsForAIContext(reusedMeta.stats), undefined, { skipAgentsMd: options.skipAgentsMd, noStats: options.noStats });
+                }
+                catch {
+                    // Best-effort only.
+                }
+                const reuseReason = `Smart analyze reused the existing graph; ${changedPaths.length} changed ` +
+                    `file(s) did not affect indexed graph inputs.`;
+                log(reuseReason);
+                progress('done', 100, 'Existing graph reused');
+                return {
+                    repoName: projectName,
+                    repoPath,
+                    stats: reusedMeta.stats ?? {},
+                    alreadyUpToDate: true,
+                    reusedExistingIndex: true,
+                    reuseReason,
+                };
+            }
+            const preview = graphRelevantChanges.slice(0, 5).map(formatChangeForLog).join(', ');
+            const suffix = graphRelevantChanges.length > 5 ? ', ...' : '';
+            log(`Smart analyze: ${graphRelevantChanges.length} indexed graph input change(s) require rebuild` +
+                (preview ? ` (${preview}${suffix})` : '') +
+                '.');
+        }
+        else {
+            log('Smart analyze: could not inspect git diff; rebuilding.');
+        }
+    }
     if (existingMeta && !schemaUpToDate) {
         log(`Index schema version ${existingMeta.schemaVersion ?? '<missing>'} is older than ` +
             `${INDEX_SCHEMA_VERSION} (FeatureCluster context-pack schema). ` +

package/dist/core/search/bm25-index.d.ts

@@ -16,17 +16,6 @@ export interface BM25SearchResult {
     rank: number;
     nodeIds?: string[];
 }
-/**
- * Drop all ensured-FTS cache entries for a given repoId.
- *
- * Called from the pool-close listener so that a pool teardown / recreation
- * forces the next `searchFTSFromCgdb` call to re-issue `CREATE_FTS_INDEX`
- * against the fresh connection rather than trust stale ensure-state from a
- * previous pool lifetime.
- *
- * Exported for tests; the listener wiring is internal.
- */
-export declare function invalidateEnsuredFTSForRepo(repoId: string): void;
 /**
  * Search using LadybugDB's built-in FTS (always fresh, reads from disk)
  *