@cplieger/deadset-ts 3.5.0 → 3.6.0

package/src/findings/completion.ts

@@ -0,0 +1,151 @@
+/**
+ * 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.
+ */
+
+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 { 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>>;
+}
+
+/** The classes ranked by the claim each makes, the strongest highest. */
+export 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 {
+  return RANK[found] <= RANK[ceiling] ? found : ceiling;
+}
+
+/**
+ * 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 {
+  return (
+    config.severity.get(code) ?? config.severity.get(code.slice(0, FAMILY_KEY_LENGTH)) ?? fallback
+  );
+}
+
+/**
+ * The reachability class of one declaration of the run. A declaration of a library's
+ * published API has callers outside the target, and the run loads no consumer that
+ * would name them, so it is `possible`; every other declaration has every reference
+ * in the loaded program, a private member and a `#private` name among them, and is
+ * `certain`.
+ */
+export function reachabilityClasses(swept: RunSweep): (id: string) => Confidence {
+  const union = swept.matrix.union;
+  const published = new Set(
+    union.rooted
+      .filter((root) => root.kind === "published-api")
+      .map((root) => union.symbols[root.at]?.id),
+  );
+  return (id) => (published.has(id) ? "possible" : "certain");
+}
+
+/** 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 {
+  const held = new Map<string, Component>();
+  for (const component of swept.sweep.components) {
+    for (const member of component.members) {
+      held.set(member, component);
+    }
+  }
+  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,
+        };
+  };
+}
+
+/** 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.
+ */
+export function placed(swept: RunSweep, findings: readonly Finding[]): readonly PlacedFinding[] {
+  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 };
+    }
+    minted += 1;
+    return {
+      ...finding,
+      component: {
+        id: componentId(minted),
+        root: true,
+        symbolCount: 1,
+        deletableLines: finding.symbol.sizeLines,
+      },
+    };
+  });
+}
+
+/**
+ * The findings no dial withholds. A finding at `allow` or below the minimum confidence
+ * is withheld, and so is every finding of the component of a root the dials withhold,
+ * because a symbol that falls with a root is dead only through it and its deletion
+ * does not compile while the root stays. A withheld finding that is no root withholds
+ * itself alone.
+ */
+export function reportable(
+  findings: readonly CompletedFinding[],
+  minConfidence: Confidence,
+): readonly CompletedFinding[] {
+  const dialed = (finding: CompletedFinding): boolean =>
+    finding.severity === "allow" || RANK[finding.confidence] < RANK[minConfidence];
+  const components = new Set(
+    findings
+      .filter((finding) => finding.component.root && dialed(finding))
+      .map((finding) => finding.component.id),
+  );
+  return findings.filter((finding) => !dialed(finding) && !components.has(finding.component.id));
+}

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

@@ -1,4 +1,82 @@
+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
+ * runs outside anything the analysis reads, and every peer a needed package
+ * requires, which the target satisfies by declaring it.
+ */
+function neededBy(dependencies: Dependencies): ReadonlySet<string> {
+  const needed = new Set(dependencies.needed);
+  for (const [name, installed] of dependencies.installed) {
+    if (installed.command) {
+      needed.add(name);
+    }
+  }
+  const pending = [...needed];
+  for (let name = pending.pop(); name !== undefined; name = pending.pop()) {
+    for (const peer of dependencies.installed.get(name)?.peers ?? []) {
+      if (!needed.has(peer)) {
+        needed.add(peer);
+        pending.push(peer);
+      }
+    }
+  }
+  return needed;
+}
+
+/**
+ * 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.
+ */
+function unusedDependencies(config: Config, dependencies: Dependencies): UnusedDependencyFinding[] {
+  if (severityOf(config, UNUSED_DEPENDENCY, UNUSED_DEPENDENCY_SEVERITY) === "allow") {
+    return [];
+  }
+  const needed = neededBy(dependencies);
+  return dependencies.declared
+    .filter((dependency) => !needed.has(dependency.name))
+    .map((dependency) => ({
+      code: UNUSED_DEPENDENCY,
+      position: dependency.position,
+      symbol: {
+        ref: renderRef(dependencies.manifest, {
+          of: "dependency",
+          name: dependency.name,
+          section: dependency.section,
+        }),
+        kind: "dependency",
+        name: dependency.name,
+        sizeLines: 1,
+      },
+      message: MESSAGES[dependency.section],
+      details: { dependencyClass: dependency.section },
+    }));
+}
+
 /** The findings of the dependencies-and-module-machinery family, `DS1600` to `DS1699`. */
