@drkmttr/adhere 0.4.1 → 0.6.0

package/README.md

@@ -30,9 +30,9 @@ with a TypeSafe AI API key: the one `adhere login` saved, or
 
 ```sh
 adhere init                          # .adhere/config.ts and two example rules
-adhere validate                      # check the config and rules, without Jev
 echo ".adhere/cache/" >> .gitignore
 adhere login                         # save your TypeSafe AI API key, once
+adhere validate                      # check the rules, and ask Jev whether any contradict
 adhere lint                          # audit the working directory
 ```
 
@@ -68,7 +68,8 @@ refusal prints its reason.
 adhere lint                    # audit the working directory
 adhere lint --preset effect    # add a built-in rule set; the config becomes optional
 adhere lint --threshold 0.8    # replace the config's threshold; per-rule thresholds still apply
-adhere validate                # load the config and rules without Jev, check for contradictions
+adhere lint --yes              # send the requests without asking first
+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
 adhere logout                  # delete the saved key
@@ -79,6 +80,24 @@ Bare `adhere` prints the help, which lists the commands, and
 `adhere <command> --help` lists a command's flags. `adhere --completions <shell>`
 prints a completion script.
 
+### Before and during a run
+
+Before it sends anything, `lint` says on stderr what it found and what judging
+takes:
+
+```text
+200 files and 14 rules: 2800 checks, 1400 cached.
+Judging the other 1400 takes 200 requests to Jev, plus 1 or more for each file with a finding.
+? Send 200 requests to Jev? › (Y/n)
+```
+
+It asks only with a terminal on stdin and stdout, and never when the cache
+answers every check; `--yes` sends without asking. While it runs, a counter on
+stderr shows the files done, the requests sent, and the findings so far, and
+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.
+
 ### What gets read
 
 `adhere lint` reads the `.ts` files under the working directory, except `.d.ts`,
@@ -99,20 +118,24 @@ kept, and no second one is added, even with `--force`.
 ### Validate
 
 `adhere validate` loads the config, rule files, and presets the way `lint`
-does, without calling Jev, so a file that fails to decode refuses here too, and
-it prints how many rules it loaded. `--preset` adds a built-in rule set, as for
-`lint`. It then checks the rules for local textual contradictions: it exits 1
-and prints the conflicting rule files when overlapping rule scopes contain
-opposite textual directives for the same topic, such as "Use service classes
-for IO" and "Do not use service classes for IO". Same-id nested rules are
-treated as intentional shadowing rather than contradictions.
+does, so a file that fails to decode refuses here too, and it prints how many
+rules it loaded. `--preset` adds a built-in rule set, as for `lint`. It then
+asks Jev whether any two rules that apply to the same files contradict, so that
+no code can follow both: one request names, per rule, the rule it conflicts
+with, if any, and each named pair then gets a probability from a request of
+its own, holding only those two rules, since other rules beside them dilute
+the judgment. A pair above
+the threshold is printed with both rule files, and the exit code is 1. Two
+rules with the same id are not compared: a nested rule that shares an id
+shadows the other on purpose. When no two rules share files nothing is sent;
+otherwise `validate` needs the API key, as `lint` does.
 
 ### Login
 
 `adhere login` prompts for a TypeSafe AI API key, masking what you type, and
 saves it to `~/.config/adhere/credentials.json`, or under `$XDG_CONFIG_HOME`
 when that is set, readable only by you. Piped input is read instead of a
-prompt: `adhere login < key.txt`. `lint` uses the saved key, but
+prompt: `adhere login < key.txt`. `lint` and `validate` use the saved key, but
 `TYPESAFE_API_KEY`, when set, takes precedence, so CI can pass a key without a
 login. `adhere logout` deletes the saved key.
 
