@cplieger/deadset-ts 3.6.0 → 3.7.0

package/src/finding.ts

@@ -1,13 +1,14 @@
+import type { Confidence, Severity } from "./config.ts";
+import type { Fixability } from "./kinds.ts";
+import type { DependencySection } from "./ref.ts";
+import type { Relation } from "./sweep.ts";
+
 /**
- * The members of a finding its emitter decides: the code, where the subject is,
- * what the subject is, and the sentence the finding reports. They are the
- * Contract's finding members of the same names, spelled in this language's case.
- *
- * Every other member the finding schema requires follows from these and from the
- * run: the kind's name, its fixability and its ceiling come from the code's row of
- * the issue-kind vocabulary, the severity and the confidence from the resolved
- * configuration, the language from the analyzer. A report completes them, so an
- * emitter cannot state one that disagrees with the vocabulary.
+ * The finding: what an emitter decides about one subject, and every member the
+ * Contract's finding schema requires, spelled in this language's case. An emitter states
+ * the code, where the subject is, what it is, the sentence, and the details its code
+ * carries; the completion step reads every other member from the run and from the code's
+ * row of the issue-kind vocabulary, so no emitter states one that disagrees with either.
  */
 
 /** Where the subject of a finding is. */
@@ -34,10 +35,75 @@ export interface FindingSubject {
   readonly sizeLines: number;
 }
 
-/** One finding, as its emitter states it. */
+/** A declaration a finding names beside the subject, with where it is written. */
+export interface PositionedSymbol {
+  readonly ref: string;
+  readonly name: string;
+  readonly position: FindingPosition;
+}
+
+/**
+ * What only some codes carry. The finding schema's branches decide which code carries
+ * which member, and every member is absent under every other code.
+ */
+export interface FindingDetails {
+  /**
+   * On `DS1101` and `DS1104`: the widest scope that holds every reference to the
+   * subject, which is the visibility its references support.
+   */
+  readonly narrowerVisibility?: "file" | "package";
+  /** On `DS1201` and `DS1203`: the classes implementing the interface, in site order. */
+  readonly implementations?: readonly PositionedSymbol[];
+  /** On `DS1301`: every position the subject is written at, in site order. */
+  readonly writePositions?: readonly FindingPosition[];
+  /** On `DS1601`: the manifest section that declares the dependency. */
+  readonly dependencyClass?: DependencySection;
+}
+
+/** One finding as its emitter states it. */
 export interface Finding {
   readonly code: string;
   readonly position: FindingPosition;
   readonly symbol: FindingSubject;
   readonly message: string;
+  /** Absent where the code carries nothing. */
+  readonly details?: FindingDetails;
+}
+
+/** The dead component a finding names, as the finding schema spells its members. */
+export interface FindingComponent {
+  readonly id: string;
+  /** Whether the subject is a root member of the component. */
+  readonly root: boolean;
+  /** The number of the component's members. */
+  readonly symbolCount: number;
+  readonly deletableLines: number;
+}
+
+/** One finding with every member the finding schema requires. */
+export interface CompletedFinding extends Finding {
+  /** The name of the code's row of the issue-kind vocabulary. */
+  readonly kind: string;
+  readonly language: "ts";
+  readonly reachabilityClass: Confidence;
+  /** The reachability class capped by the code's ceiling. */
+  readonly confidence: Confidence;
+  /**
+   * The relation that decided the subject: present on a declaration the sweep judged
+   * dead, absent on a live one and on a subject that is no declaration.
+   */
+  readonly livenessRelation?: Relation;
+  /** Whether every reference to the subject comes from a test file. */
+  readonly testOnly: boolean;
+  readonly generated: boolean;
+  readonly component: FindingComponent;
+  /** Empty on every finding: a declaration an exemption holds back is not reported. */
+  readonly retainedBy: readonly string[];
+  /** The configurations the finding holds in, in the run's order. */
+  readonly configurations: readonly string[];
+  /** The consumers the run loaded beside the target. */
+  readonly consumersLoaded: readonly string[];
+  readonly fixability: Fixability;
+  readonly severity: Severity;
+  readonly details: FindingDetails;
 }

package/src/findings/completion.ts

@@ -1,50 +1,23 @@
 /**
- * What a finding about a declaration carries beyond what its emitter decides, read from
- * the run: the reachability class and the confidence, the relation that decided the
- * subject, the dead component it falls in, the configurations it holds in, and the
- * severity the configuration gives its code. The dials withhold what they name and
- * every finding that falls with a root they withhold.
+ * What every finding carries beyond what its emitter decides, read from the run and from
+ * the code's row of the issue-kind vocabulary, and the dials that withhold a finding
+ * together with every finding that falls with a root they withhold.
  */
 
 import type { RunSweep } from "../analysis.ts";
 import { componentId, type Component } from "../components.ts";
 import type { Confidence, Config, Severity } from "../config.ts";
