@drkmttr/adhere 0.7.0 → 0.7.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Darkmatter Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

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,28 @@ 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.
 
+The firewall in front of Jev's API can refuse a request whose code reads to
+it as an attack, with a 403 and an HTML page rather than Jev's JSON. It refuses
+the same request every run, so that file is skipped, the run goes on, and the
+report lists each such file with Cloudflare's Ray ID, which TypeSafe AI can
+look the block up by. When only the question that finds the line is refused,
+the file's judgments are kept, and a rerun sends that question alone.
+
+### 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`,
@@ -413,3 +438,7 @@ runs. The publish workflow can be run manually for an already-created release
 tag if a publish needs to be retried; it skips every package whose version is
 already on npm. The main package's `files` list keeps it to `bin/`, `src/`,
 `presets/`, and `skills/`.
+
+## License
+
+MIT. See [LICENSE](LICENSE).

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.7.0",
+  "version": "0.7.3",
   "private": false,
   "description": "Lints a repository against the rules in .adhere/, judged by Jev.",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/darkmatter/adhere.git"
@@ -67,10 +68,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.3",
+    "@drkmttr/adhere-darwin-x64": "0.7.3",
+    "@drkmttr/adhere-linux-arm64": "0.7.3",
+    "@drkmttr/adhere-linux-x64": "0.7.3",
+    "@drkmttr/adhere-win32-x64": "0.7.3"
   }
 }

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

