@cplieger/deadset-ts 5.1.0 → 5.2.0

package/src/namespace-objects.ts

@@ -0,0 +1,216 @@
+/**
+ * Module namespace objects: the binding of a namespace import, the value an `await` of a
+ * dynamic `import()` produces, the first parameter of the first callback passed to `then`
+ * on one, and a `const` binding initialized with one of these. A use reads the exports it
+ * names and no other: a property access by name or by a literal index, or a destructured
+ * property, names one export, and any other use may read every export.
+ */
+
+import {
+  isArrowFunction,
+  isAwaitExpression,
+  isBindingElement,
+  isCallExpression,
+  isElementAccessExpression,
+  isExpressionStatement,
+  isFunctionExpression,
+  isIdentifier,
+  isImportDeclaration,
+  isNamespaceImport,
+  isNoSubstitutionTemplateLiteral,
+  isObjectBindingPattern,
+  isParenthesizedExpression,
+  isPropertyAccessExpression,
+  isQualifiedName,
+  isStringLiteral,
+  isVariableDeclaration,
+  isVariableDeclarationList,
+  isVoidExpression,
+  NodeFlags,
+  SyntaxKind,
+  type Identifier,
+  type Node,
+  type SourceFile,
+} from "@typescript/native/unstable/ast";
+
+/** What one use of a namespace object reads beyond the names the checker resolves. */
+export type NamespaceUse =
+  /** Every export of the module `specifier` names. */
+  | { readonly kind: "whole"; readonly specifier: Node }
+  /** The export a literal index names, the literal being the node to resolve. */
+  | { readonly kind: "indexed"; readonly literal: Node };
+
+function isLiteralText(node: Node): boolean {
+  return isStringLiteral(node) || isNoSubstitutionTemplateLiteral(node);
+}
+
+/** The outermost expression one node is, through the parentheses written around it. */
+function parenthesized(node: Node): Node {
+  let at = node;
+  while (isParenthesizedExpression(at.parent)) {
+    at = at.parent;
+  }
+  return at;
+}
+
+/** Whether one call is a dynamic `import()` whose argument is literal text. */
+function isLiteralImport(node: Node): boolean {
+  if (!isCallExpression(node) || node.expression.kind !== SyntaxKind.ImportKeyword) {
+    return false;
+  }
+  const [argument] = node.arguments;
+  return argument !== undefined && isLiteralText(argument);
+}
+
+/** The node a `const` binding's name is visible below: the block or file its statement is in. */
+function scopeOf(declaration: Node): Node {
+  const statement = declaration.parent.parent;
+  return statement.parent;
+}
+
+/** Every identifier below `scope` that spells `name`, other than `declared` and a member's name. */
+function occurrences(scope: Node, name: string, declared: Node): readonly Identifier[] {
+  const found: Identifier[] = [];
+  const visit = (node: Node): void => {
+    if (isIdentifier(node)) {
+      const parent = node.parent;
+      const member =
+        (isPropertyAccessExpression(parent) && parent.name === node) ||
+        (isQualifiedName(parent) && parent.right === node) ||
+        (isBindingElement(parent) && parent.propertyName === node);
+      if (node !== declared && node.text === name && !member) {
+        found.push(node);
+      }
+      return;
+    }
+    node.forEachChild(visit);
+  };
+  scope.forEachChild(visit);
+  return found;
+}
+
+/**
+ * Every use of the namespace objects one file holds, keyed by the node the use is written
+ * at, that reads more than a name the checker resolves: an indexed read by a literal, and
+ * any use that may read every export. A shadowing declaration of a binding's name inside
+ * its scope is read as the binding, which can only keep an export live.
+ */
+export function namespaceUses(file: SourceFile): ReadonlyMap<Node, NamespaceUse> {
+  const uses = new Map<Node, NamespaceUse>();
+
+  const binding = (name: Identifier, scope: Node, specifier: Node, seen: Set<Node>): void => {
+    if (seen.has(name)) {
+      return;
+    }
+    seen.add(name);
+    for (const one of occurrences(scope, name.text, name)) {
+      value(one, specifier, seen);
+    }
+  };
+
+  /** One use of a namespace object's value, at `node`. */
+  const value = (node: Node, specifier: Node, seen: Set<Node>): void => {
+    const at = parenthesized(node);
+    const parent = at.parent;
+    if (isExpressionStatement(parent) || isVoidExpression(parent)) {
+      return;
+    }
+    if (
+      (isPropertyAccessExpression(parent) && parent.expression === at) ||
+      (isQualifiedName(parent) && parent.left === at)
+    ) {
+      return;
+    }
+    if (isElementAccessExpression(parent) && parent.expression === at) {
+      const index = parent.argumentExpression;
+      uses.set(
+        node,
+        isLiteralText(index) ? { kind: "indexed", literal: index } : { kind: "whole", specifier },
+      );
+      return;
+    }
+    if (isVariableDeclaration(parent) && parent.initializer === at) {
+      const pattern = parent.name;
+      if (isObjectBindingPattern(pattern)) {
+        const named = pattern.elements.every(
+          (element) =>
+            element.dotDotDotToken === undefined &&
+            element.propertyName?.kind !== SyntaxKind.ComputedPropertyName,
+        );
+        if (!named) {
+          uses.set(node, { kind: "whole", specifier });
+        }
+        return;
+      }
+      const list = parent.parent;
+      if (
+        isIdentifier(pattern) &&
+        isVariableDeclarationList(list) &&
+        (list.flags & NodeFlags.Const) !== 0
+      ) {
+        binding(pattern, scopeOf(parent), specifier, seen);
+        return;
+      }
+    }
+    uses.set(node, { kind: "whole", specifier });
+  };
+
+  /** One use of a dynamic `import()` call, at `call`. */
+  const imported = (call: Node, specifier: Node, seen: Set<Node>): void => {
+    const at = parenthesized(call);
+    const parent = at.parent;
+    if (isExpressionStatement(parent) || isVoidExpression(parent)) {
+      return;
+    }
+    if (isAwaitExpression(parent)) {
+      value(parent, specifier, seen);
+      return;
+    }
+    const then = parent.parent;
+    if (
+      isPropertyAccessExpression(parent) &&
+      parent.expression === at &&
+      parent.name.text === "then" &&
+      isCallExpression(then) &&
+      then.expression === parent
+    ) {
+      const [callback] = then.arguments;
+      if (callback !== undefined && (isArrowFunction(callback) || isFunctionExpression(callback))) {
+        const [first] = callback.parameters;
+        if (first === undefined || isObjectBindingPattern(first.name)) {
+          return;
+        }
+        if (isIdentifier(first.name)) {
+          binding(first.name, callback, specifier, seen);
+          return;
+        }
+      }
+    }
+    uses.set(call, { kind: "whole", specifier });
+  };
+
+  const visit = (node: Node): void => {
+    if (isImportDeclaration(node)) {
+      const clause = node.importClause;
+      const bindings = clause?.namedBindings;
+      if (
+        clause !== undefined &&
+        clause.phaseModifier !== SyntaxKind.TypeKeyword &&
+        bindings !== undefined &&
+        isNamespaceImport(bindings)
+      ) {
+        binding(bindings.name, file, node.moduleSpecifier, new Set());
+      }
+      return;
+    }
+    if (isLiteralImport(node) && isCallExpression(node)) {
+      const [argument] = node.arguments;
+      if (argument !== undefined) {
+        imported(node, argument, new Set());
+      }
+    }
+    node.forEachChild(visit);
+  };
+  file.forEachChild(visit);
+  return uses;
+}

