@drkmttr/adhere 0.6.1 → 0.7.1

package/src/workflows/audit.ts

@@ -1,4 +1,4 @@
-import type { Rule, RuleId } from "#config.ts";
+import { type Examples, examplesOf, type Rule, type RuleId } from "#config.ts";
 import type { ScannedFile, WalkUnavailable } from "#models/Audit.ts";
 import { AdhereConfig } from "#services/AdhereConfig.ts";
 import { AuditCache, type Judgment, sha256 } from "#services/AuditCache.ts";
@@ -18,8 +18,7 @@ import { type Crypto, Effect, Record } from "effect";
 export interface Finding {
   readonly rule: RuleId;
   readonly description: string;
-  readonly reference?: string;
-  readonly avoid?: string;
+  readonly examples: Examples;
   readonly file: string;
   readonly line: number;
   readonly snippet: string;
@@ -31,11 +30,13 @@ export interface AuditResult {
   readonly judged: number;
   readonly cached: number;
   readonly skipped: number;
+  /** Files whose checks `--limit` left for a later run, none judged in this one. */
+  readonly waiting: number;
   readonly findings: ReadonlyArray<Finding>;
 }
 
 interface FileResult {
-  readonly status: "judged" | "cached" | "skipped";
+  readonly status: "judged" | "cached" | "skipped" | "waiting";
   readonly findings: ReadonlyArray<Finding>;
 }
 
@@ -70,6 +71,8 @@ export interface FilePlan {
   /** Cached judgments still valid for the file's content and the rule's text. */
   readonly kept: Readonly<Record<RuleId, Judgment>>;
   readonly pending: Readonly<Record<RuleId, PreparedRule>>;
+  /** Pending checks `--limit` leaves for a later run. */
+  readonly deferred: number;
 }
 
 /** A run worked out from the files, the rules, and the cache, before any request. */
@@ -83,6 +86,8 @@ export interface AuditPlan {
   readonly cached: number;
   /** Files too long to judge. */
   readonly skipped: number;
+  /** Checks `--limit` leaves for a later run. */
+  readonly deferred: number;
   /** Requests to Jev that judging the other checks takes. Locating findings adds 1 or more per file. */
   readonly requests: number;
 }
@@ -109,69 +114,110 @@ const inFile =
         : problem,
     );
 
-export const planAudit: Effect.Effect<
+/**
+ * The plan with at most `limit` checks left to judge, taken in path order.
+ * Past the limit a file's other checks wait for a later run; judgments are
+ * cached, so a rerun picks up where this one stopped.
+ */
+const withinLimit = (planned: ReadonlyArray<FilePlan>, limit: number): ReadonlyArray<FilePlan> => {
+  let left = limit;
+  return planned.map((plan) => {
+    const ids = Object.keys(plan.pending);
+    const taken = new Set(ids.slice(0, left));
+    left -= taken.size;
+    return taken.size === ids.length
+      ? plan
+      : {
+          ...plan,
+          pending: Record.filter(plan.pending, (_, id) => taken.has(id)),
+          deferred: ids.length - taken.size,
+        };
+  });
+};
+
+export interface PlanOptions {
+  /** Judge at most this many checks; the rest wait for a later run. */
+  readonly limit?: number;
+}
+
+export const planAudit = (
+  options: PlanOptions = {},
+): Effect.Effect<
   AuditPlan,
   WalkUnavailable,
   AdhereConfig | AuditCache | Crypto.Crypto | SourceWalker
