@cplieger/deadset-ts 7.2.0-dev.4 → 8.0.0-dev.10

package/src/augmentations.ts

@@ -7,11 +7,21 @@
  * as `import.meta` or `process.env`, so a use of its member is a use of it.
  */
 
-import type { Inventory, InventorySymbol } from "./inventory.ts";
+import {
+  isInterfaceDeclaration,
+  isModuleBlock,
+  isModuleDeclaration,
+  type Node,
+} from "@typescript/native/ast";
+import { nodeKey, type Inventory, type InventorySymbol } from "./inventory.ts";
+import { referenceKey } from "./matrix.ts";
 import type { Reference } from "./references.ts";
+import type { ProjectView } from "./session.ts";
+import type { SourceFiles } from "./source-files.ts";
+import type { NodeHandle } from "@typescript/native/sync";
 
 /** Whether one declaration is a `declare global` block: a module-level namespace named `global`. */
-function isGlobalBlock(
+export function isGlobalBlock(
   symbol: InventorySymbol,
   held: Inventory,
   files: ReadonlySet<string>,
@@ -25,25 +35,24 @@ function isGlobalBlock(
 }
 
 /**
- * For each reference to a declaration an augmentation block, or the global scope of a
- * file in `scripts`, holds, a read at the same place of every interface and namespace
- * between it and the block or the file, and of the block itself. `scripts` holds the
- * files that are no module, by identifier.
+ * Per declaration, the interfaces and namespaces between it and the augmentation block or
+ * the file in `scripts` that holds it, with the block itself, or none where no such block
+ * or file holds it; and whether that holder is the global scope rather than a module
+ * declaration. `scripts` holds the files that are no module, by identifier.
  */
-export function augmentationReferences(
+function holdersOf(
   held: Inventory,
-  found: readonly Reference[],
-  scripts: ReadonlySet<string> = new Set(),
-): readonly Reference[] {
+  scripts: ReadonlySet<string>,
+): ((id: string) => { readonly ids: readonly string[]; readonly global: boolean }) | undefined {
   const files = new Set(held.symbols.filter((one) => one.kind === "file").map((one) => one.id));
   const globals = new Set(
     held.symbols.filter((one) => isGlobalBlock(one, held, files)).map((one) => one.id),
   );
   if (globals.size === 0 && held.modules.size === 0 && scripts.size === 0) {
-    return [];
+    return undefined;
   }
   const byId = new Map(held.symbols.map((one) => [one.id, one]));
-  const holders = (id: string): string[] => {
+  return (id) => {
     const ids: string[] = [];
     for (
       let at = byId.get(byId.get(id)?.parent ?? "");
@@ -51,25 +60,145 @@ export function augmentationReferences(
       at = byId.get(at.parent)
     ) {
       if (globals.has(at.id) || held.modules.has(at.id)) {
-        return [...ids, at.id];
+        return { ids: [...ids, at.id], global: globals.has(at.id) };
       }
       if (scripts.has(at.id)) {
-        return ids;
+        return { ids, global: true };
       }
       if (at.kind === "interface" || at.kind === "namespace") {
         ids.push(at.id);
       }
     }
+    return { ids: [], global: false };
+  };
+}
+
+/**
+ * The ambient interfaces of the global scope among `interfaces`: each one a declaration
+ * file or a `declare` holds that a `declare global` block, or the top level of a file in
+ * `scripts`, declares, directly or inside a namespace there.
+ */
+export function ambientGlobalInterfaces(
+  held: Inventory,
+  interfaces: readonly string[],
+  scripts: ReadonlySet<string>,
+): readonly string[] {
+  const holders = holdersOf(held, scripts);
+  return holders === undefined
+    ? []
+    : interfaces.filter((id) => held.ambient.has(id) && holders(id).global);
+}
+
+/**
+ * Each ambient global interface of the project's own files that merges into an interface
+ * declared outside them, with every interface, namespace and block between it and the
+ * global scope: the outside declaration names it wherever a value is typed by it. Where
+ * every outside declaration is a package's, not the compiler's library, and declares no
+ * member, each member it declares as well: such an interface is a slot the package reads
+ * by type, as `keyof` does, in declarations the analysis does not walk.
+ */
+export function mergedGlobalInterfaces<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+  files: SourceFiles,
+): readonly string[] {
+  const scripts = new Set<string>();
+  const names = new Map<string, Node>();
+  for (const file of files.byName.values()) {
+    const fileId = held.declarations.get(nodeKey(file, file));
+    if (fileId !== undefined && file.externalModuleIndicator === undefined) {
+      scripts.add(fileId);
+    }
+    const visit = (node: Node): void => {
+      if (isInterfaceDeclaration(node)) {
+        const id = held.declarations.get(nodeKey(file, node));
+        if (id !== undefined) {
+          names.set(id, node.name);
+        }
+      } else if (isModuleDeclaration(node) || isModuleBlock(node)) {
+        node.forEachChild(visit);
+      }
+    };
+    file.forEachChild(visit);
+  }
+  const global = new Set(ambientGlobalInterfaces(held, [...names.keys()], scripts));
+  const asked = [...names].filter(([id]) => global.has(id));
+  if (asked.length === 0) {
     return [];
+  }
+  const answers = project.symbolsAt(asked.map(([, name]) => project.handle(name)));
+  const holders = holdersOf(held, scripts);
+  const empty = (handle: NodeHandle): boolean => {
+    if (project.program.getSourceFileMetadata(handle.path)?.isDefaultLibrary === true) {
+      return false;
+    }
+    const node = project.declarationAt(handle)?.node;
+    return node !== undefined && isInterfaceDeclaration(node) && node.members.length === 0;
   };
-  return found.flatMap((reference) =>
-    holders(reference.to).map((to) => ({
-      from: reference.from,
-      to,
-      position: reference.position,
-      use: "read" as const,
-      resolution: reference.resolution,
-      test: reference.test,
-    })),
+  return [
+    ...new Set(
+      asked.flatMap(([id], at) => {
+        const symbol = answers[at];
+        if (typeof symbol !== "object") {
+          return [];
+        }
+        const outside = symbol.declarations.filter((handle) => !files.byName.has(handle.path));
+        if (outside.length === 0) {
+          return [];
+        }
+        const members = outside.every(empty)
+          ? held.symbols.filter((one) => one.parent === id).map((one) => one.id)
+          : [];
+        return [id, ...(holders?.(id).ids ?? []), ...members];
+      }),
+    ),
+  ];
+}
+
+/**
+ * For each reference to a declaration an augmentation block, or the global scope of a
+ * file in `scripts` (the files that are no module), holds, a read at the same place of
+ * every interface and namespace between it and the block or the file, and of the block
+ * itself. A read through an interface of `merged`, an ambient global interface merging
+ * into a language or library one, is a production read whoever writes it: it types a
+ * value the runtime provides, so a test reading a member needs it as code does.
+ */
+export function augmentationReferences(
+  held: Inventory,
+  found: readonly Reference[],
+  scripts: ReadonlySet<string> = new Set(),
+  merged: ReadonlySet<string> = new Set(),
+): readonly Reference[] {
+  const holders = holdersOf(held, scripts);
+  if (holders === undefined) {
+    return [];
+  }
+  const fileOf = new Map(
+    held.symbols.filter((one) => one.kind === "file").map((one) => [one.position.path, one.id]),
   );
+  // Two uses at one place of declarations one block holds read the block once there.
+  const made = new Set(found.map(referenceKey));
+  const reads = new Map<string, Reference>();
+  for (const reference of found) {
+    const { ids } = holders(reference.to);
+    // A test's read through such an interface is held by the test file, which the test
+    // runner loads whichever of its declarations runs.
+    const typed = reference.test && ids.some((id) => merged.has(id));
+    const from = typed ? (fileOf.get(reference.position.path) ?? reference.from) : reference.from;
+    for (const to of ids) {
+      const read: Reference = {
+        from,
+        to,
+        position: reference.position,
+        use: "read",
+        resolution: reference.resolution,
+        test: reference.test && !typed,
+      };
+      const key = referenceKey(read);
+      if (!made.has(key) && !reads.has(key)) {
+        reads.set(key, read);
+      }
+    }
+  }
+  return [...reads.values()];
 }

package/src/automatic-types.ts

@@ -0,0 +1,228 @@
+/**
+ * The global names and ambient modules of the `@types` packages a compiler before version 6
+ * includes automatically: every package of each type root when the configuration lists no
+ * `types`. Version 6 and later include none, so the analysis program holds none of their
+ * declarations, and a use of one resolves to nothing; each such use is a use of the package.
+ */
+
+import {
+  isClassDeclaration,
+  isEnumDeclaration,
+  isExportAssignment,
+  isExportDeclaration,
+  isFunctionDeclaration,
+  isIdentifier,
+  isImportDeclaration,
+  isImportEqualsDeclaration,
+  isInterfaceDeclaration,
+  isModuleBlock,
+  isModuleDeclaration,
+  isStringLiteral,
+  isTypeAliasDeclaration,
+  isVariableStatement,
+  SyntaxKind,
+  type Node,
+  type SourceFile,
+  type Statement,
+} from "@typescript/native/ast";
+import type { ParseFile } from "./configuration-files.ts";
+import type { Host } from "./host.ts";
+import { ancestors, dirnamePath, joinPath, resolvePath } from "./paths.ts";
+import { entriesOf } from "./fs/tree.ts";
+import { manifestAt } from "./fs/manifest.ts";
+
+const TYPE_ROOT = "node_modules/@types";
+
+/** What the automatically included `@types` packages of one configuration declare. */
+export interface AutomaticTypes {
+  /** Per global name, the packages that declare it. */
+  readonly globals: ReadonlyMap<string, readonly string[]>;
+  /** Per ambient module name, the packages that declare it. */
+  readonly modules: ReadonlyMap<string, readonly string[]>;
+}
+
+const NONE: AutomaticTypes = { globals: new Map(), modules: new Map() };
+
+/** What one installed type package declares, by its directory. */
+interface PackageDeclarations {
+  readonly globals: readonly string[];
+  readonly modules: readonly string[];
+}
+
+/**
+ * The packages each host has read, so a run's configurations share one reading of a type
+ * root; a host reads one unchanging tree for its whole life.
+ */
+const READ = new WeakMap<Host, Map<string, PackageDeclarations>>();
+
+/** Whether one file is a module: it imports, exports or assigns an export at its top level. */
+function isModuleFile(file: SourceFile): boolean {
+  return file.statements.some(
+    (statement) =>
+      isImportDeclaration(statement) ||
+      isImportEqualsDeclaration(statement) ||
+      isExportDeclaration(statement) ||
+      isExportAssignment(statement) ||
+      ((statement as { readonly modifiers?: readonly Node[] }).modifiers ?? []).some(
+        (modifier) => modifier.kind === SyntaxKind.ExportKeyword,
+      ),
+  );
+}
+
+/** The names one statement of a global scope declares, and the ambient modules it declares. */
+function declared(statement: Statement, globals: string[], modules: string[]): void {
+  if (isVariableStatement(statement)) {
+    for (const declaration of statement.declarationList.declarations) {
+      if (isIdentifier(declaration.name)) {
+        globals.push(declaration.name.text);
+      }
+    }
+  } else if (
+    isFunctionDeclaration(statement) ||
+    isClassDeclaration(statement) ||
+    isInterfaceDeclaration(statement) ||
+    isTypeAliasDeclaration(statement) ||
+    isEnumDeclaration(statement)
+  ) {
+    if (statement.name !== undefined) {
+      globals.push(statement.name.text);
+    }
+  } else if (isModuleDeclaration(statement)) {
+    if (isStringLiteral(statement.name)) {
+      modules.push(statement.name.text);
+    } else {
+      globals.push(statement.name.text);
+    }
+  }
+}
+
+/**
+ * What one declaration file declares in the global scope: its top level where it is no
+ * module, and the body of each `declare global` block where it is one.
+ */
+function fileDeclarations(file: SourceFile, globals: string[], modules: string[]): void {
+  if (!isModuleFile(file)) {
+    file.statements.forEach((statement) => {
+      declared(statement, globals, modules);
+    });
+    return;
+  }
+  for (const statement of file.statements) {
+    if (
+      isModuleDeclaration(statement) &&
+      isIdentifier(statement.name) &&
+      statement.name.text === "global" &&
+      statement.body !== undefined &&
+      isModuleBlock(statement.body)
+    ) {
+      statement.body.statements.forEach((inner) => {
+        declared(inner, globals, modules);
+      });
+    }
+  }
+}
+
+/** The entry declaration file of one installed type package's directory. */
+function entryOf(host: Host, dir: string): string {
+  const manifest = manifestAt(host, dir);
+  const named = manifest?.["types"] ?? manifest?.["typings"];
+  if (typeof named === "string" && named !== "") {
+    const path = resolvePath(dir, named);
+    return path.endsWith(".ts") ? path : `${path}.d.ts`;
+  }
+  return joinPath(dir, "index.d.ts");
+}
+
+/**
+ * Every global name and ambient module one installed type package declares: in its entry
+ * file and each file a `/// <reference path>` of a file read reaches, inside the package.
+ */
+function packageDeclarations(host: Host, dir: string, parse: ParseFile): PackageDeclarations {
+  const known = READ.get(host) ?? new Map<string, PackageDeclarations>();
+  READ.set(host, known);
+  const held = known.get(dir);
+  if (held !== undefined) {
+    return held;
+  }
+  const globals: string[] = [];
+  const modules: string[] = [];
+  const seen = new Set<string>();
+  const pending = [entryOf(host, dir)];
+  for (let path = pending.pop(); path !== undefined; path = pending.pop()) {
+    if (seen.has(path) || !path.startsWith(`${dir}/`)) {
+      continue;
+    }
+    seen.add(path);
+    let text: string;
+    try {
+      text = host.readFile(path);
+    } catch {
+      continue;
+    }
+    const file = parse(path, text);
+    fileDeclarations(file, globals, modules);
+    for (const reference of file.referencedFiles) {
+      pending.push(resolvePath(dirnamePath(path), reference.fileName));
+    }
+  }
+  const found = { globals, modules };
+  known.set(dir, found);
+  return found;
+}
+
+/**
+ * What the `@types` packages a compiler before version 6 would include for one
+ * configuration declare: none where its options list `types`, else every package of each
+ * `node_modules/@types` directory at or above the configuration's directory, the nearest
+ * holding a name winning.
+ */
+export function automaticTypes(
+  host: Host,
+  configFile: string,
+  options: Readonly<Record<string, unknown>>,
+  parse: ParseFile,
+): AutomaticTypes {
+  if (options["types"] !== undefined) {
+    return NONE;
+  }
+  const globals = new Map<string, string[]>();
+  const modules = new Map<string, string[]>();
+  const add = (into: Map<string, string[]>, name: string, named: string): void => {
+    const held = into.get(name) ?? [];
+    if (!held.includes(named)) {
+      into.set(name, [...held, named]);
+    }
+  };
+  const read = new Set<string>();
+  for (const root of typeRoots(configFile, options)) {
+    for (const entry of entriesOf(host, root)) {
+      if (read.has(entry.name) || host.kindOf(joinPath(root, entry.name)) !== "directory") {
+        continue;
+      }
+      read.add(entry.name);
+      const named = `@types/${entry.name}`;
+      const found = packageDeclarations(host, joinPath(root, entry.name), parse);
+      found.globals.forEach((name) => {
+        add(globals, name, named);
+      });
+      found.modules.forEach((name) => {
+        add(modules, name, named);
+      });
+    }
+  }
+  return { globals, modules };
+}
+
+/**
+ * The type roots of one configuration that a package manager installs into: those its
+ * `typeRoots` lists, else each `node_modules/@types` directory at or above its directory.
+ */
+function typeRoots(configFile: string, options: Readonly<Record<string, unknown>>): string[] {
+  const listed = options["typeRoots"];
+  if (Array.isArray(listed)) {
+    return listed.filter(
+      (root): root is string => typeof root === "string" && root.endsWith(`/${TYPE_ROOT}`),
+    );
+  }
+  return ancestors(dirnamePath(configFile)).map((dir) => joinPath(dir, TYPE_ROOT));
+}