package/src/outside-tests.ts

@@ -0,0 +1,191 @@
+/**
+ * The test files no compiler configuration of a run holds. The runner executes them all
+ * the same, so each module one names is a test reference: the own file a relative
+ * specifier names, and the declarations that file exports under the names read from it.
+ * Such a file is read without a program, so what its body references beyond the modules
+ * it names is not known.
+ */
+
+import {
+  isCallExpression,
+  isExportDeclaration,
+  isImportDeclaration,
+  isNamespaceExport,
+  isNamespaceImport,
+  isNoSubstitutionTemplateLiteral,
+  isStringLiteral,
+  SyntaxKind,
+  type Node,
+  type SourceFile,
+} from "@typescript/native/unstable/ast";
+import { RESOLVED_EXTENSIONS, type ParseFile } from "./configuration-files.ts";
+import { emittedFrom } from "./emit-map.ts";
+import type { Host } from "./host.ts";
+import type { Inventory } from "./inventory.ts";
+import { dirnamePath, joinPath, normalizePath, queriedModulePath } from "./paths.ts";
+import { renderPosition } from "./position.ts";
+import { nameComponent } from "./ref.ts";
+import type { Reference } from "./references.ts";
+
+/** The paths below the target root one relative specifier may name, written path first. */
+function candidates(dir: string, specifier: string): readonly string[] {
+  if (!specifier.startsWith("./") && !specifier.startsWith("../")) {
+    return [];
+  }
+  const path = normalizePath(dir === "" ? specifier : `${dir}/${specifier}`);
+  return [
+    path,
+    ...emittedFrom(path, { sourceDirs: [] }),
+    ...RESOLVED_EXTENSIONS.map((extension) => path + extension),
+    ...RESOLVED_EXTENSIONS.map((extension) => `${path}/index${extension}`),
+  ];
+}
+
+/** One module a test file names, and the export names it reads from it; `evaluates` reads none. */
+interface NamedModule {
+  readonly specifier: Node;
+  readonly text: string;
+  readonly names: readonly string[];
+  readonly evaluates: boolean;
+}
+
+/** The text of a specifier written as literal text, or undefined for any other expression. */
+function literalText(node: Node | undefined): string | undefined {
+  return node !== undefined && (isStringLiteral(node) || isNoSubstitutionTemplateLiteral(node))
+    ? node.text
+    : undefined;
+}
+
+/**
+ * Every module one file names: an import declaration, a re-export, and an `import()` call
+ * of literal text anywhere in the file. A namespace form, a star re-export, a bare import
+ * and an `import()` evaluate the module.
+ */
+function modulesNamed(file: SourceFile): readonly NamedModule[] {
+  const found: NamedModule[] = [];
+  const name = (specifier: Node, names: readonly string[], evaluates: boolean): void => {
+    const text = literalText(specifier);
+    if (text !== undefined) {
+      found.push({ specifier, text, names, evaluates });
+    }
+  };
+  for (const statement of file.statements) {
+    if (isImportDeclaration(statement)) {
+      const clause = statement.importClause;
+      const bindings = clause?.namedBindings;
+      name(
+        statement.moduleSpecifier,
+        [
+          ...(clause?.name === undefined ? [] : ["default"]),
+          ...(bindings === undefined || isNamespaceImport(bindings)
+            ? []
+            : bindings.elements.map((one) => (one.propertyName ?? one.name).text)),
+        ],
+        bindings === undefined ? clause?.name === undefined : isNamespaceImport(bindings),
+      );
+    } else if (isExportDeclaration(statement) && statement.moduleSpecifier !== undefined) {
+      const clause = statement.exportClause;
+      const star = clause === undefined || isNamespaceExport(clause);
+      name(
+        statement.moduleSpecifier,
+        star ? [] : clause.elements.map((one) => (one.propertyName ?? one.name).text),
+        star,
+      );
+    }
+  }
+  const visit = (node: Node): void => {
+    if (isCallExpression(node) && node.expression.kind === SyntaxKind.ImportKeyword) {
+      const [argument] = node.arguments;
+      if (argument !== undefined) {
+        name(argument, [], true);
+      }
+    }
+    node.forEachChild(visit);
+  };
+  file.forEachChild(visit);
+  return found;
+}
+
+/** One test file read without a program. */
+export interface OutsideTest {
+  /** The path below the target root. */
+  readonly path: string;
+  readonly file: SourceFile;
+}
+
+/** Each of the given paths below the target root, parsed; one that cannot be read is skipped. */
+export function testFilesAt(
+  host: Host,
+  targetRoot: string,
+  paths: readonly string[],
+  parse: ParseFile,
+): readonly OutsideTest[] {
+  return paths.flatMap((path) => {
+    const fileName = joinPath(targetRoot, path);
+    let text: string;
+    try {
+      text = host.readFile(fileName);
+    } catch {
+      return [];
+    }
+    return [{ path, file: parse(fileName, text) }];
+  });
+}
+
+/**
+ * The references the given test files make to one project's own files through the
+ * modules they name ({@link modulesNamed}). A name read from a module references each
+ * top-level declaration the file exports under it; an evaluating form references the
+ * file. A query after the path names the file as {@link queriedModulePath} reads it.
+ */
+export function outsideTestReferences(
+  tests: readonly OutsideTest[],
+  held: Inventory,
+  targetRoot: string,
+): readonly Reference[] {
+  const fileAt = new Map(
+    held.symbols
+      .filter((symbol) => symbol.kind === "file")
+      .map((symbol) => [symbol.position.path, symbol.id]),
+  );
+  // Keyed on the reference's fragment, which spells the export name where the display
+  // name of a default export is its declared name.
+  const exported = new Map<string, string[]>();
+  for (const symbol of held.symbols) {
+    if (symbol.exported) {
+      const fragment = symbol.ref.slice(symbol.ref.lastIndexOf("#") + 1).replace(/:alias$/u, "");
+      const key = `${symbol.parent}\u0000${fragment}`;
+      exported.set(key, [...(exported.get(key) ?? []), symbol.id]);
+    }
+  }
+  const found: Reference[] = [];
+  for (const { path, file } of tests) {
+    const from = `${path}#`;
+    const dir = dirnamePath(path) === "." ? "" : dirnamePath(path);
+    for (const named of modulesNamed(file)) {
+      const written = named.text.includes("?") ? queriedModulePath(named.text) : named.text;
+      if (written === undefined) {
+        continue;
+      }
+      const fileId = candidates(dir, written)
+        .map((one) => fileAt.get(one))
+        .find((one) => one !== undefined);
+      if (fileId === undefined) {
+        continue;
+      }
+      const position = renderPosition(file, targetRoot, named.specifier.getStart());
+      const read = (to: string, use: Reference["use"]): void => {
+        found.push({ from, to, position, use, resolution: "syntax", test: true, unheld: true });
+      };
+      if (named.evaluates) {
+        read(fileId, "evaluation");
+      }
+      for (const name of named.names) {
+        for (const id of exported.get(`${fileId}\u0000${nameComponent(name)}`) ?? []) {
+          read(id, "read");
+        }
+      }
+    }
+  }
+  return found;
+}