-export const dependenciesAndModuleMachinery: Emitter = () => [];
+export const dependenciesAndModuleMachinery: Emitter = ({ config, dependencies }) =>
+  unusedDependencies(config, dependencies);

package/src/findings/emitter.ts

@@ -1,12 +1,32 @@
 import type { RunSweep } from "../analysis.ts";
 import type { Config } from "../config.ts";
+import type { Dependencies } from "../dependencies.ts";
+import type { FileFacts } from "../file-facts.ts";
 import type { Finding } from "../finding.ts";
+import type { Implementations } from "../implementations.ts";
+import type { Stores } from "../stores.ts";
+import type { Boundary } from "./boundary.ts";
 
-/** What every emitter reads: the configuration the run resolved and the run's sweep. */
+/**
+ * What every emitter reads: the configuration the run resolved, the run's sweep, and
+ * the facts about the run each kind family reads beside the sweep.
+ */
 export interface EmitterInput {
   readonly config: Config;
   /** The production sweep a report is built from, beside the matrix it judged. */
   readonly swept: RunSweep;
+  /** The declarations carrying the deprecation marker in any configuration of the run. */
+  readonly deprecated: ReadonlySet<string>;
+  /** The stores into the run's declarations and the reads of them, which the sweep does not keep. */
+  readonly stores: Stores;
+  /** What the target's manifest declares, and what its projects need of it. */
+  readonly dependencies: Dependencies;
+  /** How the run's interfaces are implemented by its classes. */
+  readonly implementations: Implementations;
+  /** The target's files beside the sweep: the source tree, and what a program holds by inclusion. */
+  readonly files: FileFacts;
+  /** What can reach the target from outside it: consumers, declared edges, and `exports`. */
+  readonly boundary: Boundary;
 }
 
 /**

package/src/findings/emitters.ts

@@ -1,5 +1,6 @@
 import { dependenciesAndModuleMachinery } from "./dependencies-and-module-machinery.ts";
-import type { Emitter, Emitters } from "./emitter.ts";
+import { placed, type PlacedFinding } from "./completion.ts";
+import type { Emitter, EmitterInput, Emitters } from "./emitter.ts";
 import { interfaces } from "./interfaces.ts";
 import { intraFunction } from "./intra-function.ts";
 import { nonCodeArtifacts } from "./non-code-artifacts.ts";
@@ -19,3 +20,14 @@ export const EMITTERS: Emitters = new Map<string, Emitter>([
   ["self-check", selfCheck],
   ["intra-function", intraFunction],
 ]);
+
+/**
+ * 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.
+ */
+export function findingsOf(input: EmitterInput): readonly PlacedFinding[] {
+  return placed(
+    input.swept,
+    [...EMITTERS.values()].flatMap((emit) => emit(input)),
+  );
+}

package/src/findings/interfaces.ts

@@ -1,4 +1,150 @@
-import type { Emitter } from "./emitter.ts";
+import type { Finding, FindingPosition } from "../finding.ts";
+import type { InventorySymbol } from "../inventory.ts";
+import { byPosition } from "../position.ts";
+import type { Candidate } from "../sweep.ts";
+import type { Emitter, EmitterInput } from "./emitter.ts";
 