-> = Effect.gen(function* () {
-  const config = yield* AdhereConfig;
-  const cache = yield* AuditCache;
-  const files = yield* (yield* SourceWalker).files;
+> =>
+  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 configuredRules = (file: string) =>
+      config.scopedRules === undefined ? config.rules : applicableRules(file, config.scopedRules);
 
-  const planFile = Effect.fn("audit.plan")(function* (file: ScannedFile) {
-    const rules = configuredRules(file.path);
-    // Too long for Jev's context: skipped and counted, rather than refused mid-run.
-    if (!fits(file.lines, rules)) {
+    const planFile = Effect.fn("audit.plan")(function* (file: ScannedFile) {
+      const rules = configuredRules(file.path);
+      // Too long for Jev's context: skipped and counted, rather than refused mid-run.
+      if (!fits(file.lines, rules)) {
+        return {
+          file,
+          skipped: true,
+          hash: "",
+          prepared: {},
+          kept: {},
+          pending: {},
+          deferred: 0,
+        } satisfies FilePlan;
+      }
+      const prepared: Record<RuleId, PreparedRule> = yield* Effect.forEach(
+        Object.entries(rules),
+        ([id, rule]) =>
+          Effect.map(
+            fingerprintOf(config.model, rule),
+            (fingerprint) =>
+              [id, { rule, fingerprint, threshold: rule.threshold ?? config.threshold }] as const,
+          ),
+      ).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 pending = Record.filter(prepared, (_, id) => kept[id] === undefined);
       return {
         file,
-        skipped: true,
-        hash: "",
-        prepared: {},
-        kept: {},
-        pending: {},
+        skipped: false,
+        hash,
+        prepared,
+        kept,
+        pending,
+        deferred: 0,
       } satisfies FilePlan;
-    }
-    const prepared: Record<RuleId, PreparedRule> = yield* Effect.forEach(
-      Object.entries(rules),
-      ([id, rule]) =>
-        Effect.map(
-          fingerprintOf(config.model, rule),
-          (fingerprint) =>
-            [id, { rule, fingerprint, threshold: rule.threshold ?? config.threshold }] as const,
-        ),
-    ).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 pending = Record.filter(prepared, (_, id) => kept[id] === undefined);
-    return { file, skipped: false, hash, prepared, kept, pending } satisfies FilePlan;
-  });
+    });
 
-  const sorted = [...files].sort((a, b) => a.path.localeCompare(b.path));
-  const planned: ReadonlyArray<FilePlan> = yield* Effect.forEach(sorted, planFile, {
-    concurrency: 8,
+    const sorted = [...files].sort((a, b) => a.path.localeCompare(b.path));
+    const everything: ReadonlyArray<FilePlan> = yield* Effect.forEach(sorted, planFile, {
+      concurrency: 8,
+    });
+    const planned =
+      options.limit === undefined ? everything : withinLimit(everything, options.limit);
+    const judged = planned.filter((plan) => !plan.skipped);
+    const total = (count: (plan: FilePlan) => number) =>
+      judged.reduce((sum, plan) => sum + count(plan), 0);
+    return {
+      files: planned,
+      rules: new Set(judged.flatMap((plan) => Object.keys(plan.prepared))).size,
+      checks: total((plan) => sizeOf(plan.prepared)),
+      cached: total((plan) => sizeOf(plan.kept)),
+      skipped: planned.length - judged.length,
+      deferred: total((plan) => plan.deferred),
+      requests: total((plan) =>
+        isEmpty(plan.pending) ? 0 : judgeRequests(plan.file.lines, rulesOf(plan.pending)),
+      ),
+    };
   });
-  const judged = planned.filter((plan) => !plan.skipped);
-  const total = (count: (plan: FilePlan) => number) =>
-    judged.reduce((sum, plan) => sum + count(plan), 0);
-  return {
-    files: planned,
-    rules: new Set(judged.flatMap((plan) => Object.keys(plan.prepared))).size,
-    checks: total((plan) => sizeOf(plan.prepared)),
-    cached: total((plan) => sizeOf(plan.kept)),
-    skipped: planned.length - judged.length,
-    requests: total((plan) =>
-      isEmpty(plan.pending) ? 0 : judgeRequests(plan.file.lines, rulesOf(plan.pending)),
-    ),
-  };
-});
 
 /**
  * Judges what the plan left pending and locates the findings, a file at a
@@ -192,6 +238,7 @@ export const executeAudit = (
       prepared,
       kept,
       pending,
+      deferred,
     }: FilePlan) {
       const probabilities = isEmpty(pending)
         ? {}
@@ -233,8 +280,7 @@ export const executeAudit = (
                 {
                   rule: id,
                   description: k.rule.description,
-                  reference: k.rule.reference,
-                  avoid: k.rule.avoid,
+                  examples: examplesOf(k.rule),
                   file: file.path,
                   line: judgment.line,
                   snippet: judgment.snippet ?? "",
@@ -245,7 +291,7 @@ export const executeAudit = (
         })
         .sort((a, b) => a.line - b.line);
       return {
-        result: fileResult(cached ? "cached" : "judged", findings),
+        result: fileResult(cached ? (deferred > 0 ? "waiting" : "cached") : "judged", findings),
         requests:
           (isEmpty(pending) ? 0 : judgeRequests(file.lines, rulesOf(pending))) +
           (isEmpty(flagged) ? 0 : locateRequests(file.lines, rulesOf(flagged))),
@@ -276,6 +322,7 @@ export const executeAudit = (
       judged: count("judged"),
       cached: count("cached"),
       skipped: count("skipped"),
+      waiting: count("waiting"),
       findings: results.flatMap((result) => result.findings),
     };
   });
@@ -285,6 +332,6 @@ export const runAudit: Effect.Effect<
   AuditResult,
   WalkUnavailable | JevUnavailable,
   AdhereConfig | AuditCache | Crypto.Crypto | Jev | SourceWalker
-> = Effect.flatMap(planAudit, (plan) => executeAudit(plan));
+> = Effect.flatMap(planAudit(), (plan) => executeAudit(plan));
 
 export { type RenderOptions, render } from "#workflows/format.ts";

package/src/workflows/format.ts

@@ -97,16 +97,20 @@ const excerpt = (finding: Finding, root: string | undefined): ReadonlyArray<Line
   ];
 };
 
-/** The reference as the hint. A rule without one shows its code to avoid instead, labeled so. */
+/**
+ * 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`.
+ */
 const hint = (finding: Finding): ReadonlyArray<Line> => {
+  const { good, bad } = finding.examples;
   const [label, code] =
-    finding.reference === undefined ? ["avoid", finding.avoid ?? ""] : ["hint", finding.reference];
+    good === undefined ? [bad?.word ?? "hint", bad?.code ?? ""] : ["hint", good.code];
   return hanging(span(`  ${label}: `, "label"), codeLines(code));
 };
 
 /**
  * One diagnostic, in the frame `vp lint` prints on a terminal: a red header,
- * the offending line, a pink underline, and the reference code as the hint.
+ * the offending line, a pink underline, and the code to write as the hint.
  */
 const frame = (finding: Finding, root: string | undefined): ReadonlyArray<Line> => [
   header(finding),
@@ -120,6 +124,7 @@ const summary = (result: AuditResult): ReadonlyArray<Line> => {
     `${result.judged} judged`,
     `${result.cached} cached`,
     ...(result.skipped > 0 ? [`${result.skipped} skipped`] : []),
+    ...(result.waiting > 0 ? [`${result.waiting} waiting`] : []),
   ];
   return [
     [span(`Found ${counted(result.findings.length, "error", "errors")}.`)],
@@ -149,18 +154,56 @@ export const render = (result: AuditResult, options: RenderOptions = {}): Readon
  * between them and how many the cache answers, then what judging the rest
  * takes.
  */
-export const describePlan = (plan: AuditPlan): ReadonlyArray<string> => {
+/** What a run was asked to keep to, for the plan to say. */
+export interface RunLimits {
+  readonly filter?: ReadonlyArray<string>;
+  readonly rpm?: number;
+}
+
+/** About how long `requests` take at `rpm`: seconds under a minute, minutes past it. */
+const durationAt = (requests: number, rpm: number): string => {
+  const seconds = Math.ceil((requests / rpm) * 60);
+  return seconds < 60
+    ? counted(seconds, "second", "seconds")
+    : counted(Math.round(seconds / 60), "minute", "minutes");
+};
+
+export const describePlan = (plan: AuditPlan, limits: RunLimits = {}): ReadonlyArray<string> => {
   const cached = plan.cached > 0 ? `, ${plan.cached} cached` : "";
   const skipped =
     plan.skipped > 0 ? `, ${counted(plan.skipped, "file", "files")} too long to judge` : "";
-  const found = `${counted(plan.files.length, "file", "files")} and ${counted(plan.rules, "rule", "rules")}: ${counted(plan.checks, "check", "checks")}${cached}${skipped}.`;
+  const matching = (limits.filter?.length ?? 0) > 0 ? " matching the filter" : "";
+  const found = `${counted(plan.files.length, "file", "files")}${matching} and ${counted(plan.rules, "rule", "rules")}: ${counted(plan.checks, "check", "checks")}${cached}${skipped}.`;
+  const pending = plan.checks - plan.cached;
+  const waiting =
+    plan.deferred > 0
+      ? ` The other ${plan.deferred} ${plan.deferred === 1 ? "waits" : "wait"} for a later run.`
+      : "";
   if (plan.requests === 0) {
-    return [found, plan.checks === 0 ? "Nothing to judge." : "The cache answers every check."];
+    const none =
+      plan.deferred > 0
+        ? plan.deferred === 1
+          ? "The limit leaves the 1 unjudged check for a later run."
+          : `The limit leaves all ${plan.deferred} unjudged checks for a later run.`
+        : plan.checks === 0
+          ? "Nothing to judge."
+          : "The cache answers every check.";
+    return [found, none];
   }
-  const rest = plan.cached > 0 ? `the other ${plan.checks - plan.cached}` : "them";
+  const judging = pending - plan.deferred;
+  const rest =
+    plan.deferred > 0
+      ? `${judging} of ${plan.cached > 0 ? `the other ${pending}` : "them"}`
+      : plan.cached > 0
+        ? `the other ${pending}`
+        : "them";
+  const pace =
+    limits.rpm === undefined
+      ? ""
+      : ` At ${limits.rpm} a minute, they take about ${durationAt(plan.requests, limits.rpm)}.`;
   return [
     found,
-    `Judging ${rest} takes ${counted(plan.requests, "request", "requests")} to Jev, plus 1 or more for each file with a finding.`,
+    `Judging ${rest} takes ${counted(plan.requests, "request", "requests")} to Jev, plus 1 or more for each file with a finding.${pace}${waiting}`,
   ];
 };