gitnexus 1.6.10-rc.98 → 1.6.10

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

@@ -5,6 +5,7 @@
  * Strategy lives in configs/python.ts.
  * This file contains the shared internal helper used by the strategy and tests.
  */
+import { getPythonFileIndex, importerBarePrefixes, importerDirOf, pythonSegmentAbsent, } from './python-file-index.js';
 import { tryResolveWithExtensions } from './utils.js';
 /**
  * Resolve a Python import to a file path (low-level helper).
@@ -43,8 +44,24 @@ export function resolvePythonImportInternal(currentFile, importPath, allFiles) {
     const pathLike = importPath.replace(/\./g, '/');
     if (pathLike.includes('/'))
         return null;
-    // Normalize for Windows backslashes
-    const importerDir = currentFile.replace(/\\/g, '/').split('/').slice(0, -1).join('/');
+    // O(1) proof of absence, before any probing. Every probe below — the two
+    // proximity probes and the two per ancestor step — has the shape
+    // `<X>/<pathLike>.py` or `<X>/<pathLike>/__init__.py`, and
+    // `pythonSegmentAbsent` answers "no file in the workspace has EITHER shape,
+    // for any prefix" in two Map lookups on the index the dotted tiers already
+    // build. That is `true` for `os`, `sys`, `django` and every other
+    // distribution the repo does not vendor — i.e. for most imports in most
+    // Python repos — and it retires the whole walk for them instead of running
+    // it to the workspace root. It is exact, not a filter: a miss here means
+    // every probe the walk would have issued was guaranteed to miss.
+    const index = getPythonFileIndex(allFiles);
+    if (pythonSegmentAbsent(index, pathLike))
+        return null;
+    // One derivation, shared with the index's other per-directory memo — see
+    // `importerDirOf`. It replaced `split('/').slice(0, -1).join('/')`: identical
+    // for every input (a path with no separator has no directory, which is `''`
+    // both ways) without the per-import array of one element per path component.
+    const importerDir = importerDirOf(currentFile);
     // 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 '').
@@ -59,10 +76,12 @@ export function resolvePythonImportInternal(currentFile, importPath, allFiles) {
     // 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}/` : '';
+    //
+    // The prefixes come from `importerBarePrefixes`, built ONCE per importer
+    // directory per pass and stored in the same index consulted above. Rebuilding
+    // them here — `dirParts.slice(0, i).join('/')`, one array and one string per
+    // path component — was the last per-import ancestor walk left after #2913.
+    for (const prefix of importerBarePrefixes(index, importerDir)) {
         if (allFiles.has(`${prefix}${pathLike}/__init__.py`))
             return `${prefix}${pathLike}/__init__.py`;
         if (allFiles.has(`${prefix}${pathLike}.py`))

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

@@ -11,4 +11,4 @@ import type { SuffixIndex } from './utils.js';
  * 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;
+export declare function resolveRubyImportInternal(importPath: string, normalizedFileList: readonly string[], allFileList: readonly string[], index?: SuffixIndex): string | null;

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

@@ -8,10 +8,10 @@
  * 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;
+export declare function resolveRustImportInternal(currentFile: string, importPath: string, allFiles: ReadonlySet<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;
+export declare function tryRustModulePath(modulePath: string, allFiles: ReadonlySet<string>): string | null;

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

@@ -20,7 +20,7 @@ export declare const RESOLVE_CACHE_CAP = 100000;
  * Java wildcards and Go package imports are handled by the scope-resolution
  * phase 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;
+export declare const resolveImportPath: (currentFile: string, importPath: string, allFiles: Set<string>, allFileList: readonly string[], normalizedFileList: readonly 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.

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

@@ -3,8 +3,7 @@
  *
  * Extracted from import-resolution.ts to co-locate types with their consumers.
  */
