@cplieger/deadset-ts 3.5.0 → 3.7.0

package/src/findings/completion.ts

@@ -0,0 +1,163 @@
+/**
+ * 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 { 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 { EmitterInput } from "./emitter.ts";
+
+/** The classes ranked by the claim each makes, the strongest highest. */
+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. */
+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.
+ */
+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`.
+ */
+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. */
+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,
+        };
+  };
+}
+
+/**
+ * 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 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);
+  let minted = swept.sweep.components.length;
+
+  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`);
+    }
+    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 ?? {},
+    };
+  });
+}
+
+/**
+ * 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,67 @@
+import 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";
+
+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",
+};
+
+/**
+ * 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.
+ */
+function unusedDependencies(dependencies: Dependencies): Finding[] {
+  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 = ({ dependencies }) =>
+  unusedDependencies(dependencies);

package/src/findings/emitter.ts

@@ -1,17 +1,38 @@
 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;
 }
 
 /**
- * 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,7 @@
 import { dependenciesAndModuleMachinery } from "./dependencies-and-module-machinery.ts";
-import type { Emitter, Emitters } from "./emitter.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";
 import { nonCodeArtifacts } from "./non-code-artifacts.ts";
@@ -19,3 +21,13 @@ export const EMITTERS: Emitters = new Map<string, Emitter>([
   ["self-check", selfCheck],
   ["intra-function", intraFunction],
 ]);
+
+/**
+ * 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 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,138 @@
-import type { Emitter } from "./emitter.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";
+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";
+
+/** 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 PositionedSymbol[];
+} {
+  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 PositionedSymbol[],
+): Finding {
+  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: Finding[] = [];
+  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),
+];