@codragraph/cli 2.1.4 → 2.1.6

package/dist/core/run-analyze.js

@@ -15,7 +15,7 @@ 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 { initCgdb, loadGraphToCgdb, getCgdbStats, executeQuery, executeWithReusedStatement, closeCgdb, loadCachedEmbeddings, ensureFTSIndex, applyFileGraphPatchToCgdb, replaceFileScopedGraphInCgdb, replaceGlobalGraphLayersInCgdb, loadKnowledgeGraphFromCgdb, fetchExistingEmbeddingHashes, } 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';
@@ -23,8 +23,13 @@ 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;
+import { FTS_TABLES, ftsPropertiesFor } from './search/bm25-index.js';
+import { processCommunities, } from './ingestion/community-processor.js';
+import { processProcesses } from './ingestion/process-processor.js';
+import { processFeatureClusters, } from './ingestion/feature-cluster-processor.js';
+import { createKnowledgeGraph } from './graph/graph.js';
+import { generateId } from '../lib/utils.js';
+import { decideEmbeddingRun, formatAdaptiveAnalyzePlan, resolveAdaptiveAnalyzePlan, } from './adaptive-profile.js';
 const GENERATED_AGENT_CONTEXT_PATHS = new Set(['agents.md', 'claude.md']);
 const GENERATED_AGENT_CONTEXT_PREFIXES = [
     '.claude/skills/generated/',
@@ -56,6 +61,14 @@ const GRAPH_CONFIG_BASENAMES = new Set([
 ]);
 const GRAPH_CONFIG_PATTERNS = [/^tsconfig\..+\.json$/i, /^jsconfig\..+\.json$/i];
 const MARKDOWN_EXTENSIONS = new Set(['.md', '.mdx']);
+const GLOBAL_LAYER_NODE_LABELS = new Set(['Community', 'Process', 'FeatureCluster']);
+const GLOBAL_LAYER_REL_TYPES = new Set([
+    'MEMBER_OF',
+    'STEP_IN_PROCESS',
+    'ENTRY_POINT_OF',
+    'FEATURE_MEMBER_OF',
+    'FEATURE_DEPENDS_ON',
+]);
 export const PHASE_LABELS = {
     extracting: 'Scanning files',
     structure: 'Building structure',
@@ -144,8 +157,10 @@ export const changedPathAffectsGraph = (change) => {
     const paths = [change.path, change.previousPath].filter((p) => Boolean(p));
     if (paths.some(isGraphContentPath))
         return true;
-    // Add/delete/rename/copy can change File/Folder structure even when content
-    // is not parsed. Ignored or generated-agent paths are outside the index.
+    // 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));
     }
@@ -157,11 +172,119 @@ export const changedPathAffectsGraph = (change) => {
     return true;
 };
 export const getGraphRelevantChangedPaths = (changes) => changes.filter(changedPathAffectsGraph);
+export const isPatchableIncrementalPath = (filePath) => {
+    const normalized = normalizeGitPath(filePath);
+    if (isGeneratedAgentContextPath(normalized) || shouldIgnorePath(normalized))
+        return false;
+    if (getLanguageFromFilename(normalized) !== null)
+        return true;
+    return MARKDOWN_EXTENSIONS.has(path.posix.extname(normalized.toLowerCase()));
+};
+const isTopologyPatchablePath = (filePath) => {
+    const normalized = normalizeGitPath(filePath);
+    return !isGeneratedAgentContextPath(normalized) && !shouldIgnorePath(normalized);
+};
+const isGlobalGraphInputPath = (filePath) => {
+    const normalized = normalizeGitPath(filePath);
+    const basename = path.posix.basename(normalized);
+    const lowerBasename = basename.toLowerCase();
+    return (IGNORE_CONTROL_FILES.has(lowerBasename) ||
+        GRAPH_CONFIG_BASENAMES.has(lowerBasename) ||
+        GRAPH_CONFIG_PATTERNS.some((pattern) => pattern.test(basename)));
+};
+export const buildIncrementalFilePatchPlan = (changes, _options = {}) => {
+    if (changes.length === 0) {
+        return {
+            eligible: false,
+            reason: 'no indexed graph input changes',
+            replacePaths: [],
+            currentPaths: [],
+            fileCountDelta: 0,
+            replaceAllFileScoped: false,
+            pathAliases: {},
+        };
+    }
+    const replacePaths = new Set();
+    const currentPaths = new Set();
+    const pathAliases = {};
+    let fileCountDelta = 0;
+    let replaceAllFileScoped = false;
+    const reasons = new Set();
+    for (const change of changes) {
+        const statusCode = change.status[0]?.toUpperCase();
+        const paths = statusCode === 'C'
+            ? [change.path]
+            : [change.path, change.previousPath].filter((p) => Boolean(p));
+        if (paths.some(isGlobalGraphInputPath)) {
+            replaceAllFileScoped = true;
+            reasons.add('global config/input changed');
+            continue;
+        }
+        const contentPatchable = paths.every(isPatchableIncrementalPath);
+        const topologyPatchable = paths.every(isTopologyPatchablePath);
+        if (!contentPatchable && !topologyPatchable) {
+            return {
+                eligible: false,
+                reason: `change ${change.status} ${formatChangeForLog(change)} touches a global or unsupported graph input`,
+                replacePaths: [],
+                currentPaths: [],
+                fileCountDelta: 0,
+                replaceAllFileScoped: false,
+                pathAliases: {},
+            };
+        }
+        if (statusCode === 'D') {
+            replacePaths.add(change.path);
+            fileCountDelta -= 1;
+            continue;
+        }
+        if (statusCode === 'R') {
+            if (change.previousPath) {
+                replacePaths.add(change.previousPath);
+                pathAliases[change.previousPath] = change.path;
+            }
+            replacePaths.add(change.path);
+            currentPaths.add(change.path);
+            reasons.add('rename remapped');
+            continue;
+        }
+        if (statusCode === 'M' || statusCode === 'A' || statusCode === 'T' || statusCode === 'C') {
+            replacePaths.add(change.path);
+            currentPaths.add(change.path);
+            if (statusCode === 'A' || statusCode === 'C') {
+                fileCountDelta += 1;
+            }
+            if (!contentPatchable) {
+                reasons.add('topology-only file change');
+            }
+            continue;
+        }
+        replaceAllFileScoped = true;
+        reasons.add(`unsupported git status ${change.status}`);
+    }
+    const strategy = replaceAllFileScoped
+        ? 'all file-scoped graph rows will be refreshed'
+        : `${replacePaths.size} file path(s) will be patched`;
+    if (changes.length > 20)
+        reasons.add(`${changes.length} graph input changes`);
+    return {
+        eligible: true,
+        reason: [...reasons, strategy].filter(Boolean).join('; '),
+        replacePaths: [...replacePaths].sort(),
+        currentPaths: [...currentPaths].sort(),
+        fileCountDelta,
+        replaceAllFileScoped,
+        pathAliases,
+    };
+};
 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 (existingMeta.searchIndexes?.fts !== true) {
+        return 'search indexes are missing';
+    }
     if (options.embeddings && (existingMeta.stats?.embeddings ?? 0) === 0) {
         return 'embeddings were requested but the existing index has no vectors';
     }
@@ -176,6 +299,39 @@ const buildReusedMeta = (existingMeta, repoPath, currentCommit) => ({
     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 buildAdaptiveProfileMeta = (adaptivePlan, embeddingDecision) => ({
+    requested: adaptivePlan.requestedProfile,
+    resolved: adaptivePlan.profile,
+    platform: adaptivePlan.machine.platform,
+    arch: adaptivePlan.machine.arch,
+    cpuCount: adaptivePlan.machine.availableParallelism,
+    totalMemoryBytes: adaptivePlan.machine.totalMemoryBytes,
+    heapLimitBytes: adaptivePlan.machine.heapLimitBytes,
+    compression: adaptivePlan.compress,
+    embeddingMode: adaptivePlan.embeddingMode,
+    embeddingNodeLimit: adaptivePlan.embeddingNodeLimit,
+    embeddingDecision: embeddingDecision.enabled ? 'enabled' : 'skipped',
+    embeddingReason: embeddingDecision.reason,
+    workerPoolSize: adaptivePlan.workerPoolSize,
+    workerSubBatchSize: adaptivePlan.workerSubBatchSize,
+});
+const countEmbeddings = async () => {
+    try {
+        const embResult = await executeQuery(`MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN count(e) AS cnt`);
+        return Number(embResult?.[0]?.cnt ?? embResult?.[0]?.[0] ?? 0);
+    }
+    catch {
+        return 0;
+    }
+};
 const pathExists = async (targetPath) => {
     try {
         await fs.stat(targetPath);
@@ -185,6 +341,387 @@ const pathExists = async (targetPath) => {
         return false;
     }
 };
+const addCommunityLayerToGraph = (graph, communityResult) => {
+    communityResult.communities.forEach((comm) => {
+        graph.addNode({
+            id: comm.id,
+            label: 'Community',
+            properties: {
+                name: comm.label,
+                filePath: '',
+                heuristicLabel: comm.heuristicLabel,
+                cohesion: comm.cohesion,
+                symbolCount: comm.symbolCount,
+            },
+        });
+    });
+    communityResult.memberships.forEach((membership) => {
+        graph.addRelationship({
+            id: `${membership.nodeId}_member_of_${membership.communityId}`,
+            type: 'MEMBER_OF',
+            sourceId: membership.nodeId,
+            targetId: membership.communityId,
+            confidence: 1.0,
+            reason: 'leiden-algorithm',
+        });
+    });
+};
+const addProcessLayerToGraph = (graph, processResult) => {
+    processResult.processes.forEach((proc) => {
+        graph.addNode({
+            id: proc.id,
+            label: 'Process',
+            properties: {
+                name: proc.label,
+                filePath: '',
+                heuristicLabel: proc.heuristicLabel,
+                processType: proc.processType,
+                stepCount: proc.stepCount,
+                communities: proc.communities,
+                entryPointId: proc.entryPointId,
+                terminalId: proc.terminalId,
+            },
+        });
+    });
+    processResult.steps.forEach((step) => {
+        graph.addRelationship({
+            id: `${step.nodeId}_step_${step.step}_${step.processId}`,
+            type: 'STEP_IN_PROCESS',
+            sourceId: step.nodeId,
+            targetId: step.processId,
+            confidence: 1.0,
+            reason: 'trace-detection',
+            step: step.step,
+        });
+    });
+};
+const addRouteToolProcessLinks = (graph, processResult) => {
+    const routesByFile = new Map();
+    const toolsByFile = new Map();
+    for (const node of graph.iterNodes()) {
+        const filePath = typeof node.properties?.filePath === 'string' ? node.properties.filePath : undefined;
+        const name = typeof node.properties?.name === 'string' ? node.properties.name : undefined;
+        if (!filePath || !name)
+            continue;
+        if (node.label === 'Route') {
+            let routes = routesByFile.get(filePath);
+            if (!routes) {
+                routes = [];
+                routesByFile.set(filePath, routes);
+            }
+            routes.push(name);
+        }
+        else if (node.label === 'Tool') {
+            let tools = toolsByFile.get(filePath);
+            if (!tools) {
+                tools = [];
+                toolsByFile.set(filePath, tools);
+            }
+            tools.push(name);
+        }
+    }
+    if (routesByFile.size === 0 && toolsByFile.size === 0)
+        return;
+    for (const proc of processResult.processes) {
+        if (!proc.entryPointId)
+            continue;
+        const entryNode = graph.getNode(proc.entryPointId);
+        const entryFile = typeof entryNode?.properties?.filePath === 'string' ? entryNode.properties.filePath : '';
+        if (!entryFile)
+            continue;
+        for (const routeURL of routesByFile.get(entryFile) ?? []) {
+            const routeNodeId = generateId('Route', routeURL);
+            graph.addRelationship({
+                id: generateId('ENTRY_POINT_OF', `${routeNodeId}->${proc.id}`),
+                sourceId: routeNodeId,
+                targetId: proc.id,
+                type: 'ENTRY_POINT_OF',
+                confidence: 0.85,
+                reason: 'route-handler-entry-point',
+            });
+        }
+        for (const toolName of toolsByFile.get(entryFile) ?? []) {
+            const toolNodeId = generateId('Tool', toolName);
+            graph.addRelationship({
+                id: generateId('ENTRY_POINT_OF', `${toolNodeId}->${proc.id}`),
+                sourceId: toolNodeId,
+                targetId: proc.id,
+                type: 'ENTRY_POINT_OF',
+                confidence: 0.85,
+                reason: 'tool-handler-entry-point',
+            });
+        }
+    }
+};
+const addFeatureClusterLayerToGraph = (graph, featureClusterResult) => {
+    featureClusterResult.clusters.forEach((cluster) => {
+        graph.addNode({
+            id: cluster.id,
+            label: 'FeatureCluster',
+            properties: {
+                name: cluster.name,
+                filePath: '',
+                slug: cluster.slug,
+                featureKind: cluster.featureKind,
+                summary: cluster.summary,
+                description: cluster.description,
+                repo: cluster.repo,
+                service: cluster.service,
+                signals: cluster.signals,
+                memberCount: cluster.memberCount,
+                entryPointIds: cluster.entryPointIds,
+                routes: cluster.routes,
+                tools: cluster.tools,
+                testCoverageHints: cluster.testCoverageHints,
+                lastIndexedCommit: cluster.lastIndexedCommit,
+                confidence: cluster.confidence,
+                source: 'heuristic',
+            },
+        });
+    });
+    featureClusterResult.memberships.forEach((membership) => {
+        graph.addRelationship({
+            id: generateId('FEATURE_MEMBER_OF', `${membership.nodeId}->${membership.clusterId}`),
+            sourceId: membership.nodeId,
+            targetId: membership.clusterId,
+            type: 'FEATURE_MEMBER_OF',
+            confidence: membership.confidence,
+            reason: membership.signals.join('|'),
+        });
+    });
+    featureClusterResult.dependencies.forEach((dependency) => {
+        graph.addRelationship({
+            id: generateId('FEATURE_DEPENDS_ON', `${dependency.sourceClusterId}->${dependency.targetClusterId}`),
+            sourceId: dependency.sourceClusterId,
+            targetId: dependency.targetClusterId,
+            type: 'FEATURE_DEPENDS_ON',
+            confidence: dependency.confidence,
+            reason: `member-dependency|edges:${dependency.edgeCount}|types:${dependency.relationshipTypes.join(',')}`,
+        });
+    });
+};
+const extractGlobalLayerGraph = (graph) => {
+    const globalGraph = createKnowledgeGraph();
+    const globalNodeIds = new Set();
+    for (const node of graph.iterNodes()) {
+        if (GLOBAL_LAYER_NODE_LABELS.has(node.label)) {
+            globalNodeIds.add(node.id);
+            globalGraph.addNode(node);
+        }
+    }
+    for (const rel of graph.iterRelationships()) {
+        if (GLOBAL_LAYER_REL_TYPES.has(rel.type) ||
+            globalNodeIds.has(rel.sourceId) ||
+            globalNodeIds.has(rel.targetId)) {
+            globalGraph.addRelationship(rel);
+        }
+    }
+    return globalGraph;
+};
+const scaleAnalyzerProgress = (start, span, progress) => {
+    const normalized = Math.max(0, Math.min(100, progress)) / 100;
+    return Math.round(start + normalized * span);
+};
+const recomputeGlobalGraphLayers = async (input) => {
+    const { repoPath, storagePath, currentCommit, repoNameForFeatureClusters, compress, progress } = input;
+    progress('communities', 82, 'Loading patched graph for global recompute...');
+    const graph = await loadKnowledgeGraphFromCgdb({ includeGlobal: false });
+    const communityResult = await processCommunities(graph, (message, phaseProgress) => {
+        progress('communities', scaleAnalyzerProgress(83, 2, phaseProgress), message);
+    });
+    addCommunityLayerToGraph(graph, communityResult);
+    let symbolCount = 0;
+    graph.forEachNode((n) => {
+        if (n.label !== 'File')
+            symbolCount++;
+    });
+    const dynamicMaxProcesses = Math.max(20, Math.min(300, Math.round(symbolCount / 10)));
+    const processResult = await processProcesses(graph, communityResult.memberships, (message, phaseProgress) => {
+        progress('processes', scaleAnalyzerProgress(85, 2, phaseProgress), message);
+    }, { maxProcesses: dynamicMaxProcesses, minSteps: 3 });
+    addProcessLayerToGraph(graph, processResult);
+    addRouteToolProcessLinks(graph, processResult);
+    const featureClusterResult = await processFeatureClusters(graph, (message, phaseProgress) => {
+        progress('feature_clusters', scaleAnalyzerProgress(87, 1, phaseProgress), message);
+    }, {
+        repo: repoNameForFeatureClusters,
+        lastIndexedCommit: currentCommit || undefined,
+    });
+    addFeatureClusterLayerToGraph(graph, featureClusterResult);
+    progress('cgdb', 88, 'Replacing global graph layers...');
+    const globalGraph = extractGlobalLayerGraph(graph);
+    const replaceResult = await replaceGlobalGraphLayersInCgdb(globalGraph, repoPath, storagePath, undefined, { compress });
+    return {
+        communityResult,
+        processResult,
+        featureClusterResult,
+        deletedGlobalNodes: replaceResult.deletedGlobalNodes,
+        insertedGlobalRels: replaceResult.insertedRels,
+    };
+};
+const runIncrementalFilePatchAnalysis = async (input) => {
+    const { repoPath, storagePath, cgdbPath, currentCommit, existingMeta, adaptivePlan, patchPlan, options, progress, log, } = input;
+    const repoNameForFeatureClusters = options.registryName ?? getInferredRepoName(repoPath) ?? path.basename(repoPath);
+    progress('extracting', 5, patchPlan.replaceAllFileScoped
+        ? 'Incremental full graph scan for global input change'
+        : `Incremental scan: ${patchPlan.currentPaths.length} current file(s)`);
+    const pipelineResult = await runPipelineFromRepo(repoPath, (p) => {
+        const phaseLabel = PHASE_LABELS[p.phase] || p.phase;
+        const scaled = Math.min(59, 5 + Math.round((p.percent / 100) * 54));
+        progress(p.phase, scaled, phaseLabel);
+    }, {
+        skipGraphPhases: true,
+        featureClusterRepo: repoNameForFeatureClusters,
+        lastIndexedCommit: currentCommit || undefined,
+        workerPoolSize: adaptivePlan.workerPoolSize,
+        workerSubBatchSize: adaptivePlan.workerSubBatchSize,
+        focusPaths: patchPlan.replaceAllFileScoped ? undefined : patchPlan.currentPaths,
+    });
+    progress('cgdb', 60, patchPlan.replaceAllFileScoped
+        ? 'Replacing file-scoped graph rows...'
+        : `Patching ${patchPlan.replacePaths.length} file path(s)...`);
+    await initCgdb(cgdbPath);
+    try {
+        let cgdbMsgCount = 0;
+        const fileGraphProgress = (msg) => {
+            cgdbMsgCount++;
+            const pct = Math.min(82, 60 + Math.round((cgdbMsgCount / (cgdbMsgCount + 8)) * 22));
+            progress('cgdb', pct, msg);
+        };
+        if (patchPlan.replaceAllFileScoped) {
+            const replacementResult = await replaceFileScopedGraphInCgdb(pipelineResult.graph, repoPath, storagePath, fileGraphProgress, { compress: adaptivePlan.compress });
+            log(`Smart analyze: refreshed all file-scoped graph rows, deleted ${replacementResult.deletedNodes} node(s), ` +
+                `inserted ${replacementResult.insertedRels} edge(s).`);
+        }
+        else {
+            const patchResult = await applyFileGraphPatchToCgdb(pipelineResult.graph, repoPath, storagePath, patchPlan.replacePaths, fileGraphProgress, { compress: adaptivePlan.compress, pathAliases: patchPlan.pathAliases });
+            log(`Smart analyze: incrementally patched ${patchResult.replacedFiles} path(s), ` +
+                `deleted ${patchResult.deletedNodeIds} stale node(s), inserted ${patchResult.insertedRels} edge(s), ` +
+                `restored ${patchResult.restoredRels} preserved edge(s), pruned ${patchResult.prunedFolders} folder(s).`);
+        }
+        const globalResult = await recomputeGlobalGraphLayers({
+            repoPath,
+            storagePath,
+            currentCommit,
+            repoNameForFeatureClusters,
+            compress: adaptivePlan.compress,
+            progress,
+        });
+        log(`Smart analyze: recomputed global layers (${globalResult.communityResult.stats.totalCommunities} communities, ` +
+            `${globalResult.processResult.stats.totalProcesses} processes, ` +
+            `${globalResult.featureClusterResult.stats.totalClusters} feature clusters).`);
+        progress('fts', 89, 'Refreshing search indexes...');
+        const ftsProperties = [...ftsPropertiesFor(adaptivePlan.compress)];
+        for (const { table, indexName } of FTS_TABLES) {
+            await ensureFTSIndex(table, indexName, ftsProperties);
+        }
+        const stats = await getCgdbStats();
+        const embeddingDecision = decideEmbeddingRun(adaptivePlan, {
+            nodes: stats.nodes,
+            embeddings: existingMeta.stats?.embeddings ?? 0,
+        });
+        log(embeddingDecision.enabled
+            ? `Embeddings enabled: ${embeddingDecision.reason}.`
+            : `Embeddings skipped: ${embeddingDecision.reason}.`);
+        if (embeddingDecision.enabled) {
+            const { isHttpMode } = await import('./embeddings/http-client.js');
+            const httpMode = isHttpMode();
+            progress('embeddings', 90, httpMode ? 'Connecting to embedding endpoint...' : 'Loading embedding model...');
+            const { runEmbeddingPipeline } = await import('./embeddings/embedding-pipeline.js');
+            const existingEmbeddings = await fetchExistingEmbeddingHashes(executeQuery);
+            const { readServerMapping } = await import('./embeddings/server-mapping.js');
+            const projectName = path.basename(repoPath);
+            const serverName = await readServerMapping(projectName);
+            await runEmbeddingPipeline(executeQuery, executeWithReusedStatement, (p) => {
+                const scaled = 90 + Math.round((p.percent / 100) * 7);
+                const label = p.phase === 'loading-model'
+                    ? httpMode
+                        ? 'Connecting to embedding endpoint...'
+                        : 'Loading embedding model...'
+                    : `Embedding ${p.nodesProcessed || 0}/${p.totalNodes || '?'}`;
+                progress('embeddings', scaled, label);
+            }, {}, undefined, { repoName: projectName, serverName }, existingEmbeddings);
+        }
+        progress('done', 97, 'Recording graph snapshot...');
+        let graphstoreCurrentBranch;
+        let graphstoreHeadCommit;
+        try {
+            const snapshotResult = await recordAnalysisSnapshot({
+                storagePath,
+                indexedRepoCommit: currentCommit || undefined,
+                onSkipTable: (tableName, err) => {
+                    log(`graphstore: skipped table "${tableName}": ${err instanceof Error ? err.message : String(err)}`);
+                },
+            });
+            if (snapshotResult) {
+                graphstoreCurrentBranch = snapshotResult.branch;
+                graphstoreHeadCommit = snapshotResult.commitId;
+                log(`graphstore: snapshot ${snapshotResult.snapshotId.slice(0, 19)}...  ` +
+                    `commit ${snapshotResult.commitId.slice(0, 19)}...  ` +
+                    `branch ${snapshotResult.branch}`);
+            }
+        }
+        catch (err) {
+            log(`graphstore: snapshot failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
+        }
+        progress('done', 98, 'Saving metadata...');
+        const embeddingCount = await countEmbeddings();
+        const previousFileCount = existingMeta.stats?.files ?? 0;
+        const fileCount = Math.max(0, previousFileCount + patchPlan.fileCountDelta);
+        const meta = {
+            repoPath,
+            lastCommit: currentCommit,
+            indexedAt: new Date().toISOString(),
+            schemaVersion: INDEX_SCHEMA_VERSION,
+            compress: adaptivePlan.compress,
+            searchIndexes: { fts: true },
+            adaptiveProfile: buildAdaptiveProfileMeta(adaptivePlan, embeddingDecision),
+            remoteUrl: hasGitDir(repoPath) ? getRemoteUrl(repoPath) : undefined,
+            currentBranch: graphstoreCurrentBranch,
+            headCommit: graphstoreHeadCommit,
+            stats: {
+                files: patchPlan.replaceAllFileScoped ? pipelineResult.totalFileCount : fileCount,
+                nodes: stats.nodes,
+                edges: stats.edges,
+                communities: globalResult.communityResult.stats.totalCommunities,
+                featureClusters: globalResult.featureClusterResult.stats.totalClusters,
+                processes: globalResult.processResult.stats.totalProcesses,
+                embeddings: embeddingCount,
+            },
+        };
+        await saveMeta(storagePath, meta);
+        const projectName = await registerRepo(repoPath, meta, {
+            name: options.registryName,
+            allowDuplicateName: options.allowDuplicateName,
+        });
+        if (hasGitDir(repoPath)) {
+            await addToGitignore(repoPath);
+        }
+        try {
+            await generateAIContextFiles(repoPath, storagePath, projectName, metaStatsForAIContext(meta.stats), undefined, { skipAgentsMd: options.skipAgentsMd, noStats: options.noStats });
+        }
+        catch {
+            // Best-effort only.
+        }
+        await closeCgdb();
+        progress('done', 100, 'Done');
+        return {
+            repoName: projectName,
+            repoPath,
+            stats: meta.stats ?? {},
+            pipelineResult,
+        };
+    }
+    catch (err) {
+        try {
+            await closeCgdb();
+        }
+        catch {
+            /* swallow */
+        }
+        throw err;
+    }
+};
 // ---------------------------------------------------------------------------
 // Main orchestrator
 // ---------------------------------------------------------------------------
@@ -274,6 +811,15 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     const repoHasGit = hasGitDir(repoPath);
     const currentCommit = repoHasGit ? getCurrentCommit(repoPath) : '';
     const existingMeta = await loadMeta(storagePath);
+    const adaptivePlan = resolveAdaptiveAnalyzePlan({
+        profile: options.profile,
+        embeddingMode: options.embeddingMode,
+        embeddings: options.embeddings,
+        compress: options.compress,
+        existingMeta,
+    });
+    const existingEmbeddingDecision = decideEmbeddingRun(adaptivePlan, existingMeta?.stats);
+    log(formatAdaptiveAnalyzePlan(adaptivePlan));
     // ── Early-return: already up to date ──────────────────────────────
     // Schema-version mismatch forces a full re-analyze regardless of commit
     // equality: existing 1.7.x indexes have no `schemaVersion` field at all,
@@ -288,7 +834,10 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         : null;
     const configRebuildReason = storageRebuildReason ??
         (existingMeta && schemaUpToDate && !options.force
-            ? getAnalyzeConfigRebuildReason(existingMeta, options)
+            ? getAnalyzeConfigRebuildReason(existingMeta, {
+                compress: adaptivePlan.compress,
+                embeddings: existingEmbeddingDecision.enabled,
+            })
             : null);
     if (existingMeta &&
         schemaUpToDate &&
@@ -297,8 +846,15 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         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,
@@ -327,8 +883,14 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
                 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 code, docs, config, or file structure.`;
+                    `file(s) did not affect indexed graph inputs.`;
                 log(reuseReason);
                 progress('done', 100, 'Existing graph reused');
                 return {
@@ -342,9 +904,39 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             }
             const preview = graphRelevantChanges.slice(0, 5).map(formatChangeForLog).join(', ');
             const suffix = graphRelevantChanges.length > 5 ? ', ...' : '';
-            log(`Smart analyze: ${graphRelevantChanges.length} indexed change(s) require rebuild` +
+            log(`Smart analyze: ${graphRelevantChanges.length} indexed graph input change(s) require rebuild` +
                 (preview ? ` (${preview}${suffix})` : '') +
                 '.');
+            const patchPlan = buildIncrementalFilePatchPlan(graphRelevantChanges);
+            if (patchPlan.eligible) {
+                log(`Smart analyze: ${patchPlan.reason}.`);
+                try {
+                    return await runIncrementalFilePatchAnalysis({
+                        repoPath,
+                        storagePath,
+                        cgdbPath,
+                        currentCommit,
+                        existingMeta,
+                        adaptivePlan,
+                        patchPlan,
+                        options,
+                        progress,
+                        log,
+                    });
+                }
+                catch (err) {
+                    log(`Smart analyze: incremental patch failed (${err instanceof Error ? err.message : String(err)}); rebuilding.`);
+                    try {
+                        await closeCgdb();
+                    }
+                    catch {
+                        /* swallow */
+                    }
+                }
+            }
+            else {
+                log(`Smart analyze: incremental patch unavailable: ${patchPlan.reason}; rebuilding.`);
+            }
         }
         else {
             log('Smart analyze: could not inspect git diff; rebuilding.');
@@ -358,7 +950,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     // ── Cache embeddings from existing index before rebuild ────────────
     let cachedEmbeddingNodeIds = new Set();
     let cachedEmbeddings = [];
-    if (options.embeddings && existingMeta && !options.force) {
+    if (existingEmbeddingDecision.enabled && existingMeta && !options.force) {
         try {
             progress('embeddings', 0, 'Caching embeddings...');
             await initCgdb(cgdbPath);
@@ -385,6 +977,8 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
     }, {
         featureClusterRepo: repoNameForFeatureClusters,
         lastIndexedCommit: currentCommit || undefined,
+        workerPoolSize: adaptivePlan.workerPoolSize,
+        workerSubBatchSize: adaptivePlan.workerSubBatchSize,
     });
     // ── Phase 2: LadybugDB (60–85%) ──────────────────────────────────
     progress('cgdb', 60, 'Loading into LadybugDB...');
@@ -413,7 +1007,7 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         // through encodeContent before hitting the CSV. Default 'none' is
         // a true passthrough, so the on-disk layout is byte-identical to
         // pre-Phase-2 indexes when no compression flag is passed.
-        { compress: options.compress });
+        { compress: adaptivePlan.compress });
         // ── Phase 2.5: Versioned-graph snapshot (best-effort) ────────────
         // Phase 4 hook: snapshot the freshly-loaded graph into the
         // content-addressed `.codragraph/graphstore/`. Failures here do NOT
@@ -441,12 +1035,15 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
             log(`graphstore: snapshot failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`);
         }
         // ── Phase 3: FTS (85–90%) ─────────────────────────────────────────
-        // FTS indexes are created lazily on first `query`/`context` call instead
-        // of eagerly here. On small repos / CI runners the LadybugDB
-        // CREATE_FTS_INDEX cost is ~440 ms × 5 (≈2 s) regardless of table size,
-        // which dominated `analyze` runtime and pushed Windows CI past its
-        // 30 s test budget. Lazy creation is implemented in
-        // `core/search/bm25-index.ts` via `ensureFTSIndex`.
+        // Build persisted keyword indexes while the analyzer still owns a writable
+        // LadybugDB handle. MCP/local query paths intentionally open read-only so
+        // they can coexist with editors and servers; if FTS is not warmed here,
+        // the first agent `query` degrades to a bounded table scan.
+        progress('fts', 85, 'Creating search indexes...');
+        const ftsProperties = [...ftsPropertiesFor(adaptivePlan.compress)];
+        for (const { table, indexName } of FTS_TABLES) {
+            await ensureFTSIndex(table, indexName, ftsProperties);
+        }
         // ── Phase 3.5: Re-insert cached embeddings ────────────────────────
         if (cachedEmbeddings.length > 0) {
             const cachedDims = cachedEmbeddings[0].embedding.length;
@@ -474,12 +1071,14 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         }
         // ── Phase 4: Embeddings (90–98%) ──────────────────────────────────
         const stats = await getCgdbStats();
-        let embeddingSkipped = true;
-        if (options.embeddings) {
-            if (stats.nodes <= EMBEDDING_NODE_LIMIT) {
-                embeddingSkipped = false;
-            }
-        }
+        const embeddingDecision = decideEmbeddingRun(adaptivePlan, {
+            nodes: stats.nodes,
+            embeddings: existingMeta?.stats?.embeddings ?? cachedEmbeddings.length,
+        });
+        const embeddingSkipped = !embeddingDecision.enabled;
+        log(embeddingDecision.enabled
+            ? `Embeddings enabled: ${embeddingDecision.reason}.`
+            : `Embeddings skipped: ${embeddingDecision.reason}.`);
         if (!embeddingSkipped) {
             const { isHttpMode } = await import('./embeddings/http-client.js');
             const httpMode = isHttpMode();
@@ -509,20 +1108,15 @@ export async function runFullAnalysis(repoPath, options, callbacks) {
         // ── Phase 5: Finalize (98–100%) ───────────────────────────────────
         progress('done', 98, 'Saving metadata...');
         // Count embeddings in the index (cached + newly generated)
-        let embeddingCount = 0;
-        try {
-            const embResult = await executeQuery(`MATCH (e:${EMBEDDING_TABLE_NAME}) RETURN count(e) AS cnt`);
-            embeddingCount = embResult?.[0]?.cnt ?? 0;
-        }
-        catch {
-            /* table may not exist if embeddings never ran */
-        }
+        const embeddingCount = await countEmbeddings();
         const meta = {
             repoPath,
             lastCommit: currentCommit,
             indexedAt: new Date().toISOString(),
             schemaVersion: INDEX_SCHEMA_VERSION,
-            compress: options.compress ?? 'none',
+            compress: adaptivePlan.compress,
+            searchIndexes: { fts: true },
+            adaptiveProfile: buildAdaptiveProfileMeta(adaptivePlan, embeddingDecision),
             // Captured here (not at registration) so it travels with the
             // on-disk meta.json — sibling-clone fingerprinting works for
             // out-of-tree consumers (group-status, future tooling) without