gitnexus 1.6.5-rc.8 → 1.6.5

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

@@ -11,40 +11,24 @@ import { getDefinitionNodeFromCaptures, findEnclosingClassInfo, getLabelFromCapt
 import { detectFrameworkFromAST } from './framework-detection.js';
 import { buildTypeEnv } from './type-env.js';
 import { buildMethodProps, arityForIdFromInfo, typeTagForId, constTagForId, buildCollisionGroups, } from './utils/method-props.js';
+import { extractTemplateArguments, templateArgumentsIdTag } from './utils/template-arguments.js';
 import { logger } from '../logger.js';
 import { getTreeSitterBufferSize, getTreeSitterContentByteLength, TREE_SITTER_MAX_BUFFER, } from './constants.js';
 // ============================================================================
 // Worker-based parallel parsing
 // ============================================================================
-const processParsingWithWorkers = async (graph, files, symbolTable, astCache, workerPool, onFileProgress) => {
-    // Filter to parseable files only
-    const parseableFiles = [];
-    for (const file of files) {
-        const lang = getLanguageFromFilename(file.path);
-        if (lang)
-            parseableFiles.push({ path: file.path, content: file.content });
-    }
-    if (parseableFiles.length === 0)
-        return {
-            imports: [],
-            calls: [],
-            assignments: [],
-            heritage: [],
-            routes: [],
-            fetchCalls: [],
-            decoratorRoutes: [],
-            toolDefs: [],
-            ormQueries: [],
-            constructorBindings: [],
-            fileScopeBindings: [],
-            parsedFiles: [],
-        };
-    const total = files.length;
-    // Dispatch to worker pool — pool handles splitting into chunks and sub-batching
-    const chunkResults = await workerPool.dispatch(parseableFiles, (filesProcessed) => {
-        onFileProgress?.(Math.min(filesProcessed, total), total, 'Parsing...');
-    });
-    // Merge results from all workers into graph and symbol table
+/**
+ * Merge a list of `ParseWorkerResult`s into the running graph + symbol
+ * table state and produce the chunk-aggregated `WorkerExtractedData`.
+ *
+ * Extracted from `processParsingWithWorkers` so the same merge logic can
+ * be applied to both freshly-parsed worker output AND cached worker
+ * output replayed during incremental analyze. Idempotent on the
+ * accumulator fields (push-only); idempotent on graph if the caller
+ * starts from a clean graph (otherwise duplicate `addNode` calls are
+ * silently no-op'd by `KnowledgeGraph`).
+ */
+export const mergeChunkResults = (graph, symbolTable, chunkResults) => {
     const allImports = [];
     const allCalls = [];
     const allAssignments = [];
@@ -75,6 +59,7 @@ const processParsingWithWorkers = async (graph, files, symbolTable, astCache, wo
                 parameterTypes: sym.parameterTypes,
                 returnType: sym.returnType,
                 declaredType: sym.declaredType,
+                templateArguments: sym.templateArguments,
                 ownerId: sym.ownerId,
                 qualifiedName: sym.qualifiedName,
             });
@@ -103,14 +88,70 @@ const processParsingWithWorkers = async (graph, files, symbolTable, astCache, wo
         if (result.fileScopeBindings)
             for (const item of result.fileScopeBindings)
                 fileScopeBindingsByFile.push(item);
-        // RFC #909 Ring 2: aggregate per-file scope artifacts. Tolerant of
-        // workers that don't emit the field yet (older worker builds or
-        // partial rollouts), since the additive contract means undefined =
-        // "this worker produced no ParsedFiles for this chunk".
         if (result.parsedFiles)
             for (const item of result.parsedFiles)
                 allParsedFiles.push(item);
     }
+    return {
+        imports: allImports,
+        calls: allCalls,
+        assignments: allAssignments,
+        heritage: allHeritage,
+        routes: allRoutes,
+        fetchCalls: allFetchCalls,
+        decoratorRoutes: allDecoratorRoutes,
+        toolDefs: allToolDefs,
+        ormQueries: allORMQueries,
+        constructorBindings: allConstructorBindings,
+        fileScopeBindings: fileScopeBindingsByFile,
+        parsedFiles: allParsedFiles,
+    };
+};
+const processParsingWithWorkers = async (graph, files, symbolTable, astCache, workerPool, onFileProgress, 
+/**
+ * When provided, populated with the raw worker results before merging.
+ * Used by the incremental-indexing parse cache to capture the per-chunk
+ * worker output for caching across runs. The mutation happens in-place
+ * so the caller (parse-impl) can keep a reference. See
+ * `gitnexus/src/storage/parse-cache.ts`.
+ */
+outRawResults) => {
+    // Filter to parseable files only
+    const parseableFiles = [];
+    for (const file of files) {
+        const lang = getLanguageFromFilename(file.path);
+        if (lang)
+            parseableFiles.push({ path: file.path, content: file.content });
+    }
+    if (parseableFiles.length === 0)
+        return {
+            imports: [],
+            calls: [],
+            assignments: [],
+            heritage: [],
+            routes: [],
+            fetchCalls: [],
+            decoratorRoutes: [],
+            toolDefs: [],
+            ormQueries: [],
+            constructorBindings: [],
+            fileScopeBindings: [],
+            parsedFiles: [],
+        };
+    const total = files.length;
+    // Dispatch to worker pool — pool handles splitting into chunks and sub-batching
+    const chunkResults = await workerPool.dispatch(parseableFiles, (filesProcessed) => {
+        onFileProgress?.(Math.min(filesProcessed, total), total, 'Parsing...');
+    });
+    // Capture the raw chunk results for the incremental parse cache before
+    // merging — the cache stores the unmerged worker output so a future run
+    // can re-merge them into a fresh graph state.
+    if (outRawResults) {
+        for (const r of chunkResults)
+            outRawResults.push(r);
+    }
+    // Merge results from all workers into graph and symbol table.
+    const merged = mergeChunkResults(graph, symbolTable, chunkResults);
     // Merge and log skipped languages from workers
     const skippedLanguages = new Map();
     for (const result of chunkResults) {
@@ -126,20 +167,7 @@ const processParsingWithWorkers = async (graph, files, symbolTable, astCache, wo
     }
     // Final progress
     onFileProgress?.(total, total, 'done');
-    return {
-        imports: allImports,
-        calls: allCalls,
-        assignments: allAssignments,
-        heritage: allHeritage,
-        routes: allRoutes,
-        fetchCalls: allFetchCalls,
-        decoratorRoutes: allDecoratorRoutes,
-        toolDefs: allToolDefs,
-        ormQueries: allORMQueries,
-        constructorBindings: allConstructorBindings,
-        fileScopeBindings: fileScopeBindingsByFile,
-        parsedFiles: allParsedFiles,
-    };
+    return merged;
 };
 // ============================================================================
 // Sequential fallback (original implementation)
@@ -339,6 +367,20 @@ const processParsingSequential = async (graph, files, symbolTable, astCache, sco
                 })
                 : null;
             const nodeLabel = extractedClassSymbol?.type ?? defaultNodeLabel;
+            const isClassLikeLabel = nodeLabel === 'Class' ||
+                nodeLabel === 'Struct' ||
+                nodeLabel === 'Interface' ||
+                nodeLabel === 'Enum' ||
+                nodeLabel === 'Record';
+            if (isClassLikeLabel &&
+                provider.classExtractor?.shouldSkipClassCapture?.({
+                    captureMap,
+                    definitionNode,
+                    nameNode,
+                    nodeLabel,
+                }) === true) {
+                return;
+            }
             // Synthesize name for constructors without explicit @name capture (e.g. Swift init)
             if (!nameNode && nodeLabel !== 'Constructor' && !extractedClassSymbol)
                 return;
@@ -438,7 +480,26 @@ const processParsingSequential = async (graph, files, symbolTable, astCache, sco
                 arityTag += typeTagForId(cached.map, nodeName, arityForId, seqDefMethodInfo, language, cached.groups);
                 arityTag += constTagForId(cached.map, nodeName, arityForId, seqDefMethodInfo, cached.groups);
             }
-            const nodeId = generateId(nodeLabel, `${file.path}:${qualifiedName}${arityTag}`);
+            const classTemplateArguments = extractedClassSymbol?.templateArguments ??
+                provider.classExtractor?.extractTemplateArgumentsFromCapture?.({
+                    captureMap,
+                    definitionNode,
+                    nameNode,
+                }) ??
+                (captureMap['template-arguments']
+                    ? extractTemplateArguments(captureMap['template-arguments'].text)
+                    : undefined) ??
+                (nameNode && nameNode.text ? extractTemplateArguments(nameNode.text) : undefined);
+            const classTemplateTag = (nodeLabel === 'Class' ||
+                nodeLabel === 'Struct' ||
+                nodeLabel === 'Interface' ||
+                nodeLabel === 'Enum' ||
+                nodeLabel === 'Record') &&
+                classTemplateArguments !== undefined &&
+                classTemplateArguments.length > 0
+                ? templateArgumentsIdTag(classTemplateArguments)
+                : '';
+            const nodeId = generateId(nodeLabel, `${file.path}:${qualifiedName}${classTemplateTag}${arityTag}`);
             const classNodeForSymbol = definitionNodeForRange || definitionNode || nameNode;
             const qualifiedTypeName = extractedClassSymbol?.qualifiedName ??
                 (classNodeForSymbol && provider.classExtractor?.isTypeDeclaration(classNodeForSymbol)
@@ -464,6 +525,9 @@ const processParsingSequential = async (graph, files, symbolTable, astCache, sco
                         ? isVueSetupTopLevel(nameNode || definitionNodeForRange)
                         : cachedExportCheck(provider.exportChecker, nameNode || definitionNodeForRange, nodeName),
                     ...(qualifiedTypeName !== undefined ? { qualifiedName: qualifiedTypeName } : {}),
+                    ...(classTemplateArguments !== undefined && classTemplateArguments.length > 0
+                        ? { templateArguments: classTemplateArguments }
+                        : {}),
                     ...(frameworkHint
                         ? {
                             astFrameworkMultiplier: frameworkHint.entryPointMultiplier,
@@ -517,6 +581,7 @@ const processParsingSequential = async (graph, files, symbolTable, astCache, sco
                 parameterTypes: methodProps.parameterTypes,
                 returnType: methodProps.returnType,
                 declaredType,
+                templateArguments: classTemplateArguments,
                 ownerId: enclosingClassId ?? undefined,
                 qualifiedName: qualifiedTypeName,
             });
@@ -562,7 +627,15 @@ export const processParsing = async (graph, files, symbolTable, astCache,
  * Worker-mode parses skip — Trees can't cross MessageChannels.
  * Pass `undefined` if no consumer needs cross-phase access.
  */
-scopeTreeCache, onFileProgress, workerPool) => {
+scopeTreeCache, onFileProgress, workerPool, 
+/**
+ * Optional out-parameter for the incremental parse cache. When
+ * provided AND the worker-pool path runs successfully, populated
+ * with the raw `ParseWorkerResult[]` from the workers (pre-merge).
+ * Stays empty for the sequential fallback path (no per-chunk
+ * artifact to cache there). See `gitnexus/src/storage/parse-cache.ts`.
+ */
+outRawResults) => {
     let lastProgress = 0;
     const reportProgress = onFileProgress
         ? (current, total, detail) => {
@@ -579,7 +652,7 @@ scopeTreeCache, onFileProgress, workerPool) => {
             logger.warn(`[scope-resolution prof] worker pool engaged for ${files.length} files — cross-phase tree cache will be empty; scope-resolution re-parses.`);
         }
         try {
-            return await processParsingWithWorkers(graph, files, symbolTable, astCache, workerPool, reportProgress);
+            return await processParsingWithWorkers(graph, files, symbolTable, astCache, workerPool, reportProgress, outRawResults);
         }
         catch (err) {
             const message = err instanceof Error ? err.message : String(err);

package/dist/core/ingestion/pipeline-phases/cross-file-impl.js

@@ -9,9 +9,10 @@
  */
 import { processCalls, buildImportedReturnTypes, buildImportedRawReturnTypes, } from '../call-processor.js';
 import { createASTCache } from '../ast-cache.js';
-import { getLanguageFromFilename } from '../../../_shared/index.js';
+import { getLanguageFromFilename, } from '../../../_shared/index.js';
 import { readFileContents } from '../filesystem-walker.js';
 import { isLanguageAvailable } from '../../tree-sitter/parser-loader.js';
+import { isRegistryPrimary } from '../registry-primary-flag.js';
 import { topologicalLevelSort } from '../utils/graph-sort.js';
 import { isDev } from '../utils/env.js';
 import { logger } from '../../logger.js';
@@ -88,6 +89,40 @@ export async function runCrossFileBindingPropagation(graph, ctx, parseExportedTy
     let crossFileResolved = 0;
     const crossFileStart = Date.now();
     const astCache = createASTCache(AST_CACHE_CAP);
+    // Compiled query objects keyed by language name. Shared across all processCalls
+    // invocations in this phase so the same tree-sitter query string is only
+    // compiled once per language instead of once per file (O(1) vs O(N)).
+    const compiledQueryCache = new Map();
+    // Snapshot total topological candidates for progress math.  We walk the
+    // levels once more here (fast — no I/O) so we can report meaningful
+    // percentages rather than a frozen display.
+    let totalCandidates = 0;
+    for (const level of levels) {
+        for (const filePath of level) {
+            if (totalCandidates >= MAX_CROSS_FILE_REPROCESS)
+                break;
+            const imports = ctx.namedImportMap.get(filePath);
+            if (!imports)
+                continue;
+            if (!allPathSet.has(filePath))
+                continue;
+            const lang = getLanguageFromFilename(filePath);
+            if (!lang || !isLanguageAvailable(lang))
+                continue;
+            // Registry-primary languages have their call resolution handled by the
+            // scope-resolution pipeline — processCalls skips them immediately. Skip
+            // here too so we avoid the I/O cost (readFileContents) and map-building
+            // overhead for files that would be no-ops anyway.
+            if (isRegistryPrimary(lang))
+                continue;
+            totalCandidates++;
+        }
+        if (totalCandidates >= MAX_CROSS_FILE_REPROCESS)
+            break;
+    }
+    const cappedTotal = Math.min(totalCandidates, MAX_CROSS_FILE_REPROCESS);
+    /** Emit a progress event every PROGRESS_INTERVAL files so the UI stays alive. */
+    const PROGRESS_INTERVAL = 25;
     for (const level of levels) {
         const levelCandidates = [];
         for (const filePath of level) {
@@ -114,6 +149,11 @@ export async function runCrossFileBindingPropagation(graph, ctx, parseExportedTy
             const lang = getLanguageFromFilename(filePath);
             if (!lang || !isLanguageAvailable(lang))
                 continue;
+            // Registry-primary languages have their call resolution handled by the
+            // scope-resolution pipeline — processCalls skips them immediately. Skip
+            // here to avoid readFileContents I/O and map-building for no-op files.
+            if (isRegistryPrimary(lang))
+                continue;
             levelCandidates.push({ filePath, seeded, importedReturns, importedRawReturns });
         }
         if (levelCandidates.length === 0)
@@ -136,8 +176,20 @@ export async function runCrossFileBindingPropagation(graph, ctx, parseExportedTy
             if (importedRawReturns.size > 0) {
                 importedRawReturnTypesMap.set(filePath, importedRawReturns);
             }
-            await processCalls(graph, reFile, astCache, ctx, undefined, exportedTypeMap, bindings.size > 0 ? bindings : undefined, importedReturnTypesMap.size > 0 ? importedReturnTypesMap : undefined, importedRawReturnTypesMap.size > 0 ? importedRawReturnTypesMap : undefined);
+            await processCalls(graph, reFile, astCache, ctx, undefined, exportedTypeMap, bindings.size > 0 ? bindings : undefined, importedReturnTypesMap.size > 0 ? importedReturnTypesMap : undefined, importedRawReturnTypesMap.size > 0 ? importedRawReturnTypesMap : undefined, undefined, undefined, compiledQueryCache);
             crossFileResolved++;
+            // Emit progress every PROGRESS_INTERVAL files so the UI shows real
+            // movement instead of a frozen display (cross-file can take minutes
+            // on large repos with many cross-file imports).
+            if (crossFileResolved % PROGRESS_INTERVAL === 0 || crossFileResolved === cappedTotal) {
+                const pct = cappedTotal > 0 ? Math.round((crossFileResolved / cappedTotal) * 8) : 0;
+                onProgress({
+                    phase: 'parsing',
+                    percent: 82 + pct,
+                    message: `Cross-file type propagation (${crossFileResolved}/${cappedTotal} files)...`,
+                    stats: { filesProcessed: crossFileResolved, totalFiles, nodesCreated: graph.nodeCount },
+                });
+            }
         }
         if (crossFileResolved >= MAX_CROSS_FILE_REPROCESS) {
             if (isDev)

package/dist/core/ingestion/pipeline-phases/parse-impl.d.ts

@@ -54,5 +54,10 @@ export declare function runChunkedParseAndResolve(graph: KnowledgeGraph, scanned
      *  source. See plan
      *  docs/plans/2026-04-20-002-perf-parse-heritage-mro-plan.md (Unit 4). */
     scopeTreeCache: ASTCache;
+    /** Worker-produced ParsedFile artifacts aggregated across chunks.
+     *  Threaded into scope-resolution as a re-extract cache so the warm-
+     *  cache analyze run can skip the dominant `extractParsedFile` cost
+     *  (otherwise ~58s on a 1000-file repo). */
+    parsedFiles: import('../../../_shared/index.js').ParsedFile[];
 }>;
 export {};

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

@@ -12,7 +12,8 @@
  * @module
  */
 import { BindingAccumulator, enrichExportedTypeMap, } from '../binding-accumulator.js';
-import { processParsing } from '../parsing-processor.js';
+import { processParsing, mergeChunkResults } from '../parsing-processor.js';
+import { fileContentHash, computeChunkHash } from '../../../storage/parse-cache.js';
 import { processImports, processImportsFromExtracted, buildImportResolutionContext, } from '../import-processor.js';
 import { EMPTY_INDEX } from '../import-resolvers/utils.js';
 import { processCalls, processCallsFromExtracted, processAssignmentsFromExtracted, processRoutesFromExtracted, seedCrossFileReceiverTypes, buildExportedTypeMapFromGraph, } from '../call-processor.js';
@@ -33,8 +34,22 @@ import { synthesizeWildcardImportBindings, needsSynthesis } from './wildcard-syn
 import { extractORMQueriesInline } from './orm-extraction.js';
 import { logger } from '../../logger.js';
 // ── Constants ──────────────────────────────────────────────────────────────
-/** Max bytes of source content to load per parse chunk. */
-const CHUNK_BYTE_BUDGET = 20 * 1024 * 1024; // 20MB
+/** Max bytes of source content to load per parse chunk.
+ *
+ * Memory bound for the worker pool dispatch + a granularity knob for
+ * the parse cache. A single file change invalidates only its enclosing
+ * chunk, so smaller budgets → finer-grained invalidation.
+ *
+ * Override via GITNEXUS_CHUNK_BYTE_BUDGET (bytes) — the default of 2MB
+ * gives a useful invalidation floor (~1/N chunks on a multi-MB repo)
+ * while keeping worker dispatch overhead under 5% on cold runs.
+ */
+const CHUNK_BYTE_BUDGET = (() => {
+    const env = Number(process.env.GITNEXUS_CHUNK_BYTE_BUDGET);
+    if (Number.isFinite(env) && env > 0)
+        return env;
+    return 2 * 1024 * 1024;
+})();
 /**
  * Chunked parse + resolve loop.
  *
@@ -64,6 +79,14 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
     for (const [lang, count] of skippedByLang) {
         logger.warn(`Skipping ${count} ${lang} file(s) — ${lang} parser not available (native binding may not have built). Try: npm rebuild tree-sitter-${lang}`);
     }
+    // Sort parseableScanned alphabetically for stable chunk membership
+    // across runs (Finding 4). Without this, filesystem-scan order can
+    // shift between runs (notably on macOS APFS where directory entry
+    // order can change after modifications) — different files in the
+    // same chunk → different chunk hash → cache miss even when no file
+    // content changed. The cache also becomes platform-specific: a
+    // Linux-built cache misses on macOS for the same repo.
+    parseableScanned.sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0));
     const totalParseable = parseableScanned.length;
     if (totalParseable === 0) {
         onProgress({
@@ -164,6 +187,19 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
     const deferredWorkerHeritage = [];
     const deferredConstructorBindings = [];
     const deferredAssignments = [];
+    // Aggregated per-file ParsedFile artifacts produced by workers' calls
+    // to `extractParsedFile`. Threaded through to the scope-resolution
+    // phase so it can SKIP its own re-extraction on cache hits — this is
+    // the second-half of the parse-cache speedup since scope-resolution's
+    // re-parse otherwise dominates the warm-cache wall-clock time.
+    const allParsedFiles = [];
+    // Incremental parse cache (Option B): chunk-level content-addressed.
+    // When the chunk's (filePath, content-hash) signature matches a prior
+    // run's, replay the cached ParseWorkerResult[] instead of dispatching
+    // to workers. See gitnexus/src/storage/parse-cache.ts.
+    const parseCache = options?.parseCache;
+    let chunkCacheHits = 0;
+    let chunkCacheMisses = 0;
     try {
         for (let chunkIdx = 0; chunkIdx < numChunks; chunkIdx++) {
             const chunkPaths = chunks[chunkIdx];
@@ -171,21 +207,76 @@ 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 chunkWorkerData = await processParsing(graph, chunkFiles, symbolTable, astCache, scopeTreeCache, (current, _total, filePath) => {
-                const globalCurrent = filesParsedSoFar + current;
-                const parsingProgress = 20 + (globalCurrent / totalParseable) * 62;
+            // Compute the chunk's content-hash signature (if cache available).
+            let chunkHash = null;
+            if (parseCache) {
+                const entries = chunkFiles.map((f) => ({
+                    filePath: f.path,
+                    contentHash: fileContentHash(f.content),
+                }));
+                chunkHash = computeChunkHash(entries);
+            }
+            let chunkWorkerData;
+            const cachedRaw = chunkHash ? parseCache.entries.get(chunkHash) : undefined;
+            // Track every chunk hash we touched so the orchestrator can
+            // prune stale entries (chunks whose composition no longer
+            // corresponds to a live chunk in the current scan) before saving.
+            if (parseCache && chunkHash)
+                parseCache.usedKeys.add(chunkHash);
+            if (cachedRaw && cachedRaw.length > 0) {
+                // Cache hit: replay the cached worker output through the same
+                // merge logic the live worker path uses.
+                chunkCacheHits++;
+                chunkWorkerData = mergeChunkResults(graph, symbolTable, cachedRaw);
+                if (isDev) {
+                    logger.info(`📦 parse-cache HIT: chunk ${chunkIdx + 1}/${numChunks} (${chunkFiles.length} files, ${chunkHash.slice(0, 8)})`);
+                }
+                // Progress update so UI advances even on a cache hit.
+                const cachedFiles = chunkFiles.length;
                 onProgress({
                     phase: 'parsing',
-                    percent: Math.round(parsingProgress),
-                    message: `Parsing chunk ${chunkIdx + 1}/${numChunks}...`,
-                    detail: filePath,
+                    percent: Math.round(20 + ((filesParsedSoFar + cachedFiles) / totalParseable) * 62),
+                    message: `Parsing chunk ${chunkIdx + 1}/${numChunks} (cache)...`,
                     stats: {
-                        filesProcessed: globalCurrent,
+                        filesProcessed: filesParsedSoFar + cachedFiles,
                         totalFiles: totalParseable,
                         nodesCreated: graph.nodeCount,
                     },
                 });
-            }, workerPool);
+            }
+            else {
+                // Cache miss: dispatch to workers, capture the raw results, store
+                // them under the chunk hash for the next run.
+                chunkCacheMisses++;
+                const rawResults = [];
+                chunkWorkerData = await processParsing(graph, chunkFiles, symbolTable, astCache, scopeTreeCache, (current, _total, filePath) => {
+                    const globalCurrent = filesParsedSoFar + current;
+                    const parsingProgress = 20 + (globalCurrent / totalParseable) * 62;
+                    onProgress({
+                        phase: 'parsing',
+                        percent: Math.round(parsingProgress),
+                        message: `Parsing chunk ${chunkIdx + 1}/${numChunks}...`,
+                        detail: filePath,
+                        stats: {
+                            filesProcessed: globalCurrent,
+                            totalFiles: totalParseable,
+                            nodesCreated: graph.nodeCount,
+                        },
+                    });
+                }, workerPool, 
+                // Capture raw results only when we have a cache to write to —
+                // otherwise we'd retain extra arrays for nothing.
+                parseCache && chunkHash ? rawResults : undefined);
+                // Persist the raw results for this chunk hash. Sequential path
+                // doesn't populate rawResults (it writes directly to graph), so
+                // small repos without worker pool simply don't cache. That's fine.
+                if (parseCache && chunkHash && rawResults.length > 0) {
+                    parseCache.entries.set(chunkHash, rawResults);
+                    if (isDev) {
+                        logger.info(`📦 parse-cache MISS+store: chunk ${chunkIdx + 1}/${numChunks} (${chunkFiles.length} files, ${chunkHash.slice(0, 8)})`);
+                    }
+                }
+            }
             const chunkBasePercent = 20 + (filesParsedSoFar / totalParseable) * 62;
             if (chunkWorkerData) {
                 await processImportsFromExtracted(graph, allPathObjects, chunkWorkerData.imports, ctx, (current, total) => {
@@ -217,6 +308,13 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
                     deferredWorkerHeritage.push(item);
                 for (const item of chunkWorkerData.constructorBindings)
                     deferredConstructorBindings.push(item);
+                // Aggregate worker-produced ParsedFile artifacts so scope-
+                // resolution can use them as a re-extraction cache (skips its
+                // own tree-sitter re-parse on warm runs).
+                if (chunkWorkerData.parsedFiles?.length) {
+                    for (const item of chunkWorkerData.parsedFiles)
+                        allParsedFiles.push(item);
+                }
                 if (chunkWorkerData.assignments?.length) {
                     for (const item of chunkWorkerData.assignments)
                         deferredAssignments.push(item);
@@ -297,6 +395,9 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
             filesParsedSoFar += chunkFiles.length;
             astCache.clear();
         }
+        if (isDev && parseCache && (chunkCacheHits > 0 || chunkCacheMisses > 0)) {
+            logger.info(`📦 parse-cache summary: ${chunkCacheHits} chunk hit(s), ${chunkCacheMisses} miss(es) across ${numChunks} chunk(s)`);
+        }
         const fullWorkerHeritageMap = deferredWorkerHeritage.length > 0
             ? buildHeritageMap(deferredWorkerHeritage, ctx, getHeritageStrategyForLanguage)
             : undefined;
@@ -455,5 +556,12 @@ export async function runChunkedParseAndResolve(graph, scannedFiles, allPaths, t
         // chunk-local `astCache` above is intentionally NOT exposed
         // because parse-impl clears it between chunks.
         scopeTreeCache,
+        // Per-file ParsedFile artifacts produced by workers' calls to
+        // `extractParsedFile`. Empty when only the sequential path ran
+        // (sequential doesn't go through the worker, and extracts ParsedFile
+        // inline rather than emitting it). Consumed by scope-resolution as
+        // a re-extraction cache: when the file's ParsedFile is here,
+        // scope-resolution skips its own `extractParsedFile` call.
+        parsedFiles: allParsedFiles,
     };
 }

package/dist/core/ingestion/pipeline-phases/parse.d.ts

@@ -17,6 +17,7 @@
  */
 import type { PipelinePhase } from './types.js';
 import type { BindingAccumulator } from '../binding-accumulator.js';
+import type { ParsedFile } from '../../../_shared/index.js';
 import type { ExtractedFetchCall, ExtractedRoute, ExtractedDecoratorRoute, ExtractedToolDef, ExtractedORMQuery } from '../workers/parse-worker.js';
 import type { createResolutionContext } from '../model/resolution-context.js';
 import type { ASTCache } from '../ast-cache.js';
@@ -70,5 +71,18 @@ export interface ParseOutput {
      * `scopeTreeCache.clear()` after its extract loop finishes.
      */
     readonly scopeTreeCache: ASTCache;
+    /**
+     * Per-file `ParsedFile` artifacts produced by workers' calls to
+     * `extractParsedFile`. Threaded through to `scopeResolutionPhase`
+     * as a re-extraction cache: when a file's ParsedFile is present here,
+     * scope-resolution can skip its own `extractParsedFile` (which would
+     * otherwise re-parse the file with tree-sitter on the main thread,
+     * costing ~58s on a 1000-file repo).
+     *
+     * Empty for files that went through the sequential parse fallback —
+     * sequential doesn't emit ParsedFile artifacts; scope-resolution
+     * falls back to a fresh extract for those.
+     */
+    readonly parsedFiles: readonly ParsedFile[];
 }
 export declare const parsePhase: PipelinePhase<ParseOutput>;

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

@@ -32,5 +32,18 @@ export interface PipelineOptions {
         minFiles?: number;
         minBytes?: number;
     };
+    /**
+     * Incremental-indexing parse cache. When provided:
+     *   - The parse phase looks up each chunk's content hash in
+     *     `parseCache.entries`. On hit, it replays the cached
+     *     `ParseWorkerResult[]` instead of dispatching to workers.
+     *   - On miss, it runs the workers as today and stores the new
+     *     results in `parseCache.entries` keyed by chunk hash.
+     * The caller (`run-analyze.ts`) is responsible for loading the cache
+     * before the pipeline runs and persisting it after. Cache survives
+     * `--force` because keys are content-addressed.
+     * See `gitnexus/src/storage/parse-cache.ts`.
+     */
+    parseCache?: import('../../storage/parse-cache.js').ParseCache;
 }
 export declare const runPipelineFromRepo: (repoPath: string, onProgress: (progress: PipelineProgress) => void, options?: PipelineOptions) => Promise<PipelineResult>;

package/dist/core/ingestion/registry-primary-flag.js

@@ -70,6 +70,8 @@ export const MIGRATED_LANGUAGES = new Set([
     SupportedLanguages.TypeScript,
     SupportedLanguages.Go,
     SupportedLanguages.C,
+    SupportedLanguages.CPlusPlus,
+    SupportedLanguages.PHP,
 ]);
 /**
  * Return the env-var name that controls a given language's registry-

package/dist/core/ingestion/scope-extractor.js

@@ -59,6 +59,7 @@
  *   - `ParsedFile.referenceSites` — pre-resolution usage facts.
  */
 import { buildPositionIndex, buildScopeTree, canParentScope, makeScopeId } from '../../_shared/index.js';
+import { extractTemplateArguments } from './utils/template-arguments.js';
 // ─── Public entry point ─────────────────────────────────────────────────────
 /**
  * Drive the five extraction passes and return a `ParsedFile`.
@@ -362,6 +363,8 @@ function buildDefFromDeclarationMatch(match, anchor, filePath) {
         return undefined;
     const qualifiedCap = match['@declaration.qualified_name'];
     const qualifiedName = qualifiedCap?.text;
+    const templateArguments = extractTemplateArguments(match['@declaration.template-arguments']?.text ?? '') ??
+        extractTemplateArguments(qualifiedName ?? nameCap.text);
     // Optional arity metadata — producers (e.g. Python emit-captures)
     // synthesize these on function/method declarations. Their absence is
     // the normal case for other producers; readers treat undefined as
@@ -381,6 +384,7 @@ function buildDefFromDeclarationMatch(match, anchor, filePath) {
         ...(parameterTypes !== undefined ? { parameterTypes } : {}),
         ...(declaredType !== undefined ? { declaredType } : {}),
         ...(returnType !== undefined ? { returnType } : {}),
+        ...(templateArguments !== undefined ? { templateArguments } : {}),
     };
 }
 function parseIntCapture(cap) {