@cplieger/deadset-ts 3.10.0 → 3.12.0

package/src/findings/completion.ts

@@ -6,12 +6,13 @@
 
 import type { RunSweep } from "../analysis.ts";
 import { componentId, type Component } from "../components.ts";
-import type { Confidence, Config, Severity } from "../config.ts";
+import type { Confidence, Severity } from "../config.ts";
 import type { CompletedFinding, Finding, FindingComponent } from "../finding.ts";
 import { OUTSIDE } from "../graph.ts";
-import { KINDS } from "../kinds.ts";
+import { KINDS, type KindRow } from "../kinds.ts";
 import { FAMILY_KEY_LENGTH } from "../resolve.ts";
 import { isRowSubject, type Dials } from "../suppress.ts";
+import type { Boundary } from "./boundary.ts";
 import type { EmitterInput } from "./emitter.ts";
 
 /** The classes ranked by the claim each makes, the strongest highest. */
@@ -22,31 +23,64 @@ function capped(found: Confidence, ceiling: Confidence): Confidence {
   return RANK[found] <= RANK[ceiling] ? found : ceiling;
 }
 
+/** The kind whose default turns on what the run knows about the target's consumers. */
+const UNUSED_EXPORTED = "DS1001";
+
+/** Whether the run loaded every consumer the scope declared, which holds of a scope declaring none. */
+function everyDeclaredLoaded(boundary: Boundary): boolean {
+  const { declared, loaded } = boundary.consumers;
+  return declared.every((id) => loaded.includes(id));
+}
+
+/**
+ * Whether a library's published API may have a caller the run cannot see: the target is
+ * a library, and the run either holds no consumer information or did not load a consumer
+ * the scope declared. A configuration declaring the consumer set complete holds consumer
+ * information whether or not it declares a consumer, because it says no other exists.
+ */
+function openWorld(input: EmitterInput): boolean {
+  const known = input.config.consumersComplete || input.boundary.consumers.declared.length > 0;
+  return input.config.targetKind === "library" && !(known && everyDeclaredLoaded(input.boundary));
+}
+
 /**
  * The severity the configuration gives one code: the key naming the code, else the key
- * naming its family, else the code's default.
+ * naming its family, else the code's default. The unused-exported kind defaults to
+ * `allow` while a library's published API is open to callers the run cannot see.
  */
