arceus-s 1.6.4

package/dist/core/ingestion/import-resolvers/python.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Python import resolution — PEP 328 relative imports and proximity-based bare imports.
+ * Import system spec: PEP 302 (original), PEP 451 (current).
+ *
+ * Strategy lives in configs/python.ts.
+ * This file contains the shared internal helper used by the strategy and tests.
+ */
+/**
+ * Resolve a Python import to a file path (low-level helper).
+ *
+ * 1. Relative (PEP 328): `.module`, `..module` — 1 dot = current package, each extra dot goes up one level.
+ * 2. Proximity bare import: static heuristic — checks the importer's own directory first.
+ *    Approximates the common case where co-located files find each other without an installed package.
+ *    Single-segment only — multi-segment (e.g. `os.path`) falls through to suffixResolve.
+ *    Checks package (__init__.py) before module (.py), matching CPython's finder order (PEP 451 §4).
+ *    Coexistence of both is physically impossible (same name = file vs directory), so the order
+ *    only matters for spec compliance.
+ *    Note: implicit namespace packages (Python 3.3+, directory without __init__.py) are not handled.
+ *
+ * Returns null to let the caller fall through to suffixResolve.
+ */
+export declare function resolvePythonImportInternal(currentFile: string, importPath: string, allFiles: Set<string>): string | null;

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

@@ -0,0 +1,72 @@
+/**
+ * Python import resolution — PEP 328 relative imports and proximity-based bare imports.
+ * Import system spec: PEP 302 (original), PEP 451 (current).
+ *
+ * Strategy lives in configs/python.ts.
+ * This file contains the shared internal helper used by the strategy and tests.
+ */
+import { tryResolveWithExtensions } from './utils.js';
+/**
+ * Resolve a Python import to a file path (low-level helper).
+ *
+ * 1. Relative (PEP 328): `.module`, `..module` — 1 dot = current package, each extra dot goes up one level.
+ * 2. Proximity bare import: static heuristic — checks the importer's own directory first.
+ *    Approximates the common case where co-located files find each other without an installed package.
+ *    Single-segment only — multi-segment (e.g. `os.path`) falls through to suffixResolve.
+ *    Checks package (__init__.py) before module (.py), matching CPython's finder order (PEP 451 §4).
+ *    Coexistence of both is physically impossible (same name = file vs directory), so the order
+ *    only matters for spec compliance.
+ *    Note: implicit namespace packages (Python 3.3+, directory without __init__.py) are not handled.
+ *
+ * Returns null to let the caller fall through to suffixResolve.
+ */
+export function resolvePythonImportInternal(currentFile, importPath, allFiles) {
+    // Relative import — PEP 328 (https://peps.python.org/pep-0328/)
+    if (importPath.startsWith('.')) {
+        const dotMatch = importPath.match(/^(\.+)(.*)/);
+        if (!dotMatch)
+            return null;
+        const dotCount = dotMatch[1].length;
+        const modulePart = dotMatch[2];
+        const dirParts = currentFile.split('/').slice(0, -1);
+        // PEP 328: more dots than directory levels → beyond top-level package → invalid
+        if (dotCount - 1 > dirParts.length)
+            return null;
+        for (let i = 1; i < dotCount; i++)
+            dirParts.pop();
+        if (modulePart) {
+            dirParts.push(...modulePart.replace(/\./g, '/').split('/'));
+        }
+        return tryResolveWithExtensions(dirParts.join('/'), allFiles);
+    }
+    // Proximity bare import — single-segment only; package before module (PEP 451 §4)
+    const pathLike = importPath.replace(/\./g, '/');
+    if (pathLike.includes('/'))
+        return null;
+    // Normalize for Windows backslashes
+    const importerDir = currentFile.replace(/\\/g, '/').split('/').slice(0, -1).join('/');
+    // 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.
+    // This prevents cross-language misresolution (e.g., Python `from middleware import X`
+    // resolving to a TypeScript middleware.ts via suffix matching). Issue #417.
+    const dirParts = importerDir.split('/');
+    for (let i = dirParts.length - 1; i >= 0; i--) {
+        const ancestorDir = dirParts.slice(0, i).join('/');
+        const prefix = ancestorDir ? `${ancestorDir}/` : '';
+        if (allFiles.has(`${prefix}${pathLike}/__init__.py`))
+            return `${prefix}${pathLike}/__init__.py`;
+        if (allFiles.has(`${prefix}${pathLike}.py`))
+            return `${prefix}${pathLike}.py`;
+    }
+    return null;
+}