-import type { TsconfigPaths, GoModuleConfig, CSharpProjectConfig, CSharpNamespaceEvidence, ComposerConfig } from '../language-config.js';
-import type { SwiftPackageConfig } from '../language-config.js';
+import type { ImportConfigs } from '../language-config.js';
 import type { SuffixIndex } from './utils.js';
 import type { SupportedLanguages } from '../../../_shared/index.js';
 /**
@@ -21,16 +20,6 @@ export type ImportResult = {
     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[];
-    /** In-repo namespace evidence gating C# suffix-fallback resolution (#1881). */
-    csharpNamespaces?: CSharpNamespaceEvidence;
-}
 /** Pre-built lookup structures for import resolution. Build once, reuse across chunks. */
 export interface ImportResolutionContext {
     allFilePaths: Set<string>;

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

@@ -18,15 +18,74 @@ export declare function tryResolveWithExtensions(basePath: string, allFiles: Rea
  *   etc.
  */
 export interface SuffixIndex {
-    /** Exact suffix lookup (case-sensitive) */
+    /**
+     * Exact suffix lookup (case-sensitive).
+     *
+     * The map behind this is built on the FIRST call and memoized — see
+     * `buildSuffixIndex`. All three maps are deferred; a consumer pays only for
+     * the questions it actually asks.
+     */
     get(suffix: string): string | undefined;
-    /** Case-insensitive suffix lookup */
+    /**
+     * Case-insensitive suffix lookup.
+     *
+     * Deferred like `get`, and — when `get` was asked first — DERIVED from that
+     * map rather than traversed for a second time. See `buildSuffixIndex`.
+     */
     getInsensitive(suffix: string): string | undefined;
-    /** Get all files in a directory suffix */
-    getFilesInDir(dirSuffix: string, extension: string): string[];
+    /**
+     * Get all files in a directory suffix.
+     *
+     * `dirSuffix` is matched as a SEGMENT-aligned directory suffix — every
+     * returned file is a direct child of a directory `D` with
+     * `D === dirSuffix || D.endsWith('/' + dirSuffix)`. Callers may rely on this
+     * and skip a direct-child re-check; `import-resolvers/csharp.ts` step 2 does
+     * exactly that. It bounds what may be RETURNED, not what must be found: an
+     * implementation is free to answer with fewer files, and the root-anchored
+     * index in `languages/php/import-target.ts` answers only the `D === dirSuffix`
+     * arm.
+     *
+     * `readonly` is the CONTRACT, and it is the contract for every implementation
+     * of this interface, not a description of any one of them: an implementation
+     * is free to return its own bucket by reference, so callers must treat the
+     * result as shared and never `sort`/`splice` it in place. The compiler now
+     * refuses that at the call site. Whether a given implementation shares or
+     * copies is its own business and documented where it is built —
+     * `buildSuffixIndex` shares, the root-anchored parity index in
+     * `languages/php/import-target.ts` returns a filtered copy.
+     *
+     * Implementations that memoize should note the directory map behind this may
+     * be built on the FIRST call rather than up front, so a caller that never
+     * asks a directory question never pays for it — see `buildSuffixIndex`.
+     */
+    getFilesInDir(dirSuffix: string, extension: string): readonly string[];
 }
-export declare function buildSuffixIndex(normalizedFileList: string[], allFileList: string[]): SuffixIndex;
+export interface SuffixIndexOptions {
+    /**
+     * Promise from the caller that `normalizedFileList[i] === normalizedFileList[i].toLowerCase()`
+     * for every `i` — i.e. the "normalized" list is a LOWERCASED file list, not
+     * merely a slash-normalized one.
+     *
+     * `import-resolvers/pass-cache.ts` is the one caller that can make it: it
+     * builds `normalizedFileList` as `allFileList.map((f) => f.toLowerCase())`.
+     * Every suffix of an all-lowercase path is itself lowercase, so
+     * `suffix.toLowerCase() === suffix` and the case-folded map came out a
+     * byte-identical copy of the exact one — same keys, same values, same
+     * insertion order. Measured 14.00 MiB at 32 000 paths, 29.8% of the retained
+     * `ImportPassCache` — and one `ImportPassCache` is built per ts-family
+     * adapter per pass, so the waste was carried once for each of them.
+     *
+     * With this set, `getInsensitive` reads the exact map directly instead. It is
+     * the same map the derivation below would have produced, so this is a skipped
+     * copy and not a second lookup rule — see `getLowerMap`.
+     *
+     * Setting it over a list that is NOT all-lowercase is a behaviour change, not
+     * an optimization: `getInsensitive` would then answer case-sensitively.
+     */
+    readonly alreadyLowercased?: boolean;
+}
+export declare function buildSuffixIndex(normalizedFileList: readonly string[], allFileList: readonly string[], options?: SuffixIndexOptions): 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;
+export declare function suffixResolve(pathParts: string[], normalizedFileList: readonly string[], allFileList: readonly string[], index?: SuffixIndex): string | null;

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

@@ -64,53 +64,232 @@ export function tryResolveWithExtensions(basePath, allFiles) {
     }
     return null;
 }
-export function buildSuffixIndex(normalizedFileList, allFileList) {
-    // Map: normalized suffix -> original file path
-    const exactMap = new Map();
-    // Map: lowercase suffix -> original file path
-    const lowerMap = new Map();
-    // Map: directory suffix -> list of file paths in that directory
-    const dirMap = new Map();
-    for (let i = 0; i < normalizedFileList.length; i++) {
-        const normalized = normalizedFileList[i];
-        const original = allFileList[i];
-        const parts = normalized.split('/');
-        // Index all suffixes: "a/b/c.java" -> ["c.java", "b/c.java", "a/b/c.java"]
-        for (let j = parts.length - 1; j >= 0; j--) {
-            const suffix = parts.slice(j).join('/');
-            // Only store first match (longest path wins for ambiguous suffixes)
-            if (!exactMap.has(suffix)) {
-                exactMap.set(suffix, original);
+export function buildSuffixIndex(normalizedFileList, allFileList, options) {
+    const alreadyLowercased = options?.alreadyLowercased === true;
+    /**
+     * Map: normalized suffix -> original file path.
+     *
+     * DEFERRED, like `dirMap` below and for the same reason (#2903 extended to
+     * the two suffix maps). Several consumers on the ScopeResolver path ask only
+     * ONE of the two suffix questions and were paying for both:
+     *
+     *   - `languages/java/import-target.ts` and the no-csproj leg of
+     *     `languages/csharp/import-target.ts` call `get` and never
+     *     `getInsensitive` — measured 49.98 MiB dead of a 100.82 MiB Java index
+     *     at 32 000 paths (49.6%), against a gated ceiling of 146.9 MiB;
+     *   - `languages/php/import-target.ts` calls `getInsensitive` and never `get`
+     *     — 34.49 MiB of 69.85 MiB (49.4%).
+     *
+     * Ruby, the csproj leg of C#, `group/extractors/include-extractor.ts` and
+     * `suffixResolve` below read both, and all four read `get` FIRST (they are
+     * written `get(s) || getInsensitive(s)`), which is what makes the derivation
+     * in `getLowerMap` the cheap order rather than the expensive one.
+     */
+    let exactMap = null;
+    const getExactMap = () => {
+        if (exactMap !== null)
+            return exactMap;
+        const built = new Map();
+        for (let i = 0; i < normalizedFileList.length; i++) {
+            const normalized = normalizedFileList[i];
+            const original = allFileList[i];
+            // Index all suffixes: "a/b/c.java" -> ["c.java", "b/c.java", "a/b/c.java"].
+            //
+            // Walked as slash offsets into `normalized` rather than as
+            // `normalized.split('/')` + `parts.slice(j).join('/')`: the slice of the
+            // ORIGINAL string is byte-identical to the re-joined parts (no separator
+            // is invented or dropped — verified over 361 865 suffix strings including
+            // leading, doubled and trailing slashes), and it allocates one string
+            // instead of a parts array, a slice array and a joined string per suffix.
+            // Measured 357.4 ms -> 264.5 ms at 32 000 paths.
+            let slash = normalized.lastIndexOf('/');
+            while (slash >= 0) {
+                const suffix = normalized.slice(slash + 1);
+                // Only store first match (longest path wins for ambiguous suffixes)
+                if (!built.has(suffix))
+                    built.set(suffix, original);
+                // A path may begin with '/', whose suffix is the whole string below.
+                if (slash === 0)
+                    break;
+                slash = normalized.lastIndexOf('/', slash - 1);
             }
-            const lower = suffix.toLowerCase();
-            if (!lowerMap.has(lower)) {
-                lowerMap.set(lower, original);
+            // j = 0 — the whole path, which the slash walk cannot emit.
+            if (!built.has(normalized))
+                built.set(normalized, original);
+        }
+        exactMap = built;
+        return built;
+    };
+    /**
+     * Map: lowercase suffix -> original file path.
+     *
+     * Deferred, and when the exact map already exists DERIVED from it instead of
+     * traversed for: one pass over that map's DISTINCT keys rather than a second
+     * pass over every (file × depth) suffix. Measured 330.3 ms total (200.6 build
+     * + 129.7 derive) against 388.8 ms for the single fused traversal that built
+     * both eagerly — so the two-map consumers get cheaper too, which per-map
+     * laziness on its own does not (407.1 ms, a second full traversal).
+     *
+     * The derivation is EQUAL, not approximate, and the argument is short. Let
+     * the fused loop's global order be the pairs (suffix, file) it visited. For a
+     * lowercase key L, let p be the first position whose suffix lowercases to L —
+     * the entry today's `lowerMap` keeps. Nothing before p carries that suffix
+     * spelled ANY way, so p is also the first occurrence of its exact spelling
+     * and is therefore in the exact map, holding that same file. Exact-map
+     * insertion order is by first-occurrence position, so among the exact keys
+     * folding to L, p's is reached first and first-wins keeps it. Insertion order
+     * of the derived map is the order of those p's, which is the order today's
+     * `lowerMap` inserts L. Verified rather than only argued: byte-equal keys,
+     * values and order over 968 418 entries across bench-shaped, PascalCase,
+     * case-colliding, deep-monorepo, Unicode-adversarial and 400 seeded-fuzz
+     * corpora.
+     *
+     * When `getInsensitive` is asked FIRST (PHP), there is nothing to derive
+     * from, so it is built straight — one traversal, one map, which is the point.
+     * Asking `get` afterwards would then cost the second traversal; no consumer
+     * does, and the fallback stays correct if one ever starts.
+     */
+    let lowerMap = null;
+    const getLowerMap = () => {
+        // Over an already-lowercased file list the derivation is the identity, so
+        // the exact map IS the case-folded map. Skip the copy.
+        if (alreadyLowercased)
+            return getExactMap();
+        if (lowerMap !== null)
+            return lowerMap;
+        const built = new Map();
+        if (exactMap !== null) {
+            for (const [suffix, original] of exactMap) {
+                const lower = suffix.toLowerCase();
+                if (!built.has(lower))
+                    built.set(lower, original);
+            }
+            lowerMap = built;
+            return built;
+        }
+        for (let i = 0; i < normalizedFileList.length; i++) {
+            const normalized = normalizedFileList[i];
+            const original = allFileList[i];
+            let slash = normalized.lastIndexOf('/');
+            while (slash >= 0) {
+                const lower = normalized.slice(slash + 1).toLowerCase();
+                if (!built.has(lower))
+                    built.set(lower, original);
+                if (slash === 0)
+                    break;
+                slash = normalized.lastIndexOf('/', slash - 1);
             }
+            const whole = normalized.toLowerCase();
+            if (!built.has(whole))
+                built.set(whole, original);
         }
-        // Index directory membership
-        const lastSlash = normalized.lastIndexOf('/');
-        if (lastSlash >= 0) {
-            // Build all directory suffixes
-            const dirParts = parts.slice(0, -1);
-            const fileName = parts[parts.length - 1];
-            const ext = fileName.substring(fileName.lastIndexOf('.'));
-            for (let j = dirParts.length - 1; j >= 0; j--) {
-                const dirSuffix = dirParts.slice(j).join('/');
-                const key = `${dirSuffix}:${ext}`;
-                let list = dirMap.get(key);
+        lowerMap = built;
+        return built;
+    };
+    /**
+     * Map: `${directory suffix}:${extension}` -> file paths in that directory.
+     *
+     * DEFERRED, not dropped (#2903). This is the array-valued map of the three
+     * and by far the most expensive: one entry — and one array push — per file
+     * per directory component, so O(files × depth) in entries AND in array
+     * churn. Measured on the 32k-path arms of `bench/import-target/`, it is
+     * ~15% of the retained C# index and ~19% of the retained Ruby one.
+     *
+     * Only `getFilesInDir` reads it, and only four call sites reach that:
+     * `import-resolvers/{php,csharp,jvm}.ts` and `import-resolvers/configs/
+     * python.ts`. Every other consumer of this index — `workspace-file-index.ts`
+     * serving Ruby, `languages/typescript/scope-resolver.ts`,
+     * `languages/vue/import-target.ts`, `group/extractors/include-extractor.ts`
+     * — asks only suffix questions and was paying the whole footprint for a map
+     * it never touched. Since these indexes are now retained for a whole
+     * resolution pass rather than rebuilt per import (#2877-#2880), that is
+     * retained memory against the #2649 kernel-scale OOM constraint.
+     *
+     * `null` until the first `getFilesInDir`; the MAP is memoized, not the
+     * decision to build it, so a repeated miss cannot rebuild it. Building it
+     * later is behaviour-identical because it is a pure function of
+     * `normalizedFileList` / `allFileList`, and it retains nothing new: every
+     * production caller already holds both arrays alive alongside the index
+     * (`WorkspaceFileIndex.normalized`/`.all`, the TS and Vue `PassCache`s,
+     * `IncludeExtractor.extract`'s locals).
+     */
+    let dirMap = null;
+    const getDirMap = () => {
+        if (dirMap !== null)
+            return dirMap;
+        const built = new Map();
+        for (let i = 0; i < normalizedFileList.length; i++) {
+            const normalized = normalizedFileList[i];
+            const original = allFileList[i];
+            const lastSlash = normalized.lastIndexOf('/');
+            // A file at the repo root is in no directory suffix.
+            if (lastSlash < 0)
+                continue;
+            // The file name from its last '.', or the WHOLE file name when it carries
+            // none — `substring(-1)` clamps to 0, which is what the `parts` form
+            // (`fileName.substring(fileName.lastIndexOf('.'))`) spelled. A '.' in a
+            // DIRECTORY is not an extension, hence `dot > lastSlash` rather than
+            // `dot >= 0`.
+            const dot = normalized.lastIndexOf('.');
+            const ext = dot > lastSlash ? normalized.slice(dot) : normalized.slice(lastSlash + 1);
+            // Every directory suffix of `normalized.slice(0, lastSlash)`, shortest
+            // first — the order `for (j = dirParts.length - 1; j >= 0; j--)` emitted,
+            // and load-bearing: `php.ts` returns `candidates[0]` of a bucket, so a
+            // reordered bucket is a behaviour change, not a wash.
+            //
+            // Walked as slash offsets into `normalized`, the same rewrite `getExactMap`
+            // above documents and for the same reason — a slice of the ORIGINAL string
+            // is byte-identical to the re-joined parts, and it allocates one string per
+            // suffix instead of a parts array, a slice array and a joined string per
+            // suffix. This is the map where it pays most: one entry, one array push AND
+            // one key per file per directory component, the "by far the most expensive"
+            // of the three. Measured 226.9 ms -> 173.1 ms at 32 000 paths averaging
+            // ~10 directory components (min of 9, both loops alternating in one
+            // process). Verified rather than argued, over a 32 000-path corpus
+            // carrying absolute paths, doubled separators (`a//b`), backslash paths,
+            // root-level and extensionless files, dotted directories and trailing
+            // separators: 272 956 keys and 329 361 bucket entries came out with
+            // identical key sets in identical INSERTION order and identical buckets
+            // element-for-element, and 767 732 probes of the built index — every
+            // emitted (directory, extension) pair plus a wrong-extension and a
+            // one-level-deeper miss for each — answered exactly as the `parts` form's
+            // map did. 0 differences.
+            //
+            // `slash < 0` is the whole directory, which no slash search can emit and
+            // the only suffix a one-component directory has.
+            let start = lastSlash;
+            while (start >= 0) {
+                const slash = start > 0 ? normalized.lastIndexOf('/', start - 1) : -1;
+                const key = `${normalized.slice(slash + 1, lastSlash)}:${ext}`;
+                let list = built.get(key);
                 if (!list) {
                     list = [];
-                    dirMap.set(key, list);
+                    built.set(key, list);
                 }
                 list.push(original);
+                start = slash;
             }
         }
-    }
+        dirMap = built;
+        return built;
+    };
     return {
-        get: (suffix) => exactMap.get(suffix),
-        getInsensitive: (suffix) => lowerMap.get(suffix.toLowerCase()),
+        get: (suffix) => getExactMap().get(suffix),
+        getInsensitive: (suffix) => getLowerMap().get(suffix.toLowerCase()),
+        // THIS implementation shares: it hands back `dirMap`'s own bucket rather
+        // than a copy. The map is built on first query and then held for the whole
+        // pass, so the window in which a mutating caller could corrupt later
+        // imports is the whole pass — which is why the interface makes the result
+        // `readonly` and the compiler refuses the mutation at the call site.
+        //
+        // Sharing beats copying because no caller keeps the array: two only measure
+        // it and two build a fresh array from it, so a defensive copy would
+        // allocate a whole bucket per import on the path this index exists to keep
+        // flat. `package-dir-index.ts` reached the same conclusion the same way —
+        // read-only containers, plus one copy where a bucket genuinely LEAVES
+        // (`sortedRootFiles`), which is the case `configs/swift.ts` is in.
         getFilesInDir: (dirSuffix, extension) => {
-            return dirMap.get(`${dirSuffix}:${extension}`) || [];
+            return getDirMap().get(`${dirSuffix}:${extension}`) || [];
         },
     };
 }

package/dist/core/ingestion/import-resolvers/workspace-file-index.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Per-file-set workspace index for the import-target resolvers that need the
+ * shared `SuffixIndex` (C#, Java, PHP, Ruby).
+ *
+ * The scope-resolution orchestrator passes the SAME `allFilePaths` Set object to
+ * every `resolveImportTarget` call in a pass (`pipeline/run.ts` builds it once),
+ * so memoizing on the Set's identity in a `WeakMap` turns the per-import
+ * "materialize two arrays + build a suffix index" cost into a one-time build.
+ *
+ * IMPORTANT for callers: the Set must be passed THROUGH, never copied. A
+ * defensive `new Set(allFilePaths)` in an adapter hands a fresh `WeakMap` key
+ * per call and silently restores the O(imports × files) behaviour — the exact
+ * bug PR #1918 shipped and had to fix in review (P1).
+ *
+ * Three layers guard that, and they guard different things:
+ *  - ADAPTER BOUNDARY, where the defensive-copy hazard actually lives:
+ *    `test/integration/*-import-index-reuse.test.ts` resolves through
+ *    `<lang>ScopeResolver.resolveImportTarget` — the orchestrator adapter — and
+ *    pins the EXACT number of times a run traverses the file set, one file per
+ *    covered language over that language's own corpus. (The expected count is
+ *    per language and legitimately differs: it is however many times the
+ *    adapter derives something from the Set — two indexes, or an index plus the
+ *    mutable copy the ts-family context wants.) All of them count traversals
+ *    of a `CountingSet` (`test/helpers/counting-file-set.ts`): one instrument,
+ *    no production surface, and it catches both the per-import rebuild and a
+ *    scan reintroduced beside a reused index (#2909).
+ *  - EVERY REGISTERED LANGUAGE, at the same boundary but as one property rather
+ *    than one corpus per language: `test/unit/scope-resolution/import-target-index-reuse.contract.test.ts`
+ *    drives each entry of `SCOPE_RESOLVERS` and asserts the traversal count for
+ *    many imports equals the count for two. A new language cannot skip it, and
+ *    the enforcement is a test rather than a roster anyone maintains: that
+ *    file's inventory arm compares `SCOPE_RESOLVERS`' keys against its own
+ *    fixture table and fails on a registered resolver that has neither a
+ *    fixture nor an exemption, and its next arm pins the exemption map empty.
+ *  - RESOLVER LEVEL: `test/unit/scope-resolution/import-target-index-parity.test.ts`
+ *    calls the resolvers directly, so it never crosses the adapter boundary and
+ *    a copy there leaves it green. What it catches is a rescan reintroduced
+ *    INSIDE a resolver, by counting how many times the Set is iterated.
+ */
+import { type SuffixIndex } from './utils.js';
+/**
+ * `normalized` and `all` are `readonly string[]`, and — like
+ * `SuffixIndex.getFilesInDir` — that is the CONTRACT rather than a description
+ * of the arrays: they are built once and then held for the whole pass, so an
+ * in-place `sort`/`splice`/`reverse` would corrupt every later import in that
+ * pass, and these two are the largest shared arrays here (one element per file,
+ * read by C#, Java, PHP and Ruby). `readonly` on the field is what makes the
+ * compiler refuse the mutation at the call site instead of leaving it to a
+ * comment. `ImportPassCache` (`pass-cache.ts`) states the same contract the
+ * same way for the ts-family lists.
+ *
+ * The positional pairing is load-bearing too and depends on it: `csharp.ts`
+ * caches POSITIONS into `normalized` and reads the answer out of `all`, so a
+ * reordering of either array alone silently re-points every cached position.
+ */
+export interface WorkspaceFileIndex {
+    /** Every path, backslashes normalized to `/`. Parallel to `all`. */
+    readonly normalized: readonly string[];
+    /** Every path, exactly as it appears in the Set. Parallel to `normalized`. */
+    readonly all: readonly string[];
+    /** Segment-suffix → first file (in Set iteration order) carrying that suffix. */
+    readonly index: SuffixIndex;
+    /**
+     * Normalized path → first raw path that normalizes to it. Answers "is there a
+     * file whose WHOLE path is X", which `index.get(X)` cannot: the suffix map
+     * conflates a whole-path hit with a `…/X` suffix hit, and C#'s
+     * `resolveDirectMatch` lets a whole-path match win over an earlier suffix
+     * match.
+     */
+    readonly normToRaw: Map<string, string>;
+}
+export declare const getWorkspaceFileIndex: (key: ReadonlySet<string>) => WorkspaceFileIndex;

package/dist/core/ingestion/import-resolvers/workspace-file-index.js

@@ -0,0 +1,58 @@
+/**
+ * Per-file-set workspace index for the import-target resolvers that need the
+ * shared `SuffixIndex` (C#, Java, PHP, Ruby).
+ *
+ * The scope-resolution orchestrator passes the SAME `allFilePaths` Set object to
+ * every `resolveImportTarget` call in a pass (`pipeline/run.ts` builds it once),
+ * so memoizing on the Set's identity in a `WeakMap` turns the per-import
+ * "materialize two arrays + build a suffix index" cost into a one-time build.
+ *
+ * IMPORTANT for callers: the Set must be passed THROUGH, never copied. A
+ * defensive `new Set(allFilePaths)` in an adapter hands a fresh `WeakMap` key
+ * per call and silently restores the O(imports × files) behaviour — the exact
+ * bug PR #1918 shipped and had to fix in review (P1).
+ *
+ * Three layers guard that, and they guard different things:
+ *  - ADAPTER BOUNDARY, where the defensive-copy hazard actually lives:
+ *    `test/integration/*-import-index-reuse.test.ts` resolves through
+ *    `<lang>ScopeResolver.resolveImportTarget` — the orchestrator adapter — and
+ *    pins the EXACT number of times a run traverses the file set, one file per
+ *    covered language over that language's own corpus. (The expected count is
+ *    per language and legitimately differs: it is however many times the
+ *    adapter derives something from the Set — two indexes, or an index plus the
+ *    mutable copy the ts-family context wants.) All of them count traversals
+ *    of a `CountingSet` (`test/helpers/counting-file-set.ts`): one instrument,
+ *    no production surface, and it catches both the per-import rebuild and a
+ *    scan reintroduced beside a reused index (#2909).
+ *  - EVERY REGISTERED LANGUAGE, at the same boundary but as one property rather
+ *    than one corpus per language: `test/unit/scope-resolution/import-target-index-reuse.contract.test.ts`
+ *    drives each entry of `SCOPE_RESOLVERS` and asserts the traversal count for
+ *    many imports equals the count for two. A new language cannot skip it, and
+ *    the enforcement is a test rather than a roster anyone maintains: that
+ *    file's inventory arm compares `SCOPE_RESOLVERS`' keys against its own
+ *    fixture table and fails on a registered resolver that has neither a
+ *    fixture nor an exemption, and its next arm pins the exemption map empty.
+ *  - RESOLVER LEVEL: `test/unit/scope-resolution/import-target-index-parity.test.ts`
+ *    calls the resolvers directly, so it never crosses the adapter boundary and
+ *    a copy there leaves it green. What it catches is a rescan reintroduced
+ *    INSIDE a resolver, by counting how many times the Set is iterated.
+ */
+import { perFileSet } from './per-file-set.js';
+import { buildSuffixIndex } from './utils.js';
+export const getWorkspaceFileIndex = perFileSet((allFilePaths) => {
+    const all = [...allFilePaths];
+    const normalized = all.map((f) => f.replace(/\\/g, '/'));
+    const normToRaw = new Map();
+    for (let i = 0; i < normalized.length; i++) {
+        // First wins, mirroring the `for (const raw of allFilePaths)` scans this
+        // replaces: they returned on the first match in iteration order.
+        if (!normToRaw.has(normalized[i]))
+            normToRaw.set(normalized[i], all[i]);
+    }
+    return {
+        normalized,
+        all,
+        index: buildSuffixIndex(normalized, all),
+        normToRaw,
+    };
+});