-function severityOf(config: Config, code: string, fallback: Severity): Severity {
-  return (
-    config.severity.get(code) ?? config.severity.get(code.slice(0, FAMILY_KEY_LENGTH)) ?? fallback
-  );
+function severityOf(input: EmitterInput, code: string, fallback: Severity): Severity {
+  const { config } = input;
+  const named = config.severity.get(code) ?? config.severity.get(code.slice(0, FAMILY_KEY_LENGTH));
+  if (named !== undefined) {
+    return named;
+  }
+  return code === UNUSED_EXPORTED && openWorld(input) ? "allow" : 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`.
+ * published API has callers outside the target: it is `certain` where the run loaded
+ * every consumer the scope declared and declared at least one, `probable` where it
+ * declared consumers and did not load them all, and `possible` where it declared none.
+ * Whether the configuration declares the consumer set complete decides nothing here.
+ * 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;
+function reachabilityClasses(input: EmitterInput): (id: string) => Confidence {
+  const union = input.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");
+  const { declared } = input.boundary.consumers;
+  const outside: Confidence =
+    declared.length === 0
+      ? "possible"
+      : everyDeclaredLoaded(input.boundary)
+        ? "certain"
+        : "probable";
+  return (id) => (published.has(id) ? outside : "certain");
 }
 
 /** The component each dead declaration of the run falls in, and none for a live one. */
@@ -76,22 +110,24 @@ function findingComponents(swept: RunSweep): (id: string) => FindingComponent |
  * 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; nothing
- * falls with it, so its deletion removes no line.
+ * falls with it, so its deletion removes no line. `kinds` is the vocabulary each code's
+ * row is read from, the shipped one unless a caller supplies its own.
  */
 export function completed(
   input: EmitterInput,
   findings: readonly Finding[],
+  kinds: ReadonlyMap<string, KindRow> = KINDS,
 ): 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 classOf = reachabilityClasses(input);
   const componentOf = findingComponents(swept);
   let minted = swept.sweep.components.length;
 
   return findings.map((finding): CompletedFinding => {
-    const row = KINDS.get(finding.code);
+    const row = kinds.get(finding.code);
     if (row === undefined) {
       throw new Error(`${finding.code} names no live row of the issue-kind vocabulary`);
     }
@@ -140,7 +176,7 @@ export function completed(
         (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),
+      severity: severityOf(input, finding.code, row.defaultSeverity),
       message: finding.message,
       details: finding.details ?? {},
     };
@@ -168,7 +204,7 @@ export function dialsOf(
   findings: readonly CompletedFinding[],
 ): Dials<CompletedFinding> {
   const minConfidence = input.config.analysis.minConfidence;
-  const classOf = reachabilityClasses(input.swept);
+  const classOf = reachabilityClasses(input);
   const components = new Set(
     findings
       .filter((finding) => finding.component.root && dialed(finding, minConfidence))
@@ -181,7 +217,7 @@ export function dialsOf(
         row !== undefined &&
         dialed(
           {
-            severity: severityOf(input.config, code, row.defaultSeverity),
+            severity: severityOf(input, code, row.defaultSeverity),
             confidence: capped(classOf(id), row.maxClass),
           },
           minConfidence,

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

@@ -63,11 +63,18 @@ function fileNeverBuilt({ config, swept, files }: EmitterInput): readonly Findin
 
 /**
  * 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.
+ * file or a declaration in it, a loaded consumer's file included. 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>();
+  for (const edge of union.consumed) {
+    const to = union.symbols[edge.to];
+    if (to !== undefined) {
+      reached.add(to.position.path);
+    }
+  }
   union.out.forEach((edges, from) => {
     const fromPath = union.symbols[from]?.position.path;
     for (const edge of edges) {

package/src/findings/reads-and-writes.ts

@@ -94,7 +94,9 @@ function writeOnlySymbols(run: Run): readonly Finding[] {
       held = { writes: [], reads: 0 };
       uses.set(reference.to, held);
     }
-    if (reference.use !== "write") {
+    // A consumer's store is written at a position no report of the target can name, so
+    // it counts as a use that keeps the declaration from this kind.
+    if (reference.use !== "write" || reference.consumer !== undefined) {
       held.reads += 1;
       continue;
     }

package/src/findings-pass.ts

@@ -5,7 +5,7 @@
  */
 
 import type { AnalysisInputs } from "./analysis.ts";
-import type { Config, Severity } from "./config.ts";
+import { fails, type Config } from "./config.ts";
 import type { EdgeEvaluation } from "./edges.ts";
 import type { CompletedFinding, Finding } from "./finding.ts";
 import { decidedFindings } from "./findings/emitters.ts";
@@ -44,9 +44,6 @@ export interface PassResult {
 /** 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) {
@@ -119,9 +116,10 @@ export function verdictOf(result: PassResult, config: Config): number {
   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;
+  const failing = result.findings.some((finding) =>
+    fails(finding.severity, config.reporters.failOn),
+  );
+  return failing ? EXIT_FINDINGS : EXIT_CLEAN;
 }
 
 /**

package/src/graph.ts

@@ -113,6 +113,12 @@ export interface Graph {
   readonly exportsOf: readonly (readonly number[])[];
   /** Every root naming a declaration the inventory holds, in the order the root set gives them. */
   readonly rooted: readonly Rooted[];
+  /**
+   * Every reference a loaded consumer makes to a declaration the inventory holds, in the
+   * order given. A consumer is a caller the analysis read, so the sweep holds what it
+   * names live under both relations and reaches on from there.
+   */
+  readonly consumed: readonly Edge[];
   /** The position of the declaration one identifier names, or {@link OUTSIDE}. */
   at(id: string): number;
 }
@@ -136,6 +142,7 @@ export function graphOf(
 
   const out: Edge[][] = symbols.map(() => []);
   const made = symbols.map(() => ({ production: 0, test: 0 }));
+  const consumed: Edge[] = [];
   for (const reference of references) {
     const to = at(reference.to);
     if (to === OUTSIDE) {
@@ -149,11 +156,12 @@ export function graphOf(
         counts.production += 1;
       }
     }
-    out[at(reference.from)]?.push({
-      to,
-      test: reference.test,
-      evaluation: reference.use === "evaluation",
-    });
+    const edge = { to, test: reference.test, evaluation: reference.use === "evaluation" };
+    if (reference.consumer !== undefined) {
+      consumed.push(edge);
+      continue;
+    }
+    out[at(reference.from)]?.push(edge);
   }
 
   const parent = symbols.map((symbol) => at(symbol.parent));
@@ -182,6 +190,7 @@ export function graphOf(
     subject: symbols.map((symbol) => swept(symbol.kind)),
     exportsOf,
     rooted,
+    consumed,
     at,
   };
 }

package/src/matrix.ts

@@ -69,12 +69,21 @@ function compare(a: string, b: string): number {
   return a < b ? -1 : 1;
 }
 
-/** What makes one reference one reference, whichever configuration made it. */
-function referenceKey(reference: Reference): string {
+/**
+ * What makes one reference one reference, whichever configuration made it. A consumer's
+ * position is rendered against its own root, so the consumer is part of what it names.
+ */
+export function referenceKey(reference: Reference): string {
   const { path, line, column } = reference.position;
-  return [reference.from, reference.to, path, String(line), String(column), reference.use].join(
-    "\u0000",
-  );
+  return [
+    reference.consumer ?? "",
+    reference.from,
+    reference.to,
+    path,
+    String(line),
+    String(column),
+    reference.use,
+  ].join("\u0000");
 }
 
 /**

package/src/references.ts

@@ -32,6 +32,7 @@ import { aliasChains } from "./alias-chain.ts";
 import { destructuring, propertyReadsOf, type PropertyRead } from "./destructuring.ts";
 import { globExpression } from "./glob.ts";
 import { nodeKey, type Inventory } from "./inventory.ts";
+import { relativePath } from "./paths.ts";
 import { byPosition, renderPosition, type Position } from "./position.ts";
 import type { ProjectView } from "./session.ts";
 
@@ -95,6 +96,21 @@ export interface Reference {
   readonly resolution: Resolution;
   /** Whether the file that made the reference is classified as a test file. */
   readonly test: boolean;
+  /**
+   * The identifier of the consumer whose file made the reference, absent for one the
+   * target made. A consumer's declarations are no declarations of the run, so such a
+   * reference comes from outside the inventory, and its position is rendered against
+   * the consumer's root.
+   */
+  readonly consumer?: string;
+}
+
+/** The consumer one reference pass reads the files of, beside the target it names. */
+export interface ConsumerSide {
+  /** The name the consumer publishes itself under. */
+  readonly id: string;
+  /** The consumer's directory, absolute: the files below it are its own. */
+  readonly root: string;
 }
 
 /** One rule that classified files as test files, and how many files it matched. */
@@ -162,6 +178,13 @@ export interface ReferenceOptions {
    * Each pattern is a rule of its own, which {@link testFileRulesOf} counts.
    */
   readonly testFiles: readonly string[];
+  /**
+   * The consumer whose files the pass walks instead of the target's. Its files are the
+   * program's own files below its root and not below the target root, each position is
+   * rendered against its root and the test patterns read the path below it, and only a
+   * reference to a declaration of `held`, the target's, is recorded.
+   */
+  readonly consumer?: ConsumerSide;
 }
 
 /**
@@ -555,7 +578,9 @@ function compare(a: string, b: string): number {
  *
  * `held` is the inventory of the same project, whose declaration map is what a resolved
  * symbol is looked up in; `targetRoot` is the absolute path every position is rendered
- * against, which is the root the inventory was read against.
+ * against, which is the root the inventory was read against. A pass over a consumer
+ * walks the consumer's files instead and renders against its root, as
+ * {@link ReferenceOptions.consumer} states.
  *
  * The order is by the referencing position, then by the declaration named, the
  * declaration referencing it and the use. That is a total order because one name
@@ -581,7 +606,18 @@ export function references<Brand>(
   let residueFallbacks = 0;
   let shorthandLookups = 0;
 
-  const files = project.ownSourceFiles();
+  const consumer = options.consumer;
+  const root = consumer?.root ?? targetRoot;
+  const files =
+    consumer === undefined
+      ? project.ownSourceFiles()
+      : project
+          .ownSourceFiles()
+          .filter(
+            (file) =>
+              relativePath(consumer.root, file.fileName) !== undefined &&
+              relativePath(targetRoot, file.fileName) === undefined,
+          );
   const fileIds = new Set(
     held.symbols.filter((symbol) => symbol.kind === "file").map((symbol) => symbol.id),
   );
@@ -615,7 +651,7 @@ export function references<Brand>(
   };
 
   for (const file of files) {
-    const path = renderPosition(file, targetRoot, 0).path;
+    const path = renderPosition(file, root, 0).path;
     const test = patterns.some((pattern) => pattern.test(path));
     if (test) {
       tests.push(path);
@@ -633,7 +669,7 @@ export function references<Brand>(
       found.push({
         from: declaration,
         to: declaration,
-        position: renderPosition(file, targetRoot, decorator.getStart()),
+        position: renderPosition(file, root, decorator.getStart()),
         use: "decorator",
         resolution: "syntax",
         test,
@@ -671,7 +707,7 @@ export function references<Brand>(
       if (symbol === undefined) {
         continue;
       }
-      const position = renderPosition(file, targetRoot, link.at.getStart());
+      const position = renderPosition(file, root, link.at.getStart());
       for (const id of carriedBy(link, symbol)) {
         found.push({
           from: link.from,
@@ -689,7 +725,7 @@ export function references<Brand>(
       if (module === undefined) {
         continue;
       }
-      const position = renderPosition(file, targetRoot, evaluation.node.getStart());
+      const position = renderPosition(file, root, evaluation.node.getStart());
       for (const id of chains.declarationsOf(module)) {
         if (fileIds.has(id)) {
           found.push({
@@ -711,7 +747,7 @@ export function references<Brand>(
       if (symbol === undefined || read === undefined) {
         return;
       }
-      const position = renderPosition(file, targetRoot, read.key.getStart());
+      const position = renderPosition(file, root, read.key.getStart());
       for (const target of chains.chainOf(symbol)) {
         found.push({
           from: read.from,
@@ -735,7 +771,7 @@ export function references<Brand>(
       if (symbol === undefined) {
         continue;
       }
-      const position = renderPosition(file, targetRoot, site.node.getStart());
+      const position = renderPosition(file, root, site.node.getStart());
       // A re-export something imports is used and so is the declaration behind it, so
       // the use names every link of the chain its name stands at the head of.
       for (const target of chains.chainOf(symbol)) {
@@ -761,7 +797,10 @@ export function references<Brand>(
 
   return {
     configFile: project.configFile,
-    references: found,
+    references:
+      consumer === undefined
+        ? found
+        : found.map((reference) => ({ ...reference, consumer: consumer.id })),
     testFilePaths: tests.sort(compare),
     cost: {
       batched,

package/src/report.ts

@@ -130,6 +130,13 @@ export interface ReportConfiguration {
   readonly project: string;
 }
 
+/** One consumer the run loaded, at the directory a report names it by. */
+interface ReportConsumer {
+  readonly id: string;
+  /** The consumer's directory, as the report names its target's: below the run directory. */
+  readonly path: string;
+}
+
 /** One consumer the scope declared and the run did not load, with why. */
 export interface UnavailableConsumer {
   readonly id: string;
@@ -156,7 +163,11 @@ export interface Report {
   readonly configurations_not_built: readonly never[];
   readonly consumers: {
     readonly declared: number;
-    readonly loaded: readonly never[];
+    readonly loaded: readonly {
+      readonly id: string;
+      readonly role: "consumer";
+      readonly path: string;
+    }[];
     readonly unavailable: readonly {
       readonly id: string;
       readonly role: "consumer";
@@ -180,6 +191,7 @@ export interface ReportInput {
   readonly declaredGaps: readonly DeclaredGap[];
   readonly target: { readonly kind: TargetKind; readonly root: string; readonly identity: string };
   readonly configurations: readonly ReportConfiguration[];
+  readonly loaded: readonly ReportConsumer[];
   readonly unavailable: readonly UnavailableConsumer[];
   readonly result: PassResult;
   readonly testFileRules: readonly TestFileRule[];
@@ -387,6 +399,9 @@ export function buildReport(input: ReportInput): Report {
   const unavailable = [...new Map(input.unavailable.map((one) => [one.id, one])).values()]
     .sort((a, b) => compare(a.id, b.id))
     .map((one) => ({ id: one.id, role: "consumer" as const, reason: one.reason }));
+  const loaded = [...input.loaded]
+    .sort((a, b) => compare(a.id, b.id) || compare(a.path, b.path))
+    .map((one) => ({ id: one.id, role: "consumer" as const, path: one.path }));
   return {
     schema_version: SCHEMA_VERSION,
     contract_version: input.contractVersion,
@@ -406,7 +421,7 @@ export function buildReport(input: ReportInput): Report {
       .sort((a, b) => compare(a.id, b.id))
       .map((one) => ({ id: one.id, project: one.project })),
     configurations_not_built: [],
-    consumers: { declared: unavailable.length, loaded: [], unavailable },
+    consumers: { declared: loaded.length + unavailable.length, loaded, unavailable },
     findings,
     edge_evaluations: input.result.edgeEvaluations.map(wireEvaluation).sort(byEdge),
     stale_suppressions: input.result.staleSuppressions.map(wireStale).sort(canonicalStale),

package/src/reporters/annotations.ts

@@ -0,0 +1,67 @@
+import { fails } from "../config.ts";
+import { KINDS } from "../kinds.ts";
+import type { Report } from "../report.ts";
+import type { RenderOptions } from "./reporter.ts";
+
+/** The escapes a workflow command's message needs, so a line break does not end the command. */
+const DATA_ESCAPES: Readonly<Record<string, string>> = { "%": "%25", "\r": "%0D", "\n": "%0A" };
+
+/** The escapes a property value needs: a message's, and the property list's two separators. */
+const PROPERTY_ESCAPES: Readonly<Record<string, string>> = {
+  ...DATA_ESCAPES,
+  ":": "%3A",
+  ",": "%2C",
+};
+
+function escapeData(value: string): string {
+  return value.replace(/[%\r\n]/gu, (char) => DATA_ESCAPES[char] ?? char);
+}
+
+function escapeProperty(value: string): string {
+  return value.replace(/[%\r\n:,]/gu, (char) => PROPERTY_ESCAPES[char] ?? char);
+}
+
+/** The name of the kind a code names, and the code itself where no live kind carries it. */
+function kindName(code: string): string {
+  return KINDS.get(code)?.name ?? code;
+}
+
+function command(
+  level: "error" | "warning",
+  at: { readonly path: string; readonly line: number; readonly column: number },
+  endLine: number,
+  title: string,
+  message: string,
+): string {
+  return `::${level} file=${escapeProperty(at.path)},line=${String(at.line)},col=${String(at.column)},endLine=${String(endLine)},title=${escapeProperty(title)}::${escapeData(message)}`;
+}
+
+/**
+ * One workflow annotation per finding, then one per stale suppression, each naming its
+ * file, line, column and last line, titled by its code and kind. A finding at or above the
+ * failing severity is an error and one below it a warning; a stale suppression is an error,
+ * because its kind is fixed on at the failing severity.
+ */
+export function annotations(report: Report, options: RenderOptions): string {
+  const lines = report.findings.map((found) =>
+    command(
+      fails(found.severity, options.failOn) ? "error" : "warning",
+      found.position,
+      found.position.end_line,
+      `${found.code} ${found.kind}`,
+      found.message,
+    ),
+  );
+  for (const stale of report.stale_suppressions) {
+    lines.push(
+      command(
+        "error",
+        stale.position,
+        stale.position.line,
+        `${stale.code} ${kindName(stale.code)}`,
+        stale.message,
+      ),
+    );
+  }
+  return lines.map((line) => `${line}\n`).join("");
+}

package/src/reporters/fingerprint.ts

@@ -0,0 +1,69 @@
+import { sha256Hex } from "./sha256.ts";
+
+/** The unit appended after the last unit of a file. */
+const SENTINEL = 0xffffn;
+
+/** The number of significant units one line's hash covers. */
+const WINDOW = 100;
+
+const FACTOR = 37n;
+
+/** Arithmetic is unsigned 64-bit with wraparound. */
+const MASK = (1n << 64n) - 1n;
+
+const SPACE = 0x20;
+const TAB = 0x09;
+const CR = 0x0d;
+const LF = 0x0a;
+
+/**
+ * The units of one file the line fingerprint counts: every UTF-16 code unit but a space or
+ * a tab, a carriage return read as a line feed and the line feed following it dropped, then
+ * the sentinel.
+ */
+function significantUnits(text: string): bigint[] {
+  const kept: bigint[] = [];
+  let afterCR = false;
+  for (let i = 0; i < text.length; i += 1) {
+    const unit = text.charCodeAt(i);
+    if (unit === SPACE || unit === TAB || (afterCR && unit === LF)) {
+      afterCR = false;
+      continue;
+    }
+    afterCR = unit === CR;
+    kept.push(BigInt(afterCR ? LF : unit));
+  }
+  kept.push(SENTINEL);
+  return kept;
+}
+
+/**
+ * The line fingerprint of every line of one file, indexed from zero. The procedure is the one
+ * a code-scanning service computes for a result that carries none, followed exactly, because
+ * a value that differs from the service's opens a second alert for one finding.
+ */
+export function lineHashes(text: string): readonly string[] {
+  const units = significantUnits(text);
+  const starts = [0];
+  for (let i = 0; i < units.length - 1; i += 1) {
+    if (units[i] === BigInt(LF)) {
+      starts.push(i + 1);
+    }
+  }
+  const seen = new Map<string, number>();
+  return starts.map((start) => {
+    let hash = 0n;
+    for (let i = start; i < start + WINDOW; i += 1) {
+      hash = (hash * FACTOR + (units[i] ?? 0n)) & MASK;
+    }
+    const rendered = hash.toString(16);
+    const count = (seen.get(rendered) ?? 0) + 1;
+    seen.set(rendered, count);
+    return `${rendered}:${String(count)}`;
+  });
+}
+
+/** The key a baseline joins on, which a line move leaves unchanged. */
+export function symbolFingerprint(code: string, ref: string): string {
+  return sha256Hex(`${code}\n${ref}`);
+}

package/src/reporters/json.ts

@@ -1,7 +1,7 @@
-import type { Reporter } from "./reporter.ts";
+import type { Report } from "../report.ts";
 
 /** The indentation of the report document, which with the schema's member order fixes its bytes. */
 const INDENT = 2;
 
 /** The report document itself: the report, indented, with a closing newline. */
-export const json: Reporter = (report) => `${JSON.stringify(report, null, INDENT)}\n`;
+export const json = (report: Report): string => `${JSON.stringify(report, null, INDENT)}\n`;

package/src/reporters/reporter.ts

@@ -1,8 +1,19 @@
-import type { Format } from "../config.ts";
+import type { Format, Severity } from "../config.ts";
 import type { Report } from "../report.ts";
+import type { Template } from "./template.ts";
+
+/** What a rendering reads beside the report. */
+export interface RenderOptions {
+  /** The lowest severity at which a finding fails the run. */
+  readonly failOn: Severity;
+  /** The text of the file at one path below the target root, or a throw naming why not. */
+  readonly readSource: (path: string) => string;
+  /** The template the template rendering renders, where one was named. */
+  readonly template: Template | undefined;
+}
 
 /** One rendering of a report, as the text of the file it is written to. */
-export type Reporter = (report: Report) => string;
+type Reporter = (report: Report, options: RenderOptions) => string;
 
 /**
  * One format this analyzer renders: its reporter, and the suffix appended to the report's
@@ -16,3 +27,11 @@ export interface Rendering {
 
 /** Every format this analyzer renders, each by its rendering. */
 export type Renderings = ReadonlyMap<Format, Rendering>;
+
+/** A rendering that cannot be written, which ends the run with the failure code. */
+export class RenderError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "RenderError";
+  }
+}