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

package/src/schema.ts

@@ -106,6 +106,7 @@ export const SCHEMA_ROOT: KeyNode = {
           members: { components: declarations, bases: declarations, members: leaf },
         },
         serializers: declarations,
+        roots_complete: leaf,
       },
     },
     provenance: { kind: "map" },

package/src/serialization-contract.ts

@@ -1,10 +1,10 @@
 /**
  * The serialization-contract class: the data members and `toJSON` of every type a value's
  * static type reaches, where the value reaches `JSON.stringify` or a call `ts.serializers`
- * names, and `toString` too where it reaches an `unknown` or `any` parameter of a function
- * outside the analysis or an erased property of a type the program does not declare. A
- * function of the project handing such a parameter to a destination is one, to a fixpoint,
- * and a function invoked through `call`, `apply` or `bind` is the callee.
+ * names, and `toString` too where it reaches an erased parameter of a function outside the
+ * analysis, or an erased property of a type the program does not declare. A function of
+ * the project handing such a parameter to a destination is one, to a fixpoint, and a
+ * function invoked through `call`, `apply` or `bind` is the callee.
  */
 
 import {
@@ -80,6 +80,9 @@ const SERIALIZED_CONVERSION = "toJSON";
 /** The parameter types that keep nothing of the value they are given. */
 const ERASED = TypeFlags.Any | TypeFlags.Unknown;
 
+/** How deep a callee's result is searched for a type parameter: `Promise<Box<T>>` is two levels. */
+const MENTION_DEPTH = 3;
+
 /**
  * What a destination holds back of a class: its properties, or its properties and its
  * two conversion methods. The second holds back everything the first does.
@@ -564,6 +567,30 @@ function destinations<Brand>(
     });
     return containing.length === 0 ? target.declarations : containing;
   };
+  /** Whether a type names a type parameter, through constituents, type arguments and call signatures. */
+  const mentions = (type: Type, parameter: Type, depth: number): boolean => {
+    // A conditional type an alias names, `Awaited<T>` among them, carries its arguments
+    // only on the alias the client's type object reports.
+    const aliased = (type as { readonly aliasTypeArguments?: readonly number[] })
+      .aliasTypeArguments;
+    if (type.id === parameter.id || aliased?.includes(parameter.id) === true) {
+      return true;
+    }
+    if (depth >= MENTION_DEPTH) {
+      return false;
+    }
+    const inner = [
+      ...(type.isUnionType() || type.isIntersectionType() ? must(queries.constituents(type)) : []),
+      ...must(queries.typeArguments(type)),
+      ...must(queries.signaturesOf(type, SignatureKind.Call)).flatMap((signature) => [
+        ...signature.parameters.map((_parameter, at) =>
+          must(queries.typeAtPosition(signature, at)),
+        ),
+        ...[must(queries.returnTypeOf(signature))].filter((one) => one !== undefined),
+      ]),
+    ];
+    return inner.some((one) => mentions(one, parameter, depth + 1));
+  };
   const erasedArguments = new Map<CallExpression, ReadonlySet<number>>();
   const erasedAt = (call: CallExpression, argument: number): boolean => {
     let indexes = erasedArguments.get(call);
@@ -577,8 +604,32 @@ function destinations<Brand>(
           ? []
           : must(queries.signaturesOf(type, SignatureKind.Call))
         : [resolvedOf(call)].filter((one) => one !== undefined);
+      // A type parameter of the callee that nothing constrains and its result does not name
+      // keeps nothing of the value either: the instantiated signature names the value's own
+      // type there instead, and a result that names it hands the value back.
+      const generic = invoked.indirect ? undefined : resolvedOf(call);
+      const declared = generic === undefined ? undefined : must(queries.genericOf(generic));
+      const unconstrained = (index: number): boolean => {
+        const parameter =
+          declared === undefined ? undefined : must(queries.parameterType(declared, index));
+        const parts =
+          parameter === undefined
+            ? []
+            : parameter.isUnionType()
+              ? must(queries.constituents(parameter))
+              : [parameter];
+        const result = declared === undefined ? undefined : must(queries.returnTypeOf(declared));
+        return parts.some((part) => {
+          if (!part.isTypeParameter() || (result !== undefined && mentions(result, part, 0))) {
+            return false;
+          }
+          const constraint = must(queries.constraintOf(part));
+          return constraint === undefined || (constraint.flags & ERASED) !== 0;
+        });
+      };
       indexes = new Set(
         invoked.arguments.flatMap((_unused, index) =>
+          unconstrained(index) ||
           signatures.some((signature) => {
             const parameter = must(queries.parameterType(signature, index));
             return parameter !== undefined && (parameter.flags & ERASED) !== 0;

package/src/session.ts

@@ -129,6 +129,7 @@ export function openEngine(options: EngineOptions): Engine {
     ...(mapper === undefined ? {} : { runExternalCode: true }),
   });
   let closed = false;
+  const parsed = new Map<string, { readonly text: string; readonly file: SourceFile }>();
   return {
     parseConfigFile: (file) => api.parseConfigFile(file),
     parseConfigJson: (json, configFile) =>
@@ -160,8 +161,14 @@ export function openEngine(options: EngineOptions): Engine {
         moduleResolutions: { fallback: "resolve", entries: [...entries] },
       }),
     parseSourceFile: (fileName, text) => {
+      // Every project of a run reads the same files outside its program, so one parse serves all.
+      const known = parsed.get(fileName);
+      if (known?.text === text) {
+        return known.file;
+      }
       const retained = api.createSourceFile(fileName, text);
       try {
+        parsed.set(fileName, { text, file: retained.sourceFile });
         return retained.sourceFile;
       } finally {
         retained.dispose();

package/src/source-files.ts

@@ -6,12 +6,18 @@
 
 import type { SourceFile } from "@typescript/native/ast";
 import { commonDirectory, emittedFrom } from "./emit-map.ts";
-import { dirnamePath, relativePath, resolvePath } from "./paths.ts";
+import { dirnamePath, joinPath, relativePath, resolvePath } from "./paths.ts";
 import type { ProjectView } from "./session.ts";
 
 /** The one character a subpath pattern of a manifest's `exports` holds. */
 const SUBPATH_WILDCARD = "*";
 
+/** The extension a source file's name drops when the project writes it out. */
+const SOURCE_EXTENSION = /\.[cm]?[jt]sx?$/u;
+
+/** The extensions the project may write a source file's output under. */
+const OUTPUT_EXTENSIONS = [".js", ".mjs", ".cjs", ".jsx", ".d.ts", ".d.mts", ".d.cts"] as const;
+
 /**
  * Whether one path is what a subpath pattern stands for: the text before the
  * wildcard, any run of characters including the solidus, then the text after it.
@@ -40,6 +46,47 @@ export interface SourceFiles {
   named(path: string): readonly SourceFile[];
   /** The directories the project writes its output below, absolute: its output and declaration directories. */
   readonly outputDirs: readonly string[];
+  /** The output paths, absolute, the project writes one own file to, each of which {@link named} reads back to it. */
+  writtenAs(file: SourceFile): readonly string[];
+  /**
+   * The own files one absolute path names read as an output of the project written below
+   * `outputDir`: a manifest that ships from its build directory names its entries there.
+   */
+  namedAsOutput(outputDir: string, path: string): readonly SourceFile[];
+}
+
+/** The first own file of the paths given that the project holds, or none. */
+function heldAt(
+  byName: ReadonlyMap<string, SourceFile>,
+  paths: readonly string[],
+): readonly SourceFile[] {
+  for (const candidate of paths) {
+    const file = byName.get(candidate);
+    if (file !== undefined) {
+      return [file];
+    }
+  }
+  return [];
+}
+
+/** Where one project writes its output, and the directory it writes it from, absolute. */
+function layoutOf<Brand>(
+  project: ProjectView<Brand>,
+  fileNames: readonly string[],
+): {
+  readonly outDir: string | undefined;
+  readonly declarationDir: string | undefined;
+  readonly sourceDir: string;
+} {
+  const options = project.program.getCompilerOptions();
+  const configDir = dirnamePath(project.configFile);
+  const at = (option: string | undefined): string | undefined =>
+    option === undefined ? undefined : resolvePath(configDir, option);
+  return {
+    outDir: at(options.outDir),
+    declarationDir: at(options.declarationDir),
+    sourceDir: at(options.rootDir) ?? commonDirectory(fileNames),
+  };
 }
 
 /**
@@ -62,14 +109,7 @@ export function sourceFilesOf<Brand>(project: ProjectView<Brand>, targetRoot: st
     }
   }
 
-  const options = project.program.getCompilerOptions();
-  const configDir = dirnamePath(project.configFile);
-  const at = (option: string | undefined): string | undefined =>
-    option === undefined ? undefined : resolvePath(configDir, option);
-  const outDir = at(options.outDir);
-  const declarationDir = at(options.declarationDir);
-  const sourceDir = at(options.rootDir) ?? commonDirectory([...byName.keys()]);
-
+  const { outDir, declarationDir, sourceDir } = layoutOf(project, [...byName.keys()]);
   const layout = { outDir, declarationDir, sourceDirs: [sourceDir] };
 
   /** The source paths one written path may stand for, the path itself first. */
@@ -79,15 +119,25 @@ export function sourceFilesOf<Brand>(project: ProjectView<Brand>, targetRoot: st
     byPath,
     byName,
     outputDirs: [...new Set([outDir, declarationDir])].filter((dir) => dir !== undefined),
+    writtenAs: (file) => {
+      const below = relativePath(sourceDir, file.fileName);
+      if (below === undefined) {
+        return [];
+      }
+      const written = [outDir, declarationDir].flatMap((dir) =>
+        dir === undefined
+          ? []
+          : OUTPUT_EXTENSIONS.map((extension) =>
+              joinPath(dir, below.replace(SOURCE_EXTENSION, extension)),
+            ),
+      );
+      return [...new Set(written)].filter((path) => heldAt(byName, candidates(path))[0] === file);
+    },
+    namedAsOutput: (outputDir, path) =>
+      heldAt(byName, emittedFrom(path, { outDir: outputDir, sourceDirs: [sourceDir] })),
     named: (path) => {
       if (!path.includes(SUBPATH_WILDCARD)) {
-        for (const candidate of candidates(path)) {
-          const held = byName.get(candidate);
-          if (held !== undefined) {
-            return [held];
-          }
-        }
-        return [];
+        return heldAt(byName, candidates(path));
       }
       const patterns = candidates(path).filter((candidate) => candidate.includes(SUBPATH_WILDCARD));
       return [...byName.values()].filter((file) =>

package/src/suppress-file.ts

@@ -19,6 +19,7 @@ import {
   UNSCOPED_ENTRY,
   blankReason,
   isEntryPath,
+  isPartKind,
   isSymbolRef,
   siteText,
   type Mechanism,
@@ -155,13 +156,23 @@ function readRecord(value: unknown, site: Position, byReference: ByReference, sh
   if (refusals.length > 0) {
     return { records: [], refusals };
   }
-  const named = byReference.get(declarationKey(symbol, written.path)) ?? [];
+  const named =
+    byReference.get(declarationKey(symbol, written.path)) ??
+    (isPartKind(code)
+      ? byReference.get(declarationKey(parameterHolder(symbol), written.path))
+      : undefined) ??
+    [];
   if (named.length === 0) {
     return { records: [{ ...written, bound: "" }], refusals: [] };
   }
   return { records: named.map((one) => ({ ...written, bound: one.id })), refusals: [] };
 }
 
+/** The reference of the declaration a parameter's reference names it under, or `ref` itself. */
+function parameterHolder(ref: string): string {
+  return ref.endsWith(")") ? ref.slice(0, ref.lastIndexOf("(")) : ref;
+}
+
 function byReferenceOf(symbols: readonly InventorySymbol[]): ByReference {
   const byReference = new Map<string, InventorySymbol[]>();
   for (const symbol of symbols) {

package/src/suppress-inline.ts

@@ -10,8 +10,10 @@ import {
   type Node,
   type SourceFile,
 } from "@typescript/native/ast";
+import { importBindings } from "./import-bindings.ts";
 import { isParameterProperty, nodeKey, type Inventory } from "./inventory.ts";
 import { byPosition, positionKey, renderPosition, type Position } from "./position.ts";
+import { importRef } from "./ref.ts";
 import type { ProjectView } from "./session.ts";
 import { signatureOf } from "./signatures.ts";
 import {
@@ -200,6 +202,7 @@ function declarationLines(
   file: SourceFile,
   held: Inventory,
   symbols: ReadonlyMap<string, Declared>,
+  targetRoot: string,
 ): ReadonlyMap<number, readonly Binding[]> {
   const below = new Map<number, Binding[]>();
   const add = (offset: number, one: Binding): void => {
@@ -245,6 +248,20 @@ function declarationLines(
     node.forEachChild(visit);
   };
   file.forEachChild(visit);
+  // An import binding is a subject of its own, bound on its line as a declaration is.
+  const fileId = held.declarations.get(nodeKey(file, file));
+  const moduleRef = held.symbols.find((symbol) => symbol.id === fileId)?.ref ?? "";
+  for (const name of moduleRef === "" ? [] : importBindings(file)) {
+    const position = renderPosition(file, targetRoot, name.getStart());
+    const one = { id: positionKey(position), ref: importRef(moduleRef, name.text), position };
+    let statement: Node = name;
+    while (statement.parent.kind !== SyntaxKind.SourceFile) {
+      statement = statement.parent;
+    }
+    for (const at of [statement.pos, name.getStart()]) {
+      add(at, { declared: one, part: one });
+    }
+  }
   return below;
 }
 
@@ -285,7 +302,7 @@ export function inlineDirectives<Brand>(
     if (comments.length === 0) {
       continue;
     }
-    const below = declarationLines(file, held, symbols);
+    const below = declarationLines(file, held, symbols, targetRoot);
     for (const comment of comments) {
       const site = renderPosition(file, targetRoot, comment.offset);
       const target = trails(file, comment.offset) ? site.line : site.line + 1;

package/src/suppress.ts

@@ -243,10 +243,11 @@ function claimKey(finding: Finding): string {
 
 /**
  * Whether one record names one finding. A record reaches a finding in two ways: it bound
- * the declaration at the finding's position, or it names the finding's reference and the
- * file the finding is reported in, each exactly. The second is how an entry copied from a
- * finding about a part of a declaration reaches the part, and the only way any record
- * reaches a dependency row.
+ * the declaration at the finding's position, or it names the finding's reference, or the
+ * reference of the declaration holding a part that has one of its own, and the file the
+ * finding is reported in, each exactly. The second is how an entry copied from a finding
+ * about a part of a declaration reaches the part, and the only way any record reaches a
+ * dependency row.
  */
 export function pairs(record: SuppressionRecord, finding: Finding): boolean {
   if (record.code !== finding.code) {
@@ -265,7 +266,10 @@ export function pairs(record: SuppressionRecord, finding: Finding): boolean {
   if (record.bound !== "" && record.bound === positionKey(finding.position)) {
     return true;
   }
-  return record.symbol === finding.symbol.ref && record.path === finding.position.path;
+  return (
+    (record.symbol === finding.symbol.ref || record.symbol === finding.symbol.holder) &&
+    record.path === finding.position.path
+  );
 }
 
 /**

package/src/sweep.ts

@@ -8,6 +8,7 @@
 
 import type { TSExemptionClass } from "./exempt-classes.ts";
 import { namesACaller, OUTSIDE, type Edge, type Graph } from "./graph.ts";
+import type { InventorySymbol } from "./inventory.ts";
 import type { Position } from "./position.ts";
 
 /** The liveness relation that decided a declaration, as a finding spells it. */
@@ -178,17 +179,32 @@ export function sweep(graph: Graph, input: SweepInput): Liveness {
   return { liveUnder: live, candidates };
 }
 
+/**
+ * The directory a test runner reads a manual mock from, whose exports it puts in place of
+ * the module's: https://jestjs.io/docs/manual-mocks
+ */
+const MANUAL_MOCKS = "__mocks__";
+
+/** Whether a test runner calls or reads one export of a test file: a function, or any export of a manual mock. */
+export function runnerCalls(symbol: InventorySymbol): boolean {
+  return symbol.kind === "function" || symbol.position.path.split("/").includes(MANUAL_MOCKS);
+}
+
 /**
  * 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.
+ * That run's roots are the graph's own and, of each test file, its top level and every
+ * function it exports, which a test runner may call, and every export of a manual mock,
+ * which the runner reads; any other export of a test file, and test-support code, which
+ * runs where a test imports it, are judged as any file's are.
+ * `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)
+    const exported = symbol.exported && graph.symbols[graph.parent[at] ?? OUTSIDE]?.kind === "file";
+    const called = exported && runnerCalls(symbol);
+    return graph.test[at] === true &&
+      graph.support[at] !== true &&
+      (symbol.kind === "file" || called)
       ? [{ at, kind: "test-runner" as const }]
       : [];
   });
@@ -277,10 +293,11 @@ function reachable(graph: Graph, held: readonly boolean[], mode: Mode): readonly
 
 /**
  * Admits every test declaration whose set of referenced production declarations is
- * non-empty and wholly dead, and returns which it admitted. The set is read from every
- * reference the test makes, which a production sweep does not count. A test-support
- * declaration that a test referencing a live target also references is a live target of
- * every test referencing it. A marked or exempt test is never admitted.
+ * non-empty and wholly dead, and returns which it admitted. An ambient declaration describes
+ * code the target does not implement, so it is no production declaration here. The set is
+ * read from every reference the test makes, which a production sweep does not count. A
+ * test-support declaration a test referencing a live target also references is a live
+ * target of every test referencing it. A marked or exempt test is never admitted.
  */
 function admitTestsOfDeadCode(
   graph: Graph,
@@ -293,7 +310,11 @@ function admitTestsOfDeadCode(
     let live = 0;
     if (testCode(at) && graph.subject[at] === true && held[at] !== true) {
       for (const edge of graph.out[at] ?? []) {
-        if (testCode(edge.to) || graph.subject[edge.to] !== true) {
+        if (
+          testCode(edge.to) ||
+          graph.subject[edge.to] !== true ||
+          graph.ambient[edge.to] === true
+        ) {
           continue;
         }
         targets += 1;

package/src/symbol-keys.ts

@@ -2,24 +2,31 @@
  * The members a unique symbol keys, used through element accesses. `value[key]`, where
  * `key` is a constant of a `unique symbol` type, reads the member of the receiver's type
  * whose computed name is that same constant, and a store through the access writes it.
- * No name node resolves to such a member: the key's name resolves to the constant.
+ * No name node resolves to such a member: the key's name resolves to the constant. An
+ * iteration reads the member its well-known iteration symbol keys.
  */
 
 import {
   isComputedPropertyName,
+  isForOfStatement,
   isIdentifier,
   isNoSubstitutionTemplateLiteral,
   isNumericLiteral,
   isParenthesizedExpression,
   isPropertyAccessExpression,
+  isSpreadElement,
   isStringLiteral,
   type ElementAccessExpression,
+  type Expression,
   type Node,
+  type SourceFile,
 } from "@typescript/native/ast";
 import type { Symbol as TSSymbol, Type } from "@typescript/native/sync";
 import type { AliasChains } from "./alias-chain.ts";
-import type { InventorySymbol } from "./inventory.ts";
+import { nodeKey, type Inventory, type InventorySymbol } from "./inventory.ts";
+import { renderPosition } from "./position.ts";
 import { isAnswered, type PropertyTables } from "./query.ts";
+import type { Reference } from "./references.ts";
 import type { ProjectView } from "./session.ts";
 
 /** One element access whose key is a name, and how the access uses the member it selects. */
@@ -170,3 +177,123 @@ export function keyedUses<Brand>(
     return ids.length === 0 ? [] : [{ access: one.access, ids: [...new Set(ids)] }];
   });
 }
+
+/** The well-known symbol a value's iteration calls, by the construct that iterates it. */
+type Protocol = "iterator" | "asyncIterator";
+
+/** The member name `[Symbol.<name>]` spells, where a computed name spells one. */
+function wellKnownName(name: Node | undefined): string | undefined {
+  if (name === undefined || !isComputedPropertyName(name)) {
+    return undefined;
+  }
+  const key = name.expression;
+  return isPropertyAccessExpression(key) &&
+    isIdentifier(key.expression) &&
+    key.expression.text === "Symbol" &&
+    isIdentifier(key.name)
+    ? key.name.text
+    : undefined;
+}
+
+/**
+ * The references the iterations of one project's own files make to the iteration members
+ * of the values they iterate: a `for…of` statement and a spread element read
+ * `[Symbol.iterator]`, and a `for await…of` statement reads `[Symbol.asyncIterator]` and,
+ * which it falls back to, `[Symbol.iterator]`. Each is made by the declaration holding it.
+ */
+export function iterationReferences<Brand>(
+  project: ProjectView<Brand>,
+  held: Inventory,
+  chains: AliasChains,
+  root: string,
+  testFiles: ReadonlySet<string>,
+): readonly Reference[] {
+  const queries = project.queries;
+  const ownPaths = project.ownPaths();
+  const iterated: {
+    readonly file: SourceFile;
+    readonly from: string;
+    readonly operand: Expression;
+    readonly protocols: readonly Protocol[];
+  }[] = [];
+  for (const file of project.ownSourceFiles()) {
+    const fileId = held.declarations.get(nodeKey(file, file));
+    if (fileId === undefined) {
+      continue;
+    }
+    const visit = (node: Node, from: string): void => {
+      const holder = held.declarations.get(nodeKey(file, node)) ?? from;
+      if (isForOfStatement(node)) {
+        const protocols: readonly Protocol[] =
+          node.awaitModifier === undefined ? ["iterator"] : ["asyncIterator", "iterator"];
+        iterated.push({ file, from: holder, operand: node.expression, protocols });
+      } else if (isSpreadElement(node)) {
+        iterated.push({ file, from: holder, operand: node.expression, protocols: ["iterator"] });
+      }
+      node.forEachChild((child) => {
+        visit(child, holder);
+      });
+    };
+    file.forEachChild((child) => {
+      visit(child, fileId);
+    });
+  }
+  if (iterated.length === 0) {
+    return [];
+  }
+  const types = queries.typesAt(iterated.map((one) => one.operand));
+  const members = new Map<
+    number,
+    readonly { readonly name: string; readonly ids: readonly string[] }[]
+  >();
+  const membersOf = (
+    type: Type,
+  ): readonly { readonly name: string; readonly ids: readonly string[] }[] => {
+    const known = members.get(type.id);
+    if (known !== undefined) {
+      return known;
+    }
+    const keyed: { name: string; ids: readonly string[] }[] = [];
+    const properties = queries.propertiesOf(type);
+    for (const property of isAnswered(properties) ? properties : []) {
+      for (const handle of property.declarations) {
+        const node = ownPaths.has(handle.path) ? project.declarationAt(handle)?.node : undefined;
+        const name = wellKnownName((node as { readonly name?: Node } | undefined)?.name);
+        if (name !== undefined) {
+          keyed.push({ name, ids: chains.declarationsOf(property) });
+          break;
+        }
+      }
+    }
+    members.set(type.id, keyed);
+    return keyed;
+  };
+  const found: Reference[] = [];
+  iterated.forEach((one, index) => {
+    const type = types[index];
+    if (type === undefined || !isAnswered(type)) {
+      return;
+    }
+    const parts =
+      type.isUnionType() || type.isIntersectionType() ? queries.constituents(type) : [type];
+    const position = renderPosition(one.file, root, one.operand.getStart());
+    for (const part of isAnswered(parts) ? parts : []) {
+      for (const member of membersOf(part)) {
+        if (!(one.protocols as readonly string[]).includes(member.name)) {
+          continue;
+        }
+        for (const to of member.ids) {
+          found.push({
+            from: one.from,
+            to,
+            position,
+            use: "read",
+            resolution: "keyed",
+            test: testFiles.has(position.path),
+          });
+        }
+      }
+    }
+  });
+  return found;
+}