fix(ts): a declaration in a declare module block is reached through its module (#2728)

A declaration file's declare module 'x' { ... } declares the members of
x, which no other file names by a bare name: an import of x reaches them.
The functions of such a block have been held to that since #2718, but its
other declarations, the types, classes, constants and enums, still took
bare-name matches from any file. On vscode, Node's
import { readFileSync } from 'fs' linked to the fs that vscode.d.ts's
workspace namespace declares, electron's clipboard and shell to env's, a
ProcessEnv to the proposed API's, and an LSP TextDocument re-exported
through a project barrel to the API's own.

Every block-level declaration now takes a match from another file only
when the reference is written in a block declaring the same module (the
proposed API files merge into vscode.d.ts), is a type position in a file
that imports the module (vscode.TextDocument under a namespace import,
which the extractor records by its last name), or names what the file
imports from a project file that imports the module and re-exports it
(copilot's vscodeTypes.ts).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/resolution/ambient-modules.ts

@@ -460,8 +460,10 @@ interface Memo {
   scanned: { byFile: Map<string, AmbientModule[]>; bySpecifier: Map<string, AmbientModule[]> } | null;
   /** Per block (`file`, line, column): its declarations, by name. */
   members: Map<string, Map<string, Node[]>>;
-  /** See ambientModuleFunctionIds. */
-  functionIds: ReadonlySet<string> | null;
+  /** See ambientModuleDeclarations. */
+  declarationIds: ReadonlyMap<string, string> | null;
+  /** The blocks of TypeScript files other than declaration files, by file (see isInModuleBlock). */
+  otherBlocks: Map<string, readonly AmbientModuleBlock[]>;
   /** declarationsFor's answers, by specifier and importing file. */
   declarations: Map<string, AmbientModule[]>;
   /** isMergedAmbientDeclaration's answers, by node id. */
@@ -477,7 +479,7 @@ export function clearAmbientModuleMemos(context: ResolutionContext): void {
 
 function memoFor(context: ResolutionContext): Memo {
   let memo = MEMO.get(context);
-  if (!memo) MEMO.set(context, (memo = { scanned: null, members: new Map(), functionIds: null, declarations: new Map(), merged: new Map() }));
+  if (!memo) MEMO.set(context, (memo = { scanned: null, members: new Map(), declarationIds: null, otherBlocks: new Map(), declarations: new Map(), merged: new Map() }));
   return memo;
 }
 
@@ -517,7 +519,7 @@ function scanned(context: ResolutionContext): NonNullable<Memo['scanned']> {
 const DECLARATION_KINDS = new Set<Node['kind']>(['function', 'class', 'interface', 'type_alias', 'enum', 'constant', 'variable', 'component']);
 
 /** Whether `node` starts inside the block, by position. */
-function inBlock(node: Node, block: AmbientModuleBlock): boolean {
+function inBlock(node: Pick<Node, 'startLine' | 'startColumn'>, block: AmbientModuleBlock): boolean {
   const afterStart = node.startLine > block.startLine || (node.startLine === block.startLine && node.startColumn >= block.startColumn);
   const beforeEnd = node.startLine < block.endLine || (node.startLine === block.endLine && node.startColumn <= block.endColumn);
   return afterStart && beforeEnd;
@@ -661,25 +663,51 @@ function blockDeclaring(node: Node, context: ResolutionContext): AmbientModule |
 }
 
 /**
- * The ids of the functions declaration files' `declare module 'x'` bodies
- * declare. Only an import of `x` reaches one: a module's functions are never
- * global, so a bare `encode()` elsewhere is no call of the `encode` excalidraw
- * declares for `png-chunks-encode`. A set, so asking about every reference a
- * strategy other than the import resolver settles costs a lookup.
+ * The declarations at the own level of declaration files' `declare module 'x'`
+ * bodies, by id, each with the `x` its block declares. A module's members are
+ * never global: a bare `encode()` elsewhere is no call of the `encode`
+ * excalidraw declares for `png-chunks-encode`, Node's `import * as fs from
+ * 'fs'` no import of the `fs` vscode's `workspace` namespace declares, and an
+ * ESLint `Property` no use of emmet's `declare module 'EmmetFlatNode'`. A
+ * map, so asking about every reference a strategy other than the import
+ * resolver settles costs a lookup (see reachesAmbientModule).
  */
-export function ambientModuleFunctionIds(context: ResolutionContext): ReadonlySet<string> {
+export function ambientModuleDeclarations(context: ResolutionContext): ReadonlyMap<string, string> {
   const memo = memoFor(context);
-  if (memo.functionIds) return memo.functionIds;
-  const ids = new Set<string>();
+  if (memo.declarationIds) return memo.declarationIds;
+  const ids = new Map<string, string>();
   for (const [file, modules] of scanned(context).byFile) {
     for (const node of context.getNodesInFile(file)) {
-      if (node.kind === 'function' && isBlockLevel(node) && modules.some((mod) => inBlock(node, mod))) ids.add(node.id);
+      if (!isBlockLevel(node)) continue;
+      const mod = modules.find((m) => inBlock(node, m));
+      if (mod) ids.set(node.id, mod.specifier);
     }
   }
-  memo.functionIds = ids;
+  memo.declarationIds = ids;
   return ids;
 }
 
+/**
+ * Whether line:column of `file` lies inside a block declaring `specifier`:
+ * one of the module's own declarations, which merge, as vscode's proposed API
+ * files add to `vscode.d.ts`'s `declare module 'vscode'`. A declaration
+ * file's blocks are the scanned ones; another TypeScript file's are read the
+ * first time one is asked about.
+ */
+export function isInModuleBlock(file: string, line: number, column: number, specifier: string, context: ResolutionContext): boolean {
+  let blocks: readonly AmbientModuleBlock[] | undefined = scanned(context).byFile.get(file);
+  if (!blocks && !DECLARATION_FILE.test(file)) {
+    const memo = memoFor(context);
+    blocks = memo.otherBlocks.get(file);
+    if (!blocks) {
+      const source = context.readFile(file);
+      blocks = source && /\bdeclare\s+module\s*['"]/.test(source) ? scanAmbientModules(source).blocks : [];
+      memo.otherBlocks.set(file, blocks);
+    }
+  }
+  return (blocks ?? []).some((block) => block.specifier === specifier && inBlock({ startLine: line, startColumn: column }, block));
+}
+
 /**
  * Whether `node` is one of several declarations of the same name that the
  * blocks declaring one module merge: vscode declares `InlineCompletionItemProvider`

src/resolution/import-resolver.ts

@@ -15,7 +15,7 @@ import { resolveWorkspaceImport } from './workspace-packages';
 import { stripCommentsForRegex } from './strip-comments';
 import { makeLineAt } from './synth-utils';
 import { dartDirectiveFile } from './dart-libraries';
-import { ambientModuleDeclares, findAmbientModuleExport, findAmbientModuleFile } from './ambient-modules';
+import { ambientModuleDeclares, findAmbientModuleExport, findAmbientModuleFile, isInModuleBlock } from './ambient-modules';
 import { moduleTail } from '../db/reference-tail';
 import {
   resolveMethodOnType,
@@ -2973,6 +2973,50 @@ function isBareModuleSpecifier(source: string, language: Language): boolean {
   return ESM_IMPORT_LANGUAGES.has(language) && !source.startsWith('.') && !source.startsWith('/');
 }
 
+/**
+ * Reference kinds the extractor records by a qualified name's last part: a
+ * type position (`doc: vscode.TextDocument`) and a construction (`new
+ * vscode.EventEmitter<T>()`). A call keeps what it is called through.
+ */
+const LAST_NAME_KINDS: ReadonlySet<string> = new Set(['references', 'extends', 'implements', 'type_of', 'returns', 'instantiates']);
+
+/**
+ * Whether `ref`, in another file than the declaration, may name by its bare
+ * name a declaration of the repository's own `declare module '<specifier>'`
+ * in `declaringFile` (see ambientModuleDeclarations), the import resolver
+ * having bound nothing:
+ * - written inside a block declaring the same module, whose declarations
+ *   merge (vscode's proposed API files add to `vscode.d.ts`);
+ * - the last name of a qualified one, the file importing the module or the
+ *   declaring file: `vscode.TextDocument` under `import * as vscode from
+ *   'vscode'`, typescript-language-features' `Proto.Response` under `import
+ *   type * as Proto from './protocol/protocol'`, whose `export =` hands out the
+ *   namespace the file's block augments;
+ * - a name the file imports from the module, from the declaring file, or from
+ *   a project file that imports the module and re-exports it (copilot's
+ *   `vscodeTypes.ts`: `export import X = vscode.X`).
+ * A name bound to another package (an LSP `TextDocument`), to Node's own
+ * modules (`fs`), or to a project file that doesn't import the module, or a
+ * bare name a file reaching no such module writes, is not one of the module's.
+ */
+export function reachesAmbientModule(ref: UnresolvedRef, specifier: string, declaringFile: string, context: ResolutionContext): boolean {
+  if (isInModuleBlock(ref.filePath, ref.line, ref.column ?? 0, specifier, context)) return true;
+  const mappings = context.getImportMappings(ref.filePath, ref.language);
+  const relative = (source: string): boolean => source.startsWith('.') || source.startsWith('/');
+  const leadsTo = (source: string, through: (file: string) => boolean): boolean => {
+    if (source === specifier) return true;
+    if (!relative(source)) return false;
+    const file = resolveImportPath(source, ref.filePath, ref.language, context);
+    return file !== null && (file === declaringFile || through(file));
+  };
+  const head = ref.referenceName.split('.')[0]!;
+  const binding = mappings.find((m) => m.localName === head);
+  if (binding) {
+    return leadsTo(binding.source, (file) => context.getImportMappings(file, ref.language).some((m) => m.source === specifier));
+  }
+  return LAST_NAME_KINDS.has(ref.referenceKind) && mappings.some((m) => leadsTo(m.source, () => false));
+}
+
 /**
  * Resolve a Python qualified reference whose receiver is an imported MODULE:
  * `certs.where()` after `from . import certs`, `mod.func()` after `import mod`

src/resolution/index.ts

@@ -33,9 +33,9 @@ import { gateDartLocal, clearDartLocalScopeMemos } from './dart-local-scope';
 import { clearCppTypeAliasMemos } from './cpp-type-aliases';
 import { clearCppIncluderMemos } from './cpp-includers';
 import { clearCFeatureVariantMemos } from './c-feature-variants';
-import { clearAmbientModuleMemos, ambientModuleFunctionIds } from './ambient-modules';
+import { clearAmbientModuleMemos, ambientModuleDeclarations } from './ambient-modules';
 import { matchShopifyThemeFile } from './shopify-themes';
-import { resolveViaImport, resolvePhpImportedStaticCall, resolvePhpQualifiedClassRef, resolveJvmImport, extractImportMappings, extractReExports, loadCppIncludeDirs, isPhpIncludePathRef, isCobolCopybookRef, isNixPathImportRef, isDartImportRef, isLuaRequireRef, isJsPathImportRef, isBoundToOutOfRepoImport, importBindingTail, clearImportResolverMemos, resolveImportPath, isExternalImport, ESM_IMPORT_LANGUAGES, jsModuleFile, pythonRootFingerprint, pythonReopenScope, pythonPackageImporters } from './import-resolver';
+import { resolveViaImport, resolvePhpImportedStaticCall, resolvePhpQualifiedClassRef, resolveJvmImport, extractImportMappings, extractReExports, loadCppIncludeDirs, isPhpIncludePathRef, isCobolCopybookRef, isNixPathImportRef, isDartImportRef, isLuaRequireRef, isJsPathImportRef, isBoundToOutOfRepoImport, reachesAmbientModule, importBindingTail, clearImportResolverMemos, resolveImportPath, isExternalImport, ESM_IMPORT_LANGUAGES, jsModuleFile, pythonRootFingerprint, pythonReopenScope, pythonPackageImporters } from './import-resolver';
 import { ResolverPool, minRefsForPool, shouldEngageAdaptively } from './resolver-pool';
 import { resolveAliasBinding } from './alias-binding';
 import { detectFrameworks, getResolvingFrameworks } from './frameworks';
@@ -1356,11 +1356,15 @@ export class ReferenceResolver {
       const module = this.nodeById(resolved.targetNodeId);
       if (module && module.kind !== 'file' && module.kind !== 'module') return null;
     }
-    // A function a declaration file's `declare module 'x'` declares is reached
-    // only through an import of `x`, never by its bare name from another file
-    // (see ./ambient-modules).
-    if (resolved && resolved.resolvedBy !== 'import' && ambientModuleFunctionIds(this.context).has(resolved.targetNodeId) &&
-        this.nodeById(resolved.targetNodeId)?.filePath !== ref.filePath) return null;
+    // A declaration of a declaration file's `declare module 'x'` is reached
+    // through an import of `x`, never by its bare name from a file that
+    // reaches no `x` (see reachesAmbientModule).
+    if (resolved && resolved.resolvedBy !== 'import') {
+      const specifier = ambientModuleDeclarations(this.context).get(resolved.targetNodeId);
+      const declaringFile = specifier === undefined ? undefined : this.nodeById(resolved.targetNodeId)?.filePath;
+      if (declaringFile !== undefined && declaringFile !== ref.filePath &&
+          !reachesAmbientModule(ref, specifier!, declaringFile, this.context)) return null;
+    }
     if (!resolved || ref.referenceKind !== 'calls') return resolved;
 
     const target = this.nodeById(resolved.targetNodeId);