@cplieger/deadset-ts 3.7.0 → 3.8.0

package/src/analysis.ts

@@ -14,6 +14,7 @@ import { decorator } from "./decorator.ts";
 import { dependenciesOf, projectNeeds } from "./dependencies.ts";
 import { deprecatedDeclarations } from "./deprecation.ts";
 import { diagnosticErrors, discoverProjects, DiscoveryError } from "./discover.ts";
+import { readEdgeSides } from "./edges.ts";
 import { enumGroup } from "./enum-group.ts";
 import {
   computeExemptions,
@@ -26,7 +27,13 @@ import {
 import type { TSExemptionClass } from "./exempt-classes.ts";
 import { heldByInclusion, sourceTree } from "./file-facts.ts";
 import type { Finding } from "./finding.ts";
+import { findingsPass, type PassResult } from "./findings-pass.ts";
 import type { EmitterInput } from "./findings/emitter.ts";
+import {
+  NO_SELF_CHECK,
+  unmatchedRootFindings,
+  type SelfCheckFacts,
+} from "./findings/self-check.ts";
 import { frameworkLifecycle } from "./framework-lifecycle.ts";
 import type { Host } from "./host.ts";
 import { implementations, mergeImplementations } from "./implementations.ts";
@@ -39,12 +46,15 @@ import { relativePath, resolvePath } from "./paths.ts";
 import { byPosition, type Position } from "./position.ts";
 import { reflectiveLookup } from "./reflective-lookup.ts";
 import { references } from "./references.ts";
-import { roots, unmatchedEverywhere, unmatchedRoots, type RootKind, type Roots } from "./roots.ts";
+import { roots, unmatchedEverywhere, type RootKind, type Roots } from "./roots.ts";
 import type { Scope } from "./scope.ts";
 import { serializationContract } from "./serialization-contract.ts";
 import { diagnosticsOf, runSession, type Engine, type ProjectView } from "./session.ts";
 import { accessorsOf, storesOf } from "./stores.ts";
-import type { Exemption, SweepInput } from "./sweep.ts";
+import type { Suppressions } from "./suppress.ts";
+import { readBaseline, readIgnoreFile } from "./suppress-file.ts";
+import { inlineDirectives, inlineSuppressions, type InlineDirective } from "./suppress-inline.ts";
+import type { Exemption, Mode, SweepInput } from "./sweep.ts";
 import { readTemplates, templateField } from "./template-field.ts";
 
 /** The setting whose source decides where a finding about a configured root sits. */
@@ -211,7 +221,10 @@ export function runRoots(
   return {
     configurations,
     roots: ordered,
-    findings: unmatchedRoots(unmatched, documentOf(host, provenance, ROOTS_SETTING, targetRoot)),
+    findings: unmatchedRootFindings(
+      unmatched,
+      documentOf(host, provenance, ROOTS_SETTING, targetRoot),
+    ),
   };
 }
 
@@ -245,26 +258,27 @@ interface SweptProject<Extra> {
   readonly extra: Extra;
 }
 
-/** The run's sweep, the exemption records it was swept with, and each project's extra answer. */
-interface SweptRun<Extra> {
-  readonly swept: RunSweep;
+/** What a run read of its projects before any sweep: the matrix, its exemptions, and each project's answers. */
+interface ReadRun<Extra> {
+  readonly matrix: Matrix;
   readonly exempt: readonly Exemption[];
   readonly projects: readonly SweptProject<Extra>[];
 }
 
 /**
- * Sweeps the run, reading each project's references and exemptions, and `extra`'s
- * answer, while the project's view is open.
+ * Reads every project of the run, its references and exemptions, and `extra`'s answer,
+ * while the project's view is open, and merges the projects into one matrix in the run's
+ * order.
  */
-function sweepRun<Extra>(
+function readRun<Extra>(
   engine: Engine,
   host: Host,
   scope: Scope,
   config: Config,
-  input: Pick<SweepInput, "marked" | "mode">,
+  mode: Mode,
   detectors: Detectors,
   extra: <Brand>(project: ProjectView<Brand>, read: ProjectRead) => Extra,
-): SweptRun<Extra> {
+): ReadRun<Extra> {
   const targetRoot = scope.target.path;
   const disabled = disabledClasses(config);
   const templates = disabled.has("template-field")
@@ -287,22 +301,32 @@ function sweepRun<Extra>(
       detectors,
       {
         disabled,
-        mode: input.mode,
+        mode,
         testFiles: new Set(resolved.testFilePaths),
       },
     );
     return { configured, exempt, extra: extra(project, projectRead) };
   });
-  const matrix = matrixOf(projects.map((one) => one.configured));
-  const exempt = exemptionsOf(projects.flatMap((one) => one.exempt));
-  const swept: SweepInput = { ...input, exempt };
   return {
-    swept: { matrix, sweep: sweepMatrix(matrix, swept), retained: retainedIn(matrix, swept) },
-    exempt,
+    matrix: matrixOf(projects.map((one) => one.configured)),
+    exempt: exemptionsOf(projects.flatMap((one) => one.exempt)),
     projects,
   };
 }
 
+/** The sweep of a run read once, under one set of marks. */
+function sweptOf<Extra>(
+  read: ReadRun<Extra>,
+  input: Pick<SweepInput, "marked" | "mode">,
+): RunSweep {
+  const swept: SweepInput = { ...input, exempt: read.exempt };
+  return {
+    matrix: read.matrix,
+    sweep: sweepMatrix(read.matrix, swept),
+    retained: retainedIn(read.matrix, swept),
+  };
+}
+
 /**
  * Sweeps the run the scope and the configuration describe. Each project's references
  * and exemptions are read against its own inventory while its view is open; the
@@ -321,32 +345,59 @@ export function runSweep(
   input: Pick<SweepInput, "marked" | "mode">,
   detectors: Detectors = DETECTORS,
 ): RunSweep {
-  return sweepRun(engine, host, scope, config, input, detectors, () => undefined).swept;
+  return sweptOf(
+    readRun(engine, host, scope, config, input.mode, detectors, () => undefined),
+    input,
+  );
 }
 
-/**
- * What every emitter reads of the run the scope and the configuration describe: the
- * run's sweep, and the facts beside it each kind family reads, every per-project one
- * read in the same session as the sweep. The run loads no consumer and reads no
- * declared cross-language edge, so its boundary names neither.
- */
-export function runEmitterInput(
+/** What each project contributes to the facts every emitter reads beside the sweep. */
+interface EmitterExtra {
+  readonly deprecated: readonly string[];
+  readonly accessors: ReturnType<typeof accessorsOf>;
+  readonly needs: ReturnType<typeof projectNeeds>;
+  readonly implementations: ReturnType<typeof implementations>;
+  readonly heldByInclusion: readonly string[];
+  readonly rooted: Roots;
+  readonly directives: readonly InlineDirective[];
+}
+
+/** Reads a run's projects with every per-project fact an emitter reads. */
+function readEmitterRun(
   engine: Engine,
   host: Host,
   scope: Scope,
   config: Config,
-  input: Pick<SweepInput, "marked" | "mode">,
-  detectors: Detectors = DETECTORS,
-): EmitterInput {
+  mode: Mode,
+  detectors: Detectors,
+): ReadRun<EmitterExtra> {
   const targetRoot = scope.target.path;
-  const run = sweepRun(engine, host, scope, config, input, detectors, (project, read) => ({
+  return readRun(engine, host, scope, config, mode, detectors, (project, read) => ({
     deprecated: deprecatedDeclarations(project, read.held),
     accessors: accessorsOf(project, read.held),
     needs: projectNeeds(project, read.held, host),
     implementations: implementations(project, read.held),
     heldByInclusion: heldByInclusion(project, targetRoot),
+    rooted: read.rooted,
+    directives: inlineDirectives(project, read.held, targetRoot),
   }));
-  const { swept, projects } = run;
+}
+
+/**
+ * The input every emitter reads over one sweep of a read run: the facts beside the sweep
+ * each kind family reads, every per-project one read in the same session as the sweep.
+ */
+function emitterInputOver(
+  host: Host,
+  scope: Scope,
+  config: Config,
+  read: ReadRun<EmitterExtra>,
+  input: Pick<SweepInput, "marked" | "mode">,
+  selfCheck: SelfCheckFacts,
+): EmitterInput {
+  const targetRoot = scope.target.path;
+  const swept = sweptOf(read, input);
+  const { projects } = read;
   return {
     config,
     swept,
@@ -356,7 +407,7 @@ export function runEmitterInput(
         references: one.configured.references,
         accessors: one.extra.accessors,
       })),
-      run.exempt,
+      read.exempt,
       input.mode,
     ),
     dependencies: dependenciesOf(
@@ -373,7 +424,100 @@ export function runEmitterInput(
     boundary: {
       consumers: { declared: scope.consumers.map((consumer) => consumer.id), loaded: [] },
       encapsulated: readManifest(host, targetRoot).declaresExports,
-      edges: [],
+      edges: readEdgeSides(host, targetRoot),
     },
+    selfCheck,
+  };
+}
+
+/**
+ * What every emitter reads of the run the scope and the configuration describe, swept
+ * under the caller's marks: the run's sweep, the facts beside it each kind family reads,
+ * and the sides of the target's declared cross-language edges that name a symbol of this
+ * language. The run loads no consumer, and it reads no suppression document, so the
+ * self-check family has nothing to report.
+ */
+export function runEmitterInput(
+  engine: Engine,
+  host: Host,
+  scope: Scope,
+  config: Config,
+  input: Pick<SweepInput, "marked" | "mode">,
+  detectors: Detectors = DETECTORS,
+): EmitterInput {
+  const read = readEmitterRun(engine, host, scope, config, input.mode, detectors);
+  return emitterInputOver(host, scope, config, read, input, NO_SELF_CHECK);
+}
+
+/** One run read for its findings: the input swept with and without its suppressions' marks. */
+export interface AnalysisInputs {
+  /** The run swept under the marks of every bound suppression record. */
+  readonly marked: EmitterInput;
+  /** The same run swept with no mark, which is what a record would have withheld. */
+  readonly unmarked: EmitterInput;
+  /** The run's suppression records and refusals, in reading order. */
+  readonly suppressions: Suppressions;
+}
+
+/**
+ * Reads the run the scope and the configuration describe for its findings. The inline
+ * directives, the ignore file's entries and the baseline's rows are read and bound before
+ * any sweep, and the run is swept once under every bound record's mark and once under
+ * none, so a record is decided against the finding its code would have produced. The
+ * self-check family reports the refused suppressions and the roots that named nothing.
+ */
+function runAnalysisInputs(
+  engine: Engine,
+  host: Host,
+  scope: Scope,
+  config: Config,
+  provenance: Provenance,
+  mode: Mode,
+  detectors: Detectors = DETECTORS,
+): AnalysisInputs {
+  const targetRoot = scope.target.path;
+  const read = readEmitterRun(engine, host, scope, config, mode, detectors);
+  const symbols = read.matrix.union.symbols;
+  const documents = [
+    inlineSuppressions(read.projects.map((one) => one.extra.directives)),
+    readIgnoreFile(host, targetRoot, symbols),
+    readBaseline(host, targetRoot, symbols),
+  ];
+  const suppressions: Suppressions = {
+    records: documents.flatMap((one) => one.records),
+    refusals: documents.flatMap((one) => one.refusals),
+  };
+  const facts: SelfCheckFacts = {
+    refusals: suppressions.refusals,
+    unmatchedRoots: unmatchedEverywhere(
+      config.rootPatterns,
+      read.projects.map((one) => one.extra.rooted),
+    ),
+    rootsDocument: documentOf(host, provenance, ROOTS_SETTING, targetRoot),
   };
+  const marked = [...new Set(suppressions.records.map((record) => record.bound))].filter(
+    (id) => id !== "",
+  );
+  return {
+    marked: emitterInputOver(host, scope, config, read, { marked, mode }, facts),
+    unmarked: emitterInputOver(host, scope, config, read, { marked: [], mode }, facts),
+    suppressions,
+  };
+}
+
+/**
+ * The findings of the run the scope and the configuration describe: the run read with its
+ * suppressions bound, then every family's findings with the suppressions applied and the
+ * declared edges evaluated.
+ */
+export function runFindings(
+  engine: Engine,
+  host: Host,
+  scope: Scope,
+  config: Config,
+  provenance: Provenance,
+  mode: Mode,
+  detectors: Detectors = DETECTORS,
+): PassResult {
+  return findingsPass(runAnalysisInputs(engine, host, scope, config, provenance, mode, detectors));
 }

package/src/edges.ts

@@ -0,0 +1,241 @@
+/**
+ * Declared cross-language edges: the sides of the target's edges document that name a
+ * symbol of this language, and the evaluation the report publishes for each. This analyzer
+ * never resolves the paired symbol: the other language's analyzer decides whether the
+ * pairing is a use, and the merge reads the two evaluations together.
+ */
+
+import { ConfigError } from "./config.ts";
+import type { Finding } from "./finding.ts";
+import type { EdgeSide, EdgeSideName } from "./findings/boundary.ts";
+import type { Host } from "./host.ts";
+import type { InventorySymbol } from "./inventory.ts";
+import { positionAt, walkDocument } from "./json-document.ts";
+import { joinPath } from "./paths.ts";
+import { positionKey } from "./position.ts";
+
+/** The name and the location the Contract fixes for the edges document. */
+export const EDGES_FILE = "deadset-edges.json";
+
+/** The language prefix of every reference this analyzer evaluates. */
+const OWN_PREFIX = "ts://";
+
+/** The closed key list of the document and of one edge. */
+const DOCUMENT_KEYS: ReadonlySet<string> = new Set(["description", "edges"]);
+const EDGE_KEYS: ReadonlySet<string> = new Set(["id", "because", "provides", "used_by"]);
+
+/** An edge identifier: solidus-separated segments of ASCII letters, digits, `_`, `.` and `-`. */
+const ID_FORM = /^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/u;
+
+/** A reference naming one symbol of some language: `<language>://<scope>#<fragment>`. */
+const REFERENCE_FORM = /^[a-z][a-z0-9]*:\/\/[^ \t\r\n#]+#[^ \t\r\n]*$/u;
+
+const DOCUMENT_WANT = "an object carrying the edges array, and an optional description";
+const EDGE_WANT = "an edge naming id, provides and used_by, each a string, and an optional because";
+const ID_WANT =
+  "one or more solidus-separated segments of ASCII letters, digits, underscore, full stop and hyphen";
+const REFERENCE_WANT =
+  "a stable symbol reference naming one symbol exactly, <language>://<scope>#<fragment>";
+
+/** An edges document the Contract refuses: a malformed input, answered with the usage code. */
+export class EdgesError extends ConfigError {
+  constructor(at: string, text: string, want: string) {
+    super("malformed", EDGES_FILE, `${at}: ${text}: want ${want}`);
+    this.name = "EdgesError";
+  }
+}
+
+/**
+ * Whether a reference carries a wildcard outside a quoted or a computed component, which
+ * would name a set of symbols rather than one.
+ */
+function carriesWildcard(ref: string): boolean {
+  let quoted = false;
+  let computed = false;
+  let escaped = false;
+  for (const char of ref) {
+    if (escaped) {
+      escaped = false;
+    } else if (quoted && char === "\\") {
+      escaped = true;
+    } else if (quoted) {
+      quoted = char !== "'";
+    } else if (computed) {
+      computed = char !== "]";
+    } else if (char === "'") {
+      quoted = true;
+    } else if (char === "[") {
+      computed = true;
+    } else if (char === "*") {
+      return true;
+    }
+  }
+  return false;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** One edge, checked: the closed key list, the value types and the value forms. */
+function readEdge(value: unknown, at: string): { id: string; provides: string; usedBy: string } {
+  const refuse = (text: string, want: string): never => {
+    throw new EdgesError(at, text, want);
+  };
+  if (!isObject(value)) {
+    return refuse(JSON.stringify(value), EDGE_WANT);
+  }
+  for (const [key, held] of Object.entries(value)) {
+    if (!EDGE_KEYS.has(key) || typeof held !== "string") {
+      refuse(`the member ${JSON.stringify(key)} holding ${JSON.stringify(held)}`, EDGE_WANT);
+    }
+  }
+  const edge = value as Readonly<Record<string, string | undefined>>;
+  const id = edge["id"] ?? refuse("an edge naming no id", EDGE_WANT);
+  const provides = edge["provides"] ?? refuse("an edge naming no provides side", EDGE_WANT);
+  const usedBy = edge["used_by"] ?? refuse("an edge naming no used_by side", EDGE_WANT);
+  if (!ID_FORM.test(id)) {
+    refuse(JSON.stringify(id), ID_WANT);
+  }
+  for (const ref of [provides, usedBy]) {
+    if (!REFERENCE_FORM.test(ref) || carriesWildcard(ref)) {
+      refuse(JSON.stringify(ref), REFERENCE_WANT);
+    }
+  }
+  return { id, provides, usedBy };
+}
+
+/**
+ * Every side of a declared edge that names a symbol of this language, in document order,
+ * `provides` before `used_by` within an edge. An absent document declares no edge. The
+ * document is strict JSON with a closed key list at both levels, and a defect in it is an
+ * {@link EdgesError}.
+ */
+export function readEdgeSides(host: Host, targetRoot: string): readonly EdgeSide[] {
+  const file = joinPath(targetRoot, EDGES_FILE);
+  if (host.kindOf(file) === "absent") {
+    return [];
+  }
+  const text = host.readFile(file);
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch (error: unknown) {
+    throw new EdgesError(
+      EDGES_FILE,
+      error instanceof Error ? error.message : String(error),
+      DOCUMENT_WANT,
+    );
+  }
+  if (!isObject(parsed)) {
+    throw new EdgesError(EDGES_FILE, JSON.stringify(parsed), DOCUMENT_WANT);
+  }
+  const walk = walkDocument(text, "edges");
+  if (walk.twice !== undefined) {
+    throw new EdgesError(
+      positionKey(positionAt(text, EDGES_FILE, walk.twice.offset)),
+      `the member ${JSON.stringify(walk.twice.name)} is written twice, so neither value is chosen`,
+      DOCUMENT_WANT,
+    );
+  }
+  const unknown = Object.keys(parsed).find((key) => !DOCUMENT_KEYS.has(key));
+  const description = parsed["description"];
+  const edges = parsed["edges"];
+  if (
+    unknown !== undefined ||
+    (description !== undefined && typeof description !== "string") ||
+    !Array.isArray(edges)
+  ) {
+    throw new EdgesError(
+      EDGES_FILE,
+      unknown === undefined ? EDGES_FILE : `the member ${JSON.stringify(unknown)}`,
+      DOCUMENT_WANT,
+    );
+  }
+
+  const sides: EdgeSide[] = [];
+  (edges as readonly unknown[]).forEach((value, index) => {
+    const offset = walk.opened[index];
+    const at =
+      offset === undefined ? EDGES_FILE : positionKey(positionAt(text, EDGES_FILE, offset));
+    const edge = readEdge(value, at);
+    const named: readonly [EdgeSideName, string][] = [
+      ["provides", edge.provides],
+      ["used_by", edge.usedBy],
+    ];
+    for (const [side, symbol] of named) {
+      if (symbol.startsWith(OWN_PREFIX)) {
+        sides.push({ edge: edge.id, side, symbol });
+      }
+    }
+  });
+  return sides;
+}
+
+/** One side's verdict, as an evaluation names it. */
+export type EdgeState = "live" | "dead" | "absent";
+
+/** One edge evaluation: one side of this language, its state, and the finding it holds. */
+export interface EdgeEvaluation<F extends Finding = Finding> extends EdgeSide {
+  readonly state: EdgeState;
+  /** Present exactly when the state is `dead`: the finding a live paired symbol cancels. */
+  readonly finding?: F;
+}
+
+/** The findings a report publishes, and one evaluation per declared side of this language. */
+export interface Evaluated<F extends Finding> {
+  readonly findings: readonly F[];
+  /** Ordered by edge, then by side, each compared bytewise. */
+  readonly evaluations: readonly EdgeEvaluation<F>[];
+}
+
+/** Two strings ordered bytewise. */
+function compare(a: string, b: string): number {
+  if (a === b) {
+    return 0;
+  }
+  return a < b ? -1 : 1;
+}
+
+/**
+ * Evaluates every declared side of this language over the run's findings. A side naming a
+ * symbol the run enumerates nothing under is `absent`; one naming a symbol the run holds a
+ * finding about is `dead` and carries that finding, pending until a merge reads the other
+ * side and reported nowhere else, a narrowing finding included; any other is `live`.
+ */
+export function evaluateEdges<F extends Finding>(
+  findings: readonly F[],
+  sides: readonly EdgeSide[],
+  symbols: readonly InventorySymbol[],
+): Evaluated<F> {
+  if (sides.length === 0) {
+    return { findings, evaluations: [] };
+  }
+  const byRef = new Map<string, string>();
+  for (const symbol of symbols) {
+    if (symbol.kind !== "file" && !byRef.has(symbol.ref)) {
+      byRef.set(symbol.ref, symbol.id);
+    }
+  }
+  const held = new Map<string, number>();
+  findings.forEach((finding, at) => {
+    held.set(positionKey(finding.position), at);
+  });
+
+  const pending = new Set<number>();
+  const evaluations = sides.map((side): EdgeEvaluation<F> => {
+    const id = byRef.get(side.symbol);
+    if (id === undefined) {
+      return { ...side, state: "absent" };
+    }
+    const at = held.get(id);
+    const finding = at === undefined ? undefined : findings[at];
+    if (at === undefined || finding === undefined) {
+      return { ...side, state: "live" };
+    }
+    pending.add(at);
+    return { ...side, state: "dead", finding };
+  });
+  evaluations.sort((a, b) => compare(a.edge, b.edge) || compare(a.side, b.side));
+  return { findings: findings.filter((_finding, at) => !pending.has(at)), evaluations };
+}

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 type { Dials } from "../suppress.ts";
 import type { EmitterInput } from "./emitter.ts";
 
 /** The classes ranked by the claim each makes, the strongest highest. */
@@ -141,23 +142,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;
 }
 
 /**