@cplieger/deadset-ts 8.0.0-dev.1 → 8.0.0-dev.3

package/src/conventions.ts

@@ -66,6 +66,7 @@ import { dirnamePath, joinPath, normalizePath, relativePath, resolvePath } from
 import type { SetupFailure } from "./setup-failure.ts";
 import type { SourceFiles } from "./source-files.ts";
 import { satisfies } from "./version-range.ts";
+import { yamlDocument } from "./yaml-document.ts";
 
 /** One manifest the analysis reads. */
 export interface ConventionManifest {
@@ -151,6 +152,13 @@ type ParseSource = (fileName: string, text: string) => SourceFile;
 
 const JSON_EXTENSION = ".json";
 
+/**
+ * A configuration file its tool reads as a YAML document, read as the JSON document it
+ * denotes. Its nodes' offsets are that JSON text's, so no move may read one: a failure's
+ * line would name the wrong line.
+ */
+const YAML_NAME = /\.ya?ml$/u;
+
 /** A configuration file with no extension that its tool reads as a JSON document. */
 const JSON_RC = /^\.[\w-]+rc$/u;
 
@@ -883,6 +891,14 @@ function readingFiles(
       } catch {
         continue;
       }
+      if (YAML_NAME.test(name)) {
+        const value = yamlDocument(text);
+        if (value !== undefined) {
+          const json = JSON.stringify(value);
+          found.push({ name, text: json, file: parse(`${path}${JSON_EXTENSION}`, json) });
+        }
+        continue;
+      }
       found.push({
         name,
         text,

package/src/dependencies.ts

@@ -871,6 +871,98 @@ function scriptTokensOf(manifest: Record<string, unknown>): ReadonlySet<string>
   return found;
 }
 
+/**
+ * The runtime flags whose value is a module loaded before the entry, as `--flag value` or
+ * `--flag=value`: https://nodejs.org/api/cli.html#--importmodule,
+ * https://nodejs.org/api/cli.html#--experimental-loadermodule,
+ * https://nodejs.org/api/cli.html#-r---require-module
+ */
+const PRELOAD_FLAGS: ReadonlySet<string> = new Set([
+  "--experimental-loader",
+  "--import",
+  "--loader",
+  "--require",
+  "-r",
+]);
+
+/**
+ * The programs that pass a preload flag to the runtime they start: Node itself, and the
+ * runners that forward Node's flags or read the same `--require`:
+ * https://mochajs.org/#-require-module-r-module, https://tsx.is/node-enhancement,
+ * https://typestrong.org/ts-node/docs/options#require,
+ * https://github.com/remy/nodemon#running-non-node-scripts
+ */
+const PRELOADING_PROGRAMS: ReadonlySet<string> = new Set([
+  "mocha",
+  "node",
+  "nodemon",
+  "ts-node",
+  "tsx",
+]);
+
+/** The programs that run the command after them, and an environment assignment before it. */
+const LAUNCHERS: ReadonlySet<string> = new Set(["cross-env", "env", "npx"]);
+const ASSIGNMENT = /^[A-Za-z_][A-Za-z0-9_]*=/u;
+
+/** The commands one script string runs, split at the shell's list and pipeline operators. */
+const COMMAND_SEPARATORS = /&&|\|\||;|\||&/u;
+
+/**
+ * The packages one manifest's scripts preload by a runtime flag's bare module specifier,
+ * a flag counting only in a command whose program passes it to the runtime, and for Node
+ * only before the script it runs, whose own arguments come after it.
+ */
+function scriptPreloadsOf(manifest: Record<string, unknown>): ReadonlySet<string> {
+  const scripts = manifest["scripts"];
+  const found = new Set<string>();
+  if (!isRecord(scripts)) {
+    return found;
+  }
+  for (const script of Object.values(scripts)) {
+    if (typeof script !== "string") {
+      continue;
+    }
+    for (const command of script.split(COMMAND_SEPARATORS)) {
+      const tokens = scriptTokens(command);
+      let at = 0;
+      while (
+        at < tokens.length &&
+        (ASSIGNMENT.test(tokens[at] ?? "") || LAUNCHERS.has(tokens[at] ?? ""))
+      ) {
+        at += 1;
+      }
+      const path = tokens[at] ?? "";
+      const program = path.slice(path.lastIndexOf("/") + 1);
+      if (!PRELOADING_PROGRAMS.has(program)) {
+        continue;
+      }
+      for (at += 1; at < tokens.length; at += 1) {
+        const token = tokens[at] ?? "";
+        if (!token.startsWith("-")) {
+          if (program === "node") {
+            break;
+          }
+          continue;
+        }
+        const equals = token.indexOf("=");
+        const flag = equals < 0 ? token : token.slice(0, equals);
+        if (!PRELOAD_FLAGS.has(flag)) {
+          continue;
+        }
+        if (equals < 0) {
+          at += 1;
+        }
+        const value = equals < 0 ? tokens[at] : token.slice(equals + 1);
+        const name = value === undefined ? undefined : packageOfSpecifier(value);
+        if (name !== undefined) {
+          found.add(name);
+        }
+      }
+    }
+  }
+  return found;
+}
+
 /** Whether a path below the target root lies in the directory `dir` below it, `""` being the root. */
 function isInside(path: string, dir: string): boolean {
   return dir === "" || path.startsWith(`${dir}/`);
@@ -976,12 +1068,16 @@ export function dependenciesOf(
       continue;
     }
     const tokens = scriptTokensOf(read.value);
+    const preloads = scriptPreloadsOf(read.value);
     for (const dependency of declaredIn(read.text, read.value, path, scopeOf(path))) {
       const found = installedOf(host, dir, dependency.name);
       if (found === undefined && uninstalledHere.has(dir)) {
         continue;
       }
       declared.push(dependency);
+      if (preloads.has(dependency.name)) {
+        ran.add(declarationKey(dependency));
+      }
       if (found === undefined) {
         continue;
       }

package/src/entry-points.ts

@@ -14,7 +14,6 @@
 import {
   isArrayLiteralExpression,
   isAsExpression,
-  isBinaryExpression,
   isCallExpression,
   isExportAssignment,
   isIdentifier,
@@ -27,7 +26,6 @@ import {
   isPropertyAssignment,
   isSatisfiesExpression,
   isStringLiteral,
-  isTemplateExpression,
   SyntaxKind,
   type Node,
   type SourceFile,
@@ -40,6 +38,7 @@ import {
   type ParseFile,
 } from "./configuration-files.ts";
 import type { Selected } from "./conventions.ts";
+import { buildScriptEntries } from "./build-scripts.ts";
 import { globExpression } from "./glob.ts";
 import type { Host } from "./host.ts";
 import { htmlEntries } from "./html-entries.ts";
@@ -48,6 +47,7 @@ import { dirnamePath, relativePath, resolvePath } from "./paths.ts";
 import { UNANSWERED } from "./query.ts";
 import type { ProjectView } from "./session.ts";
 import type { SourceFiles } from "./source-files.ts";
+import { computedLoadDirectory, leadingLiteral } from "./unseen-loads.ts";
 import { workflowEntries } from "./workflow-steps.ts";
 
 /** Which rule entered a file. */
@@ -56,6 +56,8 @@ export type EntryRule =
   | "configuration-file"
   /** A file a relative string of a configuration module or a JSON configuration file names. */
   | "configuration-string"
+  /** An entry a build script's bundler call names, whose exports the bundle exposes. */
+  | "bundler-entry"
   /** The test runner: its workspace configuration, its setup files and the test files. */
   | "test-runner"
   /** The test files below the browser-test runner's test directory. */
@@ -324,10 +326,7 @@ function configurationEntries(
     strings(dirnamePath(document.path), unselectedIn(document.path, document.strings));
   }
   for (const { file } of outside) {
-    strings(
-      dirnamePath(file.fileName),
-      moduleStrings(file).map((one) => one.text),
-    );
+    strings(dirnamePath(file.fileName), unselected(file));
   }
   return found;
 }
@@ -541,18 +540,6 @@ function workersOf<Brand>(
   return found;
 }
 
-/** The literal text a computed path starts with: a template's head, or a concatenation's first literal. */
-function leadingLiteral(node: Node): string | undefined {
-  const at = unwrapped(node);
-  if (isTemplateExpression(at)) {
-    return at.head.text;
-  }
-  if (isBinaryExpression(at) && at.operatorToken.kind === SyntaxKind.PlusToken) {
-    return literalOf(unwrapped(at.left)) ?? leadingLiteral(at.left);
-  }
-  return undefined;
-}
-
 /** Whether one call is `import.meta.glob(...)`. */
 function isMetaGlob(node: Node): boolean {
   if (!isCallExpression(node) || !isPropertyAccessExpression(node.expression)) {
@@ -579,13 +566,8 @@ function computedImportsOf(file: SourceFile, files: SourceFiles): readonly Entry
   const dir = dirnamePath(file.fileName);
   const found: EntryPoint[] = [];
   const below = (prefix: string): void => {
-    const target = resolvePath(dir, prefix);
-    if (
-      !isModuleRelative(prefix) ||
-      !prefix.endsWith("/") ||
-      target === dir ||
-      relativePath(target, dir) !== undefined
-    ) {
+    const target = computedLoadDirectory(dir, prefix);
+    if (target === undefined) {
       return;
     }
     for (const candidate of files.byName.values()) {
@@ -680,6 +662,9 @@ export function entryPoints<Brand>(
       ...(names === undefined ? {} : { names }),
     });
   }
+  for (const { file, source } of buildScriptEntries(host, targetRoot, files, parse)) {
+    found.push({ file, rule: "bundler-entry", source, exports: true });
+  }
   for (const { file, source } of workflowEntries(host, targetRoot, files)) {
     found.push({ file, rule: "workflow-step", source, exports: true });
   }

package/src/file-facts.ts

@@ -11,6 +11,7 @@ import { packageScope } from "./inventory.ts";
 import { dirnamePath, joinPath, relativePath, resolvePath } from "./paths.ts";
 import { renderRef } from "./ref.ts";
 import type { ProjectView } from "./session.ts";
+import type { UnseenLoad } from "./unseen-loads.ts";
 
 /** A file name the compiler reads as a source file. */
 const SOURCE_FILE = /\.(?:ts|tsx|mts|cts)$/u;
@@ -51,6 +52,8 @@ export interface FileFacts {
   readonly generated?: ReadonlySet<string>;
   /** The property names an `in` expression of a production file tests by a literal. */
   readonly inOperands?: ReadonlySet<string>;
+  /** The loads of production files whose target the analysis cannot resolve. */
+  readonly unseenLoads?: readonly UnseenLoad[];
 }
 
 /** The line of the last character of one text, counted from one; an empty text is one line. */

package/src/finding.ts

@@ -119,6 +119,11 @@ export interface CompletedFinding extends Finding {
   readonly reachabilityClass: Confidence;
   /** The reachability class capped by the code's ceiling. */
   readonly confidence: Confidence;
+  /**
+   * Where test-used code alone lowers the confidence, the one the finding would carry
+   * otherwise, which its component's cap and the dials read.
+   */
+  readonly componentConfidence?: Confidence;
   /**
    * The relation that decided the subject: present on a declaration the sweep judged
    * dead, absent on a live one and on a subject that is no declaration.

package/src/findings/completion.ts

@@ -132,6 +132,34 @@ function reachabilityClasses(input: EmitterInput): (id: string) => Confidence {
   };
 }
 
+/**
+ * Whether one test of dead code references a target symbol that is published API of a run
+ * that declares no consumer, which outside programs the run cannot see may use, so the
+ * target counts as live for the test and the test is no test of dead code.
+ */
+export function testsUnseenAPI(input: EmitterInput): (id: string) => boolean {
+  if (input.boundary.consumers.declared.length > 0) {
+    return () => false;
+  }
+  const union = input.swept.matrix.union;
+  const published = publishedIds(union);
+  return (id) => testTargets(union, id).some((target) => published.has(target));
+}
+
+/** The target symbols one test of dead code references, by id: production declarations the sweep judges. */
+function testTargets(union: Graph, id: string): readonly string[] {
+  return (union.out[union.at(id)] ?? []).flatMap((edge) => {
+    const target = union.symbols[edge.to];
+    const testCode = union.test[edge.to] === true || union.support[edge.to] === true;
+    return target !== undefined &&
+      !testCode &&
+      union.ambient[edge.to] !== true &&
+      union.subject[edge.to] === true
+      ? [target.id]
+      : [];
+  });
+}
+
 /**
  * The confidence ceiling of a test of dead code: the lowest reachability class among the
  * target symbols it references, because its deadness is theirs, whether or not they share
@@ -145,40 +173,59 @@ function testCeilings(
   const tests = new Set(
     input.swept.sweep.candidates.filter((one) => one.testOfDeadCode).map((one) => one.id),
   );
-  return (id) => {
-    let lowest: Confidence = "certain";
-    if (!tests.has(id)) {
-      return lowest;
-    }
-    for (const edge of union.out[union.at(id)] ?? []) {
-      const target = union.symbols[edge.to];
-      const testCode = union.test[edge.to] === true || union.support[edge.to] === true;
-      if (
-        target !== undefined &&
-        !testCode &&
-        union.ambient[edge.to] !== true &&
-        union.subject[edge.to] === true
-      ) {
-        lowest = capped(lowest, classOf(target.id));
-      }
+  return (id) =>
+    tests.has(id)
+      ? testTargets(union, id).reduce<Confidence>(
+          (lowest, target) => capped(lowest, classOf(target)),
+          "certain",
+        )
+      : "certain";
+}
+
+/**
+ * The subjects dead only because production code only tests use is: each declaration the
+ * sweep marks test-used, each `DS1502` file of such code, and each test of dead code every
+ * target of which is one. Nothing they hold references a dead declaration outside them, so
+ * the rest of a component they share is reported without them.
+ */
+function testUsedSubjects(input: EmitterInput): {
+  readonly declarations: ReadonlySet<string>;
+  readonly files: ReadonlySet<string>;
+} {
+  const { matrix, sweep } = input.swept;
+  const union = matrix.union;
+  const used = new Set(sweep.candidates.filter((one) => one.testUsed).map((one) => one.id));
+  for (const test of sweep.candidates.filter((one) => one.testOfDeadCode)) {
+    const targets = testTargets(union, test.id);
+    if (targets.length > 0 && targets.every((target) => used.has(target))) {
+      used.add(test.id);
     }
-    return lowest;
-  };
+  }
+  const files = new Set(
+    union.symbols.flatMap((symbol, at) =>
+      matrix.testUsed[at] === true ? [symbol.position.path] : [],
+    ),
+  );
+  return { declarations: used, files };
 }
 
 /**
  * The ceiling the roots the run found put on one dead subject: a subject other declarations
- * reference, found dead only because no root reaches them, is `probable` unless
- * the configuration declares the roots complete, because a root the analysis cannot see
- * would make it live; every other declaration has none below `certain`.
+ * reference, found dead only because no root reaches them, is `probable` unless the
+ * configuration declares the roots complete and no configuration holding the subject loads
+ * a module the analysis cannot resolve, because a root the analysis cannot see would make
+ * it live; every other declaration has none below `certain`.
  */
 function rootsCeiling(
   input: EmitterInput,
   finding: Finding,
   candidate: Candidate | undefined,
+  configurations: readonly string[],
 ): Confidence {
   const unreachable = candidate?.relation === "reachability" || finding.unreachableOnly === true;
-  return unreachable && !input.config.ts.rootsComplete ? "probable" : "certain";
+  const unseen = new Set((input.files.unseenLoads ?? []).map((load) => load.configuration));
+  const complete = input.config.ts.rootsComplete && !configurations.some((one) => unseen.has(one));
+  return unreachable && !complete ? "probable" : "certain";
 }
 
 /**
@@ -196,9 +243,28 @@ function findingComponents(
       held.set(member, component);
     }
   }
+  const listed = membersListed(swept);
+  return (id) => {
+    const component = held.get(id);
+    return component === undefined
+      ? undefined
+      : {
+          id: component.id,
+          root: component.roots.includes(id),
+          symbolCount: component.members.length,
+          deletableLines: component.deletableLines,
+          ...(cascade === "full" ? { members: listed(component.members) } : {}),
+        };
+  };
+}
+
+/** The members of a component as the run lists them, positioned and in the canonical order. */
+function membersListed(
+  swept: RunSweep,
+): (members: readonly string[]) => readonly PositionedSymbol[] {
   const symbols = new Map(swept.matrix.union.symbols.map((symbol) => [symbol.id, symbol]));
-  const listed = (component: Component): readonly PositionedSymbol[] =>
-    component.members
+  return (members) =>
+    members
       .flatMap((member) => {
         const symbol = symbols.get(member);
         return symbol === undefined
@@ -215,18 +281,6 @@ function findingComponents(
             ];
       })
       .sort((a, b) => byPosition(a.position, b.position));
-  return (id) => {
-    const component = held.get(id);
-    return component === undefined
-      ? undefined
-      : {
-          id: component.id,
-          root: component.roots.includes(id),
-          symbolCount: component.members.length,
-          deletableLines: component.deletableLines,
-          ...(cascade === "full" ? { members: listed(component) } : {}),
-        };
-  };
 }
 
 /**
@@ -321,18 +375,20 @@ export function completed(
   const candidates = new Map(swept.sweep.candidates.map((candidate) => [candidate.id, candidate]));
   const classOf = reachabilityClasses(input);
   const ceilingOf = testCeilings(input, classOf);
+  const testUsed = testUsedSubjects(input);
   const { components, computed, files } = runComponents(swept, findings);
   const componentOf = findingComponents(swept, components, input.config.reporters.cascade);
   const held = new Set(components.filter((one) => one.held).flatMap((one) => one.members));
   // A join keeps its first component's identifier, so a minted one counts past every computed one.
   let minted = computed;
   const dead = new Set(components.map((component) => component.id));
-  const fallingWith = new Map<string, number>();
-  for (const { heldByTests } of swept.sweep.candidates) {
+  const fallingWith = new Map<string, string[]>();
+  for (const { id, heldByTests } of swept.sweep.candidates) {
     if (heldByTests !== undefined) {
-      fallingWith.set(heldByTests, (fallingWith.get(heldByTests) ?? 0) + 1);
+      fallingWith.set(heldByTests, [...(fallingWith.get(heldByTests) ?? []), id]);
     }
   }
+  const listed = membersListed(swept);
 
   const done = findings.map((finding): CompletedFinding => {
     const row = kinds.get(finding.code);
@@ -383,19 +439,50 @@ export function completed(
     let component = found;
     if (component === undefined) {
       minted += 1;
+      const falling = symbol?.kind === "interface" ? fallingWith.get(symbol.id) : undefined;
       component = {
         id: componentId(minted),
         root: true,
-        symbolCount: symbol?.kind === "interface" ? (fallingWith.get(symbol.id) ?? 1) : 1,
+        symbolCount: falling?.length ?? 1,
         deletableLines: 0,
+        ...(input.config.reporters.cascade !== "full"
+          ? {}
+          : falling === undefined
+            ? {
+                members: [
+                  {
+                    ref: finding.symbol.ref,
+                    name: finding.symbol.name,
+                    position: finding.position,
+                  },
+                ],
+              }
+            : { members: listed(falling) }),
       };
     }
     const counts =
       candidate === undefined
         ? union.made[at]
         : { production: candidate.productionRefs, test: candidate.testRefs };
-    const reachabilityClass =
+    const ownClass =
       judged === undefined ? (finding.reachabilityClass ?? "certain") : classOf(judged.id);
+    const used =
+      judged !== undefined
+        ? candidate !== undefined && testUsed.declarations.has(judged.id)
+        : finding.code === FILE_NEVER_IMPORTED && testUsed.files.has(finding.position.path);
+    const reachabilityClass = used && candidate?.testOfDeadCode !== true ? "possible" : ownClass;
+    const configurations =
+      candidate?.configurations ??
+      (judged === undefined && !part
+        ? swept.matrix.configurations
+        : (swept.matrix.heldIn[at] ?? swept.matrix.configurations));
+    const untested = capped(
+      capped(
+        capped(ownClass, row.maxClass),
+        rootsCeiling(input, finding, candidate, configurations),
+      ),
+      judged === undefined ? "certain" : ceilingOf(judged.id),
+    );
     const generated = input.files.generated?.has(finding.position.path) === true;
     const fixability = generated
       ? "none"
@@ -420,20 +507,14 @@ export function completed(
       position: finding.position,
       symbol: finding.symbol,
       reachabilityClass,
-      confidence: capped(
-        capped(capped(reachabilityClass, row.maxClass), rootsCeiling(input, finding, candidate)),
-        judged === undefined ? "certain" : ceilingOf(judged.id),
-      ),
+      confidence: used ? "possible" : untested,
+      ...(used ? { componentConfidence: untested } : {}),
       ...(candidate === undefined ? {} : { livenessRelation: candidate.relation }),
       testOnly: judged !== undefined && counts?.production === 0 && counts.test > 0,
       generated,
       component,
       retainedBy: [],
-      configurations:
-        candidate?.configurations ??
-        (judged === undefined && !part
-          ? swept.matrix.configurations
-          : (swept.matrix.heldIn[at] ?? swept.matrix.configurations)),
+      configurations,
       consumersLoaded: input.boundary.consumers.loaded,
       fixability,
       severity: severityOf(input, finding.code, row.defaultSeverity),
@@ -450,7 +531,7 @@ export function completed(
 /**
  * The findings with every finding of a dead component capped by the lowest confidence
  * among the component's root members, so the minimum confidence reports or withholds a
- * component whole.
+ * component whole but for the findings test-used code lowers on their own.
  */
 function componentCapped(
   findings: readonly CompletedFinding[],
@@ -461,17 +542,29 @@ function componentCapped(
     const { id, root } = finding.component;
     if (root && dead.has(id)) {
       const held = lowest.get(id);
-      lowest.set(id, held === undefined ? finding.confidence : capped(held, finding.confidence));
+      const own = componentConfidenceOf(finding);
+      lowest.set(id, held === undefined ? own : capped(held, own));
     }
   }
   return findings.map((finding) => {
     const cap = lowest.get(finding.component.id);
-    return cap === undefined || RANK[cap] >= RANK[finding.confidence]
-      ? finding
-      : { ...finding, confidence: cap };
+    if (cap === undefined) {
+      return finding;
+    }
+    const own = finding.componentConfidence;
+    return {
+      ...finding,
+      confidence: capped(finding.confidence, cap),
+      ...(own === undefined ? {} : { componentConfidence: capped(own, cap) }),
+    };
   });
 }
 
+/** The confidence a finding gives its component's cap and the dials. */
+function componentConfidenceOf(finding: CompletedFinding): Confidence {
+  return finding.componentConfidence ?? finding.confidence;
+}
+
 /** Whether the dials withhold a finding by its own severity or confidence. */
 function dialed(
   finding: Pick<CompletedFinding, "severity" | "confidence">,
@@ -494,7 +587,11 @@ export function dialsOf(
   const minConfidence = input.config.analysis.minConfidence;
   const components = new Set(
     findings
-      .filter((finding) => finding.component.root && dialed(finding, minConfidence))
+      .filter(
+        (finding) =>
+          finding.component.root &&
+          dialed({ ...finding, confidence: componentConfidenceOf(finding) }, minConfidence),
+      )
       .map((finding) => finding.component.id),
   );
   return {

package/src/findings/intra-function.ts

@@ -42,7 +42,8 @@ type ParameterVerdict =
  * caller may pass a function used as a value more arguments than it declares, so there one
  * a read parameter follows is renamed to an underscore name, which the compilers read as
  * declared unread, and one no read parameter follows is deleted: kept where the call's
- * inference may read its annotation, at `probable` where nothing reads the annotation.
+ * inference may read its annotation, at `probable` where nothing reads the annotation or
+ * where it is a name a contextually typed object pattern binds.
  */
 function parameterVerdict(
   part: PartFact,
@@ -63,7 +64,8 @@ function parameterVerdict(
   if (place?.annotated === "steers") {
     return undefined;
   }
-  return { fix: "delete", confidence: place?.annotated === "free" ? "probable" : "certain" };
+  const unseen = place?.annotated === "free" || place?.contextualPattern === true;
+  return { fix: "delete", confidence: unseen ? "probable" : "certain" };
 }
 
 /**

package/src/findings/reads-and-writes.ts

@@ -8,8 +8,8 @@ import type { Emitter, EmitterInput } from "./emitter.ts";
 /** The codes of this family. */
 type ReadsAndWritesCode = "DS1301" | "DS1302" | "DS1303";
 
-/** The containers whose type parameters `DS1303` reports: a function and a class method. */
-const SIGNATURES: ReadonlySet<string> = new Set(["function", "method"]);
+/** The containers whose type parameters `DS1303` reports: a function, a class method and a type alias. */
+const SIGNATURES: ReadonlySet<string> = new Set(["function", "method", "type"]);
 
 /** What the family reads of one run, indexed by declaration. */
 interface Run {
@@ -225,10 +225,11 @@ function unusedEnumMembers(run: Run): readonly Finding[] {
 }
 
 /**
- * `DS1303`: a type parameter of a function or a class method that neither the
- * declaration's signature nor its body names. A type parameter of a class, an interface,
- * a type alias or a method signature belongs to a type declaration and is never
- * reported, because a phantom parameter makes two instantiations distinct types.
+ * `DS1303`: a type parameter of a function, a class method or a type alias that neither
+ * the declaration's signature nor its body names. An alias names no type of its own, so
+ * a parameter its type never names makes no two instantiations distinct. One of a class,
+ * an interface or a method signature is never reported: a class or an interface merges
+ * only with declarations of the same parameters.
  */
 function unusedTypeParameters(run: Run): readonly Finding[] {
   return unnamed(run, "type-parameter")