@drkmttr/adhere 0.7.0 → 0.7.1

package/README.md

@@ -75,6 +75,9 @@ adhere lint                    # audit the working directory
 adhere lint --preset effect    # add a built-in rule set; the config becomes optional
 adhere lint --threshold 0.9    # replace the config's threshold; per-rule thresholds still apply
 adhere lint --yes              # send the requests without asking first
+adhere lint --limit 500        # judge at most 500 checks; the rest wait for the next run
+adhere lint --rpm 30           # send at most 30 requests a minute
+adhere lint --filter 'src/**'  # read only the files a glob matches
 adhere validate                # load the config and rules, ask Jev whether any contradict
 adhere init [--force]          # scaffold .adhere/config.ts and two example rules
 adhere login                   # save a TypeSafe AI API key for later runs
@@ -104,6 +107,21 @@ the report goes to stdout. A request Jev refuses stops the run with the file,
 the HTTP status, and Jev's reason. Files finished before it are cached, so
 running again continues from there.
 
+### Limiting a run
+
+Three flags bound what a run does. `--limit <checks>` judges at most that many
+checks, taken in path order; the rest wait, and since judgments are cached, the
+next run with the same limit picks up where this one stopped. `--limit 0` shows
+the plan and judges nothing. `--rpm <requests>` sends at most that many requests
+to Jev a minute, evenly spaced, retries included, and the plan says about how
+long they take. `--filter <glob>` reads only the files whose path from the
+working directory matches, such as `src/**` or `**/*.service.ts`; repeat it for
+more, and start a pattern with `!` to leave out what it matches. Together:
+
+```sh
+adhere lint --filter 'packages/api/**' --filter '!**/generated/**' --limit 200 --rpm 30
+```
+
 ### What gets read
 
 `adhere lint` reads the `.ts` files under the working directory, except `.d.ts`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.7.0",
+  "version": "0.7.1",
   "private": false,
   "description": "Lints a repository against the rules in .adhere/, judged by Jev.",
   "repository": {
@@ -67,10 +67,10 @@
     }
   },
   "optionalDependencies": {
-    "@drkmttr/adhere-darwin-arm64": "0.7.0",
-    "@drkmttr/adhere-darwin-x64": "0.7.0",
-    "@drkmttr/adhere-linux-arm64": "0.7.0",
-    "@drkmttr/adhere-linux-x64": "0.7.0",
-    "@drkmttr/adhere-win32-x64": "0.7.0"
+    "@drkmttr/adhere-darwin-arm64": "0.7.1",
+    "@drkmttr/adhere-darwin-x64": "0.7.1",
+    "@drkmttr/adhere-linux-arm64": "0.7.1",
+    "@drkmttr/adhere-linux-x64": "0.7.1",
+    "@drkmttr/adhere-win32-x64": "0.7.1"
   }
 }

package/src/cli.ts

@@ -68,6 +68,33 @@ const threshold = Flag.float("threshold").pipe(
   ),
 );
 
