@cplieger/deadset-ts 3.6.0 → 3.8.0

package/src/findings/self-check.ts

@@ -1,4 +1,207 @@
+import { REPOSITORY_DOCUMENT } from "../config.ts";
+import type { Finding } from "../finding.ts";
+import type { InventorySymbol } from "../inventory.ts";
+import type { Position } from "../position.ts";
+import {
+  STALE_SUPPRESSION,
+  SUPPRESSION_WITHOUT_REASON,
+  type Mechanism,
+  type Refusal,
+  type SuppressionRecord,
+} from "../suppress.ts";
 import type { Emitter } from "./emitter.ts";
 
-/** The findings of the self-check family, `DS1700` to `DS1799`. */
-export const selfCheck: Emitter = () => [];
+/** The code a configured root that matches nothing is reported under. */
+const UNMATCHED_ROOT = "DS1704";
+
+/** The subject kind of a finding about a suppression record. */
+const SUPPRESSION_SUBJECT = "suppression";
+
+/** The subject kind of a finding about a configured root. */
+const ROOT_SUBJECT = "root";
+
+/** The fixed position of a finding about a document rather than about a line of one. */
+const DOCUMENT_POSITION = 1;
+
+/** One record no finding matched, and the codes its declaration reports instead. */
+export interface StaleRecord {
+  readonly record: SuppressionRecord;
+  /** The codes the bound declaration would report, none of them the record's own. */
+  readonly reports: readonly string[];
+}
+
+/** What the self-check family reads: the run's refused suppressions and its configured roots. */
+export interface SelfCheckFacts {
+  /** The suppressions the grammar refused with a finding, in reading order. */
+  readonly refusals: readonly Refusal[];
+  /** Every configured root or pattern that matched nothing in any project. */
+  readonly unmatchedRoots: readonly string[];
+  /** The document below the target root that declared the roots, empty where none did. */
+  readonly rootsDocument: string;
+}
+
+/** A run with nothing for the self-check family to report. */
+export const NO_SELF_CHECK: SelfCheckFacts = {
+  refusals: [],
+  unmatchedRoots: [],
+  rootsDocument: "",
+};
+
+/** The words a message names a mechanism by. */
+const WRITTEN: Readonly<Record<Mechanism, string>> = {
+  inline: "inline directive",
+  ignore: "ignore entry",
+  baseline: "baseline row",
+};
+
+/** The file references of a run's declarations, by path. */
+export function fileRefsOf(symbols: readonly InventorySymbol[]): FileRefs {
+  const byPath = new Map(
+    symbols
+      .filter((symbol) => symbol.kind === "file")
+      .map((symbol) => [symbol.position.path, symbol.ref]),
+  );
+  return (path) => byPath.get(path);
+}
+
+/** A list of codes as a sentence names them. */
+function spelled(codes: readonly string[]): string {
+  if (codes.length < 2) {
+    return codes.join("");
+  }
+  return `${codes.slice(0, -1).join(", ")} and ${codes.at(-1) ?? ""}`;
+}
+
+/** A finding about one suppression, at the suppression's own site. */
+function aboutSuppression(code: string, ref: string, site: Position, message: string): Finding {
+  return {
+    code,
+    position: { ...site, endLine: site.line },
+    symbol: { ref, kind: SUPPRESSION_SUBJECT, name: ref, sizeLines: 1 },
+    message,
+  };
+}
+
+/** Each file of the run by its path, as the reference of the file it is. */
+export type FileRefs = (path: string) => string | undefined;
+
+/**
+ * The reference a finding about a suppression names: the symbol it names or bound, else
+ * the file form of the document that holds it, else that document's path.
+ */
+function suppressionRef(symbol: string, path: string, files: FileRefs): string {
+  return symbol === "" ? (files(path) ?? path) : symbol;
+}
+
+/** One finding per refused suppression: the grammar's reason refusal and its scope refusal. */
+export function refusedSuppressions(
+  refusals: readonly Refusal[],
+  files: FileRefs,
+): readonly Finding[] {
+  return refusals.map((refused) =>
+    aboutSuppression(
+      refused.reported,
+      suppressionRef(refused.symbol, refused.path, files),
+      refused.site,
+      `${WRITTEN[refused.mechanism]} for ${refused.code} ${
+        refused.reported === SUPPRESSION_WITHOUT_REASON
+          ? "carries no reason"
+          : "names a symbol and no path"
+      }`,
+    ),
+  );
+}
+
+/** One stale suppression as the report's stale-suppression record carries it. */
+export interface StaleSuppression {
+  readonly code: typeof STALE_SUPPRESSION;
+  readonly mechanism: Mechanism;
+  readonly entry: {
+    readonly code: string;
+    readonly symbol?: string;
+    readonly path: string;
+    readonly reason: string;
+  };
+  readonly position: Position;
+  readonly symbol: string;
+  readonly message: string;
+}
+
+/**
+ * One record per site at which a suppression matched nothing, whatever the number of
+ * codes or declarations written there: the first record names the entry, and the message
+ * names every code the site's records named and every code the declaration reports
+ * instead, so the maintainer corrects the code rather than hunting for it.
+ */
+export function staleSuppressions(
+  stale: readonly StaleRecord[],
+  files: FileRefs,
+): readonly StaleSuppression[] {
+  const bySite = new Map<string, { first: SuppressionRecord; records: StaleRecord[] }>();
+  for (const one of stale) {
+    const { site, mechanism } = one.record;
+    const key = `${mechanism}\u0000${site.path}\u0000${String(site.line)}\u0000${String(site.column)}`;
+    const held = bySite.get(key) ?? { first: one.record, records: [] };
+    held.records.push(one);
+    bySite.set(key, held);
+  }
+  return [...bySite.values()].map(({ first, records }) => {
+    const codes = [...new Set(records.map((one) => one.record.code))].sort();
+    const reports = [...new Set(records.flatMap((one) => one.reports))]
+      .filter((code) => !codes.includes(code))
+      .sort();
+    const instead = reports.length === 0 ? "" : `, and its declaration reports ${spelled(reports)}`;
+    return {
+      code: STALE_SUPPRESSION,
+      mechanism: first.mechanism,
+      entry: {
+        code: first.code,
+        ...(first.symbol === "" ? {} : { symbol: first.symbol }),
+        path: first.path,
+        reason: first.reason,
+      },
+      position: first.site,
+      symbol: suppressionRef(first.symbol, first.path, files),
+      message: `${WRITTEN[first.mechanism]} for ${spelled(codes)} matches no current finding${instead}`,
+    };
+  });
+}
+
+/**
+ * One finding per configured root or pattern that named nothing in any project. A finding
+ * names the document that declared the roots, or the conventional repository configuration
+ * where no document of the target did, and every finding of one run sits at that
+ * document's first position: the roots are an array whose members carry no line of their
+ * own, so the string each finding names tells one from another.
+ */
+export function unmatchedRootFindings(
+  sources: readonly string[],
+  document: string,
+): readonly Finding[] {
+  const position = {
+    path: document === "" ? REPOSITORY_DOCUMENT : document,
+    line: DOCUMENT_POSITION,
+    column: DOCUMENT_POSITION,
+    endLine: DOCUMENT_POSITION,
+  };
+  return sources.map((source) => ({
+    code: UNMATCHED_ROOT,
+    position,
+    symbol: { ref: source, kind: ROOT_SUBJECT, name: source, sizeLines: 1 },
+    message:
+      source.includes("*") || source.includes("?")
+        ? "configured root pattern matches no symbol of the inventory"
+        : "configured root matches no symbol of the inventory",
+  }));
+}
+
+/**
+ * The findings of the self-check family, `DS1700` to `DS1799`: a suppression refused for
+ * carrying no reason or naming no path, and a configured root that named nothing. A
+ * suppression that matched nothing is a record of the report's stale suppressions, which
+ * {@link staleSuppressions} builds, and a stale cross-language edge is the merge's to report.
+ */
+export const selfCheck: Emitter = ({ selfCheck: facts, swept }) => [
+  ...refusedSuppressions(facts.refusals, fileRefsOf(swept.matrix.union.symbols)),
+  ...unmatchedRootFindings(facts.unmatchedRoots, facts.rootsDocument),
+];

