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

package/src/findings/completion.ts

@@ -4,21 +4,38 @@
  * together with every finding that falls with a root they withhold.
  */
 
+import {
+  CODE,
+  FAMILY_KEY_LENGTH,
+  type Confidence,
+  type Severity,
+  KIND_ROWS,
+  type KindRow,
+} from "../contract/contract.generated.ts";
 import type { RunSweep } from "../analysis.ts";
 import { componentId, type Component } from "../components.ts";
-import type { Cascade, Confidence, Severity } from "../config.ts";
+import { deadComponents } from "../matrix.ts";
+import type { Cascade } from "../config.ts";
 import type { CompletedFinding, Finding, FindingComponent, PositionedSymbol } from "../finding.ts";
 import { OUTSIDE, type Graph } from "../graph.ts";
 import type { SymbolKind } from "../inventory.ts";
-import { KINDS, type KindRow } from "../kinds.ts";
+import { KINDS } from "../kinds.ts";
 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 fixability grammar/analysis.md "Fixability" gives a finding about a held declaration. */
+/**
+ * The codes whose subject the run that counts test references holds live, 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(
+  KIND_ROWS.filter((row) => row.holdsLive).map((row) => row.code),
+);
+
+/** The fixability grammar/analysis/fixability.md gives a finding about a held declaration. */
 const MANUAL = "manual";
 
 /** The member kinds an object property can declare, which an `in` expression tests by name. */
@@ -48,10 +65,9 @@ function everyDeclaredLoaded(boundary: Boundary): boolean {
  * naming its family, else the code's default.
  */
 function severityOf(input: EmitterInput, code: string, fallback: Severity): Severity {
-  const { config } = input;
-  return (
-    config.severity.get(code) ?? config.severity.get(code.slice(0, FAMILY_KEY_LENGTH)) ?? fallback
-  );
+  const { severity } = input.config;
+  const key = [code, code.slice(0, FAMILY_KEY_LENGTH)].find((one) => Object.hasOwn(severity, one));
+  return key === undefined ? fallback : (severity[key] ?? fallback);
 }
 
 /**
@@ -94,17 +110,13 @@ 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, and one a function outside the
+ * analysis fills, is `possible`.
  */
 function reachabilityClasses(input: EmitterInput): (id: string) => Confidence {
   const tested = testedByIn(input);
+  const filled = input.boundary.filledOutside ?? new Set<string>();
   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,13 +125,41 @@ function reachabilityClasses(input: EmitterInput): (id: string) => Confidence {
         ? "certain"
         : "probable";
   return (id) => {
-    if (usedByTests.has(id) || tested.has(id)) {
+    if (tested.has(id) || filled.has(id)) {
       return "possible";
     }
     return published.has(id) ? outside : "certain";
   };
 }
 
+/**
+ * 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
@@ -133,20 +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.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 `DS1602` 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 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;
+  const unseen = new Set((input.files.unseenLoads ?? []).map((load) => load.configuration));
+  const complete = input.config.ts.roots_complete && !configurations.some((one) => unseen.has(one));
+  return unreachable && !complete ? "probable" : "certain";
 }
 
 /**
@@ -155,17 +234,37 @@ function testCeilings(
  */
 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);
     }
   }
+  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
@@ -182,17 +281,76 @@ 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) } : {}),
-        };
+}
+
+/**
+ * The run's dead components with each file a `DS1602` 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 === CODE.fileNeverImported).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])),
   };
 }
 
@@ -217,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 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 fallingWith = new Map<string, number>();
-  for (const { heldByTests } of swept.sweep.candidates) {
+  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, 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);
@@ -239,18 +399,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 === CODE.fileNeverImported ? 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 (
@@ -264,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 === CODE.fileNeverImported && 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"
@@ -287,9 +493,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 === CODE.fileNeverImported
+            ? input.dependencies.fileLastUses.get(finding.position.path)
+            : undefined;
     return {
       code: finding.code,
       kind: row.name,
@@ -297,20 +507,14 @@ export function completed(
       position: finding.position,
       symbol: finding.symbol,
       reachabilityClass,
-      confidence: capped(
-        capped(reachabilityClass, row.maxClass),
-        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),
@@ -327,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[],
@@ -338,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">,
@@ -368,10 +584,14 @@ export function dialsOf(
   input: EmitterInput,
   findings: readonly CompletedFinding[],
 ): Dials<CompletedFinding> {
-  const minConfidence = input.config.analysis.minConfidence;
+  const minConfidence = input.config.analysis.min_confidence;
   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/dependencies-and-module-machinery.ts

@@ -1,9 +1,9 @@
+import { CODE } from "../contract/contract.generated.ts";
 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";
-
-const UNUSED_DEPENDENCY = "DS1601";
+import type { Emitter, EmitterInput } from "./emitter.ts";
+import { nonCodeArtifacts } from "./non-code-artifacts.ts";
 
 const MESSAGES: Readonly<Record<DependencySection, string>> = {
   dependency: "no import in the target needs the declared dependency",
@@ -11,38 +11,97 @@ const MESSAGES: Readonly<Record<DependencySection, string>> = {
   "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 === CODE.fileNeverImported && 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: CODE.unusedDependency,
+        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);
+/** The findings of the dependencies family, `DS1700` to `DS1799`. */
+export const dependenciesAndModuleMachinery: Emitter = (input) =>
+  unusedDependencies(input, input.dependencies);