@drkmttr/adhere 0.9.5 → 0.11.0

package/src/workflows/audit.ts

@@ -1,5 +1,6 @@
-import { type Examples, examplesOf, type Rule, type RuleId } from "#config.ts";
-import { type Excerpt, excerptOf } from "#excerpt.ts";
+import { isNote, withoutComments } from "#comments.ts";
+import { type Examples, examplesOf, type Level, type Rule, type RuleId } from "#config.ts";
+import { type Excerpt, type Range } from "#excerpt.ts";
 import type { ScannedFile, WalkUnavailable } from "#models/Audit.ts";
 import { AdhereConfig } from "#services/AdhereConfig.ts";
 import { AuditCache, answersOf, type Judgment, sha256, type Tally } from "#services/AuditCache.ts";
@@ -12,7 +13,9 @@ import {
   judgeLoad,
   judgeRequests,
   linterQuestion,
+  type Located,
   locateRequests,
+  matcherQuestions,
   questionRoom,
   tokensOf,
 } from "#services/Jev.ts";
@@ -20,7 +23,8 @@ import { SourceWalker } from "#services/SourceWalker.ts";
 import { clearingStatus, counted, countOf, Status } from "#services/Status.ts";
 import { SAMPLE, tallyKeyOf } from "#mechanical.ts";
 import { priceOf } from "#pricing.ts";
