@cplieger/deadset-ts 3.7.0 → 3.9.0

package/src/findings/boundary.ts

@@ -1,5 +1,3 @@
-import type { Finding } from "../finding.ts";
-
 /** Which side of a declared cross-language edge, as the edges document spells it. */
 export type EdgeSideName = "provides" | "used_by";
 
@@ -12,15 +10,6 @@ export interface EdgeSide {
   readonly symbol: string;
 }
 
-/**
- * One finding a declared edge holds back: the finding the analyzer would report about
- * the symbol one side of the edge names, which a report carries only inside that side's
- * evaluation, because the code that may use the symbol is in the other language.
- */
-export interface PendingFinding extends EdgeSide {
-  readonly finding: Finding;
-}
-
 /** What the run knows about the code outside the target that can reach its declarations. */
 export interface Boundary {
   readonly consumers: {

package/src/findings/completion.ts

@@ -11,6 +11,7 @@ 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 { isRowSubject, type Dials } from "../suppress.ts";
 import type { EmitterInput } from "./emitter.ts";
 
 /** The classes ranked by the claim each makes, the strongest highest. */
@@ -74,7 +75,8 @@ function findingComponents(swept: RunSweep): (id: string) => FindingComponent |
  * 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.
+ * numbered past the computed ones in finding order, so no two families mint one; nothing
+ * falls with it, so its deletion removes no line.
  */
 export function completed(
   input: EmitterInput,
@@ -93,7 +95,11 @@ export function completed(
     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;
+    // A row's reference may spell a declaration's, as an ignore entry naming one does, and
+    // a row is still never the declaration.
+    const at = isRowSubject(finding.symbol.kind)
+      ? OUTSIDE
+      : (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);
@@ -108,7 +114,7 @@ export function completed(
         id: componentId(minted),
         root: true,
         symbolCount: 1,
-        deletableLines: finding.symbol.sizeLines,
+        deletableLines: 0,
       };
     }
     const counts =
@@ -141,23 +147,56 @@ export function completed(
   });
 }
 
+/** Whether the dials withhold a finding by its own severity or confidence. */
+function dialed(
+  finding: Pick<CompletedFinding, "severity" | "confidence">,
+  minConfidence: Confidence,
+): boolean {
+  return finding.severity === "allow" || RANK[finding.confidence] < RANK[minConfidence];
+}
+
 /**
- * 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.
+ * The configuration's dials over one run's completed findings. 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. A code is withheld from a declaration when the finding it
+ * would report there, completed, is withheld by its own severity or confidence.
  */
-export function reportable(
+export function dialsOf(
+  input: EmitterInput,
   findings: readonly CompletedFinding[],
-  minConfidence: Confidence,
-): readonly CompletedFinding[] {
-  const dialed = (finding: CompletedFinding): boolean =>
-    finding.severity === "allow" || RANK[finding.confidence] < RANK[minConfidence];
+): Dials<CompletedFinding> {
+  const minConfidence = input.config.analysis.minConfidence;
+  const classOf = reachabilityClasses(input.swept);
   const components = new Set(
     findings
-      .filter((finding) => finding.component.root && dialed(finding))
+      .filter((finding) => finding.component.root && dialed(finding, minConfidence))
       .map((finding) => finding.component.id),
   );
-  return findings.filter((finding) => !dialed(finding) && !components.has(finding.component.id));
+  return {
+    withholdsCode: (code, id) => {
+      const row = KINDS.get(code);
+      return (
+        row !== undefined &&
+        dialed(
+          {
+            severity: severityOf(input.config, code, row.defaultSeverity),
+            confidence: capped(classOf(id), row.maxClass),
+          },
+          minConfidence,
+        )
+      );
+    },
+    withholds: (finding) => dialed(finding, minConfidence) || components.has(finding.component.id),
+  };
+}
+
+/** The findings of one run's completed findings that no dial withholds, in the order given. */
+export function reportable(
+  input: EmitterInput,
+  findings: readonly CompletedFinding[],
+): readonly CompletedFinding[] {
+  const dials = dialsOf(input, findings);
+  return findings.filter((finding) => !dials.withholds(finding));
 }

package/src/findings/emitter.ts

@@ -6,6 +6,7 @@ import type { Finding } from "../finding.ts";
 import type { Implementations } from "../implementations.ts";
 import type { Stores } from "../stores.ts";
 import type { Boundary } from "./boundary.ts";
+import type { SelfCheckFacts } from "./self-check.ts";
 
 /**
  * What every emitter reads: the configuration the run resolved, the run's sweep, and
@@ -27,6 +28,8 @@ export interface EmitterInput {
   readonly files: FileFacts;
   /** What can reach the target from outside it: consumers, declared edges, and `exports`. */
   readonly boundary: Boundary;
+  /** The run's suppression outcomes and configured roots, which the self-check family reports. */
+  readonly selfCheck: SelfCheckFacts;
 }
 
 /**

package/src/findings/emitters.ts

@@ -1,6 +1,8 @@
-import { dependenciesAndModuleMachinery } from "./dependencies-and-module-machinery.ts";
+import { evaluateEdges, type EdgeEvaluation } from "../edges.ts";
 import type { CompletedFinding } from "../finding.ts";
-import { completed, reportable } from "./completion.ts";
+import { ledgerOf, type Dials, type Ledger, type SuppressionRecord } from "../suppress.ts";
+import { completed, dialsOf, reportable } from "./completion.ts";
+import { dependenciesAndModuleMachinery } from "./dependencies-and-module-machinery.ts";
 import type { Emitter, EmitterInput, Emitters } from "./emitter.ts";
 import { interfaces } from "./interfaces.ts";
 import { intraFunction } from "./intra-function.ts";
@@ -22,12 +24,84 @@ export const EMITTERS: Emitters = new Map<string, Emitter>([
   ["intra-function", intraFunction],
 ]);
 
+/** What the suppressions of a run swept under their marks are decided against. */
+export interface Suppressed {
+  /** The same run swept with no mark, which is where a kind about liveness reports a marked declaration. */
+  readonly unmarked: EmitterInput;
+  /** The run's suppression records, in reading order. */
+  readonly records: readonly SuppressionRecord[];
+}
+
+/** What the emitter table answers about one run. */
+export interface DecidedFindings {
+  /** Every finding the run reports, each family's in table order. */
+  readonly findings: readonly CompletedFinding[];
+  /** One evaluation per declared edge side of this language, ordered by edge, then by side. */
+  readonly evaluations: readonly EdgeEvaluation<CompletedFinding>[];
+  /** What every suppression record did, in reading order. */
+  readonly ledger: Ledger<CompletedFinding>;
+  /** Every finding a record could name: the run's with no mark, then the run's as swept. */
+  readonly would: readonly CompletedFinding[];
+}
+
+/** Every family's findings over one sweep, completed by one step. */
+function completedOver(input: EmitterInput): readonly CompletedFinding[] {
+  return completed(
+    input,
+    [...EMITTERS.values()].flatMap((emit) => emit(input)),
+  );
+}
+
 /**
- * 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.
+ * The dials over the findings a record could name, each read against the sweep that
+ * produced it, so a component one sweep numbers withholds nothing of the other's.
  */
+function dialsOver(
+  input: EmitterInput,
+  found: readonly CompletedFinding[],
+  suppressed: Suppressed,
+  unmarked: readonly CompletedFinding[],
+): Dials<CompletedFinding> {
+  const marked = dialsOf(input, found);
+  const before = dialsOf(suppressed.unmarked, unmarked);
+  const fromUnmarked = new Set(unmarked);
+  return {
+    withholdsCode: marked.withholdsCode,
+    withholds: (finding) =>
+      fromUnmarked.has(finding) ? before.withholds(finding) : marked.withholds(finding),
+  };
+}
+
+/**
+ * Every finding of one run swept under its suppressions' marks, decided in one pass: every
+ * family's findings completed by one step, so every component number is minted once, a
+ * pending finding's among them; the finding each record claims withheld, whatever its
+ * kind; the rest withheld by the dials, so a root one family reports withholds what
+ * another family reports in its component; and every declared edge evaluated over what
+ * remains, so a finding it holds pending is in its evaluation and nowhere else.
+ */
+export function decidedFindings(
+  input: EmitterInput,
+  suppressed: Suppressed = { unmarked: input, records: [] },
+): DecidedFindings {
+  const found = completedOver(input);
+  const unmarked = suppressed.records.length === 0 ? [] : completedOver(suppressed.unmarked);
+  const would = [...unmarked, ...found];
+  const ledger = ledgerOf(suppressed.records, would, dialsOver(input, found, suppressed, unmarked));
+  const kept = reportable(
+    input,
+    found.filter((finding) => !ledger.withheld(finding)),
+  );
+  const evaluated = evaluateEdges(kept, input.boundary.edges, input.swept.matrix.union.symbols);
+  return {
+    findings: evaluated.findings,
+    evaluations: evaluated.evaluations,
+    ledger,
+    would,
+  };
+}
+
+/** Every finding the run reports, each family's in table order. */
 export function findingsOf(input: EmitterInput): readonly CompletedFinding[] {
-  const found = [...EMITTERS.values()].flatMap((emit) => emit(input));
-  return reportable(completed(input, found), input.config.analysis.minConfidence);
+  return decidedFindings(input).findings;
 }

package/src/findings/self-check.ts

@@ -1,4 +1,228 @@
+import { REPOSITORY_DOCUMENT } from "../config.ts";
+import type { Finding, FindingDetails, SuppressionEntry } 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,
+  details: FindingDetails,
+): Finding {
+  return {
+    code,
+    position: { ...site, endLine: site.line },
+    symbol: { ref, kind: SUPPRESSION_SUBJECT, name: ref, sizeLines: 1 },
+    message,
+    details,
+  };
+}
+
+/** Whether a reason holds a character other than whitespace. */
+const STATED = /[^ \t\r\n]/u;
+
+/** A refused suppression as written: a member it lacks is absent. */
+function writtenEntry(refused: Refusal): SuppressionEntry {
+  return {
+    code: refused.code,
+    ...(refused.symbol === "" ? {} : { symbol: refused.symbol }),
+    ...(refused.path === "" ? {} : { path: refused.path }),
+    ...(STATED.test(refused.reason) ? { reason: refused.reason } : {}),
+  };
+}
+
+/** 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"
+      }`,
+      { mechanism: refused.mechanism, entry: writtenEntry(refused) },
+    ),
+  );
+}
+
+/** 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/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;
@@ -236,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(
@@ -263,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;
 }
 
 /**
@@ -303,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;