+const limit = Flag.integer("limit").pipe(
+  Flag.filter(
+    (checks) => checks >= 0,
+    (checks) => `--limit is a number of checks, 0 or more, not ${checks}.`,
+  ),
+  Flag.optional,
+  Flag.withDescription(
+    "Judge at most this many checks. The rest wait for a later run, which picks up where this one stopped, since judgments are cached. --limit 0 shows the plan and judges nothing.",
+  ),
+);
+
+const rpm = Flag.integer("rpm").pipe(
+  Flag.filter(
+    (requests) => requests > 0,
+    (requests) => `--rpm is a number of requests a minute, more than 0, not ${requests}.`,
+  ),
+  Flag.optional,
+  Flag.withDescription("Send at most this many requests to Jev a minute, evenly spaced."),
+);
+
+const filter = Flag.string("filter").pipe(
+  Flag.atLeast(0),
+  Flag.withDescription(
+    "Read only files whose path from the working directory matches this glob, such as 'src/**' or '**/*.service.ts'. Repeat it for more; a pattern starting with ! leaves out what it matches.",
+  ),
+);
+
 const yes = Flag.boolean("yes").pipe(
   Flag.withAlias("y"),
   Flag.withDefault(false),
@@ -114,53 +141,61 @@ const force = Flag.boolean("force").pipe(
 const chosenPresets = (flag: Option.Option<PresetName>): ReadonlyArray<PresetName> =>
   Option.isSome(flag) ? [flag.value] : [];
 
-export const auditLayer = (overrides: Overrides) =>
+export const auditLayer = (overrides: Overrides, filter: ReadonlyArray<string> = []) =>
   Layer.mergeAll(
-    SourceWalkerLive,
+    SourceWalkerLive(filter),
     AuditCacheLive,
     JevLive.pipe(Layer.provide([FetchHttpClient.layer, CredentialsLive])),
   ).pipe(Layer.provideMerge(AdhereConfigLive(overrides)));
 
 /** `adhere lint`: the audit. */
-export const lintCommand = Command.make("lint", { preset, threshold, yes }, (input) =>
-  Effect.gen(function* () {
-    const stdio = yield* Stdio.Stdio;
-    const plan = yield* planAudit;
-    yield* toStderr(`${describePlan(plan).join("\n")}\n`);
-    // A prompt draws on stdout, so it needs a terminal at both ends: none when
-    // the report is redirected, or in CI.
-    const interactive = (yield* stdio.stdinIsTerminal) && (yield* stdio.stdoutIsTerminal);
-    if (plan.requests > 0 && interactive && !input.yes) {
-      const send = yield* Prompt.run(
-        Prompt.confirm({ message: sendQuestion(plan), initial: true }),
+export const lintCommand = Command.make(
+  "lint",
+  { preset, threshold, yes, limit, rpm, filter },
+  (input) =>
+    Effect.gen(function* () {
+      const stdio = yield* Stdio.Stdio;
+      const plan = yield* planAudit({ limit: Option.getOrUndefined(input.limit) });
+      const limits = { filter: input.filter, rpm: Option.getOrUndefined(input.rpm) };
+      yield* toStderr(`${describePlan(plan, limits).join("\n")}\n`);
+      // A prompt draws on stdout, so it needs a terminal at both ends: none when
+      // the report is redirected, or in CI.
+      const interactive = (yield* stdio.stdinIsTerminal) && (yield* stdio.stdoutIsTerminal);
+      if (plan.requests > 0 && interactive && !input.yes) {
+        const send = yield* Prompt.run(
+          Prompt.confirm({ message: sendQuestion(plan), initial: true }),
+        );
+        if (!send) {
+          yield* toStderr("Nothing sent.\n");
+          return yield* Cancelled.make({});
+        }
+      }
+      const counter = counterFor(plan);
+      yield* counter.start;
+      const result = yield* executeAudit(plan, counter.update).pipe(
+        Effect.onExit((exit) => counter.finish(Exit.isFailure(exit))),
       );
-      if (!send) {
-        yield* toStderr("Nothing sent.\n");
-        return yield* Cancelled.make({});
+      const color = yield* stdio.stdoutIsTerminal;
+      const path = yield* Path.Path;
+      // One write: separate Console.log calls have interleaved out of order here.
+      yield* Console.log(render(result, { color, root: path.resolve() }).join("\n"));
+      if (result.findings.length > 0) {
+        yield* FindingsReported.make({ count: result.findings.length });
       }
-    }
-    const counter = counterFor(plan);
-    yield* counter.start;
-    const result = yield* executeAudit(plan, counter.update).pipe(
-      Effect.onExit((exit) => counter.finish(Exit.isFailure(exit))),
-    );
-    const color = yield* stdio.stdoutIsTerminal;
-    const path = yield* Path.Path;
-    // One write: separate Console.log calls have interleaved out of order here.
-    yield* Console.log(render(result, { color, root: path.resolve() }).join("\n"));
-    if (result.findings.length > 0) {
-      yield* FindingsReported.make({ count: result.findings.length });
-    }
-  }),
+    }),
 ).pipe(
   Command.withDescription(
     "Audit the working directory against the rules in .adhere/ or a preset, judged by Jev.",
   ),
   Command.provide((input) =>
-    auditLayer({
-      presets: chosenPresets(input.preset),
-      threshold: Option.getOrUndefined(input.threshold),
-    }),
+    auditLayer(
+      {
+        presets: chosenPresets(input.preset),
+        threshold: Option.getOrUndefined(input.threshold),
+        rpm: Option.getOrUndefined(input.rpm),
+      },
+      input.filter,
+    ),
   ),
 );
 

package/src/config.ts

@@ -148,6 +148,8 @@ export interface ResolvedConfig {
   readonly threshold: number;
   readonly rules: Rules;
   readonly scopedRules?: RuleSet;
+  /** Requests to Jev a minute, at most. Unset, requests go out as fast as they are made. */
+  readonly rpm?: number;
 }
 
 /** Command-line values that apply on top of the config file. */
@@ -155,6 +157,8 @@ export interface Overrides {
   readonly presets?: ReadonlyArray<PresetName>;
   /** Replaces the config's global threshold. Per-rule thresholds still win. */
   readonly threshold?: number;
+  /** Throttles requests to Jev to at most this many a minute. */
+  readonly rpm?: number;
 }
 
 /** The presets a run applies, command-line ones first. */
@@ -183,6 +187,7 @@ export const resolveConfig = (
     model: config.model ?? last("model") ?? DEFAULT_MODEL,
     threshold: overrides.threshold ?? config.threshold ?? last("threshold") ?? DEFAULT_THRESHOLD,
     rules: Object.assign({}, ...applied.map((preset) => preset.rules), config.rules),
+    ...(overrides.rpm === undefined ? {} : { rpm: overrides.rpm }),
   };
 };
 

package/src/services/Jev.http.ts

@@ -19,9 +19,10 @@ import {
   requestsOf,
   type Rules,
 } from "#services/Jev.ts";
-import { type Cause, Effect, Layer, Option, Record, Schedule, Schema } from "effect";
+import { type Cause, Duration, Effect, Layer, Option, Record, 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";
 
 const SYSTEM_ONE = "https://api.typesafe.ai/v1/systemone";
 
@@ -53,7 +54,9 @@ const isOverflow = (body: string): boolean =>
  * the run with its status and what Jev said, since the status alone does not
  * say why, and a request that got no answer refuses with the cause.
  */
-const failed = (problem: HttpClientError.HttpClientError | Cause.TimeoutError) => {
+const failed = (
+  problem: HttpClientError.HttpClientError | RateLimiter.RateLimiterError | Cause.TimeoutError,
+) => {
   if (!HttpClientError.isHttpClientError(problem) || problem.reason._tag !== "StatusCodeError") {
     return Effect.fail(refused(`System One request failed: ${problem.message}`));
   }
@@ -79,8 +82,27 @@ export const JevLive = Layer.effect(Jev)(
   Effect.gen(function* () {
     const config = yield* AdhereConfig;
     const credentials = yield* Credentials;
-    const client = (yield* HttpClient.HttpClient).pipe(
-      HttpClient.filterStatusOk,
+    const http = (yield* HttpClient.HttpClient).pipe(HttpClient.filterStatusOk);
+    // `--rpm`: one request per 60/rpm seconds, evenly spaced rather than in a
+    // burst each minute. Before the retries, so a retry waits its turn too.
+    type Failure = HttpClientError.HttpClientError | RateLimiter.RateLimiterError;
+    const paced: HttpClient.HttpClient.With<Failure> =
+      config.rpm === undefined
+        ? // The same client, typed to fail the ways the throttled one can.
+          HttpClient.transformResponse(
+            http,
+            (response): Effect.Effect<HttpClientResponse.HttpClientResponse, Failure> => response,
+          )
+        : http.pipe(
+            HttpClient.withRateLimiter({
+              limiter: yield* RateLimiter.RateLimiter,
+              key: "jev",
+              algorithm: "token-bucket",
+              limit: 1,
+              window: Duration.millis(60_000 / config.rpm),
+            }),
+          );
+    const client = paced.pipe(
       HttpClient.transformResponse(Effect.timeout("30 seconds")),
       HttpClient.retryTransient({
         schedule: Schedule.exponential("500 millis"),
@@ -172,4 +194,4 @@ export const JevLive = Layer.effect(Jev)(
 
     return Jev.of({ judge, locate, conflicts, contradicts });
   }),
-);
+).pipe(Layer.provide(RateLimiter.layer.pipe(Layer.provide(RateLimiter.layerStoreMemory))));

package/src/services/SourceWalker.ts

@@ -1,3 +1,4 @@
+import { matchesGlob } from "node:path";
 import { Context, Effect, FileSystem, Layer, Path } from "effect";
 import { ADHERE_DIRECTORY, SKIPPED_DIRECTORIES } from "#config.ts";
 import type { ScannedFile } from "#models/Audit.ts";
@@ -31,6 +32,22 @@ export const isInSkippedTree = (relative: string): boolean =>
     .split(/[\\/]/)
     .some((segment) => segment === ADHERE_DIRECTORY || SKIPPED_DIRECTORIES.has(segment));
 
+/**
+ * Whether a path, relative to the working directory, passes a run's filter.
+ * A pattern is a glob; one starting with `!` leaves out what it matches. A
+ * path passes when no `!` pattern matches it and either another pattern does
+ * or there are none.
+ */
+export const passesFilter = (relative: string, patterns: ReadonlyArray<string>): boolean => {
+  const path = relative.replaceAll("\\", "/");
+  const matches = (pattern: string) => matchesGlob(path, pattern);
+  const include = patterns.filter((pattern) => !pattern.startsWith("!"));
+  const exclude = patterns
+    .filter((pattern) => pattern.startsWith("!"))
+    .map((pattern) => pattern.slice(1));
+  return (include.length === 0 || include.some(matches)) && !exclude.some(matches);
+};
+
 const isInside = (file: string, root: string): boolean =>
   file === root || file.startsWith(`${root}/`);
 
@@ -49,18 +66,21 @@ const refused = (problem: { readonly message: string }): WalkUnavailable =>
 /** `readdir(recursive)` yields paths relative to the root it read: root them. */
 const rooted = (root: string, paths: ReadonlyArray<string>) => paths.map((rel) => `${root}/${rel}`);
 
+/** A test on a path relative to the root being read: whether the run wants it. */
+type Keep = (relative: string) => boolean;
+
 /** What the root actually contains: only paths the audit reads. */
-const scannable = (root: string, paths: ReadonlyArray<string>, self: string) =>
+const scannable = (root: string, paths: ReadonlyArray<string>, self: string, keep: Keep) =>
   rooted(
     root,
-    paths.filter((relative) => !isInSkippedTree(relative)),
+    paths.filter((relative) => !isInSkippedTree(relative) && keep(relative)),
   ).filter((file) => isScannable(file, self));
 
 /** One root's paths, filtered to what the audit reads. */
 const listRoot = Effect.fn("SourceWalker.listRoot")(
-  (fs: FileSystem.FileSystem, root: string, self: string) =>
+  (fs: FileSystem.FileSystem, root: string, self: string, keep: Keep) =>
     Effect.map(fs.readDirectory(root, { recursive: true }), (paths) =>
-      scannable(root, paths, self),
+      scannable(root, paths, self, keep),
     ),
 );
 
@@ -78,8 +98,8 @@ const readEach = (fs: FileSystem.FileSystem, paths: ReadonlyArray<string>) =>
 
 /** One root's files, in directory order: read every scannable path. */
 const readRoot = Effect.fn("SourceWalker.readRoot")(
-  (fs: FileSystem.FileSystem, root: string, self: string) =>
-    Effect.flatMap(listRoot(fs, root, self), (paths) => readEach(fs, paths)),
+  (fs: FileSystem.FileSystem, root: string, self: string, keep: Keep) =>
+    Effect.flatMap(listRoot(fs, root, self, keep), (paths) => readEach(fs, paths)),
 );
 
 /**
@@ -103,20 +123,24 @@ const scanDirs = Effect.fn("SourceWalker.scanDirs")(function* (
  * The scan root is the current working directory, so the audit reads the
  * repository it is run in.
  */
-export const SourceWalkerLive = Layer.effect(SourceWalker)(
-  Effect.gen(function* () {
-    const fs = yield* FileSystem.FileSystem;
-    const path = yield* Path.Path;
-    // No segments: Path resolves against the working directory.
-    const root = path.resolve();
-    const self = yield* path.fromFileUrl(new URL("../../", import.meta.url)).pipe(Effect.orDie);
-    const walk = Effect.fn("SourceWalker.files")(function* () {
-      const dirs = yield* scanDirs(fs, root).pipe(Effect.mapError(refused));
-      const trees = yield* Effect.forEach(dirs, (dir) =>
-        readRoot(fs, path.join(root, dir), self).pipe(Effect.mapError(refused)),
-      );
-      return trees.flat();
-    });
-    return SourceWalker.of({ files: walk() });
-  }),
-);
+export const SourceWalkerLive = (filter: ReadonlyArray<string> = []) =>
+  Layer.effect(SourceWalker)(
+    Effect.gen(function* () {
+      const fs = yield* FileSystem.FileSystem;
+      const path = yield* Path.Path;
+      // No segments: Path resolves against the working directory.
+      const root = path.resolve();
+      const self = yield* path.fromFileUrl(new URL("../../", import.meta.url)).pipe(Effect.orDie);
+      const walk = Effect.fn("SourceWalker.files")(function* () {
+        const dirs = yield* scanDirs(fs, root).pipe(Effect.mapError(refused));
+        const trees = yield* Effect.forEach(dirs, (dir) =>
+          readRoot(fs, path.join(root, dir), self, (relative) =>
+            // Filter patterns are relative to the working directory, not the tree read.
+            passesFilter(dir === "." ? relative : `${dir}/${relative}`, filter),
+          ).pipe(Effect.mapError(refused)),
+        );
+        return trees.flat();
+      });
+      return SourceWalker.of({ files: walk() });
+    }),
+  );

package/src/workflows/audit.ts

@@ -30,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>;
 }
 
@@ -69,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. */
@@ -82,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;
 }
@@ -108,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
@@ -191,6 +238,7 @@ export const executeAudit = (
       prepared,
       kept,
       pending,
+      deferred,
     }: FilePlan) {
       const probabilities = isEmpty(pending)
         ? {}
@@ -243,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))),
@@ -274,6 +322,7 @@ export const executeAudit = (
       judged: count("judged"),
       cached: count("cached"),
       skipped: count("skipped"),
+      waiting: count("waiting"),
       findings: results.flatMap((result) => result.findings),
     };
   });
@@ -283,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

@@ -124,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")}.`)],
@@ -153,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}`,
   ];
 };