gitnexus 1.6.10-rc.183 → 1.6.10-rc.185

package/dist/core/ingestion/import-resolvers/configs/csharp.js

@@ -24,7 +24,11 @@ export const csharpNamespaceStrategy = (rawImportPath, _filePath, ctx) => {
         }
         return null;
     }
-    const resolvedFiles = resolveCSharpImportInternal(rawImportPath, csharpConfigs, ctx.normalizedFileList, ctx.allFileList, ctx.index, evidence);
+    const resolvedFiles = resolveCSharpImportInternal(rawImportPath, csharpConfigs, 
+    // The Set, not `ctx.normalizedFileList`/`ctx.allFileList`: the resolver
+    // derives both from it through the same per-pass memo the ctx's own arrays
+    // come from, so this is the identical pair by a shorter route.
+    ctx.allFilePaths, ctx.index, evidence);
     if (resolvedFiles.length > 1) {
         const dirSuffix = resolveCSharpNamespaceDir(rawImportPath, csharpConfigs);
         if (dirSuffix) {

package/dist/core/ingestion/import-resolvers/configs/swift.js

@@ -31,6 +31,19 @@ import { SupportedLanguages } from '../../../../_shared/index.js';
  * stable reference and the index is built once — not once per import. A
  * fresh run produces a fresh array → a fresh index, so cross-run staleness
  * is impossible.
+ *
+ * DELIBERATELY NOT ON `import-resolvers/per-file-set.ts` (#2909 sweep): this is
+ * a TWO-input memo keyed on ONE of them. The index is a function of both
+ * `ctx` (`allFileList` + the index-aligned `normalizedFileList`) and `targets`,
+ * but the key is only `ctx.allFileList`, and `perFileSet`'s `build: (key) => T`
+ * hands the builder nothing but the key. It is sound here only because of an
+ * invariant OUTSIDE the memo — `targets` is `ctx.configs.swiftPackageConfig
+ * .targets`, so it shares `ctx`'s lifetime and cannot vary while
+ * `ctx.allFileList` is fixed — and `perFileSet` has no way to express "and this
+ * other input is pinned by the same lifetime". Re-keying on `ctx` to make
+ * `targets` derivable from the key would change what the cache is keyed on and
+ * force an unreachable null-config arm into the builder, so it is a behaviour
+ * change rather than a consolidation. Leave it hand-rolled.
  */
 const SWIFT_TARGET_INDEX_CACHE = new WeakMap();
 function getSwiftTargetIndex(ctx, targets) {

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

@@ -13,8 +13,16 @@ import type { CSharpProjectConfig, CSharpNamespaceEvidence } from '../language-c
  * The final unanchored suffix fallback is gated on `evidence` so BCL usings
  * (e.g. `System.Threading.Tasks`) can't match a coincidentally-named local
  * file (#1881). When `evidence` is omitted the fallback stays permissive.
+ *
+ * Takes the file SET, not the two materialized lists it used to take: both are
+ * derived here from the per-pass `getWorkspaceFileIndex` memo, which is where
+ * every caller already got them. That leaves one key shape for the indexes
+ * below and makes the `normalized`/`all` pairing structural rather than a
+ * contract the caller has to honour. `index` stays a parameter — the parity
+ * harness drives this resolver with and without one, and the no-index legs are
+ * a tested dimension, not a degenerate case.
  */
-export declare function resolveCSharpImportInternal(importPath: string, csharpConfigs: CSharpProjectConfig[], normalizedFileList: string[], allFileList: string[], index?: SuffixIndex, evidence?: CSharpNamespaceEvidence): string[];
+export declare function resolveCSharpImportInternal(importPath: string, csharpConfigs: CSharpProjectConfig[], allFilePaths: ReadonlySet<string>, index?: SuffixIndex, evidence?: CSharpNamespaceEvidence): string[];
 /**
  * Compute the directory suffix for a C# namespace import (for PackageMap).
  * Returns a suffix like "/ProjectDir/Models/" or null if no config matches.

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

@@ -4,8 +4,154 @@
  * Strategy lives in configs/csharp.ts.
  * This file contains shared helpers for namespace-based resolution.
  */
+import { perFileSet } from './per-file-set.js';
+import { getWorkspaceFileIndex } from './workspace-file-index.js';
 import { suffixResolve } from './utils.js';
 import { csharpSuffixFallbackAllowed } from '../csharp-namespace-gate.js';
+/**
+ * Memoized on the file SET's identity, the same key every other per-file-set
+ * index in this pipeline uses: the orchestrator builds one Set per pass and
+ * threads it through every import, so this build runs once.
+ *
+ * It used to key on the `normalizedFileList` ARRAY, which was a second key
+ * shape and — more to the point — one no guard could instrument. Copying an
+ * array mints a fresh `WeakMap` key while traversing the SET zero extra times,
+ * so a `[...normalized]` copy at the adapter boundary rebuilt this index once
+ * per `using` while every scan-counting guard stayed green and only the timing
+ * bench noticed (#2911 review). Taking the array from
+ * `getWorkspaceFileIndex(allFilePaths)` inside the builder retires that shape:
+ * the only way to defeat the memo now is to copy the Set, which is exactly what
+ * `CountingSet` counts.
+ *
+ * It also retires a precondition. The cached positions index `normalized` while
+ * the emitted value is read from `all`; both now come from the same
+ * `getWorkspaceFileIndex` object, so the caller can no longer pair a position
+ * list against a differently-ordered array.
+ */
+const getCsharpNamespaceDirIndex = perFileSet((allFilePaths) => {
+    const { normalized: normalizedFileList } = getWorkspaceFileIndex(allFilePaths);
+    const dirsByLastSegment = new Map();
+    const positionsByDir = new Map();
+    const singleSegmentDirs = [];
+    for (let i = 0; i < normalizedFileList.length; i++) {
+        const normalized = normalizedFileList[i];
+        if (!normalized.endsWith('.cs'))
+            continue;
+        const lastSlash = normalized.lastIndexOf('/');
+        // A file with no directory can never match: the needle always ends with
+        // '/', so `indexOf` on a slash-free path is always -1.
+        if (lastSlash < 0)
+            continue;
+        const dir = normalized.slice(0, lastSlash);
+        let positions = positionsByDir.get(dir);
+        if (positions === undefined) {
+            positions = [];
+            positionsByDir.set(dir, positions);
+            const lastSegment = dir.slice(dir.lastIndexOf('/') + 1);
+            if (lastSegment === dir)
+                singleSegmentDirs.push(dir);
+            let dirs = dirsByLastSegment.get(lastSegment);
+            if (dirs === undefined) {
+                dirs = [];
+                dirsByLastSegment.set(lastSegment, dirs);
+            }
+            dirs.push(dir);
+        }
+        positions.push(i);
+    }
+    return { dirsByLastSegment, positionsByDir, singleSegmentDirs };
+});
+/**
+ * Every directory that could satisfy `dirPrefix`, as a superset — the exact
+ * test runs in `matchingDirPositions`.
+ *
+ * When `dirPrefix` contains a '/', its own slash forces a segment boundary in
+ * any matching directory: `H` ending with `…/<lastSeg>/` means `D` ends with
+ * `/<lastSeg>`, so `D`'s last segment IS `lastSeg` and the exact bucket is
+ * complete. Without a '/', `D`'s last segment only has to END with `dirPrefix`
+ * (`SubModels` for `Models`), which no single bucket holds, so the last-segment
+ * KEYS are swept. That is the one term here that is not O(matches), and it is
+ * O(distinct last segments), not O(directories): C# repos reuse `Models`,
+ * `Services`, `Controllers` under every project, so the sweep collapses on the
+ * layouts that actually occur. Measured at 200 000 `.cs` files, 25 000
+ * directories: 456 µs per import when every directory name is unique, 7.9 µs
+ * on a `SrcN/Models` layout. Closing the unique-name case needs a character-
+ * suffix map over the segments, which is the O(files × depth) memory shape
+ * `package-dir-index.ts` cites #2649 to avoid — a design change, not a tune.
+ *
+ * An empty `dirPrefix` would sweep every key and keep every directory, so it is
+ * answered from `singleSegmentDirs` instead: its needle is a bare '/', which
+ * only a slash-free directory can carry as its LAST slash.
+ */
+function* candidateDirs(index, dirPrefix) {
+    if (dirPrefix === '') {
+        yield* index.singleSegmentDirs;
+        return;
+    }
+    const lastSlash = dirPrefix.lastIndexOf('/');
+    if (lastSlash >= 0) {
+        const bucket = index.dirsByLastSegment.get(dirPrefix.slice(lastSlash + 1));
+        if (bucket !== undefined)
+            yield* bucket;
+        return;
+    }
+    for (const [lastSegment, dirs] of index.dirsByLastSegment) {
+        if (!lastSegment.endsWith(dirPrefix))
+            continue;
+        yield* dirs;
+    }
+}
+/** Positions of the `.cs` files in each directory matching `dirPrefix`. */
+function* matchingDirPositions(index, dirPrefix) {
+    const needle = dirPrefix + '/';
+    for (const dir of candidateDirs(index, dirPrefix)) {
+        const haystack = dir + '/';
+        // The length guard is not redundant: for a shorter `haystack`, `indexOf`
+        // returns -1 and `haystack.length - needle.length` can also be -1, which
+        // would report a bogus match.
+        if (haystack.length < needle.length)
+            continue;
+        if (haystack.indexOf(needle) !== haystack.length - needle.length)
+            continue;
+        const positions = index.positionsByDir.get(dir);
+        if (positions !== undefined)
+            yield positions;
+    }
+}
+/**
+ * Append every `.cs` file directly inside a directory matching `dirPrefix`, in
+ * `normalizedFileList` order — the order the single-pass scan emitted, which
+ * this function's callers return as the whole edge target list.
+ */
+function pushFilesDirectlyInNamespaceDir(index, dirPrefix, allFileList, results) {
+    // One matching directory is the overwhelmingly common case, and its positions
+    // are already ascending, so the first bucket is held by reference. A second
+    // one promotes it to a real accumulator that is appended to from then on —
+    // never re-spread per directory, which would cost O(files × dirs²) copies in
+    // a monorepo carrying the same namespace directory under many projects.
+    let first = null;
+    let merged = null;
+    for (const positions of matchingDirPositions(index, dirPrefix)) {
+        if (first === null) {
+            first = positions;
+            continue;
+        }
+        if (merged === null)
+            merged = [...first];
+        for (const position of positions)
+            merged.push(position);
+    }
+    if (first === null)
+        return;
+    if (merged === null) {
+        for (const position of first)
+            results.push(allFileList[position]);
+        return;
+    }
+    merged.sort((a, b) => a - b);
+    for (const position of merged)
+        results.push(allFileList[position]);
+}
 /**
  * Resolve a C# using-directive import path to matching .cs files (low-level helper).
  * Tries single-file match first, then directory match for namespace imports.
@@ -13,8 +159,17 @@ import { csharpSuffixFallbackAllowed } from '../csharp-namespace-gate.js';
  * The final unanchored suffix fallback is gated on `evidence` so BCL usings
  * (e.g. `System.Threading.Tasks`) can't match a coincidentally-named local
  * file (#1881). When `evidence` is omitted the fallback stays permissive.
+ *
+ * Takes the file SET, not the two materialized lists it used to take: both are
+ * derived here from the per-pass `getWorkspaceFileIndex` memo, which is where
+ * every caller already got them. That leaves one key shape for the indexes
+ * below and makes the `normalized`/`all` pairing structural rather than a
+ * contract the caller has to honour. `index` stays a parameter — the parity
+ * harness drives this resolver with and without one, and the no-index legs are
+ * a tested dimension, not a degenerate case.
  */
-export function resolveCSharpImportInternal(importPath, csharpConfigs, normalizedFileList, allFileList, index, evidence) {
+export function resolveCSharpImportInternal(importPath, csharpConfigs, allFilePaths, index, evidence) {
+    const { normalized: normalizedFileList, all: allFileList } = getWorkspaceFileIndex(allFilePaths);
     const namespacePath = importPath.replace(/\./g, '/');
     const results = [];
     for (const config of csharpConfigs) {
@@ -65,24 +220,26 @@ export function resolveCSharpImportInternal(importPath, csharpConfigs, normalize
             if (results.length > 0)
                 return results;
         }
-        // 3. Linear scan fallback for directory matching
-        if (results.length === 0) {
-            const dirTrail = dirPrefix + '/';
-            for (let i = 0; i < normalizedFileList.length; i++) {
-                const normalized = normalizedFileList[i];
-                if (!normalized.endsWith('.cs'))
-                    continue;
-                const prefixIdx = normalized.indexOf(dirTrail);
-                if (prefixIdx < 0)
-                    continue;
-                const afterDir = normalized.substring(prefixIdx + dirTrail.length);
-                if (!afterDir.includes('/')) {
-                    results.push(allFileList[i]);
-                }
-            }
-            if (results.length > 0)
-                return results;
-        }
+        // 3. Directory matching, UNANCHORED.
+        //
+        // Not redundant with step 2, and not skippable when `index` is present:
+        // `getFilesInDir` is keyed on SEGMENT suffixes of a directory, while this
+        // leg's predicate is an unanchored substring one, so it additionally
+        // answers `Models` with `src/SubModels/` and `src/Models` with
+        // `vendor/mysrc/Models/`. It is also the only leg that answers an empty
+        // `dirPrefix` — the `relative = ''` branch above (the import IS the root
+        // namespace) with no `projectDir` to stand in for it — because
+        // `buildSuffixIndex` emits an empty directory suffix only for a path that
+        // BEGINS with '/', so over repo-relative paths `getFilesInDir('', '.cs')`
+        // is always empty. See `CsharpNamespaceDirIndex` above for the index that
+        // replaced the per-import Θ(files) scan this used to be (#2902).
+        //
+        // `results` is provably empty here: step 2 returns as soon as it pushes
+        // anything, and so does this leg, so every iteration of the config loop
+        // starts empty.
+        pushFilesDirectlyInNamespaceDir(getCsharpNamespaceDirIndex(allFilePaths), dirPrefix, allFileList, results);
+        if (results.length > 0)
+            return results;
     }
     // Fallback: suffix matching without namespace stripping (single file).
     // Gated on in-repo declared-namespace evidence (#1881).

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

@@ -14,4 +14,4 @@ export declare function resolveGoPackageDir(importPath: string, goModule: GoModu
  * Resolve a Go internal package import to all .go files in the package directory.
  * Returns an array of file paths.
  */
-export declare function resolveGoPackage(importPath: string, goModule: GoModuleConfig, normalizedFileList: string[], allFileList: string[]): string[];
+export declare function resolveGoPackage(importPath: string, goModule: GoModuleConfig, normalizedFileList: readonly string[], allFileList: readonly string[]): string[];

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

@@ -18,10 +18,10 @@ export declare const appendKotlinWildcard: (importPath: string, importNode: Synt
  * Resolve a JVM wildcard import (com.example.*) to all matching files.
  * Works for both Java (.java) and Kotlin (.kt, .kts).
  */
-export declare function resolveJvmWildcard(importPath: string, normalizedFileList: string[], allFileList: string[], extensions: readonly string[], index?: SuffixIndex): string[];
+export declare function resolveJvmWildcard(importPath: string, normalizedFileList: readonly string[], allFileList: readonly string[], extensions: readonly string[], index?: SuffixIndex): string[];
 /**
  * Try to resolve a JVM member/static import by stripping the member name.
  * Java: "com.example.Constants.VALUE" -> resolve "com.example.Constants"
  * Kotlin: "com.example.Constants.VALUE" -> resolve "com.example.Constants"
  */
-export declare function resolveJvmMemberImport(importPath: string, normalizedFileList: string[], allFileList: string[], extensions: readonly string[], index?: SuffixIndex): string | null;
+export declare function resolveJvmMemberImport(importPath: string, normalizedFileList: readonly string[], allFileList: readonly string[], extensions: readonly string[], index?: SuffixIndex): string | null;

package/dist/core/ingestion/import-resolvers/pass-cache.d.ts

@@ -0,0 +1,50 @@
+import { type SuffixIndex } from './utils.js';
+/**
+ * Everything the standard `resolveTsTarget` path derives from one workspace
+ * file set: the file list, the lower-cased file list, the suffix index and the
+ * per-pass `resolveCache`.
+ *
+ * Without this memoization the resolver re-derived `allFileList` and
+ * `normalizedFileList` (both O(N_files)), rebuilt the index and threw away the
+ * `resolveCache` on every import — O(N_files × N_imports) total work for what
+ * should be O(N_files + N_imports).
+ */
+export interface ImportPassCache {
+    readonly allFilePaths: Set<string>;
+    readonly allFileList: readonly string[];
+    readonly normalizedFileList: readonly string[];
+    readonly index: SuffixIndex;
+    readonly resolveCache: Map<string, string | null>;
+}
+/**
+ * Build that state. Shared by every adapter whose resolution runs through
+ * `resolveTsTarget`.
+ *
+ * Not a dedup of identical copies, and the difference is the point. At
+ * 49c5b7d81 each of those adapters carried this record inline and they did NOT
+ * agree: `languages/typescript/scope-resolver.ts` and
+ * `languages/vue/import-target.ts` held six byte-identical fields built around
+ * `index: buildSuffixIndex(normalizedFileList, allFileList)`, while
+ * `languages/javascript/import-target.ts` held five and never called
+ * `buildSuffixIndex` at all. That one missing field IS the O(imports × files)
+ * defect PR #2911 fixed — `resolveTsTarget` fell back to `suffixResolve`'s
+ * linear scan for every JavaScript import — and the header of
+ * `languages/javascript/import-target.ts` carries the measurements. Hoisting
+ * the builder is what makes a fourth adapter unable to omit it again: `index`
+ * is not optional on `ImportPassCache`.
+ *
+ * The BUILDER is shared; the MEMO deliberately is not. Each adapter wraps this
+ * in its own `perFileSet(...)`, so each gets its own `WeakMap`, its own index
+ * instance and — the one that would be a behaviour change — its own
+ * `resolveCache`. The languages disagree about what a specifier resolves to
+ * (`tsconfigPaths` is read from config for TypeScript and Vue, pinned to `null`
+ * for JavaScript, and the tried extension list differs), so one shared resolve
+ * cache across them would hand a language another language's answers.
+ *
+ * Sharing the builder is a code dedup and nothing more: it buys no runtime
+ * reuse, because there is none to buy. Each provider pass builds its own
+ * `allFilePaths` Set (`scope-resolution/pipeline/run.ts`, per provider), so
+ * TypeScript's set and JavaScript's set are different objects and therefore
+ * different `WeakMap` keys even where the two memos are the same code.
+ */
+export declare function buildImportPassCache(allFilePaths: ReadonlySet<string>): ImportPassCache;

package/dist/core/ingestion/import-resolvers/pass-cache.js

@@ -0,0 +1,60 @@
+import { buildSuffixIndex } from './utils.js';
+/**
+ * Build that state. Shared by every adapter whose resolution runs through
+ * `resolveTsTarget`.
+ *
+ * Not a dedup of identical copies, and the difference is the point. At
+ * 49c5b7d81 each of those adapters carried this record inline and they did NOT
+ * agree: `languages/typescript/scope-resolver.ts` and
+ * `languages/vue/import-target.ts` held six byte-identical fields built around
+ * `index: buildSuffixIndex(normalizedFileList, allFileList)`, while
+ * `languages/javascript/import-target.ts` held five and never called
+ * `buildSuffixIndex` at all. That one missing field IS the O(imports × files)
+ * defect PR #2911 fixed — `resolveTsTarget` fell back to `suffixResolve`'s
+ * linear scan for every JavaScript import — and the header of
+ * `languages/javascript/import-target.ts` carries the measurements. Hoisting
+ * the builder is what makes a fourth adapter unable to omit it again: `index`
+ * is not optional on `ImportPassCache`.
+ *
+ * The BUILDER is shared; the MEMO deliberately is not. Each adapter wraps this
+ * in its own `perFileSet(...)`, so each gets its own `WeakMap`, its own index
+ * instance and — the one that would be a behaviour change — its own
+ * `resolveCache`. The languages disagree about what a specifier resolves to
+ * (`tsconfigPaths` is read from config for TypeScript and Vue, pinned to `null`
+ * for JavaScript, and the tried extension list differs), so one shared resolve
+ * cache across them would hand a language another language's answers.
+ *
+ * Sharing the builder is a code dedup and nothing more: it buys no runtime
+ * reuse, because there is none to buy. Each provider pass builds its own
+ * `allFilePaths` Set (`scope-resolution/pipeline/run.ts`, per provider), so
+ * TypeScript's set and JavaScript's set are different objects and therefore
+ * different `WeakMap` keys even where the two memos are the same code.
+ */
+export function buildImportPassCache(allFilePaths) {
+    const allFileList = Array.from(allFilePaths);
+    // LOWERCASED, not slash-normalized — unlike every other caller of
+    // `buildSuffixIndex`. That is what `alreadyLowercased` below records.
+    const normalizedFileList = allFileList.map((f) => f.toLowerCase());
+    return {
+        // Copied ONCE per file set, not once per import: `TsResolveContext` wants a
+        // mutable `Set` and the orchestrator hands us a `ReadonlySet`. The copy is
+        // not the #1918 hazard because the cache KEY is the caller's original Set.
+        allFilePaths: new Set(allFilePaths),
+        allFileList,
+        normalizedFileList,
+        // Every suffix of an all-lowercase path is itself lowercase, so the index's
+        // case-folded map came out a byte-for-byte copy of its exact map — same
+        // keys, same values, same insertion order — one per `ImportPassCache`, so
+        // once per adapter per pass. Measured 14.00 MiB at 32 000 paths, 29.8% of
+        // the retained `ImportPassCache`. The flag drops the copy; it does not change
+        // what `getInsensitive` answers, because the copy was the identity (see
+        // `SuffixIndexOptions`). Checked, not assumed: over 474 524 probes on four
+        // mixed-case corpora — Vue PascalCase plus alias specifiers, case-colliding
+        // twins, a 600-file deep monorepo, and Unicode paths carrying final sigma,
+        // dotted-I and sharp-S — the two maps came out byte-identical, the exact
+        // map was the sole answerer 0 times, and `get(s) || getInsensitive(s)`
+        // returned the same file 474 524 times out of 474 524.
+        index: buildSuffixIndex(normalizedFileList, allFileList, { alreadyLowercased: true }),
+        resolveCache: new Map(),
+    };
+}

package/dist/core/ingestion/import-resolvers/per-file-set.d.ts

@@ -0,0 +1,71 @@
+/**
+ * The one memo every per-file-set index in this pipeline is built on.
+ *
+ * The scope-resolution orchestrator builds ONE file-set object per provider
+ * pass and threads that same object through every `resolveImportTarget` call in
+ * the pass, so anything derived from it — a suffix index, a package-directory
+ * map, a basename bucket — can be built once and read by every import instead
+ * of rebuilt per import. Keying on the object's IDENTITY is what makes that
+ * work, and it is equally the contract callers must keep: the set is passed
+ * THROUGH, never copied. A defensive `new Set(allFilePaths)` at an adapter
+ * boundary hands a fresh key per import and silently restores
+ * O(imports × files) — the bug PR #1918 shipped and had to fix in review (P1).
+ * The guards are `test/integration/<lang>-import-index-reuse.test.ts` and, for
+ * every registered language at once,
+ * `test/unit/scope-resolution/import-target-index-reuse.contract.test.ts`,
+ * whose inventory arm fails when an entry of `SCOPE_RESOLVERS` has no fixture.
+ * That arm is why no language is named here: the registry is the census, and a
+ * hand-copied list of languages goes stale the release after it is written.
+ *
+ * A `WeakMap` rather than a `Map`: the entry is reclaimed with the file set it
+ * was derived from, so a pass can never read a previous pass's index and memory
+ * does not grow across runs. There is no invalidation rule to get wrong because
+ * there is nothing to invalidate — a new file set is a new key.
+ *
+ * The KEY TYPE is constrained rather than described, because which object is
+ * the key decides whether the guards above can see the memo fail, and a prose
+ * list of call sites is the thing this file elsewhere tells you not to write.
+ * `K` admits exactly the two shapes the orchestrator keeps stable for a pass:
+ *
+ *  - `ReadonlySet<string>`, the pass's file set — every index derived from it,
+ *    including the derived header-closure sets that `languages/{c,cpp}/
+ *    scope-resolver.ts` memoize inside an outer per-file-set memo. Defeating
+ *    one of these means copying the SET, which re-traverses it, which the
+ *    `CountingSet` instrument (`test/helpers/counting-file-set.ts`) reads as a
+ *    scan count rising with the import count.
+ *  - `readonly ParsedFile[]`, the pass's parsed-file array. Not derived from
+ *    the file set at all, so the file-set guards do not reach them; these key
+ *    on the array the orchestrator already threads through the pass, and their
+ *    contract is that same pass-through discipline. The instrument that CAN see
+ *    them counts element reads on that array — `countedParsedFiles`, beside
+ *    `CountingSet`, driven by the contract test's `minimumParsedFileReads`.
+ *
+ * A THIRD shape — an array materialized from the file set — is what the type
+ * exists to reject. `import-resolvers/csharp.ts` used one until #2911, and it
+ * is worth a compile error rather than a rule: copying an array mints a fresh
+ * `WeakMap` key while traversing the Set zero extra times, so every
+ * scan-counting guard stays green at its correct value while the index rebuilds
+ * once per import. That failure is invisible to the whole instrument family
+ * above and was caught only by a timing ratio in `bench/import-target/`. Derive
+ * the array inside the builder from `getWorkspaceFileIndex(allFilePaths)`
+ * instead. `string[]` is not assignable to `K`, so the shape cannot come back
+ * silently — `configs/swift.ts` keeps the one hand-rolled `WeakMap` on
+ * `ctx.allFileList` in the tree, deliberately and with its reasons written
+ * down, and it is deliberately NOT on this primitive.
+ *
+ * `T extends object` is deliberate, chosen over probing `has` before `get`.
+ * `WeakMap.get` returning `undefined` cannot distinguish "not built yet" from
+ * "built, and the value is `undefined`"; constraining the value to an object
+ * makes the second case unrepresentable rather than paying a second lookup on
+ * every import, and it needs no cast to type-check. Every index memoized here
+ * is a record, `Map` or `Set`, so the constraint costs nothing today — and a
+ * later caller wanting to memoize a `string | null` gets a compile error
+ * pointing at this line instead of a memo that silently rebuilds on every miss.
+ *
+ * A `build` that THROWS stores nothing, so the next call for that key runs it
+ * again: failures are not memoized, and a half-filled index is never published.
+ * Inert for the builders here — each is a pure, total pass over the file set —
+ * and the safer of the two behaviours if that ever stops being true.
+ */
+import type { ParsedFile } from '../../../_shared/index.js';
+export declare function perFileSet<K extends ReadonlySet<string> | readonly ParsedFile[], T extends object>(build: (key: K) => T): (key: K) => T;

package/dist/core/ingestion/import-resolvers/per-file-set.js

@@ -0,0 +1,11 @@
+export function perFileSet(build) {
+    const cache = new WeakMap();
+    return (key) => {
+        const cached = cache.get(key);
+        if (cached !== undefined)
+            return cached;
+        const built = build(key);
+        cache.set(key, built);
+        return built;
+    };
+}

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

@@ -21,4 +21,4 @@ import type { ComposerConfig } from '../language-config.js';
  * a known limitation — PHP function imports cannot be resolved to a specific file
  * without parsing all candidate files.
  */
-export declare function resolvePhpImportInternal(importPath: string, composerConfig: ComposerConfig | null, allFiles: Set<string>, normalizedFileList: string[], allFileList: string[], index?: SuffixIndex): string | null;
+export declare function resolvePhpImportInternal(importPath: string, composerConfig: ComposerConfig | null, allFiles: Set<string>, normalizedFileList: readonly string[], allFileList: readonly string[], index?: SuffixIndex): string | null;

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

@@ -53,19 +53,38 @@ export function resolvePhpImportInternal(importPath, composerConfig, allFiles, n
                 //    e.g. App\Models\getUser → directory app/Models/, find first .php file in that dir.
                 const lastSlash = remainder.lastIndexOf('/');
                 const nsDir = lastSlash >= 0 ? dirPrefix + '/' + remainder.slice(0, lastSlash) : dirPrefix;
-                // Prefer SuffixIndex directory lookup (O(log n + matches)) over linear scan
+                // Prefer SuffixIndex directory lookup (O(log n + matches)) over linear scan.
+                //
+                // An EMPTY bucket is a final answer, not a miss to retry with the scan
+                // below — which is what the `else` restores, and what this comment
+                // always claimed. Re-scanning on empty was the last per-import
+                // workspace traversal left in PHP resolution after #2901: any `use`
+                // matching a PSR-4 prefix whose directory holds no direct `.php` child
+                // (`App\Legacy\Ghost`) paid a full pass, measured at 201 traversals for
+                // 200 imports.
+                //
+                // The bucket is a superset of what the scan can find, for BOTH index
+                // shapes that reach here. A root-anchored direct child `nsDir/<x>.php`
+                // has its directory exactly equal to `nsDir`, and `nsDir` is always one
+                // of that directory's own suffixes — so the shared `dirMap` (keyed on
+                // every directory suffix) necessarily contains it, as does the
+                // root-anchored parity index `languages/php/import-target.ts` builds.
+                // Empty superset therefore implies empty scan, and control falls
+                // through to the next PSR-4 prefix exactly as before.
                 if (index) {
                     const candidates = index.getFilesInDir(nsDir, '.php');
                     if (candidates.length > 0)
                         return candidates[0];
                 }
-                // Fallback: linear scan (only when SuffixIndex unavailable)
-                const nsDirPrefix = nsDir.endsWith('/') ? nsDir : nsDir + '/';
-                for (const f of allFiles) {
-                    if (f.startsWith(nsDirPrefix) &&
-                        f.endsWith('.php') &&
-                        !f.slice(nsDirPrefix.length).includes('/')) {
-                        return f;
+                else {
+                    // Linear scan, only when a SuffixIndex is genuinely unavailable.
+                    const nsDirPrefix = nsDir.endsWith('/') ? nsDir : nsDir + '/';
+                    for (const f of allFiles) {
+                        if (f.startsWith(nsDirPrefix) &&
+                            f.endsWith('.php') &&
+                            !f.slice(nsDirPrefix.length).includes('/')) {
+                            return f;
+                        }
                     }
                 }
             }