package/src/findings/unused-declarations.ts

@@ -1,33 +1,9 @@
-import type { Confidence, Severity } from "../config.ts";
+import type { Finding } from "../finding.ts";
 import type { InventorySymbol, SymbolKind } from "../inventory.ts";
 import type { MatrixCandidate } from "../matrix.ts";
-import {
-  capped,
-  findingComponents,
-  reachabilityClasses,
-  reportable,
-  severityOf,
-  type CompletedFinding,
-} from "./completion.ts";
-import type { Emitter, EmitterInput } from "./emitter.ts";
+import type { Emitter } from "./emitter.ts";
 import { unreachableExports } from "./visibility-narrowing.ts";
 
-/** What the issue-kind vocabulary states about one code of the family. */
-interface KindRow {
-  readonly defaultSeverity: Severity;
-  readonly maxClass: Confidence;
-}
-
-/** The codes of the unused-declarations family, each by its row of the vocabulary. */
-export const UNUSED_DECLARATION_KINDS: ReadonlyMap<string, KindRow> = new Map([
-  ["DS1001", { defaultSeverity: "deny", maxClass: "certain" }],
-  ["DS1002", { defaultSeverity: "deny", maxClass: "certain" }],
-  ["DS1003", { defaultSeverity: "deny", maxClass: "certain" }],
-  ["DS1004", { defaultSeverity: "deny", maxClass: "certain" }],
-  ["DS1005", { defaultSeverity: "deny", maxClass: "certain" }],
-  ["DS1006", { defaultSeverity: "deny", maxClass: "certain" }],
-]);
-
 /** The kinds of declaration that are members of a class, an interface, a type or an enum. */
 const MEMBERS: ReadonlySet<SymbolKind> = new Set([
   "method",
@@ -160,20 +136,14 @@ function messageOf(code: string, judged: Judged): string {
   return `${subject} has no reference in the target`;
 }
 
-/**
- * The findings of the unused-declarations family, `DS1000` to `DS1099`, completed and
- * with what the dials withhold left out.
- */
-export function unusedDeclarationFindings(input: EmitterInput): readonly CompletedFinding[] {
-  const { config, swept } = input;
-  const union = swept.matrix.union;
-  const dead = new Set(swept.sweep.candidates.map((candidate) => candidate.id));
-  const classOf = reachabilityClasses(swept);
-  const componentOf = findingComponents(swept);
+/** The findings of the unused-declarations family, `DS1000` to `DS1099`. */
+export const unusedDeclarations: Emitter = (input) => {
+  const union = input.swept.matrix.union;
+  const dead = new Set(input.swept.sweep.candidates.map((candidate) => candidate.id));
   const unreachable = unreachableExports(input);
 
-  const found: CompletedFinding[] = [];
-  for (const candidate of swept.sweep.candidates) {
+  const found: Finding[] = [];
+  for (const candidate of input.swept.sweep.candidates) {
     const at = union.at(candidate.id);
     const symbol = union.symbols[at];
     if (symbol === undefined) {
@@ -188,16 +158,10 @@ export function unusedDeclarationFindings(input: EmitterInput): readonly Complet
       unreachable: unreachable.has(symbol.id),
     };
     const code = codeOf(judged);
-    const row = code === undefined ? undefined : UNUSED_DECLARATION_KINDS.get(code);
-    if (code === undefined || row === undefined) {
+    if (code === undefined) {
       continue;
     }
-    const component = componentOf(symbol.id);
-    if (component === undefined) {
-      throw new Error(`${symbol.id} is reported dead and falls in no dead component`);
-    }
     const endLine = Math.max(symbol.position.line, symbol.endLine);
-    const reachabilityClass = classOf(symbol.id);
     found.push({
       code,
       position: { ...symbol.position, endLine },
@@ -208,18 +172,7 @@ export function unusedDeclarationFindings(input: EmitterInput): readonly Complet
         sizeLines: endLine - symbol.position.line + 1,
       },
       message: messageOf(code, judged),
-      reachabilityClass,
-      confidence: capped(reachabilityClass, row.maxClass),
-      livenessRelation: candidate.relation,
-      testOnly: candidate.productionRefs === 0 && candidate.testRefs > 0,
-      component,
-      configurations: candidate.configurations,
-      severity: severityOf(config, code, row.defaultSeverity),
-      details: {},
     });
   }
-  return reportable(found, config.analysis.minConfidence);
-}
-
-/** The findings of the unused-declarations family, `DS1000` to `DS1099`. */
-export const unusedDeclarations: Emitter = unusedDeclarationFindings;
+  return found;
+};

package/src/findings/visibility-narrowing.ts

@@ -3,7 +3,6 @@ import { OUTSIDE, type Graph } from "../graph.ts";
 import type { InventorySymbol, SymbolKind } from "../inventory.ts";
 import type { MatrixCandidate } from "../matrix.ts";
 import type { RootKind } from "../roots.ts";
-import type { PendingFinding } from "./boundary.ts";
 import type { Emitter, EmitterInput } from "./emitter.ts";
 import { writeOnlyDeclarations } from "./reads-and-writes.ts";
 
@@ -33,13 +32,6 @@ const WORDS: Partial<Readonly<Record<SymbolKind, string>>> = {
   "export-alias": "re-export",
 };
 
-/** What the family found: the findings it reports, and those a declared edge holds pending. */
-export interface Narrowings {
-  readonly findings: readonly Finding[];
-  /** Ordered by edge, then by side. */
-  readonly pending: readonly PendingFinding[];
-}
-
 /** Per declaration of the run, the facts both rules read. */
 interface Facts {
   readonly graph: Graph;
@@ -126,18 +118,13 @@ function wordOf(symbol: InventorySymbol): string {
   return WORDS[symbol.kind] ?? symbol.kind;
 }
 
-/** A finding of this family, with the visibility a narrowing would give its subject. */
-interface NarrowingFinding extends Finding {
-  readonly details: { readonly narrowerVisibility?: "file" | "package" };
-}
-
 /** The visibility each narrowing code names, which only the narrowing codes carry. */
 const NARROWER: Readonly<Record<string, "file" | "package">> = {
   [REDUNDANT_EXPORT_KEYWORD]: "file",
   [UNNECESSARY_EXPORT]: "package",
 };
 
-function findingOf(symbol: InventorySymbol, code: string, message: string): NarrowingFinding {
+function findingOf(symbol: InventorySymbol, code: string, message: string): Finding {
   const { path, line, column } = symbol.position;
   const narrower = Object.hasOwn(NARROWER, code) ? NARROWER[code] : undefined;
   const endLine = Math.max(line, symbol.endLine);
@@ -241,26 +228,15 @@ function unreachable(
   );
 }
 
-/** Two strings ordered bytewise. */
-function compare(a: string, b: string): number {
-  if (a === b) {
-    return 0;
-  }
-  return a < b ? -1 : 1;
-}
-
 /**
- * The visibility-narrowing family over one run: `DS1101`, `DS1103` and `DS1104`.
- *
- * A finding about a symbol a declared cross-language edge names is pending instead of
- * reported, once per side naming it: the edge counts as a reference from outside the
- * file and the package, and whether it is a use is decided on the side in the other
- * language.
+ * The visibility-narrowing family over one run: `DS1101`, `DS1103` and `DS1104`. A finding
+ * about a symbol a declared cross-language edge names is reported here like any other, and
+ * the edge's evaluation then holds it pending, because the edge stands for a reference from
+ * outside the file and the package whose use is decided in the other language.
  */
-export function narrowings(input: EmitterInput): Narrowings {
-  const { boundary } = input;
+export function narrowings(input: EmitterInput): readonly Finding[] {
   const facts = factsOf(input.swept.matrix.union);
-  const { declared, loaded } = boundary.consumers;
+  const { declared, loaded } = input.boundary.consumers;
   const closed = input.config.consumersComplete && declared.every((id) => loaded.includes(id));
   const world = { closed, writeOnly: writeOnlyDeclarations(input) };
   const candidates = new Map(
@@ -268,27 +244,17 @@ export function narrowings(input: EmitterInput): Narrowings {
   );
 
   const findings: Finding[] = [];
-  const pending: PendingFinding[] = [];
   facts.graph.symbols.forEach((symbol, at) => {
     const candidate = candidates.get(symbol.id);
     const found =
       candidate === undefined
         ? narrowing(facts, at, symbol, world)
         : unreachable(facts, at, symbol, candidate, input);
-    if (found === undefined) {
-      return;
-    }
-    const named = boundary.edges.filter((side) => side.symbol === symbol.ref);
-    if (named.length === 0) {
+    if (found !== undefined) {
       findings.push(found);
-      return;
-    }
-    for (const side of named) {
-      pending.push({ ...side, finding: found });
     }
   });
-  pending.sort((a, b) => compare(a.edge, b.edge) || compare(a.side, b.side));
-  return { findings, pending };
+  return findings;
 }
 
 /**
@@ -308,18 +274,5 @@ export function unreachableExports(input: EmitterInput): ReadonlySet<string> {
   return found;
 }
 
-/**
- * The findings of the visibility-narrowing family, `DS1100` to `DS1199`. A finding a
- * declared edge holds pending belongs in that edge's evaluation, which this analyzer
- * does not publish yet, so a run that holds one is refused rather than reported
- * without it.
- */
-export const visibilityNarrowing: Emitter = (input) => {
-  const { findings, pending } = narrowings(input);
-  if (pending.length > 0) {
-    throw new Error(
-      `${String(pending.length)} finding(s) a declared edge holds pending, and no edge evaluation is published`,
-    );
-  }
-  return findings;
-};
+/** The findings of the visibility-narrowing family, `DS1100` to `DS1199`. */
+export const visibilityNarrowing: Emitter = narrowings;

package/src/findings-pass.ts

@@ -0,0 +1,145 @@
+/**
+ * The findings pass over one run: the emitter table's findings with the suppressions
+ * applied and the declared edges evaluated, and the stale suppressions, the totals and the
+ * verdict a report carries beside them.
+ */
+
+import type { AnalysisInputs } from "./analysis.ts";
+import type { Config, Severity } from "./config.ts";
+import type { EdgeEvaluation } from "./edges.ts";
+import type { CompletedFinding, Finding } from "./finding.ts";
+import { decidedFindings } from "./findings/emitters.ts";
+import {
+  fileRefsOf,
+  staleSuppressions,
+  type StaleRecord,
+  type StaleSuppression,
+} from "./findings/self-check.ts";
+import { isRowSubject, pairs, suppressionCounts, type Ledger } from "./suppress.ts";
+import type { Provenance, Recorded } from "./suppress-file.ts";
+import { EXIT_CLEAN, EXIT_FINDINGS } from "./verbs/verb.ts";
+
+/** The counts a report's totals carry beside its findings. */
+export interface PassTotals {
+  readonly suppressionsInEffect: number;
+  readonly reasonsRecorded: number;
+  readonly staleSuppressions: number;
+  /** The evaluations that hold a finding pending. */
+  readonly pending: number;
+}
+
+/** What the pass answers about one run. */
+export interface PassResult {
+  /** Every finding the report publishes, in the canonical order. */
+  readonly findings: readonly CompletedFinding[];
+  /** One record per site at which a suppression matched nothing, in reading order. */
+  readonly staleSuppressions: readonly StaleSuppression[];
+  /** One evaluation per declared edge side of this language. */
+  readonly edgeEvaluations: readonly EdgeEvaluation<CompletedFinding>[];
+  readonly totals: PassTotals;
+  /** What every suppression record did, in reading order. */
+  readonly ledger: Ledger<CompletedFinding>;
+}
+
+/** The exit code of a report holding at least one pending finding. */
+export const EXIT_PENDING = 4;
+
+/** The severities ranked, the strongest highest. */
+const SEVERITY_RANK: Readonly<Record<Severity, number>> = { allow: 0, warn: 1, deny: 2 };
+
+/** Two strings ordered bytewise. */
+function compare(a: string, b: string): number {
+  if (a === b) {
+    return 0;
+  }
+  return a < b ? -1 : 1;
+}
+
+/** The canonical order: path, line, column, code, then the symbol reference. */
+function canonical(a: Finding, b: Finding): number {
+  return (
+    compare(a.position.path, b.position.path) ||
+    a.position.line - b.position.line ||
+    a.position.column - b.position.column ||
+    compare(a.code, b.code) ||
+    compare(a.symbol.ref, b.symbol.ref)
+  );
+}
+
+/**
+ * The pass over one run. The emitter table decides every record against every finding the
+ * run would produce with no record there, withholds what the records claim, and evaluates
+ * the declared edges; a stale record then names the codes its declaration reports instead.
+ */
+export function findingsPass(inputs: AnalysisInputs): PassResult {
+  const { marked, unmarked, suppressions } = inputs;
+  const decided = decidedFindings(marked, { unmarked, records: suppressions.records });
+  const { ledger, would } = decided;
+
+  const stale: StaleRecord[] = [];
+  suppressions.records.forEach((record, at) => {
+    if (ledger.verdicts[at] !== "stale") {
+      return;
+    }
+    const reports = would
+      .filter(
+        (finding) =>
+          finding.code !== record.code && pairs({ ...record, code: finding.code }, finding),
+      )
+      .map((finding) => finding.code);
+    stale.push({ record, reports });
+  });
+
+  const records = staleSuppressions(stale, fileRefsOf(marked.swept.matrix.union.symbols));
+  const counts = suppressionCounts(suppressions.records, ledger);
+  return {
+    findings: [...decided.findings].sort(canonical),
+    staleSuppressions: records,
+    edgeEvaluations: decided.evaluations,
+    totals: {
+      suppressionsInEffect: counts.inEffect,
+      reasonsRecorded: counts.reasonsRecorded,
+      staleSuppressions: records.length,
+      pending: decided.evaluations.filter((one) => one.finding !== undefined).length,
+    },
+    ledger,
+  };
+}
+
+/**
+ * The exit code of a report the pass answered: pending when an evaluation holds a finding,
+ * which outranks the rest because an unmerged report is not an answer; findings when a
+ * suppression is stale or a finding's severity reaches the configured failing severity;
+ * clean otherwise.
+ */
+export function verdictOf(result: PassResult, config: Config): number {
+  if (result.totals.pending > 0) {
+    return EXIT_PENDING;
+  }
+  if (result.totals.staleSuppressions > 0) {
+    return EXIT_FINDINGS;
+  }
+  const failing = SEVERITY_RANK[config.reporters.failOn];
+  const fails = result.findings.some((finding) => SEVERITY_RANK[finding.severity] >= failing);
+  return fails ? EXIT_FINDINGS : EXIT_CLEAN;
+}
+
+/**
+ * The findings of a report as a baseline records them, in report order. A finding about a
+ * row of a document is not recorded: no record withholds one, so a row recording it would
+ * be stale on the first read back.
+ */
+export function recordedFindings(result: PassResult): readonly Recorded[] {
+  return result.findings
+    .filter((finding) => !isRowSubject(finding.symbol.kind))
+    .map((finding) => ({
+      code: finding.code,
+      symbol: finding.symbol.ref,
+      path: finding.position.path,
+    }));
+}
+
+/** The analyzer identity a baseline this analyzer writes names as its rows' provenance. */
+export function analyzerProvenance(version: string): Provenance {
+  return { analyzer: "deadset-ts", version };
+}