package/dist/core/ingestion/import-resolvers/resolver-factory.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Import resolver factory — creates a composable import resolver from
+ * an ordered list of strategies.
+ *
+ * Mirrors the method-extractors/generic.ts and call-extractors/generic.ts
+ * pattern: declare a config per language, produce a runtime resolver via factory.
+ *
+ * Each strategy is tried in order. The first non-null result wins.
+ * A result with an empty `files` array is treated as "handled but unresolved"
+ * (stops the chain without producing import edges).
+ */
+import type { ImportResolverFn, ImportResolutionConfig } from './types.js';
+/**
+ * Create an ImportResolverFn from a declarative config.
+ *
+ * Chains strategies in declaration order — first non-null result wins.
+ * Returns null only if every strategy returns null.
+ *
+ * Error behaviour: if a strategy throws, the error propagates immediately
+ * and remaining strategies are not tried.  Strategies are expected to be
+ * pure data transforms that never throw; any unexpected exception indicates
+ * a bug in the strategy implementation.
+ */
+export declare function createImportResolver(config: ImportResolutionConfig): ImportResolverFn;

package/dist/core/ingestion/import-resolvers/resolver-factory.js

@@ -0,0 +1,33 @@
+/**
+ * Import resolver factory — creates a composable import resolver from
+ * an ordered list of strategies.
+ *
+ * Mirrors the method-extractors/generic.ts and call-extractors/generic.ts
+ * pattern: declare a config per language, produce a runtime resolver via factory.
+ *
+ * Each strategy is tried in order. The first non-null result wins.
+ * A result with an empty `files` array is treated as "handled but unresolved"
+ * (stops the chain without producing import edges).
+ */
+/**
+ * Create an ImportResolverFn from a declarative config.
+ *
+ * Chains strategies in declaration order — first non-null result wins.
+ * Returns null only if every strategy returns null.
+ *
+ * Error behaviour: if a strategy throws, the error propagates immediately
+ * and remaining strategies are not tried.  Strategies are expected to be
+ * pure data transforms that never throw; any unexpected exception indicates
+ * a bug in the strategy implementation.
+ */
+export function createImportResolver(config) {
+    const { strategies } = config;
+    return (rawImportPath, filePath, ctx) => {
+        for (const strategy of strategies) {
+            const result = strategy(rawImportPath, filePath, ctx);
+            if (result)
+                return result;
+        }
+        return null;
+    };
+}

package/dist/core/ingestion/import-resolvers/ruby.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Ruby require/require_relative import resolution — internal helpers.
+ *
+ * Strategy lives in configs/ruby.ts.
+ * This file only contains the low-level helper used by the strategy.
+ */
+import type { SuffixIndex } from './utils.js';
+/**
+ * Resolve a Ruby require/require_relative path to a matching .rb file (low-level helper).
+ *
+ * require_relative paths are pre-normalized to './' prefix by the caller.
+ * require paths use suffix matching (gem-style paths like 'json', 'net/http').
+ */
+export declare function resolveRubyImportInternal(importPath: string, normalizedFileList: string[], allFileList: string[], index?: SuffixIndex): string | null;

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