@@ -137,7 +160,7 @@ export default {
   rules: {
     "data/brand-meaningful-primitives": {
       description:
-        "A primitive with semantic meaning, such as an id, email, URL, port, or count, is a branded schema.",
+        "A primitive with semantic meaning, such as an id, email, URL, port, or count, should be a branded schema.",
       reference: `
 const UserId = Schema.String.pipe(Schema.brand("UserId"))
 type UserId = typeof UserId.Type
@@ -250,25 +273,36 @@ beats all of the above for that rule.
 
 ## How a file is judged
 
-1. One Jev request per file, with the file's numbered lines and every rule as
-   the state, and one `noul` (yes/no probability) question per rule: whether
-   the file diverges from the reference or, for a rule with only code to
-   avoid, whether it contains that code. Every question shares the state cost
-   of the request.
+1. One Jev request per file. The state is the file's numbered lines and
+   nothing else. Each rule is one `noul` (yes/no probability) question that
+   carries the rule: whether the file breaks the rule's description, with
+   criteria for each answer. Yes means part of the file breaks the rule, and
+   the code to avoid is an example of it. No means the file follows the rule
+   or has nothing the rule covers, and the reference is an example of it.
+   Since no rule sits in the shared state, a rule's probability depends only
+   on the file and that rule, not on which other rules share the request.
+   Every question shares the state cost of the request.
 2. A second request only when at least one rule's probability is above its
    threshold: one `choice` question per flagged rule over the file's non-blank
    lines, which yields the line to report. A file with more than 255 non-blank
    lines is located in two steps (a block of 20 lines, then a line inside it).
-   Files longer than 5100 lines are skipped and counted in the summary.
+3. Jev reads at most 32k tokens of state and one question together, and 64k
+   tokens in a request. adhere estimates tokens from the JSON it sends, at
+   about three bytes a token. When a file's questions would not fit in one
+   request, they are split across several. A file whose code and longest
+   question would not fit together, or that has more than 5100 lines, is
+   skipped and counted in the summary, and the rest of the run goes on.
 
 ## Cache
 
 Judgments are cached in `.adhere/cache/` (add it to `.gitignore`), one entry
 per file. An entry stores the file's content hash and, per rule, the
-probability, the located line, and a fingerprint of the rule's text and model.
-A changed file re-judges every rule for that file. An edited rule re-judges
-only that rule. A lowered threshold locates cached judgments that are newly
-above it without judging again. Entries depend on content, not on the
+probability, the located line, and a fingerprint of the model and the
+question asked for the rule, which carries the rule's text. A changed file
+re-judges every rule for that file. An edited rule re-judges only that rule,
+and an adhere that asks its questions differently re-judges every rule once.
+A lowered threshold locates cached judgments that are newly above it without
+judging again. Entries depend on content, not on the
 machine, so restoring `.adhere/cache/` between CI runs skips unchanged files.
 
 The API key is read only when a request is about to be sent. A run where

package/package.json

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

package/presets/effect/basics/fn-for-named-effects.md

@@ -1,5 +1,5 @@
 ---
-description: A named function that returns an Effect is defined with Effect.fn so the call site is traced.
+description: A named function that returns an Effect should be defined with Effect.fn so the call site is traced.
 ---
 
 ```ts

package/presets/effect/basics/gen-for-sequencing.md

@@ -1,5 +1,5 @@
 ---
-description: Sequential effectful steps are written with Effect.gen and yield*, not nested flatMap or callback chains.
+description: Sequential effectful steps should be written with Effect.gen and yield*, not nested flatMap or callback chains.
 ---
 
 ```ts

package/presets/effect/basics/instrument-with-pipe.md

@@ -1,5 +1,5 @@
 ---
-description: Timeouts, retries, logging, and spans are attached with .pipe, not written into the body of the effect.
+description: Timeouts, retries, logging, and spans should be attached with .pipe, not written into the body of the effect.
 ---
 
 ```ts

package/presets/effect/config/business-logic-depends-on-config-service.md

@@ -1,5 +1,5 @@
 ---
-description: Business logic depends on a config service. Config primitives are read only inside that service's layer.
+description: Business logic depends on a config service. Config primitives should be read only inside that service's layer.
 ---
 
 ```ts

package/presets/effect/config/secrets-are-redacted.md

@@ -1,5 +1,5 @@
 ---
-description: A token, password, or key is read with Config.redacted.
+description: A token, password, or key should be read with Config.redacted.
 ---
 
 ```ts

package/presets/effect/config/validate-with-schema.md

@@ -1,5 +1,5 @@
 ---
-description: A config value with constraints is read with Config.schema, not mapped and checked by hand.
+description: A config value with constraints should be read with Config.schema, not mapped and checked by hand.
 ---
 
 ```ts

package/presets/effect/data/brand-meaningful-primitives.md

@@ -1,5 +1,5 @@
 ---
-description: A primitive with semantic meaning, such as an id, email, URL, port, or count, is a branded schema.
+description: A primitive with semantic meaning, such as an id, email, URL, port, or count, should be a branded schema.
 ---
 
 ```ts

package/presets/effect/data/decode-json-with-schema.md

@@ -1,5 +1,5 @@
 ---
-description: JSON crossing a boundary is decoded with Schema.fromJsonString, not JSON.parse followed by a cast.
+description: JSON crossing a boundary should be decoded with Schema.fromJsonString, not JSON.parse followed by a cast.
 ---
 
 ```ts

package/presets/effect/data/records-are-schema-classes.md

@@ -1,5 +1,5 @@
 ---
-description: Domain records are defined with Schema.Class, not with a plain interface or type alias.
+description: Domain records should be defined with Schema.Class, not with a plain interface or type alias.
 ---
 
 ```ts

package/presets/effect/data/variants-are-tagged-unions.md

@@ -1,5 +1,5 @@
 ---
-description: Structured variants are Schema.TaggedClass in a Schema.Union and are matched with Match.tag and Match.exhaustive.
+description: Structured variants should be Schema.TaggedClass in a Schema.Union and matched with Match.tag and Match.exhaustive.
 ---
 
 ```ts

package/presets/effect/errors/catch-defects-at-boundaries-only.md

@@ -1,5 +1,5 @@
 ---
-description: Defects are caught only at a system boundary for logging or shutdown, never in business logic.
+description: Defects should be caught only at a system boundary for logging or shutdown, never in business logic.
 ---
 
 ```ts

package/presets/effect/errors/defects-for-bugs.md

@@ -1,5 +1,5 @@
 ---
-description: A typed error is for a failure the caller can handle. A bug or invariant violation is a defect.
+description: A typed error should be for a failure the caller can handle. A bug or invariant violation should be a defect.
 ---
 
 ```ts

package/presets/effect/errors/domain-errors-are-tagged.md

@@ -1,5 +1,5 @@
 ---
-description: A domain failure is a Schema.TaggedError with its own tag.
+description: A domain failure should be a Schema.TaggedError with its own tag.
 ---
 
 ```ts

package/presets/effect/errors/wrap-external-errors.md

@@ -1,5 +1,5 @@
 ---
-description: An error from an external library is wrapped in a tagged error with a Schema.Defect field, not passed through raw.
+description: An error from an external library should be wrapped in a tagged error with a Schema.Defect field, not passed through raw.
 ---
 
 ```ts

package/presets/effect/platform/os-access-through-platform-services.md

@@ -1,5 +1,5 @@
 ---
-description: File, path, process, terminal, and HTTP access goes through Effect's platform services (FileSystem, Path, ChildProcess, Terminal, HttpClient, KeyValueStore), acquired with yield*, not through node: builtins, Bun globals, or fetch. The Bun implementations are provided once at the entry point with BunServices.layer.
+description: File, path, process, terminal, and HTTP access goes through Effect's platform services (FileSystem, Path, ChildProcess, Terminal, HttpClient, KeyValueStore), acquired with yield*, not through node: builtins, Bun globals, or fetch. The Bun implementations should be provided once at the entry point with BunServices.layer.
 ---
 
 ```ts

package/presets/effect/services/fresh-layer-per-test.md

@@ -1,5 +1,5 @@
 ---
-description: Each it.effect provides its own layer. it.layer is used only to share an expensive resource across a suite.
+description: Each it.effect provides its own layer. it.layer should be used only to share an expensive resource across a suite.
 ---
 
 ```ts

package/presets/effect/services/memoize-parameterized-layers.md

@@ -1,5 +1,5 @@
 ---
-description: The result of a parameterized layer constructor is stored in a module constant before it is used in more than one place.
+description: The result of a parameterized layer constructor should be stored in a module constant before it is used in more than one place.
 ---
 
 ```ts

package/presets/effect/services/methods-have-no-requirements.md

@@ -1,5 +1,5 @@
 ---
-description: Service method signatures have no requirements. Dependencies are acquired inside the layer, not declared on the method.
+description: Service method signatures have no requirements. Dependencies should be acquired inside the layer, not declared on the method.
 ---
 
 ```ts

package/presets/effect/services/provide-at-entry.md

@@ -1,5 +1,5 @@
 ---
-description: Layers are provided once at the program entry. A module that is not an entry point does not call Effect.provide.
+description: Layers should be provided once at the program entry. A module that is not an entry point does not call Effect.provide.
 ---
 
 ```ts

package/presets/effect/services/test-layers-are-in-memory.md

@@ -1,5 +1,5 @@
 ---
-description: A test implementation of a service is built with Layer.sync or Layer.succeed over in-memory state.
+description: A test implementation of a service should be built with Layer.sync or Layer.succeed over in-memory state.
 ---
 
 ```ts

package/presets/effect/testing/test-clock-for-time.md

@@ -1,5 +1,5 @@
 ---
-description: A test that depends on time uses TestClock. Real sleeps and it.live are used only when real time is required.
+description: A test that depends on time uses TestClock. Real sleeps and it.live should be used only when real time is required.
 ---
 
 ```ts

package/skills/adhere/SKILL.md

@@ -103,7 +103,7 @@ precedence; in this org it comes from SOPS via `just shell`.
 ## 5. Run and calibrate
 
 ```sh
-adhere validate              # decodes the config and rules, checks contradictions
+adhere validate              # decodes the config and rules, asks Jev about contradictions
 adhere lint                  # or: adhere lint --preset effect
 adhere lint --threshold 0.9  # re-reads the cache, sends nothing
 ```

package/src/cli.ts

@@ -3,7 +3,20 @@ import { AuditCacheLive } from "#services/AuditCache.ts";
 import { Credentials, CredentialsLive, CredentialsUnavailable } from "#services/Credentials.ts";
 import { JevLive } from "#services/Jev.http.ts";
 import { SourceWalkerLive } from "#services/SourceWalker.ts";
-import { render, runAudit } from "#workflows/audit.ts";
+import {
+  type AuditPlan,
+  executeAudit,
+  type FileDone,
+  planAudit,
+  render,
+} from "#workflows/audit.ts";
+import {
+  describePlan,
+  type Progress,
+  progressAfter,
+  progressLine,
+  sendQuestion,
+} from "#workflows/format.ts";
 import type { Overrides } from "#config.ts";
 import { findContradictions, formatContradictions } from "#contradictions.ts";
 import { initProject } from "#init.ts";
@@ -12,6 +25,7 @@ import { globalRuleSet } from "#rules.ts";
 import {
   Console,
   Effect,
+  Exit,
   Layer,
   Option,
   Path,
@@ -54,6 +68,44 @@ const threshold = Flag.float("threshold").pipe(
   ),
 );
 
+const yes = Flag.boolean("yes").pipe(
+  Flag.withAlias("y"),
+  Flag.withDefault(false),
+  Flag.withDescription(
+    "Send the requests without asking first. lint only asks with a terminal on stdin and stdout.",
+  ),
+);
+
+class Cancelled extends Schema.TaggedError<Cancelled>()("Cancelled", {}) {
+  readonly [Runtime.errorReported] = false;
+}
+
+/** Text on stderr, beside the report on stdout. */
+const toStderr = (text: string) =>
+  Effect.sync(() => {
+    process.stderr.write(text);
+  });
+
+/**
+ * A counter on stderr, redrawn in place on a terminal as files finish. On
+ * anything else it stays quiet, so a log gets the plan and the report rather
+ * than a line per file. A failed run keeps its last count on screen.
+ */
+const counterFor = (plan: AuditPlan) => {
+  const live = process.stderr.isTTY === true;
+  let progress: Progress = { files: 0, requests: 0, findings: 0 };
+  const draw = () => (live ? toStderr(`\r\u001b[2K${progressLine(progress, plan)}`) : Effect.void);
+  return {
+    start: Effect.suspend(draw),
+    update: (done: FileDone) =>
+      Effect.suspend(() => {
+        progress = progressAfter(progress, done);
+        return draw();
+      }),
+    finish: (failed: boolean) => (live ? toStderr(failed ? "\n" : "\r\u001b[2K") : Effect.void),
+  };
+};
+
 const force = Flag.boolean("force").pipe(
   Flag.withDefault(false),
   Flag.withDescription("Overwrite existing scaffold files."),
@@ -70,10 +122,28 @@ export const auditLayer = (overrides: Overrides) =>
   ).pipe(Layer.provideMerge(AdhereConfigLive(overrides)));
 
 /** `adhere lint`: the audit. */
-export const lintCommand = Command.make("lint", { preset, threshold }, () =>
+export const lintCommand = Command.make("lint", { preset, threshold, yes }, (input) =>
   Effect.gen(function* () {
-    const result = yield* runAudit;
     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 }),
+      );
+      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))),
+    );
     const color = yield* stdio.stdoutIsTerminal;
     const path = yield* Path.Path;
     // One write: separate Console.log calls have interleaved out of order here.