-import type { Finding } from "../finding.ts";
+import type { CompletedFinding, Finding, FindingComponent } from "../finding.ts";
+import { OUTSIDE } from "../graph.ts";
+import { KINDS } from "../kinds.ts";
 import { FAMILY_KEY_LENGTH } from "../resolve.ts";
-import type { Relation } from "../sweep.ts";
-
-/** The dead component a finding names, as the finding schema spells its members. */
-export interface FindingComponent {
-  readonly id: string;
-  /** Whether the subject is a root member of the component. */
-  readonly root: boolean;
-  /** The number of the component's members. */
-  readonly symbolCount: number;
-  readonly deletableLines: number;
-}
-
-/** One finding with the members the run decides, in this language's case. */
-export interface CompletedFinding extends Finding {
-  readonly reachabilityClass: Confidence;
-  /** The reachability class capped by the code's ceiling. */
-  readonly confidence: Confidence;
-  /** The relation that decided the subject, absent where none did. */
-  readonly livenessRelation?: Relation;
-  /** Whether every reference to the subject comes from a test file. */
-  readonly testOnly: boolean;
-  readonly component: FindingComponent;
-  /** The configurations the finding holds in, in the run's order. */
-  readonly configurations: readonly string[];
-  readonly severity: Severity;
-  /** The per-code members of the finding schema's `details`, empty for a code with none. */
-  readonly details: Readonly<Record<string, unknown>>;
-}
+import type { EmitterInput } from "./emitter.ts";
 
 /** The classes ranked by the claim each makes, the strongest highest. */
-export const RANK: Readonly<Record<Confidence, number>> = { certain: 3, probable: 2, possible: 1 };
+const RANK: Readonly<Record<Confidence, number>> = { certain: 3, probable: 2, possible: 1 };
 
 /** The weaker of two classes, which is a class capped by a ceiling. */
