@codragraph/cli 2.1.5 → 2.1.6

package/dist/core/cgdb/cgdb-adapter.d.ts

@@ -60,6 +60,37 @@ export declare const loadGraphToCgdb: (graph: KnowledgeGraph, repoPath: string,
     skippedRels: number;
     warnings: string[];
 }>;
+export interface FileGraphPatchResult {
+    replacedFiles: number;
+    deletedNodeIds: number;
+    insertedRels: number;
+    restoredRels: number;
+    prunedFolders: number;
+}
+export interface FileGraphPatchOptions {
+    compress?: ContentEncoding;
+    /** Map old relative paths to their new relative paths for rename remapping. */
+    pathAliases?: ReadonlyMap<string, string> | Record<string, string>;
+}
+export interface FileGraphReplacementResult {
+    deletedNodes: number;
+    insertedRels: number;
+}
+export interface GlobalGraphLayerReplaceResult {
+    deletedGlobalNodes: number;
+    insertedRels: number;
+}
+export interface LoadKnowledgeGraphFromCgdbOptions {
+    includeGlobal?: boolean;
+}
+export declare const applyFileGraphPatchToCgdb: (graph: KnowledgeGraph, repoPath: string, storagePath: string, filePaths: readonly string[], onProgress?: CgdbProgressCallback, options?: FileGraphPatchOptions) => Promise<FileGraphPatchResult>;
+export declare const replaceFileScopedGraphInCgdb: (graph: KnowledgeGraph, repoPath: string, storagePath: string, onProgress?: CgdbProgressCallback, options?: {
+    compress?: ContentEncoding;
+}) => Promise<FileGraphReplacementResult>;
+export declare const replaceGlobalGraphLayersInCgdb: (graph: KnowledgeGraph, repoPath: string, storagePath: string, onProgress?: CgdbProgressCallback, options?: {
+    compress?: ContentEncoding;
+}) => Promise<GlobalGraphLayerReplaceResult>;
+export declare const loadKnowledgeGraphFromCgdb: (options?: LoadKnowledgeGraphFromCgdbOptions) => Promise<KnowledgeGraph>;
 /**
  * Insert a single node to LadybugDB
  * @param label - Node type (File, Function, Class, etc.)
@@ -143,12 +174,10 @@ export declare const loadVectorExtension: () => Promise<void>;
  */
 export declare const createFTSIndex: (tableName: string, indexName: string, properties: string[], stemmer?: string) => Promise<void>;
 /**
- * Lazy-create an FTS index, caching the fact in-process.
+ * Create an FTS index if needed, caching the fact in-process.
  *
- * Used by `queryFTS` so that `analyze` doesn't pay the ~440 ms × 5 fixed
- * LadybugDB cost up-front (it dominates analyze on small repos). Instead,
- * the cost is moved to the first `query`/`context` call in a session,
- * where it's amortised across many lookups.
+ * Used by analyze to warm persisted keyword indexes while the DB is writable,
+ * and by direct core search as a defensive fallback for older indexes.
  *
  * Safe to call repeatedly — the in-process Set guarantees only the first
  * call hits LadybugDB. `closeCgdb` clears the cache so re-init starts fresh.

package/dist/core/cgdb/cgdb-adapter.js

@@ -5,6 +5,7 @@ import { once } from 'events';
 import { finished } from 'stream/promises';
 import path from 'path';
 import cgdb from '@ladybugdb/core';
+import { createKnowledgeGraph } from '../graph/graph.js';
 import { NODE_TABLES, REL_TABLE_NAME, SCHEMA_QUERIES, EMBEDDING_TABLE_NAME, STALE_HASH_SENTINEL, } from './schema.js';
 import { streamAllCSVsToDisk } from './csv-generator.js';
 /**
@@ -432,6 +433,419 @@ export const loadGraphToCgdb = async (graph, repoPath, storagePath, onProgress,
     catch { }
     return { success: true, insertedRels, skippedRels, warnings };
 };
+const FILE_SCOPED_NODE_TABLES = NODE_TABLES.filter((table) => table !== 'Community' && table !== 'Process' && table !== 'FeatureCluster');
+const GLOBAL_NODE_TABLES = new Set(['Community', 'Process', 'FeatureCluster']);
+const PRESERVABLE_OUTGOING_REL_TYPES = new Set([
+    'MEMBER_OF',
+    'STEP_IN_PROCESS',
+    'ENTRY_POINT_OF',
+    'FEATURE_MEMBER_OF',
+]);
+const rowString = (row, named, positional) => String(row[named] ?? row[positional] ?? '');
+const rowNumber = (row, named, positional, fallback) => {
+    const value = Number(row[named] ?? row[positional] ?? fallback);
+    return Number.isFinite(value) ? value : fallback;
+};
+const nodeLabelForId = (nodeId) => {
+    if (nodeId.startsWith('comm_'))
+        return 'Community';
+    if (nodeId.startsWith('proc_'))
+        return 'Process';
+    return nodeId.split(':')[0] || 'CodeElement';
+};
+const fileScopedNodeSignature = (label, name, filePath) => {
+    if (!name || !filePath)
+        return null;
+    return `${label}\0${name}\0${filePath}`;
+};
+const normalizePathAliases = (aliases) => {
+    if (!aliases)
+        return new Map();
+    if (aliases instanceof Map) {
+        return new Map([...aliases].map(([from, to]) => [from.replace(/\\/g, '/'), to.replace(/\\/g, '/')]));
+    }
+    return new Map(Object.entries(aliases).map(([from, to]) => [
+        from.replace(/\\/g, '/'),
+        String(to).replace(/\\/g, '/'),
+    ]));
+};
+const remapFilePath = (filePath, aliases) => {
+    const normalized = filePath.replace(/\\/g, '/');
+    return aliases.get(normalized) ?? normalized;
+};
+const collectNodeIdsForFiles = async (filePaths) => {
+    const nodeIds = new Set();
+    if (filePaths.length === 0)
+        return nodeIds;
+    for (const table of FILE_SCOPED_NODE_TABLES) {
+        for (const filePath of filePaths) {
+            try {
+                const rows = await executePrepared(`MATCH (n:${escapeTableName(table)}) WHERE n.filePath = $filePath RETURN n.id AS id`, { filePath });
+                for (const row of rows) {
+                    const id = rowString(row, 'id', 0);
+                    if (id)
+                        nodeIds.add(id);
+                }
+            }
+            catch {
+                /* table may be absent in old indexes */
+            }
+        }
+    }
+    return nodeIds;
+};
+const buildPatchNodeLookup = (graph, filePaths) => {
+    const ids = new Set();
+    const signatureBuckets = new Map();
+    for (const node of graph.iterNodes()) {
+        const filePath = node.properties?.filePath;
+        if (typeof filePath === 'string' && filePaths.has(filePath)) {
+            ids.add(node.id);
+            const signature = fileScopedNodeSignature(node.label, typeof node.properties?.name === 'string' ? node.properties.name : undefined, filePath);
+            if (signature) {
+                let bucket = signatureBuckets.get(signature);
+                if (bucket === undefined) {
+                    bucket = new Set();
+                    signatureBuckets.set(signature, bucket);
+                }
+                bucket.add(node.id);
+            }
+        }
+    }
+    const signatureToId = new Map();
+    for (const [signature, nodeIds] of signatureBuckets) {
+        if (nodeIds.size === 1) {
+            signatureToId.set(signature, [...nodeIds][0]);
+        }
+    }
+    return { ids, signatureToId };
+};
+const prunePatchGraphRelationships = (graph, patchNodeIds) => {
+    for (const rel of [...graph.iterRelationships()]) {
+        if (!patchNodeIds.has(rel.sourceId) && !patchNodeIds.has(rel.targetId)) {
+            graph.removeRelationship(rel.id);
+        }
+    }
+};
+const collectPreservedRelationships = async (oldNodeIds) => {
+    const preserved = [];
+    for (const nodeId of oldNodeIds) {
+        try {
+            const incoming = await executePrepared(`MATCH (a)-[r:${REL_TABLE_NAME}]->(b) WHERE b.id = $nodeId RETURN a.id AS sourceId, b.id AS targetId, r.type AS type, r.confidence AS confidence, r.reason AS reason, r.step AS step, a.name AS sourceName, a.filePath AS sourceFilePath, b.name AS targetName, b.filePath AS targetFilePath`, { nodeId });
+            for (const row of incoming) {
+                const sourceId = rowString(row, 'sourceId', 0);
+                const targetId = rowString(row, 'targetId', 1);
+                if (!sourceId || !targetId || oldNodeIds.has(sourceId))
+                    continue;
+                preserved.push({
+                    sourceId,
+                    targetId,
+                    type: rowString(row, 'type', 2),
+                    confidence: rowNumber(row, 'confidence', 3, 1),
+                    reason: rowString(row, 'reason', 4),
+                    step: rowNumber(row, 'step', 5, 0),
+                    sourceName: rowString(row, 'sourceName', 6),
+                    sourceFilePath: rowString(row, 'sourceFilePath', 7),
+                    targetName: rowString(row, 'targetName', 8),
+                    targetFilePath: rowString(row, 'targetFilePath', 9),
+                });
+            }
+        }
+        catch {
+            /* best-effort preservation */
+        }
+        try {
+            const outgoing = await executePrepared(`MATCH (a)-[r:${REL_TABLE_NAME}]->(b) WHERE a.id = $nodeId RETURN a.id AS sourceId, b.id AS targetId, r.type AS type, r.confidence AS confidence, r.reason AS reason, r.step AS step, a.name AS sourceName, a.filePath AS sourceFilePath, b.name AS targetName, b.filePath AS targetFilePath`, { nodeId });
+            for (const row of outgoing) {
+                const sourceId = rowString(row, 'sourceId', 0);
+                const targetId = rowString(row, 'targetId', 1);
+                const type = rowString(row, 'type', 2);
+                if (!sourceId ||
+                    !targetId ||
+                    oldNodeIds.has(targetId) ||
+                    !PRESERVABLE_OUTGOING_REL_TYPES.has(type)) {
+                    continue;
+                }
+                preserved.push({
+                    sourceId,
+                    targetId,
+                    type,
+                    confidence: rowNumber(row, 'confidence', 3, 1),
+                    reason: rowString(row, 'reason', 4),
+                    step: rowNumber(row, 'step', 5, 0),
+                    sourceName: rowString(row, 'sourceName', 6),
+                    sourceFilePath: rowString(row, 'sourceFilePath', 7),
+                    targetName: rowString(row, 'targetName', 8),
+                    targetFilePath: rowString(row, 'targetFilePath', 9),
+                });
+            }
+        }
+        catch {
+            /* best-effort preservation */
+        }
+    }
+    return preserved;
+};
+const deleteEmbeddingsForNodeIds = async (nodeIds) => {
+    await executeWithReusedStatement(`MATCH (e:${EMBEDDING_TABLE_NAME} {nodeId: $nodeId}) DELETE e`, [...nodeIds].map((nodeId) => ({ nodeId })));
+};
+const deleteFileScopedNodes = async (filePaths) => {
+    for (const table of FILE_SCOPED_NODE_TABLES) {
+        for (const filePath of filePaths) {
+            try {
+                await executePrepared(`MATCH (n:${escapeTableName(table)}) WHERE n.filePath = $filePath DETACH DELETE n`, { filePath });
+            }
+            catch (err) {
+                if (!isMissingColumnOrTableError(err instanceof Error ? err.message : String(err))) {
+                    throw err;
+                }
+                /* table may be absent in old indexes */
+            }
+        }
+    }
+};
+const restorePreservedRelationships = async (relationships, patchLookup, pathAliases) => {
+    let restored = 0;
+    const seen = new Set();
+    for (const rel of relationships) {
+        const sourceSignature = fileScopedNodeSignature(nodeLabelForId(rel.sourceId), rel.sourceName, remapFilePath(rel.sourceFilePath, pathAliases));
+        const targetSignature = fileScopedNodeSignature(nodeLabelForId(rel.targetId), rel.targetName, remapFilePath(rel.targetFilePath, pathAliases));
+        const resolvedSourceId = (patchLookup.ids.has(rel.sourceId) ? rel.sourceId : undefined) ??
+            (sourceSignature ? patchLookup.signatureToId.get(sourceSignature) : undefined) ??
+            rel.sourceId;
+        const resolvedTargetId = (patchLookup.ids.has(rel.targetId) ? rel.targetId : undefined) ??
+            (targetSignature ? patchLookup.signatureToId.get(targetSignature) : undefined) ??
+            rel.targetId;
+        const patchSideSurvives = patchLookup.ids.has(resolvedSourceId) || patchLookup.ids.has(resolvedTargetId);
+        if (!patchSideSurvives)
+            continue;
+        const key = `${resolvedSourceId}\0${rel.type}\0${resolvedTargetId}\0${rel.step}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        const sourceLabel = escapeTableName(nodeLabelForId(resolvedSourceId));
+        const targetLabel = escapeTableName(nodeLabelForId(resolvedTargetId));
+        try {
+            const existingRows = await executePrepared(`MATCH (a:${sourceLabel})-[r:${REL_TABLE_NAME}]->(b:${targetLabel}) WHERE a.id = $sourceId AND b.id = $targetId AND r.type = $type AND r.step = $step RETURN count(r) AS cnt`, { ...rel, sourceId: resolvedSourceId, targetId: resolvedTargetId });
+            const existing = rowNumber(existingRows?.[0] ?? {}, 'cnt', 0, 0);
+            if (existing > 0)
+                continue;
+            await executePrepared(`MATCH (a:${sourceLabel} {id: $sourceId}), (b:${targetLabel} {id: $targetId}) CREATE (a)-[:${REL_TABLE_NAME} {type: $type, confidence: $confidence, reason: $reason, step: $step}]->(b)`, { ...rel, sourceId: resolvedSourceId, targetId: resolvedTargetId });
+            restored++;
+        }
+        catch {
+            /* source or target disappeared; skip */
+        }
+    }
+    return restored;
+};
+export const applyFileGraphPatchToCgdb = async (graph, repoPath, storagePath, filePaths, onProgress, options) => {
+    if (!conn) {
+        throw new Error('LadybugDB not initialized. Call initCgdb first.');
+    }
+    const normalizedFiles = [...new Set(filePaths.map((p) => p.replace(/\\/g, '/')))];
+    const pathAliases = normalizePathAliases(options?.pathAliases);
+    const patchFileSet = new Set(normalizedFiles);
+    const oldNodeIds = await collectNodeIdsForFiles(normalizedFiles);
+    const preservedRels = await collectPreservedRelationships(oldNodeIds);
+    await loadFTSExtension();
+    await deleteEmbeddingsForNodeIds(oldNodeIds);
+    await deleteFileScopedNodes(normalizedFiles);
+    const patchLookup = buildPatchNodeLookup(graph, patchFileSet);
+    prunePatchGraphRelationships(graph, patchLookup.ids);
+    const loadResult = graph.nodeCount > 0
+        ? await loadGraphToCgdb(graph, repoPath, storagePath, onProgress, options)
+        : { insertedRels: 0 };
+    const restoredRels = await restorePreservedRelationships(preservedRels, patchLookup, pathAliases);
+    const prunedFolders = await pruneEmptyFoldersFromCgdb();
+    return {
+        replacedFiles: normalizedFiles.length,
+        deletedNodeIds: oldNodeIds.size,
+        insertedRels: loadResult.insertedRels,
+        restoredRels,
+        prunedFolders,
+    };
+};
+const deleteEmbeddingsForAllNodes = async () => {
+    try {
+        await executeQuery(`MATCH (e:${EMBEDDING_TABLE_NAME}) DELETE e`);
+    }
+    catch {
+        /* table may be absent in old indexes */
+    }
+};
+const deleteAllFileScopedNodes = async () => {
+    let deleted = 0;
+    for (const table of FILE_SCOPED_NODE_TABLES) {
+        try {
+            const rows = await executeQuery(`MATCH (n:${escapeTableName(table)}) RETURN count(n) AS cnt`);
+            deleted += Number(rows?.[0]?.cnt ?? rows?.[0]?.[0] ?? 0);
+        }
+        catch (err) {
+            if (!isMissingColumnOrTableError(err instanceof Error ? err.message : String(err))) {
+                throw err;
+            }
+            /* table may be absent in old indexes */
+        }
+        try {
+            await executeQuery(`MATCH (n:${escapeTableName(table)}) DETACH DELETE n`);
+        }
+        catch (err) {
+            if (!isMissingColumnOrTableError(err instanceof Error ? err.message : String(err))) {
+                throw err;
+            }
+            /* table may be absent in old indexes */
+        }
+    }
+    return deleted;
+};
+export const replaceFileScopedGraphInCgdb = async (graph, repoPath, storagePath, onProgress, options) => {
+    if (!conn) {
+        throw new Error('LadybugDB not initialized. Call initCgdb first.');
+    }
+    await loadFTSExtension();
+    await deleteEmbeddingsForAllNodes();
+    const deletedNodes = await deleteAllFileScopedNodes();
+    const loadResult = graph.nodeCount > 0
+        ? await loadGraphToCgdb(graph, repoPath, storagePath, onProgress, options)
+        : { insertedRels: 0 };
+    return { deletedNodes, insertedRels: loadResult.insertedRels };
+};
+export const replaceGlobalGraphLayersInCgdb = async (graph, repoPath, storagePath, onProgress, options) => {
+    if (!conn) {
+        throw new Error('LadybugDB not initialized. Call initCgdb first.');
+    }
+    await loadFTSExtension();
+    let deletedGlobalNodes = 0;
+    for (const table of GLOBAL_NODE_TABLES) {
+        try {
+            const rows = await executeQuery(`MATCH (n:${escapeTableName(table)}) RETURN count(n) AS cnt`);
+            deletedGlobalNodes += Number(rows?.[0]?.cnt ?? rows?.[0]?.[0] ?? 0);
+        }
+        catch {
+            /* table may be absent in old indexes */
+        }
+        try {
+            await executeQuery(`MATCH (n:${escapeTableName(table)}) DETACH DELETE n`);
+        }
+        catch {
+            /* table may be absent in old indexes */
+        }
+    }
+    const loadResult = graph.nodeCount > 0
+        ? await loadGraphToCgdb(graph, repoPath, storagePath, onProgress, options)
+        : { insertedRels: 0 };
+    return { deletedGlobalNodes, insertedRels: loadResult.insertedRels };
+};
+const unwrapNodeResult = (raw) => {
+    if (!raw || typeof raw !== 'object')
+        return null;
+    const row = raw;
+    const candidate = row.n ?? row[0];
+    return candidate && typeof candidate === 'object' && !Array.isArray(candidate)
+        ? candidate
+        : null;
+};
+const nodePropertiesFromCgdbRow = (row) => {
+    const properties = {
+        name: String(row.name ?? ''),
+        filePath: String(row.filePath ?? ''),
+    };
+    for (const [key, value] of Object.entries(row)) {
+        if (key === 'id' || key === '_id' || key === '_label')
+            continue;
+        properties[key] = value;
+    }
+    return properties;
+};
+export const loadKnowledgeGraphFromCgdb = async (options = {}) => {
+    if (!conn) {
+        throw new Error('LadybugDB not initialized. Call initCgdb first.');
+    }
+    const includeGlobal = options.includeGlobal ?? false;
+    const graph = createKnowledgeGraph();
+    for (const table of NODE_TABLES) {
+        if (!includeGlobal && GLOBAL_NODE_TABLES.has(table))
+            continue;
+        try {
+            const rows = await executeQuery(`MATCH (n:${escapeTableName(table)}) RETURN n`);
+            for (const raw of rows) {
+                const node = unwrapNodeResult(raw);
+                const id = node ? String(node.id ?? '') : '';
+                if (!node || !id)
+                    continue;
+                graph.addNode({
+                    id,
+                    label: table,
+                    properties: nodePropertiesFromCgdbRow(node),
+                });
+            }
+        }
+        catch {
+            /* table may be absent in old indexes */
+        }
+    }
+    try {
+        const rows = await executeQuery(`MATCH (a)-[r:${REL_TABLE_NAME}]->(b) RETURN a.id AS sourceId, b.id AS targetId, r.type AS type, r.confidence AS confidence, r.reason AS reason, r.step AS step`);
+        let relIndex = 0;
+        for (const row of rows) {
+            const sourceId = rowString(row, 'sourceId', 0);
+            const targetId = rowString(row, 'targetId', 1);
+            if (!sourceId || !targetId)
+                continue;
+            if (!includeGlobal) {
+                const sourceLabel = nodeLabelForId(sourceId);
+                const targetLabel = nodeLabelForId(targetId);
+                if (GLOBAL_NODE_TABLES.has(sourceLabel) || GLOBAL_NODE_TABLES.has(targetLabel))
+                    continue;
+            }
+            const type = rowString(row, 'type', 2);
+            graph.addRelationship({
+                id: `cgdb:${relIndex++}:${sourceId}->${type}->${targetId}`,
+                sourceId,
+                targetId,
+                type: type,
+                confidence: rowNumber(row, 'confidence', 3, 1),
+                reason: rowString(row, 'reason', 4),
+                step: rowNumber(row, 'step', 5, 0),
+            });
+        }
+    }
+    catch {
+        /* relationships may be absent in old indexes */
+    }
+    return graph;
+};
+const pruneEmptyFoldersFromCgdb = async () => {
+    let folderRows = [];
+    let fileRows = [];
+    try {
+        folderRows = await executeQuery('MATCH (f:Folder) RETURN f.id AS id, f.filePath AS filePath');
+        fileRows = await executeQuery('MATCH (f:File) RETURN f.filePath AS filePath');
+    }
+    catch {
+        return 0;
+    }
+    const filePaths = fileRows.map((row) => rowString(row, 'filePath', 0)).filter(Boolean);
+    let pruned = 0;
+    for (const row of folderRows) {
+        const id = rowString(row, 'id', 0);
+        const folderPath = rowString(row, 'filePath', 1);
+        if (!id || !folderPath)
+            continue;
+        const hasDescendantFile = filePaths.some((filePath) => filePath.startsWith(`${folderPath}/`));
+        if (hasDescendantFile)
+            continue;
+        try {
+            await executePrepared('MATCH (f:Folder {id: $id}) DETACH DELETE f', { id });
+            pruned++;
+        }
+        catch {
+            /* best-effort cleanup */
+        }
+    }
+    return pruned;
+};
 // LadybugDB default ESCAPE is '\' (backslash), but our CSV uses RFC 4180 escaping ("" for literal quotes).
 // Source code content is full of backslashes which confuse the auto-detection.
 // We MUST explicitly set ESCAPE='"' to use RFC 4180 escaping, and disable auto_detect to prevent
@@ -1254,12 +1668,10 @@ export const createFTSIndex = async (tableName, indexName, properties, stemmer =
     }
 };
 /**
- * Lazy-create an FTS index, caching the fact in-process.
+ * Create an FTS index if needed, caching the fact in-process.
  *
- * Used by `queryFTS` so that `analyze` doesn't pay the ~440 ms × 5 fixed
- * LadybugDB cost up-front (it dominates analyze on small repos). Instead,
- * the cost is moved to the first `query`/`context` call in a session,
- * where it's amortised across many lookups.
+ * Used by analyze to warm persisted keyword indexes while the DB is writable,
+ * and by direct core search as a defensive fallback for older indexes.
  *
  * Safe to call repeatedly — the in-process Set guarantees only the first
  * call hits LadybugDB. `closeCgdb` clears the cache so re-init starts fresh.
@@ -1327,6 +1739,7 @@ export const dropFTSIndex = async (tableName, indexName) => {
     if (!conn) {
         throw new Error('LadybugDB not initialized. Call initCgdb first.');
     }
+    await loadFTSExtension();
     try {
         await conn.query(`CALL DROP_FTS_INDEX('${tableName}', '${indexName}')`);
     }

package/dist/core/cgdb/pool-adapter.js

@@ -586,7 +586,7 @@ function isBenignLabelScanError(error) {
     const message = error.message.toLowerCase();
     return (message.includes('cannot find property') ||
         message.includes('does not have property') ||
-        message.includes('property') && message.includes('not found'));
+        (message.includes('property') && message.includes('not found')));
 }
 export const executeQuery = async (repoId, cypher) => {
     const entry = pool.get(repoId);

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

@@ -119,7 +119,9 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                     workerUrl = pathToFileURL(distWorker);
                 }
             }
-            workerPool = createWorkerPool(workerUrl);
+            workerPool = createWorkerPool(workerUrl, options?.workerPoolSize, {
+                subBatchSize: options?.workerSubBatchSize,
+            });
         }
         catch (err) {
             console.warn('Worker pool creation failed, using sequential fallback:', err.message);

package/dist/core/ingestion/pipeline-phases/structure.js

@@ -20,16 +20,32 @@ export const structurePhase = {
             message: 'Analyzing project structure...',
             stats: { filesProcessed: 0, totalFiles, nodesCreated: ctx.graph.nodeCount },
         });
-        processStructure(ctx.graph, allPaths);
+        const focusSet = ctx.options?.focusPaths
+            ? new Set(ctx.options.focusPaths.map((p) => p.replace(/\\/g, '/')))
+            : null;
+        const graphPaths = focusSet ? allPaths.filter((p) => focusSet.has(p)) : allPaths;
+        processStructure(ctx.graph, graphPaths);
         ctx.onProgress({
             phase: 'structure',
             percent: 20,
             message: 'Project structure analyzed',
-            stats: { filesProcessed: totalFiles, totalFiles, nodesCreated: ctx.graph.nodeCount },
+            stats: {
+                filesProcessed: graphPaths.length,
+                totalFiles: focusSet ? graphPaths.length : totalFiles,
+                nodesCreated: ctx.graph.nodeCount,
+            },
         });
         // Build the set once here so cobol, markdown, and cross-file propagation
         // can all reuse it instead of re-materializing `new Set(allPaths)` each.
         const allPathSet = new Set(allPaths);
-        return { scannedFiles, allPaths, allPathSet, totalFiles };
+        const focusedScannedFiles = focusSet
+            ? scannedFiles.filter((f) => focusSet.has(f.path))
+            : scannedFiles;
+        return {
+            scannedFiles: focusedScannedFiles,
+            allPaths,
+            allPathSet,
+            totalFiles: focusSet ? focusedScannedFiles.length : totalFiles,
+        };
     },
 };

package/dist/core/ingestion/pipeline.d.ts

@@ -25,6 +25,16 @@ export interface PipelineOptions {
     featureClusterRepo?: string;
     /** Indexed source commit written onto FeatureCluster metadata. */
     lastIndexedCommit?: string;
+    /**
+     * Optional focused indexing set for incremental file analysis. The walker
+     * still scans the repo so import resolution sees every path, but graph
+     * writes and content parsing are limited to these relative paths.
+     */
+    focusPaths?: readonly string[];
+    /** Adaptive analyze worker pool size. */
+    workerPoolSize?: number;
+    /** Adaptive analyze max files per worker message. */
+    workerSubBatchSize?: number;
     /**
      * @internal Test-only override for worker-pool gating thresholds.
      * When unset, production defaults apply (15 files OR 512 KB total bytes).

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

@@ -10,6 +10,7 @@
  */
 import { type RepoMeta } from '../storage/repo-manager.js';
 import type { ContentEncoding } from '@codragraph/graphstore';
+import { type AnalyzeProfileOption, type CompressionOption, type EmbeddingMode } from './adaptive-profile.js';
 export interface AnalyzeCallbacks {
     onProgress: (phase: string, percent: number, message: string) => void;
     onLog?: (message: string) => void;
@@ -23,6 +24,8 @@ export interface AnalyzeOptions {
      */
     force?: boolean;
     embeddings?: boolean;
+    profile?: AnalyzeProfileOption;
+    embeddingMode?: EmbeddingMode;
     skipGit?: boolean;
     /** Skip AGENTS.md and CLAUDE.md codragraph block updates. */
     skipAgentsMd?: boolean;
@@ -54,7 +57,7 @@ export interface AnalyzeOptions {
      * that wrote the rows). Readers on older Node will get a clear
      * forward-compat error rather than silently bad content.
      */
-    compress?: ContentEncoding;
+    compress?: CompressionOption;
 }
 export interface AnalyzeResult {
     repoName: string;
@@ -91,7 +94,29 @@ 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;
+export interface IncrementalFilePatchPlan {
+    eligible: boolean;
+    reason: string;
+    replacePaths: string[];
+    currentPaths: string[];
+    fileCountDelta: number;
+    /**
+     * True when a change can affect resolver/global structure broadly
+     * (config/ignore/package). The incremental path still avoids deleting the
+     * whole DB, but it replaces every file-scoped node from a fresh full scan.
+     */
+    replaceAllFileScoped: boolean;
+    /** Old path -> new path aliases used to reconnect external edges across renames. */
+    pathAliases: Record<string, string>;
+}
+export declare const isPatchableIncrementalPath: (filePath: string) => boolean;
+export declare const buildIncrementalFilePatchPlan: (changes: readonly AnalyzeChangedPath[], _options?: {
+    limit?: number;
+}) => IncrementalFilePatchPlan;
+export declare const getAnalyzeConfigRebuildReason: (existingMeta: Pick<RepoMeta, "compress" | "searchIndexes" | "stats">, options: {
+    compress?: ContentEncoding;
+    embeddings?: boolean;
+}) => string | null;
 /**
  * Run the full CodraGraph analysis pipeline.
  *