@cplieger/deadset-ts 5.1.1 → 5.2.1

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/partial.ts

@@ -38,7 +38,7 @@ export function partialNotes(partial: Partial): readonly string[] {
     }
     const where = [...byProject].map(([configFile, n]) => `${configFile}: ${String(n)}`).join(", ");
     notes.push(
-      `the checker answered ${counted(partial.unanswered.length, "question", "questions")} with a failure (${where}); every declaration an answer could have kept live is kept live and reported by nothing`,
+      `the checker answered ${counted(partial.unanswered.length, "question", "questions")} with a failure (${where}), so every declaration an answer could have kept live is kept live and reported by nothing`,
     );
   }
   return notes;

package/src/references.ts

@@ -12,8 +12,11 @@ import {
   isForInStatement,
   isForOfStatement,
   isForStatement,
+  isIdentifier,
   isImportDeclaration,
   isImportEqualsDeclaration,
+  isMetaProperty,
+  isNewExpression,
   isNamespaceExport,
   isNoSubstitutionTemplateLiteral,
   isObjectLiteralExpression,
@@ -35,6 +38,8 @@ import type { Symbol as TSSymbol } from "@typescript/native/unstable/sync";
 import { aliasChains, type ChainTarget } from "./alias-chain.ts";
 import { contextualUses, type FlowAt, type LiteralAt } from "./contextual-uses.ts";
 import { destructuring, propertyReadsOf, type PropertyRead } from "./destructuring.ts";
+import { specifierCandidates } from "./configuration-files.ts";
+import { namespaceUses } from "./namespace-objects.ts";
 import { globExpression } from "./glob.ts";
 import { declarationsByName, nodeKey, type Inventory, type InventorySymbol } from "./inventory.ts";
 import { overrideReferences } from "./overrides.ts";
@@ -424,6 +429,27 @@ interface Evaluation {
   readonly from: string;
 }
 
+/**
+ * One module URL a source file builds: `new URL(<literal>, import.meta.url)` or
+ * `import.meta.resolve(<literal>)`, the literal relative. A runtime starts the file it
+ * names as a module, so it is an import of that file for its effects.
+ */
+interface ModuleURL {
+  readonly specifier: string;
+  /** The `URL` the constructor names, which must name no declaration of the target. */
+  readonly constructor: Node | undefined;
+  readonly at: Node;
+}
+
+/** One use of a module namespace object that may read every export of the module. */
+interface WholeRead {
+  /** The module specifier, whose symbol is the module read. */
+  readonly specifier: Node;
+  /** The use, whose position the reference carries. */
+  readonly at: Node;
+  readonly from: string;
+}
+
 /** One decorator expression, and the declaration it is attached to. */
 interface Decorated {
   readonly decorator: Node;
@@ -443,9 +469,55 @@ interface FileSites {
   readonly reads: readonly Read[];
   readonly links: readonly Link[];
   readonly evaluations: readonly Evaluation[];
+  readonly wholes: readonly WholeRead[];
+  readonly urls: readonly ModuleURL[];
   readonly decorated: readonly Decorated[];
 }
 
+/** Whether one node is `import.meta.url`. */
+function isImportMetaURL(node: Node): boolean {
+  const at = unparenthesized(node);
+  return (
+    isPropertyAccessExpression(at) &&
+    isMetaProperty(at.expression) &&
+    at.expression.keywordToken === SyntaxKind.ImportKeyword &&
+    at.name.text === "url"
+  );
+}
+
+/** The module URL one node builds, where it builds one. */
+function moduleURLOf(node: Node): ModuleURL | undefined {
+  const relative = (argument: Node | undefined): string | undefined => {
+    const at = argument === undefined ? undefined : unparenthesized(argument);
+    return at !== undefined &&
+      (isStringLiteral(at) || isNoSubstitutionTemplateLiteral(at)) &&
+      /^\.\.?\//u.test(at.text)
+      ? at.text
+      : undefined;
+  };
+  if (isNewExpression(node) && isIdentifier(node.expression) && node.expression.text === "URL") {
+    const [reference, base] = node.arguments ?? [];
+    const specifier = relative(reference);
+    return specifier !== undefined && base !== undefined && isImportMetaURL(base)
+      ? { specifier, constructor: node.expression, at: node }
+      : undefined;
+  }
+  if (isCallExpression(node)) {
+    const callee = unparenthesized(node.expression);
+    const specifier = relative(node.arguments[0]);
+    if (
+      specifier !== undefined &&
+      isPropertyAccessExpression(callee) &&
+      isMetaProperty(callee.expression) &&
+      callee.expression.keywordToken === SyntaxKind.ImportKeyword &&
+      callee.name.text === "resolve"
+    ) {
+      return { specifier, constructor: undefined, at: node };
+    }
+  }
+  return undefined;
+}
+
 /** Whether one node is a string literal or a template literal with no substitution. */
 function isLiteralText(node: Node | undefined): node is Node {
   return node !== undefined && (isStringLiteral(node) || isNoSubstitutionTemplateLiteral(node));
@@ -584,7 +656,10 @@ function sitesOf(
   const reads: Read[] = [];
   const links: Link[] = [];
   const evaluations: Evaluation[] = [];
+  const wholes: WholeRead[] = [];
+  const urls: ModuleURL[] = [];
   const decorated: Decorated[] = [];
+  const namespaces = namespaceUses(file);
   const literals: LiteralAt[] = [];
   const flows: FlowAt[] = [];
   const writes = new Set<number>();
@@ -615,6 +690,12 @@ function sitesOf(
     if (unread.has(node)) {
       return;
     }
+    const namespace = namespaces.get(node);
+    if (namespace?.kind === "whole") {
+      wholes.push({ specifier: namespace.specifier, at: node, from: enclosing });
+    } else if (namespace?.kind === "indexed") {
+      found.push({ node: namespace.literal, shorthand: undefined, from: enclosing, use: "read" });
+    }
     if (isName(node)) {
       if (!declared.has(node.pos)) {
         const site = { node, shorthand: shorthands.get(node.pos), from: enclosing };
@@ -644,6 +725,10 @@ function sitesOf(
     if (evaluated !== undefined) {
       evaluations.push({ node: evaluated, from: enclosing });
     }
+    const url = moduleURLOf(node);
+    if (url !== undefined) {
+      urls.push(url);
+    }
     const held = declarations.get(nodeKey(file, node));
     const outer = enclosing;
     if (held !== undefined) {
@@ -659,7 +744,7 @@ function sitesOf(
   };
 
   file.forEachChild(visit);
-  return { uses: found, literals, flows, reads, links, evaluations, decorated };
+  return { uses: found, literals, flows, reads, links, evaluations, wholes, urls, decorated };
 }
 
 /** The declaration kinds of a property an object literal declares. */
@@ -922,6 +1007,36 @@ export function references<Brand>(
     return topLevel.get(fileId) ?? [];
   };
 
+  const exportsCache = new Map<number, readonly ChainTarget[]>();
+  /**
+   * Every declaration one module exports, each re-export walked along its chain. A module
+   * the checker left unanswered may be any file, so it reads every file's exports.
+   */
+  const exportsRead = (module: Answer<TSSymbol>): readonly ChainTarget[] => {
+    if (module === UNANSWERED) {
+      return [...fileIds].flatMap((id) =>
+        declaredIn(id)
+          .filter((symbol) => symbol.exported)
+          .map((symbol) => ({ id: symbol.id, stepped: false, guessed: true })),
+      );
+    }
+    const known = exportsCache.get(module.id);
+    if (known !== undefined) {
+      return known;
+    }
+    const table = project.queries.exportsOfModule(module);
+    const read =
+      table === UNANSWERED
+        ? chains.declarationsOf(module).flatMap((id) =>
+            declaredIn(id)
+              .filter((symbol) => symbol.exported)
+              .map((symbol) => ({ id: symbol.id, stepped: false, guessed: true })),
+          )
+        : table.flatMap((exported) => chains.chainOf(exported));
+    exportsCache.set(module.id, read);
+    return read;
+  };
+
   /** The identifier of the declaration one node of this program is, where it is one. */
   const declaredAt = (node: Node): string | undefined =>
     declarations.get(nodeKey(node.getSourceFile(), node));
@@ -1022,7 +1137,7 @@ export function references<Brand>(
     const fileId = declaredAt(file) ?? "";
     return { file, fileId, ...sitesOf(file, declarations, fileId, unread) };
   });
-  const fileIdByName = new Map(
+  const fileIdByName = new Map<string, string>(
     walked.filter((one) => fileIds.has(one.fileId)).map((one) => [one.file.fileName, one.fileId]),
   );
   const contextual = contextualUses(
@@ -1112,7 +1227,7 @@ export function references<Brand>(
     }
   }
 
-  for (const { file, fileId, uses, reads, links, evaluations, decorated } of walked) {
+  for (const { file, fileId, uses, reads, links, evaluations, wholes, urls, decorated } of walked) {
     const test = testFile.get(file) === true;
     // A component file's markup may use any binding its blocks declare at the top level.
     const markup = isComponentFile(file);
@@ -1142,6 +1257,8 @@ export function references<Brand>(
         ...uses.filter((site) => site.shorthand === undefined).map((site) => site.node),
         ...links.map((link) => link.node),
         ...evaluations.map((evaluation) => evaluation.node),
+        ...wholes.map((whole) => whole.specifier),
+        ...urls.flatMap((url) => url.constructor ?? []),
         ...bindings.map((binding) => binding.node),
       ]),
     ];
@@ -1217,6 +1334,47 @@ export function references<Brand>(
       }
     }
 
+    for (const url of urls) {
+      const constructor = url.constructor === undefined ? undefined : answered.get(url.constructor);
+      if (
+        typeof constructor === "object" &&
+        constructor.declarations.some((handle) => ownPaths.has(handle.path))
+      ) {
+        continue;
+      }
+      const loaded = specifierCandidates(dirnamePath(file.fileName), url.specifier)
+        .map((path) => fileIdByName.get(path))
+        .find((id) => id !== undefined);
+      if (loaded !== undefined) {
+        found.push({
+          from: fileId,
+          to: loaded,
+          position: renderPosition(file, root, url.at.getStart()),
+          use: "evaluation",
+          resolution: "syntax",
+          test,
+        });
+      }
+    }
+
+    for (const whole of wholes) {
+      const module = answered.get(whole.specifier);
+      if (module === undefined) {
+        continue;
+      }
+      const position = renderPosition(file, root, whole.at.getStart());
+      for (const target of exportsRead(module)) {
+        found.push({
+          from: whole.from,
+          to: target.id,
+          position,
+          use: "read",
+          resolution: target.guessed ? "by-name" : "batch",
+          test,
+        });
+      }
+    }
+
     if (markup) {
       for (const symbol of declaredIn(fileId)) {
         found.push({

package/src/roots.ts

@@ -26,6 +26,7 @@ import { globExpression } from "./glob.ts";
 import type { Host } from "./host.ts";
 import { nodeKey, type Inventory, type InventorySymbol } from "./inventory.ts";
 import type { Manifest, ManifestEntry } from "./manifest.ts";
+import { relativePath, resolvePath } from "./paths.ts";
 import { byPosition } from "./position.ts";
 import { UNANSWERED } from "./query.ts";
 import type { ProjectView } from "./session.ts";
@@ -135,6 +136,50 @@ const ENTRY_KINDS = {
   script: "script",
 } as const satisfies Record<ManifestEntry["role"], RootKind>;
 
+/** The rules whose rooted files a manifest target is read back to by name. */
+const READ_BACK_RULES: ReadonlySet<EntryRule> = new Set([
+  "configuration-file",
+  "configuration-string",
+  "html-entry",
+]);
+
+/** The extensions a manifest target's name drops: the ones a build writes. */
+const OUTPUT_EXTENSION = /\.(?:d\.ts|d\.mts|d\.cts|js|mjs|cjs|jsx)$/u;
+
+/** The extension a source file's name drops. */
+const SOURCE_EXTENSION = /\.(?:d\.)?[cm]?[jt]sx?$/u;
+
+/**
+ * The rooted files one manifest target reads back to by name: its path below the
+ * manifest's directory, past its first directory where it names one, without its output
+ * extension, is the name, and a rooted file is one whose path below the same directory,
+ * without its source extension, ends with that name at a directory boundary.
+ */
+function readBackByName(
+  host: Host,
+  entry: ManifestEntry,
+  rooted: readonly SourceFile[],
+): readonly SourceFile[] {
+  const dir = resolvePath(host.workingDirectory(), entry.dir);
+  const below = relativePath(dir, resolvePath(host.workingDirectory(), entry.path));
+  if (below === undefined || below === "") {
+    return [];
+  }
+  const cut = below.indexOf("/");
+  const name = (cut === -1 ? below : below.slice(cut + 1)).replace(OUTPUT_EXTENSION, "");
+  if (name === "") {
+    return [];
+  }
+  const found = new Map<string, SourceFile>();
+  for (const file of rooted) {
+    const path = relativePath(dir, file.fileName)?.replace(SOURCE_EXTENSION, "");
+    if (path !== undefined && (path === name || path.endsWith(`/${name}`))) {
+      found.set(file.fileName, file);
+    }
+  }
+  return [...found.values()];
+}
+
 /** Whether a configured string carries either special character. */
 function isPattern(text: string): boolean {
   return text.includes("*") || text.includes("?");
@@ -245,6 +290,14 @@ export function roots<Brand>(
     entered.push({ file, kind, source, exports });
   };
 
+  const points = entryPoints(
+    project,
+    files,
+    options.testFiles,
+    options.host,
+    targetRoot,
+    options.parse,
+  );
   const published: SourceFile[] = [];
   const entries = [
     ...options.manifest.entries.map((entry) => ({
@@ -255,14 +308,27 @@ export function roots<Brand>(
     })),
     ...(options.otherPackages ?? []).map((entry) => ({ entry, publishes: entry.published })),
   ];
+  const scripted = entries.flatMap(({ entry }) =>
+    entry.role === "script" ? files.named(entry.path) : [],
+  );
+  const readBackTo = [
+    ...scripted,
+    ...points.filter((point) => READ_BACK_RULES.has(point.rule)).map((point) => point.file),
+  ];
+  const entryFiles = (entry: ManifestEntry): readonly SourceFile[] => {
+    const named = files.named(entry.path);
+    return named.length > 0 || entry.role === "script"
+      ? named
+      : readBackByName(options.host, entry, readBackTo);
+  };
   for (const { entry, publishes } of entries) {
     if (options.publishedAPI && publishes) {
-      published.push(...files.named(entry.path));
+      published.push(...entryFiles(entry));
     }
   }
   const publishedNames = new Set(published.map((file) => file.fileName));
   for (const { entry } of entries) {
-    for (const file of files.named(entry.path)) {
+    for (const file of entryFiles(entry)) {
       const kind = ENTRY_KINDS[entry.role];
       enter(file, kind, entry.member, !publishedNames.has(file.fileName));
     }
@@ -280,14 +346,7 @@ export function roots<Brand>(
     : conventionEntries(options.conventions, files)) {
     enter(file, "convention", row, true);
   }
-  for (const point of entryPoints(
-    project,
-    files,
-    options.testFiles,
-    options.host,
-    targetRoot,
-    options.parse,
-  )) {
+  for (const point of points) {
     enter(point.file, point.rule, point.source, point.exports);
   }
   for (const file of files.byPath.values()) {

package/src/sweep.ts

@@ -166,6 +166,25 @@ export function sweep(graph: Graph, input: SweepInput): Liveness {
   return { liveUnder: live, candidates };
 }
 
+/**
+ * Per declaration of the graph, whether the run that counts test references reaches it.
+ * That run's roots are the graph's own and each test file, being the file's top level
+ * and every declaration it exports, which a test runner may call; `held` seeds it as a
+ * mark or an exemption seeds a sweep.
+ */
+export function reachedWithTheTests(graph: Graph, held: readonly string[]): readonly boolean[] {
+  const tests = graph.symbols.flatMap((symbol, at) => {
+    const top =
+      symbol.kind === "file" || graph.symbols[graph.parent[at] ?? OUTSIDE]?.kind === "file";
+    return graph.test[at] === true && top && (symbol.kind === "file" || symbol.exported)
+      ? [{ at, kind: "test-runner" as const }]
+      : [];
+  });
+  return reachable({ ...graph, rooted: [...graph.rooted, ...tests] }, flagged(graph, held), {
+    production: false,
+  });
+}
+
 /**
  * The references a loaded consumer makes that the mode counts. A production mode counts
  * none a consumer's test file made, as it counts none of the target's.