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

package/src/findings/completion.ts

@@ -6,6 +6,7 @@
 
 import type { RunSweep } from "../analysis.ts";
 import { componentId, type Component } from "../components.ts";
+import { deadComponents } from "../matrix.ts";
 import type { Cascade, Confidence, Severity } from "../config.ts";
 import type { CompletedFinding, Finding, FindingComponent, PositionedSymbol } from "../finding.ts";
 import { OUTSIDE, type Graph } from "../graph.ts";
@@ -15,9 +16,26 @@ import { byPosition, positionKey } from "../position.ts";
 import { declarationKey } from "../ref.ts";
 import { FAMILY_KEY_LENGTH } from "../resolve.ts";
 import { isPartSubject, isRowSubject, type Dials } from "../suppress.ts";
+import type { Candidate } from "../sweep.ts";
 import type { Boundary } from "./boundary.ts";
 import type { EmitterInput } from "./emitter.ts";
 
+/** The unused-file code, whose deletion removes every use its file writes. */
+const FILE_NEVER_IMPORTED = "DS1502";
+
+/**
+ * The codes whose subject the run that counts test references holds live, as
+ * finding.schema.json lists them, so a test file's candidate reported under one carries
+ * none of a dead declaration's sweep facts.
+ */
+const LIVE_SUBJECT: ReadonlySet<string> = new Set([
+  "DS1101",
+  "DS1102",
+  "DS1104",
+  "DS1204",
+  "DS1301",
+]);
+
 /** The fixability grammar/analysis.md "Fixability" gives a finding about a held declaration. */
 const MANUAL = "manual";
 
