gitnexus 1.6.10-rc.21 → 1.6.10-rc.211

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

@@ -1,50 +1,55 @@
 /**
  * Phase: di
  *
- * Framework-neutral dependency-injection resolution. Routes `Property` nodes
- * by `properties.language` to the per-language field matchers registered in
- * `di-extractors/` (`DI_MATCHERS` — same registry seam shape as
- * `SCOPE_RESOLVERS`), then fans each match out to `INJECTS` edges from the
- * consumer Class node to every Class implementing the matched element
- * interface.
- *
- * This file names NO language or framework: which fields count as
- * container-injected — and why — is entirely the registered matcher's
- * business (see `di-extractors/` for the matchers and their semantics,
- * including deliberate annotation exclusions). The matcher also supplies the
- * human-readable edge `reason`, so framework specifics stay in the payload,
- * never in this phase.
- *
- * The resolution uses ONLY graph data — Property nodes, `HAS_PROPERTY` edges,
- * `IMPLEMENTS` edges, and Interface nodes. No filesystem access is performed:
- * the structural information was already extracted by earlier parse /
- * structure phases.
- *
- * Interface resolution is scoped to the CANDIDATE'S OWN language and prefers
- * qualified names: a dotted element type resolves via the language's
- * `qualifiedName` index; a bare simple name resolves only while unique within
- * that language. Ambiguous names — simple OR qualified (a qualifiedName has
- * no file-path component, so the same package+name duplicated across monorepo
- * modules collides too) — fail CLOSED — no edge, never
- * last-writer-wins — but observably: skips are counted in the phase output's
- * `ambiguousSkipped` and named in an isDev debug log, so "no DI fields" is
- * distinguishable from "all candidates ambiguous". Same-package/import-aware
- * disambiguation is a documented follow-up (see the plan's Deferred work).
+ * Framework-neutral dependency-injection resolution. Per-language resolvers
+ * identify injection sites and provider metadata; this phase performs only
+ * graph-level type/heritage resolution and emits owner/site -> provider INJECTS edges.
  *
  * @deps    mro
- * @reads   graph (Property nodes, HAS_PROPERTY edges, IMPLEMENTS edges, Interface nodes)
+ * @reads   graph (Class/Interface/member nodes and heritage/ownership edges)
  * @writes  graph (INJECTS edges)
  */
-import { DI_MATCHERS, isSupportedLanguage } from '../di-extractors/index.js';
+import { DI_RESOLVERS, isSupportedLanguage, } from '../di-extractors/index.js';
 import { isDev } from '../utils/env.js';
 import { logger } from '../../logger.js';
-/** Sentinel marking an interface name (simple or qualified) claimed by more
- *  than one Interface node within a language — resolution must fail closed. */
 const AMBIGUOUS = Symbol('ambiguous');
