@cplieger/deadset-ts 5.2.3 → 6.0.0

package/src/intra-function-parts.ts

@@ -12,8 +12,10 @@ import {
   isBinaryExpression,
   isBlock,
   isBreakStatement,
+  isBindingElement,
   isCallExpression,
   isCaseClause,
+  isCatchClause,
   isClassDeclaration,
   isClassExpression,
   isContinueStatement,
@@ -24,6 +26,7 @@ import {
   isExportSpecifier,
   isExpressionStatement,
   isFunctionDeclaration,
+  isFunctionExpression,
   isHeritageClause,
   isIdentifier,
   isIfStatement,
@@ -35,6 +38,8 @@ import {
   isNamespaceImport,
   isNoSubstitutionTemplateLiteral,
   isNumericLiteral,
+  isObjectBindingPattern,
+  isObjectLiteralExpression,
   isParenthesizedExpression,
   isPrefixUnaryExpression,
   isPropertyAccessExpression,
@@ -50,8 +55,10 @@ import {
   isVoidExpression,
   NodeFlags,
   SyntaxKind,
+  type BindingName,
   type Block,
   type CallExpression,
+  type CatchClause,
   type Identifier,
   type Node,
   type SourceFile,
@@ -81,6 +88,16 @@ export interface PartFact {
   readonly message: string;
   /** Whether the project found the part in use, which takes it out of the answer. */
   readonly used: boolean;
+  /** Where the part is a parameter's name, what a function used as a value decides it by. */
+  readonly parameter?: ParameterPlace;
+}
+
+/** What decides a parameter of a function used as a value: a caller may pass it more arguments. */
+interface ParameterPlace {
+  /** Whether a parameter after this one, which is no binding-pattern name, is read. */
+  readonly beforeARead: boolean;
+  /** Whether no declaration of the inventory declares the function, which is then a value. */
+  readonly inValue: boolean;
 }
 
 /** What one declaration's signature answers to beside its body. */
@@ -119,9 +136,6 @@ const NO_VALUE: ReadonlySet<string> = new Set([
   "Promise<never>",
 ]);
 
-/** The prefix that marks a parameter as unused on purpose, as the compiler's own rule reads it. */
-const UNUSED_PREFIX = "_";
-
 /** The rendered position of one node, from its first token to its last line. */
 function spanOf(file: SourceFile, root: string, node: Node): FindingPosition {
   const start = renderPosition(file, root, node.getStart());
@@ -410,9 +424,31 @@ function readsBinding(
   return at === undefined || at === UNANSWERED || own === UNANSWERED || at === own;
 }
 
+/** A function written as a value that no inventory declaration declares, and what holds it. */
+interface ValueFunction {
+  readonly holder: string;
+  readonly signature: SignatureNode;
+}
+
+/** One name a parameter binds, whole or through a binding pattern. */
+interface ParameterName {
+  readonly name: Identifier;
+  /** The parameter's index in its list. */
+  readonly at: number;
+  readonly pattern: boolean;
+  /** A name beside a rest element of its object pattern: removing it changes what the rest holds. */
+  readonly exempt: boolean;
+}
+
 /** What one file's walk collects before the batch that resolves its names. */
 interface FileWalk {
   readonly declared: Declared[];
+  readonly values: ValueFunction[];
+  readonly catches: {
+    readonly clause: CatchClause;
+    readonly name: Identifier;
+    readonly holder: string;
+  }[];
   readonly blocks: Block[];
   readonly unreachable: { readonly statement: Statement; readonly holder: string }[];
   readonly cases: { readonly clause: Node; readonly text: string; readonly holder: string }[];
@@ -443,6 +479,8 @@ export function projectParts<Brand>(
       const id = held.declarations.get(nodeKey(file, node));
       return id === undefined || kinds.get(id) === "file" ? undefined : id;
     };
+    // A part no declaration holds belongs to the file, which is judged while the file is live.
+    const fileId = held.declarations.get(nodeKey(file, file));
     const holderOf = (node: Node): string | undefined => {
       for (let at = node.parent; at.kind !== SyntaxKind.SourceFile; at = at.parent) {
         const id = declarationAt(at);
@@ -450,9 +488,17 @@ export function projectParts<Brand>(
           return id;
         }
       }
-      return undefined;
+      return fileId;
     };
-    const walk: FileWalk = { declared: [], blocks: [], unreachable: [], cases: [] };
+    const walk: FileWalk = {
+      declared: [],
+      values: [],
+      catches: [],
+      blocks: [],
+      unreachable: [],
+      cases: [],
+    };
+    const covered = new Set<Node>();
     const position = (node: Node): string =>
       positionKey(renderPosition(file, targetRoot, node.getStart()));
 
@@ -483,6 +529,19 @@ export function projectParts<Brand>(
       const signature = id === undefined ? undefined : signatureOf(node);
       if (id !== undefined && signature !== undefined) {
         walk.declared.push({ id, node, signature });
+        covered.add(signature);
+      }
+      const value = covered.has(node) ? undefined : valueSignature(node);
+      const valueHolder = id ?? holderOf(node);
+      if (value !== undefined && valueHolder !== undefined && !isStub(value)) {
+        walk.values.push({ holder: valueHolder, signature: value });
+      }
+      if (isCatchClause(node) && node.variableDeclaration !== undefined) {
+        const name = node.variableDeclaration.name;
+        const holder = holderOf(node);
+        if (isIdentifier(name) && holder !== undefined && silenced === 0) {
+          walk.catches.push({ clause: node, name, holder });
+        }
       }
       if (isCallExpression(node)) {
         const name = calleeName(node);
@@ -532,16 +591,24 @@ export function projectParts<Brand>(
 
     // One batch per file resolves every name a parameter or a local is read through.
     const asked: Identifier[] = [];
-    const readers = new Map<Declared, { names: Identifier[]; uses: Identifier[] }>();
-    for (const one of walk.declared) {
-      const names = one.signature.parameters
-        .map((parameter) => parameter.name)
-        .filter(isIdentifier);
-      const spelled = new Set(names.map((name) => name.text));
-      const uses = identifiersNaming(one.signature, spelled).filter((use) => !names.includes(use));
-      readers.set(one, { names, uses });
-      asked.push(...names, ...uses);
+    const readers = new Map<SignatureNode, { names: ParameterName[]; uses: Identifier[] }>();
+    for (const signature of [
+      ...walk.declared.map((one) => one.signature),
+      ...walk.values.map((one) => one.signature),
+    ]) {
+      const names = parameterNames(signature);
+      const declaredNames = new Set<Node>(names.map((one) => one.name));
+      const spelled = new Set(names.map((one) => one.name.text));
+      const uses = identifiersNaming(signature, spelled).filter((use) => !declaredNames.has(use));
+      readers.set(signature, { names, uses });
+      asked.push(...names.map((one) => one.name), ...uses);
     }
+    const caught = walk.catches.map(({ clause, name }) =>
+      identifiersNaming(clause.block, new Set([name.text])),
+    );
+    walk.catches.forEach(({ name }, at) => {
+      asked.push(name, ...(caught[at] ?? []));
+    });
     const stores = walk.blocks.map((block) => localsOf(block));
     for (const store of stores) {
       asked.push(...store.flatMap((local) => [local.name, ...local.uses]));
@@ -555,9 +622,30 @@ export function projectParts<Brand>(
         stub: isStub(one.signature),
         fixed: hierarchyFixes(one.node, extended),
       });
-      const { uses } = readers.get(one) ?? { uses: [] };
-      parts.push(...parameterParts(file, targetRoot, one, uses, ids));
+      const reader = readers.get(one.signature);
+      if (reader !== undefined) {
+        parts.push(...parameterParts(file, targetRoot, one.id, one.signature, reader, ids, false));
+      }
+    }
+    for (const one of walk.values) {
+      const reader = readers.get(one.signature);
+      if (reader !== undefined) {
+        parts.push(
+          ...parameterParts(file, targetRoot, one.holder, one.signature, reader, ids, true),
+        );
+      }
     }
+    walk.catches.forEach(({ name, holder }, at) => {
+      parts.push({
+        code: DEAD_STORE,
+        declaration: holder,
+        kind: "store",
+        name: name.text,
+        position: spanOf(file, targetRoot, name),
+        message: `value written to ${name.text} is never read`,
+        used: (caught[at] ?? []).some((use) => readsBinding(use, name, ids)),
+      });
+    });
     walk.blocks.forEach((block, at) => {
       const holder = holderOf(block);
       if (holder !== undefined) {
@@ -592,41 +680,107 @@ export function projectParts<Brand>(
   return { parts, signatures, calls, specifiers };
 }
 
-/** Each named parameter of one function and whether the function reads it. */
+/**
+ * A function written in place that no declaration declares: an arrow, a function
+ * expression, a nested function declaration, or a method of an object literal.
+ */
+function valueSignature(node: Node): SignatureNode | undefined {
+  if (isArrowFunction(node) || isFunctionExpression(node)) {
+    return node;
+  }
+  if (isFunctionDeclaration(node)) {
+    return node.body === undefined ? undefined : node;
+  }
+  return isMethodDeclaration(node) &&
+    node.body !== undefined &&
+    isObjectLiteralExpression(node.parent)
+    ? node
+    : undefined;
+}
+
+/**
+ * Every name one function's parameters bind, a binding pattern's names one by one. A
+ * `this` parameter receives no argument and a decorated one is read by its decorator, so
+ * neither binds a subject.
+ */
+function parameterNames(signature: SignatureNode): ParameterName[] {
+  const found: ParameterName[] = [];
+  const patternNames = (pattern: BindingName, at: number): void => {
+    if (isIdentifier(pattern)) {
+      found.push({ name: pattern, at, pattern: true, exempt: false });
+      return;
+    }
+    const rest =
+      isObjectBindingPattern(pattern) &&
+      pattern.elements.some((element) => element.dotDotDotToken !== undefined);
+    for (const element of pattern.elements) {
+      if (!isBindingElement(element) || element.name === undefined) {
+        continue;
+      }
+      if (isIdentifier(element.name)) {
+        const exempt = rest && element.dotDotDotToken === undefined;
+        found.push({ name: element.name, at, pattern: true, exempt });
+      } else {
+        patternNames(element.name, at);
+      }
+    }
+  };
+  signature.parameters.forEach((parameter, at) => {
+    const name = parameter.name;
+    if (
+      ((parameter as { readonly modifiers?: readonly Node[] }).modifiers ?? []).some(isDecorator)
+    ) {
+      return;
+    }
+    if (isIdentifier(name)) {
+      if (name.text !== "this") {
+        found.push({ name, at, pattern: false, exempt: false });
+      }
+      return;
+    }
+    patternNames(name, at);
+  });
+  return found;
+}
+
+/**
+ * Each name one function's parameters bind and whether the function reads it. A binding
+ * pattern counts as read where its function reads any name it binds.
+ */
 function parameterParts(
   file: SourceFile,
   root: string,
-  one: Declared,
-  uses: readonly Identifier[],
+  declaration: string,
+  signature: SignatureNode,
+  reader: { readonly names: readonly ParameterName[]; readonly uses: readonly Identifier[] },
   ids: ReadonlyMap<Node, Answer<number>>,
+  inValue: boolean,
 ): PartFact[] {
-  const signature = one.signature;
   // A function that reads `arguments` reads every parameter by position.
   const readsArguments =
     !isArrowFunction(signature) && identifiersNaming(signature, new Set(["arguments"])).length > 0;
+  const read = reader.names.map(
+    ({ name }) =>
+      readsArguments ||
+      reader.uses.some((use) => use.text === name.text && readsBinding(use, name, ids)),
+  );
+  const lastRead = Math.max(-1, ...reader.names.filter((_, at) => read[at]).map((one) => one.at));
   const found: PartFact[] = [];
-  for (const parameter of signature.parameters) {
-    const name = parameter.name;
-    if (
-      !isIdentifier(name) ||
-      name.text === "this" ||
-      name.text.startsWith(UNUSED_PREFIX) ||
-      ((parameter as { readonly modifiers?: readonly Node[] }).modifiers ?? []).some(isDecorator)
-    ) {
-      continue;
+  reader.names.forEach(({ name, at, pattern, exempt }, index) => {
+    if (exempt) {
+      return;
     }
     found.push({
       code: UNUSED_PARAMETER,
-      declaration: one.id,
+      declaration,
       kind: "parameter",
       name: name.text,
       position: spanOf(file, root, name),
       message: `parameter ${name.text} is never read in the body`,
-      used:
-        readsArguments ||
-        uses.some((use) => use.text === name.text && readsBinding(use, name, ids)),
+      used: read[index] === true,
+      parameter: { beforeARead: !pattern && at < lastRead, inValue },
     });
-  }
+  });
   return found;
 }
 
@@ -823,6 +977,8 @@ export interface IntraFunctionFacts {
   readonly parts: readonly PartFact[];
   /** The declarations whose signature is free to change. */
   readonly free: ReadonlySet<string>;
+  /** The declarations whose signature is free but for a use as a value. */
+  readonly freeButValued: ReadonlySet<string>;
   /**
    * The declarations every reference of which is a call in the loaded program that
    * discards the call's value, with at least one such call.
@@ -882,8 +1038,13 @@ export function intraFunctionFacts(
       .map((one) => one.declaration)
       .filter((id) => !fixed.has(id) && !exempted.has(id) && !valued.has(id)),
   );
+  const freeButValued = new Set(
+    signatures
+      .map((one) => one.declaration)
+      .filter((id) => !fixed.has(id) && !exempted.has(id) && valued.has(id)),
+  );
   const discardedEverywhere = new Set(
     [...called].filter(([id, all]) => all && !valued.has(id)).map(([id]) => id),
   );
-  return { parts: [...parts.values()], free, discardedEverywhere };
+  return { parts: [...parts.values()], free, freeButValued, discardedEverywhere };
 }

package/src/inventory.ts

@@ -20,6 +20,7 @@ import {
   isPropertyDeclaration,
   isPropertySignatureDeclaration,
   isSetAccessorDeclaration,
+  isStringLiteral,
   isTypeAliasDeclaration,
   isTypeLiteralNode,
   isUnionTypeNode,
@@ -178,6 +179,8 @@ export interface Inventory {
    * component, its declared name where that differs, and a type parameter's own name.
    */
   readonly byName: ReadonlyMap<string, readonly string[]>;
+  /** Each `declare module` declaration whose name is a string literal, by id, to that name. */
+  readonly modules: ReadonlyMap<string, string>;
 }
 
 /** A declaration under construction, before its reference is rendered. */
@@ -532,6 +535,7 @@ export function inventory<Brand>(
   const exportScopes: ExportScope[] = [];
   const containers: Container[] = [];
   const starReExports: string[] = [];
+  const modules: (readonly [Building, string])[] = [];
   let outsideOwnFiles = 0;
 
   const keep = (record: Building): Building => {
@@ -737,6 +741,9 @@ export function inventory<Brand>(
         localName: undefined,
       });
       exportScopes.push({ owner: record, nameNode: node.name });
+      if (isStringLiteral(node.name)) {
+        modules.push([record, node.name.text]);
+      }
       const body = node.body;
       if (body === undefined) {
         return;
@@ -1022,6 +1029,7 @@ export function inventory<Brand>(
       .filter((symbol) => underUnanswered(byId.get(symbol.id), unansweredOwners))
       .map((symbol) => symbol.id),
     byName: namesOf(building),
+    modules: new Map(modules.map(([record, name]) => [positionKey(record.position), name])),
   };
 }
 

package/src/kinds.ts

@@ -101,9 +101,9 @@ const ROWS: readonly KindRow[] = [
     code: "DS1101",
     name: "unnecessary-export",
     languages: ["go", "ts"],
-    rule: "An exported symbol whose every reference is inside the symbol's own package or module, reported as a candidate for unexporting. The subject is a package-level declaration or a method, and three subjects are excluded: an interface method, whose exportedness is the contract of the interface that declares it; a struct field, which an encoder reads by name; and a method that satisfies an interface some symbol uses as a type, which cannot be unexported without its type ceasing to satisfy that interface. The finding names the narrower visibility the references support. A declared cross-language edge counts as an out-of-package reference; where the edge's other side is unknown to the analyzer the finding is emitted pending.",
+    rule: "An exported symbol whose every reference is inside the symbol's own package or module, reported as a candidate for unexporting. The subject is a package-level declaration or a method. Three subjects are excluded. An interface method is excluded because its exportedness is the contract of the interface that declares it. A struct field is excluded because an encoder reads it by name. A method that satisfies an interface some symbol uses as a type is excluded because it cannot be unexported without its type ceasing to satisfy that interface. The finding names the narrower visibility the references support. A declared cross-language edge counts as an out-of-package reference. Where the edge's other side is unknown to the analyzer, the finding is emitted pending.",
     precondition:
-      "Closed world only. Reported always for a main package and an internal/ directory tree, and for a published package only when the configuration declares the consumer set complete and every declared consumer loads. A library with no consumer loaded and no complete consumer set declared gets this finding on its internal/ tree and its main packages and never on its published API. A symbol the rule of DS1301 holds for is not reported under this code, whatever severity the configuration gives DS1301, because the write-only finding names the defect to fix first. A type that a parameter or a result of an exported function or method of its own package names is not reported when a reference from outside the package references that function or method, because the caller holds values of the type, and unexporting it would leave an exported signature naming a type its callers cannot name.",
+      "Closed world only. A Go main package, and an internal/ directory tree for importers outside its parent, are closed worlds whatever the configuration declares, because no other program can import them, so this finding is reported there always. A published package is a closed world only when the configuration declares the consumer set complete and every declared consumer loads. A library with no consumer loaded and no complete consumer set declared gets this finding on its internal/ tree and its main packages and never on its published API. A symbol the rule of DS1301 holds for is not reported under this code, whatever severity the configuration gives DS1301, because the write-only finding names the defect to fix first. A type that a parameter or a result of an exported function or method of its own package names is not reported when a reference from outside the package references that function or method, because the caller holds values of the type, and unexporting it would leave an exported signature naming a type its callers cannot name.",
     defaultSeverity: "warn",
     maxClass: "certain",
     fixability: "narrowable",
@@ -113,7 +113,7 @@ const ROWS: readonly KindRow[] = [
     code: "DS1102",
     name: "unnecessary-exposure",
     languages: ["go"],
-    rule: "An exported symbol of a non-internal package whose every reference is inside the target module, reported as a candidate for relocation behind an internal boundary. The subject is a package-level declaration or a method, and three subjects are excluded: an interface method, whose exportedness is the contract of the interface that declares it; a struct field, which an encoder reads by name; and a method that satisfies an interface some symbol uses as a type, which cannot be unexported without its type ceasing to satisfy that interface. The finding names the narrower visibility the references support. A declared cross-language edge counts as an out-of-package reference; where the edge's other side is unknown to the analyzer the finding is emitted pending.",
+    rule: "An exported symbol of a non-internal package whose every reference is inside the target module, reported as a candidate for relocation behind an internal boundary. The subject is a package-level declaration or a method. Three subjects are excluded. An interface method is excluded because its exportedness is the contract of the interface that declares it. A struct field is excluded because an encoder reads it by name. A method that satisfies an interface some symbol uses as a type is excluded because it cannot be unexported without its type ceasing to satisfy that interface. The finding names the narrower visibility the references support. A declared cross-language edge counts as an out-of-package reference. Where the edge's other side is unknown to the analyzer, the finding is emitted pending.",
     precondition:
       "Closed world only. Reported always for a main package and an internal/ directory tree, and for a published package only when the configuration declares the consumer set complete and every declared consumer loads. A library with no consumer loaded and no complete consumer set declared gets this finding on its internal/ tree and its main packages and never on its published API. A symbol the rule of DS1301 holds for is not reported under this code, whatever severity the configuration gives DS1301, because the write-only finding names the defect to fix first. A type that a parameter or a result of an exported function or method of its own package names is not reported when a reference from outside the target module references that function or method, because the caller holds values of the type, and moving it behind an internal boundary would leave an exported signature naming a type its callers cannot name.",
     defaultSeverity: "warn",
@@ -137,7 +137,7 @@ const ROWS: readonly KindRow[] = [
     languages: ["ts"],
     rule: "An exported declaration used only inside its own file, reported as a candidate for removing the export keyword. The finding names the narrower visibility the references support.",
     precondition:
-      "Closed world only. Reported in a file that is not an entry file and that either belongs to a project whose consumer set the configuration declares complete or is reached by no manifest export. A declared cross-language edge counts as a reference from outside the file; where the edge's other side is unknown to the analyzer the finding is emitted pending. A symbol the rule of DS1301 holds for is not reported under this code, whatever severity the configuration gives DS1301, because the write-only finding names the defect to fix first.",
+      "Closed world only. Reported in a file that is not an entry file and that either belongs to a project whose consumer set the configuration declares complete or is reached by no manifest export. A declared cross-language edge counts as a reference from outside the file. Where the edge's other side is unknown to the analyzer, the finding is emitted pending. A symbol the rule of DS1301 holds for is not reported under this code, whatever severity the configuration gives DS1301, because the write-only finding names the defect to fix first.",
     defaultSeverity: "warn",
     maxClass: "certain",
     fixability: "narrowable",
@@ -157,9 +157,9 @@ const ROWS: readonly KindRow[] = [
     code: "DS1203",
     name: "uncalled-interface-method",
     languages: ["go", "ts"],
-    rule: "An interface method that no call site invokes or selects through the interface, whatever the number of implementations. The finding names the concrete implementations and their positions.",
+    rule: "An interface method that no call site invokes or selects through the interface, whatever the number of implementations. The finding names the concrete implementations and their positions. Each method that implements it and that nothing else keeps is reported under the code its own references select. Such a method counts as referenced by the interface method alone, so it belongs to this finding's dead component, whose root member is the interface method.",
     precondition:
-      "Exempt: in Go, every method of an interface that declares an unexported method, the sum-type shape whose method set exists to restrict the implementors, a shape a TypeScript interface cannot take because it declares no member less visible than itself; and, in both languages, every marker method, an interface method whose every implementation carries an empty body.",
+      "In Go, every method of an interface that declares an unexported method is exempt. That is the sum-type shape, whose method set exists to restrict the implementors, and a TypeScript interface cannot take it because it declares no member less visible than itself. In both languages, every marker method is exempt, an interface method whose every implementation carries an empty body.",
     defaultSeverity: "warn",
     maxClass: "certain",
     fixability: "manual",
@@ -213,7 +213,7 @@ const ROWS: readonly KindRow[] = [
     languages: ["go", "ts"],
     rule: "A source file no configuration in the build matrix builds. On the Go side the finding names the build constraint that excluded the file. A file whose build constraint is the ignore tag is never reported: the toolchain applies no build constraint to a file named on its own command line, so that tag is the toolchain's convention for a file built by hand. A file any other custom tag excludes is reported under a matrix the configuration declares complete, because completeness is the maintainer's assertion that the listed configurations are every one the target builds, and a configuration the maintainer builds by hand belongs in that list.",
     precondition:
-      'Reported only when the configuration declares the build matrix complete, and never for a file the toolchain ignored solely because it imports "C" under a build with cgo disabled; such a file is recorded as excluded by cgo rather than as never built.',
+      'Reported only when the configuration declares the build matrix complete, and never for a file the toolchain ignored solely because it imports "C" under a build with cgo disabled. Such a file is recorded as excluded by cgo rather than as never built.',
     defaultSeverity: "deny",
     maxClass: "certain",
     fixability: "deletable",
@@ -235,7 +235,7 @@ const ROWS: readonly KindRow[] = [
     languages: ["go", "ts"],
     rule: "A directly declared dependency that no import in the target needs. On the Go side, a direct require whose module provides no package any target package or test variant imports. On the TypeScript side, a manifest dependency, development dependency or peer dependency the project's import closure does not need. A deletion finding whose fix would remove the last use of a dependency names that dependency.",
     precondition:
-      "On the Go side the rule is the semantics of `go mod tidy -diff` exactly: a requirement marked indirect is never reported, because it exists to pin a transitive version and removing it changes the build list. On the TypeScript side the import closure is the files of the run's projects, and three more dependencies are needed: one whose installed manifest declares a command, because a command is run by name rather than imported; one that the installed manifest of a needed dependency declares as a peer and does not mark optional; and, to a fixpoint, the required peers of every dependency so held. An installed manifest is the package's manifest in the nearest node_modules directory at or above the target, and a dependency with none is decided by the import closure alone.",
+      "On the Go side the rule is the semantics of `go mod tidy -diff` exactly: a requirement marked indirect is never reported, because it exists to pin a transitive version and removing it changes the build list. On the TypeScript side the import closure is the files of the run's projects, and four more dependencies are needed. The first is one whose installed manifest declares a command, because a command is run by name rather than imported. The second is one that the installed manifest of a needed dependency declares as a peer and does not mark optional. The third is every required peer of a dependency so held, to a fixpoint. The fourth is one that a string names under a manifest key of an applied convention row, as grammar/analysis.md states. An installed manifest is the package's manifest in the nearest node_modules directory at or above the target, and a dependency with none is decided by the import closure alone.",
     defaultSeverity: "deny",
     maxClass: "certain",
     fixability: "manual",
@@ -247,7 +247,7 @@ const ROWS: readonly KindRow[] = [
     languages: ["go"],
     rule: "A replace directive whose target module is absent from the build list, the one case in which the directive is exactly a no-op.",
     precondition:
-      "Only a replace whose target is absent from the build list. No other module-file directive is reported: not an exclude directive, because not selected is a counterfactual about a resolution that did not happen; not a workspace use entry and not a tool directive, because each is an external entry point whose invocation lives outside anything the analysis reads.",
+      "Only a replace whose target is absent from the build list. No other module-file directive is reported. An exclude directive is not, because not selected is a counterfactual about a resolution that did not happen. A workspace use entry and a tool directive are not, because each is an external entry point whose invocation lives outside anything the analysis reads.",
     defaultSeverity: "warn",
     maxClass: "certain",
     fixability: "deletable",
@@ -267,7 +267,7 @@ const ROWS: readonly KindRow[] = [
     code: "DS1702",
     name: "unscoped-ignore-entry",
     languages: ["go", "ts"],
-    rule: "An ignore-file entry or a baseline row that names a symbol and no file path. The entry is reported rather than matched, so a bare name cannot mask a match anywhere else in the project; the inline directive is scoped by its position and cannot be unscoped.",
+    rule: "An ignore-file entry or a baseline row that names a symbol and no file path. The entry is reported rather than matched, so a bare name cannot mask a match anywhere else in the project. The inline directive is scoped by its position and cannot be unscoped.",
     defaultSeverity: "deny",
     maxClass: "certain",
     fixability: "none",
@@ -319,7 +319,7 @@ const ROWS: readonly KindRow[] = [
     languages: ["go", "ts"],
     rule: "A parameter with no reference inside its function body, on a function whose signature is free to change.",
     precondition:
-      "The signature must be free, defined as follows: the function is not a method retained by interface satisfaction, is not used as a value, is not a go:linkname or cgo target, is not a function the Go test driver runs (a test, benchmark or fuzz test of a test file, or TestMain), and is not a stub whose body is empty or only panics. A parameter its body never names is dead whatever the callers, so a published declaration of a library is reported too, with the fixability the vocabulary gives the kind: the signature change is a breaking change.",
+      "The signature must be free, defined as follows: the function is not a method retained by interface satisfaction, is not used as a value, is not a go:linkname or cgo target, is not a function the Go test driver runs (a test, benchmark or fuzz test of a test file, or TestMain), and is not a stub whose body is empty or only panics. A parameter its body never names is dead whatever the callers, so a published declaration of a library is reported too, with the fixability the vocabulary gives the kind: the signature change is a breaking change. In TypeScript a caller may pass a function used as a value more arguments than it declares parameters, so in such a function whose signature is free but for that use, a parameter its body never reads is reported when its body reads no parameter after it, and an unread parameter before the last read one is not. A TypeScript parameter that is a binding pattern is judged by the names it binds: each name the body never reads is reported wherever the pattern stands, because removing it from the pattern moves no argument, except a name beside a rest element of the same object pattern, whose removal changes what that element holds, and the pattern counts as a read parameter when the body reads any name it binds. A rest parameter is judged as the last parameter. A TypeScript `this` parameter declares the type of `this` and receives no argument, so it is never reported. No name exempts a parameter. A TypeScript parameter whose name starts with an underscore is judged as any other is, and a Go parameter named by the blank identifier declares no name a body could read and is never reported.",
     defaultSeverity: "warn",
     maxClass: "certain",
     fixability: "manual",
@@ -367,11 +367,13 @@ const ROWS: readonly KindRow[] = [
     name: "dead-store",
     languages: ["go", "ts"],
     rule: "A write to a local variable with no read before the next write to it or the end of its scope, computed on the same read-and-write classification the write-only-symbol kind uses. The finding names the write position.",
+    precondition:
+      "In TypeScript the binding of a catch clause is a local variable the clause writes when it catches, so a binding that is a name and that the clause's block never reads is a dead store, positioned at the binding: the clause written with no binding behaves the same.",
     defaultSeverity: "deny",
     maxClass: "certain",
     fixability: "deletable",
     fixed: false,
-    overlap: ["eslint no-useless-assignment"],
+    overlap: ["eslint no-useless-assignment", "@typescript-eslint/no-unused-vars"],
   },
   {
     code: "DS1809",

package/src/matrix.ts

@@ -10,7 +10,14 @@ import type { InventorySymbol } from "./inventory.ts";
 import { byPosition } from "./position.ts";
 import type { Reference } from "./references.ts";
 import type { Root } from "./roots.ts";
-import { sweep, type Candidate, type Liveness, type Relation, type SweepInput } from "./sweep.ts";
+import {
+  reachedWithTheTests,
+  sweep,
+  type Candidate,
+  type Liveness,
+  type Relation,
+  type SweepInput,
+} from "./sweep.ts";
 
 /** What the passes answered for one configuration of the run. */
 export interface Configured {
@@ -62,6 +69,12 @@ export interface MatrixCandidate extends Candidate {
    * declaration it contains is a member of a dead component.
    */
   readonly heldByTests: string | undefined;
+  /**
+   * Whether a test file declares it, no test of dead code, and the run that counts test
+   * references does not reach it: it is reported as a production declaration of its
+   * shape nothing references would be.
+   */
+  readonly unreferencedTest: boolean;
 }
 
 /** One run's sweep. */
@@ -186,32 +199,61 @@ export function sweepMatrix(matrix: Matrix, input: SweepInput): SweepResult {
   const dead = union.symbols.map(() => false);
   const testOfDeadCode = union.symbols.map(() => false);
   const heldBy: (string | undefined)[] = union.symbols.map(() => undefined);
-  const candidates: MatrixCandidate[] = [];
-  union.symbols.forEach((symbol, at) => {
+  const unreferencedTest = union.symbols.map(() => false);
+  const testReached = reachedWithTheTests(union, [
+    ...input.marked,
+    ...(input.exempt ?? []).map((record) => record.id),
+    ...(input.unanswered ?? []),
+  ]);
+  const judged = union.symbols.map((symbol, at): readonly Candidate[] | undefined => {
     const held = matrix.heldIn[at] ?? [];
     const found = held.map((configuration) => byConfiguration.get(configuration)?.get(symbol.id));
-    if (held.length === 0 || found.some((candidate) => candidate === undefined)) {
+    return held.length === 0 || found.some((candidate) => candidate === undefined)
+      ? undefined
+      : found.filter((candidate): candidate is Candidate => candidate !== undefined);
+  });
+  // A configuration that does not hold a test's subject's caller finds the subject dead,
+  // so a test is of dead code only where every production subject it names is dead in
+  // every configuration that holds it.
+  const subjectsDead = (at: number): boolean =>
+    (union.out[at] ?? []).every(
+      (edge) =>
+        union.test[edge.to] === true ||
+        union.support[edge.to] === true ||
+        union.subject[edge.to] !== true ||
+        judged[edge.to] !== undefined,
+    );
+  const candidates: MatrixCandidate[] = [];
+  union.symbols.forEach((symbol, at) => {
+    const all = judged[at];
+    if (all === undefined) {
       return;
     }
-    const all = found.filter((candidate): candidate is Candidate => candidate !== undefined);
-    const admitted = all.every((candidate) => candidate.testOfDeadCode);
+    const held = matrix.heldIn[at] ?? [];
+    const admitted = all.every((candidate) => candidate.testOfDeadCode) && subjectsDead(at);
     const testRefs = union.made[at]?.test ?? 0;
     const heldByTests =
       heldBy[union.parent[at] ?? OUTSIDE] ??
       (union.support[at] === true && testRefs > 0 && !admitted ? symbol.id : undefined);
+    const unreferenced = union.test[at] === true && !admitted && testReached[at] !== true;
     dead[at] = true;
     testOfDeadCode[at] = admitted;
     heldBy[at] = heldByTests;
+    unreferencedTest[at] = unreferenced;
+    const productionRefs = union.made[at]?.production ?? 0;
+    const counted = all.every((candidate) => candidate.relation === "reference-counting");
     candidates.push({
       id: symbol.id,
-      productionRefs: union.made[at]?.production ?? 0,
+      productionRefs,
       testRefs,
-      relation: all.every((candidate) => candidate.relation === "reference-counting")
+      // The run that judges a test-file declaration counts its test references.
+      relation: (unreferenced ? productionRefs + testRefs === 0 : counted)
         ? "reference-counting"
         : "reachability",
       testOfDeadCode: admitted,
       configurations: held,
       heldByTests,
+      unreferencedTest: unreferenced,
     });
   });
 
@@ -222,6 +264,7 @@ export function sweepMatrix(matrix: Matrix, input: SweepInput): SweepResult {
       union,
       dead.map((one, at) => one && heldBy[at] === undefined),
       testOfDeadCode,
+      unreferencedTest,
     ),
   };
 }