@cplieger/deadset-ts 5.2.3 → 6.0.1

package/src/findings/emitters.ts

@@ -1,6 +1,8 @@
+import type { Confidence } from "../config.ts";
 import { evaluateEdges, type EdgeEvaluation } from "../edges.ts";
 import type { CompletedFinding } from "../finding.ts";
 import { liveFilesAt } from "../matrix.ts";
+import { declarationKey } from "../ref.ts";
 import { ledgerOf, type Dials, type Ledger, type SuppressionRecord } from "../suppress.ts";
 import { insideSkipped } from "../type-errors.ts";
 import { completed, dialsOf, reportable } from "./completion.ts";
@@ -27,10 +29,10 @@ export const EMITTERS: Emitters = new Map<string, Emitter>([
 ]);
 
 /**
- * The references of every declaration an unanswered question could have kept live, which
- * the run reports nothing about: a finding about one would be computed from the gap.
+ * The keys of every declaration an unanswered question could have kept live, which the run
+ * reports nothing about: a finding about one would be computed from the gap.
  */
-function heldRefs(input: EmitterInput): ReadonlySet<string> {
+function heldKeys(input: EmitterInput): ReadonlySet<string> {
   const held = new Set(input.swept.heldByUnanswered);
   if (held.size === 0) {
     return held;
@@ -38,16 +40,16 @@ function heldRefs(input: EmitterInput): ReadonlySet<string> {
   return new Set(
     input.swept.matrix.union.symbols
       .filter((symbol) => held.has(symbol.id))
-      .map((symbol) => symbol.ref),
+      .map((symbol) => declarationKey(symbol.ref, symbol.position.path)),
   );
 }
 
 /**
- * The references of every top-level declaration of a live component file. The file's
+ * The keys of every top-level declaration of a live component file. The file's
  * markup may use each of them, which no analysis of the markup can rule out, so the run
  * reports nothing about one while the file is live.
  */
-function markupRefs(input: EmitterInput): ReadonlySet<string> {
+function markupKeys(input: EmitterInput): ReadonlySet<string> {
   const { swept } = input;
   if (swept.componentFiles.length === 0) {
     return new Set();
@@ -60,7 +62,7 @@ function markupRefs(input: EmitterInput): ReadonlySet<string> {
   return new Set(
     swept.matrix.union.symbols
       .filter((symbol) => live.has(symbol.parent))
-      .map((symbol) => symbol.ref),
+      .map((symbol) => declarationKey(symbol.ref, symbol.position.path)),
   );
 }
 
@@ -82,8 +84,13 @@ export interface DecidedFindings {
   readonly ledger: Ledger<CompletedFinding>;
   /** Every finding a record could name: the run's with no mark, then the run's as swept. */
   readonly would: readonly CompletedFinding[];
+  /** The findings the minimum confidence withheld, by confidence. */
+  readonly withheld: Withheld;
 }
 
+/** How many findings the minimum confidence withheld at each confidence. */
+export type Withheld = Readonly<Record<Confidence, number>>;
+
 /** Every family's findings over one sweep, and those of any further emitter, completed by one step. */
 function completedOver(
   input: EmitterInput,
@@ -116,12 +123,12 @@ function dialsOver(
 }
 
 /**
- * Every finding of one run swept under its suppressions' marks, decided in one pass: every
- * family's findings completed by one step, so every component number is minted once, a
- * pending finding's among them; the finding each record claims withheld, whatever its
- * kind; the rest withheld by the dials, so a root one family reports withholds what
- * another family reports in its component; and every declared edge evaluated over what
- * remains, so a finding it holds pending is in its evaluation and nowhere else.
+ * Every finding of one run swept under its suppressions' marks, decided in one pass: each
+ * family's findings completed by one step, so every component number is minted once, the
+ * finding each record claims withheld, the rest withheld by the dials, so a root one family
+ * reports withholds what another reports in its component, and every declared edge
+ * evaluated over what remains, so a pending finding is in its evaluation alone. What the
+ * minimum confidence withheld is what the same decision at the lowest minimum adds.
  */
 export function decidedFindings(
   input: EmitterInput,
@@ -131,26 +138,81 @@ export function decidedFindings(
   const unmarked =
     suppressed.records.length === 0 ? [] : completedOver(suppressed.unmarked, fallenMembers);
   const would = [...unmarked, ...found];
+  const decided = dialledOver(input, suppressed, found, unmarked);
+  const shown =
+    input.config.analysis.minConfidence === "possible"
+      ? decided
+      : dialledOver(
+          atPossible(input),
+          {
+            unmarked: atPossible(suppressed.unmarked),
+            records: suppressed.records,
+          },
+          found,
+          unmarked,
+        );
+  return { ...decided, would, withheld: withheldOf(decided.findings, shown.findings) };
+}
+
+/** The run's input with the minimum confidence at its lowest, which withholds nothing. */
+function atPossible(input: EmitterInput): EmitterInput {
+  const { config } = input;
+  return {
+    ...input,
+    config: { ...config, analysis: { ...config.analysis, minConfidence: "possible" } },
+  };
+}
+
+/**
+ * The run's completed findings decided under its dials: the finding each record claims
+ * withheld, the rest withheld by the dials, and every declared edge evaluated over what
+ * remains.
+ */
+function dialledOver(
+  input: EmitterInput,
+  suppressed: Suppressed,
+  found: readonly CompletedFinding[],
+  unmarked: readonly CompletedFinding[],
+): Omit<DecidedFindings, "would" | "withheld"> {
+  const would = [...unmarked, ...found];
   const ledger = ledgerOf(suppressed.records, would, dialsOver(input, found, suppressed, unmarked));
-  const unanswered = heldRefs(input);
-  const markup = markupRefs(input);
+  const unanswered = heldKeys(input);
+  const markup = markupKeys(input);
   const kept = reportable(
     input,
-    found.filter(
-      (finding) =>
+    found.filter((finding) => {
+      const key = declarationKey(finding.symbol.ref, finding.position.path);
+      return (
         !ledger.withheld(finding) &&
-        !unanswered.has(finding.symbol.ref) &&
-        !markup.has(finding.symbol.ref) &&
-        !insideSkipped(input.swept.skipped, finding.position),
-    ),
+        !unanswered.has(key) &&
+        !markup.has(key) &&
+        !insideSkipped(input.swept.skipped, finding.position)
+      );
+    }),
   );
   const evaluated = evaluateEdges(kept, input.boundary.edges, input.swept.matrix.union.symbols);
-  return {
-    findings: evaluated.findings,
-    evaluations: evaluated.evaluations,
-    ledger,
-    would,
-  };
+  return { findings: evaluated.findings, evaluations: evaluated.evaluations, ledger };
+}
+
+/** The findings the lowest minimum would report that the run does not, counted by confidence. */
+function withheldOf(
+  reported: readonly CompletedFinding[],
+  shown: readonly CompletedFinding[],
+): Withheld {
+  const kept = new Set(reported.map(findingKey));
+  const counts = { certain: 0, probable: 0, possible: 0 };
+  for (const finding of shown) {
+    if (!kept.has(findingKey(finding))) {
+      counts[finding.confidence] += 1;
+    }
+  }
+  return counts;
+}
+
+/** A finding's identity across two decisions of one run: its position, code and subject. */
+function findingKey(finding: CompletedFinding): string {
+  const { path, line, column } = finding.position;
+  return JSON.stringify([path, line, column, finding.code, finding.symbol.ref]);
 }
 
 /** Every finding the run reports, each family's in table order. */

package/src/findings/interfaces.ts

@@ -1,7 +1,7 @@
 import type { Finding, FindingPosition, PositionedSymbol } from "../finding.ts";
 import type { InventorySymbol } from "../inventory.ts";
 import { byPosition } from "../position.ts";
-import type { Candidate } from "../sweep.ts";
+import type { MatrixCandidate } from "../matrix.ts";
 import type { Emitter, EmitterInput } from "./emitter.ts";
 
 const UNUSED_INTERFACE = "DS1201";
@@ -31,7 +31,7 @@ function compare(a: string, b: string): number {
 function indexed(input: EmitterInput): {
   readonly symbolOf: (id: string) => InventorySymbol | undefined;
   readonly inTest: (id: string) => boolean;
-  readonly candidateOf: (id: string) => Candidate | undefined;
+  readonly candidateOf: (id: string) => MatrixCandidate | undefined;
   readonly implementationsOf: (id: string) => readonly PositionedSymbol[];
 } {
   const union = input.swept.matrix.union;
@@ -79,15 +79,16 @@ function findingOf(
  * The findings of the interfaces family, `DS1200` to `DS1299`: `DS1201`, a dead
  * interface, whose members fall with it unreported; and `DS1203`, a method of a live
  * interface no reference names, unless it is a marker, a method whose every
- * implementation has an empty body. A test file's declaration is neither kind's
- * subject, because a production sweep counts none of the references it can have.
+ * implementation has an empty body. A test file's declaration is neither kind's subject,
+ * because a production sweep counts none of the references it can have, save an interface
+ * the run that counts test references does not reach, which is `DS1201`'s.
  */
 export const interfaces: Emitter = (input) => {
   const run = indexed(input);
   const found: Finding[] = [];
   for (const candidate of input.swept.sweep.candidates) {
     const symbol = run.symbolOf(candidate.id);
-    if (symbol === undefined || run.inTest(candidate.id)) {
+    if (symbol === undefined || (run.inTest(candidate.id) && !candidate.unreferencedTest)) {
       continue;
     }
     if (symbol.kind === "interface") {
@@ -122,7 +123,7 @@ export const interfaces: Emitter = (input) => {
 };
 
 /** What one unused interface's finding says, by the references the sweep counted. */
-function unusedMessage(candidate: Candidate): string {
+function unusedMessage(candidate: MatrixCandidate): string {
   if (candidate.relation === "reachability") {
     return UNUSED_DEAD_MESSAGE;
   }

package/src/findings/intra-function.ts

@@ -19,6 +19,24 @@ function overlapClause(overlap: readonly string[]): string {
     : `also reported by ${spelled(overlap)}`;
 }
 
+/**
+ * Whether one parameter's name is reported: every unread one of a function whose
+ * signature is free, and of a function used as a value only one no read parameter follows,
+ * because a caller may pass such a function more arguments than it declares.
+ */
+function parameterReported(
+  part: PartFact,
+  free: ReadonlySet<string>,
+  freeButValued: ReadonlySet<string>,
+): boolean {
+  const place = part.parameter;
+  if (place?.inValue !== true && free.has(part.declaration)) {
+    return true;
+  }
+  const valued = place?.inValue === true || freeButValued.has(part.declaration);
+  return valued && place?.beforeARead !== true;
+}
+
 /**
  * Whether one part is reported. A parameter needs its function's signature free to
  * change; a result needs that, every call in the loaded program to discard it, and every
@@ -34,10 +52,10 @@ function reported(
   if (part.used) {
     return false;
   }
-  const { free, discardedEverywhere } = input.intraFunction;
+  const { free, freeButValued, discardedEverywhere } = input.intraFunction;
   switch (part.code) {
     case UNUSED_PARAMETER:
-      return free.has(part.declaration);
+      return parameterReported(part, free, freeButValued);
     case UNUSED_RESULT:
       return (
         free.has(part.declaration) &&

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

@@ -2,6 +2,7 @@ import type { Finding, FindingDetails, FindingPosition } from "../finding.ts";
 import type { InventorySymbol } from "../inventory.ts";
 import type { MatrixCandidate } from "../matrix.ts";
 import { positionKey } from "../position.ts";
+import { declarationKey } from "../ref.ts";
 import type { Emitter, EmitterInput } from "./emitter.ts";
 
 /** The codes of this family. */
@@ -242,12 +243,16 @@ function unusedTypeParameters(run: Run): readonly Finding[] {
 }
 
 /**
- * The references of the declarations the write-only kind reports, whatever the
+ * The keys of the declarations the write-only kind reports, whatever the
  * severity: a narrowing kind yields each to it, since deleting the declaration
  * supersedes narrowing it.
  */
 export function writeOnlyDeclarations(input: EmitterInput): ReadonlySet<string> {
-  return new Set(writeOnlySymbols(indexed(input)).map((finding) => finding.symbol.ref));
+  return new Set(
+    writeOnlySymbols(indexed(input)).map((finding) =>
+      declarationKey(finding.symbol.ref, finding.position.path),
+    ),
+  );
 }
 
 /**

package/src/findings/unused-declarations.ts

@@ -71,9 +71,16 @@ function codeOf(judged: Judged): string | undefined {
   if (candidate.testOfDeadCode) {
     return "DS1005";
   }
-  if (judged.test || judged.containerDead || NOT_THIS_FAMILY.has(symbol.kind)) {
+  if (
+    (judged.test && !candidate.unreferencedTest) ||
+    judged.containerDead ||
+    NOT_THIS_FAMILY.has(symbol.kind)
+  ) {
     return undefined;
   }
+  if (candidate.unreferencedTest) {
+    return unreferencedCode(symbol);
+  }
   const referenced = candidate.productionRefs + candidate.testRefs > 0;
   if (symbol.kind === "enum-member" && !referenced) {
     return undefined;
@@ -96,6 +103,14 @@ function codeOf(judged: Judged): string | undefined {
   return judged.unreachable ? undefined : "DS1001";
 }
 
+/** The code a declaration nothing references carries, by its shape and its visibility. */
+function unreferencedCode(symbol: InventorySymbol): string {
+  if (MEMBERS.has(symbol.kind)) {
+    return "DS1003";
+  }
+  return symbol.exported ? "DS1001" : "DS1002";
+}
+
 /** The visibility a member's message names, where it narrows the member's reach. */
 function visibilityWord(symbol: InventorySymbol): string {
   switch (symbol.visibility) {

package/src/findings/visibility-narrowing.ts

@@ -2,6 +2,7 @@ import type { Finding } from "../finding.ts";
 import { OUTSIDE, type Graph } from "../graph.ts";
 import type { InventorySymbol, SymbolKind } from "../inventory.ts";
 import type { MatrixCandidate } from "../matrix.ts";
+import { declarationKey } from "../ref.ts";
 import type { RootKind } from "../roots.ts";
 import type { Emitter, EmitterInput } from "./emitter.ts";
 import { writeOnlyDeclarations } from "./reads-and-writes.ts";
@@ -159,7 +160,7 @@ function narrowing(
   const file = facts.fileOf[at] ?? OUTSIDE;
   if (
     !topLevelExport(facts, at, symbol) ||
-    world.writeOnly.has(symbol.ref) ||
+    world.writeOnly.has(declarationKey(symbol.ref, symbol.position.path)) ||
     symbol.kind === "export-alias" ||
     entersByName(facts.rootedBy[at]) ||
     entersByName(facts.rootedBy[file]) ||

package/src/findings-pass.ts

@@ -8,7 +8,7 @@ import type { AnalysisInputs } from "./analysis.ts";
 import { fails, type Config } from "./config.ts";
 import type { EdgeEvaluation } from "./edges.ts";
 import type { CompletedFinding, Finding } from "./finding.ts";
-import { decidedFindings } from "./findings/emitters.ts";
+import { decidedFindings, type Withheld } from "./findings/emitters.ts";
 import {
   fileRefsOf,
   staleSuppressions,
@@ -26,6 +26,8 @@ export interface PassTotals {
   readonly staleSuppressions: number;
   /** The evaluations that hold a finding pending. */
   readonly pending: number;
+  /** The findings the minimum confidence withheld, by confidence. */
+  readonly withheld: Withheld;
 }
 
 /** What the pass answers about one run. */
@@ -98,6 +100,7 @@ export function findingsPass(inputs: AnalysisInputs): PassResult {
       reasonsRecorded: counts.reasonsRecorded,
       staleSuppressions: records.length,
       pending: decided.evaluations.filter((one) => one.finding !== undefined).length,
+      withheld: decided.withheld,
     },
     ledger,
   };

package/src/graph.ts

@@ -39,11 +39,11 @@ const SWEPT: Readonly<Record<SymbolKind, boolean>> = {
 
 /**
  * Whether a root of each kind names a caller, which holds it live under both relations: a
- * tool reads the configuration it loads and the files its strings name, a runtime runs a
- * test file, a setup file, a worker, a page's module script, a command and a script, the
- * manifest names what enters the package, an alias global stands for the export it names,
- * and an entry file, a configured root and a pattern assert a caller. A library's
- * published API only supposes an unseen consumer, so it is live under reachability alone.
+ * tool reads what it loads and what its strings name, a runtime runs a test, setup or
+ * worker file, a page's module script, a command, a script or a workflow step, the manifest
+ * names what enters the package, an alias global stands for its export, and an entry file,
+ * a configured root and a pattern assert a caller. A library's published API only supposes
+ * an unseen consumer, so it is live under reachability alone.
  */
 const NAMES_A_CALLER: Readonly<Record<RootKind, boolean>> = {
   "entry-file": true,
@@ -59,10 +59,10 @@ const NAMES_A_CALLER: Readonly<Record<RootKind, boolean>> = {
   "configuration-file": true,
   "configuration-string": true,
   "test-runner": true,
-  "mutation-testing": true,
   "browser-tests": true,
   worker: true,
   "html-entry": true,
+  "workflow-step": true,
 };
 
 /** Whether the sweep judges a declaration of one kind. */

package/src/implementations.ts

@@ -118,7 +118,7 @@ function typesAt<Brand>(project: ProjectView<Brand>, nodes: readonly Node[]): Ma
 }
 
 /** Whether one class member is a method whose every written body holds no statement. */
-function emptyImplementation<Brand>(project: ProjectView<Brand>, member: TSSymbol): boolean {
+export function emptyImplementation<Brand>(project: ProjectView<Brand>, member: TSSymbol): boolean {
   const own = project.ownPaths();
   let bodies = 0;
   for (const handle of member.declarations) {