@@ -7,6 +7,7 @@ import {
   conflictBody,
   contradictBody,
   Jev,
+  JevBlocked,
   JevOverflow,
   JevUnavailable,
   judgeBody,
@@ -19,9 +20,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";
 
@@ -47,40 +49,80 @@ const Overflowed = Schema.fromJsonString(
 const isOverflow = (body: string): boolean =>
   Option.isSome(Schema.decodeUnknownOption(Overflowed)(body));
 
+/** A firewall's block page: HTML where Jev answers JSON, even for its own errors. */
+const isBlockPage = (response: HttpClientResponse.HttpClientResponse, body: string): boolean =>
+  (response.headers["content-type"] ?? "").includes("text/html") ||
+  body.trimStart().startsWith("<");
+
 /**
  * A request that failed. A 400 saying the request is over Jev's context is a
  * `JevOverflow`, which skips the file. Any other answer outside 2xx refuses
  * 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}`));
   }
   const { response } = problem.reason;
   return Effect.flatMap(
     Effect.orElseSucceed(response.text, () => ""),
-    (body): Effect.Effect<never, JevOverflow | JevUnavailable> =>
+    (body): Effect.Effect<never, JevOverflow | JevBlocked | JevUnavailable> =>
       response.status === 400 && isOverflow(body)
         ? Effect.fail(JevOverflow.make())
-        : Effect.fail(refused(`Jev answered HTTP ${response.status}${detailOf(body)}`)),
+        : response.status === 403 && isBlockPage(response, body)
+          ? Effect.fail(JevBlocked.make({ ray: response.headers["cf-ray"] ?? "none given" }))
+          : Effect.fail(refused(`Jev answered HTTP ${response.status}${detailOf(body)}`)),
   );
 };
 
-/** Comparing rules has no file to skip, so a request over Jev's context refuses instead. */
+/**
+ * Comparing rules has no file to skip, so a request over Jev's context, or one
+ * the firewall blocks, refuses instead.
+ */
 const refuseOverflow = <A>(
-  self: Effect.Effect<A, JevOverflow | JevUnavailable>,
+  self: Effect.Effect<A, JevOverflow | JevBlocked | JevUnavailable>,
 ): Effect.Effect<A, JevUnavailable> =>
-  Effect.catchTag(self, "JevOverflow", () =>
-    Effect.fail(refused("Comparing the rules took a request over Jev's context")),
+  self.pipe(
+    Effect.catchTag("JevOverflow", () =>
+      Effect.fail(refused("Comparing the rules took a request over Jev's context")),
+    ),
+    Effect.catchTag("JevBlocked", ({ ray }) =>
+      Effect.fail(
+        refused(
+          `The firewall in front of Jev's API blocked comparing the rules (Cloudflare Ray ID ${ray})`,
+        ),
+      ),
+    ),
   );
 
 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 +214,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/Jev.ts

@@ -14,17 +14,27 @@ export class JevUnavailable extends Schema.TaggedError<JevUnavailable>()("JevUna
  */
 export class JevOverflow extends Schema.TaggedError<JevOverflow>()("JevOverflow", {}) {}
 
+/**
+ * A request the firewall in front of Jev's API refused: a 403 with an HTML
+ * block page where Jev answers JSON. It reads some code as an attack, so the
+ * same request is refused every time while the rest of a run goes through.
+ * `ray` is Cloudflare's Ray ID, which TypeSafe AI can look the block up by.
+ */
+export class JevBlocked extends Schema.TaggedError<JevBlocked>()("JevBlocked", {
+  ray: Schema.String,
+}) {}
+
 export class Jev extends Context.Service<
   Jev,
   {
     readonly judge: (
       lines: Lines,
       rules: Rules,
-    ) => Effect.Effect<Record<RuleId, number>, JevUnavailable | JevOverflow>;
+    ) => Effect.Effect<Record<RuleId, number>, JevUnavailable | JevOverflow | JevBlocked>;
     readonly locate: (
       lines: Lines,
       rules: Rules,
-    ) => Effect.Effect<Record<RuleId, number>, JevUnavailable | JevOverflow>;
+    ) => Effect.Effect<Record<RuleId, number>, JevUnavailable | JevOverflow | JevBlocked>;
     /**
      * Per rule, the partner Jev names as impossible to follow in the same code,
      * as `[rule, partner]` indexes into `rules`. A rule Jev names none for is

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,12 +30,23 @@ 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;
+  /** 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";
+  readonly status: "judged" | "cached" | "skipped" | "waiting" | "blocked";
   readonly findings: ReadonlyArray<Finding>;
+  readonly blocked?: Blocked;
 }
 
 interface PreparedRule {
@@ -69,6 +80,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 +95,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 +123,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 +247,7 @@ export const executeAudit = (
       prepared,
       kept,
       pending,
+      deferred,
     }: FilePlan) {
       const probabilities = isEmpty(pending)
         ? {}
@@ -209,9 +266,22 @@ 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
@@ -243,7 +313,10 @@ export const executeAudit = (
         })
         .sort((a, b) => a.line - b.line);
       return {
-        result: fileResult(cached ? "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(flagged) ? 0 : locateRequests(file.lines, rulesOf(flagged))),
@@ -261,6 +334,17 @@ export const executeAudit = (
                 requests: judgeRequests(plan.file.lines, rulesOf(plan.pending)),
               }),
             ),
+            // 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)),
+              }),
+            ),
           );
       yield* progress({ requests, findings: result.findings.length });
       return result;
@@ -274,6 +358,8 @@ export const executeAudit = (
       judged: count("judged"),
       cached: count("cached"),
       skipped: count("skipped"),
+      waiting: count("waiting"),
+      blocked: results.flatMap((result) => (result.blocked === undefined ? [] : [result.blocked])),
       findings: results.flatMap((result) => result.findings),
     };
   });
@@ -283,6 +369,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

@@ -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,22 @@ 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 soft white. 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.
  */
 const THEME: Readonly<Record<Role, string>> = {
-  error: "38;2;219;91;81;1",
+  error: "38;5;197;1",
+  probability: "38;2;250;179;135",
+  description: "38;2;242;205;205",
   path: "38;2;5;125;160;1",
   lineNumber: "2",
   underline: "38;2;255;0;175",
-  label: "38;2;180;105;245",
+  label: "38;5;212",
   comment: "2",
   string: "32",
   constant: "33",
@@ -77,9 +90,11 @@ 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. */
@@ -109,8 +124,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 offending line, a pink underline, and the code to write
+ * as the hint.
  */
 const frame = (finding: Finding, root: string | undefined): ReadonlyArray<Line> => [
   header(finding),
@@ -124,6 +140,8 @@ const summary = (result: AuditResult): ReadonlyArray<Line> => {
     `${result.judged} judged`,
     `${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")}.`)],
@@ -131,6 +149,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;
@@ -146,6 +185,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));
 
 /**
@@ -153,18 +193,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}`,
   ];
 };