-/** The findings of the interfaces family, `DS1200` to `DS1299`. */
-export const interfaces: Emitter = () => [];
+const UNUSED_INTERFACE = "DS1201";
+const UNCALLED_INTERFACE_METHOD = "DS1203";
+
+/** What each finding says, by what the sweep found about the subject's references. */
+const UNUSED_MESSAGE = "nothing in the target names the interface as a type";
+const UNUSED_DEAD_MESSAGE =
+  "the interface is named as a type only from declarations that are themselves dead";
+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) };
+}
+
+/** Two strings ordered bytewise. */
+function compare(a: string, b: string): number {
+  if (a === b) {
+    return 0;
+  }
+  return a < b ? -1 : 1;
+}
+
+/** One run's declarations and candidates, indexed for the two kinds. */
+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[];
+} {
+  const union = input.swept.matrix.union;
+  const symbols = new Map(union.symbols.map((symbol) => [symbol.id, symbol]));
+  const candidates = new Map(
+    input.swept.sweep.candidates.map((candidate) => [candidate.id, candidate]),
+  );
+  const symbolOf = (id: string): InventorySymbol | undefined => symbols.get(id);
+  return {
+    symbolOf,
+    inTest: (id) => union.test[union.at(id)] === true,
+    candidateOf: (id) => candidates.get(id),
+    implementationsOf: (id) =>
+      [...(input.implementations.classes.get(id) ?? [])]
+        .map(symbolOf)
+        .filter((symbol): symbol is InventorySymbol => symbol !== undefined)
+        .map((symbol) => ({ ref: symbol.ref, name: symbol.name, position: positionOf(symbol) }))
+        .sort((a, b) => byPosition(a.position, b.position) || compare(a.ref, b.ref)),
+  };
+}
+
+/** The finding one code makes about one declaration. */
+function findingOf(
+  code: string,
+  symbol: InventorySymbol,
+  message: string,
+  implementations: readonly Implementation[],
+): InterfaceFinding {
+  const position = positionOf(symbol);
+  return {
+    code,
+    position,
+    symbol: {
+      ref: symbol.ref,
+      kind: symbol.kind,
+      name: symbol.name,
+      sizeLines: position.endLine - position.line + 1,
+    },
+    message,
+    details: { implementations },
+  };
+}
+
+/**
+ * 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.
+ */
+export const interfaces: Emitter = (input) => {
+  const run = indexed(input);
+  const found: InterfaceFinding[] = [];
+  for (const candidate of input.swept.sweep.candidates) {
+    const symbol = run.symbolOf(candidate.id);
+    if (symbol === undefined || run.inTest(candidate.id)) {
+      continue;
+    }
+    if (symbol.kind === "interface") {
+      found.push(
+        findingOf(
+          UNUSED_INTERFACE,
+          symbol,
+          unusedMessage(candidate),
+          run.implementationsOf(candidate.id),
+        ),
+      );
+      continue;
+    }
+    if (
+      symbol.kind !== "interface-method" ||
+      candidate.productionRefs + candidate.testRefs > 0 ||
+      run.candidateOf(symbol.parent) !== undefined ||
+      marker(input, candidate.id)
+    ) {
+      continue;
+    }
+    found.push(
+      findingOf(
+        UNCALLED_INTERFACE_METHOD,
+        symbol,
+        UNCALLED_MESSAGE,
+        run.implementationsOf(symbol.parent),
+      ),
+    );
+  }
+  return found;
+};
+
+/** What one unused interface's finding says, by the references the sweep counted. */
+function unusedMessage(candidate: Candidate): string {
+  if (candidate.relation === "reachability") {
+    return UNUSED_DEAD_MESSAGE;
+  }
+  return candidate.testRefs > 0 && candidate.productionRefs === 0
+    ? UNUSED_TEST_MESSAGE
+    : UNUSED_MESSAGE;
+}
+
+/** Whether one interface method has implementations and every one has an empty body. */
+function marker(input: EmitterInput, method: string): boolean {
+  const bodies = [...(input.implementations.bodies.get(method)?.values() ?? [])];
+  return bodies.length > 0 && bodies.every((empty) => empty);
+}

package/src/findings/non-code-artifacts.ts

