gitnexus 1.6.3-rc.9 → 1.6.3

package/dist/core/ingestion/emit-references.js

@@ -0,0 +1,229 @@
+/**
+ * Phase 5 of the RFC #909 ingestion lifecycle: drain `ReferenceIndex`
+ * into the knowledge graph as labeled edges with `confidence` and
+ * `evidence` properties (Ring 2 PKG #925).
+ *
+ * The resolution phase (future PR) writes `Reference` records into
+ * `model.scopes.referenceSites`-derived `ReferenceIndex`; this module
+ * materializes those records as `GraphRelationship`s via
+ * `graph.addRelationship`. Every emitted edge carries:
+ *
+ *   - `type`: one of `'CALLS' | 'ACCESSES' | 'INHERITS' | 'USES'`
+ *     (mapped from `Reference.kind` — `'read'` and `'write'` both route
+ *     to `ACCESSES`; `'type-reference'` and `'import-use'` route to
+ *     `USES`; `'call'` stays `CALLS`; `'inherits'` stays `INHERITS`).
+ *   - `confidence`: the pre-computed confidence from the Reference record.
+ *   - `reason`: human-readable summary (`"scope-resolution: call | confidence 0.75"`).
+ *   - `evidence`: the full `ResolutionEvidence[]` trace — additive graph
+ *     property (see `GraphRelationship.evidence` in gitnexus-shared),
+ *     so queries that don't know about it are unaffected.
+ *   - `step`: carries the reference's access-kind discriminant when
+ *     available (`1` for read, `2` for write) so `ACCESSES` edges retain
+ *     the read/write distinction without forcing a new edge type.
+ *
+ * ## Optional scope-tree flush
+ *
+ * When `INGESTION_EMIT_SCOPES=1` is set, this module also emits:
+ *
+ *   - `Scope` nodes for every `Scope` in the tree
+ *   - `CONTAINS` edges from parent scope to child scope
+ *   - `DEFINES` edges from scope to its `ownedDefs` members
+ *   - `IMPORTS` edges from scope to `targetModuleScope` of each finalized
+ *     `ImportEdge` that carries one
+ *
+ * Off by default — existing queries that don't know about `Scope` nodes
+ * continue to work, and the storage cost is opt-in.
+ *
+ * ## Source-of-truth: the caller def for a reference
+ *
+ * A `Reference` says "some code inside `fromScope` references `toDef`".
+ * The graph wants `(callerNodeId, calleeNodeId)`. We resolve the caller
+ * by walking up the scope tree from `fromScope` until we find a scope
+ * whose `ownedDefs` contains a Function-like def. If no such ancestor
+ * exists, the edge is attributed to the first def owned by the innermost
+ * ancestor scope, and if THAT produces nothing either the edge is
+ * skipped (with a count returned in `EmitStats.skippedNoCaller`).
+ */
+/**
+ * Drain `referenceIndex.bySourceScope` into graph edges.
+ *
+ * The scope-tree flush is controlled separately by
+ * `INGESTION_EMIT_SCOPES` — callers can run `emitReferencesToGraph`
+ * without scope-node emission or layer the two calls as needed.
+ */
+export function emitReferencesToGraph(input) {
+    const { graph, scopes, referenceIndex } = input;
+    const sourceLabel = input.sourceLabel ?? 'scope-resolution';
+    let edgesEmitted = 0;
+    let skippedNoCaller = 0;
+    let skippedMissingTarget = 0;
+    for (const [fromScope, refs] of referenceIndex.bySourceScope) {
+        for (const ref of refs) {
+            const targetDef = scopes.defs.get(ref.toDef);
+            if (targetDef === undefined) {
+                skippedMissingTarget++;
+                continue;
+            }
+            const callerId = resolveCallerNodeId(fromScope, scopes);
+            if (callerId === undefined) {
+                skippedNoCaller++;
+                continue;
+            }
+            graph.addRelationship(buildRelationship(ref, callerId, targetDef, sourceLabel));
+            edgesEmitted++;
+        }
+    }
+    const scopeStats = isScopeEmissionEnabled()
+        ? emitScopeGraph({ graph, scopes })
+        : { scopeNodesEmitted: 0, scopeEdgesEmitted: 0 };
+    return { edgesEmitted, skippedNoCaller, skippedMissingTarget, ...scopeStats };
+}
+/**
+ * Emit `Scope` nodes + `CONTAINS`/`DEFINES`/`IMPORTS` edges representing
+ * the lexical scope tree itself. Skipped unless `INGESTION_EMIT_SCOPES=1`
+ * at the public entry point; exported here for tests that want to
+ * exercise the path directly.
+ */
+export function emitScopeGraph(input) {
+    const { graph, scopes } = input;
+    let scopeNodesEmitted = 0;
+    let scopeEdgesEmitted = 0;
+    for (const scope of scopes.scopeTree.byId.values()) {
+        graph.addNode({
+            id: scope.id,
+            label: 'CodeElement', // the generic bucket for non-symbol graph nodes
+            properties: {
+                name: scope.kind,
+                filePath: scope.filePath,
+                startLine: scope.range.startLine,
+                endLine: scope.range.endLine,
+                description: `Scope: ${scope.kind}`,
+            },
+        });
+        scopeNodesEmitted++;
+        if (scope.parent !== null) {
+            graph.addRelationship({
+                id: `rel:contains:${scope.parent}->${scope.id}`,
+                sourceId: scope.parent,
+                targetId: scope.id,
+                type: 'CONTAINS',
+                confidence: 1,
+                reason: 'scope-tree parent/child',
+            });
+            scopeEdgesEmitted++;
+        }
+        for (const def of scope.ownedDefs) {
+            graph.addRelationship({
+                id: `rel:defines:${scope.id}->${def.nodeId}`,
+                sourceId: scope.id,
+                targetId: def.nodeId,
+                type: 'DEFINES',
+                confidence: 1,
+                reason: 'scope.ownedDefs',
+            });
+            scopeEdgesEmitted++;
+        }
+    }
+    for (const [scopeId, edges] of scopes.imports) {
+        for (const edge of edges) {
+            if (edge.targetModuleScope === undefined)
+                continue;
+            graph.addRelationship({
+                id: `rel:imports:${scopeId}->${edge.targetModuleScope}:${edge.localName}`,
+                sourceId: scopeId,
+                targetId: edge.targetModuleScope,
+                type: 'IMPORTS',
+                confidence: edge.linkStatus === 'unresolved' ? 0.5 : 1,
+                reason: `import ${edge.kind} ${edge.localName}`,
+            });
+            scopeEdgesEmitted++;
+        }
+    }
+    return { scopeNodesEmitted, scopeEdgesEmitted };
+}
+// ─── Internal ───────────────────────────────────────────────────────────────
+/** Accepted truthy values for `INGESTION_EMIT_SCOPES`. */
+const TRUTHY = new Set(['true', '1', 'yes']);
+function isScopeEmissionEnabled() {
+    const raw = process.env['INGESTION_EMIT_SCOPES'];
+    if (raw === undefined)
+        return false;
+    return TRUTHY.has(raw.trim().toLowerCase());
+}
+/**
+ * Walk up from `startScope` looking for the first ancestor scope whose
+ * `ownedDefs` contains a Function-like def (Function / Method /
+ * Constructor). Fall back to the innermost ancestor's first `ownedDef`
+ * if none is found; return `undefined` if all ancestors have no defs.
+ */
+function resolveCallerNodeId(startScope, scopes) {
+    const tree = scopes.scopeTree;
+    let current = startScope;
+    const visited = new Set();
+    let firstOwnedFallback;
+    while (current !== null) {
+        if (visited.has(current))
+            break;
+        visited.add(current);
+        const scope = tree.getScope(current);
+        if (scope === undefined)
+            break;
+        // Prefer a Function-like owner.
+        const fnDef = scope.ownedDefs.find((d) => isFunctionLike(d.type));
+        if (fnDef !== undefined)
+            return fnDef.nodeId;
+        // Stash the first owned def we see as a conservative fallback.
+        if (firstOwnedFallback === undefined && scope.ownedDefs.length > 0) {
+            firstOwnedFallback = scope.ownedDefs[0].nodeId;
+        }
+        current = scope.parent;
+    }
+    return firstOwnedFallback;
+}
+function isFunctionLike(type) {
+    return type === 'Function' || type === 'Method' || type === 'Constructor';
+}
+function buildRelationship(ref, callerId, targetDef, sourceLabel) {
+    const type = mapKindToType(ref.kind);
+    const reason = `${sourceLabel}: ${ref.kind} | confidence ${ref.confidence.toFixed(3)}`;
+    // `step` encodes read/write discriminator for ACCESSES edges (1=read, 2=write).
+    // Other kinds omit `step`.
+    const step = ref.kind === 'read' ? 1 : ref.kind === 'write' ? 2 : undefined;
+    return {
+        id: `rel:${type}:${callerId}->${targetDef.nodeId}:${ref.atRange.startLine}:${ref.atRange.startCol}`,
+        sourceId: callerId,
+        targetId: targetDef.nodeId,
+        type,
+        confidence: ref.confidence,
+        reason,
+        evidence: ref.evidence.map(serializeEvidence),
+        ...(step !== undefined ? { step } : {}),
+    };
+}
+/**
+ * Map a `Reference.kind` to an existing `RelationshipType`. Read/write
+ * both fold into `ACCESSES`; `type-reference` + `import-use` both fold
+ * into `USES`. This keeps the graph schema additive — no new
+ * RelationshipType values are introduced by this module.
+ */
+function mapKindToType(kind) {
+    switch (kind) {
+        case 'call':
+            return 'CALLS';
+        case 'read':
+        case 'write':
+            return 'ACCESSES';
+        case 'inherits':
+            return 'INHERITS';
+        case 'type-reference':
+        case 'import-use':
+            return 'USES';
+    }
+}
+function serializeEvidence(e) {
+    return {
+        kind: e.kind,
+        weight: e.weight,
+        ...(e.note !== undefined ? { note: e.note } : {}),
+    };
+}