+function addProvidedType(index, language, typeName, providerId) {
+    const byName = index.get(language) ?? new Map();
+    const names = new Set([typeName, typeName.slice(typeName.lastIndexOf('.') + 1)]);
+    for (const name of names) {
+        const providers = byName.get(name) ?? new Set();
+        providers.add(providerId);
+        byName.set(name, providers);
+    }
+    index.set(language, byName);
+}
+function emptyNameIndex() {
+    return { byQualifiedName: new Map(), bySimpleName: new Map() };
+}
+function addIndexedName(index, node) {
+    const qualifiedName = node.properties.qualifiedName;
+    if (typeof qualifiedName === 'string') {
+        index.byQualifiedName.set(qualifiedName, index.byQualifiedName.has(qualifiedName) ? AMBIGUOUS : node.id);
+    }
+    const simpleName = node.properties.name;
+    index.bySimpleName.set(simpleName, index.bySimpleName.has(simpleName) ? AMBIGUOUS : node.id);
+}
+function resolveIndexedName(index, name) {
+    if (index === undefined)
+        return undefined;
+    return name.includes('.') ? index.byQualifiedName.get(name) : index.bySimpleName.get(name);
+}
+function providerCandidates(ids, providers) {
+    const all = [...ids];
+    const recognized = all.filter((id) => providers.has(id));
+    // Recall-first fallback: provider metadata can be incomplete (custom
+    // registration mechanisms and legacy indexes can omit it). Prefer
+    // framework-recognized providers when present, but keep structurally valid
+    // candidates when none are known instead of dropping the injection entirely.
+    return recognized.length > 0 ? recognized : all;
+}
 export const diPhase = {
     name: 'di',
-    // Depends on `mro` for ordering: heritage edges (IMPLEMENTS/EXTENDS) must be
-    // fully populated before we resolve interface→implementer fan-out.
     deps: ['mro'],
     async execute(ctx) {
         ctx.onProgress({
@@ -53,165 +58,278 @@ export const diPhase = {
             message: 'Resolving dependency-injection edges...',
             stats: { filesProcessed: 0, totalFiles: 0, nodesCreated: ctx.graph.nodeCount },
         });
-        // ── Pass 1: route Property nodes to registered per-language matchers ───
-        // Early-exit optimization: if no registered matcher accepts any Property
-        // node, skip all index construction. This makes the phase a no-op on
-        // repos with no DI-matched fields (no IMPLEMENTS / HAS_PROPERTY scans).
         const candidates = [];
+        const providers = new Map();
+        const providedTypes = new Map();
+        const providerNames = new Map();
+        const providerNodes = new Map();
+        const providersByDeclarer = new Map();
         ctx.graph.forEachNode((node) => {
-            if (node.label !== 'Property')
-                return;
             const language = node.properties.language;
             if (language === undefined || !isSupportedLanguage(language))
                 return;
-            const matcher = DI_MATCHERS.get(language);
-            if (matcher === undefined)
-                return;
-            const match = matcher(node);
-            if (match === null)
+            const resolver = DI_RESOLVERS.get(language);
+            if (resolver === undefined)
                 return;
-            candidates.push({
-                propertyId: node.id,
-                language,
-                elementTypeName: match.elementTypeName,
-                reason: match.reason,
-            });
+            const provider = resolver.matchProvider(node);
+            if (provider !== null) {
+                providers.set(node.id, provider);
+                providerNodes.set(node.id, node);
+                const namesByLanguage = providerNames.get(language) ?? new Map();
+                for (const name of provider.names) {
+                    const namedProviders = namesByLanguage.get(name) ?? new Set();
+                    namedProviders.add(node.id);
+                    namesByLanguage.set(name, namedProviders);
+                }
+                providerNames.set(language, namesByLanguage);
+                if (provider.providedTypeName !== undefined) {
+                    addProvidedType(providedTypes, language, provider.providedTypeName, node.id);
+                }
+                if (provider.declaredByNodeId !== undefined) {
+                    const declared = providersByDeclarer.get(provider.declaredByNodeId) ?? new Set();
+                    declared.add(node.id);
+                    providersByDeclarer.set(provider.declaredByNodeId, declared);
+                }
+            }
+            for (const match of resolver.matchInjectionSites(node)) {
+                candidates.push({ ...match, siteNodeId: node.id, language });
+            }
         });
         if (candidates.length === 0) {
-            return { injectsEdges: 0, fieldsScanned: 0, ambiguousSkipped: 0 };
+            return {
+                injectsEdges: 0,
+                fieldsScanned: 0,
+                ambiguousSkipped: 0,
+                ambiguousInjections: 0,
+            };
         }
-        // ── Pass 2: build single-pass reverse indexes ─────────────────────────
-        // interfaceNodeId → Set<implementerClassId>  (reverse of IMPLEMENTS edge)
-        // IMPLEMENTS edges go Class→Interface, so target is the interface.
-        // Keyed by node id — globally unique — so this index needs no language
-        // scoping; only NAME-based lookups (below) do.
         const interfaceToImplementers = new Map();
+        const directSupertypes = new Map();
         for (const rel of ctx.graph.iterRelationshipsByType('IMPLEMENTS')) {
-            const implementerId = rel.sourceId; // Class
-            const interfaceId = rel.targetId; // Interface
-            let set = interfaceToImplementers.get(interfaceId);
-            if (set === undefined) {
-                set = new Set();
-                interfaceToImplementers.set(interfaceId, set);
-            }
-            set.add(implementerId);
+            const set = interfaceToImplementers.get(rel.targetId) ?? new Set();
+            set.add(rel.sourceId);
+            interfaceToImplementers.set(rel.targetId, set);
+            const supertypes = directSupertypes.get(rel.sourceId) ?? new Set();
+            supertypes.add(rel.targetId);
+            directSupertypes.set(rel.sourceId, supertypes);
         }
-        // propertyNodeId → consumerClassId  (reverse of HAS_PROPERTY edge)
-        // HAS_PROPERTY edges go Class→Property, so target is the property.
-        const propertyToClass = new Map();
-        for (const rel of ctx.graph.iterRelationshipsByType('HAS_PROPERTY')) {
-            propertyToClass.set(rel.targetId, rel.sourceId);
+        for (const rel of ctx.graph.iterRelationshipsByType('EXTENDS')) {
+            const supertypes = directSupertypes.get(rel.sourceId) ?? new Set();
+            supertypes.add(rel.targetId);
+            directSupertypes.set(rel.sourceId, supertypes);
         }
-        // language → InterfaceIndex  (from Interface-labeled nodes). Scoped per
-        // language so an Interface in one language can never satisfy a candidate
-        // from another. Within a language, a name resolves only while unique —
-        // a second Interface claiming the same simple OR qualified name flips
-        // that entry to AMBIGUOUS and resolution fails closed (never
-        // last-writer-wins).
-        // Index only languages that can resolve: an Interface in a language with
-        // no candidate can never be looked up in Pass 3.
-        const candidateLanguages = new Set(candidates.map((c) => c.language));
+        const memberToClass = new Map();
+        for (const relationType of ['HAS_PROPERTY', 'HAS_METHOD']) {
+            for (const rel of ctx.graph.iterRelationshipsByType(relationType)) {
+                memberToClass.set(rel.targetId, rel.sourceId);
+            }
+        }
+        const candidateLanguages = new Set(candidates.map((candidate) => candidate.language));
         const interfacesByLanguage = new Map();
+        const classesByLanguage = new Map();
         ctx.graph.forEachNode((node) => {
-            if (node.label !== 'Interface')
+            if (node.label !== 'Class' && node.label !== 'Interface')
                 return;
             const language = node.properties.language;
-            if (typeof language !== 'string')
-                return; // no language ⇒ unindexable
-            if (!candidateLanguages.has(language))
+            if (typeof language !== 'string' || !candidateLanguages.has(language))
                 return;
-            let index = interfacesByLanguage.get(language);
-            if (index === undefined) {
-                index = { byQualifiedName: new Map(), bySimpleName: new Map() };
-                interfacesByLanguage.set(language, index);
+            const indexes = node.label === 'Class' ? classesByLanguage : interfacesByLanguage;
+            const index = indexes.get(language) ?? emptyNameIndex();
+            addIndexedName(index, node);
+            indexes.set(language, index);
+            if (node.label === 'Class')
+                providerNodes.set(node.id, node);
+        });
+        // A declaration returning a concrete class is assignable to every class or
+        // interface that type extends/implements. Expand once per language+type and
+        // register the declaration under those ancestor names. This keeps named
+        // selection fast (set intersection below) while allowing, for example, a
+        // `DefaultGateway` Bean to satisfy a named `Gateway` Resource site.
+        const assignableNamesByProvidedType = new Map();
+        for (const [providerId, provider] of providers) {
+            if (provider.providedTypeName === undefined)
+                continue;
+            const providerNode = providerNodes.get(providerId);
+            const language = providerNode?.properties.language;
+            if (typeof language !== 'string')
+                continue;
+            const cacheKey = `${language}\0${provider.providedTypeName}`;
+            let assignableTypeNames = assignableNamesByProvidedType.get(cacheKey);
+            if (assignableTypeNames === undefined) {
+                const classEntry = resolveIndexedName(classesByLanguage.get(language), provider.providedTypeName);
+                const interfaceEntry = resolveIndexedName(interfacesByLanguage.get(language), provider.providedTypeName);
+                const rootTypeId = typeof classEntry === 'string' && interfaceEntry === undefined
+                    ? classEntry
+                    : typeof interfaceEntry === 'string' && classEntry === undefined
+                        ? interfaceEntry
+                        : undefined;
+                const names = new Set();
+                if (rootTypeId !== undefined) {
+                    const queue = [rootTypeId];
+                    const visited = new Set();
+                    while (queue.length > 0) {
+                        const typeId = queue.pop();
+                        if (typeId === undefined)
+                            continue;
+                        if (visited.has(typeId))
+                            continue;
+                        visited.add(typeId);
+                        const typeNode = ctx.graph.getNode(typeId);
+                        if ((typeNode?.label === 'Class' || typeNode?.label === 'Interface') &&
+                            typeNode.properties.language === language) {
+                            names.add(typeNode.properties.name);
+                            const qualifiedName = typeNode.properties.qualifiedName;
+                            if (typeof qualifiedName === 'string')
+                                names.add(qualifiedName);
+                        }
+                        for (const supertypeId of directSupertypes.get(typeId) ?? []) {
+                            queue.push(supertypeId);
+                        }
+                    }
+                }
+                assignableTypeNames = [...names];
+                assignableNamesByProvidedType.set(cacheKey, assignableTypeNames);
             }
-            // `qualifiedName` reaches NodeProperties through the extensible index
-            // signature, so narrow it explicitly (no `any`).
-            const qualifiedName = node.properties.qualifiedName;
-            if (typeof qualifiedName === 'string') {
-                index.byQualifiedName.set(qualifiedName, index.byQualifiedName.has(qualifiedName) ? AMBIGUOUS : node.id);
+            for (const typeName of assignableTypeNames) {
+                addProvidedType(providedTypes, language, typeName, providerId);
             }
-            const simpleName = node.properties.name;
-            index.bySimpleName.set(simpleName, index.bySimpleName.has(simpleName) ? AMBIGUOUS : node.id);
-        });
-        // ── Pass 3: emit INJECTS edges ────────────────────────────────────────
-        let injectsEdges = 0;
+        }
         let ambiguousSkipped = 0;
-        const ambiguousElementTypes = new Set();
-        const seenEdges = new Set();
+        let ambiguousInjections = 0;
+        const ambiguousTypeNames = new Set();
+        const pending = new Map();
+        const queueEdge = (edge) => {
+            if (edge.sourceId === edge.targetId)
+                return;
+            const id = `INJECTS:${edge.sourceId}->${edge.targetId}`;
+            const existing = pending.get(id);
+            if (existing === undefined || edge.confidence > existing.confidence)
+                pending.set(id, edge);
+        };
         for (const candidate of candidates) {
-            // Resolve the consumer Class that owns this Property.
-            const consumerClassId = propertyToClass.get(candidate.propertyId);
-            if (!consumerClassId)
+            const siteNode = ctx.graph.getNode(candidate.siteNodeId);
+            const consumerClassId = siteNode?.label === 'Class' ? siteNode.id : memberToClass.get(candidate.siteNodeId);
+            if (consumerClassId === undefined)
                 continue;
-            // Resolve the element type name via the CANDIDATE'S OWN language index
-            // only — a same-named Interface in another language never participates.
-            const index = interfacesByLanguage.get(candidate.language);
-            if (index === undefined)
+            const edgeSourceId = candidate.edgeSource === 'site' && siteNode !== undefined ? siteNode.id : consumerClassId;
+            const classEntry = resolveIndexedName(classesByLanguage.get(candidate.language), candidate.targetTypeName);
+            const interfaceEntry = resolveIndexedName(interfacesByLanguage.get(candidate.language), candidate.targetTypeName);
+            if (classEntry === AMBIGUOUS ||
+                interfaceEntry === AMBIGUOUS ||
+                (classEntry !== undefined && interfaceEntry !== undefined)) {
+                // A simple/qualified name claimed by both a Class and an Interface is
+                // type-ambiguous too. Fail closed rather than guessing which Java type
+                // the injection site meant; import-aware disambiguation is not
+                // available in this graph-only phase. This intentionally applies to
+                // legacy collection sites too: a Class/Interface collision no longer
+                // fans out through the interface on a simple-name guess.
+                ambiguousSkipped++;
+                ambiguousTypeNames.add(candidate.targetTypeName);
+                continue;
+            }
+            const structural = new Set();
+            if (typeof classEntry === 'string')
+                structural.add(classEntry);
+            if (typeof interfaceEntry === 'string') {
+                for (const id of interfaceToImplementers.get(interfaceEntry) ?? [])
+                    structural.add(id);
+            }
+            for (const id of providedTypes.get(candidate.language)?.get(candidate.targetTypeName) ?? []) {
+                structural.add(id);
+            }
+            for (const id of providersByDeclarer.get(edgeSourceId) ?? [])
+                structural.delete(id);
+            structural.delete(consumerClassId);
+            structural.delete(edgeSourceId);
+            if (structural.size === 0)
                 continue;
-            // A dotted element type is a qualified name (e.g. `com.a.Shape`) —
-            // exact qualifiedName lookup, unaffected by simple-name ambiguity.
-            // A bare name uses the simple-name index. BOTH lookups fail CLOSED
-            // on their own ambiguity (a qualified name too can be claimed twice —
-            // same package+name across monorepo modules): no edge (never
-            // last-writer-wins), but counted and logged so the skip is
-            // observable. Same-package/import-aware disambiguation is a
-            // deliberate follow-up (plan: Deferred work).
-            let interfaceId;
-            if (candidate.elementTypeName.includes('.')) {
-                const entry = index.byQualifiedName.get(candidate.elementTypeName);
-                if (entry === AMBIGUOUS) {
-                    ambiguousSkipped++;
-                    ambiguousElementTypes.add(candidate.elementTypeName);
+            const namedSelection = candidate.namedSelection;
+            let usedNamedSelection = false;
+            let selectionSuffix = '';
+            let viable;
+            if (namedSelection !== undefined) {
+                const named = [
+                    ...(providerNames.get(candidate.language)?.get(namedSelection.name) ?? []),
+                ].filter((id) => structural.has(id));
+                if (named.length > 0) {
+                    viable = named;
+                    usedNamedSelection = true;
+                    selectionSuffix = `; ${namedSelection.reason}`;
+                }
+                else if (namedSelection.fallbackToType === true) {
+                    viable = providerCandidates(structural, providers);
+                    selectionSuffix = `; ${namedSelection.reason} unmatched; type fallback`;
+                }
+                else {
                     continue;
                 }
-                interfaceId = entry;
             }
             else {
-                const entry = index.bySimpleName.get(candidate.elementTypeName);
-                if (entry === AMBIGUOUS) {
-                    ambiguousSkipped++;
-                    ambiguousElementTypes.add(candidate.elementTypeName);
-                    continue;
+                viable = providerCandidates(structural, providers);
+            }
+            if (candidate.cardinality === 'collection') {
+                const confidence = usedNamedSelection ? 0.9 : 0.8;
+                for (const targetId of viable) {
+                    queueEdge({
+                        sourceId: edgeSourceId,
+                        targetId,
+                        confidence,
+                        reason: candidate.reason + selectionSuffix,
+                    });
                 }
-                interfaceId = entry;
+                continue;
             }
-            if (interfaceId === undefined)
+            if (viable.length === 1) {
+                queueEdge({
+                    sourceId: edgeSourceId,
+                    targetId: viable[0],
+                    confidence: usedNamedSelection ? 0.95 : namedSelection === undefined ? 0.9 : 0.85,
+                    reason: candidate.reason + selectionSuffix,
+                });
                 continue;
-            // Fan out to every class implementing that interface.
-            const implementers = interfaceToImplementers.get(interfaceId);
-            if (!implementers)
+            }
+            const preferred = viable.flatMap((id) => {
+                const reason = providers.get(id)?.preferenceReason;
+                return reason === undefined ? [] : [{ id, reason }];
+            });
+            if (!usedNamedSelection && preferred.length === 1) {
+                const selected = preferred[0];
+                queueEdge({
+                    sourceId: edgeSourceId,
+                    targetId: selected.id,
+                    confidence: 0.95,
+                    reason: `${candidate.reason}${selectionSuffix}; ${selected.reason}`,
+                });
                 continue;
-            for (const implId of implementers) {
-                // Skip self-edges: a class never injects its own bean into itself.
-                if (implId === consumerClassId)
-                    continue;
-                // Dedup-safe edge ID: deterministic from (consumer, implementer).
-                const edgeId = `INJECTS:${consumerClassId}->${implId}`;
-                if (seenEdges.has(edgeId))
-                    continue;
-                seenEdges.add(edgeId);
-                ctx.graph.addRelationship({
-                    id: edgeId,
-                    sourceId: consumerClassId,
-                    targetId: implId,
-                    type: 'INJECTS',
-                    confidence: 0.8,
-                    // Matcher-supplied reason — names the framework and the annotation
-                    // actually found on the field (see di-extractors/).
-                    reason: candidate.reason,
+            }
+            ambiguousInjections++;
+            const candidateNames = viable
+                .map((id) => providerNodes.get(id)?.properties.name ?? id)
+                .sort()
+                .join(', ');
+            for (const targetId of viable) {
+                queueEdge({
+                    sourceId: edgeSourceId,
+                    targetId,
+                    confidence: 0.5,
+                    reason: `${candidate.reason}${selectionSuffix}; ambiguous candidates: ${candidateNames}`,
                 });
-                injectsEdges++;
             }
         }
+        for (const [id, edge] of pending) {
+            ctx.graph.addRelationship({ id, type: 'INJECTS', ...edge });
+        }
         if (isDev && ambiguousSkipped > 0) {
-            // One aggregated debug line (not per-candidate spam): duplicate simple
-            // names are NORMAL in large repos, but the skip must stay observable.
-            logger.debug(`🧩 DI: ${ambiguousSkipped} candidate(s) skipped — ambiguous element interface name(s): ${[...ambiguousElementTypes].sort().join(', ')}`);
+            logger.debug(`DI: ${ambiguousSkipped} site(s) skipped because requested type names were ambiguous: ${[...ambiguousTypeNames].sort().join(', ')}`);
         }
-        if (isDev && (injectsEdges > 0 || ambiguousSkipped > 0)) {
-            logger.info(`🧩 DI: ${injectsEdges} INJECTS edges from ${candidates.length} injection-annotated collection fields (${ambiguousSkipped} ambiguous skipped)`);
+        if (isDev && (pending.size > 0 || ambiguousInjections > 0)) {
+            logger.info(`DI: ${pending.size} INJECTS edges from ${candidates.length} injection sites (${ambiguousInjections} ambiguous single-site resolutions)`);
         }
-        return { injectsEdges, fieldsScanned: candidates.length, ambiguousSkipped };
+        return {
+            injectsEdges: pending.size,
+            fieldsScanned: candidates.length,
+            ambiguousSkipped,
+            ambiguousInjections,
+        };
     },
 };

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

@@ -14,6 +14,9 @@ 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 { scopeResolutionPhase, type ScopeResolutionOutput, } from '../scope-resolution/pipeline/phase.js';
+export { springConfigPhase, type SpringConfigOutput } from './spring-config.js';
+export { springAutoConfigurationPhase, type SpringAutoConfigurationOutput, } from './spring-auto-configuration.js';
+export { springAopPhase, springAopInheritancePhase, type SpringAopOutput, type SpringAopInheritanceOutput, } from './spring-aop.js';
 export { pruneLocalSymbolsPhase, type PruneLocalSymbolsOutput } from './prune-local-symbols.js';
 export { taintSummariesPhase, type TaintSummariesOutput } from './taint-summaries.js';
 export { callSummariesPhase, type CallSummariesOutput } from './call-summaries.js';

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

@@ -15,6 +15,9 @@ export { toolsPhase } from './tools.js';
 export { ormPhase } from './orm.js';
 export { crossFilePhase } from './cross-file.js';
 export { scopeResolutionPhase, } from '../scope-resolution/pipeline/phase.js';
+export { springConfigPhase } from './spring-config.js';
+export { springAutoConfigurationPhase, } from './spring-auto-configuration.js';
+export { springAopPhase, springAopInheritancePhase, } from './spring-aop.js';
 export { pruneLocalSymbolsPhase } from './prune-local-symbols.js';
 export { taintSummariesPhase } from './taint-summaries.js';
 export { callSummariesPhase } from './call-summaries.js';

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

@@ -21,6 +21,21 @@ import { type PipelineProgress } from '../../../_shared/index.js';
 import type { ExtractedDecoratorRoute, ExtractedFetchCall, ExtractedORMQuery, ExtractedRoute, ExtractedToolDef, FetchWrapperDef } from '../workers/parse-worker.js';
 import type { KnowledgeGraph } from '../../graph/types.js';
 import type { PipelineOptions } from '../pipeline.js';
+/** Projected main-thread heap need for the parse phase (#2649). */
+export declare function projectParseHeapNeedBytes(parseableFileCount: number): number;
+/** True when the mid-loop heap guard should abort the parse (#2649). */
+export declare function shouldAbortForHeapPressure(heapUsedBytes: number, heapLimitBytes: number): boolean;
+/**
+ * The ONE action a user should take when this repository doesn't fit the
+ * current heap (#2649). Users hitting memory limits are already frustrated —
+ * a menu of env knobs at that moment is noise. Branch on whether the machine
+ * itself has more memory to give: if this process's limit sits well below
+ * what the RAM-aware auto-sizer would grant (an inherited NODE_OPTIONS pin or
+ * explicit flag), the fix is to drop the pin — gitnexus sizes itself.
+ * Otherwise the machine is the ceiling and only scope or hardware helps.
+ * Escape hatches (GITNEXUS_MEMORY etc.) stay in the README env table.
+ */
+export declare function heapPressureRemedy(heapLimitBytes: number): string;
 type ScannedFile = {
     path: string;
     size: number;