gitnexus 1.6.0 → 1.6.1

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

@@ -74,30 +74,30 @@ const processParsingWithWorkers = async (graph, files, symbolTable, astCache, wo
                 qualifiedName: sym.qualifiedName,
             });
         }
-        for (const _item of result.imports)
-            allImports.push(_item);
-        for (const _item of result.calls)
-            allCalls.push(_item);
-        for (const _item of result.assignments)
-            allAssignments.push(_item);
-        for (const _item of result.heritage)
-            allHeritage.push(_item);
-        for (const _item of result.routes)
-            allRoutes.push(_item);
-        for (const _item of result.fetchCalls)
-            allFetchCalls.push(_item);
-        for (const _item of result.decoratorRoutes)
-            allDecoratorRoutes.push(_item);
-        for (const _item of result.toolDefs)
-            allToolDefs.push(_item);
+        for (const item of result.imports)
+            allImports.push(item);
+        for (const item of result.calls)
+            allCalls.push(item);
+        for (const item of result.assignments)
+            allAssignments.push(item);
+        for (const item of result.heritage)
+            allHeritage.push(item);
+        for (const item of result.routes)
+            allRoutes.push(item);
+        for (const item of result.fetchCalls)
+            allFetchCalls.push(item);
+        for (const item of result.decoratorRoutes)
+            allDecoratorRoutes.push(item);
+        for (const item of result.toolDefs)
+            allToolDefs.push(item);
         if (result.ormQueries)
-            for (const _item of result.ormQueries)
-                allORMQueries.push(_item);
-        for (const _item of result.constructorBindings)
-            allConstructorBindings.push(_item);
+            for (const item of result.ormQueries)
+                allORMQueries.push(item);
+        for (const item of result.constructorBindings)
+            allConstructorBindings.push(item);
         if (result.fileScopeBindings)
-            for (const _item of result.fileScopeBindings)
-                fileScopeBindingsByFile.push(_item);
+            for (const item of result.fileScopeBindings)
+                fileScopeBindingsByFile.push(item);
     }
     // Merge and log skipped languages from workers
     const skippedLanguages = new Map();