package/src/overrides.ts

@@ -0,0 +1,136 @@
+/**
+ * The overrides of the target's class members. A call through the base class, `this`
+ * in the base's own body or a value typed as the base, names the base's member and
+ * runs the override of whichever subclass the value is, so the base member's
+ * declaration references every override as a use of it.
+ */
+
+import {
+  isClassDeclaration,
+  isClassExpression,
+  isExpressionWithTypeArguments,
+  isPropertyAccessExpression,
+  isQualifiedName,
+  SyntaxKind,
+  type HeritageClauseElement,
+  type Node,
+} from "@typescript/native/unstable/ast";
+import type { AliasChains } from "./alias-chain.ts";
+import { memberComponent } from "./class-members.ts";
+import { nodeKey, type Inventory, type InventorySymbol } from "./inventory.ts";
+import { UNANSWERED } from "./query.ts";
+import type { Reference } from "./references.ts";
+import type { ProjectView } from "./session.ts";
+
+/** The member kinds a subclass overrides. */
+const OVERRIDABLE: ReadonlySet<string> = new Set(["method", "class-member"]);
+
+/** The node naming the class one `extends` entry names. */
+function nameOf(entry: HeritageClauseElement): Node {
+  if (isExpressionWithTypeArguments(entry)) {
+    return isPropertyAccessExpression(entry.expression) ? entry.expression.name : entry.expression;
+  }
+  return isQualifiedName(entry.typeName) ? entry.typeName.right : entry.typeName;
+}
+
+/** Each class of the target whose `extends` clause names a class, with the name node. */
+function extending<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+): readonly { readonly id: string; readonly base: Node }[] {
+  const found: { id: string; base: Node }[] = [];
+  for (const file of project.ownSourceFiles()) {
+    const visit = (node: Node): void => {
+      if (isClassDeclaration(node) || isClassExpression(node)) {
+        const id = held.declarations.get(nodeKey(file, node));
+        const clause = node.heritageClauses?.find((one) => one.token === SyntaxKind.ExtendsKeyword);
+        const base = clause?.types[0];
+        if (id !== undefined && base !== undefined) {
+          found.push({ id, base: nameOf(base) });
+        }
+      }
+      node.forEachChild(visit);
+    };
+    file.forEachChild(visit);
+  }
+  return found;
+}
+
+/**
+ * The references each base class member makes to its overrides, for the classes of one
+ * project that extend another class of the target. A member a nearer base already
+ * overrides is reached through that override. A private member is not overridden.
+ * Each reference is placed at the override and made by its file.
+ */
+export function overrideReferences<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+  chains: AliasChains,
+  testFiles: ReadonlySet<string>,
+): readonly Reference[] {
+  const classes = extending(project, held);
+  if (classes.length === 0) {
+    return [];
+  }
+  const byId = new Map(held.symbols.map((symbol) => [symbol.id, symbol]));
+  const members = new Map<string, Map<string, InventorySymbol>>();
+  for (const symbol of held.symbols) {
+    const component = memberComponent(symbol, byId);
+    if (
+      component === undefined ||
+      !OVERRIDABLE.has(symbol.kind) ||
+      symbol.visibility === "private" ||
+      symbol.visibility === "private-name"
+    ) {
+      continue;
+    }
+    const own = members.get(symbol.parent) ?? new Map<string, InventorySymbol>();
+    own.set(component, symbol);
+    members.set(symbol.parent, own);
+  }
+  const bases = new Map<string, readonly string[]>();
+  const symbols = project.symbolsAt(classes.map((one) => project.handle(one.base)));
+  classes.forEach(({ id }, index) => {
+    const symbol = symbols[index];
+    if (symbol !== undefined && symbol !== UNANSWERED) {
+      bases.set(
+        id,
+        chains
+          .chainOf(symbol)
+          .map((target) => target.id)
+          .filter((target) => byId.get(target)?.kind === "class" && target !== id),
+      );
+    }
+  });
+
+  /** The nearest member of one component the class or a class it extends declares. */
+  const declaredAbove = (classId: string, component: string, seen: Set<string>): string[] => {
+    if (seen.has(classId)) {
+      return [];
+    }
+    seen.add(classId);
+    const own = members.get(classId)?.get(component);
+    if (own !== undefined) {
+      return [own.id];
+    }
+    return (bases.get(classId) ?? []).flatMap((base) => declaredAbove(base, component, seen));
+  };
+
+  const found: Reference[] = [];
+  for (const [classId, baseIds] of bases) {
+    for (const [component, member] of members.get(classId) ?? []) {
+      const seen = new Set([classId]);
+      for (const base of baseIds.flatMap((one) => declaredAbove(one, component, seen))) {
+        found.push({
+          from: base,
+          to: member.id,
+          position: member.position,
+          use: "read",
+          resolution: "override",
+          test: testFiles.has(member.position.path),
+        });
+      }
+    }
+  }
+  return found;
+}

package/src/paths.ts

@@ -72,6 +72,24 @@ export function resolvePath(against: string, path: string): string {
   return isAbsolutePath(path) ? normalizePath(path) : joinPath(against, path);
 }
 
+/**
+ * The relative path before the query of a relative module specifier such as
+ * `./worker.ts?worker`, the module a bundler loads; undefined for a specifier with no
+ * query, one that is not relative, and one whose query has a `raw` parameter, which
+ * reads the file as text and so evaluates nothing.
+ */
+export function queriedModulePath(specifier: string): string | undefined {
+  const query = specifier.indexOf("?");
+  if (query < 0 || !(specifier.startsWith("./") || specifier.startsWith("../"))) {
+    return undefined;
+  }
+  const raw = specifier
+    .slice(query + 1)
+    .split("&")
+    .some((parameter) => parameter.split("=")[0] === "raw");
+  return raw ? undefined : specifier.slice(0, query);
+}
+
 /**
  * One path as it reads below a root, or undefined when it is not below the root.
  * Both are normalized first, so a root written with a trailing separator or a `.`