gitnexus 1.6.10-rc.98 → 1.6.10

package/dist/core/ingestion/languages/python/import-target.js

@@ -9,8 +9,9 @@
  * Returning `null` lets the finalize algorithm mark the edge as
  * `linkStatus: 'unresolved'`.
  */
+import { perFileSet } from '../../import-resolvers/per-file-set.js';
+import { getPythonFileIndex, importerAncestors, importerDirOf, } from '../../import-resolvers/python-file-index.js';
 import { resolvePythonImportInternal } from '../../import-resolvers/python.js';
-import { recordPythonFileIndexBuild } from './index-stats.js';
 export function resolvePythonImportTarget(parsedImport, workspaceIndex) {
     // WorkspaceIndex is `unknown` in the shared contract (Ring 1
     // placeholder). The scope-resolution orchestrator hands us a
@@ -33,6 +34,56 @@ export function resolvePythonImportTarget(parsedImport, workspaceIndex) {
         return null;
     if (parsedImport.targetRaw === null || parsedImport.targetRaw === '')
         return null;
+    const submoduleTarget = pythonImportedSubmoduleTarget(parsedImport);
+    if (submoduleTarget !== null &&
+        (parsedImport.kind === 'named' || parsedImport.kind === 'alias')) {
+        // Python's IMPORT_FROM first reads an attribute already exported by the
+        // package and only loads a same-named submodule when that attribute is
+        // absent. Preserve that precedence when parsed workspace facts are
+        // available; the flag suppresses this submodule probe in the recursive
+        // base-package lookup.
+        const packageTarget = resolvePythonImportTarget({ ...parsedImport, targetIncludesImportedName: true }, workspaceIndex);
+        if (packageTarget !== null &&
+            pythonFileExportsName(packageTarget, parsedImport.importedName, ctx.parsedFiles)) {
+            return packageTarget;
+        }
+        const submodule = resolvePythonImportTarget({
+            kind: 'namespace',
+            localName: parsedImport.localName,
+            importedName: parsedImport.importedName,
+            targetRaw: submoduleTarget,
+        }, workspaceIndex);
+        if (submodule !== null)
+            return submodule;
+        // `return packageTarget`, not `if (packageTarget !== null) return …` —
+        // falling through when it is null RE-RAN THE ENTIRE TAIL BELOW, a second
+        // time, with byte-identical arguments.
+        //
+        // `packageTarget` IS this function's tail for this import. The recursion
+        // above differs from the outer frame in exactly one field,
+        // `targetIncludesImportedName`, whose only effect is to make
+        // `pythonImportedSubmoduleTarget` return null and so skip this branch: the
+        // spread preserves `kind` (still `named`/`alias`, so the
+        // `dynamic-unresolved` guard cannot fire) and `targetRaw` (which already
+        // passed the null/empty guard), and `workspaceIndex` is the same object, so
+        // `ctx.fromFile`, `ctx.allFilePaths` and `ctx.parsedFiles` are the same
+        // references. The recursion therefore ran `resolvePythonImportInternal` →
+        // relative gate → `hasRepoCandidate` → `resolveAbsoluteFromFiles` on
+        // exactly the inputs the fallthrough would use.
+        //
+        // That tail is a pure function of (`fromFile`, `targetRaw`,
+        // `allFilePaths`): it only reads the Set and indexes memoized on the Set,
+        // and the `submodule` probe in between is equally read-only, so nothing can
+        // have changed the answer. Reaching this line means the tail already
+        // returned null; running it again returns null again, after another
+        // proximity probe and another full ancestor walk to the workspace root.
+        //
+        // Measured before this change, `from x import y` at four directory
+        // components: 24 `allFilePaths.has` probes per import, of which probes
+        // 12-23 were byte-identical repeats of 0-11. `python-import-probe-count
+        // .test.ts` is the gate.
+        return packageTarget;
+    }
     // PEP-328 relative + single-segment proximity bare imports.
     const internal = resolvePythonImportInternal(ctx.fromFile, parsedImport.targetRaw, ctx.allFilePaths);
     if (internal !== null)
@@ -64,6 +115,69 @@ export function resolvePythonImportTarget(parsedImport, workspaceIndex) {
     // both files exist).
     return resolveAbsoluteFromFiles(pathLike, ctx.allFilePaths, ctx.fromFile);
 }
+/**
+ * Answers "does this package expose `importedName` as an attribute?" from
+ * `localDefs` alone — so it says no for a name the package only re-exports.
+ *
+ * KNOWN DIVERGENCE from `buildReexportClosures`, which since #2864 does carry
+ * re-exported names (`ParsedImport.reexportsName`). With
+ * `pkg/__init__.py: from .impl import log`, `pkg/impl.py: def log`, and a
+ * same-named `pkg/log.py`, this returns false, the caller falls through to the
+ * submodule probe, and `from pkg import log` targets `pkg/log.py` — where
+ * `log` is not a local def either, so the edge ends unresolved and the closure
+ * is never consulted, for exactly the case it was built for. CPython binds
+ * `pkg.log` to the function.
+ *
+ * NOT fixed by reusing the flag here, which is the obvious three-line change
+ * and is wrong: `reexportsName` is also set for `pkg/__init__.py: from .
+ * import log`, where CPython binds `pkg.log` to the **module** `pkg/log.py`
+ * (verified on 3.11) and returning true here would kill the correct namespace
+ * edge. Separating the two needs the re-export's own resolved target, i.e.
+ * re-entering `resolvePythonImportTarget` from a different `fromFile` — and
+ * that classification is what open issue #2882 is about, so it belongs with
+ * that fix rather than bolted on here. Not a regression: both halves behave
+ * exactly as they did before #2864.
+ *
+ * The `parsedFiles.find` this used to open with was the same O(imports x files)
+ * shape #2913 removes on the path Set, keyed on the other collection the
+ * orchestrator threads: every import whose package probe resolves scanned the
+ * whole parsed workspace, and on a repo where `from pkg import X` usually
+ * resolves that is most imports. `parsedFileByPath` replaces it with one pass
+ * per pass.
+ */
+function pythonFileExportsName(targetFile, importedName, parsedFiles) {
+    if (parsedFiles === undefined)
+        return false;
+    const parsed = parsedFileByPath(parsedFiles).get(targetFile);
+    if (parsed === undefined)
+        return false;
+    return parsed.localDefs.some((def) => {
+        const qualifiedName = def.qualifiedName;
+        if (qualifiedName === undefined || qualifiedName.length === 0)
+            return false;
+        const dot = qualifiedName.lastIndexOf('.');
+        return (dot === -1 ? qualifiedName : qualifiedName.slice(dot + 1)) === importedName;
+    });
+}
+/**
+ * `filePath -> ParsedFile`, memoized on the identity of the pass's
+ * `parsedFiles` array — the second stable object the orchestrator threads
+ * through `resolveImportTarget`, beside the path Set.
+ *
+ * FIRST WINS on a duplicated path, which is what `Array.prototype.find`
+ * returned, so the answer is unchanged for a workspace that somehow parsed one
+ * path twice. Values are references to the array's own elements: the Map costs
+ * one pointer per parsed file and, living in a `WeakMap` keyed on the array,
+ * is reclaimed with the pass rather than accumulating across runs (#2649).
+ */
+const parsedFileByPath = perFileSet((parsedFiles) => {
+    const byPath = new Map();
+    for (const file of parsedFiles) {
+        if (!byPath.has(file.filePath))
+            byPath.set(file.filePath, file);
+    }
+    return byPath;
+});
 /**
  * Resolve `package/sub/module` style paths (already dot-flattened) to a
  * concrete file in `allFilePaths`. Tries the exact path first, then walks
@@ -95,20 +209,45 @@ function resolveAbsoluteFromFiles(pathLike, allFilePaths, fromFile) {
         return directFile;
     if (allFilePaths.has(directPkg))
         return directPkg;
+    // Both remaining tiers — the ancestor walk and the suffix fallback — can only
+    // ever land on a file whose basename is `<lastSeg>.py`, or on an `__init__.py`
+    // whose parent directory is named `<lastSeg>`. The two buckets the suffix
+    // fallback already needs therefore also decide, in O(1) and before the walk,
+    // whether the walk can hit at all: neither bucket present means no tier below
+    // can match, and one bucket absent removes that tier's probe from EVERY step
+    // of the walk. On the deep corpus that is half the walk's probes (#2913).
+    //
+    // `pythonSegmentAbsent` states this same rule for the single-segment bare
+    // tier. It is deliberately not called here: that tier needs only the answer,
+    // this one needs the candidate ARRAYS for the suffix fallback below, so
+    // sharing would mean two extra `has` lookups per import to save four lines.
+    const index = getPythonFileIndex(allFilePaths);
+    const lastSeg = pathLike.slice(pathLike.lastIndexOf('/') + 1);
+    const moduleCandidates = index.byBasename.get(`${lastSeg}.py`);
+    const packageCandidates = index.byInitParent.get(`${lastSeg}/__init__.py`);
+    const mayBeModule = moduleCandidates !== undefined;
+    // `byInitParent` skips `__init__.py` files whose parent directory name is
+    // empty (a doubled separator), so an empty `<lastSeg>` — a target spelled
+    // with a trailing dot — cannot use the bucket as proof of absence and keeps
+    // probing exactly as before.
+    const mayBePackage = packageCandidates !== undefined || lastSeg === '';
+    if (!mayBeModule && !mayBePackage)
+        return null;
     // Ancestor walk — match the single-segment resolver's behavior at
-    // multi-segment granularity. Closest match wins. Stop at `i > 0` because
-    // `i === 0` would re-check the workspace-root candidates already covered
-    // by the direct check above.
-    const importerDir = fromFile.replace(/\\/g, '/').split('/').slice(0, -1).join('/');
-    if (importerDir) {
-        const dirParts = importerDir.split('/').filter(Boolean);
-        for (let i = dirParts.length; i > 0; i--) {
-            const ancestor = dirParts.slice(0, i).join('/');
-            const prefix = `${ancestor}/`;
-            const candidateFile = `${prefix}${directFile}`;
-            const candidatePkg = `${prefix}${directPkg}`;
+    // multi-segment granularity. Closest match wins. The chain stops short of the
+    // workspace root because the root candidates are the direct check above.
+    //
+    // The chain comes from `importerAncestors`, which builds it ONCE per importer
+    // directory per pass. Rebuilding it here — one `slice(0, i).join('/')` per
+    // path component, on every import — was half of the depth quadratic in #2913.
+    for (const ancestor of importerAncestors(index, importerDirOf(fromFile))) {
+        if (mayBeModule) {
+            const candidateFile = `${ancestor}/${directFile}`;
             if (allFilePaths.has(candidateFile))
                 return candidateFile;
+        }
+        if (mayBePackage) {
+            const candidatePkg = `${ancestor}/${directPkg}`;
             if (allFilePaths.has(candidatePkg))
                 return candidatePkg;
         }
@@ -137,10 +276,8 @@ function resolveAbsoluteFromFiles(pathLike, allFilePaths, fromFile) {
     // shared buildSuffixIndex is deliberately NOT used: it keeps only one
     // path per suffix (longest wins) and so cannot reproduce this exact
     // fewest-segments-then-lexicographic tie-break across all candidates.
-    const index = getPythonFileIndex(allFilePaths);
-    const lastSeg = pathLike.slice(pathLike.lastIndexOf('/') + 1);
     const matches = [];
-    for (const cand of index.byBasename.get(`${lastSeg}.py`) ?? []) {
+    for (const cand of moduleCandidates ?? []) {
         if (cand.norm.endsWith(suffixFile))
             matches.push(cand);
     }
@@ -148,7 +285,7 @@ function resolveAbsoluteFromFiles(pathLike, allFilePaths, fromFile) {
     // can match `…/<lastSeg>/__init__.py` — look them up by parent key (P2b) and
     // confirm the full suffix. Same final candidate set as the old `__init__.py`
     // scan, just without iterating unrelated packages.
-    for (const cand of index.byInitParent.get(`${lastSeg}/__init__.py`) ?? []) {
+    for (const cand of packageCandidates ?? []) {
         if (cand.norm.endsWith(suffixPkg))
             matches.push(cand);
     }
@@ -194,94 +331,143 @@ function hasRepoCandidate(leadingSegment, allFilePaths, fromFile) {
     const prefix = `${leadingSegment}/`;
     const rootFile = `${leadingSegment}.py`;
     const initFile = `${leadingSegment}/__init__.py`;
-    // Build importer-ancestor prefixes: for `backend/routers/cron.py`,
-    // produces `["backend/routers/services/", "backend/services/"]` for
-    // segment `services` (closest first, root excluded — covered above).
-    const importerDir = fromFile.replace(/\\/g, '/').split('/').slice(0, -1).join('/');
-    const dirParts = importerDir ? importerDir.split('/').filter(Boolean) : [];
-    const ancestorPrefixes = [];
-    for (let i = dirParts.length; i > 0; i--) {
-        ancestorPrefixes.push(`${dirParts.slice(0, i).join('/')}/${leadingSegment}/`);
-    }
     // Indexed equivalents of the old O(files) scan:
     //  (1) `f === rootFile || f === initFile`  -> normalized-path membership.
     //  (2) `f.startsWith(`${seg}/`) && f.endsWith('.py')` -> some .py file lives
     //      under directory `${seg}/`, i.e. `${seg}/` is a known .py dir prefix.
     //  (3) ancestor namespace case -> `${ancestor}/${seg}/` is a known .py dir
-    //      prefix.
+    //      prefix, for some ancestor of the importer's directory.
     const index = getPythonFileIndex(allFilePaths);
     if (index.normSet.has(rootFile) || index.normSet.has(initFile))
         return true;
     if (index.dirPrefixes.has(prefix))
         return true;
-    for (const ap of ancestorPrefixes) {
-        if (index.dirPrefixes.has(ap))
+    // (3) used to MATERIALIZE one `${ancestor}/${seg}/` string per component of
+    // the importer's directory, eagerly, before checks (1) and (2) had even run —
+    // O(depth^2) characters on every import, and the other half of #2913. Two
+    // things replace that: `nestedDirNames` answers "is `seg` the name of any
+    // directory sitting under a non-empty parent?" in O(1), which is `false` for
+    // every external import (`os`, `django`, an unknown distribution) and skips
+    // the walk outright; and what remains walks the per-directory ancestor chain,
+    // built once per pass, closest first, so the common in-repo hit exits after a
+    // step or two. `nestedDirNames` is exact, not a filter: `${A}/${seg}/` can
+    // only be a directory prefix if `seg` names a directory under the non-empty
+    // parent `A`, so a miss here means the old loop would have missed too.
+    if (!index.nestedDirNames.has(leadingSegment))
+        return false;
+    for (const ancestor of importerAncestors(index, importerDirOf(fromFile))) {
+        if (index.dirPrefixes.has(`${ancestor}/${prefix}`))
             return true;
     }
     return false;
 }
-const PYTHON_FILE_INDEX_CACHE = new WeakMap();
-function getPythonFileIndex(allFilePaths) {
-    const cached = PYTHON_FILE_INDEX_CACHE.get(allFilePaths);
-    if (cached !== undefined)
-        return cached;
-    // Cache miss: materialize a fresh index. Counted so a test can assert this
-    // happens once per run, not once per import (PR #1918 review P1 guard).
-    recordPythonFileIndexBuild();
-    const normSet = new Set();
-    const byBasename = new Map();
-    const byInitParent = new Map();
-    const dirPrefixes = new Set();
-    for (const raw of allFilePaths) {
-        const norm = raw.replace(/\\/g, '/');
-        // Python import resolution only ever queries `.py` paths: module `<seg>.py`
-        // and package `<seg>/__init__.py` membership (normSet), `<lastSeg>.py` /
-        // `__init__.py` basename buckets (byBasename), and `.py` directory prefixes
-        // (dirPrefixes). Non-`.py` files can never match any of those, so skip them
-        // — they were dead weight in every structure on polyglot monorepos
-        // (PR #1918 review P3b; dirPrefixes was already `.py`-gated).
-        if (!norm.endsWith('.py'))
-            continue;
-        normSet.add(norm);
-        const lastSlash = norm.lastIndexOf('/');
-        const base = lastSlash >= 0 ? norm.slice(lastSlash + 1) : norm;
-        let bucket = byBasename.get(base);
-        if (bucket === undefined) {
-            bucket = [];
-            byBasename.set(base, bucket);
-        }
-        bucket.push({ raw, norm });
-        // Package files also get a parent-keyed bucket so a `pkg.sub` lookup hits
-        // only `…/sub/__init__.py` candidates, not every `__init__.py` (P2b).
-        if (base === '__init__.py' && lastSlash >= 0) {
-            const dir = norm.slice(0, lastSlash);
-            const parentSlash = dir.lastIndexOf('/');
-            const parentName = parentSlash >= 0 ? dir.slice(parentSlash + 1) : dir;
-            if (parentName) {
-                const initKey = `${parentName}/__init__.py`;
-                let ib = byInitParent.get(initKey);
-                if (ib === undefined) {
-                    ib = [];
-                    byInitParent.set(initKey, ib);
-                }
-                ib.push({ raw, norm });
-            }
-        }
-        // Directory prefixes: every slash-terminated prefix of the path (every
-        // index just past a '/', up to and including the file's own directory).
-        // Scanning the FULL normalized path — including any leading '/' for
-        // absolute paths — makes `dirPrefixes.has(X)` match exactly when the old
-        // gate's `f.startsWith(X)` (X always ends in '/') matched. The previous
-        // split+`filter(Boolean)` dropped the leading empty component, so an
-        // absolute file `/repo/svc/x.py` yielded `repo/svc/` (no leading slash) and
-        // gate-passed where `"/repo/svc/x.py".startsWith("repo/svc/")` is false
-        // (PR #1918 review P3a). For relative paths the set is identical.
-        for (let i = 0; i <= lastSlash; i++) {
-            if (norm[i] === '/')
-                dirPrefixes.add(norm.slice(0, i + 1));
-        }
+function pythonImportedSubmoduleTarget(parsedImport) {
+    if (parsedImport.kind !== 'named' && parsedImport.kind !== 'alias')
+        return null;
+    if (parsedImport.targetIncludesImportedName === true)
+        return null;
+    const separator = parsedImport.targetRaw.endsWith('.') ? '' : '.';
+    return parsedImport.targetRaw + separator + parsedImport.importedName;
+}
+/**
+ * A named Python import is a namespace handle only when its resolved file is
+ * the concrete submodule formed by appending the imported name. This keeps
+ * ordinary symbol imports on the named-binding path.
+ */
+export function isPythonImportedModule(parsedImport, targetFile, fromFile) {
+    const submoduleTarget = pythonImportedSubmoduleTarget(parsedImport);
+    if (submoduleTarget === null)
+        return false;
+    const normalizedTarget = targetFile.replace(/\\/g, '/');
+    let pathLike;
+    if (submoduleTarget.startsWith('.')) {
+        const match = submoduleTarget.match(/^(\.+)(.*)$/);
+        if (match === null)
+            return false;
+        const ascend = match[1].length - 1;
+        const base = fromFile.replace(/\\/g, '/').split('/').slice(0, -1);
+        if (ascend > base.length)
+            return false;
+        const relativeParts = match[2].split('.').filter(Boolean);
+        pathLike = [...base.slice(0, base.length - ascend), ...relativeParts].join('/');
+    }
+    else {
+        pathLike = submoduleTarget.replace(/\./g, '/');
+    }
+    const moduleFile = pathLike + '.py';
+    const packageFile = pathLike + '/__init__.py';
+    return (normalizedTarget === moduleFile ||
+        normalizedTarget === packageFile ||
+        normalizedTarget.endsWith('/' + moduleFile) ||
+        normalizedTarget.endsWith('/' + packageFile));
+}
+/**
+ * The receiver spellings `import a.b.c` makes callable, and the file each one
+ * names (#2826).
+ *
+ * `import a.b.c` binds ONE name — `a` — but makes three attribute paths
+ * reachable, and they name three different files:
+ *
+ *   a        → a/__init__.py
+ *   a.b      → a/b/__init__.py
+ *   a.b.c    → a/b/c.py        (the edge's own target)
+ *
+ * The shared default keyed `a` to the LEAF, which is wrong in both directions:
+ * `a.helper()` resolved into `a/b/c.py` whenever that module happened to export
+ * `helper`, and `a.b.mid()` resolved to nothing.
+ *
+ * Returns `undefined` — meaning "use the shared default" — for every spelling
+ * where the bound name is not the path's root:
+ *   - `import single`            — no dotted path to expand;
+ *   - `import a.b as x`          — binds only `x`; writing `a.b.f()` there is a
+ *                                  NameError, so `a.b` must NOT become a key;
+ *   - `from pkg import db`       — reclassified to a namespace edge whose
+ *                                  importPath is the bare name `db`.
+ *
+ * Prefix files are proposed, not asserted: `moduleFileExists` drops any that
+ * the workspace did not parse, so a PEP-420 namespace package (no
+ * `__init__.py`) contributes no key rather than one pointing at a missing file.
+ */
+export function pythonNamespaceReceiverPaths(edge, moduleFileExists) {
+    const segments = edge.importPath.split('.');
+    if (segments.length < 2)
+        return undefined;
+    if (segments[0] !== edge.localName)
+        return undefined;
+    const out = [[edge.importPath, edge.targetFile]];
+    // Anchor the prefix packages on the RESOLVED leaf, never on the import
+    // spelling. `resolvePythonImportTarget` resolves off-root in two of its three
+    // tiers (suffix match and ancestor-relative), so `import utils.db` can land on
+    // `libs/common/utils/db.py`. Building `utils/__init__.py` from the spelling
+    // would then name a DIFFERENT package that merely shares the root segment —
+    // a wrong edge — and in a `src/` layout it would match nothing at all,
+    // silently making prefix keying inert for the most common Python layout.
+    //
+    // Walking back from the leaf also inherits that path's own separator, so no
+    // POSIX-vs-Windows probing is needed: workspace paths are not normalized at
+    // ingestion, and `moduleScopeByFile` is keyed by the raw `ParsedFile.filePath`.
+    const dirs = edge.targetFile.split('/').slice(0, -1);
+    // The import's leading segments name the leaf's innermost directories.
+    const offset = dirs.length - (segments.length - 1);
+    if (offset < 0)
+        return out;
+    for (let i = 1; i < segments.length; i++) {
+        const spelling = segments.slice(0, i).join('.');
+        const packageFile = dirs.slice(0, offset + i).join('/') + '/__init__.py';
+        // Package FIRST, then the leaf as a fallback — order is the whole point.
+        //
+        // `findExportedDef` only accepts a binding whose `origin === 'local'`, and
+        // the canonical package re-exports (`from .b.c import helper` in
+        // `__init__.py`) produce an IMPORT binding. Keying the prefix at the
+        // package alone therefore loses `a.helper()` entirely for the most common
+        // package shape — the fixtures here all define members locally in
+        // `__init__.py`, which is precisely the one layout where that mistake is
+        // invisible. Keeping the leaf behind the package restores that resolution
+        // while still letting a real definition in `__init__.py` win over a
+        // same-named decoy deeper in the package.
+        if (moduleFileExists(packageFile))
+            out.push([spelling, packageFile]);
+        out.push([spelling, edge.targetFile]);
     }
-    const index = { normSet, byBasename, byInitParent, dirPrefixes };
-    PYTHON_FILE_INDEX_CACHE.set(allFilePaths, index);
-    return index;
+    return out;
 }

package/dist/core/ingestion/languages/python/index.d.ts

@@ -75,5 +75,5 @@ export { getPythonCaptureCacheStats, resetPythonCaptureCacheStats } from './cach
 export { interpretPythonImport, interpretPythonTypeBinding } from './interpret.js';
 export { pythonMergeBindings } from './merge-bindings.js';
 export { pythonArityCompatibility } from './arity.js';
-export { resolvePythonImportTarget, type PythonResolveContext } from './import-target.js';
+export { isPythonImportedModule, pythonNamespaceReceiverPaths, resolvePythonImportTarget, type PythonResolveContext, } from './import-target.js';
 export { pythonBindingScopeFor, pythonFunctionDefinitionLabel, pythonImportOwningScope, pythonReceiverBinding, } from './simple-hooks.js';

package/dist/core/ingestion/languages/python/index.js

@@ -75,5 +75,5 @@ export { getPythonCaptureCacheStats, resetPythonCaptureCacheStats } from './cach
 export { interpretPythonImport, interpretPythonTypeBinding } from './interpret.js';
 export { pythonMergeBindings } from './merge-bindings.js';
 export { pythonArityCompatibility } from './arity.js';
-export { resolvePythonImportTarget } from './import-target.js';
+export { isPythonImportedModule, pythonNamespaceReceiverPaths, resolvePythonImportTarget, } from './import-target.js';
 export { pythonBindingScopeFor, pythonFunctionDefinitionLabel, pythonImportOwningScope, pythonReceiverBinding, } from './simple-hooks.js';

package/dist/core/ingestion/languages/python/interpret.d.ts

@@ -13,3 +13,55 @@
 import type { CaptureMatch, ParsedImport, ParsedTypeBinding } from '../../../../_shared/index.js';
 export declare function interpretPythonImport(captures: CaptureMatch): ParsedImport | null;
 export declare function interpretPythonTypeBinding(captures: CaptureMatch): ParsedTypeBinding | null;
+/**
+ * Container bases whose SINGLE type argument is the element type.
+ *
+ * The single source of truth for both the matcher below and the property test
+ * that asserts every one of them is also declined as a user generic — the two
+ * lists drifting apart is the defect this arrangement exists to make
+ * impossible. Order is significant only in that it is the regex alternation
+ * order; keep additions grouped with their family.
+ */
+export declare const SINGLE_ARG_CONTAINERS: readonly string[];
+/** Container bases whose SECOND type argument is the value type. See {@link SINGLE_ARG_CONTAINERS}. */
+export declare const MAPPING_CONTAINERS: readonly string[];
+/**
+ * Bases a subscripted annotation may carry that are NOT user-defined generics.
+ *
+ * SCOPE — the standard library, and deliberately nothing else. The names below
+ * are the documented Python type-system surface (`typing`'s deprecated PEP 585
+ * aliases and its special forms, plus the stdlib classes those aliases point
+ * at); that universe is CLOSED and versioned by CPython, so the list is
+ * auditable against
+ * <https://docs.python.org/3/library/typing.html#deprecated-aliases>.
+ *
+ * Third-party generics (`Mapped[int]`, `QuerySet[User]`) are NOT listed. That
+ * universe is open, so enumerating it only ever chases the last escape, and
+ * denying an ordinary name like `Model` would cost real edges in the many
+ * projects that legitimately declare one. Those spellings still reduce to their
+ * base, and the base is now admitted only on the grounds `resolveErasedBaseName`
+ * applies at resolution time — the file's scope chain binds it, the declaration
+ * is in this very file, the index proves the name is a template family, or the
+ * file has no cross-file class channel to be absent from. A `Mapped[User]` whose
+ * base the file cannot see therefore binds nothing, which is the structural
+ * answer this parse-time pass cannot give and no longer has to.
+ *
+ * Two distinct reasons to decline, both always-correct at this layer:
+ *   - CONTAINERS, including ones the two rules above do not own. Reducing
+ *     `deque[User]` to `deque` types a receiver as the container and retargets
+ *     every call in a for-loop chain, and reducing `dict[str, list[User]]` to
+ *     `dict` destroys the value type the dict rule leaves for a downstream pass.
+ *   - `typing` SPECIAL FORMS, which are not classes at all. `Callable`,
+ *     `Literal`, `Union` reduce to a bare name that binds to a workspace class
+ *     of that name if one exists — a fabricated edge.
+ *
+ * Members are listed ONCE per case-insensitive concept: {@link
+ * isNotAUserGenericBase} folds case, so the builtin spelling covers its PEP 585
+ * `typing` twin (`deque` covers `Deque`, `frozenset` covers `FrozenSet`).
+ * Non-generic ABCs (`Hashable`, `Sized`) are omitted — they cannot be written
+ * subscripted, so they never reach this branch.
+ *
+ * Exported for the property test that asserts the case-fold closure holds
+ * behaviourally; nothing else should read it.
+ */
+export declare const NOT_A_USER_GENERIC_SPELLINGS: readonly string[];