@@ -135,11 +135,11 @@ const processParsingWithWorkers = async (graph, files, symbolTable, astCache, wo
 // Keyed by tree-sitter node reference — cleared at the start of each file.
 const classInfoCache = new Map();
 const exportCache = new Map();
-const cachedFindEnclosingClassInfo = (node, filePath) => {
+const cachedFindEnclosingClassInfo = (node, filePath, resolveEnclosingOwner) => {
     const cached = classInfoCache.get(node);
     if (cached !== undefined)
         return cached;
-    const result = findEnclosingClassInfo(node, filePath);
+    const result = findEnclosingClassInfo(node, filePath, resolveEnclosingOwner);
     classInfoCache.set(node, result);
     return result;
 };
@@ -158,24 +158,34 @@ const seqFieldInfoCache = new Map();
 const seqMethodExtractCache = new Map();
 // Derived method map + collision groups cache — avoids rebuilding per method.
 const seqMethodMapCache = new Map();
-function seqFindEnclosingClassNode(node) {
+/** Provider-aware enclosing container lookup.
+ *  Walks up from `node` until a CLASS_CONTAINER_TYPES node is found.
+ *  When `resolveEnclosingOwner` is provided, delegates language-specific
+ *  container remapping (e.g., Ruby singleton_class → enclosing class).
+ *  Without the hook, returns the first matching container directly (raw lookup). */
+function seqFindEnclosingOwnerNode(node, resolveEnclosingOwner) {
     let current = node.parent;
     while (current) {
         if (CLASS_CONTAINER_TYPES.has(current.type)) {
-            // Return singleton_class directly so the method extractor sees it as
-            // the owner node and correctly marks methods as static. Name resolution
-            // for qualified names is handled separately by findEnclosingClassInfo.
+            if (resolveEnclosingOwner) {
+                const resolved = resolveEnclosingOwner(current);
+                if (resolved === null) {
+                    // Provider says skip this container — keep walking up.
+                    current = current.parent;
+                    continue;
+                }
+                return resolved;
+            }
             return current;
         }
         current = current.parent;
     }
     return null;
 }
-/** Minimal no-op SymbolTable stub for FieldExtractorContext (sequential
- *  path has a real SymbolTable, but it's incomplete at this stage — use
- *  the stub for safety). Implements the full {@link SymbolTableReader}
- *  surface so future extractor additions don't silently fall off an
- *  `as unknown as` cast. */
+/** Minimal no-op SymbolTable stub for sequential extractor contexts. The real
+ *  SymbolTable is not fully populated yet at this stage, so use the stub for safety.
+ *  Implements the full {@link SymbolTableReader} surface so future extractor additions
+ *  don't silently fall off an `as unknown as` cast. */
 const NOOP_SYMBOL_TABLE_SEQ = {
     lookupExact: () => undefined,
     lookupExactFull: () => undefined,
@@ -318,7 +328,7 @@ const processParsingSequential = async (graph, files, symbolTable, astCache, onF
                 nodeLabel === 'Property' ||
                 nodeLabel === 'Function';
             const enclosingClassInfo = needsOwner
-                ? cachedFindEnclosingClassInfo(nameNode || definitionNodeForRange, file.path)
+                ? cachedFindEnclosingClassInfo(nameNode || definitionNodeForRange, file.path, provider.resolveEnclosingOwner)
                 : null;
             const enclosingClassId = enclosingClassInfo?.classId ?? null;
             // Qualify method/property IDs with enclosing class name to avoid collisions
@@ -339,19 +349,21 @@ const processParsingSequential = async (graph, files, symbolTable, astCache, onF
             if (isMethodLike && definitionNode) {
                 let enriched = false;
                 if (provider.methodExtractor) {
-                    // Try class-based extraction (method inside a class/struct/trait body)
-                    const classNode = seqFindEnclosingClassNode(definitionNode);
-                    if (classNode) {
+                    // Try class-based extraction (method inside a class/struct/trait body).
+                    // Raw lookup (no resolveEnclosingOwner) so the method extractor sees
+                    // the actual container node (e.g. singleton_class) for static detection.
+                    const methodOwnerNode = seqFindEnclosingOwnerNode(definitionNode);
+                    if (methodOwnerNode) {
                         // Cache extract() results per class node to avoid re-traversing the
                         // same class body for every method it contains (O(N) -> O(1) per hit).
-                        let result = seqMethodExtractCache.get(classNode.id);
+                        let result = seqMethodExtractCache.get(methodOwnerNode.id);
                         if (result === undefined) {
                             result =
-                                provider.methodExtractor.extract(classNode, {
+                                provider.methodExtractor.extract(methodOwnerNode, {
                                     filePath: file.path,
                                     language,
                                 }) ?? null;
-                            seqMethodExtractCache.set(classNode.id, result);
+                            seqMethodExtractCache.set(methodOwnerNode.id, result);
                         }
                         if (result?.methods?.length) {
                             const defLine = definitionNode.startPosition.row + 1;
@@ -362,7 +374,7 @@ const processParsingSequential = async (graph, files, symbolTable, astCache, onF
                                 methodProps = buildMethodProps(info);
                                 seqDefMethodInfo = info;
                                 seqDefMethods = result.methods;
-                                seqClassNodeId = classNode.id;
+                                seqClassNodeId = methodOwnerNode.id;
                             }
                         }
                     }
@@ -443,7 +455,7 @@ const processParsingSequential = async (graph, files, symbolTable, astCache, onF
             if (nodeLabel === 'Property' && definitionNode) {
                 // FieldExtractor is the single source of truth when available
                 if (provider.fieldExtractor && typeEnv) {
-                    const classNode = seqFindEnclosingClassNode(definitionNode);
+                    const classNode = seqFindEnclosingOwnerNode(definitionNode, provider.resolveEnclosingOwner);
                     if (classNode) {
                         const fieldMap = seqGetFieldInfo(classNode, provider, {
                             typeEnv,

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

@@ -0,0 +1,16 @@
+/**
+ * Phase: cobol
+ *
+ * Processes COBOL and JCL files via regex extraction (no tree-sitter).
+ *
+ * @deps    structure
+ * @reads   scannedFiles, allPaths (from structure phase)
+ * @writes  graph (COBOL program/paragraph/section nodes, JCL job/step nodes)
+ */
+import type { PipelinePhase } from './types.js';
+export interface CobolOutput {
+    programs: number;
+    paragraphs: number;
+    sections: number;
+}
+export declare const cobolPhase: PipelinePhase<CobolOutput>;

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

@@ -0,0 +1,45 @@
+/**
+ * Phase: cobol
+ *
+ * Processes COBOL and JCL files via regex extraction (no tree-sitter).
+ *
+ * @deps    structure
+ * @reads   scannedFiles, allPaths (from structure phase)
+ * @writes  graph (COBOL program/paragraph/section nodes, JCL job/step nodes)
+ */
+import { getPhaseOutput } from './types.js';
+import { processCobol, isCobolFile, isJclFile } from '../cobol-processor.js';
+import { readFileContents } from '../filesystem-walker.js';
+import { isDev } from '../utils/env.js';
+export const cobolPhase = {
+    name: 'cobol',
+    deps: ['structure'],
+    async execute(ctx, deps) {
+        const { scannedFiles, allPathSet } = getPhaseOutput(deps, 'structure');
+        const cobolScanned = scannedFiles.filter((f) => isCobolFile(f.path) || isJclFile(f.path));
+        if (cobolScanned.length === 0) {
+            return { programs: 0, paragraphs: 0, sections: 0 };
+        }
+        const cobolContents = await readFileContents(ctx.repoPath, cobolScanned.map((f) => f.path));
+        const cobolFiles = cobolScanned
+            .filter((f) => cobolContents.has(f.path))
+            .map((f) => ({ path: f.path, content: cobolContents.get(f.path) }));
+        const cobolResult = processCobol(ctx.graph, cobolFiles, allPathSet);
+        if (isDev) {
+            console.log(`  COBOL: ${cobolResult.programs} programs, ${cobolResult.paragraphs} paragraphs, ${cobolResult.sections} sections from ${cobolFiles.length} files`);
+            if (cobolResult.execSqlBlocks > 0 ||
+                cobolResult.execCicsBlocks > 0 ||
+                cobolResult.entryPoints > 0) {
+                console.log(`  COBOL enriched: ${cobolResult.execSqlBlocks} SQL blocks, ${cobolResult.execCicsBlocks} CICS blocks, ${cobolResult.entryPoints} entry points, ${cobolResult.moves} moves, ${cobolResult.fileDeclarations} file declarations`);
+            }
+            if (cobolResult.jclJobs > 0) {
+                console.log(`  JCL: ${cobolResult.jclJobs} jobs, ${cobolResult.jclSteps} steps`);
+            }
+        }
+        return {
+            programs: cobolResult.programs,
+            paragraphs: cobolResult.paragraphs,
+            sections: cobolResult.sections,
+        };
+    },
+};

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

@@ -0,0 +1,16 @@
+/**
+ * Phase: communities
+ *
+ * Detects code communities via Leiden algorithm and creates
+ * Community nodes + MEMBER_OF edges.
+ *
+ * @deps    mro
+ * @reads   graph (all nodes and relationships)
+ * @writes  graph (Community nodes, MEMBER_OF edges)
+ */
+import type { PipelinePhase } from './types.js';
+import { type CommunityDetectionResult } from '../community-processor.js';
+export interface CommunitiesOutput {
+    communityResult: CommunityDetectionResult;
+}
+export declare const communitiesPhase: PipelinePhase<CommunitiesOutput>;

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

@@ -0,0 +1,62 @@
+/**
+ * Phase: communities
+ *
+ * Detects code communities via Leiden algorithm and creates
+ * Community nodes + MEMBER_OF edges.
+ *
+ * @deps    mro
+ * @reads   graph (all nodes and relationships)
+ * @writes  graph (Community nodes, MEMBER_OF edges)
+ */
+import { getPhaseOutput } from './types.js';
+import { processCommunities } from '../community-processor.js';
+import { isDev } from '../utils/env.js';
+export const communitiesPhase = {
+    name: 'communities',
+    deps: ['mro', 'structure'],
+    async execute(ctx, deps) {
+        const { totalFiles } = getPhaseOutput(deps, 'structure');
+        ctx.onProgress({
+            phase: 'communities',
+            percent: 84,
+            message: 'Detecting code communities...',
+            stats: { filesProcessed: totalFiles, totalFiles, nodesCreated: ctx.graph.nodeCount },
+        });
+        const communityResult = await processCommunities(ctx.graph, (message, progress) => {
+            const communityProgress = 84 + progress * 0.09;
+            ctx.onProgress({
+                phase: 'communities',
+                percent: Math.round(communityProgress),
+                message,
+                stats: { filesProcessed: totalFiles, totalFiles, nodesCreated: ctx.graph.nodeCount },
+            });
+        });
+        if (isDev) {
+            console.log(`🏘️ Community detection: ${communityResult.stats.totalCommunities} communities found (modularity: ${communityResult.stats.modularity.toFixed(3)})`);
+        }
+        communityResult.communities.forEach((comm) => {
+            ctx.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) => {
+            ctx.graph.addRelationship({
+                id: `${membership.nodeId}_member_of_${membership.communityId}`,
+                type: 'MEMBER_OF',
+                sourceId: membership.nodeId,
+                targetId: membership.communityId,
+                confidence: 1.0,
+                reason: 'leiden-algorithm',
+            });
+        });
+        return { communityResult };
+    },
+};

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

@@ -0,0 +1,17 @@
+/**
+ * Cross-file binding propagation — extracted from pipeline.ts.
+ *
+ * Seeds downstream files with resolved type bindings from upstream exports.
+ * Files are processed in topological import order so upstream bindings
+ * are available when downstream files are re-resolved.
+ *
+ * @module
+ */
+import type { createResolutionContext } from '../model/resolution-context.js';
+import { type PipelineProgress } from '../../../_shared/index.js';
+import type { KnowledgeGraph } from '../../graph/types.js';
+/**
+ * Cross-file binding propagation.
+ * Returns the number of files re-processed.
+ */
+export declare function runCrossFileBindingPropagation(graph: KnowledgeGraph, ctx: ReturnType<typeof createResolutionContext>, parseExportedTypeMap: ReadonlyMap<string, ReadonlyMap<string, string>>, allPathSet: ReadonlySet<string>, totalFiles: number, repoPath: string, pipelineStart: number, onProgress: (progress: PipelineProgress) => void): Promise<number>;

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

@@ -0,0 +1,156 @@
+/**
+ * Cross-file binding propagation — extracted from pipeline.ts.
+ *
+ * Seeds downstream files with resolved type bindings from upstream exports.
+ * Files are processed in topological import order so upstream bindings
+ * are available when downstream files are re-resolved.
+ *
+ * @module
+ */
+import { processCalls, buildImportedReturnTypes, buildImportedRawReturnTypes, } from '../call-processor.js';
+import { createASTCache } from '../ast-cache.js';
+import { getLanguageFromFilename } from '../../../_shared/index.js';
+import { readFileContents } from '../filesystem-walker.js';
+import { isLanguageAvailable } from '../../tree-sitter/parser-loader.js';
+import { topologicalLevelSort } from '../utils/graph-sort.js';
+import { isDev } from '../utils/env.js';
+/** Max AST trees to keep in LRU cache for cross-file binding propagation. */
+const AST_CACHE_CAP = 50;
+/** Minimum percentage of files that must benefit from cross-file seeding. */
+const CROSS_FILE_SKIP_THRESHOLD = 0.03;
+/** Hard cap on files re-processed during cross-file propagation. */
+const MAX_CROSS_FILE_REPROCESS = 2000;
+/**
+ * Cross-file binding propagation.
+ * Returns the number of files re-processed.
+ */
+export async function runCrossFileBindingPropagation(graph, ctx, parseExportedTypeMap, allPathSet, totalFiles, repoPath, pipelineStart, onProgress) {
+    if (parseExportedTypeMap.size === 0 || ctx.namedImportMap.size === 0)
+        return 0;
+    // Build a local mutable working copy. Per-file re-resolution below mutates
+    // this map (each `processCalls` writes that file's exports back into it so
+    // later iterations in the same level/loop can resolve transitive bindings).
+    // Owning a local copy here keeps `ParseOutput.exportedTypeMap` truly
+    // read-only at the phase boundary — no cast, no shared-mutable handoff.
+    const exportedTypeMap = new Map();
+    for (const [fp, exports] of parseExportedTypeMap) {
+        exportedTypeMap.set(fp, new Map(exports));
+    }
+    const { levels, cycleCount } = topologicalLevelSort(ctx.importMap);
+    if (isDev && cycleCount > 0) {
+        console.log(`🔄 ${cycleCount} files in import cycles (processed last in undefined order)`);
+    }
+    let filesWithGaps = 0;
+    const gapThreshold = Math.max(1, Math.ceil(totalFiles * CROSS_FILE_SKIP_THRESHOLD));
+    outer: for (const level of levels) {
+        for (const filePath of level) {
+            const imports = ctx.namedImportMap.get(filePath);
+            if (!imports)
+                continue;
+            for (const [, binding] of imports) {
+                const upstream = exportedTypeMap.get(binding.sourcePath);
+                if (upstream?.has(binding.exportedName)) {
+                    filesWithGaps++;
+                    break;
+                }
+                const def = ctx.model.symbols.lookupExactFull(binding.sourcePath, binding.exportedName);
+                if (def?.returnType) {
+                    filesWithGaps++;
+                    break;
+                }
+            }
+            if (filesWithGaps >= gapThreshold)
+                break outer;
+        }
+    }
+    const gapRatio = totalFiles > 0 ? filesWithGaps / totalFiles : 0;
+    if (gapRatio < CROSS_FILE_SKIP_THRESHOLD && filesWithGaps < gapThreshold) {
+        if (isDev) {
+            console.log(`⏭️ Cross-file re-resolution skipped (${filesWithGaps}/${totalFiles} files, ${(gapRatio * 100).toFixed(1)}% < ${CROSS_FILE_SKIP_THRESHOLD * 100}% threshold)`);
+        }
+        return 0;
+    }
+    // Intentionally reports `phase: 'parsing'` rather than a separate
+    // 'crossFile' phase: cross-file re-resolution is logically a continuation of
+    // the parsing/resolution work and is bucketed under "parsing" in any
+    // telemetry that groups events by phase name. Kept consistent with the
+    // upstream `parse` phase's progress events so the UI shows one continuous
+    // progress segment instead of a phase flicker. If a future change splits
+    // this out into its own phase, also rename `parse-impl.ts` per-chunk
+    // progress events accordingly.
+    onProgress({
+        phase: 'parsing',
+        percent: 82,
+        message: `Cross-file type propagation (${filesWithGaps}+ files)...`,
+        stats: { filesProcessed: totalFiles, totalFiles, nodesCreated: graph.nodeCount },
+    });
+    let crossFileResolved = 0;
+    const crossFileStart = Date.now();
+    const astCache = createASTCache(AST_CACHE_CAP);
+    for (const level of levels) {
+        const levelCandidates = [];
+        for (const filePath of level) {
+            if (crossFileResolved + levelCandidates.length >= MAX_CROSS_FILE_REPROCESS)
+                break;
+            const imports = ctx.namedImportMap.get(filePath);
+            if (!imports)
+                continue;
+            const seeded = new Map();
+            for (const [localName, binding] of imports) {
+                const upstream = exportedTypeMap.get(binding.sourcePath);
+                if (upstream) {
+                    const type = upstream.get(binding.exportedName);
+                    if (type)
+                        seeded.set(localName, type);
+                }
+            }
+            const importedReturns = buildImportedReturnTypes(filePath, ctx.namedImportMap, ctx.model.symbols);
+            const importedRawReturns = buildImportedRawReturnTypes(filePath, ctx.namedImportMap, ctx.model.symbols);
+            if (seeded.size === 0 && importedReturns.size === 0)
+                continue;
+            if (!allPathSet.has(filePath))
+                continue;
+            const lang = getLanguageFromFilename(filePath);
+            if (!lang || !isLanguageAvailable(lang))
+                continue;
+            levelCandidates.push({ filePath, seeded, importedReturns, importedRawReturns });
+        }
+        if (levelCandidates.length === 0)
+            continue;
+        const levelPaths = levelCandidates.map((c) => c.filePath);
+        const contentMap = await readFileContents(repoPath, levelPaths);
+        for (const { filePath, seeded, importedReturns, importedRawReturns } of levelCandidates) {
+            const content = contentMap.get(filePath);
+            if (!content)
+                continue;
+            const reFile = [{ path: filePath, content }];
+            const bindings = new Map();
+            if (seeded.size > 0)
+                bindings.set(filePath, seeded);
+            const importedReturnTypesMap = new Map();
+            if (importedReturns.size > 0) {
+                importedReturnTypesMap.set(filePath, importedReturns);
+            }
+            const importedRawReturnTypesMap = new Map();
+            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);
+            crossFileResolved++;
+        }
+        if (crossFileResolved >= MAX_CROSS_FILE_REPROCESS) {
+            if (isDev)
+                console.log(`⚠️ Cross-file re-resolution capped at ${MAX_CROSS_FILE_REPROCESS} files`);
+            break;
+        }
+    }
+    astCache.clear();
+    if (isDev) {
+        const elapsed = Date.now() - crossFileStart;
+        const totalElapsed = Date.now() - pipelineStart;
+        const reResolutionPct = totalElapsed > 0 ? ((elapsed / totalElapsed) * 100).toFixed(1) : '0';
+        console.log(`🔗 Cross-file re-resolution: ${crossFileResolved} candidates re-processed` +
+            ` in ${elapsed}ms (${reResolutionPct}% of total ingestion time so far)`);
+    }
+    return crossFileResolved;
+}

package/dist/core/ingestion/pipeline-phases/cross-file.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Phase: crossFile
+ *
+ * Cross-file binding propagation: seeds downstream files with resolved
+ * type bindings from upstream exports. Files are processed in topological
+ * import order so upstream bindings are available when downstream files
+ * are re-resolved.
+ *
+ * @deps    parse, routes, tools, orm (waits for all post-parse phases)
+ * @reads   exportedTypeMap, allPaths, totalFiles
+ * @writes  graph (refined CALLS edges via re-resolution)
+ *
+ * **Accumulator ownership / residual risk.** This phase is the sole
+ * disposer of the `BindingAccumulator` produced by `parse`. The dispose
+ * call lives inside a `finally` block in `execute()` so that a throw
+ * inside `runCrossFileBindingPropagation` (or anywhere else in the body)
+ * still releases the accumulator's heap. The dependency declaration
+ * (`deps: ['parse', 'routes', 'tools', 'orm']`) plus the runner's
+ * topological scheduling guarantee that every other consumer of the
+ * accumulator has finished before this phase starts, so disposing here
+ * is correct.
+ *
+ * The residual risk is intentional and accepted: if a future phase is
+ * inserted between `parse` and `crossFile` that reads the accumulator
+ * and throws, `crossFile.execute()` never runs and the accumulator
+ * leaks. Any author inserting a new phase between `parse` and
+ * `crossFile` MUST either route the new phase's output through
+ * `crossFile` (so disposal still happens here) or take ownership of
+ * the accumulator's lifetime explicitly (its own try/finally that
+ * disposes on the failure path). Do not silently rely on the GC.
+ */
+import type { PipelinePhase } from './types.js';
+export interface CrossFileOutput {
+    /** Number of files re-processed during cross-file propagation. */
+    filesReprocessed: number;
+}
+export declare const crossFilePhase: PipelinePhase<CrossFileOutput>;

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

@@ -0,0 +1,63 @@
+/**
+ * Phase: crossFile
+ *
+ * Cross-file binding propagation: seeds downstream files with resolved
+ * type bindings from upstream exports. Files are processed in topological
+ * import order so upstream bindings are available when downstream files
+ * are re-resolved.
+ *
+ * @deps    parse, routes, tools, orm (waits for all post-parse phases)
+ * @reads   exportedTypeMap, allPaths, totalFiles
+ * @writes  graph (refined CALLS edges via re-resolution)
+ *
+ * **Accumulator ownership / residual risk.** This phase is the sole
+ * disposer of the `BindingAccumulator` produced by `parse`. The dispose
+ * call lives inside a `finally` block in `execute()` so that a throw
+ * inside `runCrossFileBindingPropagation` (or anywhere else in the body)
+ * still releases the accumulator's heap. The dependency declaration
+ * (`deps: ['parse', 'routes', 'tools', 'orm']`) plus the runner's
+ * topological scheduling guarantee that every other consumer of the
+ * accumulator has finished before this phase starts, so disposing here
+ * is correct.
+ *
+ * The residual risk is intentional and accepted: if a future phase is
+ * inserted between `parse` and `crossFile` that reads the accumulator
+ * and throws, `crossFile.execute()` never runs and the accumulator
+ * leaks. Any author inserting a new phase between `parse` and
+ * `crossFile` MUST either route the new phase's output through
+ * `crossFile` (so disposal still happens here) or take ownership of
+ * the accumulator's lifetime explicitly (its own try/finally that
+ * disposes on the failure path). Do not silently rely on the GC.
+ */
+import { getPhaseOutput } from './types.js';
+import { runCrossFileBindingPropagation } from './cross-file-impl.js';
+import { isDev } from '../utils/env.js';
+export const crossFilePhase = {
+    name: 'crossFile',
+    deps: ['parse', 'routes', 'tools', 'orm'],
+    async execute(ctx, deps) {
+        const { exportedTypeMap, allPathSet, totalFiles, bindingAccumulator, resolutionContext } = getPhaseOutput(deps, 'parse');
+        try {
+            // Telemetry must run BEFORE dispose: totalBindings, fileCount, and
+            // estimateMemoryBytes() all return 0 once dispose() clears the
+            // internal maps.
+            if (isDev) {
+                if (bindingAccumulator.totalBindings > 0) {
+                    const memKB = Math.round(bindingAccumulator.estimateMemoryBytes() / 1024);
+                    console.log(`📦 BindingAccumulator: ${bindingAccumulator.totalBindings} bindings across ${bindingAccumulator.fileCount} files (~${memKB} KB)`);
+                }
+                else if (totalFiles > 0) {
+                    console.log(`📦 BindingAccumulator: EMPTY — 0 bindings across 0 files despite ${totalFiles} parsed files. If the codebase has typed bindings, this indicates an upstream regression.`);
+                }
+            }
+            const filesReprocessed = await runCrossFileBindingPropagation(ctx.graph, resolutionContext, exportedTypeMap, allPathSet, totalFiles, ctx.repoPath, ctx.pipelineStart, ctx.onProgress);
+            return { filesReprocessed };
+        }
+        finally {
+            // Single dispose call site for the accumulator — runs on both the
+            // happy path and the throw path so the heap is always released
+            // before the runner moves on (or surfaces the error).
+            bindingAccumulator.dispose();
+        }
+    },
+};

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

@@ -0,0 +1,21 @@
+/**
+ * Pipeline Phases — barrel export.
+ *
+ * Exports all phases, the runner, types, and shared utilities
+ * for the ingestion pipeline.
+ */
+export { scanPhase, type ScanOutput } from './scan.js';
+export { structurePhase, type StructureOutput } from './structure.js';
+export { markdownPhase, type MarkdownOutput } from './markdown.js';
+export { cobolPhase, type CobolOutput } from './cobol.js';
+export { parsePhase, type ParseOutput } from './parse.js';
+export { routesPhase, type RoutesOutput, type RouteEntry } from './routes.js';
+export { toolsPhase, type ToolsOutput, type ToolDef } from './tools.js';
+export { ormPhase, type ORMOutput } from './orm.js';
+export { crossFilePhase, type CrossFileOutput } from './cross-file.js';
+export { mroPhase, type MROOutput } from './mro.js';
+export { communitiesPhase, type CommunitiesOutput } from './communities.js';
+export { processesPhase, type ProcessesOutput } from './processes.js';
+export { runPipeline } from './runner.js';
+export type { PipelinePhase, PipelineContext, PhaseResult } from './types.js';
+export { getPhaseOutput } from './types.js';

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

@@ -0,0 +1,22 @@
+/**
+ * Pipeline Phases — barrel export.
+ *
+ * Exports all phases, the runner, types, and shared utilities
+ * for the ingestion pipeline.
+ */
+// ── Phase exports (in dependency order) ────────────────────────────────────
+export { scanPhase } from './scan.js';
+export { structurePhase } from './structure.js';
+export { markdownPhase } from './markdown.js';
+export { cobolPhase } from './cobol.js';
+export { parsePhase } from './parse.js';
+export { routesPhase } from './routes.js';
+export { toolsPhase } from './tools.js';
+export { ormPhase } from './orm.js';
+export { crossFilePhase } from './cross-file.js';
+export { mroPhase } from './mro.js';
+export { communitiesPhase } from './communities.js';
+export { processesPhase } from './processes.js';
+// ── Infrastructure ─────────────────────────────────────────────────────────
+export { runPipeline } from './runner.js';
+export { getPhaseOutput } from './types.js';

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

@@ -0,0 +1,17 @@
+/**
+ * Phase: markdown
+ *
+ * Processes Markdown/MDX files to extract headings and cross-links.
+ *
+ * @deps    structure
+ * @reads   scannedFiles, allPaths (from structure phase)
+ * @writes  graph (Markdown section nodes + cross-link edges)
+ */
+import type { PipelinePhase } from './types.js';
+export interface MarkdownOutput {
+    /** Number of markdown sections extracted. */
+    sections: number;
+    /** Number of cross-links created. */
+    links: number;
+}
+export declare const markdownPhase: PipelinePhase<MarkdownOutput>;