@drkmttr/adhere 0.7.1 → 0.8.0

package/src/services/SourceWalker.ts

@@ -79,9 +79,16 @@ const scannable = (root: string, paths: ReadonlyArray<string>, self: string, kee
 /** One root's paths, filtered to what the audit reads. */
 const listRoot = Effect.fn("SourceWalker.listRoot")(
   (fs: FileSystem.FileSystem, root: string, self: string, keep: Keep) =>
-    Effect.map(fs.readDirectory(root, { recursive: true }), (paths) =>
-      scannable(root, paths, self, keep),
-    ),
+    Effect.flatMap(fs.readDirectory(root, { recursive: true }), (paths) => {
+      const files = scannable(root, paths, self, keep);
+      // The paths listed against the files kept: node_modules shows as the difference.
+      return Effect.as(
+        Effect.logDebug(
+          `listed ${root}: ${paths.length} paths, ${files.length} source files to read`,
+        ),
+        files,
+      );
+    }),
 );
 
 /** One scannable path, read into lines. */
@@ -89,7 +96,7 @@ const readFile = Effect.fn("SourceWalker.readFile")((fs: FileSystem.FileSystem,
   Effect.map(fs.readFileString(path), (content): ScannedFile => ({
     path,
     lines: content.split("\n"),
-  })),
+  })).pipe(Effect.tap((file) => Effect.logTrace(`read ${path}: ${file.lines.length} lines`))),
 );
 
 /** Read a batch of paths; the inner loop hoisted out of `forEach`. */

package/src/wording.ts

@@ -0,0 +1,90 @@
+import { type Example, examplesOf, type Rule } from "#config.ts";
+import type { RuleEntry } from "#rules.ts";
+
+type Word = Example["word"];
+
+/**
+ * A way a rule's wording differs from the README's rule writing tips, which
+ * the eval measured: the rule shows code of both kinds, and its description
+ * says the words its code is under.
+ */
+export type Straying =
+  /** The rule has code under `word`, and its description does not say it. */
+  | { readonly _tag: "Unsaid"; readonly word: Word }
+  /** The rule has code to write, and no example under `word` of code that breaks it. */
+  | { readonly _tag: "Unshown"; readonly word: Word }
+  /** The description says `word`, which belongs to the other kind of rule. */
+  | { readonly _tag: "Mixed"; readonly word: Word };
+
+/** A rule whose wording differs from the tips, with each way it does. */
+export interface Stray {
+  readonly entry: RuleEntry;
+  readonly straying: ReadonlyArray<Straying>;
+}
+
+export const TIPS_URL = "https://github.com/darkmatter/adhere#rule-writing-tips";
+
+/** Whether a description says a word, whole and in any case: "Must" does, "mustard" does not. */
+const says = (description: string, word: Word): boolean =>
+  new RegExp(`\\b${word.replace(" ", "\\s+")}\\b`, "i").test(description);
+
+/**
+ * How one rule strays from the tips. A rule with only code that breaks it
+ * lacks no example: the README keeps that for a rule with no single correct
+ * form to show.
+ */
+export const strayingOf = (rule: Rule): ReadonlyArray<Straying> => {
+  const { good, bad } = examplesOf(rule);
+  const guideline = good?.word === "should" || bad?.word === "should not";
+  const shown = [good, bad].flatMap((example) => (example === undefined ? [] : [example.word]));
+  const unshown: ReadonlyArray<Word> =
+    good !== undefined && bad === undefined ? [guideline ? "should not" : "never"] : [];
+  // "should" also finds "should not", so a requirement is checked for the one word.
+  const others: ReadonlyArray<Word> = guideline ? ["must", "never"] : ["should"];
+  return [
+    ...shown
+      .filter((word) => !says(rule.description, word))
+      .map((word): Straying => ({ _tag: "Unsaid", word })),
+    ...unshown.map((word): Straying => ({ _tag: "Unshown", word })),
+    ...others
+      .filter((word) => says(rule.description, word))
+      .map((word): Straying => ({ _tag: "Mixed", word })),
+  ];
+};
+
+/** The rules that stray, in the order given. */
+export const straysAmong = (entries: ReadonlyArray<RuleEntry>): ReadonlyArray<Stray> =>
+  entries.flatMap((entry) => {
+    const straying = strayingOf(entry.rule);
+    return straying.length === 0 ? [] : [{ entry, straying }];
+  });
+
+/** One way a rule strays, as a sentence. */
+const sentenceOf = (straying: Straying): string => {
+  switch (straying._tag) {
+    case "Unsaid":
+      return `The description does not say "${straying.word}", though the rule has a ${straying.word} example.`;
+    case "Unshown":
+      return `The rule has no ${straying.word} example. Rules with one example of each kind judge best.`;
+    case "Mixed":
+      return straying.word === "should"
+        ? `The description says "should", a guideline's word, but the rule is a requirement.`
+        : `The description says "${straying.word}", a requirement's word, but the rule is a guideline.`;
+  }
+};
+
+const displayPath = (file: string, root: string): string =>
+  file.startsWith(`${root}/`) ? file.slice(root.length + 1) : file;
+
+/** The wording part of `adhere validate`'s report: each rule that strays, then how. */
+export const formatStrays = (strays: ReadonlyArray<Stray>, root: string): ReadonlyArray<string> =>
+  strays.length === 0
+    ? ["Every rule is worded as the rule writing tips recommend."]
+    : [
+        `${strays.length} ${strays.length === 1 ? "rule is" : "rules are"} not worded as the rule writing tips recommend:`,
+        ...strays.flatMap(({ entry, straying }) => [
+          `  ${entry.id}${entry.file === undefined ? "" : ` (${displayPath(entry.file, root)})`}`,
+          ...straying.map((one) => `    ${sentenceOf(one)}`),
+        ]),
+        `Rule writing tips: ${TIPS_URL}`,
+      ];