@@ -0,0 +1,17 @@
+/**
+ * Ruby require/require_relative import resolution — internal helpers.
+ *
+ * Strategy lives in configs/ruby.ts.
+ * This file only contains the low-level helper used by the strategy.
+ */
+import { suffixResolve } from './utils.js';
+/**
+ * Resolve a Ruby require/require_relative path to a matching .rb file (low-level helper).
+ *
+ * require_relative paths are pre-normalized to './' prefix by the caller.
+ * require paths use suffix matching (gem-style paths like 'json', 'net/http').
+ */
+export function resolveRubyImportInternal(importPath, normalizedFileList, allFileList, index) {
+    const pathParts = importPath.replace(/^\.\//, '').split('/').filter(Boolean);
+    return suffixResolve(pathParts, normalizedFileList, allFileList, index);
+}

package/dist/core/ingestion/import-resolvers/rust.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Rust module import resolution — internal helpers.
+ *
+ * Strategy lives in configs/rust.ts.
+ * This file contains shared helpers used by the strategy and standard.ts.
+ */
+/**
+ * Resolve Rust use-path to a file (low-level helper).
+ * Handles crate::, super::, self:: prefixes and :: path separators.
+ */
+export declare function resolveRustImportInternal(currentFile: string, importPath: string, allFiles: Set<string>): string | null;
+/**
+ * Try to resolve a Rust module path to a file.
+ * Tries: path.rs, path/mod.rs, and with the last segment stripped
+ * (last segment might be a symbol name, not a module).
+ */
+export declare function tryRustModulePath(modulePath: string, allFiles: Set<string>): string | null;

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

@@ -0,0 +1,75 @@
+/**
+ * Rust module import resolution — internal helpers.
+ *
+ * Strategy lives in configs/rust.ts.
+ * This file contains shared helpers used by the strategy and standard.ts.
+ */
+/**
+ * Resolve Rust use-path to a file (low-level helper).
+ * Handles crate::, super::, self:: prefixes and :: path separators.
+ */
+export function resolveRustImportInternal(currentFile, importPath, allFiles) {
+    let rustPath;
+    if (importPath.startsWith('crate::')) {
+        // crate:: resolves from src/ directory (standard Rust layout)
+        rustPath = importPath.slice(7).replace(/::/g, '/');
+        // Try from src/ (standard layout)
+        const fromSrc = tryRustModulePath('src/' + rustPath, allFiles);
+        if (fromSrc)
+            return fromSrc;
+        // Try from repo root (non-standard)
+        const fromRoot = tryRustModulePath(rustPath, allFiles);
+        if (fromRoot)
+            return fromRoot;
+        return null;
+    }
+    if (importPath.startsWith('super::')) {
+        // super:: = parent directory of current file's module
+        const currentDir = currentFile.split('/').slice(0, -1);
+        currentDir.pop(); // Go up one level for super::
+        rustPath = importPath.slice(7).replace(/::/g, '/');
+        const fullPath = [...currentDir, rustPath].join('/');
+        return tryRustModulePath(fullPath, allFiles);
+    }
+    if (importPath.startsWith('self::')) {
+        // self:: = current module's directory
+        const currentDir = currentFile.split('/').slice(0, -1);
+        rustPath = importPath.slice(6).replace(/::/g, '/');
+        const fullPath = [...currentDir, rustPath].join('/');
+        return tryRustModulePath(fullPath, allFiles);
+    }
+    // Bare path without prefix (e.g., from a use in a nested module)
+    // Convert :: to / and try suffix matching
+    if (importPath.includes('::')) {
+        rustPath = importPath.replace(/::/g, '/');
+        return tryRustModulePath(rustPath, allFiles);
+    }
+    return null;
+}
+/**
+ * Try to resolve a Rust module path to a file.
+ * Tries: path.rs, path/mod.rs, and with the last segment stripped
+ * (last segment might be a symbol name, not a module).
+ */
+export function tryRustModulePath(modulePath, allFiles) {
+    // Try direct: path.rs
+    if (allFiles.has(modulePath + '.rs'))
+        return modulePath + '.rs';
+    // Try directory: path/mod.rs
+    if (allFiles.has(modulePath + '/mod.rs'))
+        return modulePath + '/mod.rs';
+    // Try path/lib.rs (for crate root)
+    if (allFiles.has(modulePath + '/lib.rs'))
+        return modulePath + '/lib.rs';
+    // The last segment might be a symbol (function, struct, etc.), not a module.
+    // Strip it and try again.
+    const lastSlash = modulePath.lastIndexOf('/');
+    if (lastSlash > 0) {
+        const parentPath = modulePath.substring(0, lastSlash);
+        if (allFiles.has(parentPath + '.rs'))
+            return parentPath + '.rs';
+        if (allFiles.has(parentPath + '/mod.rs'))
+            return parentPath + '/mod.rs';
+    }
+    return null;
+}

package/dist/core/ingestion/import-resolvers/standard.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Standard import path resolution.
+ * Handles relative imports, path alias rewriting, and generic suffix matching.
+ * Used as the fallback when language-specific resolvers don't match.
+ */
+import type { SuffixIndex } from './utils.js';
+import { SupportedLanguages } from '../../../_shared/index.js';
+import type { ImportResult, ImportResolverStrategy, ResolveCtx } from './types.js';
+import type { TsconfigPaths } from '../language-config.js';
+/** Max entries in the resolve cache. Beyond this, entries are evicted.
+ *  100K entries ≈ 15MB — covers the most common import patterns. */
+export declare const RESOLVE_CACHE_CAP = 100000;
+/**
+ * Resolve an import path to a file path in the repository.
+ *
+ * Language-specific preprocessing is applied before the generic resolution:
+ * - TypeScript/JavaScript: rewrites tsconfig path aliases
+ * - Rust: converts crate::/super::/self:: to relative paths
+ *
+ * Java wildcards and Go package imports are handled separately in processImports
+ * because they resolve to multiple files.
+ */
+export declare const resolveImportPath: (currentFile: string, importPath: string, allFiles: Set<string>, allFileList: string[], normalizedFileList: string[], resolveCache: Map<string, string | null>, language: SupportedLanguages, tsconfigPaths: TsconfigPaths | null, index?: SuffixIndex) => string | null;
+/**
+ * Standard single-file resolution (TS/JS/C/C++ and fallback for other languages).
+ * Handles relative imports, tsconfig path aliases, and suffix matching.
+ */
+export declare function resolveStandard(rawImportPath: string, filePath: string, ctx: ResolveCtx, language: SupportedLanguages): ImportResult;
+/** Create a reusable standard-resolution strategy for a given language. */
+export declare function createStandardStrategy(language: SupportedLanguages): ImportResolverStrategy;
+/**
+ * Strip a JS-family extension from a path, returning the stem.
+ * Returns `null` if the path does not end with a JS-family extension.
+ */
+export declare function stripJsExtension(path: string): string | null;

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

@@ -0,0 +1,168 @@
+/**
+ * Standard import path resolution.
+ * Handles relative imports, path alias rewriting, and generic suffix matching.
+ * Used as the fallback when language-specific resolvers don't match.
+ */
+import { tryResolveWithExtensions, suffixResolve } from './utils.js';
+import { resolveRustImportInternal } from './rust.js';
+import { SupportedLanguages } from '../../../_shared/index.js';
+/** Max entries in the resolve cache. Beyond this, entries are evicted.
+ *  100K entries ≈ 15MB — covers the most common import patterns. */
+export const RESOLVE_CACHE_CAP = 100_000;
+/**
+ * Resolve an import path to a file path in the repository.
+ *
+ * Language-specific preprocessing is applied before the generic resolution:
+ * - TypeScript/JavaScript: rewrites tsconfig path aliases
+ * - Rust: converts crate::/super::/self:: to relative paths
+ *
+ * Java wildcards and Go package imports are handled separately in processImports
+ * because they resolve to multiple files.
+ */
+export const resolveImportPath = (currentFile, importPath, allFiles, allFileList, normalizedFileList, resolveCache, language, tsconfigPaths, index) => {
+    const cacheKey = `${currentFile}::${importPath}`;
+    if (resolveCache.has(cacheKey))
+        return resolveCache.get(cacheKey) ?? null;
+    const cache = (result) => {
+        // Evict oldest 20% when cap is reached instead of clearing all
+        if (resolveCache.size >= RESOLVE_CACHE_CAP) {
+            const evictCount = Math.floor(RESOLVE_CACHE_CAP * 0.2);
+            const iter = resolveCache.keys();
+            for (let i = 0; i < evictCount; i++) {
+                const key = iter.next().value;
+                if (key !== undefined)
+                    resolveCache.delete(key);
+            }
+        }
+        resolveCache.set(cacheKey, result);
+        return result;
+    };
+    // ---- TypeScript/JavaScript: rewrite path aliases ----
+    if ((language === SupportedLanguages.TypeScript || language === SupportedLanguages.JavaScript) &&
+        tsconfigPaths &&
+        !importPath.startsWith('.')) {
+        for (const [aliasPrefix, targetPrefix] of tsconfigPaths.aliases) {
+            if (importPath.startsWith(aliasPrefix)) {
+                const remainder = importPath.slice(aliasPrefix.length);
+                // Build the rewritten path relative to baseUrl
+                const rewritten = tsconfigPaths.baseUrl === '.'
+                    ? targetPrefix + remainder
+                    : tsconfigPaths.baseUrl + '/' + targetPrefix + remainder;
+                // Try direct resolution from repo root
+                const resolved = tryResolveWithExtensions(rewritten, allFiles);
+                if (resolved)
+                    return cache(resolved);
+                // Try suffix matching as fallback
+                const parts = rewritten.split('/').filter(Boolean);
+                const suffixResult = suffixResolve(parts, normalizedFileList, allFileList, index);
+                if (suffixResult)
+                    return cache(suffixResult);
+            }
+        }
+    }
+    // ---- Rust: convert module path syntax to file paths ----
+    if (language === SupportedLanguages.Rust) {
+        // Handle grouped imports: use crate::module::{Foo, Bar, Baz}
+        // Extract the prefix path before ::{...} and resolve the module, not the symbols
+        let rustImportPath = importPath;
+        const braceIdx = importPath.indexOf('::{');
+        if (braceIdx !== -1) {
+            rustImportPath = importPath.substring(0, braceIdx);
+        }
+        else if (importPath.startsWith('{') && importPath.endsWith('}')) {
+            // Top-level grouped imports: use {crate::a, crate::b}
+            // Iterate each part and return the first that resolves. This function returns a single
+            // string, so callers that need ALL edges must intercept before reaching here (see the
+            // Rust grouped-import blocks in processImports / processImportsBatch). This fallback
+            // handles any path that reaches resolveImportPath directly.
+            const inner = importPath.slice(1, -1);
+            const parts = inner
+                .split(',')
+                .map((p) => p.trim())
+                .filter(Boolean);
+            for (const part of parts) {
+                const partResult = resolveRustImportInternal(currentFile, part, allFiles);
+                if (partResult)
+                    return cache(partResult);
+            }
+            return cache(null);
+        }
+        const rustResult = resolveRustImportInternal(currentFile, rustImportPath, allFiles);
+        if (rustResult)
+            return cache(rustResult);
+        // Fall through to generic resolution if Rust-specific didn't match
+    }
+    // ---- Generic relative import resolution (./ and ../) ----
+    const currentDir = currentFile.split('/').slice(0, -1);
+    const parts = importPath.split('/');
+    for (const part of parts) {
+        if (part === '.')
+            continue;
+        if (part === '..') {
+            currentDir.pop();
+        }
+        else {
+            currentDir.push(part);
+        }
+    }
+    const basePath = currentDir.join('/');
+    if (importPath.startsWith('.')) {
+        const resolved = tryResolveWithExtensions(basePath, allFiles);
+        if (resolved)
+            return cache(resolved);
+        // TypeScript ESM: imports use .js/.jsx/.mjs/.cjs but source files are
+        // .ts/.tsx/.mts/.cts. Strip the JS-family extension and re-resolve.
+        // NOTE: This fallback only applies to relative imports. Path alias imports
+        // (e.g. @/utils.js via tsconfig paths) do not yet strip .js extensions —
+        // that is a known limitation tracked for follow-up.
+        if (language === SupportedLanguages.TypeScript || language === SupportedLanguages.JavaScript) {
+            const stripped = stripJsExtension(basePath);
+            if (stripped !== null) {
+                return cache(tryResolveWithExtensions(stripped, allFiles));
+            }
+        }
+        return cache(null);
+    }
+    // ---- Generic package/absolute import resolution (suffix matching) ----
+    // Java wildcards are handled in processImports, not here
+    if (importPath.endsWith('.*')) {
+        return cache(null);
+    }
+    // C/C++ includes use actual file paths (e.g. "animal.h") — don't convert dots to slashes
+    const isCpp = language === SupportedLanguages.C || language === SupportedLanguages.CPlusPlus;
+    const pathLike = importPath.includes('/') || isCpp ? importPath : importPath.replace(/\./g, '/');
+    const pathParts = pathLike.split('/').filter(Boolean);
+    const resolved = suffixResolve(pathParts, normalizedFileList, allFileList, index);
+    return cache(resolved);
+};
+// ============================================================================
+// Per-language dispatch functions (moved from import-resolution.ts)
+// ============================================================================
+/**
+ * Standard single-file resolution (TS/JS/C/C++ and fallback for other languages).
+ * Handles relative imports, tsconfig path aliases, and suffix matching.
+ */
+export function resolveStandard(rawImportPath, filePath, ctx, language) {
+    const resolvedPath = resolveImportPath(filePath, rawImportPath, ctx.allFilePaths, ctx.allFileList, ctx.normalizedFileList, ctx.resolveCache, language, ctx.configs.tsconfigPaths, ctx.index);
+    return resolvedPath ? { kind: 'files', files: [resolvedPath] } : null;
+}
+// ============================================================================
+// Strategy factory — composable hook for ImportResolutionConfig
+// ============================================================================
+/** Create a reusable standard-resolution strategy for a given language. */
+export function createStandardStrategy(language) {
+    return (raw, fp, ctx) => resolveStandard(raw, fp, ctx, language);
+}
+// ============================================================================
+// ESM extension helpers
+// ============================================================================
+/** JS-family extensions that TypeScript ESM maps to TS equivalents. */
+const JS_EXTENSION_PATTERN = /\.(js|jsx|mjs|cjs)$/;
+/**
+ * Strip a JS-family extension from a path, returning the stem.
+ * Returns `null` if the path does not end with a JS-family extension.
+ */
+export function stripJsExtension(path) {
+    const match = JS_EXTENSION_PATTERN.exec(path);
+    return match ? path.slice(0, -match[0].length) : null;
+}

package/dist/core/ingestion/import-resolvers/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Import resolution types — shared across all per-language resolvers.
+ *
+ * Extracted from import-resolution.ts to co-locate types with their consumers.
+ */
+import type { TsconfigPaths, GoModuleConfig, CSharpProjectConfig, ComposerConfig } from '../language-config.js';
+import type { SwiftPackageConfig } from '../language-config.js';
+import type { SuffixIndex } from './utils.js';
+import type { SupportedLanguages } from '../../../_shared/index.js';
+/**
+ * Result of resolving an import via language-specific dispatch.
+ * - 'files': resolved to one or more files -> add to ImportMap
+ * - 'package': resolved to a directory -> add graph edges + store dirSuffix in PackageMap
+ * - null: no resolution (external dependency, etc.)
+ */
+export type ImportResult = {
+    kind: 'files';
+    files: string[];
+} | {
+    kind: 'package';
+    files: string[];
+    dirSuffix: string;
+} | null;
+/** Bundled language-specific configs loaded once per ingestion run. */
+export interface ImportConfigs {
+    tsconfigPaths: TsconfigPaths | null;
+    goModule: GoModuleConfig | null;
+    composerConfig: ComposerConfig | null;
+    swiftPackageConfig: SwiftPackageConfig | null;
+    csharpConfigs: CSharpProjectConfig[];
+}
+/** Pre-built lookup structures for import resolution. Build once, reuse across chunks. */
+export interface ImportResolutionContext {
+    allFilePaths: Set<string>;
+    allFileList: string[];
+    normalizedFileList: string[];
+    index: SuffixIndex;
+    resolveCache: Map<string, string | null>;
+}
+/** Full context for import resolution: file lookups + language configs. */
+export interface ResolveCtx extends ImportResolutionContext {
+    configs: ImportConfigs;
+}
+/** Per-language import resolver -- function alias matching ExportChecker/CallRouter pattern. */
+export type ImportResolverFn = (rawImportPath: string, filePath: string, resolveCtx: ResolveCtx) => ImportResult;
+/**
+ * A single import resolution strategy — one step in a composable chain.
+ * Same signature as ImportResolverFn. Returns null to let the next strategy
+ * in the chain try; returns a result (even with empty files) to stop the chain.
+ */
+export type ImportResolverStrategy = ImportResolverFn;
+/**
+ * Declarative config for composable import resolution — mirrors the
+ * MethodExtractionConfig / CallExtractionConfig pattern.
+ *
+ * Each language declares an ordered list of strategies to try.
+ * The factory (`createImportResolver`) chains them: first non-null result wins.
+ */
+export interface ImportResolutionConfig {
+    /**
+     * Documentation-only metadata identifying which language this config serves.
+     * **Not used by `createImportResolver`** — the factory only iterates `strategies`.
+     * Useful for logging, debugging, and compile-time exhaustiveness checks when
+     * mapping `SupportedLanguages → ImportResolutionConfig` in language providers.
+     */
+    readonly language: SupportedLanguages;
+    readonly strategies: readonly ImportResolverStrategy[];
+}

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

@@ -0,0 +1,6 @@
+/**
+ * Import resolution types — shared across all per-language resolvers.
+ *
+ * Extracted from import-resolution.ts to co-locate types with their consumers.
+ */
+export {};

package/dist/core/ingestion/import-resolvers/utils.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Shared utilities for import resolution.
+ * Extracted from import-processor.ts to reduce file size.
+ */
+/** All file extensions to try during resolution */
+export declare const EXTENSIONS: string[];
+/**
+ * Try to match a path (with extensions) against the known file set.
+ * Returns the matched file path or null.
+ */
+export declare function tryResolveWithExtensions(basePath: string, allFiles: Set<string>): string | null;
+/**
+ * Build a suffix index for O(1) endsWith lookups.
+ * Maps every possible path suffix to its original file path.
+ * e.g. for "src/com/example/Foo.java":
+ *   "Foo.java" -> "src/com/example/Foo.java"
+ *   "example/Foo.java" -> "src/com/example/Foo.java"
+ *   "com/example/Foo.java" -> "src/com/example/Foo.java"
+ *   etc.
+ */
+export interface SuffixIndex {
+    /** Exact suffix lookup (case-sensitive) */
+    get(suffix: string): string | undefined;
+    /** Case-insensitive suffix lookup */
+    getInsensitive(suffix: string): string | undefined;
+    /** Get all files in a directory suffix */
+    getFilesInDir(dirSuffix: string, extension: string): string[];
+}
+/** Sentinel index that returns no results. Used to release memory after import resolution. */
+export declare const EMPTY_INDEX: SuffixIndex;
+export declare function buildSuffixIndex(normalizedFileList: string[], allFileList: string[]): SuffixIndex;
+/**
+ * Suffix-based resolution using index. O(1) per lookup instead of O(files).
+ */
+export declare function suffixResolve(pathParts: string[], normalizedFileList: string[], allFileList: string[], index?: SuffixIndex): string | null;