-import { applicableRules } from "#rules.ts";
+import { applicableRules, judgesFile, shownId } from "#rules.ts";
+import { NO_SUPPRESSIONS, suppresses, type Suppressions, suppressionsOf } from "#suppress.ts";
 import { type Crypto, Duration, Effect, Record, Result, Semaphore } from "effect";
 
 export interface Finding {
@@ -30,12 +34,30 @@ export interface Finding {
   readonly description: string;
   readonly examples: Examples;
   readonly file: string;
-  readonly line: number;
-  /** The code around `line` the report shows. */
+  /** The section of the file Jev points at, which a finding is in. */
+  readonly section: Range;
+  /** The lines in the section the code that breaks the rule starts and ends on, when Jev named them. */
+  readonly lines?: Range;
+  /** 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.
+   */
+  readonly insufficiency?: number;
   readonly probability: number;
+  /** An error fails the run; a warning does not, unless `--deny-warnings`. */
+  readonly level: Level;
 }
 
+/** The findings that fail a run: its errors, and its warnings too when `denyWarnings`. */
+export const failing = (
+  findings: ReadonlyArray<Finding>,
+  denyWarnings = false,
+): ReadonlyArray<Finding> =>
+  denyWarnings ? findings : findings.filter((finding) => finding.level === "error");
+
 export interface AuditResult {
   readonly files: number;
   readonly judged: number;
@@ -46,6 +68,8 @@ export interface AuditResult {
   /** 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>;
+  /** Findings an `adhere-ignore` comment covers, left out of `findings`. */
+  readonly suppressed: number;
 }
 
 /** A file whose request the firewall refused, and Cloudflare's Ray ID for the refusal. */
@@ -58,6 +82,8 @@ interface FileResult {
   readonly status: "judged" | "cached" | "skipped" | "waiting" | "blocked";
   readonly findings: ReadonlyArray<Finding>;
   readonly blocked?: Blocked;
+  /** Findings an `adhere-ignore` comment covers, left out of `findings`. */
+  readonly suppressed?: number;
 }
 
 interface PreparedRule {
@@ -75,17 +101,58 @@ const fileResult = (
 
 const isEmpty = Record.isEmptyReadonlyRecord;
 
+/** How Jev reads a file, which a judgment depends on: a new layout re-judges every rule. */
+const LAYOUT = "sections";
+
 /**
- * What a judgment depends on besides the file: the model, and the question
- * asked for the rule, which carries the rule. An edited rule re-judges
- * itself, and a question asked differently re-judges every rule.
+ * What a judgment depends on besides the file: the model, how the file is
+ * 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.
  */
-const fingerprintOf = (model: string, rule: Rule) =>
-  sha256(`${model}\u0000${JSON.stringify(judgeQuestion(rule))}`);
+const fingerprintOf = (model: string, rule: Rule) => {
+  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}`);
+};
+
+/** A section's lines as written, without the blank lines at either end. */
+const excerptOf = (lines: ReadonlyArray<string>, { first, last }: Range): Excerpt => {
+  let start = first;
+  let end = last;
+  while (start < end && (lines[start - 1] ?? "").trim() === "") start += 1;
+  while (end > start && (lines[end - 1] ?? "").trim() === "") end -= 1;
+  return { start, lines: lines.slice(start - 1, end) };
+};
+
+/** A matcher's score counts as a yes above this. */
+const MATCHER_THRESHOLD = 0.5;
+
+/** Whether a judgment's matchers let it stand: a yes to every `appliesTo`, and to no `excludeIf`. */
+const inScope = (judgment: Judgment): boolean =>
+  (judgment.appliesTo ?? []).every((score) => score > MATCHER_THRESHOLD) &&
+  !(judgment.excludeIf ?? []).some((score) => score > MATCHER_THRESHOLD);
+
+/** The matchers that dropped a judgment, with their scores, as the debug log names them. */
+const scopeMisses = (rule: Rule, judgment: Judgment): string =>
+  [
+    ...(rule.appliesTo ?? []).flatMap((matcher, index) => {
+      const score = judgment.appliesTo?.[index] ?? 0;
+      return score > MATCHER_THRESHOLD ? [] : [`appliesTo "${matcher}" (${score.toFixed(2)})`];
+    }),
+    ...(rule.excludeIf ?? []).flatMap((matcher, index) => {
+      const score = judgment.excludeIf?.[index] ?? 0;
+      return score > MATCHER_THRESHOLD ? [`excludeIf "${matcher}" (${score.toFixed(2)})`] : [];
+    }),
+  ].join(", ");
 
 /** One file before anything is sent: its rules, and which of them the cache answers. */
 export interface FilePlan {
+  /** The file as Jev reads it: its comments taken out, unless the config keeps them. */
   readonly file: ScannedFile;
+  /** The file's lines as written, which the report's excerpts show. */
+  readonly original: ReadonlyArray<string>;
   /** Too long for Jev: counted, not judged. */
   readonly skipped: boolean;
   readonly hash: string;
@@ -97,11 +164,18 @@ export interface FilePlan {
   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>>;
+  /** What the file's `adhere-ignore` comments suppress. */
+  readonly suppressions: Suppressions;
 }
 
 /** A run worked out from the files, the rules, and the cache, before any request. */
 export interface AuditPlan {
   readonly files: ReadonlyArray<FilePlan>;
+  /**
+   * The content hashes of files read that no rule in the run judges, such as
+   * tests when no rule says `tests`: a prune keeps what other runs know of them.
+   */
+  readonly unjudged: ReadonlyArray<string>;
   /** Rules that apply to at least one file that is judged. */
   readonly rules: number;
   /** Every pair of a judged file and a rule that applies to it. */
@@ -118,6 +192,8 @@ export interface AuditPlan {
   readonly tokens: number;
   /** The model's price per million input tokens, in dollars, when adhere knows it. */
   readonly price?: number;
+  /** Below this, a finding's sufficiency adds a warning to it. */
+  readonly sufficiencyThreshold: number;
 }
 
 /** A file finished, for a progress counter: the requests it took and the findings it has. */
@@ -165,7 +241,7 @@ const withinLimit = (planned: ReadonlyArray<FilePlan>, limit: number): ReadonlyA
 
 export interface PlanOptions {
   /** Judge at most this many checks; the rest wait for a later run. */
-  readonly limit?: number;
+  readonly limit?: number | undefined;
 }
 
 export const planAudit = (
@@ -178,13 +254,37 @@ export const planAudit = (
   Effect.gen(function* () {
     const config = yield* AdhereConfig;
     const cache = yield* AuditCache;
-    const files = yield* (yield* SourceWalker).files;
-
-    const configuredRules = (file: string) =>
-      config.scopedRules === undefined ? config.rules : applicableRules(file, config.scopedRules);
+    const walked = yield* (yield* SourceWalker).files;
+    // Each file as Jev reads it, each line keeping its number: its adhere-ignore comments blanked,
+    // and every other comment too but the @adhere notes, unless the config keeps comments. A
+    // comment changes nothing a file does, so it should not change the report.
+    const suppressed = new Map<string, Suppressions>();
+    const originals = new Map<string, ReadonlyArray<string>>();
+    const files = walked.map((file) => {
+      const { lines: directed, suppressions } = suppressionsOf(file.lines);
+      if (suppressions !== NO_SUPPRESSIONS) suppressed.set(file.path, suppressions);
+      const lines = config.includeComments === true ? directed : withoutComments(directed, isNote);
+      if (lines === file.lines) return file;
+      originals.set(file.path, file.lines);
+      return { ...file, lines };
+    });
+    const suppressionsIn = (file: ScannedFile) => suppressed.get(file.path) ?? NO_SUPPRESSIONS;
+    const originalOf = (file: ScannedFile) => originals.get(file.path) ?? file.lines;
+
+    // The rules that judge a file: those scoped to it, of which only the rules that say `tests`
+    // judge a test, and none that an adhere-ignore-file comment names.
+    const configuredRules = (file: ScannedFile) =>
+      Record.filter(
+        config.scopedRules === undefined
+          ? config.rules
+          : applicableRules(file.path, config.scopedRules),
+        (rule, id) =>
+          judgesFile(rule, file.test === true) &&
+          !suppressionsIn(file).file.has(shownId({ id, preset: presetOfRule.get(rule) })),
+      );
 
     const planFile = Effect.fn("audit.plan")(function* (file: ScannedFile) {
-      const rules = configuredRules(file.path);
+      const rules = configuredRules(file);
       // Hashed even when skipped, so a prune keeps what other runs know of its content.
       const hash = yield* sha256(file.lines.join("\n"));
       // Too long for Jev's context: skipped and counted, rather than refused mid-run.
@@ -199,6 +299,8 @@ export const planAudit = (
           pending: {},
           deferred: 0,
           sampled: {},
+          suppressions: suppressionsIn(file),
+          original: originalOf(file),
         } satisfies FilePlan;
       }
       const prepared: Record<RuleId, PreparedRule> = yield* Effect.forEach(
@@ -235,6 +337,8 @@ export const planAudit = (
         pending,
         deferred: 0,
         sampled: {},
+        suppressions: suppressionsIn(file),
+        original: originalOf(file),
       } satisfies FilePlan;
     });
 
@@ -305,7 +409,16 @@ export const planAudit = (
       });
     });
 
-    const sorted = [...files].sort((a, b) => a.path.localeCompare(b.path));
+    // A file no rule judges, such as a test when no rule says `tests`, is not part of the run,
+    // but its content is: another run's rules may judge it.
+    const sorted = files
+      .filter((file) => !isEmpty(configuredRules(file)))
+      .sort((a, b) => a.path.localeCompare(b.path));
+    const unjudged = yield* Effect.forEach(
+      files.filter((file) => isEmpty(configuredRules(file))),
+      (file) => sha256(file.lines.join("\n")),
+      { concurrency: 8 },
+    );
     const status = yield* Status;
     let done = 0;
     const everything: ReadonlyArray<FilePlan> = yield* clearingStatus(
@@ -337,6 +450,7 @@ export const planAudit = (
       judged.reduce((sum, plan) => sum + count(plan), 0);
     return {
       files: planned,
+      unjudged,
       rules: new Set(judged.flatMap((plan) => Object.keys(plan.prepared))).size,
       checks: total((plan) => sizeOf(plan.prepared)),
       cached: total((plan) => sizeOf(plan.kept)),
@@ -345,6 +459,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 }),
+      sufficiencyThreshold: config.sufficiencyThreshold,
     };
   });
 
@@ -386,6 +501,7 @@ export const executeAudit = (
     /** Judges and locates one file the plan left pending, with the requests that took. */
     const judgeFile = Effect.fn("audit.judgeFile")(function* ({
       file,
+      original,
       hash,
       prepared,
       kept,
@@ -393,14 +509,25 @@ export const executeAudit = (
       deferred,
       sampled,
     }: FilePlan) {
-      const { probabilities, linter }: Judged = isEmpty(pending)
+      const { probabilities, linter, matchers }: 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];
-        if (k !== undefined) judged[id] = { fingerprint: k.fingerprint, probability };
+        if (k !== undefined) {
+          judged[id] = { fingerprint: k.fingerprint, probability, ...matchers?.[id] };
+        }
+      }
+      // Above its threshold, but its matchers put the code out of the rule's scope.
+      for (const [id, judgment] of Object.entries(judged)) {
+        const k = prepared[id];
+        if (k !== undefined && judgment.probability > k.threshold && !inScope(judgment)) {
+          yield* Effect.logDebug(
+            `${file.path}: ${id} (${judgment.probability.toFixed(2)}) dropped by ${scopeMisses(k.rule, judgment)}`,
+          );
+        }
       }
 
       const flagged = Record.filter(prepared, (k, id) => {
@@ -408,28 +535,30 @@ export const executeAudit = (
         return (
           judgment !== undefined &&
           judgment.probability > k.threshold &&
-          judgment.line === undefined
+          inScope(judgment) &&
+          (judgment.section === undefined || judgment.sufficiency === undefined)
         );
       });
-      // A blocked line question still leaves the judgments worth caching: a rerun
-      // asks only for the lines again, not for every rule.
+      // A blocked locate question still leaves the judgments worth caching: a rerun
+      // asks only for the sections again, not for every rule.
       const {
-        lines,
+        places,
         blocked,
-      }: { readonly lines: Readonly<Record<RuleId, number>>; readonly blocked?: Blocked } = isEmpty(
-        flagged,
-      )
-        ? { lines: {}, blocked: undefined }
+      }: {
+        readonly places: Readonly<Record<RuleId, Located>>;
+        readonly blocked: Blocked | undefined;
+      } = isEmpty(flagged)
+        ? { places: {}, blocked: undefined }
         : yield* jev.locate(file.lines, rulesOf(flagged)).pipe(
-            Effect.map((lines) => ({ lines, blocked: undefined })),
+            Effect.map((places) => ({ places, blocked: undefined })),
             Effect.catchTag("JevBlocked", ({ ray }) =>
-              Effect.succeed({ lines: {}, blocked: { file: file.path, ray } }),
+              Effect.succeed({ places: {}, blocked: { file: file.path, ray } }),
             ),
             inFile(file),
           );
       const located = Record.map(judged, (judgment, id) => {
-        const line = lines[id];
-        return line === undefined ? judgment : { ...judgment, line };
+        const place = places[id];
+        return place === undefined ? judgment : { ...judgment, ...place };
       });
 
       const cached = isEmpty(pending) && isEmpty(flagged);
@@ -439,8 +568,9 @@ export const executeAudit = (
         .flatMap(([id, judgment]): ReadonlyArray<Finding> => {
           const k = prepared[id];
           return k !== undefined &&
-            judgment.line !== undefined &&
-            judgment.probability > k.threshold
+            judgment.section !== undefined &&
+            judgment.probability > k.threshold &&
+            inScope(judgment)
             ? [
                 {
                   rule: id,
@@ -448,14 +578,20 @@ export const executeAudit = (
                   description: k.rule.description,
                   examples: examplesOf(k.rule),
                   file: file.path,
-                  line: judgment.line,
-                  excerpt: excerptOf(file.lines, judgment.line),
+                  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 }
+                    : {}),
                   probability: judgment.probability,
+                  level: k.rule.level ?? "error",
                 },
               ]
             : [];
         })
-        .sort((a, b) => a.line - b.line);
+        .sort((a, b) => (a.lines ?? a.section).first - (b.lines ?? b.section).first);
       return {
         result:
           blocked === undefined
@@ -511,8 +647,22 @@ export const executeAudit = (
         ),
         Effect.annotateLogs("file", plan.file.path),
       );
-      yield* progress({ requests, findings: result.findings.length });
-      return result;
+      // A finding an adhere-ignore comment covers is left out of the report, and counted.
+      const shown = result.findings.filter(
+        (finding) =>
+          !suppresses(
+            plan.suppressions,
+            shownId({ id: finding.rule, preset: finding.preset }),
+            finding.lines ?? finding.section,
+          ),
+      );
+      if (shown.length < result.findings.length) {
+        yield* Effect.logDebug(
+          `${result.findings.length - shown.length} suppressed by adhere-ignore`,
+        ).pipe(Effect.annotateLogs("file", plan.file.path));
+      }
+      yield* progress({ requests, findings: shown.length });
+      return { ...result, findings: shown, suppressed: result.findings.length - shown.length };
     });
 
     const results = yield* Effect.forEach(plan.files, auditFile, { concurrency: 8 });
@@ -526,13 +676,15 @@ export const executeAudit = (
       waiting: count("waiting"),
       blocked: results.flatMap((result) => (result.blocked === undefined ? [] : [result.blocked])),
       findings: results.flatMap((result) => result.findings),
+      suppressed: results.reduce((sum, result) => sum + (result.suppressed ?? 0), 0),
     };
   });
 
 /**
  * Deletes from the cache the answers about content no file has anymore.
  * Answers to rules the run left out stay, since a run with other presets or
- * rules asks them. Only after a run that read every file; a run narrowed by
+ * rules asks them, and so do answers about files the run read but judged
+ * against no rule. Only after a run that read every file; a run narrowed by
  * `--filter` cannot tell what content the files it left out have.
  */
 export const pruneCache = Effect.fn("audit.prune")(function* (plan: AuditPlan) {
@@ -544,7 +696,7 @@ export const pruneCache = Effect.fn("audit.prune")(function* (plan: AuditPlan) {
   );
   const deleted = yield* cache.prune({
     // A file too long to judge counts: a run with shorter questions judges it.
-    hashes: new Set(plan.files.map((file) => file.hash)),
+    hashes: new Set([...plan.files.map((file) => file.hash), ...plan.unjudged]),
     tallies: new Set(tallies),
   });
   yield* Effect.logDebug(`cache pruned: ${deleted} ${deleted === 1 ? "file" : "files"} deleted`);

package/src/workflows/format.ts

@@ -9,6 +9,7 @@ import type { AuditPlan, AuditResult, FileDone, Finding } from "#workflows/audit
  */
 type Role =
   | "error"
+  | "warning"
   | "probability"
   | "description"
   | "path"
@@ -27,15 +28,16 @@ type Line = ReadonlyArray<Span>;
 /**
  * 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.
+ * 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.
  */
 const THEME: Readonly<Record<Role, string>> = {
   error: "38;2;164;20;71;1",
+  warning: "38;2;214;154;0;1",
   probability: "38;5;156",
   description: "38;2;230;230;255",
   path: "38;2;5;125;160;1",
@@ -90,9 +92,9 @@ const counted = (count: number, one: string, many: string): string =>
 
 const header = (finding: Finding): Line => [
   span("  "),
-  span("×", "error"),
+  span(finding.level === "warning" ? "⚠" : "×", finding.level),
   span(" "),
-  span(shownId({ id: finding.rule, preset: finding.preset }), "error"),
+  span(shownId({ id: finding.rule, preset: finding.preset }), finding.level),
   span(" ("),
   span(finding.probability.toFixed(2), "probability"),
   span("): "),
@@ -100,36 +102,74 @@ const header = (finding: Finding): Line => [
 ];
 
 /**
- * The path, then the finding's excerpt with each line numbered in the gutter,
- * and an underline under the offending line's code.
+ * The path at the lines Jev points at, or the section's first line when it
+ * named none, then the section with each line numbered in the gutter. One
+ * line Jev points at is underlined under its code; several are marked by a
+ * bar in a column of their own beside the code, as `vp lint` marks a span,
+ * so each line of code keeps one line of the report.
  */
 const excerpt = (finding: Finding, root: string | undefined): ReadonlyArray<Line> => {
   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}]`;
+  const indentOf = (line: string) => line.slice(0, line.length - line.trimStart().length);
+  const pointed = finding.lines;
+  const at = pointed?.first ?? start;
+  const location = `:${at}:${indentOf(lines[at - start] ?? "").length + 1}]`;
+  const spanning = pointed !== undefined && pointed.last > pointed.first;
+  const inside = (line: number) =>
+    pointed !== undefined && pointed.first <= line && line <= pointed.last;
   return [
     [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 marker = spanning ? [inside(start + index) ? span("┃ ", "underline") : span("  ")] : [];
       const numbered = [
         span(" ".repeat(width - number.length + 1)),
         span(number, "lineNumber"),
         span(" │ "),
+        ...marker,
         ...code,
       ];
-      return start + index === finding.line
-        ? [numbered, [gutter, span("· "), span(indent), span(underline, "underline")]]
+      const text = lines[index] ?? "";
+      // The line's own indentation, tabs and all, lines the underline up under its code.
+      return !spanning && inside(start + index) && text.trim() !== ""
+        ? [
+            numbered,
+            [
+              gutter,
+              span("· "),
+              span(indentOf(text)),
+              span("─".repeat(text.trim().length), "underline"),
+            ],
+          ]
         : [numbered];
     }),
     [gutter, span("╰────")],
   ];
 };
 
+/**
+ * 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.
+ */
+const insufficient = (finding: Finding): ReadonlyArray<Line> =>
+  finding.insufficiency === undefined
+    ? []
+    : [
+        [
+          span("  warning: ", "warning"),
+          span(
+            `this file may not show enough to check this rule (Jev: ${finding.insufficiency.toFixed(2)} that it does not)`,
+          ),
+        ],
+        ...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] ?? [],
+        ]),
+      ];
+
 /**
  * The code to write as the hint. A rule with only code not to write shows
  * that instead, labeled with its word: `never`, or `should not`.
@@ -143,15 +183,24 @@ 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 code around the offending line, a pink underline under
- * it, and the code to write as the hint.
+ * 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.
  */
 const frame = (finding: Finding, root: string | undefined): ReadonlyArray<Line> => [
   header(finding),
   ...excerpt(finding, root),
+  ...insufficient(finding),
   ...hint(finding),
 ];
 
