@drkmttr/adhere 0.12.0 → 0.13.1

package/src/services/Jev.http.ts

@@ -1,4 +1,4 @@
-import type { RuleId } from "#config.ts";
+import type { AppendState, JevState, JudgedFile, RuleId } from "#config.ts";
 import { sectionsOf } from "#excerpt.ts";
 import { AdhereConfig } from "#services/AdhereConfig.ts";
 import { Credentials } from "#services/Credentials.ts";
@@ -22,6 +22,7 @@ import {
   namedPairs,
   type Pair,
   pairProbability,
+  requestGroups,
   requestsOf,
   type Rules,
   sufficiencyKey,
@@ -38,9 +39,9 @@ import {
   Schedule,
   Schema,
 } from "effect";
-import { HttpClient, HttpClientError, HttpClientResponse } from "effect/unstable/http";
-import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
-import { RateLimiter } from "effect/unstable/persistence";
+import { HttpClient, HttpClientError, HttpClientResponse } from "effect/http";
+import * as HttpClientRequest from "effect/http/HttpClientRequest";
+import { RateLimiter } from "effect/persistence";
 
 const SYSTEM_ONE = "https://api.typesafe.ai/v1/systemone";
 
@@ -63,6 +64,40 @@ const LocateAnswers = Schema.Struct({
 
 const refused = (message: string) => JevUnavailable.make({ message });
 
+/** Bun's API, for a rule's hook. Read off `globalThis`, as presets.ts reads it: Vitest runs this on Node. */
+const bun = (globalThis as { readonly Bun?: unknown }).Bun as Parameters<AppendState>[2];
+
+/**
+ * A body as it goes out: when its rule has `includeWorkspacePackages`, with
+ * the workspace's packages in its state, and when it has `appendState`, with
+ * what the hook returns spread over that. A hook that fails refuses the run.
+ */
+const hooked = (
+  sent: Body & { readonly state: JevState },
+  group: Rules,
+  file: JudgedFile,
+  workspacePackages: Readonly<Record<string, string>>,
+): Effect.Effect<Body, JevUnavailable> => {
+  const body = Object.values(group).some((rule) => rule.includeWorkspacePackages === true)
+    ? { ...sent, state: { ...sent.state, workspacePackages } }
+    : sent;
+  const [hook] = Object.entries(group).flatMap(([id, rule]) =>
+    rule.appendState === undefined ? [] : [[id, rule.appendState] as const],
+  );
+  if (hook === undefined) return Effect.succeed(body);
+  const [id, appendState] = hook;
+  return Effect.tryPromise({
+    try: async () => ({
+      ...body,
+      state: { ...body.state, ...(await appendState(body.state, file, bun)) },
+    }),
+    catch: (cause) =>
+      refused(
+        `the appendState of ${id} failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+      ),
+  });
+};
+
 /** A failed attempt, for the log: the status and Ray ID when Jev's side answered, the cause otherwise. */
 const attemptFailure = (
   problem: HttpClientError.HttpClientError | RateLimiter.RateLimiterError | Cause.TimeoutError,
@@ -224,14 +259,45 @@ export const JevLive = Layer.effect(Jev)(
           ),
       );
 
+    /**
+     * Every answer about a file's rules: a body for each group that
+     * `requestGroups` makes of them, each with its rule's hook run right
+     * before it goes out.
+     */
+    const answersAbout = <A>(
+      kind: string,
+      rules: Rules,
+      bodyOf: (group: Rules) => Body & { readonly state: JevState },
+      file: JudgedFile,
+      Answers: Schema.Codec<
+        { readonly answers: Readonly<Record<string, A>> },
+        unknown,
+        never,
+        never
+      >,
+    ) =>
+      Effect.map(
+        Effect.forEach(requestGroups(rules), (group) =>
+          Effect.flatMap(
+            hooked(bodyOf(group), group, file, config.workspacePackages ?? {}),
+            (body) => answersTo(kind, body, Answers),
+          ),
+        ),
+        (groups) =>
+          groups.reduce<Record<string, A>>((answers, some) => ({ ...answers, ...some }), {}),
+      );
+
     const judge = Effect.fn("Jev.judge")(function* (
       lines: Lines,
       rules: Rules,
-      sampled: ReadonlyArray<RuleId> = [],
+      sampled: ReadonlyArray<RuleId>,
+      file: JudgedFile,
     ) {
-      const answers = yield* answersTo(
+      const answers = yield* answersAbout(
         "judge",
-        judgeBody(config.model, lines, rules, sampled),
+        rules,
+        (group) => judgeBody(config.model, lines, group, sampled),
+        file,
         NoulAnswers,
       );
       /** Each rule's answer, read from the question it rode under. */
@@ -270,11 +336,17 @@ export const JevLive = Layer.effect(Jev)(
       } satisfies Judged;
     });
 
-    const locate = Effect.fn("Jev.locate")(function* (lines: Lines, rules: Rules) {
+    const locate = Effect.fn("Jev.locate")(function* (
+      lines: Lines,
+      rules: Rules,
+      file: JudgedFile,
+    ) {
       const sections = sectionsOf(lines);
-      const answers = yield* answersTo(
+      const answers = yield* answersAbout(
         "locate",
-        locateBody(config.model, lines, rules),
+        rules,
+        (group) => locateBody(config.model, lines, group),
+        file,
         LocateAnswers,
       );
       // A file of one section has every finding in it. An answer that names no section,

package/src/services/Jev.ts

@@ -1,4 +1,11 @@
-import { type Example, examplesOf, type Rule, type RuleId, type Rules } from "#config.ts";
+import {
+  type Example,
+  examplesOf,
+  type JudgedFile,
+  type Rule,
+  type RuleId,
+  type Rules,
+} from "#config.ts";
 import { type Range, sectionsOf } from "#excerpt.ts";
 import { Context, type Effect, Record, Schema } from "effect";
 
@@ -47,12 +54,13 @@ export class Jev extends Context.Service<
     /**
      * Each rule's probability that the file breaks it. A rule in `sampled`
      * also carries the linter check's question, whose answer comes back
-     * under `linter`.
+     * under `linter`. `file` is what a rule's `appendState` gets.
      */
     readonly judge: (
       lines: Lines,
       rules: Rules,
-      sampled?: ReadonlyArray<RuleId>,
+      sampled: ReadonlyArray<RuleId>,
+      file: JudgedFile,
     ) => Effect.Effect<Judged, JevUnavailable | JevOverflow | JevBlocked>;
     /**
      * Per rule, the section of the file that most clearly breaks it, and
@@ -62,6 +70,7 @@ export class Jev extends Context.Service<
     readonly locate: (
       lines: Lines,
       rules: Rules,
+      file: JudgedFile,
     ) => Effect.Effect<Record<RuleId, Located>, JevUnavailable | JevOverflow | JevBlocked>;
     /**
      * Per rule, the partner Jev names as impossible to follow in the same code,
@@ -468,33 +477,55 @@ export const requestsOf = (body: Body): ReadonlyArray<Body> => {
   return requests.map(({ questions }) => ({ ...body, questions }));
 };
 
+/** Whether a rule reads state of its own: what its `appendState` adds, or the workspace's packages. */
+const readsOwnState = (rule: Rule): boolean =>
+  rule.appendState !== undefined || rule.includeWorkspacePackages === true;
+
+/**
+ * The rules as requests carry them: every rule that reads only the code in
+ * one body, and each rule with state of its own in a body of its own, so
+ * that what is added to the state for it only its own questions read.
+ */
+export const requestGroups = (rules: Rules): ReadonlyArray<Rules> => {
+  const shared = Record.filter(rules, (rule) => !readsOwnState(rule));
+  return [
+    ...(Record.isEmptyRecord(shared) ? [] : [shared]),
+    ...Object.entries(rules).flatMap(([id, rule]) => (readsOwnState(rule) ? [{ [id]: rule }] : [])),
+  ];
+};
+
+/** The judge requests for `rules` over a file: a body per group, split to fit, as `judge` sends them. */
+const judgeRequestsOf = (lines: Lines, rules: Rules, sampled: ReadonlyArray<RuleId>) =>
+  requestGroups(rules).flatMap((group) => requestsOf(judgeBody("", lines, group, sampled)));
+
 /**
  * The requests judging `rules` over a file takes, and about how many input
- * tokens they carry, by `tokensOf`: the judge body, split to fit, as `judge`
- * sends it, each request with the file again.
+ * tokens they carry, by `tokensOf`: the judge bodies, split to fit, as
+ * `judge` sends them, each request with the file again. What a rule's
+ * `appendState` adds is not known before it runs, so it is not counted.
  */
 export const judgeLoad = (
   lines: Lines,
   rules: Rules,
   sampled: ReadonlyArray<RuleId> = [],
 ): { readonly requests: number; readonly tokens: number } => {
-  const requests = requestsOf(judgeBody("", lines, rules, sampled));
+  const requests = judgeRequestsOf(lines, rules, sampled);
   return {
     requests: requests.length,
     tokens: requests.reduce((sum, request) => sum + tokensOf(request), 0),
   };
 };
 
-/** The requests judging `rules` over a file takes: the judge body, split to fit, as `judge` sends it. */
+/** The requests judging `rules` over a file takes: the judge bodies, split to fit, as `judge` sends them. */
 export const judgeRequests = (
   lines: Lines,
   rules: Rules,
   sampled: ReadonlyArray<RuleId> = [],
-): number => requestsOf(judgeBody("", lines, rules, sampled)).length;
+): number => judgeRequestsOf(lines, rules, sampled).length;
 
-/** The requests locating `rules` in a file takes, split to fit as `locate` sends them. */
+/** The requests locating `rules` in a file takes, a body per group split to fit, as `locate` sends them. */
 export const locateRequests = (lines: Lines, rules: Rules): number =>
-  requestsOf(locateBody("", lines, rules)).length;
+  requestGroups(rules).flatMap((group) => requestsOf(locateBody("", lines, group))).length;
 
 /** A choice keeps one criterion for "none", which leaves this many for partners. */
 const PARTNERS_PER_QUESTION = CHOICE_LIMIT - 1;

package/src/workflows/audit.ts

@@ -41,12 +41,14 @@ export interface Finding {
   /** The section's code as written, comments and all, without blank lines at either end. */
   readonly excerpt: Excerpt;
   /**
-   * Jev's probability that the file does not show enough to check the rule,
-   * when its probability that it does is below the sufficiency threshold:
-   * the report warns, and says how to add the context.
+   * Jev's probability that the file shows enough to check the rule. Below the
+   * sufficiency threshold, the report warns, and says how to add the context.
    */
-  readonly insufficiency?: number;
+  readonly context?: number;
+  /** Jev's probability that the file breaks the rule. */
   readonly probability: number;
+  /** The rule's threshold: lint reports the finding only when its probability is above it. */
+  readonly threshold: number;
   /** An error fails the run; a warning does not, unless `--deny-warnings`. */
   readonly level: Level;
 }
@@ -109,12 +111,24 @@ const LAYOUT = "sections";
  * laid out, and the questions asked for the rule, which carry the rule: its
  * judge question, and its matchers' when it has any. An edited rule or
  * matcher re-judges the rule, and a question asked differently re-judges
- * every rule.
+ * every rule. So does an edited `appendState`, by its source; what the hook
+ * reads outside the file is not known until it runs, so a change there does
+ * not. A rule that reads the workspace's packages depends on them too, so a
+ * package added, renamed, or moved re-judges that rule and no other.
  */
-const fingerprintOf = (model: string, rule: Rule) => {
+const fingerprintOf = (
+  model: string,
+  rule: Rule,
+  workspacePackages: Readonly<Record<string, string>> = {},
+) => {
   const matchers = matcherQuestions("", rule).map(([, question]) => question);
   const scope = matchers.length === 0 ? "" : `\u0000${JSON.stringify(matchers)}`;
-  return sha256(`${model}\u0000${LAYOUT}\u0000${JSON.stringify(judgeQuestion(rule))}${scope}`);
+  const hook = rule.appendState === undefined ? "" : `\u0000${rule.appendState.toString()}`;
+  const packages =
+    rule.includeWorkspacePackages === true ? `\u0000${JSON.stringify(workspacePackages)}` : "";
+  return sha256(
+    `${model}\u0000${LAYOUT}\u0000${JSON.stringify(judgeQuestion(rule))}${scope}${hook}${packages}`,
+  );
 };
 
 /** A section's lines as written, without the blank lines at either end. */
@@ -192,6 +206,8 @@ export interface AuditPlan {
   readonly tokens: number;
   /** The model's price per million input tokens, in dollars, when adhere knows it. */
   readonly price?: number;
+  /** The run's threshold, which a rule's own, or an override's, replaces for that rule. */
+  readonly threshold: number;
   /** Below this, a finding's sufficiency adds a warning to it. */
   readonly sufficiencyThreshold: number;
 }
@@ -306,7 +322,7 @@ export const planAudit = (
       const prepared: Record<RuleId, PreparedRule> = yield* Effect.forEach(
         Object.entries(rules),
         ([id, rule]) =>
-          Effect.map(fingerprintOf(config.model, rule), (fingerprint) => {
+          Effect.map(fingerprintOf(config.model, rule, config.workspacePackages), (fingerprint) => {
             const preset = presetOfRule.get(rule);
             return [
               id,
@@ -459,6 +475,7 @@ export const planAudit = (
       requests: loads.reduce((sum, load) => sum + load.requests, 0),
       tokens: loads.reduce((sum, load) => sum + load.tokens, 0),
       ...(price === undefined ? {} : { price }),
+      threshold: config.threshold,
       sufficiencyThreshold: config.sufficiencyThreshold,
     };
   });
@@ -509,9 +526,13 @@ export const executeAudit = (
       deferred,
       sampled,
     }: FilePlan) {
+      // What a rule's appendState gets: the file as written, not as Jev reads it.
+      const asWritten = { path: file.path, contents: original.join("\n") };
       const { probabilities, linter, matchers }: Judged = isEmpty(pending)
         ? { probabilities: {}, linter: {} }
-        : yield* jev.judge(file.lines, rulesOf(pending), Object.keys(sampled)).pipe(inFile(file));
+        : yield* jev
+            .judge(file.lines, rulesOf(pending), Object.keys(sampled), asWritten)
+            .pipe(inFile(file));
       if (!isEmpty(linter)) yield* record(file.path, sampled, linter);
       const judged: Record<RuleId, Judgment> = { ...kept };
       for (const [id, probability] of Object.entries(probabilities)) {
@@ -549,7 +570,7 @@ export const executeAudit = (
         readonly blocked: Blocked | undefined;
       } = isEmpty(flagged)
         ? { places: {}, blocked: undefined }
-        : yield* jev.locate(file.lines, rulesOf(flagged)).pipe(
+        : yield* jev.locate(file.lines, rulesOf(flagged), asWritten).pipe(
             Effect.map((places) => ({ places, blocked: undefined })),
             Effect.catchTag("JevBlocked", ({ ray }) =>
               Effect.succeed({ places: {}, blocked: { file: file.path, ray } }),
@@ -581,11 +602,9 @@ export const executeAudit = (
                   section: judgment.section,
                   ...(judgment.lines === undefined ? {} : { lines: judgment.lines }),
                   excerpt: excerptOf(original, judgment.section),
-                  ...(judgment.sufficiency !== undefined &&
-                  judgment.sufficiency < plan.sufficiencyThreshold
-                    ? { insufficiency: 1 - judgment.sufficiency }
-                    : {}),
+                  ...(judgment.sufficiency === undefined ? {} : { context: judgment.sufficiency }),
                   probability: judgment.probability,
+                  threshold: k.threshold,
                   level: k.rule.level ?? "error",
                 },
               ]

package/src/workflows/format.ts

@@ -1,3 +1,4 @@
+import { DEFAULT_SUFFICIENCY_THRESHOLD, DEFAULT_THRESHOLD } from "#config.ts";
 import { type Kind, tokenize } from "#highlight.ts";
 import { shownId } from "#rules.ts";
 import type { AuditPlan, AuditResult, FileDone, Finding } from "#workflows/audit.ts";
@@ -11,11 +12,15 @@ type Role =
   | "error"
   | "warning"
   | "probability"
+  | "low"
+  | "below"
   | "description"
   | "path"
   | "lineNumber"
   | "underline"
   | "label"
+  | "legend"
+  | "quiet"
   | Kind;
 
 interface Span {
@@ -30,20 +35,28 @@ type Line = ReadonlyArray<Span>;
  * palette (`38;5;N`) or truecolor (`38;2;R;G;B`), bold with a trailing `;1`,
  * and a dim line number. Of the header, only the `×` and the rule are red, or
  * a warning's `⚠` and rule amber, since a whole line of red is hard to read:
- * the probability is an accent, and the description a cool near-white, set
- * here since a theme's own white can be gray. The code's are the terminal's
- * own colors (`3N`), so the user's theme picks shades that read on its
- * background; none is magenta, which would run into the underline.
+ * the description is a cool near-white, set here since a theme's own white
+ * can be gray. A score's three colors are one set, of like lightness, so
+ * they read as a scale, and none is the red of the `×`. Its labels, and the
+ * legend's meanings, are dim. The legend's words are bold in the terminal's
+ * own color, so they do not read as the hint's label. The code's are the
+ * terminal's own colors (`3N`), so the
+ * user's theme picks shades that read on its background; none is magenta,
+ * which would run into the underline.
  */
 const THEME: Readonly<Record<Role, string>> = {
   error: "38;2;164;20;71;1",
   warning: "38;2;214;154;0;1",
-  probability: "38;5;156",
+  probability: "38;2;152;195;121",
+  low: "38;2;229;192;123",
+  below: "38;2;224;108;117",
   description: "38;2;230;230;255",
   path: "38;2;5;125;160;1",
   lineNumber: "2",
   underline: "38;2;255;0;175",
   label: "38;2;242;205;205",
+  legend: "1",
+  quiet: "2",
   comment: "2",
   string: "32",
   constant: "33",
@@ -90,15 +103,60 @@ const displayPath = (file: string, root: string | undefined): string =>
 const counted = (count: number, one: string, many: string): string =>
   `${count} ${count === 1 ? one : many}`;
 
-const header = (finding: Finding): Line => [
-  span("  "),
-  span(finding.level === "warning" ? "⚠" : "×", finding.level),
-  span(" "),
-  span(shownId({ id: finding.rule, preset: finding.preset }), finding.level),
-  span(" ("),
-  span(finding.probability.toFixed(2), "probability"),
-  span("): "),
-  span(finding.description, "description"),
+/** A score as a header shows it, in hundredths, so two compare as they read. */
+const hundredths = (value: number): number => Math.round(value * 100);
+
+/**
+ * Where a confidence stops being far below a threshold and where it starts
+ * being well above it, in hundredths. Between the two it is near the
+ * threshold: within a quarter of the room above it, on either side, so the
+ * band narrows as the threshold rises and leaves room above for scores to be
+ * well clear of it. Scores that gather in the band, reported or not, turn on
+ * where the threshold sits, a sign it may be too low or too high.
+ */
+const bandsOf = (threshold: number): { readonly near: number; readonly clear: number } => {
+  const at = hundredths(threshold);
+  const margin = (100 - at) / 4;
+  return { near: Math.max(0, Math.ceil(at - margin)), clear: Math.ceil(at + margin) };
+};
+
+/**
+ * A score in one of three ranges set by its threshold: amber near it, red
+ * below that, the accent above. A confidence's threshold is its rule's, and
+ * a red one shows only in a run that prints every judgment. A context's is
+ * the sufficiency threshold, and a red one marks the finding to doubt first.
+ */
+const score = (value: number, threshold: number): Span => {
+  const { near, clear } = bandsOf(threshold);
+  const shown = hundredths(value);
+  return span(value.toFixed(2), shown < near ? "below" : shown < clear ? "low" : "probability");
+};
+
+const lacksContext = (finding: Finding, sufficiencyThreshold: number): boolean =>
+  finding.context !== undefined && finding.context < sufficiencyThreshold;
+
+/**
+ * The rule and its description, as `vp lint` heads a diagnostic, then the
+ * scores on a line of their own, where they start in one place whatever the
+ * rule's length. Their labels are dim, so only the numbers carry color.
+ */
+const header = (finding: Finding, sufficiencyThreshold: number): ReadonlyArray<Line> => [
+  [
+    span("  "),
+    span(finding.level === "warning" ? "⚠" : "×", finding.level),
+    span(" "),
+    span(shownId({ id: finding.rule, preset: finding.preset }), finding.level),
+    span(": "),
+    span(finding.description, "description"),
+  ],
+  [
+    span("    "),
+    span("confidence ", "quiet"),
+    score(finding.probability, finding.threshold),
+    ...(finding.context === undefined
+      ? []
+      : [span(" · context ", "quiet"), score(finding.context, sufficiencyThreshold)]),
+  ],
 ];
 
 /**
@@ -151,19 +209,14 @@ const excerpt = (finding: Finding, root: string | undefined): ReadonlyArray<Line
 
 /**
  * The warning on a finding whose file may not show enough to check its rule,
- * with Jev's probability that it does not, and help: how to add what the
- * code relies on as a note Jev reads, in the form the README asks for.
+ * which its context score in the header says how far, and help: how to add
+ * what the code relies on as a note Jev reads, in the form the README asks for.
  */
-const insufficient = (finding: Finding): ReadonlyArray<Line> =>
-  finding.insufficiency === undefined
+const insufficient = (finding: Finding, sufficiencyThreshold: number): ReadonlyArray<Line> =>
+  !lacksContext(finding, sufficiencyThreshold)
     ? []
     : [
-        [
-          span("  warning: ", "warning"),
-          span(
-            `this file may not show enough to check this rule (Jev: ${finding.insufficiency.toFixed(2)} that it does not)`,
-          ),
-        ],
+        [span("  warning: ", "warning"), span("this file may not show enough to check this rule")],
         ...hanging(span("     help: ", "label"), [
           [span("add what the code relies on outside this file as a note Jev reads:")],
           highlighted("// @adhere <the fact>, and how you know it")[0] ?? [],
@@ -183,17 +236,91 @@ const hint = (finding: Finding): ReadonlyArray<Line> => {
 
 /**
  * One diagnostic, in the frame `vp lint` prints on a terminal: a header with
- * the rule in red, the section of the file Jev points at with the lines it
- * names in pink, a warning when the file may not show enough to decide, and
- * the code to write as the hint.
+ * the rule in red and its scores, the description, the section of the file
+ * Jev points at with the lines it names in pink, a warning when the file may
+ * not show enough to decide, and the code to write as the hint.
  */
-const frame = (finding: Finding, root: string | undefined): ReadonlyArray<Line> => [
-  header(finding),
+const frame = (
+  finding: Finding,
+  root: string | undefined,
+  sufficiencyThreshold: number,
+): ReadonlyArray<Line> => [
+  ...header(finding, sufficiencyThreshold),
   ...excerpt(finding, root),
-  ...insufficient(finding),
+  ...insufficient(finding, sufficiencyThreshold),
   ...hint(finding),
 ];
 
+/** A bound of a range: hundredths as a score shows them, and 0 and 1 without decimals. */
+const bound = (value: number): string =>
+  value === 0 ? "0" : value === 100 ? "1" : (value / 100).toFixed(2);
+
+/** The scores from one number of hundredths through another: `0–0.74`, or `0.85–1`. */
+const range = (from: number, to: number): string => `${bound(from)}–${bound(to)}`;
+
+/**
+ * A legend row's cells for a threshold: the scores far below it, the
+ * threshold, and the scores well above it, as in `0–0.74 < 0.8 < 0.85–1`.
+ * The scores between the two ranges are the ones near the threshold, so it
+ * and each `<` are in their color, and the ranges in theirs. A threshold too low to
+ * have scores far below it has no first range, and no `<` after one.
+ */
+const cellsOf = (threshold: number): ReadonlyArray<Span> => {
+  const { near, clear } = bandsOf(threshold);
+  return [
+    span(near > 0 ? range(0, near - 1) : "", "below"),
+    span(near > 0 ? "<" : "", "low"),
+    span(String(hundredths(threshold) / 100), "low"),
+    span("<", "low"),
+    span(range(clear, 100), "probability"),
+  ];
+};
+
+/**
+ * What the scores under a header mean, once under the findings, as a table:
+ * a row for each score with its ranges around its threshold, then what the
+ * score is, dim. The cells stand in columns, so a color lines up down the
+ * rows. A confidence's threshold is the run's; a rule with a threshold of
+ * its own has its ranges around that. A context's is the sufficiency
+ * threshold.
+ */
+const legend = (
+  result: AuditResult,
+  threshold: number,
+  sufficiencyThreshold: number,
+): ReadonlyArray<Line> => {
+  const rows = [
+    ["confidence", cellsOf(threshold), "Jev's probability that the file breaks the rule"],
+    [
+      "context",
+      cellsOf(sufficiencyThreshold),
+      "its probability that the file shows enough to decide",
+    ],
+  ] as const;
+  const padding = (text: string, width: number): Span => span(" ".repeat(width - text.length));
+  const labels = Math.max(...rows.map(([label]) => label.length));
+  const widthOf = (column: number): number =>
+    Math.max(...rows.map(([, cells]) => cells[column]?.text.length ?? 0));
+  return result.findings.length === 0
+    ? []
+    : [
+        ...rows.map(([label, cells, meaning]) => [
+          span("  "),
+          span(label, "legend"),
+          padding(label, labels),
+          span(" "),
+          ...cells.flatMap((cell, column) => [
+            span(" "),
+            cell,
+            padding(cell.text, widthOf(column)),
+          ]),
+          span("  "),
+          span(meaning, "quiet"),
+        ]),
+        [],
+      ];
+};
+
 /** The findings counted by level: `1 error`, or `2 errors and 1 warning` once there are warnings. */
 const found = (findings: ReadonlyArray<Finding>): string => {
   const warnings = findings.filter((finding) => finding.level === "warning").length;
@@ -239,19 +366,29 @@ export interface RenderOptions {
   /** Color the frame the way `vp lint` does on a terminal, and highlight the code. */
   readonly color?: boolean;
   readonly root?: string;
+  /** The run's threshold, for the legend: lint reports no finding at or below it. Defaults to 0.8. */
+  readonly threshold?: number;
+  /** Below this, a finding's context is low and it carries a warning. Defaults to 0.6. */
+  readonly sufficiencyThreshold?: number;
 }
 
 /**
  * The report, in the default `vp lint` layout: each diagnostic followed by a
- * blank line, then the counts. Color is on when the caller is writing to a
- * terminal.
+ * blank line, then the legend for their scores, then the counts. Color is on
+ * when the caller is writing to a terminal.
  */
-export const render = (result: AuditResult, options: RenderOptions = {}): ReadonlyArray<string> =>
-  [
-    ...result.findings.flatMap((finding) => [...frame(finding, options.root), []]),
+export const render = (result: AuditResult, options: RenderOptions = {}): ReadonlyArray<string> => {
+  const sufficiencyThreshold = options.sufficiencyThreshold ?? DEFAULT_SUFFICIENCY_THRESHOLD;
+  return [
+    ...result.findings.flatMap((finding) => [
+      ...frame(finding, options.root, sufficiencyThreshold),
+      [],
+    ]),
+    ...legend(result, options.threshold ?? DEFAULT_THRESHOLD, sufficiencyThreshold),
     ...summary(result),
     ...blockedFiles(result, options.root),
   ].map((line) => serialize(line, options.color === true));
+};
 
 /**
  * What a run will do, before it asks: the files and rules found, the checks