arceus-s 1.6.4

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

@@ -0,0 +1,204 @@
+/**
+ * Pipeline Phase Runner
+ *
+ * Executes pipeline phases in dependency order using Kahn's topological sort.
+ * Each phase receives typed outputs from its upstream dependencies.
+ *
+ * The runner is intentionally simple:
+ * - No dynamic phase loading
+ * - No plugin system
+ * - Static phase graph, compile-time type safety
+ * - Sequential execution (parallel support is architecturally possible
+ *   but most phases have linear dependencies)
+ */
+import { isDev } from '../utils/env.js';
+import { logger } from '../../logger.js';
+/**
+ * Validate that the phases form a valid dependency graph (no cycles, all deps present).
+ * Returns phases in topological execution order.
+ */
+function topologicalSort(phases) {
+    const phaseMap = new Map();
+    for (const phase of phases) {
+        if (phaseMap.has(phase.name)) {
+            throw new Error(`Duplicate phase name: '${phase.name}'`);
+        }
+        phaseMap.set(phase.name, phase);
+    }
+    // Validate all deps exist
+    for (const phase of phases) {
+        for (const dep of phase.deps) {
+            if (!phaseMap.has(dep)) {
+                throw new Error(`Phase '${phase.name}' depends on '${dep}', which is not registered`);
+            }
+        }
+    }
+    // Kahn's algorithm
+    const inDegree = new Map();
+    const reverseDeps = new Map();
+    for (const phase of phases) {
+        inDegree.set(phase.name, phase.deps.length);
+        for (const dep of phase.deps) {
+            let rev = reverseDeps.get(dep);
+            if (!rev) {
+                rev = [];
+                reverseDeps.set(dep, rev);
+            }
+            rev.push(phase.name);
+        }
+    }
+    const sorted = [];
+    const queue = [...inDegree.entries()].filter(([, d]) => d === 0).map(([name]) => name);
+    while (queue.length > 0) {
+        const name = queue.shift();
+        sorted.push(phaseMap.get(name));
+        for (const dependent of reverseDeps.get(name) ?? []) {
+            const newDeg = (inDegree.get(dependent) ?? 1) - 1;
+            inDegree.set(dependent, newDeg);
+            if (newDeg === 0)
+                queue.push(dependent);
+        }
+    }
+    if (sorted.length !== phases.length) {
+        const remaining = new Set([...inDegree.entries()].filter(([, d]) => d > 0).map(([name]) => name));
+        const cyclePath = findCyclePath(remaining, phaseMap);
+        const dependentsBlocked = remaining.size - new Set(cyclePath).size;
+        let message = `Cycle detected in pipeline phases: ${cyclePath.join(' -> ')}`;
+        if (dependentsBlocked > 0) {
+            message += ` (and ${dependentsBlocked} transitive dependent${dependentsBlocked === 1 ? '' : 's'} blocked)`;
+        }
+        throw new Error(message);
+    }
+    return sorted;
+}
+/**
+ * Find a concrete cycle path among the phases that Kahn's algorithm could not drain.
+ *
+ * Kahn's leftovers include both true cycle members AND phases transitively dependent
+ * on them. To produce an actionable error message, we DFS over the leftovers (using
+ * each leftover's `deps` as edges) until we hit a back-edge — that closes the cycle.
+ * The returned list is the cycle in order with the entry node repeated at the end:
+ * `[A, B, C, A]` for `A -> B -> C -> A`.
+ *
+ * Falls back to the raw remaining set (sorted) if no back-edge is found, which
+ * should be unreachable but keeps the error informative.
+ */
+function findCyclePath(remaining, phaseMap) {
+    for (const start of remaining) {
+        const stack = [];
+        const onStack = new Set();
+        const visited = new Set();
+        const dfs = (name) => {
+            stack.push(name);
+            onStack.add(name);
+            visited.add(name);
+            const phase = phaseMap.get(name);
+            if (phase) {
+                for (const dep of phase.deps) {
+                    if (!remaining.has(dep))
+                        continue; // dep already drained — not part of cycle
+                    if (onStack.has(dep)) {
+                        // Back-edge — slice from the first occurrence of `dep` and close the loop.
+                        const cycleStart = stack.indexOf(dep);
+                        return [...stack.slice(cycleStart), dep];
+                    }
+                    if (!visited.has(dep)) {
+                        const found = dfs(dep);
+                        if (found)
+                            return found;
+                    }
+                }
+            }
+            stack.pop();
+            onStack.delete(name);
+            return null;
+        };
+        const cycle = dfs(start);
+        if (cycle)
+            return cycle;
+    }
+    // Unreachable in practice (Kahn proved a cycle exists), but stay defensive.
+    return [...remaining].sort();
+}
+/**
+ * Execute a set of pipeline phases in dependency order.
+ *
+ * @param phases  All phases to execute (order doesn't matter — sorted internally)
+ * @param ctx     Shared pipeline context
+ * @returns       Map of phase name → PhaseResult (all completed phases)
+ */
+export async function runPipeline(phases, ctx) {
+    let sorted;
+    try {
+        sorted = topologicalSort(phases);
+    }
+    catch (err) {
+        // Emit a terminal 'error' progress event for graph-validation failures
+        // (cycle detected, duplicate phase, missing dep) so CLI/MCP consumers see
+        // the failure before the rejection propagates. Symmetric with the
+        // per-phase error path below. Best-effort: a throwing handler must not
+        // mask the underlying validation error.
+        const message = err instanceof Error ? err.message : String(err);
+        try {
+            ctx.onProgress({
+                phase: 'error',
+                percent: 100,
+                message: 'Pipeline graph validation failed',
+                detail: message,
+            });
+        }
+        catch {
+            // Swallow handler errors — preserving the original cause is more important.
+        }
+        throw err;
+    }
+    const results = new Map();
+    for (const phase of sorted) {
+        const start = Date.now();
+        if (isDev) {
+            logger.info(`▶ Phase: ${phase.name}`);
+        }
+        // Only expose declared dependencies — prevents hidden coupling to undeclared phases.
+        const declaredDeps = new Map();
+        for (const depName of phase.deps) {
+            const depResult = results.get(depName);
+            if (depResult)
+                declaredDeps.set(depName, depResult);
+        }
+        let output;
+        try {
+            output = await phase.execute(ctx, declaredDeps);
+        }
+        catch (err) {
+            const originalMessage = err instanceof Error ? err.message : String(err);
+            const wrapped = new Error(`Phase '${phase.name}' failed: ${originalMessage}`, {
+                cause: err,
+            });
+            // Emit a terminal 'error' progress event so CLI/MCP consumers see the failure
+            // before the rejection propagates. Best-effort: a throwing handler must not
+            // mask the underlying phase error.
+            try {
+                ctx.onProgress({
+                    phase: 'error',
+                    percent: 100,
+                    message: `Phase '${phase.name}' failed`,
+                    detail: originalMessage,
+                });
+            }
+            catch {
+                // Swallow handler errors — preserving the original cause is more important.
+            }
+            throw wrapped;
+        }
+        const durationMs = Date.now() - start;
+        results.set(phase.name, {
+            phaseName: phase.name,
+            output,
+            durationMs,
+        });
+        if (isDev) {
+            logger.info(`✓ Phase: ${phase.name} (${durationMs}ms)`);
+        }
+    }
+    return results;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Phase: scan
+ *
+ * Walks the repository filesystem and collects file paths + sizes.
+ * Does NOT read file contents — that happens in downstream phases.
+ *
+ * @deps    (none — this is the pipeline root)
+ * @reads   repoPath (filesystem)
+ * @writes  graph (nothing yet — just returns scanned paths)
+ * @output  ScannedFile[], allPaths[], totalFiles
+ */
+import type { PipelinePhase } from './types.js';
+export interface ScanOutput {
+    scannedFiles: {
+        path: string;
+        size: number;
+    }[];
+    allPaths: string[];
+    totalFiles: number;
+}
+export declare const scanPhase: PipelinePhase<ScanOutput>;

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

@@ -0,0 +1,46 @@
+/**
+ * Phase: scan
+ *
+ * Walks the repository filesystem and collects file paths + sizes.
+ * Does NOT read file contents — that happens in downstream phases.
+ *
+ * @deps    (none — this is the pipeline root)
+ * @reads   repoPath (filesystem)
+ * @writes  graph (nothing yet — just returns scanned paths)
+ * @output  ScannedFile[], allPaths[], totalFiles
+ */
+import { walkRepositoryPaths } from '../filesystem-walker.js';
+export const scanPhase = {
+    name: 'scan',
+    deps: [],
+    async execute(ctx) {
+        ctx.onProgress({
+            phase: 'extracting',
+            percent: 0,
+            message: 'Scanning repository...',
+        });
+        const scannedFiles = await walkRepositoryPaths(ctx.repoPath, (current, total, filePath) => {
+            const scanProgress = Math.round((current / total) * 15);
+            ctx.onProgress({
+                phase: 'extracting',
+                percent: scanProgress,
+                message: 'Scanning repository...',
+                detail: filePath,
+                stats: {
+                    filesProcessed: current,
+                    totalFiles: total,
+                    nodesCreated: ctx.graph.nodeCount,
+                },
+            });
+        });
+        const totalFiles = scannedFiles.length;
+        const allPaths = scannedFiles.map((f) => f.path);
+        ctx.onProgress({
+            phase: 'extracting',
+            percent: 15,
+            message: 'Repository scanned successfully',
+            stats: { filesProcessed: totalFiles, totalFiles, nodesCreated: ctx.graph.nodeCount },
+        });
+        return { scannedFiles, allPaths, totalFiles };
+    },
+};

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

@@ -0,0 +1,27 @@
+/**
+ * Phase: structure
+ *
+ * Builds File and Folder nodes in the graph from scanned paths.
+ *
+ * @deps    scan
+ * @reads   allPaths (from scan phase)
+ * @writes  graph (File, Folder nodes + CONTAINS edges)
+ */
+import type { PipelinePhase } from './types.js';
+/** Structure phase produces no additional data — it writes directly to the graph. */
+export interface StructureOutput {
+    /** Pass-through from scan for downstream phases. */
+    scannedFiles: {
+        path: string;
+        size: number;
+    }[];
+    allPaths: string[];
+    /**
+     * Materialized once here and shared across all downstream consumers
+     * (cobol, markdown, cross-file propagation). Avoids the previous
+     * per-phase `new Set(allPaths)` allocations on multi-thousand-file repos.
+     */
+    allPathSet: ReadonlySet<string>;
+    totalFiles: number;
+}
+export declare const structurePhase: PipelinePhase<StructureOutput>;

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

@@ -0,0 +1,35 @@
+/**
+ * Phase: structure
+ *
+ * Builds File and Folder nodes in the graph from scanned paths.
+ *
+ * @deps    scan
+ * @reads   allPaths (from scan phase)
+ * @writes  graph (File, Folder nodes + CONTAINS edges)
+ */
+import { getPhaseOutput } from './types.js';
+import { processStructure } from '../structure-processor.js';
+export const structurePhase = {
+    name: 'structure',
+    deps: ['scan'],
+    async execute(ctx, deps) {
+        const { scannedFiles, allPaths, totalFiles } = getPhaseOutput(deps, 'scan');
+        ctx.onProgress({
+            phase: 'structure',
+            percent: 15,
+            message: 'Analyzing project structure...',
+            stats: { filesProcessed: 0, totalFiles, nodesCreated: ctx.graph.nodeCount },
+        });
+        processStructure(ctx.graph, allPaths);
+        ctx.onProgress({
+            phase: 'structure',
+            percent: 20,
+            message: 'Project structure analyzed',
+            stats: { filesProcessed: totalFiles, totalFiles, nodesCreated: ctx.graph.nodeCount },
+        });
+        // Build the set once here so cobol, markdown, and cross-file propagation
+        // can all reuse it instead of re-materializing `new Set(allPaths)` each.
+        const allPathSet = new Set(allPaths);
+        return { scannedFiles, allPaths, allPathSet, totalFiles };
+    },
+};

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

@@ -0,0 +1,21 @@
+/**
+ * Phase: tools
+ *
+ * Detects MCP/RPC tool definitions and creates Tool graph nodes.
+ *
+ * @deps    parse
+ * @reads   allToolDefs (from parse), allPaths
+ * @writes  graph (Tool nodes, HANDLES_TOOL edges)
+ * @output  toolDefs array
+ */
+import type { PipelinePhase } from './types.js';
+export interface ToolDef {
+    name: string;
+    filePath: string;
+    description: string;
+    handlerNodeId?: string;
+}
+export interface ToolsOutput {
+    toolDefs: ToolDef[];
+}
+export declare const toolsPhase: PipelinePhase<ToolsOutput>;

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

@@ -0,0 +1,86 @@
+/**
+ * Phase: tools
+ *
+ * Detects MCP/RPC tool definitions and creates Tool graph nodes.
+ *
+ * @deps    parse
+ * @reads   allToolDefs (from parse), allPaths
+ * @writes  graph (Tool nodes, HANDLES_TOOL edges)
+ * @output  toolDefs array
+ */
+import { getPhaseOutput } from './types.js';
+import { generateId } from '../../../lib/utils.js';
+import { readFileContents } from '../filesystem-walker.js';
+import { isDev } from '../utils/env.js';
+import { logger } from '../../logger.js';
+export const toolsPhase = {
+    name: 'tools',
+    deps: ['parse'],
+    async execute(ctx, deps) {
+        const { allToolDefs, allPaths } = getPhaseOutput(deps, 'parse');
+        const toolDefs = [];
+        const seenToolNames = new Set();
+        for (const td of allToolDefs) {
+            if (seenToolNames.has(td.toolName))
+                continue;
+            seenToolNames.add(td.toolName);
+            const handlerNodeId = td.handlerNodeId && ctx.graph.getNode(td.handlerNodeId) ? td.handlerNodeId : undefined;
+            toolDefs.push({
+                name: td.toolName,
+                filePath: td.filePath,
+                description: td.description,
+                ...(handlerNodeId !== undefined ? { handlerNodeId } : {}),
+            });
+        }
+        // TS tool definition arrays — require inputSchema nearby
+        const toolCandidatePaths = allPaths.filter((p) => (p.endsWith('.ts') || p.endsWith('.js')) &&
+            p.toLowerCase().includes('tool') &&
+            !p.includes('node_modules') &&
+            !p.includes('test') &&
+            !p.includes('__'));
+        if (toolCandidatePaths.length > 0) {
+            const toolContents = await readFileContents(ctx.repoPath, toolCandidatePaths);
+            for (const [filePath, content] of toolContents) {
+                if (!content.includes('inputSchema'))
+                    continue;
+                const toolPattern = /name:\s*['"](\w+)['"]\s*,\s*\n?\s*description:\s*[`'"]([\s\S]*?)[`'"]/g;
+                let match;
+                while ((match = toolPattern.exec(content)) !== null) {
+                    const name = match[1];
+                    if (seenToolNames.has(name))
+                        continue;
+                    seenToolNames.add(name);
+                    toolDefs.push({
+                        name,
+                        filePath,
+                        description: match[2].slice(0, 200).replace(/\n/g, ' ').trim(),
+                    });
+                }
+            }
+        }
+        // Create Tool nodes and HANDLES_TOOL edges
+        if (toolDefs.length > 0) {
+            for (const td of toolDefs) {
+                const toolNodeId = generateId('Tool', td.name);
+                ctx.graph.addNode({
+                    id: toolNodeId,
+                    label: 'Tool',
+                    properties: { name: td.name, filePath: td.filePath, description: td.description },
+                });
+                const handlerId = td.handlerNodeId ?? generateId('File', td.filePath);
+                ctx.graph.addRelationship({
+                    id: generateId('HANDLES_TOOL', `${handlerId}->${toolNodeId}`),
+                    sourceId: handlerId,
+                    targetId: toolNodeId,
+                    type: 'HANDLES_TOOL',
+                    confidence: 1.0,
+                    reason: 'tool-definition',
+                });
+            }
+            if (isDev) {
+                logger.info(`🔧 Tool registry: ${toolDefs.length} tools detected`);
+            }
+        }
+        return { toolDefs };
+    },
+};

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

@@ -0,0 +1,79 @@
+/**
+ * Pipeline Phase — Type definitions.
+ *
+ * Each phase is a named node in the dependency graph with typed inputs and outputs.
+ * The runner resolves dependencies via topological sort and passes
+ * typed results from upstream phases as inputs to downstream phases.
+ *
+ * Design goals:
+ *  - Explicit data flow between phases via typed outputs
+ *  - The knowledge graph is a shared mutable accumulator — phases add nodes/edges
+ *    and may read prior phases' contributions. This is intentional: the graph is
+ *    the pipeline's primary output, not an inter-phase communication channel.
+ *  - Compile-time exhaustiveness (adding a phase = type error until wired)
+ *  - Each phase is independently testable with mocked inputs
+ */
+import type { KnowledgeGraph } from '../../graph/types.js';
+import type { PipelineProgress } from '../../../_shared/index.js';
+import type { PipelineOptions } from '../pipeline.js';
+/** Immutable context available to every phase. */
+export interface PipelineContext {
+    /** Absolute path to the repository root. */
+    readonly repoPath: string;
+    /** Mutable knowledge graph — the single shared accumulator. */
+    readonly graph: KnowledgeGraph;
+    /** Progress callback for UI updates. */
+    readonly onProgress: (progress: PipelineProgress) => void;
+    /** Pipeline options (skipGraphPhases, skipWorkers, etc.). */
+    readonly options?: PipelineOptions;
+    /** Pipeline start timestamp (for elapsed-time logging). */
+    readonly pipelineStart: number;
+}
+/** Wraps a phase's output with timing metadata. */
+export interface PhaseResult<T> {
+    /** Phase name (matches the phase's `name` field). */
+    readonly phaseName: string;
+    /** The typed output of the phase. */
+    readonly output: T;
+    /** Wall-clock duration in milliseconds. */
+    readonly durationMs: number;
+}
+/**
+ * A single phase in the ingestion pipeline.
+ *
+ * @typeParam TDeps - Tuple of dependency phase output types
+ * @typeParam TOutput - This phase's output type
+ */
+export interface PipelinePhase<TOutput = unknown> {
+    /** Unique name for logging and result lookup. */
+    readonly name: string;
+    /**
+     * Names of phases this phase depends on.
+     * The runner guarantees these have completed before execute() is called.
+     */
+    readonly deps: readonly string[];
+    /**
+     * Execute the phase.
+     *
+     * @param ctx    Shared pipeline context (graph, repoPath, progress, options)
+     * @param deps   Map of dependency name → PhaseResult (typed outputs from upstream phases)
+     * @returns      The phase's typed output
+     */
+    execute(ctx: PipelineContext, deps: ReadonlyMap<string, PhaseResult<unknown>>): Promise<TOutput>;
+}
+/**
+ * Helper to extract the typed output of a dependency phase.
+ *
+ * Type safety note: This uses an `as T` cast because the runner stores
+ * heterogeneous phase outputs in a single `Map<string, PhaseResult<unknown>>`.
+ * The cast is safe as long as callers use the correct output type for the
+ * named phase. Mismatches will surface as runtime type errors, not compile-time
+ * errors — this is an intentional trade-off for a static phase graph without
+ * a dynamic type registry.
+ *
+ * @param deps       The resolved dependency map from the runner
+ * @param phaseName  The name of the upstream phase whose output you need
+ * @returns          The typed output of the phase
+ * @throws           If the phase is not found in the dependency map
+ */
+export declare function getPhaseOutput<T>(deps: ReadonlyMap<string, PhaseResult<unknown>>, phaseName: string): T;

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

@@ -0,0 +1,37 @@
+/**
+ * Pipeline Phase — Type definitions.
+ *
+ * Each phase is a named node in the dependency graph with typed inputs and outputs.
+ * The runner resolves dependencies via topological sort and passes
+ * typed results from upstream phases as inputs to downstream phases.
+ *
+ * Design goals:
+ *  - Explicit data flow between phases via typed outputs
+ *  - The knowledge graph is a shared mutable accumulator — phases add nodes/edges
+ *    and may read prior phases' contributions. This is intentional: the graph is
+ *    the pipeline's primary output, not an inter-phase communication channel.
+ *  - Compile-time exhaustiveness (adding a phase = type error until wired)
+ *  - Each phase is independently testable with mocked inputs
+ */
+/**
+ * Helper to extract the typed output of a dependency phase.
+ *
+ * Type safety note: This uses an `as T` cast because the runner stores
+ * heterogeneous phase outputs in a single `Map<string, PhaseResult<unknown>>`.
+ * The cast is safe as long as callers use the correct output type for the
+ * named phase. Mismatches will surface as runtime type errors, not compile-time
+ * errors — this is an intentional trade-off for a static phase graph without
+ * a dynamic type registry.
+ *
+ * @param deps       The resolved dependency map from the runner
+ * @param phaseName  The name of the upstream phase whose output you need
+ * @returns          The typed output of the phase
+ * @throws           If the phase is not found in the dependency map
+ */
+export function getPhaseOutput(deps, phaseName) {
+    const result = deps.get(phaseName);
+    if (!result) {
+        throw new Error(`Phase '${phaseName}' not found in resolved dependencies`);
+    }
+    return result.output;
+}

package/dist/core/ingestion/pipeline-phases/wildcard-synthesis.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Wildcard import binding synthesis.
+ *
+ * Languages with whole-module import semantics (Go, Ruby, C/C++, Swift)
+ * import all exported symbols from a file, not specific named symbols.
+ * After parsing, we know which symbols each file exports (via graph
+ * `isExported`), so we can expand IMPORTS edges into per-symbol bindings
+ * that the cross-file propagation phase can use for type resolution.
+ *
+ * Also builds Python module-alias maps for namespace-import languages
+ * (`import models` → `models.User()` resolves to `models.py:User`).
+ *
+ * @module
+ */
+import type { KnowledgeGraph } from '../../graph/types.js';
+import type { createResolutionContext } from '../model/resolution-context.js';
+import type { SupportedLanguages } from '../../../_shared/index.js';
+/** Check if a language uses wildcard (whole-module) import semantics. */
+export declare function isWildcardImportLanguage(lang: SupportedLanguages): boolean;
+/** Check if a language needs synthesis before call resolution.
+ *  True for wildcard-import languages AND namespace-import languages (Python). */
+export declare function needsSynthesis(lang: SupportedLanguages): boolean;
+/**
+ * Strategy implementation for `importSemantics: 'wildcard-transitive'` (C, C++).
+ *
+ * Textual-include languages chain symbols through files: if `dict.c` includes
+ * `server.h` and `server.h` includes `dict.h`, then `dict.c` sees symbols from
+ * all three files. This helper walks the include graph (combining both the
+ * ingestion-context `importMap` and the graph-level IMPORTS edges) until the
+ * closure is stable.
+ *
+ * **Order matters.** The returned `Set` preserves iteration order (insertion
+ * order). `synthesizeWildcardImportBindings` dedupes bindings by symbol name
+ * on a first-seen-wins basis, so this closure's ordering determines which
+ * declaration wins when multiple headers export the same name (e.g. overloaded
+ * free functions like `write_audit()` vs `write_audit(const char*)` in
+ * different headers). We therefore:
+ *   1. Seed the closure with direct imports in declaration order (matches the
+ *      order of `#include` directives in the source file).
+ *   2. Use FIFO / true BFS (`queue.shift()`) for transitive expansion, so
+ *      closer headers are seen before deeper ones.
+ *
+ * Cycle-safe: the `closure.has(file)` guard prevents infinite loops on circular
+ * header includes, which are valid C/C++ when paired with `#pragma once` or
+ * include guards.
+ *
+ * Size-bounded: the closure is capped at `MAX_TRANSITIVE_CLOSURE_SIZE` files to
+ * prevent OOM on pathological codebases (e.g. boost, monoheader kernel code)
+ * where one translation unit can transitively reach tens of thousands of
+ * headers. Partial closures still yield useful bindings for the cluster of
+ * headers closest to the importer, which is what overload resolution and
+ * cross-file call resolution care about.
+ *
+ * Queue implementation: uses a head-index over a growing array (O(1) dequeue)
+ * instead of `Array.prototype.shift()` (O(n)) so deep chains stay linear.
+ */
+export declare function expandTransitiveIncludeClosure(directImports: Iterable<string>, importMap: ReadonlyMap<string, ReadonlySet<string>>, graphImports: ReadonlyMap<string, ReadonlySet<string>>): Set<string>;
+/**
+ * Synthesize namedImportMap entries for languages with whole-module imports.
+ *
+ * For each file that imports another file via wildcard semantics:
+ * 1. Look up all exported symbols from the imported file (via graph nodes)
+ * 2. Create synthetic named bindings: `{ name → { sourcePath, exportedName } }`
+ * 3. Build Python module-alias maps for namespace-import languages
+ *
+ * @param graph  The knowledge graph with parsed symbol nodes
+ * @param ctx    Resolution context with importMap and namedImportMap
+ * @returns      Number of synthetic bindings created
+ */
+export declare function synthesizeWildcardImportBindings(graph: KnowledgeGraph, ctx: ReturnType<typeof createResolutionContext>): number;