package/src/workflows/audit.ts

@@ -1,19 +1,24 @@
 import { type Examples, examplesOf, type Rule, type RuleId } from "#config.ts";
+import { type Excerpt, excerptOf } from "#excerpt.ts";
 import type { ScannedFile, WalkUnavailable } from "#models/Audit.ts";
 import { AdhereConfig } from "#services/AdhereConfig.ts";
-import { AuditCache, type Judgment, sha256 } from "#services/AuditCache.ts";
+import { AuditCache, answersOf, type Judgment, sha256, type Tally } from "#services/AuditCache.ts";
 import {
   fits,
   Jev,
   JevUnavailable,
+  type Judged,
   judgeQuestion,
   judgeRequests,
+  linterQuestion,
   locateRequests,
-  snippetOf,
+  questionRoom,
+  tokensOf,
 } from "#services/Jev.ts";
 import { SourceWalker } from "#services/SourceWalker.ts";
+import { SAMPLE, tallyKeyOf } from "#mechanical.ts";
 import { applicableRules } from "#rules.ts";
-import { type Crypto, Effect, Record } from "effect";
+import { type Crypto, Duration, Effect, Record, Result, Semaphore } from "effect";
 
 export interface Finding {
   readonly rule: RuleId;
@@ -21,7 +26,8 @@ export interface Finding {
   readonly examples: Examples;
   readonly file: string;
   readonly line: number;
-  readonly snippet: string;
+  /** The code around `line` the report shows. */
+  readonly excerpt: Excerpt;
   readonly probability: number;
 }
 
@@ -32,12 +38,21 @@ export interface AuditResult {
   readonly skipped: number;
   /** Files whose checks `--limit` left for a later run, none judged in this one. */
   readonly waiting: number;
+  /** Files the firewall in front of Jev's API refused, with the ID to report each by. */
+  readonly blocked: ReadonlyArray<Blocked>;
   readonly findings: ReadonlyArray<Finding>;
 }
 
+/** A file whose request the firewall refused, and Cloudflare's Ray ID for the refusal. */
+export interface Blocked {
+  readonly file: string;
+  readonly ray: string;
+}
+
 interface FileResult {
-  readonly status: "judged" | "cached" | "skipped" | "waiting";
+  readonly status: "judged" | "cached" | "skipped" | "waiting" | "blocked";
   readonly findings: ReadonlyArray<Finding>;
+  readonly blocked?: Blocked;
 }
 
 interface PreparedRule {
@@ -73,6 +88,8 @@ export interface FilePlan {
   readonly pending: Readonly<Record<RuleId, PreparedRule>>;
   /** Pending checks `--limit` leaves for a later run. */
   readonly deferred: number;
+  /** Pending rules whose linter check question rides along on this file, each with its tally's key. */
+  readonly sampled: Readonly<Record<RuleId, string>>;
 }
 
 /** A run worked out from the files, the rules, and the cache, before any request. */
@@ -159,6 +176,7 @@ export const planAudit = (
       const rules = configuredRules(file.path);
       // Too long for Jev's context: skipped and counted, rather than refused mid-run.
       if (!fits(file.lines, rules)) {
+        yield* Effect.logTrace(`plan ${file.path}: too long for Jev's context, skipped`);
         return {
           file,
           skipped: true,
@@ -167,6 +185,7 @@ export const planAudit = (
           kept: {},
           pending: {},
           deferred: 0,
+          sampled: {},
         } satisfies FilePlan;
       }
       const prepared: Record<RuleId, PreparedRule> = yield* Effect.forEach(
@@ -179,13 +198,15 @@ export const planAudit = (
           ),
       ).pipe(Effect.map(Record.fromEntries));
       const hash = yield* sha256(file.lines.join("\n"));
-      const entry = yield* cache.get(file.path);
-      const remembered = entry?.hash === hash ? entry.judgments : {};
-      const kept = Record.filter(
-        remembered,
-        (judgment, id) => judgment.fingerprint === prepared[id]?.fingerprint,
-      );
+      const answers = yield* cache.get(hash, file.path);
+      const kept: Record<RuleId, Judgment> = Record.filterMap(prepared, ({ fingerprint }) => {
+        const answer = answers[fingerprint];
+        return answer === undefined ? Result.failVoid : Result.succeed({ fingerprint, ...answer });
+      });
       const pending = Record.filter(prepared, (_, id) => kept[id] === undefined);
+      yield* Effect.logTrace(
+        `plan ${file.path}: ${sizeOf(prepared)} rules, ${sizeOf(kept)} cached, ${sizeOf(pending)} to judge`,
+      );
       return {
         file,
         skipped: false,
@@ -194,15 +215,78 @@ export const planAudit = (
         kept,
         pending,
         deferred: 0,
+        sampled: {},
       } satisfies FilePlan;
     });
 
+    // Preset rules are not the project's to change, so the linter check leaves them out.
+    const presetRules = new Set(
+      (config.scopedRules ?? []).flatMap((entry) =>
+        entry.preset === undefined ? [] : [entry.rule],
+      ),
+    );
+
+    /**
+     * The linter check's samples: for each project rule its tally still needs
+     * answers for, files this run judges it on, spread evenly over them in path
+     * order, skipping files the tally has and files its question would not fit.
+     */
+    const withSamples = Effect.fn("audit.samples")(function* (plans: ReadonlyArray<FilePlan>) {
+      const needs = new Map<Rule, { readonly key: string; readonly tallied: Tally["files"] }>();
+      for (const plan of plans) {
+        for (const { rule } of Object.values(plan.pending)) {
+          if (presetRules.has(rule) || needs.has(rule)) continue;
+          const key = yield* tallyKeyOf(config.model, rule);
+          needs.set(rule, { key, tallied: (yield* cache.tally(key))?.files ?? {} });
+        }
+      }
+      for (const [rule, { tallied }] of needs) {
+        if (Object.keys(tallied).length >= SAMPLE) needs.delete(rule);
+      }
+      if (needs.size === 0) return plans;
+
+      const candidates = new Map<Rule, Array<{ readonly plan: FilePlan; readonly id: RuleId }>>();
+      const tokens = new Map<Rule, number>();
+      for (const plan of plans) {
+        let room: number | undefined;
+        for (const [id, { rule }] of Object.entries(plan.pending)) {
+          const need = needs.get(rule);
+          if (need === undefined || need.tallied[plan.file.path] !== undefined) continue;
+          room ??= questionRoom(plan.file.lines);
+          const size = tokens.get(rule) ?? tokensOf(linterQuestion(rule));
+          tokens.set(rule, size);
+          if (size > room) continue;
+          const found = candidates.get(rule);
+          if (found === undefined) candidates.set(rule, [{ plan, id }]);
+          else found.push({ plan, id });
+        }
+      }
+
+      const sampled = new Map<FilePlan, Record<RuleId, string>>();
+      for (const [rule, found] of candidates) {
+        const need = needs.get(rule);
+        if (need === undefined) continue;
+        const count = Math.min(found.length, SAMPLE - Object.keys(need.tallied).length);
+        for (let index = 0; index < count; index++) {
+          const pick = found[Math.floor((index * found.length) / count)];
+          if (pick !== undefined) {
+            sampled.set(pick.plan, { ...sampled.get(pick.plan), [pick.id]: need.key });
+          }
+        }
+      }
+      return plans.map((plan) => {
+        const some = sampled.get(plan);
+        return some === undefined ? plan : { ...plan, sampled: some };
+      });
+    });
+
     const sorted = [...files].sort((a, b) => a.path.localeCompare(b.path));
     const everything: ReadonlyArray<FilePlan> = yield* Effect.forEach(sorted, planFile, {
       concurrency: 8,
     });
-    const planned =
+    const limited =
       options.limit === undefined ? everything : withinLimit(everything, options.limit);
+    const planned = yield* withSamples(limited);
     const judged = planned.filter((plan) => !plan.skipped);
     const total = (count: (plan: FilePlan) => number) =>
       judged.reduce((sum, plan) => sum + count(plan), 0);
@@ -214,7 +298,9 @@ export const planAudit = (
       skipped: planned.length - judged.length,
       deferred: total((plan) => plan.deferred),
       requests: total((plan) =>
-        isEmpty(plan.pending) ? 0 : judgeRequests(plan.file.lines, rulesOf(plan.pending)),
+        isEmpty(plan.pending)
+          ? 0
+          : judgeRequests(plan.file.lines, rulesOf(plan.pending), Object.keys(plan.sampled)),
       ),
     };
   });
@@ -230,6 +316,29 @@ export const executeAudit = (
   Effect.gen(function* () {
     const jev = yield* Jev;
     const cache = yield* AuditCache;
+    // Files finish together; each tally is read, extended, and written back by one file at a time.
+    const tallying = yield* Semaphore.make(1);
+
+    /** Adds one file's linter check answers to their rules' tallies. */
+    const record = (
+      file: string,
+      sampled: Readonly<Record<RuleId, string>>,
+      linter: Readonly<Record<RuleId, number>>,
+    ) =>
+      tallying.withPermits(1)(
+        Effect.forEach(
+          Object.entries(linter),
+          ([id, probability]) => {
+            const key = sampled[id];
+            return key === undefined
+              ? Effect.void
+              : Effect.flatMap(cache.tally(key), (tally) =>
+                  cache.putTally(key, { files: { ...tally?.files, [file]: probability } }),
+                );
+          },
+          { discard: true },
+        ),
+      );
 
     /** Judges and locates one file the plan left pending, with the requests that took. */
     const judgeFile = Effect.fn("audit.judgeFile")(function* ({
@@ -239,10 +348,12 @@ export const executeAudit = (
       kept,
       pending,
       deferred,
+      sampled,
     }: FilePlan) {
-      const probabilities = isEmpty(pending)
-        ? {}
-        : yield* jev.judge(file.lines, rulesOf(pending)).pipe(inFile(file));
+      const { probabilities, linter }: Judged = isEmpty(pending)
+        ? { probabilities: {}, linter: {} }
+        : yield* jev.judge(file.lines, rulesOf(pending), Object.keys(sampled)).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)) {
         const k = pending[id];
@@ -257,18 +368,29 @@ export const executeAudit = (
           judgment.line === undefined
         );
       });
-      const lines = isEmpty(flagged)
-        ? {}
-        : yield* jev.locate(file.lines, rulesOf(flagged)).pipe(inFile(file));
+      // A blocked line question still leaves the judgments worth caching: a rerun
+      // asks only for the lines again, not for every rule.
+      const {
+        lines,
+        blocked,
+      }: { readonly lines: Readonly<Record<RuleId, number>>; readonly blocked?: Blocked } = isEmpty(
+        flagged,
+      )
+        ? { lines: {}, blocked: undefined }
+        : yield* jev.locate(file.lines, rulesOf(flagged)).pipe(
+            Effect.map((lines) => ({ lines, blocked: undefined })),
+            Effect.catchTag("JevBlocked", ({ ray }) =>
+              Effect.succeed({ lines: {}, blocked: { file: file.path, ray } }),
+            ),
+            inFile(file),
+          );
       const located = Record.map(judged, (judgment, id) => {
         const line = lines[id];
-        return line === undefined
-          ? judgment
-          : { ...judgment, line, snippet: snippetOf(file.lines[line - 1] ?? "") };
+        return line === undefined ? judgment : { ...judgment, line };
       });
 
       const cached = isEmpty(pending) && isEmpty(flagged);
-      if (!cached) yield* cache.put(file.path, { hash, judgments: located });
+      if (!cached) yield* cache.put(hash, answersOf(located));
 
       const findings = Object.entries(located)
         .flatMap(([id, judgment]): ReadonlyArray<Finding> => {
@@ -283,7 +405,7 @@ export const executeAudit = (
                   examples: examplesOf(k.rule),
                   file: file.path,
                   line: judgment.line,
-                  snippet: judgment.snippet ?? "",
+                  excerpt: excerptOf(file.lines, judgment.line),
                   probability: judgment.probability,
                 },
               ]
@@ -291,25 +413,60 @@ export const executeAudit = (
         })
         .sort((a, b) => a.line - b.line);
       return {
-        result: fileResult(cached ? (deferred > 0 ? "waiting" : "cached") : "judged", findings),
+        result:
+          blocked === undefined
+            ? fileResult(cached ? (deferred > 0 ? "waiting" : "cached") : "judged", findings)
+            : { status: "blocked", findings, blocked },
         requests:
-          (isEmpty(pending) ? 0 : judgeRequests(file.lines, rulesOf(pending))) +
+          (isEmpty(pending)
+            ? 0
+            : judgeRequests(file.lines, rulesOf(pending), Object.keys(sampled))) +
           (isEmpty(flagged) ? 0 : locateRequests(file.lines, rulesOf(flagged))),
       };
     });
 
     const auditFile = Effect.fn("audit.file")(function* (plan: FilePlan) {
-      const { result, requests } = plan.skipped
-        ? { result: fileResult("skipped", []), requests: 0 }
-        : yield* judgeFile(plan).pipe(
+      const judging = plan.skipped
+        ? Effect.succeed({ result: fileResult("skipped", []), requests: 0 })
+        : judgeFile(plan).pipe(
             // Jev counted more than `fits` estimated. Its count decides: skipped the same way.
             Effect.catchTag("JevOverflow", () =>
               Effect.succeed({
                 result: fileResult("skipped", []),
-                requests: judgeRequests(plan.file.lines, rulesOf(plan.pending)),
+                requests: judgeRequests(
+                  plan.file.lines,
+                  rulesOf(plan.pending),
+                  Object.keys(plan.sampled),
+                ),
+              }),
+            ),
+            // The firewall refuses this file's code every time; the rest of the run goes on.
+            Effect.catchTag("JevBlocked", ({ ray }) =>
+              Effect.succeed({
+                result: {
+                  status: "blocked",
+                  findings: [],
+                  blocked: { file: plan.file.path, ray },
+                } satisfies FileResult,
+                requests: judgeRequests(
+                  plan.file.lines,
+                  rulesOf(plan.pending),
+                  Object.keys(plan.sampled),
+                ),
               }),
             ),
           );
+      // Everything logged while judging a file, requests included, names the file.
+      // A file that sent nothing, whether cached or too long, is a trace line: a
+      // large repo's cache would otherwise bury the requests.
+      const [, { result, requests }] = yield* Effect.timed(judging).pipe(
+        Effect.tap(([elapsed, { result, requests }]) =>
+          (requests > 0 ? Effect.logDebug : Effect.logTrace)(
+            `${result.status}: ${requests} ${requests === 1 ? "request" : "requests"}, ${result.findings.length} ${result.findings.length === 1 ? "finding" : "findings"}, ${Math.round(Duration.toMillis(elapsed))} ms`,
+          ),
+        ),
+        Effect.annotateLogs("file", plan.file.path),
+      );
       yield* progress({ requests, findings: result.findings.length });
       return result;
     });
@@ -323,10 +480,33 @@ export const executeAudit = (
       cached: count("cached"),
       skipped: count("skipped"),
       waiting: count("waiting"),
+      blocked: results.flatMap((result) => (result.blocked === undefined ? [] : [result.blocked])),
       findings: results.flatMap((result) => result.findings),
     };
   });
 
+/**
+ * Deletes from the cache what the files and rules of a run no longer need:
+ * answers about content no file has, answers to rule texts no rule asks, and
+ * tallies of rules gone. Only after a run that read every file; a run narrowed
+ * by `--filter` cannot tell what the files it left out need.
+ */
+export const pruneCache = Effect.fn("audit.prune")(function* (plan: AuditPlan) {
+  const config = yield* AdhereConfig;
+  const cache = yield* AuditCache;
+  const read = plan.files.filter((file) => !file.skipped);
+  const prepared = read.flatMap((file) => Object.values(file.prepared));
+  const tallies = yield* Effect.forEach(new Set(prepared.map(({ rule }) => rule)), (rule) =>
+    tallyKeyOf(config.model, rule),
+  );
+  const deleted = yield* cache.prune({
+    hashes: new Set(read.map((file) => file.hash)),
+    fingerprints: new Set(prepared.map(({ fingerprint }) => fingerprint)),
+    tallies: new Set(tallies),
+  });
+  yield* Effect.logDebug(`cache pruned: ${deleted} ${deleted === 1 ? "file" : "files"} deleted`);
+});
+
 /** Plans the run and executes it, without asking and without a counter. */
 export const runAudit: Effect.Effect<
   AuditResult,

package/src/workflows/format.ts

@@ -6,7 +6,15 @@ import type { AuditPlan, AuditResult, FileDone, Finding } from "#workflows/audit
  * token of code, named by its role. Layout measures text; only `serialize`
  * turns a role into color, so no width or blank line ever sees an escape code.
  */
-type Role = "error" | "path" | "lineNumber" | "underline" | "label" | Kind;
+type Role =
+  | "error"
+  | "probability"
+  | "description"
+  | "path"
+  | "lineNumber"
+  | "underline"
+  | "label"
+  | Kind;
 
 interface Span {
   readonly text: string;
@@ -16,17 +24,23 @@ interface Span {
 type Line = ReadonlyArray<Span>;
 
 /**
- * SGR parameters per role. The frame's match `vp lint`: truecolor
- * (`38;2;R;G;B`), bold with a trailing `;1`, and a dim line number. 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 label.
+ * SGR parameters per role. The frame's are set colors, from the 256-color
+ * 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,
+ * 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.
  */
 const THEME: Readonly<Record<Role, string>> = {
-  error: "38;2;219;91;81;1",
+  error: "38;2;164;20;71;1",
+  probability: "38;5;156",
+  description: "38;2;230;230;255",
   path: "38;2;5;125;160;1",
   lineNumber: "2",
   underline: "38;2;255;0;175",
-  label: "38;2;180;105;245",
+  label: "38;2;242;205;205",
   comment: "2",
   string: "32",
   constant: "33",
@@ -77,22 +91,40 @@ const header = (finding: Finding): Line => [
   span("  "),
   span("×", "error"),
   span(" "),
-  span(`${finding.rule} (${finding.probability.toFixed(2)})`, "error"),
-  span(": "),
-  span(finding.description, "error"),
+  span(finding.rule, "error"),
+  span(" ("),
+  span(finding.probability.toFixed(2), "probability"),
+  span("): "),
+  span(finding.description, "description"),
 ];
 
-/** The path, the offending line numbered in the gutter, and an underline as long as the line. */
+/**
+ * The path, then the finding's excerpt with each line numbered in the gutter,
+ * and an underline under the offending line's code.
+ */
 const excerpt = (finding: Finding, root: string | undefined): ReadonlyArray<Line> => {
-  const number = String(finding.line);
-  const gutter = span(" ".repeat(number.length + 2));
-  // A snippet is one line: `snippetOf` trims it out of the file.
-  const [code = []] = highlighted(finding.snippet);
-  const underline = "─".repeat(Math.max(1, finding.snippet.trim().length));
+  const { start, lines } = finding.excerpt;
+  const width = String(start + lines.length - 1).length;
+  const gutter = span(" ".repeat(width + 2));
+  const offending = lines[finding.line - start] ?? "";
+  // The line's own indentation, tabs and all, lines the underline up under its code.
+  const indent = offending.slice(0, offending.length - offending.trimStart().length);
+  const underline = "─".repeat(Math.max(1, offending.trim().length));
+  const location = `:${finding.line}:${indent.length + 1}]`;
   return [
-    [gutter, span("╭─["), span(displayPath(finding.file, root), "path"), span(`:${number}:1]`)],
-    [span(" "), span(number, "lineNumber"), span(" │ "), ...code],
-    [gutter, span("· "), span(underline, "underline")],
+    [gutter, span("╭─["), span(displayPath(finding.file, root), "path"), span(location)],
+    ...highlighted(lines.join("\n")).flatMap((code, index): ReadonlyArray<Line> => {
+      const number = String(start + index);
+      const numbered = [
+        span(" ".repeat(width - number.length + 1)),
+        span(number, "lineNumber"),
+        span(" │ "),
+        ...code,
+      ];
+      return start + index === finding.line
+        ? [numbered, [gutter, span("· "), span(indent), span(underline, "underline")]]
+        : [numbered];
+    }),
     [gutter, span("╰────")],
   ];
 };
@@ -109,8 +141,9 @@ const hint = (finding: Finding): ReadonlyArray<Line> => {
 };
 
 /**
- * One diagnostic, in the frame `vp lint` prints on a terminal: a red header,
- * the offending line, a pink underline, and the code to write as the hint.
+ * One diagnostic, in the frame `vp lint` prints on a terminal: a header with
+ * the rule in red, the code around the offending line, a pink underline under
+ * it, and the code to write as the hint.
  */
 const frame = (finding: Finding, root: string | undefined): ReadonlyArray<Line> => [
   header(finding),
@@ -125,6 +158,7 @@ const summary = (result: AuditResult): ReadonlyArray<Line> => {
     `${result.cached} cached`,
     ...(result.skipped > 0 ? [`${result.skipped} skipped`] : []),
     ...(result.waiting > 0 ? [`${result.waiting} waiting`] : []),
+    ...(result.blocked.length > 0 ? [`${result.blocked.length} blocked`] : []),
   ];
   return [
     [span(`Found ${counted(result.findings.length, "error", "errors")}.`)],
@@ -132,6 +166,27 @@ const summary = (result: AuditResult): ReadonlyArray<Line> => {
   ];
 };
 
+/**
+ * The files the firewall in front of Jev's API refused, each with the Ray ID
+ * TypeSafe AI can look the block up by, so a gap in the audit says where it is.
+ */
+const blockedFiles = (result: AuditResult, root: string | undefined): ReadonlyArray<Line> =>
+  result.blocked.length === 0
+    ? []
+    : [
+        [],
+        [
+          span(
+            `The firewall in front of Jev's API blocked ${counted(result.blocked.length, "file", "files")}, so ${result.blocked.length === 1 ? "it is" : "they are"} not judged in full. TypeSafe AI can look each block up by its Ray ID:`,
+          ),
+        ],
+        ...result.blocked.map(({ file, ray }) => [
+          span("  "),
+          span(displayPath(file, root), "path"),
+          span(` (Ray ID ${ray})`),
+        ]),
+      ];
+
 export interface RenderOptions {
   /** Color the frame the way `vp lint` does on a terminal, and highlight the code. */
   readonly color?: boolean;
@@ -147,6 +202,7 @@ export const render = (result: AuditResult, options: RenderOptions = {}): Readon
   [
     ...result.findings.flatMap((finding) => [...frame(finding, options.root), []]),
     ...summary(result),
+    ...blockedFiles(result, options.root),
   ].map((line) => serialize(line, options.color === true));
 
 /**