+/** 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;
+  const errors = counted(findings.length - warnings, "error", "errors");
+  return warnings === 0 ? errors : `${errors} and ${counted(warnings, "warning", "warnings")}`;
+};
+
 const summary = (result: AuditResult): ReadonlyArray<Line> => {
   const counts = [
     counted(result.files, "file", "files"),
@@ -160,11 +209,9 @@ const summary = (result: AuditResult): ReadonlyArray<Line> => {
     ...(result.skipped > 0 ? [`${result.skipped} skipped`] : []),
     ...(result.waiting > 0 ? [`${result.waiting} waiting`] : []),
     ...(result.blocked.length > 0 ? [`${result.blocked.length} blocked`] : []),
+    ...(result.suppressed > 0 ? [`${result.suppressed} suppressed`] : []),
   ];
-  return [
-    [span(`Found ${counted(result.findings.length, "error", "errors")}.`)],
-    [span(`${counts.join(", ")}.`)],
-  ];
+  return [[span(`Found ${found(result.findings)}.`)], [span(`${counts.join(", ")}.`)]];
 };
 
 /**
@@ -214,7 +261,7 @@ export const render = (result: AuditResult, options: RenderOptions = {}): Readon
 /** What a run was asked to keep to, for the plan to say. */
 export interface RunLimits {
   readonly filter?: ReadonlyArray<string>;
-  readonly rpm?: number;
+  readonly rpm?: number | undefined;
 }
 
 /** About how long `requests` take at `rpm`: seconds under a minute, minutes past it. */