@@ -1,4 +1,126 @@
-import type { Emitter } from "./emitter.ts";
+import type { Config } from "../config.ts";
+import type { Finding } from "../finding.ts";
+import type { Graph } from "../graph.ts";
+import type { Emitter, EmitterInput } from "./emitter.ts";
+
+const FILE_NEVER_BUILT = "DS1501";
+const FILE_NEVER_IMPORTED = "DS1502";
+
+/** The subject kind of a finding about a source file, from the finding schema's vocabulary. */
+const FILE_SUBJECT = "file";
+
+/** A file's subject starts at its first character. */
+const FILE_START = 1;
+
+/**
+ * Whether the configuration declares the run's matrix complete. The declaration is
+ * about the projects the configuration lists, so a configuration declaring
+ * completeness and listing no project declares it of a matrix the run derived, and a
+ * derived matrix is never complete.
+ */
+function completeMatrix(config: Config): boolean {
+  return (
+    config.analysis.matrixComplete &&
+    config.analysis.configurations.some((entry) => entry.shape === "project")
+  );
+}
+
+/** One finding about a whole file. */
+function fileFinding(
+  code: string,
+  file: { readonly path: string; readonly ref: string; readonly endLine: number },
+  message: string,
+): Finding {
+  return {
+    code,
+    position: { path: file.path, line: FILE_START, column: FILE_START, endLine: file.endLine },
+    symbol: { ref: file.ref, kind: FILE_SUBJECT, name: file.path, sizeLines: file.endLine },
+    message,
+  };
+}
+
+/**
+ * Every source file below the target root that no project of the matrix includes,
+ * under a matrix the configuration declares complete: that declaration says the listed
+ * projects are every one the target builds, so a file none of them includes is built
+ * by nothing. Under a derived matrix nothing is reported, because a project the
+ * derivation did not find is no evidence that nothing builds the file.
+ */
+function fileNeverBuilt({ config, swept, files }: EmitterInput): readonly Finding[] {
+  if (!completeMatrix(config)) {
+    return [];
+  }
+  const built = new Set(
+    swept.matrix.union.symbols
+      .filter((symbol) => symbol.kind === FILE_SUBJECT)
+      .map((symbol) => symbol.position.path),
+  );
+  const message = `no project of the build matrix includes this file (${swept.matrix.configurations.join(", ")})`;
+  return files.tree
+    .filter((file) => !built.has(file.path))
+    .map((file) => fileFinding(FILE_NEVER_BUILT, file, message));
+}
+
+/**
+ * The paths of every file a reference written in another file reaches, naming the
+ * file or a declaration in it. An import is such a reference, so an import from any
+ * file reaches what it names, whatever reaches the importing file.
+ */
+function reachedFromOutside(union: Graph): ReadonlySet<string> {
+  const reached = new Set<string>();
+  union.out.forEach((edges, from) => {
+    const fromPath = union.symbols[from]?.position.path;
+    for (const edge of edges) {
+      const to = union.symbols[edge.to];
+      if (to !== undefined && to.position.path !== fromPath) {
+        reached.add(to.position.path);
+      }
+    }
+  });
+  return reached;
+}
+
+/**
+ * The paths of the files an import reaches, a root names, or a declared edge names a
+ * declaration in. A file holding a declaration the sweep judged live is kept whatever
+ * held it live, and so is a file a program holds by inclusion, which acts on every
+ * file of the program without an import naming it.
+ */
+function keptFiles({ swept, files, boundary }: EmitterInput): ReadonlySet<string> {
+  const union = swept.matrix.union;
+  const edgeNamed = new Set(boundary.edges.map((side) => side.symbol));
+  const dead = new Set(swept.sweep.candidates.map((candidate) => candidate.id));
+  const kept = new Set([...reachedFromOutside(union), ...files.heldByInclusion]);
+  for (const root of union.rooted) {
+    const named = union.symbols[root.at];
+    if (named !== undefined) {
+      kept.add(named.position.path);
+    }
+  }
+  for (const symbol of union.symbols) {
+    if ((symbol.kind !== FILE_SUBJECT && !dead.has(symbol.id)) || edgeNamed.has(symbol.ref)) {
+      kept.add(symbol.position.path);
+    }
+  }
+  return kept;
+}
+
+/** Every file of the run that no import reaches and no root or edge names. */
+function fileNeverImported(input: EmitterInput): readonly Finding[] {
+  const kept = keptFiles(input);
+  return input.swept.matrix.union.symbols
+    .filter((symbol) => symbol.kind === FILE_SUBJECT && !kept.has(symbol.position.path))
+    .map((symbol) =>
+      fileFinding(
+        FILE_NEVER_IMPORTED,
+        { path: symbol.position.path, ref: symbol.ref, endLine: symbol.endLine },
+        "no import reaches this file and no root names it or a declaration in it",
+      ),
+    );
+}
 
 /** The findings of the non-code-artifacts family, `DS1500` to `DS1599`. */
-export const nonCodeArtifacts: Emitter = () => [];
+export const nonCodeArtifacts: Emitter = (input) => [
+  ...fileNeverBuilt(input),
+  ...fileNeverImported(input),
+];