-export function capped(found: Confidence, ceiling: Confidence): Confidence {
+function capped(found: Confidence, ceiling: Confidence): Confidence {
   return RANK[found] <= RANK[ceiling] ? found : ceiling;
 }
 
@@ -52,7 +25,7 @@ export function capped(found: Confidence, ceiling: Confidence): Confidence {
  * The severity the configuration gives one code: the key naming the code, else the key
  * naming its family, else the code's default.
  */
-export function severityOf(config: Config, code: string, fallback: Severity): Severity {
+function severityOf(config: Config, code: string, fallback: Severity): Severity {
   return (
     config.severity.get(code) ?? config.severity.get(code.slice(0, FAMILY_KEY_LENGTH)) ?? fallback
   );
@@ -65,7 +38,7 @@ export function severityOf(config: Config, code: string, fallback: Severity): Se
  * in the loaded program, a private member and a `#private` name among them, and is
  * `certain`.
  */
-export function reachabilityClasses(swept: RunSweep): (id: string) => Confidence {
+function reachabilityClasses(swept: RunSweep): (id: string) => Confidence {
   const union = swept.matrix.union;
   const published = new Set(
     union.rooted
@@ -76,7 +49,7 @@ export function reachabilityClasses(swept: RunSweep): (id: string) => Confidence
 }
 
 /** The component each dead declaration of the run falls in, and none for a live one. */
-export function findingComponents(swept: RunSweep): (id: string) => FindingComponent | undefined {
+function findingComponents(swept: RunSweep): (id: string) => FindingComponent | undefined {
   const held = new Map<string, Component>();
   for (const component of swept.sweep.components) {
     for (const member of component.members) {
@@ -96,35 +69,74 @@ export function findingComponents(swept: RunSweep): (id: string) => FindingCompo
   };
 }
 
-/** One finding with the component it names. */
-export type PlacedFinding = Finding & { readonly component: FindingComponent };
-
 /**
- * Every finding of the run, each with its component, in the order given: the dead
- * component its subject falls in. A subject in none, a live declaration, a file no
- * program builds or a manifest row, falls with nothing and is given a component of its
- * own, numbered past the run's computed components in the order the findings come, so
- * no two families mint one identifier.
+ * 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 holds where it is declared; a file or a manifest row is `certain` and
+ * holds in every configuration. A subject in no dead component gets one of its own,
+ * numbered past the computed ones in finding order, so no two families mint one.
  */
-export function placed(swept: RunSweep, findings: readonly Finding[]): readonly PlacedFinding[] {
+export function completed(
+  input: EmitterInput,
+  findings: readonly Finding[],
+): readonly CompletedFinding[] {
+  const { swept } = input;
+  const union = swept.matrix.union;
+  const positions = new Map(union.symbols.map((symbol, at) => [symbol.ref, at]));
+  const candidates = new Map(swept.sweep.candidates.map((candidate) => [candidate.id, candidate]));
+  const classOf = reachabilityClasses(swept);
   const componentOf = findingComponents(swept);
-  const ids = new Map(swept.matrix.union.symbols.map((symbol) => [symbol.ref, symbol.id]));
   let minted = swept.sweep.components.length;
-  return findings.map((finding) => {
-    const id = ids.get(finding.symbol.ref);
-    const component = id === undefined ? undefined : componentOf(id);
-    if (component !== undefined) {
-      return { ...finding, component };
+
+  return findings.map((finding): CompletedFinding => {
+    const row = KINDS.get(finding.code);
+    if (row === undefined) {
+      throw new Error(`${finding.code} names no live row of the issue-kind vocabulary`);
     }
-    minted += 1;
-    return {
-      ...finding,
-      component: {
+    const at = positions.get(finding.symbol.ref) ?? OUTSIDE;
+    const symbol = union.symbols[at];
+    const judged = union.subject[at] === true ? symbol : undefined;
+    const candidate = judged === undefined ? undefined : candidates.get(judged.id);
+    const found = symbol === undefined ? undefined : componentOf(symbol.id);
+    if (candidate !== undefined && found === undefined) {
+      throw new Error(`${candidate.id} is judged dead and falls in no dead component`);
+    }
+    let component = found;
+    if (component === undefined) {
+      minted += 1;
+      component = {
         id: componentId(minted),
         root: true,
         symbolCount: 1,
         deletableLines: finding.symbol.sizeLines,
-      },
+      };
+    }
+    const counts =
+      candidate === undefined
+        ? union.made[at]
+        : { production: candidate.productionRefs, test: candidate.testRefs };
+    const reachabilityClass = judged === undefined ? "certain" : classOf(judged.id);
+    return {
+      code: finding.code,
+      kind: row.name,
+      language: "ts",
+      position: finding.position,
+      symbol: finding.symbol,
+      reachabilityClass,
+      confidence: capped(reachabilityClass, row.maxClass),
+      ...(candidate === undefined ? {} : { livenessRelation: candidate.relation }),
+      testOnly: judged !== undefined && counts?.production === 0 && counts.test > 0,
+      generated: false,
+      component,
+      retainedBy: [],
+      configurations:
+        candidate?.configurations ??
+        (judged === undefined ? swept.matrix.configurations : (swept.matrix.heldIn[at] ?? [])),
+      consumersLoaded: input.boundary.consumers.loaded,
+      fixability: row.fixability,
+      severity: severityOf(input.config, finding.code, row.defaultSeverity),
+      message: finding.message,
+      details: finding.details ?? {},
     };
   });
 }

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

@@ -1,26 +1,16 @@
-import type { Config, Severity } from "../config.ts";
 import type { Dependencies } from "../dependencies.ts";
 import type { Finding } from "../finding.ts";
 import { renderRef, type DependencySection } from "../ref.ts";
-import { severityOf } from "./completion.ts";
 import type { Emitter } from "./emitter.ts";
 
 const UNUSED_DEPENDENCY = "DS1601";
 
-/** The severity the kind ships at, which the configuration's keys override. */
-const UNUSED_DEPENDENCY_SEVERITY: Severity = "deny";
-
 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",
 };
 
-/** An unused-dependency finding, with the section that declares the dependency. */
-export interface UnusedDependencyFinding extends Finding {
-  readonly details: { readonly dependencyClass: DependencySection };
-}
-
 /**
  * The dependencies the target needs: every package the projects' uses name, every
  * declared dependency that ships a command, which a script, a workflow or a shell
@@ -48,14 +38,9 @@ function neededBy(dependencies: Dependencies): ReadonlySet<string> {
 
 /**
  * A dependency, development dependency or peer dependency of the target's manifest
- * that the target does not need, at the position of its key. Nothing is reported at
- * `allow`. Every subject is a manifest entry, which is `certain` whatever the
- * consumers, so no minimum confidence withholds one.
+ * that the target does not need, at the position of its key.
  */
-function unusedDependencies(config: Config, dependencies: Dependencies): UnusedDependencyFinding[] {
-  if (severityOf(config, UNUSED_DEPENDENCY, UNUSED_DEPENDENCY_SEVERITY) === "allow") {
-    return [];
-  }
+function unusedDependencies(dependencies: Dependencies): Finding[] {
   const needed = neededBy(dependencies);
   return dependencies.declared
     .filter((dependency) => !needed.has(dependency.name))
@@ -78,5 +63,5 @@ function unusedDependencies(config: Config, dependencies: Dependencies): UnusedD
 }
 
 /** The findings of the dependencies-and-module-machinery family, `DS1600` to `DS1699`. */
-export const dependenciesAndModuleMachinery: Emitter = ({ config, dependencies }) =>
-  unusedDependencies(config, dependencies);
+export const dependenciesAndModuleMachinery: Emitter = ({ dependencies }) =>
+  unusedDependencies(dependencies);

package/src/findings/emitter.ts

@@ -30,8 +30,9 @@ export interface EmitterInput {
 }
 
 /**
- * One kind family's rule over one run: the findings of the codes in its family's range
- * of the Contract's code space, in no particular order.
+ * One kind family's rule over one run: every finding of the codes in its family's range
+ * of the Contract's code space, whatever severity and minimum confidence the
+ * configuration sets, in no particular order.
  */
 export type Emitter = (input: EmitterInput) => readonly Finding[];
 

package/src/findings/emitters.ts

@@ -1,5 +1,6 @@
 import { dependenciesAndModuleMachinery } from "./dependencies-and-module-machinery.ts";
-import { placed, type PlacedFinding } from "./completion.ts";
+import type { CompletedFinding } from "../finding.ts";
+import { completed, reportable } from "./completion.ts";
 import type { Emitter, EmitterInput, Emitters } from "./emitter.ts";
 import { interfaces } from "./interfaces.ts";
 import { intraFunction } from "./intra-function.ts";
@@ -22,12 +23,11 @@ export const EMITTERS: Emitters = new Map<string, Emitter>([
 ]);
 
 /**
- * Every finding of the run, each family's in table order, each placed in its component
- * by the one step that numbers the components minted for subjects that fall with none.
+ * Every finding of the run the dials do not withhold, each family's in table order: every
+ * family's findings completed by one step, then withheld by one step, so a root one
+ * family reports withholds what another family reports in its component.
  */
-export function findingsOf(input: EmitterInput): readonly PlacedFinding[] {
-  return placed(
-    input.swept,
-    [...EMITTERS.values()].flatMap((emit) => emit(input)),
-  );
+export function findingsOf(input: EmitterInput): readonly CompletedFinding[] {
+  const found = [...EMITTERS.values()].flatMap((emit) => emit(input));
+  return reportable(completed(input, found), input.config.analysis.minConfidence);
 }

package/src/findings/interfaces.ts

@@ -1,4 +1,4 @@
-import type { Finding, FindingPosition } from "../finding.ts";
+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";
@@ -14,18 +14,6 @@ const UNUSED_DEAD_MESSAGE =
 const UNUSED_TEST_MESSAGE = "the interface is named as a type only from test files";
 const UNCALLED_MESSAGE = "no call site invokes or selects the method through the interface";
 
-/** One class a finding names as an implementation of its interface. */
-interface Implementation {
-  readonly ref: string;
-  readonly name: string;
-  readonly position: FindingPosition;
-}
-
-/** A finding of this family, with the implementations its details carry. */
-interface InterfaceFinding extends Finding {
-  readonly details: { readonly implementations: readonly Implementation[] };
-}
-
 /** Where one declaration is written, as a finding carries it. */
 function positionOf(symbol: InventorySymbol): FindingPosition {
   return { ...symbol.position, endLine: Math.max(symbol.position.line, symbol.endLine) };
@@ -44,7 +32,7 @@ function indexed(input: EmitterInput): {
   readonly symbolOf: (id: string) => InventorySymbol | undefined;
   readonly inTest: (id: string) => boolean;
   readonly candidateOf: (id: string) => Candidate | undefined;
-  readonly implementationsOf: (id: string) => readonly Implementation[];
+  readonly implementationsOf: (id: string) => readonly PositionedSymbol[];
 } {
   const union = input.swept.matrix.union;
   const symbols = new Map(union.symbols.map((symbol) => [symbol.id, symbol]));
@@ -70,8 +58,8 @@ function findingOf(
   code: string,
   symbol: InventorySymbol,
   message: string,
-  implementations: readonly Implementation[],
-): InterfaceFinding {
+  implementations: readonly PositionedSymbol[],
+): Finding {
   const position = positionOf(symbol);
   return {
     code,
@@ -96,7 +84,7 @@ function findingOf(
  */
 export const interfaces: Emitter = (input) => {
   const run = indexed(input);
-  const found: InterfaceFinding[] = [];
+  const found: Finding[] = [];
   for (const candidate of input.swept.sweep.candidates) {
     const symbol = run.symbolOf(candidate.id);
     if (symbol === undefined || run.inTest(candidate.id)) {