@drkmttr/adhere 0.11.0 → 0.13.0

package/src/rules.ts

@@ -1,7 +1,7 @@
 import {
   ConfigUnavailable,
   type Override,
-  type Rule,
+  Rule,
   type RuleId,
   type RuleSource,
   SKIPPED_DIRECTORIES,
@@ -9,7 +9,7 @@ import {
 import { parseRuleMarkdown } from "#markdown.ts";
 import { walkFiles } from "#walk.ts";
 import { clearingStatus, countOf, Status } from "#services/Status.ts";
-import { Effect, FileSystem, Path, Record } from "effect";
+import { Effect, FileSystem, Path, Record, Schema } from "effect";
 
 const refused = (directory: string) => (problem: { readonly message: string }) =>
   ConfigUnavailable.make({
@@ -40,6 +40,10 @@ export type RuleSet = ReadonlyArray<RuleEntry>;
 
 const ADHERE_SEGMENT = ".adhere";
 const CACHE_SEGMENT = "cache";
+/** Where in a `.adhere/` its rules sit, one to a directory. */
+const RULES_PREFIX = "rules/";
+/** The file in a rule's directory that is the rule: Markdown, or TypeScript that default-exports `defineRule({...})`. */
+const RULE_FILES: ReadonlySet<string> = new Set(["RULE.md", "RULE.ts"]);
 
 const normalized = (path: string): string => path.replaceAll("\\", "/");
 
@@ -48,12 +52,69 @@ const segmentsOf = (relative: string): ReadonlyArray<string> =>
     .split("/")
     .filter((segment) => segment.length > 0);
 
-const isMarkdown = (path: string): boolean => path.endsWith(".md");
+/** A rule file, and its path in the directory it was read from. */
+interface RuleFile {
+  readonly id: RuleId;
+  readonly leaf: string;
+}
+
+/**
+ * The rules among `leaves`, the paths in `directory`, whose rules sit under
+ * `prefix` one to a directory: `<id>/RULE.md` or `<id>/RULE.ts`. Anything else
+ * in a rule's directory, such as a helper its RULE.ts imports, is not a rule.
+ * A directory with both files refuses, and so does a Markdown file outside
+ * every rule's directory, but a README.md: before rule directories, it was a
+ * rule, and the refusal says where it goes now to keep its id.
+ */
+const ruleFilesIn = (
+  directory: string,
+  leaves: ReadonlyArray<string>,
+  prefix: string,
+): Effect.Effect<ReadonlyArray<RuleFile>, ConfigUnavailable> => {
+  const files = leaves.flatMap((leaf): ReadonlyArray<RuleFile> => {
+    const segments = segmentsOf(leaf.slice(prefix.length));
+    return leaf.startsWith(prefix) && segments.length > 1 && RULE_FILES.has(segments.at(-1) ?? "")
+      ? [{ id: segments.slice(0, -1).join("/"), leaf }]
+      : [];
+  });
+  const both = files.find((file, index) => files.findIndex(({ id }) => id === file.id) < index);
+  if (both !== undefined) {
+    return Effect.fail(
+      ConfigUnavailable.make({
+        message: `${directory}/${prefix}${both.id}: a rule is a RULE.md or a RULE.ts, not both`,
+      }),
+    );
+  }
+  const homes = files.map(({ leaf }) => leaf.slice(0, leaf.lastIndexOf("/") + 1));
+  const flat = leaves.filter((leaf) => {
+    const name = segmentsOf(leaf).at(-1) ?? "";
+    return (
+      leaf.endsWith(".md") &&
+      !RULE_FILES.has(name) &&
+      name !== "README.md" &&
+      !homes.some((home) => leaf.startsWith(home))
+    );
+  });
+  if (flat.length > 0) {
+    return Effect.fail(
+      ConfigUnavailable.make({
+        message: [
+          `Rules now live one to a directory, as ${directory}/${prefix}<id>/RULE.md or RULE.ts. Move each of these to keep its id:`,
+          ...flat.map(
+            (leaf) =>
+              `  ${directory}/${leaf} → ${directory}/${prefix}${leaf.slice(0, -".md".length)}/RULE.md`,
+          ),
+        ].join("\n"),
+      }),
+    );
+  }
+  return Effect.succeed(files);
+};
 
 /**
  * Whether the rule walk reads into a directory: on the way to a `.adhere/`,
  * not a skipped tree or `.git`; inside one, anything but its cache, since a
- * directory there such as `.adhere/e2e/` is a rule topic.
+ * directory there such as `.adhere/rules/e2e/` is a rule topic.
  */
 const entersForRules = (relative: string): boolean => {
   const segments = segmentsOf(relative);
@@ -65,45 +126,30 @@ const entersForRules = (relative: string): boolean => {
   return name === ADHERE_SEGMENT || !(SKIPPED_DIRECTORIES.has(name) || name === ".git");
 };
 
-const isNestedRuleFile = (relative: string): boolean => {
-  const segments = segmentsOf(relative);
-  const adhere = segments.lastIndexOf(ADHERE_SEGMENT);
-  return (
-    adhere >= 0 &&
-    segments[adhere + 1] !== CACHE_SEGMENT &&
-    isMarkdown(relative) &&
-    // Only the path to the `.adhere/`: `.adhere/e2e/` is a rule topic, not a skip.
-    !segments.slice(0, adhere).some((segment) => SKIPPED_DIRECTORIES.has(segment))
-  );
-};
-
-const rulePathOf = (segments: ReadonlyArray<string>): ReadonlyArray<string> => {
-  const adhere = segments.lastIndexOf(ADHERE_SEGMENT);
-  return adhere < 0 ? [] : segments.slice(adhere + 1);
-};
-
-const scopePathOf = (segments: ReadonlyArray<string>): ReadonlyArray<string> => {
-  const adhere = segments.lastIndexOf(ADHERE_SEGMENT);
-  return adhere < 0 ? [] : segments.slice(0, adhere);
-};
-
-const ruleIdOf = (relative: string): RuleId => {
-  const rulePath = rulePathOf(segmentsOf(relative));
-  const leaf = rulePath.join("/");
-  return leaf.slice(0, -".md".length);
+/**
+ * Each `.adhere/` the walk found, by its path from the root, with the paths
+ * of the files in it. Only the path to a `.adhere/` counts against skipped
+ * trees: `.adhere/rules/e2e/` is a rule topic, not a skip.
+ */
+const adhereDirectoriesOf = (
+  relatives: ReadonlyArray<string>,
+): ReadonlyMap<string, ReadonlyArray<string>> => {
+  const found = new Map<string, Array<string>>();
+  for (const relative of relatives) {
+    const segments = segmentsOf(relative);
+    const adhere = segments.lastIndexOf(ADHERE_SEGMENT);
+    if (adhere < 0 || segments.slice(0, adhere).some((name) => SKIPPED_DIRECTORIES.has(name))) {
+      continue;
+    }
+    const directory = segments.slice(0, adhere + 1).join("/");
+    found.set(directory, [...(found.get(directory) ?? []), segments.slice(adhere + 1).join("/")]);
+  }
+  return found;
 };
 
 const joinPath = (path: Path.Path, root: string, parts: ReadonlyArray<string>): string =>
   parts.reduce((current, part) => path.join(current, part), root);
 
-const scopedRule = (path: Path.Path, root: string, relative: string, rule: Rule): RuleEntry => {
-  const segments = segmentsOf(relative);
-  const scopeParts = scopePathOf(segments);
-  const scope = scopeParts.length === 0 ? path.resolve(root) : joinPath(path, root, scopeParts);
-  const file = joinPath(path, root, segments);
-  return { id: ruleIdOf(relative), file, scope, rule };
-};
-
 const isInside = (file: string, scope: string): boolean =>
   file === scope || file.startsWith(`${scope}/`);
 
@@ -111,9 +157,40 @@ const moreSpecific = (a: RuleEntry, b: RuleEntry): RuleEntry =>
   normalized(a.scope).length >= normalized(b.scope).length ? a : b;
 
 /**
- * Every `*.md` file under `directory`, validated and keyed by its path
- * relative to the directory without the extension: `basics/gen.md` is the
- * rule `basics/gen`.
+ * A rule written in TypeScript: the file's default export, decoded as a
+ * config's inline rule is, so a hook such as `appendState` comes with it.
+ * Like a config, the file is imported, so its code runs.
+ */
+const importRule = Effect.fn("importRule")(function* (file: string) {
+  const path = yield* Path.Path;
+  const url = yield* path.toFileUrl(file).pipe(Effect.orDie);
+  const loaded = yield* Effect.tryPromise({
+    try: () => import(url.href) as Promise<{ readonly default?: unknown }>,
+    catch: (cause) =>
+      ConfigUnavailable.make({
+        message: `Could not load ${file}: ${cause instanceof Error ? cause.message : String(cause)}`,
+      }),
+  });
+  return yield* Schema.decodeUnknownEffect(Rule)(loaded.default).pipe(
+    Effect.mapError((problem) =>
+      ConfigUnavailable.make({
+        message: `${file}: a rule file must default-export defineRule({...}): ${problem.message}`,
+      }),
+    ),
+  );
+});
+
+/** A rule file's rule. A file that cannot be read refuses with the directory it was read from. */
+const readRule = Effect.fn("readRule")(function* (file: string, directory: string) {
+  if (file.endsWith(".ts")) return yield* importRule(file);
+  const fs = yield* FileSystem.FileSystem;
+  const text = yield* fs.readFileString(file).pipe(Effect.mapError(refused(directory)));
+  return yield* parseRuleMarkdown(text, file);
+});
+
+/**
+ * Every rule under `directory`, validated and keyed by its directory's path
+ * in it: `basics/gen/RULE.md` is the rule `basics/gen`.
  */
 export const loadRules = Effect.fn("loadRules")(function* (directory: string) {
   const fs = yield* FileSystem.FileSystem;
@@ -121,19 +198,18 @@ export const loadRules = Effect.fn("loadRules")(function* (directory: string) {
   const entries = yield* fs
     .readDirectory(directory, { recursive: true })
     .pipe(Effect.mapError(refused(directory)));
-  const files = entries.filter((entry) => entry.endsWith(".md")).sort();
-  const rules = yield* Effect.forEach(files, (relative) =>
-    Effect.gen(function* () {
-      const file = path.join(directory, relative);
-      const text = yield* fs.readFileString(file).pipe(Effect.mapError(refused(directory)));
-      const id: RuleId = relative.slice(0, -".md".length).split(path.sep).join("/");
-      return [id, yield* parseRuleMarkdown(text, file)] as const;
-    }),
+  const files = yield* ruleFilesIn(directory, entries.map(normalized).sort(), "");
+  const rules = yield* Effect.forEach(files, ({ id, leaf }) =>
+    Effect.map(readRule(path.join(directory, leaf), directory), (rule) => [id, rule] as const),
   );
   return Record.fromEntries(rules) as Readonly<Record<RuleId, Rule>>;
 });
 
-/** Every nested `.adhere/` rule under `root`, scoped to its owner directory. */
+/**
+ * Every rule in a `.adhere/rules/` under `root`, scoped to the directory that
+ * holds its `.adhere/`: `packages/api/.adhere/rules/data/ports/RULE.md` is
+ * `data/ports` for the files under `packages/api/`.
+ */
 export const loadAdhereRuleSet = Effect.fn("loadAdhereRuleSet")(function* (root: string) {
   const fs = yield* FileSystem.FileSystem;
   const path = yield* Path.Path;
@@ -145,14 +221,17 @@ export const loadAdhereRuleSet = Effect.fn("loadAdhereRuleSet")(function* (root:
       ),
     ),
   ).pipe(Effect.mapError(refused(root)));
-  const files = entries.filter(isNestedRuleFile);
-  return yield* Effect.forEach(files, (relative) =>
-    Effect.gen(function* () {
-      const file = joinPath(path, root, segmentsOf(relative));
-      const text = yield* fs.readFileString(file).pipe(Effect.mapError(refused(root)));
-      return scopedRule(path, root, relative, yield* parseRuleMarkdown(text, file));
+  const found = yield* Effect.forEach(adhereDirectoriesOf(entries), ([adhere, leaves]) =>
+    Effect.flatMap(ruleFilesIn(adhere, [...leaves].sort(), RULES_PREFIX), (files) => {
+      const owner = segmentsOf(adhere).slice(0, -1);
+      const scope = owner.length === 0 ? path.resolve(root) : joinPath(path, root, owner);
+      return Effect.forEach(files, ({ id, leaf }) => {
+        const file = joinPath(path, root, segmentsOf(`${adhere}/${leaf}`));
+        return Effect.map(readRule(file, root), (rule): RuleEntry => ({ id, file, scope, rule }));
+      });
     }),
   );
+  return found.flat();
 });
 
 /** Rules as given, or loaded from the directory a source names. */

package/src/services/AdhereConfig.ts

@@ -1,5 +1,4 @@
 import {
-  ADHERE_DIRECTORY,
   AdhereConfig as AdhereConfigSchema,
   CONFIG_FILES,
   ConfigUnavailable,
@@ -10,6 +9,7 @@ import {
   presetsOf,
   type ResolvedConfig,
   resolveConfig,
+  RULES_DIRECTORY,
 } from "#config.ts";
 import { type PresetName, presetOf, presets, wholePresetOf } from "#presets.ts";
 import {
@@ -94,7 +94,7 @@ export const AdhereConfigLive = (flags: Flags) =>
       const hasProjectRules = discoveredEntries.length > 0;
       if (configFile === undefined && !hasProjectRules && !hasPreset) {
         return yield* ConfigUnavailable.make({
-          message: `Nothing to audit against: no config file (${CONFIG_FILES.join(", ")}), no ${ADHERE_DIRECTORY}/ directory of rules, and no --preset. Pass --preset effect to use the built-in rules.`,
+          message: `Nothing to audit against: no config file (${CONFIG_FILES.join(", ")}), no rules in ${RULES_DIRECTORY}/, and no --preset. Pass --preset effect to use the built-in rules.`,
         });
       }
       const projectEntries: RuleSet =

package/src/services/Credentials.ts

@@ -46,10 +46,10 @@ export const CredentialsLive = Layer.effect(Credentials)(
     const fs = yield* FileSystem.FileSystem;
     const path = yield* Path.Path;
 
-    const file = Config.nonEmptyString("XDG_CONFIG_HOME").pipe(
+    const file = Config.NonEmptyString("XDG_CONFIG_HOME").pipe(
       Config.orElse(() =>
-        Config.nonEmptyString("HOME").pipe(
-          Config.orElse(() => Config.nonEmptyString("USERPROFILE")),
+        Config.NonEmptyString("HOME").pipe(
+          Config.orElse(() => Config.NonEmptyString("USERPROFILE")),
           Config.map((home) => path.join(home, ".config")),
         ),
       ),
@@ -78,7 +78,7 @@ export const CredentialsLive = Layer.effect(Credentials)(
 
     // Read when a request needs the key, not before: a cached run needs none.
     const apiKey = Effect.fn("Credentials.apiKey")(function* () {
-      const fromEnvironment = yield* Config.option(Config.redacted("TYPESAFE_API_KEY")).pipe(
+      const fromEnvironment = yield* Config.option(Config.Redacted("TYPESAFE_API_KEY")).pipe(
         Effect.mapError((problem) => refused(`Cannot read TYPESAFE_API_KEY: ${problem.message}`)),
       );
       if (Option.isSome(fromEnvironment)) return fromEnvironment.value;

package/src/services/Jev.http.ts

@@ -1,4 +1,4 @@
-import type { RuleId } from "#config.ts";
+import type { AppendState, JevState, JudgedFile, RuleId } from "#config.ts";
 import { sectionsOf } from "#excerpt.ts";
 import { AdhereConfig } from "#services/AdhereConfig.ts";
 import { Credentials } from "#services/Credentials.ts";
@@ -22,6 +22,7 @@ import {
   namedPairs,
   type Pair,
   pairProbability,
+  requestGroups,
   requestsOf,
   type Rules,
   sufficiencyKey,
@@ -38,9 +39,9 @@ import {
   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";
+import { HttpClient, HttpClientError, HttpClientResponse } from "effect/http";
+import * as HttpClientRequest from "effect/http/HttpClientRequest";
+import { RateLimiter } from "effect/persistence";
 
 const SYSTEM_ONE = "https://api.typesafe.ai/v1/systemone";
 
@@ -63,6 +64,35 @@ const LocateAnswers = Schema.Struct({
 
 const refused = (message: string) => JevUnavailable.make({ message });
 
+/** Bun's API, for a rule's hook. Read off `globalThis`, as presets.ts reads it: Vitest runs this on Node. */
+const bun = (globalThis as { readonly Bun?: unknown }).Bun as Parameters<AppendState>[2];
+
+/**
+ * A body as it goes out: when its rule has `appendState`, with what the hook
+ * returns spread over the body's state. A hook that fails refuses the run.
+ */
+const hooked = (
+  body: Body & { readonly state: JevState },
+  group: Rules,
+  file: JudgedFile,
+): Effect.Effect<Body, JevUnavailable> => {
+  const [hook] = Object.entries(group).flatMap(([id, rule]) =>
+    rule.appendState === undefined ? [] : [[id, rule.appendState] as const],
+  );
+  if (hook === undefined) return Effect.succeed(body);
+  const [id, appendState] = hook;
+  return Effect.tryPromise({
+    try: async () => ({
+      ...body,
+      state: { ...body.state, ...(await appendState(body.state, file, bun)) },
+    }),
+    catch: (cause) =>
+      refused(
+        `the appendState of ${id} failed: ${cause instanceof Error ? cause.message : String(cause)}`,
+      ),
+  });
+};
+
 /** A failed attempt, for the log: the status and Ray ID when Jev's side answered, the cause otherwise. */
 const attemptFailure = (
   problem: HttpClientError.HttpClientError | RateLimiter.RateLimiterError | Cause.TimeoutError,
@@ -224,14 +254,44 @@ export const JevLive = Layer.effect(Jev)(
           ),
       );
 
+    /**
+     * Every answer about a file's rules: a body for each group that
+     * `requestGroups` makes of them, each with its rule's hook run right
+     * before it goes out.
+     */
+    const answersAbout = <A>(
+      kind: string,
+      rules: Rules,
+      bodyOf: (group: Rules) => Body & { readonly state: JevState },
+      file: JudgedFile,
+      Answers: Schema.Codec<
+        { readonly answers: Readonly<Record<string, A>> },
+        unknown,
+        never,
+        never
+      >,
+    ) =>
+      Effect.map(
+        Effect.forEach(requestGroups(rules), (group) =>
+          Effect.flatMap(hooked(bodyOf(group), group, file), (body) =>
+            answersTo(kind, body, Answers),
+          ),
+        ),
+        (groups) =>
+          groups.reduce<Record<string, A>>((answers, some) => ({ ...answers, ...some }), {}),
+      );
+
     const judge = Effect.fn("Jev.judge")(function* (
       lines: Lines,
       rules: Rules,
-      sampled: ReadonlyArray<RuleId> = [],
+      sampled: ReadonlyArray<RuleId>,
+      file: JudgedFile,
     ) {
-      const answers = yield* answersTo(
+      const answers = yield* answersAbout(
         "judge",
-        judgeBody(config.model, lines, rules, sampled),
+        rules,
+        (group) => judgeBody(config.model, lines, group, sampled),
+        file,
         NoulAnswers,
       );
       /** Each rule's answer, read from the question it rode under. */
@@ -270,11 +330,17 @@ export const JevLive = Layer.effect(Jev)(
       } satisfies Judged;
     });
 
-    const locate = Effect.fn("Jev.locate")(function* (lines: Lines, rules: Rules) {
+    const locate = Effect.fn("Jev.locate")(function* (
+      lines: Lines,
+      rules: Rules,
+      file: JudgedFile,
+    ) {
       const sections = sectionsOf(lines);
-      const answers = yield* answersTo(
+      const answers = yield* answersAbout(
         "locate",
-        locateBody(config.model, lines, rules),
+        rules,
+        (group) => locateBody(config.model, lines, group),
+        file,
         LocateAnswers,
       );
       // A file of one section has every finding in it. An answer that names no section,

package/src/services/Jev.ts

@@ -1,4 +1,11 @@
-import { type Example, examplesOf, type Rule, type RuleId, type Rules } from "#config.ts";
+import {
+  type Example,
+  examplesOf,
+  type JudgedFile,
+  type Rule,
+  type RuleId,
+  type Rules,
+} from "#config.ts";
 import { type Range, sectionsOf } from "#excerpt.ts";
 import { Context, type Effect, Record, Schema } from "effect";
 
@@ -47,12 +54,13 @@ export class Jev extends Context.Service<
     /**
      * Each rule's probability that the file breaks it. A rule in `sampled`
      * also carries the linter check's question, whose answer comes back
-     * under `linter`.
+     * under `linter`. `file` is what a rule's `appendState` gets.
      */
     readonly judge: (
       lines: Lines,
       rules: Rules,
-      sampled?: ReadonlyArray<RuleId>,
+      sampled: ReadonlyArray<RuleId>,
+      file: JudgedFile,
     ) => Effect.Effect<Judged, JevUnavailable | JevOverflow | JevBlocked>;
     /**
      * Per rule, the section of the file that most clearly breaks it, and
@@ -62,6 +70,7 @@ export class Jev extends Context.Service<
     readonly locate: (
       lines: Lines,
       rules: Rules,
+      file: JudgedFile,
     ) => Effect.Effect<Record<RuleId, Located>, JevUnavailable | JevOverflow | JevBlocked>;
     /**
      * Per rule, the partner Jev names as impossible to follow in the same code,
@@ -468,33 +477,53 @@ export const requestsOf = (body: Body): ReadonlyArray<Body> => {
   return requests.map(({ questions }) => ({ ...body, questions }));
 };
 
+/**
+ * The rules as requests carry them: every rule without `appendState` in one
+ * body, and each rule with it in a body of its own, so that what its hook
+ * puts in the state only its own questions read.
+ */
+export const requestGroups = (rules: Rules): ReadonlyArray<Rules> => {
+  const shared = Record.filter(rules, (rule) => rule.appendState === undefined);
+  return [
+    ...(Record.isEmptyRecord(shared) ? [] : [shared]),
+    ...Object.entries(rules).flatMap(([id, rule]) =>
+      rule.appendState === undefined ? [] : [{ [id]: rule }],
+    ),
+  ];
+};
+
+/** The judge requests for `rules` over a file: a body per group, split to fit, as `judge` sends them. */
+const judgeRequestsOf = (lines: Lines, rules: Rules, sampled: ReadonlyArray<RuleId>) =>
+  requestGroups(rules).flatMap((group) => requestsOf(judgeBody("", lines, group, sampled)));
+
 /**
  * The requests judging `rules` over a file takes, and about how many input
- * tokens they carry, by `tokensOf`: the judge body, split to fit, as `judge`
- * sends it, each request with the file again.
+ * tokens they carry, by `tokensOf`: the judge bodies, split to fit, as
+ * `judge` sends them, each request with the file again. What a rule's
+ * `appendState` adds is not known before it runs, so it is not counted.
  */
 export const judgeLoad = (
   lines: Lines,
   rules: Rules,
   sampled: ReadonlyArray<RuleId> = [],
 ): { readonly requests: number; readonly tokens: number } => {
-  const requests = requestsOf(judgeBody("", lines, rules, sampled));
+  const requests = judgeRequestsOf(lines, rules, sampled);
   return {
     requests: requests.length,
     tokens: requests.reduce((sum, request) => sum + tokensOf(request), 0),
   };
 };
 
-/** The requests judging `rules` over a file takes: the judge body, split to fit, as `judge` sends it. */
+/** The requests judging `rules` over a file takes: the judge bodies, split to fit, as `judge` sends them. */
 export const judgeRequests = (
   lines: Lines,
   rules: Rules,
   sampled: ReadonlyArray<RuleId> = [],
-): number => requestsOf(judgeBody("", lines, rules, sampled)).length;
+): number => judgeRequestsOf(lines, rules, sampled).length;
 
-/** The requests locating `rules` in a file takes, split to fit as `locate` sends them. */
+/** The requests locating `rules` in a file takes, a body per group split to fit, as `locate` sends them. */
 export const locateRequests = (lines: Lines, rules: Rules): number =>
-  requestsOf(locateBody("", lines, rules)).length;
+  requestGroups(rules).flatMap((group) => requestsOf(locateBody("", lines, group))).length;
 
 /** A choice keeps one criterion for "none", which leaves this many for partners. */
 const PARTNERS_PER_QUESTION = CHOICE_LIMIT - 1;

package/src/workflows/audit.ts

@@ -41,12 +41,14 @@ export interface Finding {
   /** 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.
+   * Jev's probability that the file shows enough to check the rule. Below the
+   * sufficiency threshold, the report warns, and says how to add the context.
    */
-  readonly insufficiency?: number;
+  readonly context?: number;
+  /** Jev's probability that the file breaks the rule. */
   readonly probability: number;
+  /** The rule's threshold: lint reports the finding only when its probability is above it. */
+  readonly threshold: number;
   /** An error fails the run; a warning does not, unless `--deny-warnings`. */
   readonly level: Level;
 }
@@ -109,12 +111,16 @@ const LAYOUT = "sections";
  * 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.
+ * every rule. So does an edited `appendState`, by its source; what the hook
+ * reads outside the file is not known until it runs, so a change there does not.
  */
 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}`);
+  const hook = rule.appendState === undefined ? "" : `\u0000${rule.appendState.toString()}`;
+  return sha256(
+    `${model}\u0000${LAYOUT}\u0000${JSON.stringify(judgeQuestion(rule))}${scope}${hook}`,
+  );
 };
 
 /** A section's lines as written, without the blank lines at either end. */
@@ -192,6 +198,8 @@ export interface AuditPlan {
   readonly tokens: number;
   /** The model's price per million input tokens, in dollars, when adhere knows it. */
   readonly price?: number;
+  /** The run's threshold, which a rule's own, or an override's, replaces for that rule. */
+  readonly threshold: number;
   /** Below this, a finding's sufficiency adds a warning to it. */
   readonly sufficiencyThreshold: number;
 }
@@ -459,6 +467,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 }),
+      threshold: config.threshold,
       sufficiencyThreshold: config.sufficiencyThreshold,
     };
   });
@@ -509,9 +518,13 @@ export const executeAudit = (
       deferred,
       sampled,
     }: FilePlan) {
+      // What a rule's appendState gets: the file as written, not as Jev reads it.
+      const asWritten = { path: file.path, contents: original.join("\n") };
       const { probabilities, linter, matchers }: Judged = isEmpty(pending)
         ? { probabilities: {}, linter: {} }
-        : yield* jev.judge(file.lines, rulesOf(pending), Object.keys(sampled)).pipe(inFile(file));
+        : yield* jev
+            .judge(file.lines, rulesOf(pending), Object.keys(sampled), asWritten)
+            .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)) {
@@ -549,7 +562,7 @@ export const executeAudit = (
         readonly blocked: Blocked | undefined;
       } = isEmpty(flagged)
         ? { places: {}, blocked: undefined }
-        : yield* jev.locate(file.lines, rulesOf(flagged)).pipe(
+        : yield* jev.locate(file.lines, rulesOf(flagged), asWritten).pipe(
             Effect.map((places) => ({ places, blocked: undefined })),
             Effect.catchTag("JevBlocked", ({ ray }) =>
               Effect.succeed({ places: {}, blocked: { file: file.path, ray } }),
@@ -581,11 +594,9 @@ export const executeAudit = (
                   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 }
-                    : {}),
+                  ...(judgment.sufficiency === undefined ? {} : { context: judgment.sufficiency }),
                   probability: judgment.probability,
+                  threshold: k.threshold,
                   level: k.rule.level ?? "error",
                 },
               ]