package/dist/core/ingestion/filesystem-walker.js

@@ -1,17 +1,17 @@
 import { isVerboseIngestionEnabled } from './utils/verbose.js';
+import { DEFAULT_MAX_FILE_SIZE_BYTES, getMaxFileSizeBytes } from './utils/max-file-size.js';
 import fs from 'fs/promises';
 import path from 'path';
 import { glob } from 'glob';
 import { createIgnoreFilter } from '../../config/ignore-service.js';
 const READ_CONCURRENCY = 32;
-/** Skip files larger than 512KB — they're usually generated/vendored and crash tree-sitter */
-const MAX_FILE_SIZE = 512 * 1024;
 /**
  * Phase 1: Scan repository — stat files to get paths + sizes, no content loaded.
  * Memory: ~10MB for 100K files vs ~1GB+ with content.
  */
 export const walkRepositoryPaths = async (repoPath, onProgress) => {
     const ignoreFilter = await createIgnoreFilter(repoPath);
+    const maxFileSizeBytes = getMaxFileSizeBytes();
     const filtered = await glob('**/*', {
         cwd: repoPath,
         nodir: true,
@@ -27,7 +27,7 @@ export const walkRepositoryPaths = async (repoPath, onProgress) => {
         const results = await Promise.allSettled(batch.map(async (relativePath) => {
             const fullPath = path.join(repoPath, relativePath);
             const stat = await fs.stat(fullPath);
-            if (stat.size > MAX_FILE_SIZE) {
+            if (stat.size > maxFileSizeBytes) {
                 skippedLarge++;
                 skippedLargePaths.push(relativePath.replace(/\\/g, '/'));
                 return null;
@@ -46,7 +46,9 @@ export const walkRepositoryPaths = async (repoPath, onProgress) => {
         }
     }
     if (skippedLarge > 0) {
-        console.warn(`  Skipped ${skippedLarge} large files (>${MAX_FILE_SIZE / 1024}KB, likely generated/vendored)`);
+        const isDefault = maxFileSizeBytes === DEFAULT_MAX_FILE_SIZE_BYTES;
+        const suffix = isDefault ? ', likely generated/vendored' : '';
+        console.warn(`  Skipped ${skippedLarge} large files (>${maxFileSizeBytes / 1024}KB${suffix})`);
         if (isVerboseIngestionEnabled()) {
             for (const p of skippedLargePaths) {
                 console.warn(`  - ${p}`);

package/dist/core/ingestion/finalize-orchestrator.d.ts

@@ -0,0 +1,63 @@
+/**
+ * `finalizeScopeModel` — turn a workspace's `ParsedFile[]` into a
+ * materialized `ScopeResolutionIndexes` (RFC §3.2 Phase 2; Ring 2 PKG #921).
+ *
+ * Thin integration glue, per issue #884's boundary: all algorithmic logic
+ * lives in `gitnexus-shared` (finalize algorithm #915, the four per-file
+ * indexes #913, the method-dispatch materialization #914, the scope tree
+ * #912). This file does three things only:
+ *
+ *   1. Map `ParsedFile[]` → `FinalizeInput` and call shared `finalize()`.
+ *   2. Build the four workspace-wide indexes from the union of per-file
+ *      defs/scopes/modules/qualified-names.
+ *   3. Bundle the results into `ScopeResolutionIndexes` for
+ *      `MutableSemanticModel.attachScopeIndexes(...)`.
+ *
+ * ## What this module is NOT responsible for
+ *
+ *   - Invoking tree-sitter or running AST walks. That's the extractor (#919).
+ *   - Per-language import-target resolution. Hooks are plumbed through
+ *     but default to "unresolved" when no provider supplies them — the
+ *     real adapters land with #922.
+ *   - Populating `ReferenceIndex`. That's the resolution phase (#925).
+ *   - Deciding which language uses registry-primary lookup. That's the
+ *     flag reader (#924).
+ *
+ * ## Empty-input behavior
+ *
+ * When `parsedFiles` is empty (the common case today — no language has
+ * migrated yet), the orchestrator produces a valid but empty bundle: all
+ * indexes are zero-sized, the scope tree is empty, and
+ * `finalize.stats.totalFiles === 0`. This lets downstream consumers
+ * safely consult `model.scopes` without branching on presence.
+ */
+import type { FinalizeHooks, ParsedFile, WorkspaceIndex } from '../../_shared/index.js';
+import type { ScopeResolutionIndexes } from './model/scope-resolution-indexes.js';
+/**
+ * Options forwarded to the orchestrator. All fields optional so callers
+ * that don't yet have per-language hooks (today) get sensible defaults;
+ * #922 will populate `hooks.resolveImportTarget` + friends per language.
+ */
+export interface FinalizeOrchestratorOptions {
+    /**
+     * Hooks forwarded to shared `finalize()`. Any omitted field gets a
+     * no-op default: unresolved targets, empty wildcard expansion, append
+     * merge for bindings.
+     */
+    readonly hooks?: Partial<FinalizeHooks>;
+    /**
+     * Opaque workspace context forwarded to hooks. `undefined` today; Ring
+     * 2 PKG #922 populates this with a real cross-file index for the
+     * per-language resolvers.
+     */
+    readonly workspaceIndex?: WorkspaceIndex;
+}
+/**
+ * Produce a fully materialized `ScopeResolutionIndexes` from the
+ * workspace's per-file artifacts.
+ *
+ * Pure function (given pure hooks). No I/O, no globals consulted. The
+ * pipeline calls this once per ingestion run and hands the result to
+ * `MutableSemanticModel.attachScopeIndexes`.
+ */
+export declare function finalizeScopeModel(parsedFiles: readonly ParsedFile[], options?: FinalizeOrchestratorOptions): ScopeResolutionIndexes;

package/dist/core/ingestion/finalize-orchestrator.js

@@ -0,0 +1,139 @@
+/**
+ * `finalizeScopeModel` — turn a workspace's `ParsedFile[]` into a
+ * materialized `ScopeResolutionIndexes` (RFC §3.2 Phase 2; Ring 2 PKG #921).
+ *
+ * Thin integration glue, per issue #884's boundary: all algorithmic logic
+ * lives in `gitnexus-shared` (finalize algorithm #915, the four per-file
+ * indexes #913, the method-dispatch materialization #914, the scope tree
+ * #912). This file does three things only:
+ *
+ *   1. Map `ParsedFile[]` → `FinalizeInput` and call shared `finalize()`.
+ *   2. Build the four workspace-wide indexes from the union of per-file
+ *      defs/scopes/modules/qualified-names.
+ *   3. Bundle the results into `ScopeResolutionIndexes` for
+ *      `MutableSemanticModel.attachScopeIndexes(...)`.
+ *
+ * ## What this module is NOT responsible for
+ *
+ *   - Invoking tree-sitter or running AST walks. That's the extractor (#919).
+ *   - Per-language import-target resolution. Hooks are plumbed through
+ *     but default to "unresolved" when no provider supplies them — the
+ *     real adapters land with #922.
+ *   - Populating `ReferenceIndex`. That's the resolution phase (#925).
+ *   - Deciding which language uses registry-primary lookup. That's the
+ *     flag reader (#924).
+ *
+ * ## Empty-input behavior
+ *
+ * When `parsedFiles` is empty (the common case today — no language has
+ * migrated yet), the orchestrator produces a valid but empty bundle: all
+ * indexes are zero-sized, the scope tree is empty, and
+ * `finalize.stats.totalFiles === 0`. This lets downstream consumers
+ * safely consult `model.scopes` without branching on presence.
+ */
+import { buildDefIndex, buildMethodDispatchIndex, buildModuleScopeIndex, buildQualifiedNameIndex, buildScopeTree, finalize, } from '../../_shared/index.js';
+/**
+ * Produce a fully materialized `ScopeResolutionIndexes` from the
+ * workspace's per-file artifacts.
+ *
+ * Pure function (given pure hooks). No I/O, no globals consulted. The
+ * pipeline calls this once per ingestion run and hands the result to
+ * `MutableSemanticModel.attachScopeIndexes`.
+ */
+export function finalizeScopeModel(parsedFiles, options = {}) {
+    const hooks = withDefaultHooks(options.hooks ?? {});
+    const workspaceIndex = options.workspaceIndex ?? undefined;
+    // ── Step 1: Shared finalize — runs SCC-aware cross-file link + binding
+    // materialization. Returns linked imports + merged bindings per module
+    // scope + SCC condensation + stats.
+    const finalizeInput = {
+        files: parsedFiles.map(toFinalizeFile),
+        workspaceIndex,
+    };
+    const finalizeOut = finalize(finalizeInput, hooks);
+    // ── Step 2: Workspace-wide indexes built from the per-file unions.
+    // These are pure aggregations — no algorithm beyond what the builders
+    // in gitnexus-shared already encapsulate (first-write-wins, qname
+    // collision buckets, etc.).
+    const allScopes = [];
+    const allDefs = [];
+    const moduleEntries = [];
+    const allReferenceSites = [];
+    for (const file of parsedFiles) {
+        for (const s of file.scopes)
+            allScopes.push(s);
+        for (const d of file.localDefs)
+            allDefs.push(d);
+        moduleEntries.push({ filePath: file.filePath, moduleScopeId: file.moduleScope });
+    }
+    // References kept out of the loop above to centralize list-init.
+    allReferenceSites.push(...collectReferenceSites(parsedFiles));
+    const scopeTree = buildScopeTree(allScopes);
+    const defs = buildDefIndex(allDefs);
+    const qualifiedNames = buildQualifiedNameIndex(allDefs);
+    const moduleScopes = buildModuleScopeIndex(moduleEntries);
+    // ── Step 3: MethodDispatchIndex. Today we lack per-language MRO
+    // strategies wired into this orchestrator (that belongs with the
+    // HeritageMap bridge, a separate piece of work). Ship an EMPTY index
+    // so the bundle shape is consistent; the callbacks return `[]` for
+    // every owner and `implementsOf` returns `[]`. Populating this
+    // properly is tracked alongside the per-language provider hooks.
+    const methodDispatch = buildMethodDispatchIndex({
+        owners: [], // empty → no MRO entries; `mroFor(x)` returns the frozen empty array
+        computeMro: () => [],
+        implementsOf: () => [],
+    });
+    return {
+        scopeTree,
+        defs,
+        qualifiedNames,
+        moduleScopes,
+        methodDispatch,
+        imports: finalizeOut.imports,
+        bindings: finalizeOut.bindings,
+        referenceSites: Object.freeze([...allReferenceSites]),
+        sccs: finalizeOut.sccs,
+        stats: finalizeOut.stats,
+    };
+}
+// ─── Internal ───────────────────────────────────────────────────────────────
+/** Shape-reduce a `ParsedFile` to the narrower `FinalizeFile` the shared
+ *  algorithm reads. The subset is stable — `FinalizeFile` is a proper
+ *  subset of `ParsedFile`. */
+function toFinalizeFile(file) {
+    return {
+        filePath: file.filePath,
+        moduleScope: file.moduleScope,
+        parsedImports: file.parsedImports,
+        localDefs: file.localDefs,
+    };
+}
+/** Flatten every file's reference sites into one list. Order reflects
+ *  input-file order, then capture order inside each file. Deterministic. */
+function collectReferenceSites(parsedFiles) {
+    const out = [];
+    for (const file of parsedFiles) {
+        for (const site of file.referenceSites)
+            out.push(site);
+    }
+    return out;
+}
+/**
+ * Fill in no-op defaults for any omitted hook. Keeps `finalize()`
+ * behavior well-defined for the zero-provider case today:
+ *
+ *   - `resolveImportTarget: () => null` — every import edge ends up
+ *     `linkStatus: 'unresolved'` (or dynamic-unresolved pass-through).
+ *   - `expandsWildcardTo: () => []` — wildcards don't materialize.
+ *   - `mergeBindings: (existing, incoming) => [...existing, ...incoming]`
+ *     — append without precedence; providers override to implement local-
+ *     shadows-import and similar rules.
+ */
+function withDefaultHooks(partial) {
+    return {
+        resolveImportTarget: partial.resolveImportTarget ?? (() => null),
+        expandsWildcardTo: partial.expandsWildcardTo ?? (() => []),
+        mergeBindings: partial.mergeBindings ??
+            ((existing, incoming) => [...existing, ...incoming]),
+    };
+}

package/dist/core/ingestion/framework-detection.js

@@ -21,10 +21,14 @@ import { SupportedLanguages } from '../../_shared/index.js';
  */
 export function detectFrameworkFromPath(filePath) {
     // Normalize path separators and ensure leading slash for consistent matching
-    let p = filePath.toLowerCase().replace(/\\/g, '/');
+    const originalPath = filePath.replace(/\\/g, '/');
+    let p = originalPath.toLowerCase();
     if (!p.startsWith('/')) {
         p = '/' + p; // Add leading slash so patterns like '/app/' match 'app/...'
     }
+    const originalPathWithLeadingSlash = originalPath.startsWith('/')
+        ? originalPath
+        : `/${originalPath}`;
     // ========== JAVASCRIPT / TYPESCRIPT FRAMEWORKS ==========
     // Next.js - Pages Router (high confidence)
     if (p.includes('/pages/') && !p.includes('/_') && !p.includes('/api/')) {
@@ -91,7 +95,7 @@ export function detectFrameworkFromPath(filePath) {
     if ((p.includes('/components/') || p.includes('/views/')) &&
         (p.endsWith('.tsx') || p.endsWith('.jsx'))) {
         // Only boost if PascalCase filename (likely a component, not util)
-        const fileName = p.split('/').pop() || '';
+        const fileName = originalPathWithLeadingSlash.split('/').pop() || '';
         if (/^[A-Z]/.test(fileName)) {
             return { framework: 'react', entryPointMultiplier: 1.5, reason: 'react-component' };
         }

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

@@ -9,6 +9,7 @@ import { getTreeSitterBufferSize } from './constants.js';
 import { loadImportConfigs } from './language-config.js';
 import { buildSuffixIndex } from './import-resolvers/utils.js';
 import { isDev } from './utils/env.js';
+import { isRegistryPrimary } from './registry-primary-flag.js';
 /** Group files by provider (only those with implicit import wiring), then call each wirer
  *  with its own language's files. O(n) over files, O(1) per provider lookup. */
 function wireImplicitImports(files, importMap, addImportEdge, projectConfig) {
@@ -64,6 +65,9 @@ export function preprocessImportPath(sourceText, importNode, provider) {
 function createImportEdgeHelpers(graph, importMap) {
     let totalImportsResolved = 0;
     const addImportGraphEdge = (filePath, resolvedPath) => {
+        const language = getLanguageFromFilename(filePath);
+        if (language !== null && isRegistryPrimary(language))
+            return;
         const sourceId = generateId('File', filePath);
         const targetId = generateId('File', resolvedPath);
         const relId = generateId('IMPORTS', `${filePath}->${resolvedPath}`);

package/dist/core/ingestion/import-resolvers/python.js

@@ -45,12 +45,15 @@ export function resolvePythonImportInternal(currentFile, importPath, allFiles) {
         return null;
     // Normalize for Windows backslashes
     const importerDir = currentFile.replace(/\\/g, '/').split('/').slice(0, -1).join('/');
-    if (!importerDir)
-        return null;
-    if (allFiles.has(`${importerDir}/${pathLike}/__init__.py`))
-        return `${importerDir}/${pathLike}/__init__.py`;
-    if (allFiles.has(`${importerDir}/${pathLike}.py`))
-        return `${importerDir}/${pathLike}.py`;
+    // Proximity check — only applies when the importer lives in a subdirectory.
+    // Root-level importers (importerDir === '') skip straight to the ancestor
+    // walk below, which handles the root case correctly (prefix becomes '').
+    if (importerDir) {
+        if (allFiles.has(`${importerDir}/${pathLike}/__init__.py`))
+            return `${importerDir}/${pathLike}/__init__.py`;
+        if (allFiles.has(`${importerDir}/${pathLike}.py`))
+            return `${importerDir}/${pathLike}.py`;
+    }
     // Ancestor directory walk — Python resolves bare imports against sys.path entries,
     // which typically includes the project root and package directories. Walk up from the
     // importer's directory to find the module in an ancestor, preferring the closest match.

package/dist/core/ingestion/import-target-adapter.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Bridge between CLI-package per-language `ImportResolverFn`s and the
+ * shared `FinalizeHooks.resolveImportTarget` contract
+ * (RFC §5.2; Ring 2 PKG #922).
+ *
+ * The shared finalize algorithm (#915) asks one question:
+ *
+ *     resolveImportTarget(targetRaw, fromFile, workspaceIndex): string | null
+ *
+ * The CLI already has 16 language-specific resolvers satisfying a
+ * richer signature:
+ *
+ *     ImportResolverFn(rawImportPath, filePath, resolveCtx): ImportResult
+ *
+ * This module builds a dispatch adapter — one FinalizeHook implementation
+ * that looks up the file's language from its path and delegates to the
+ * right per-language resolver. Callers package per-language resolvers +
+ * a shared `ResolveCtx` into an opaque `ImportTargetWorkspace` and pass
+ * it as `workspaceIndex` to `finalizeScopeModel`.
+ *
+ * ## What's deliberately NOT here
+ *
+ *   - **Re-implementation of any per-language resolver.** We wrap the
+ *     existing `importResolver` field on each `LanguageProvider` — the
+ *     same code path the legacy DAG uses today.
+ *   - **Dynamic-import handling.** The shared finalize algorithm short-
+ *     circuits `ParsedImport { kind: 'dynamic-unresolved' }` before
+ *     calling `resolveImportTarget`, so the adapter never sees those.
+ *   - **`importPathPreprocessor`.** Preprocessing belongs inside the
+ *     provider's `interpretImport` hook (which writes the final
+ *     `ParsedImport.targetRaw`). By the time finalize passes a
+ *     `targetRaw` to this adapter, it is the string the provider wants
+ *     resolved verbatim.
+ */
+import { type SupportedLanguages, type WorkspaceIndex } from '../../_shared/index.js';
+import type { ImportResolverFn, ResolveCtx } from './import-resolvers/types.js';
+import type { LanguageProvider } from './language-provider.js';
+/** A single language's resolver bundled with the context it needs. */
+export interface LanguageResolverEntry {
+    readonly resolver: ImportResolverFn;
+    readonly ctx: ResolveCtx;
+}
+/**
+ * The opaque `workspaceIndex` shape recognized by
+ * `resolveImportTargetAcrossLanguages`. Built once per ingestion run via
+ * `buildImportTargetWorkspace`, threaded through `finalizeScopeModel`.
+ */
+export interface ImportTargetWorkspace {
+    readonly perLanguage: ReadonlyMap<SupportedLanguages, LanguageResolverEntry>;
+}
+/**
+ * Build the workspace index from a map of language → provider. Providers
+ * whose `importResolver` is absent are silently skipped (no language will
+ * ever hit that branch at dispatch time).
+ *
+ * The `resolveCtx` is shared across all languages. Callers assemble it
+ * once per run (the existing pipeline already does this for the legacy
+ * DAG) and hand it to both the legacy resolution path and this factory.
+ */
+export declare function buildImportTargetWorkspace(providers: ReadonlyMap<SupportedLanguages, LanguageProvider>, resolveCtx: ResolveCtx): ImportTargetWorkspace;
+/**
+ * The FinalizeHooks-compatible implementation. Dispatches on `fromFile`'s
+ * extension → per-language resolver. Returns the first resolved file,
+ * or `null` if the resolver returns `null` or doesn't know about the
+ * language.
+ *
+ * Picks the first entry of `files[]` for both `'files'` and `'package'`
+ * result kinds — the legacy pipeline uses the whole array, but the
+ * shared `finalize()` hook contract is single-file. If the workspace
+ * later needs richer semantics (split-target packages), this is the
+ * single site to extend.
+ */
+export declare function resolveImportTargetAcrossLanguages(targetRaw: string, fromFile: string, workspaceIndex: WorkspaceIndex): string | null;