@@ -94,17 +112,11 @@ function testedByIn(input: EmitterInput): ReadonlySet<string> {
  * published API, a public member of a published type included, is `certain` where the
  * run loaded every consumer the scope declared and declared one, `probable` where one did
  * not load, and `possible` where it declared none, whatever the configuration says of the
- * consumer set. Test-support code test code references, outside the test-of-dead-code
- * rule, what it contains, and a member an `in` expression tests by name are `possible`.
+ * consumer set. A member an `in` expression tests by name is `possible`.
  */
 function reachabilityClasses(input: EmitterInput): (id: string) => Confidence {
   const tested = testedByIn(input);
   const published = publishedIds(input.swept.matrix.union);
-  const usedByTests = new Set(
-    input.swept.sweep.candidates
-      .filter((candidate) => candidate.heldByTests !== undefined)
-      .map((candidate) => candidate.id),
-  );
   const { declared } = input.boundary.consumers;
   const outside: Confidence =
     declared.length === 0
@@ -113,7 +125,7 @@ function reachabilityClasses(input: EmitterInput): (id: string) => Confidence {
         ? "certain"
         : "probable";
   return (id) => {
-    if (usedByTests.has(id) || tested.has(id)) {
+    if (tested.has(id)) {
       return "possible";
     }
     return published.has(id) ? outside : "certain";
@@ -141,7 +153,12 @@ function testCeilings(
     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.subject[edge.to] === true) {
+      if (
+        target !== undefined &&
+        !testCode &&
+        union.ambient[edge.to] !== true &&
+        union.subject[edge.to] === true
+      ) {
         lowest = capped(lowest, classOf(target.id));
       }
     }
@@ -149,16 +166,32 @@ function testCeilings(
   };
 }
 
+/**
+ * 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`.
+ */
+function rootsCeiling(
+  input: EmitterInput,
+  finding: Finding,
+  candidate: Candidate | undefined,
+): Confidence {
+  const unreachable = candidate?.relation === "reachability" || finding.unreachableOnly === true;
+  return unreachable && !input.config.ts.rootsComplete ? "probable" : "certain";
+}
+
 /**
  * The component each dead declaration of the run falls in, and none for a live one, with
  * its members listed in the canonical order where the run lists a component in full.
  */
 function findingComponents(
   swept: RunSweep,
+  components: readonly Component[],
   cascade: Cascade,
 ): (id: string) => FindingComponent | undefined {
   const held = new Map<string, Component>();
-  for (const component of swept.sweep.components) {
+  for (const component of components) {
     for (const member of component.members) {
       held.set(member, component);
     }
@@ -196,6 +229,77 @@ function findingComponents(
   };
 }
 
+/**
+ * The run's dead components with each file a `DS1502` finding reports dead among them, so
+ * the file's declarations fall with it, and with the components each subject that is no
+ * declaration falls with joined into one.
+ */
+function runComponents(
+  swept: RunSweep,
+  findings: readonly Finding[],
+): {
+  readonly components: readonly Component[];
+  readonly computed: number;
+  readonly files: ReadonlyMap<string, string>;
+} {
+  const union = swept.matrix.union;
+  const reported = new Set(
+    findings.filter((one) => one.code === FILE_NEVER_IMPORTED).map((one) => one.position.path),
+  );
+  const files = new Map(
+    union.symbols.flatMap((symbol, at) =>
+      symbol.kind === "file" && reported.has(symbol.position.path) ? [[at, symbol] as const] : [],
+    ),
+  );
+  const computed =
+    files.size === 0
+      ? swept.sweep.components
+      : deadComponents(swept.matrix, swept.sweep, new Set(files.keys()));
+  const place = new Map<string, number>();
+  computed.forEach((component, at) => {
+    for (const member of component.members) {
+      place.set(member, at);
+    }
+  });
+  const leader = computed.map((_component, at) => at);
+  const find = (at: number): number => {
+    let top = at;
+    while ((leader[top] ?? top) !== top) {
+      top = leader[top] ?? top;
+    }
+    return top;
+  };
+  for (const { fallsWith } of findings) {
+    const joined = (fallsWith ?? []).flatMap((id) => place.get(id) ?? []).map(find);
+    const first = Math.min(...joined);
+    for (const one of joined) {
+      leader[one] = first;
+    }
+  }
+  const merged = new Map<number, Component>();
+  computed.forEach((component, at) => {
+    const top = find(at);
+    const into = merged.get(top);
+    merged.set(
+      top,
+      into === undefined
+        ? component
+        : {
+            id: into.id,
+            members: [...into.members, ...component.members],
+            roots: [...into.roots, ...component.roots],
+            deletableLines: into.deletableLines + component.deletableLines,
+            held: into.held && component.held,
+          },
+    );
+  });
+  return {
+    components: [...merged.values()],
+    computed: computed.length,
+    files: new Map([...files.values()].map((symbol) => [symbol.position.path, symbol.id])),
+  };
+}
+
 /**
  * Every finding of the run completed, in the order given. A dead declaration carries its
  * candidate's relation, counts, configurations and component; a live one carries no relation and
@@ -217,12 +321,12 @@ 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 componentOf = findingComponents(swept, input.config.reporters.cascade);
-  const held = new Set(
-    swept.sweep.components.filter((one) => one.held).flatMap((one) => one.members),
-  );
-  let minted = swept.sweep.components.length;
-  const dead = new Set(swept.sweep.components.map((component) => component.id));
+  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) {
     if (heldByTests !== undefined) {
@@ -239,18 +343,33 @@ export function completed(
     // a row is still never the declaration. Two declarations of one file can share a
     // reference, so the one the finding is positioned at is the subject where there is one.
     const declared = union.at(positionKey(finding.position));
+    const ref = finding.symbol.holder ?? finding.symbol.ref;
     const at = isRowSubject(finding.symbol.kind)
       ? OUTSIDE
-      : union.symbols[declared]?.ref === finding.symbol.ref
+      : union.symbols[declared]?.ref === ref
         ? declared
-        : (positions.get(declarationKey(finding.symbol.ref, finding.position.path)) ?? OUTSIDE);
+        : (positions.get(declarationKey(ref, finding.position.path)) ?? OUTSIDE);
     // A part names the declaration that holds it, and is decided inside it rather than by
     // the declaration's liveness, so it carries none of the declaration's sweep facts.
     const part = isPartSubject(finding.symbol.kind);
     const symbol = union.symbols[at];
     const judged = !part && union.subject[at] === true ? symbol : undefined;
-    const candidate = judged === undefined ? undefined : candidates.get(judged.id);
-    const found = symbol === undefined || part ? undefined : componentOf(symbol.id);
+    const candidate =
+      judged === undefined || LIVE_SUBJECT.has(finding.code)
+        ? undefined
+        : candidates.get(judged.id);
+    const fallsWith = finding.fallsWith?.[0];
+    const joined = fallsWith === undefined ? undefined : componentOf(fallsWith);
+    const file =
+      finding.code === FILE_NEVER_IMPORTED ? files.get(finding.position.path) : undefined;
+    const found =
+      joined !== undefined
+        ? { ...joined, root: false }
+        : file !== undefined
+          ? componentOf(file)
+          : symbol === undefined || part
+            ? undefined
+            : componentOf(symbol.id);
     // A test file's declaration is a component member only as a test of dead code, and
     // test code keeps the test-support code it references out of every component.
     if (
@@ -287,9 +406,13 @@ export function completed(
         ? MANUAL
         : row.fixability;
     const lastUses =
-      fixability === "deletable" && candidate !== undefined
-        ? input.dependencies.lastUses.get(candidate.id)
-        : undefined;
+      fixability !== "deletable"
+        ? undefined
+        : candidate !== undefined
+          ? input.dependencies.lastUses.get(candidate.id)
+          : finding.code === FILE_NEVER_IMPORTED
+            ? input.dependencies.fileLastUses.get(finding.position.path)
+            : undefined;
     return {
       code: finding.code,
       kind: row.name,
@@ -298,7 +421,7 @@ export function completed(
       symbol: finding.symbol,
       reachabilityClass,
       confidence: capped(
-        capped(reachabilityClass, row.maxClass),
+        capped(capped(reachabilityClass, row.maxClass), rootsCeiling(input, finding, candidate)),
         judged === undefined ? "certain" : ceilingOf(judged.id),
       ),
       ...(candidate === undefined ? {} : { livenessRelation: candidate.relation }),

package/src/findings/dependencies-and-module-machinery.ts

@@ -1,48 +1,110 @@
 import { declarationKey, type Dependencies } from "../dependencies.ts";
 import type { Finding } from "../finding.ts";
 import { renderRef, type DependencySection } from "../ref.ts";
-import type { Emitter } from "./emitter.ts";
+import type { Emitter, EmitterInput } from "./emitter.ts";
+import { nonCodeArtifacts } from "./non-code-artifacts.ts";
 
 const UNUSED_DEPENDENCY = "DS1601";
 
+const FILE_NEVER_IMPORTED = "DS1502";
+
 const MESSAGES: Readonly<Record<DependencySection, string>> = {
   dependency: "no import in the target needs the declared dependency",
   "dev-dependency": "no import in the target needs the declared development dependency",
   "peer-dependency": "no import in the target needs the declared peer dependency",
 };
 
+const DEAD_USERS_MESSAGES: Readonly<Record<DependencySection, string>> = {
+  dependency: "only code that is itself dead uses the declared dependency",
+  "dev-dependency": "only code that is itself dead uses the declared development dependency",
+  "peer-dependency": "only code that is itself dead uses the declared peer dependency",
+};
+
+/** How the run judged the declarations and files a dependency's uses may sit in. */
+interface DeadCode {
+  /** The members of the dead components, and the top level of each file reported unimported. */
+  readonly dead: ReadonlySet<string>;
+  /** Those found dead under reachability alone. */
+  readonly reachedOnly: ReadonlySet<string>;
+  /** The declarations of a library's published API, whose findings sit at the consumers' class. */
+  readonly published: ReadonlySet<string>;
+}
+
+/**
+ * The run's dead code: test code keeps the code it references out of every dead component
+ * unless that code is dead as well, and a file's top level is dead where the file is.
+ */
+function deadCode(input: EmitterInput): DeadCode {
+  const { swept } = input;
+  const union = swept.matrix.union;
+  const files = new Map(
+    union.symbols.filter((one) => one.kind === "file").map((one) => [one.position.path, one.id]),
+  );
+  const dead = new Set(swept.sweep.components.flatMap((component) => component.members));
+  const reachedOnly = new Set(
+    swept.sweep.candidates.filter((one) => one.relation === "reachability").map((one) => one.id),
+  );
+  for (const finding of nonCodeArtifacts(input)) {
+    const id = files.get(finding.position.path);
+    if (finding.code === FILE_NEVER_IMPORTED && id !== undefined) {
+      dead.add(id);
+      if (finding.unreachableOnly === true) {
+        reachedOnly.add(id);
+      }
+    }
+  }
+  const published = new Set(
+    union.rooted
+      .filter((root) => root.kind === "published-api")
+      .flatMap((root) => union.symbols[root.at]?.id ?? []),
+  );
+  return { dead, reachedOnly, published };
+}
+
 /**
  * A dependency, development dependency or peer dependency of a manifest the run reads
- * that the target does not need, at the position of its key.
+ * that the target does not need, at the position of its key, and one whose every use is
+ * held by dead code, which is dead only through that code and falls with its component:
+ * at `possible` where one of its holders is published, and found under reachability alone
+ * where one of them is.
  */
-function unusedDependencies(dependencies: Dependencies): Finding[] {
-  return dependencies.declared
-    .filter(
-      (dependency) =>
-        !dependencies.needed.has(declarationKey(dependency)) &&
-        !dependencies.ran.has(declarationKey(dependency)),
-    )
-    .map((dependency) => ({
-      code: UNUSED_DEPENDENCY,
-      position: dependency.position,
-      symbol: {
-        ref: renderRef(dependency.manifest, {
-          of: "dependency",
+function unusedDependencies(input: EmitterInput, dependencies: Dependencies): Finding[] {
+  const { dead, reachedOnly, published } = deadCode(input);
+  return dependencies.declared.flatMap((dependency) => {
+    const key = declarationKey(dependency);
+    const held = dependencies.heldBy.get(key);
+    const users = held?.every((id) => dead.has(id)) === true ? held : undefined;
+    if (dependencies.ran.has(key) || (dependencies.needed.has(key) && users === undefined)) {
+      return [];
+    }
+    const unbuilt = dependencies.unbuilt.has(dependency.position.path);
+    const atPossible = unbuilt || users?.some((id) => published.has(id)) === true;
+    return [
+      {
+        code: UNUSED_DEPENDENCY,
+        position: dependency.position,
+        symbol: {
+          ref: renderRef(dependency.manifest, {
+            of: "dependency",
+            name: dependency.name,
+            section: dependency.section,
+          }),
+          kind: "dependency",
           name: dependency.name,
-          section: dependency.section,
-        }),
-        kind: "dependency",
-        name: dependency.name,
-        sizeLines: 1,
+          sizeLines: 1,
+        },
+        message: (users === undefined ? MESSAGES : DEAD_USERS_MESSAGES)[dependency.section],
+        details: { dependencyClass: dependency.section },
+        ...(atPossible ? { reachabilityClass: "possible" as const } : {}),
+        ...(users?.some((id) => reachedOnly.has(id)) === true
+          ? { unreachableOnly: true as const }
+          : {}),
+        ...(users === undefined ? {} : { fallsWith: users }),
       },
-      message: MESSAGES[dependency.section],
-      details: { dependencyClass: dependency.section },
-      ...(dependencies.unbuilt.has(dependency.position.path)
-        ? { reachabilityClass: "possible" as const }
-        : {}),
-    }));
+    ];
+  });
 }
 
 /** The findings of the dependencies-and-module-machinery family, `DS1600` to `DS1699`. */
-export const dependenciesAndModuleMachinery: Emitter = ({ dependencies }) =>
-  unusedDependencies(dependencies);
+export const dependenciesAndModuleMachinery: Emitter = (input) =>
+  unusedDependencies(input, input.dependencies);

package/src/findings/emitters.ts

@@ -165,7 +165,7 @@ function dialledOver(
   const unanswered = heldKeys(input);
   const markup = markupKeys(input);
   const candidates = found.filter((finding) => {
-    const key = declarationKey(finding.symbol.ref, finding.position.path);
+    const key = declarationKey(finding.symbol.holder ?? finding.symbol.ref, finding.position.path);
     return (
       !ledger.withheld(finding) &&
       !unanswered.has(key) &&

package/src/findings/intra-function.ts

@@ -1,5 +1,7 @@
+import type { Confidence } from "../config.ts";
 import type { Finding } from "../finding.ts";
 import { KINDS } from "../kinds.ts";
+import { parameterRef } from "../ref.ts";
 import { UNUSED_PARAMETER, UNUSED_RESULT, type PartFact } from "../intra-function-parts.ts";
 import { reachedWithTheTests } from "../sweep.ts";
 import type { Emitter, EmitterInput } from "./emitter.ts";
@@ -12,29 +14,56 @@ function spelled(rules: readonly string[]): string {
   return `${rules.slice(0, -1).join(", ")} and ${rules.at(-1) ?? ""}`;
 }
 
-/** The clause a message ends with: the other rules that report the kind, or that none is known. */
-function overlapClause(overlap: readonly string[]): string {
-  return overlap.length === 1 && overlap[0] === "none known"
+/** The compiler's rule of the parameter kind's overlap list, which reports only in a file it checks. */
+const COMPILER_PARAMETER_RULE = "tsc --noUnusedParameters";
+
+/**
+ * The clause a message ends with: the other rules that report the part, or that none is
+ * known. A parameter of a file the compiler does not check is no report of the compiler's.
+ */
+function overlapClause(overlap: readonly string[], part: PartFact): string {
+  const rules =
+    part.parameter?.checked === false
+      ? overlap.filter((rule) => rule !== COMPILER_PARAMETER_RULE)
+      : overlap;
+  return rules.length === 1 && rules[0] === "none known"
     ? "no other rule is known to report it"
-    : `also reported by ${spelled(overlap)}`;
+    : `also reported by ${spelled(rules)}`;
 }
 
+/** What a parameter's finding asks: its deletion, or, where a read parameter follows it, its rename. */
+type ParameterVerdict =
+  | { readonly fix: "delete"; readonly confidence: Confidence }
+  | { readonly fix: "rename" }
+  | undefined;
+
 /**
- * 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.
+ * Whether one unread parameter is reported, and how. Of a free signature it is deleted. A
+ * 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.
  */
-function parameterReported(
+function parameterVerdict(
   part: PartFact,
   free: ReadonlySet<string>,
   freeButValued: ReadonlySet<string>,
-): boolean {
+): ParameterVerdict {
   const place = part.parameter;
   if (place?.inValue !== true && free.has(part.declaration)) {
-    return true;
+    return place?.annotated === undefined ? { fix: "delete", confidence: "certain" } : undefined;
   }
   const valued = place?.inValue === true || freeButValued.has(part.declaration);
-  return valued && place?.beforeARead !== true;
+  if (!valued) {
+    return undefined;
+  }
+  if (place?.beforeARead === true) {
+    return { fix: "rename" };
+  }
+  if (place?.annotated === "steers") {
+    return undefined;
+  }
+  return { fix: "delete", confidence: place?.annotated === "free" ? "probable" : "certain" };
 }
 
 /**
@@ -55,7 +84,7 @@ function reported(
   const { free, freeButValued, discardedEverywhere } = input.intraFunction;
   switch (part.code) {
     case UNUSED_PARAMETER:
-      return parameterReported(part, free, freeButValued);
+      return parameterVerdict(part, free, freeButValued) !== undefined;
     case UNUSED_RESULT:
       return (
         free.has(part.declaration) &&
@@ -119,20 +148,33 @@ export const intraFunction: Emitter = (input) => {
     if (declaration === undefined || !judged(declaration.id) || !reported(input, part, unknown)) {
       continue;
     }
+    const verdict =
+      part.code === UNUSED_PARAMETER
+        ? parameterVerdict(part, input.intraFunction.free, input.intraFunction.freeButValued)
+        : undefined;
+    const message =
+      verdict?.fix === "rename"
+        ? `${part.message}, and a read parameter follows it, so rename it to _${part.name}`
+        : part.message;
     found.push({
       code: part.code,
       position: part.position,
       symbol: {
-        ref: declaration.ref,
+        ...(part.code === UNUSED_PARAMETER
+          ? { ref: parameterRef(declaration.ref, part.name), holder: declaration.ref }
+          : { ref: declaration.ref }),
         kind: part.kind,
         name: part.name,
         sizeLines: part.position.endLine - part.position.line + 1,
       },
-      message: `${part.message}; ${overlapClause(overlap)}`,
+      message: `${message}; ${overlapClause(overlap, part)}`,
       details: {
         ...(part.kind === "store" ? { writePositions: [part.position] } : {}),
         overlap,
       },
+      ...(verdict?.fix === "delete" && verdict.confidence !== "certain"
+        ? { reachabilityClass: verdict.confidence }
+        : {}),
     });
   }
   return found;