@@ -94,16 +164,24 @@ export const lintCommand = Command.make("lint", { preset, threshold }, () =>
   ),
 );
 
+/** Jev, with the key `lint` uses, and the config it reads the model and threshold from. */
+export const validateLayer = (overrides: Overrides) =>
+  JevLive.pipe(
+    Layer.provide([FetchHttpClient.layer, CredentialsLive]),
+    Layer.provideMerge(AdhereConfigLive(overrides)),
+  );
+
 /**
- * `adhere validate`: everything `lint` loads, without Jev. A config, rule file,
- * or preset that does not decode refuses here the way it would refuse `lint`.
+ * `adhere validate`: everything `lint` loads, then Jev on whether any two rules
+ * that apply to the same files contradict. A config, rule file, or preset that
+ * does not decode refuses here the way it would refuse `lint`.
  */
 export const validateCommand = Command.make("validate", { preset }, () =>
   Effect.gen(function* () {
     const config = yield* AdhereConfig;
     const path = yield* Path.Path;
     const entries = config.scopedRules ?? globalRuleSet(config.rules, path.resolve());
-    const contradictions = findContradictions(entries);
+    const contradictions = yield* findContradictions(entries, config.threshold);
     const loaded = `${entries.length} ${entries.length === 1 ? "rule" : "rules"} loaded.`;
     yield* Console.log([loaded, formatContradictions(contradictions)].join("\n"));
     if (contradictions.length > 0) {
@@ -112,9 +190,9 @@ export const validateCommand = Command.make("validate", { preset }, () =>
   }),
 ).pipe(
   Command.withDescription(
-    "Load the config, rule files, and presets the way lint does, without calling Jev, and check the rules for contradictions.",
+    "Load the config, rule files, and presets the way lint does, then ask Jev whether any two rules that apply to the same files contradict each other.",
   ),
-  Command.provide((input) => AdhereConfigLive({ presets: chosenPresets(input.preset) })),
+  Command.provide((input) => validateLayer({ presets: chosenPresets(input.preset) })),
 );
 
 /** `adhere init`: the scaffold. */

package/src/contradictions.ts

@@ -1,19 +1,14 @@
 import type { RuleEntry } from "#rules.ts";
+import { Jev, type Pair } from "#services/Jev.ts";
+import { Effect } from "effect";
 
 export interface Contradiction {
   readonly first: RuleEntry;
   readonly second: RuleEntry;
-  readonly reason: string;
+  /** Jev's probability that no code can follow both rules. */
+  readonly probability: number;
 }
 
-type Polarity = "positive" | "negative";
-
-const NEGATIVE = /\b(?:avoid|do not|don't|must not|never|no|should not)\b/gi;
-const POSITIVE = /\b(?:always|must|prefer|require|requires|required|should|use)\b/gi;
-const NEGATIVE_WORD = /\b(?:avoid|do not|don't|must not|never|no|should not)\b/i;
-const POSITIVE_WORD = /\b(?:always|must|prefer|require|requires|required|should|use)\b/i;
-const FILLER = /\b(?:a|an|the|for|to|with|by|in|of)\b/gi;
-
 const normalized = (path: string): string => path.replaceAll("\\", "/");
 
 const scopesOverlap = (a: string, b: string): boolean => {
@@ -22,58 +17,57 @@ const scopesOverlap = (a: string, b: string): boolean => {
   return first === second || first.startsWith(`${second}/`) || second.startsWith(`${first}/`);
 };
 
-const polarityOf = (text: string): Polarity | undefined => {
-  if (NEGATIVE_WORD.test(text)) return "negative";
-  if (POSITIVE_WORD.test(text)) return "positive";
-  return undefined;
-};
-
-const topicOf = (text: string): string =>
-  text
-    .toLowerCase()
-    .replaceAll(NEGATIVE, " ")
-    .replaceAll(POSITIVE, " ")
-    .replaceAll(FILLER, " ")
-    .replace(/[^a-z0-9]+/g, " ")
-    .trim()
-    .replace(/\s+/g, " ");
+/**
+ * Per rule, the rules that apply to some of the same files. A rule with the
+ * same id is left out: a nested rule that shares an id shadows the other on
+ * purpose.
+ */
+const partnersOf = (entries: ReadonlyArray<RuleEntry>): ReadonlyArray<ReadonlyArray<number>> =>
+  entries.map((first, index) =>
+    entries.flatMap((second, other) =>
+      other !== index && first.id !== second.id && scopesOverlap(first.scope, second.scope)
+        ? [other]
+        : [],
+    ),
+  );
 
-const contradicts = (first: RuleEntry, second: RuleEntry): boolean => {
-  if (first.id === second.id) return false;
-  if (!scopesOverlap(first.scope, second.scope)) return false;
-  const firstPolarity = polarityOf(first.rule.description);
-  const secondPolarity = polarityOf(second.rule.description);
-  if (
-    firstPolarity === undefined ||
-    secondPolarity === undefined ||
-    firstPolarity === secondPolarity
-  ) {
-    return false;
+/** Each pair Jev named once, lower index first. */
+const distinctPairs = (named: ReadonlyArray<Pair>): ReadonlyArray<Pair> => {
+  const pairs = new Map<string, Pair>();
+  for (const [rule, partner] of named) {
+    const pair: Pair = rule < partner ? [rule, partner] : [partner, rule];
+    pairs.set(`${pair[0]}-${pair[1]}`, pair);
   }
-  const firstTopic = topicOf(first.rule.description);
-  const secondTopic = topicOf(second.rule.description);
-  return firstTopic.length > 0 && firstTopic === secondTopic;
+  return [...pairs.values()].sort((a, b) => a[0] - b[0] || a[1] - b[1]);
 };
 
-export const findContradictions = (
+/**
+ * Pairs of rules that apply to the same files and that Jev judges no code can
+ * follow both of, above `threshold`. Jev first names, per rule, which rule
+ * sharing its files it conflicts with, then gives each named pair a
+ * probability. Nothing is sent when no two rules share files, so such a run
+ * needs no API key.
+ */
+export const findContradictions = Effect.fn("findContradictions")(function* (
   entries: ReadonlyArray<RuleEntry>,
-): ReadonlyArray<Contradiction> => {
-  const contradictions: Array<Contradiction> = [];
-  for (let i = 0; i < entries.length; i++) {
-    const first = entries[i];
-    if (first === undefined) continue;
-    for (let j = i + 1; j < entries.length; j++) {
-      const second = entries[j];
-      if (second === undefined || !contradicts(first, second)) continue;
-      contradictions.push({
-        first,
-        second,
-        reason: "overlapping scopes contain opposite textual directives for the same topic",
-      });
-    }
-  }
-  return contradictions;
-};
+  threshold: number,
+) {
+  const none: ReadonlyArray<Contradiction> = [];
+  const partners = partnersOf(entries);
+  if (partners.every((some) => some.length === 0)) return none;
+  const jev = yield* Jev;
+  const pairs = distinctPairs(yield* jev.conflicts(entries, partners));
+  if (pairs.length === 0) return none;
+  const probabilities = yield* jev.contradicts(entries, pairs);
+  return pairs.flatMap(([first, second], index): ReadonlyArray<Contradiction> => {
+    const one = entries[first];
+    const other = entries[second];
+    const probability = probabilities[index] ?? 0;
+    return one !== undefined && other !== undefined && probability > threshold
+      ? [{ first: one, second: other, probability }]
+      : [];
+  });
+});
 
 const locationOf = (entry: RuleEntry): string => `${entry.id} (${entry.file ?? entry.scope})`;
 
@@ -87,7 +81,7 @@ export const formatContradictions = (contradictions: ReadonlyArray<Contradiction
     } among configured rules:`,
     "",
     ...contradictions.flatMap((contradiction, index) => [
-      `${index + 1}. ${contradiction.reason}`,
+      `${index + 1}. No code can follow both (${contradiction.probability.toFixed(2)}):`,
       `   - ${locationOf(contradiction.first)}`,
       `     ${contradiction.first.rule.description}`,
       `   - ${locationOf(contradiction.second)}`,