package/presets/alchemy/data/parameterized-sql.md

@@ -1,13 +0,0 @@
----
-description: SQL must pass values as parameters, through tagged-template interpolation, sql.in, sql.insert, or prepare().bind(), never by string concatenation or a template string handed to an unsafe or raw API.
----
-
-```ts must
-const user = yield* sql`SELECT * FROM users WHERE email = ${email}`;
-const row = yield* Effect.promise(() => d1.prepare("SELECT * FROM users WHERE id = ?").bind(id).first());
-```
-
-```ts never
-const user = yield* sql.unsafe(`SELECT * FROM users WHERE email = '${email}'`);
-const row = yield* Effect.promise(() => d1.prepare("SELECT * FROM users WHERE id = " + id).first());
-```

package/presets/alchemy/secrets/never-logged-returned-or-output.md

@@ -1,15 +0,0 @@
----
-description: A secret, credential, connection string, token, signed URL, or private key must never be logged, returned in an HTTP response, or returned as a stack output; code must expose only names, presence, or non-secret metadata.
----
-
-```ts must
-if (url.pathname === "/secret") {
-  return yield* HttpServerResponse.json({ name: "API_TOKEN", set: Redacted.value(token).length > 0 });
-}
-return { serial: certificate.serial, expires: certificate.notAfter }; // stack output
-```
-
-```ts never
-yield* Effect.log(`token=${Redacted.value(token)}`);
-return { databaseUrl: connection.databaseUrl, tlsKey: certificate.privateKey }; // stack output
-```

package/presets/effect/basics/external-calls-are-resilient.md

@@ -1,17 +0,0 @@
----
-description: A call over the network, such as an HTTP request, a database query, or a third-party API, should carry a timeout and a retry schedule, and should not go out bare. A call through a client that already applies both, such as an HttpClient built with a timeout and retryTransient or an SDK with its own retries, has them. Calls through the platform FileSystem and Path services are local and are not in scope.
----
-
-```ts should
-const retryPolicy = Schedule.exponential("100 millis").pipe(Schedule.both(Schedule.recurs(3)));
-
-const resilientCall = HttpClient.get("https://api.example.com/users").pipe(
-  Effect.timeout("2 seconds"),
-  Effect.retry(retryPolicy),
-  Effect.timeout("10 seconds"),
-);
-```
-
-```ts should not
-const response = yield* HttpClient.get(`https://api.example.com/users/${id}`);
-```