@drkmttr/adhere 0.4.0 → 0.5.0

package/README.md

@@ -23,15 +23,16 @@ and run `npx adhere`. To try it without installing, run
 Windows on x64. It needs Node to start, and no Bun.
 
 adhere sends each file it judges to Jev at `api.typesafe.ai`, authenticated
-with a TypeSafe AI API key in `TYPESAFE_API_KEY`.
+with a TypeSafe AI API key: the one `adhere login` saved, or
+`TYPESAFE_API_KEY` when it is set.
 
 ## Quick start
 
 ```sh
 adhere init                          # .adhere/config.ts and two example rules
-adhere validate                      # check the config and rules, without Jev
 echo ".adhere/cache/" >> .gitignore
-export TYPESAFE_API_KEY=...
+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
 ```
 
@@ -55,10 +56,11 @@ Found 1 error.
 
 The header is the rule id, Jev's probability, and the rule's description. The
 hint is the rule's reference; a rule with only code to avoid shows that code,
-labeled `avoid:`, instead. The exit code is 0 when nothing is reported and 1
-when something is. It is also 1 when the run refuses, for example on an invalid
-config or rule file, a missing `TYPESAFE_API_KEY`, or an unknown command or
-flag; a refusal prints its reason.
+labeled `avoid:`, instead. On a terminal, the report is in color and the code
+in it is highlighted. The exit code is 0 when nothing is reported and 1 when
+something is. It is also 1 when the run refuses, for example on an invalid
+config or rule file, a missing API key, or an unknown command or flag; a
+refusal prints its reason.
 
 ## Usage
 
@@ -66,8 +68,10 @@ flag; a 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 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
 adhere skill                   # print the agent skill (below)
 ```
 
@@ -95,13 +99,26 @@ 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` 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.
 
 ## Config
 
@@ -258,8 +275,8 @@ only that rule. 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.
 
-`TYPESAFE_API_KEY` is read only when a request is about to be sent. A run
-where every file is cached needs no key and no network.
+The API key is read only when a request is about to be sent. A run where
+every file is cached needs no key and no network.
 
 ## Agent skill
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@drkmttr/adhere",
-  "version": "0.4.0",
+  "version": "0.5.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.0",
-    "@drkmttr/adhere-darwin-x64": "0.4.0",
-    "@drkmttr/adhere-linux-arm64": "0.4.0",
-    "@drkmttr/adhere-linux-x64": "0.4.0",
-    "@drkmttr/adhere-win32-x64": "0.4.0"
+    "@drkmttr/adhere-darwin-arm64": "0.5.0",
+    "@drkmttr/adhere-darwin-x64": "0.5.0",
+    "@drkmttr/adhere-linux-arm64": "0.5.0",
+    "@drkmttr/adhere-linux-x64": "0.5.0",
+    "@drkmttr/adhere-win32-x64": "0.5.0"
   }
 }

package/skills/adhere/SKILL.md

@@ -96,13 +96,14 @@ export default {
 } satisfies Config;
 ```
 
-Add `.adhere/cache/` to `.gitignore`. `TYPESAFE_API_KEY` must be set for
-uncached files; in this org it comes from SOPS via `just shell`.
+Add `.adhere/cache/` to `.gitignore`. Uncached files need a TypeSafe AI API
+key: one saved by `adhere login`, or `TYPESAFE_API_KEY`, which takes
+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

@@ -1,5 +1,6 @@
 import { AdhereConfig, AdhereConfigLive } from "#services/AdhereConfig.ts";
 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";
@@ -14,11 +15,13 @@ import {
   Layer,
   Option,
   Path,
+  Redacted,
   Runtime,
   Schema,
   Stdio,
+  Stream,
 } from "effect";
-import { Command, Flag } from "effect/unstable/cli";
+import { Command, Flag, Prompt } from "effect/unstable/cli";
 import { FetchHttpClient } from "effect/unstable/http";
 // A Bun text import (https://bun.sh/docs/bundler/loaders#text): the file's
 // contents become a string at bundle time, so the compiled binary carries the
@@ -63,7 +66,7 @@ export const auditLayer = (overrides: Overrides) =>
   Layer.mergeAll(
     SourceWalkerLive,
     AuditCacheLive,
-    JevLive.pipe(Layer.provide(FetchHttpClient.layer)),
+    JevLive.pipe(Layer.provide([FetchHttpClient.layer, CredentialsLive])),
   ).pipe(Layer.provideMerge(AdhereConfigLive(overrides)));
 
 /** `adhere lint`: the audit. */
@@ -91,16 +94,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) {
@@ -109,9 +120,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. */
@@ -127,6 +138,63 @@ export const initCommand = Command.make("init", { force }, (input) =>
   }),
 ).pipe(Command.withDescription("Scaffold .adhere/config.ts and example Markdown rules."));
 
+/**
+ * The key typed at a masked prompt, or piped in: `adhere login < key.txt`.
+ * Whitespace around it, like the newline a pipe ends with, is dropped.
+ */
+const readApiKey = Effect.fn("login.readApiKey")(function* () {
+  const stdio = yield* Stdio.Stdio;
+  const typed: string = (yield* stdio.stdinIsTerminal)
+    ? Redacted.value(yield* Prompt.run(Prompt.password({ message: "TypeSafe AI API key" })))
+    : yield* stdio.stdin.pipe(
+        Stream.decodeText(),
+        Stream.mkString,
+        Effect.mapError((problem) =>
+          CredentialsUnavailable.make({
+            message: `Cannot read the key from stdin: ${problem.message}`,
+          }),
+        ),
+      );
+  const key = typed.trim();
+  if (key.length === 0) {
+    return yield* CredentialsUnavailable.make({
+      message: "No API key given: type it at the prompt, or pipe it in.",
+    });
+  }
+  return Redacted.make(key);
+});
+
+/** `adhere login`: save the API key, so a run needs no TYPESAFE_API_KEY. */
+export const loginCommand = Command.make("login", {}, () =>
+  Effect.gen(function* () {
+    const credentials = yield* Credentials;
+    yield* credentials.save(yield* readApiKey());
+    yield* Console.log(`Saved the API key to ${yield* credentials.file}.`);
+  }),
+).pipe(
+  Command.withDescription(
+    "Save a TypeSafe AI API key in ~/.config/adhere ($XDG_CONFIG_HOME/adhere when set), readable only by you, so lint runs without TYPESAFE_API_KEY. Prompts for the key, or reads it from stdin when piped.",
+  ),
+  Command.provide(CredentialsLive),
+);
+
+/** `adhere logout`: delete the saved API key. */
+export const logoutCommand = Command.make("logout", {}, () =>
+  Effect.gen(function* () {
+    const credentials = yield* Credentials;
+    const file = yield* credentials.file;
+    const removed = yield* credentials.remove;
+    yield* Console.log(
+      removed ? `Deleted the API key saved in ${file}.` : `No API key is saved in ${file}.`,
+    );
+  }),
+).pipe(
+  Command.withDescription(
+    "Delete the API key adhere login saved. TYPESAFE_API_KEY, when set, still applies.",
+  ),
+  Command.provide(CredentialsLive),
+);
+
 /** `adhere skill`: the agent skill for writing rules, as shipped in the binary. */
 export const skillCommand = Command.make("skill", {}, () => Console.log(skill.trimEnd())).pipe(
   Command.withDescription(
@@ -140,11 +208,19 @@ export const cli = Command.make("adhere").pipe(
   Command.withExamples([
     { command: "adhere init", description: "Scaffold .adhere/config.ts and two example rules" },
     { command: "adhere validate", description: "Check the config and rules without calling Jev" },
+    { command: "adhere login", description: "Save your TypeSafe AI API key for later runs" },
     { command: "adhere lint", description: "Audit the working directory" },
     {
       command: "adhere lint --preset effect",
       description: "Audit against the built-in Effect rules",
     },
   ]),
-  Command.withSubcommands([lintCommand, validateCommand, initCommand, skillCommand]),
+  Command.withSubcommands([
+    lintCommand,
+    validateCommand,
+    initCommand,
+    loginCommand,
+    logoutCommand,
+    skillCommand,
+  ]),
 );

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)}`,

package/src/highlight.ts

@@ -0,0 +1,106 @@
+/**
+ * TypeScript split into the token classes a reader scans for: comments,
+ * strings, constants, keywords, and type names. A tokenizer, not a parser: a
+ * token it cannot classify has no kind, and the tokens' text joins back into
+ * the input exactly.
+ */
+export type Kind = "comment" | "string" | "constant" | "keyword" | "type";
+
+export interface Token {
+  readonly text: string;
+  readonly kind?: Kind;
+}
+
+const words = (list: string): ReadonlySet<string> => new Set(list.split(" "));
+
+const KEYWORDS = words(
+  "abstract as async await break case catch class const continue declare default delete do " +
+    "else enum export extends finally for from function get if implements import in infer " +
+    "instanceof interface is keyof let namespace new of private protected public readonly " +
+    "return satisfies set static super switch this throw try type typeof var void while yield",
+);
+const CONSTANTS = words("true false null undefined");
+const PRIMITIVES = words("any bigint boolean never number object string symbol unknown");
+/** Keywords that keep their color before a colon: `default:`, `a ? this : b`. */
+const NOT_KEYS = words("default super this");
+
+/** The groups that name their token's kind. */
+const CLASSES = ["comment", "string", "constant"] as const;
+
+/** One group per token class, tried in order at each position. */
+const TOKEN = new RegExp(
+  [
+    /(?<comment>\/\/[^\n]*|\/\*[\s\S]*?(?:\*\/|$))/,
+    /(?<string>"(?:[^"\\\n]|\\.)*"?|'(?:[^'\\\n]|\\.)*'?|`(?:[^`\\]|\\[\s\S])*`?)/,
+    /(?<constant>0[box][\da-f_]+n?|\d[\d_]*(?:\.\d[\d_]*)?(?:e[+-]?\d+)?n?)/,
+    /(?<word>[a-z_$][\w$]*)/,
+    /(?<space>\s+)/,
+    // Anything else, a run at a time; `/` alone, since it can start a comment.
+    /(?<punctuation>[^\w\s$"'`/]+|\/)/,
+  ]
+    .map((group) => group.source)
+    .join("|"),
+  "iy",
+);
+/** A regex literal, tried only where an expression can start: `a / b` divides. */
+const REGEX = /\/(?![*/])(?:[^/\\\n[]|\\.|\[(?:[^\]\\\n]|\\.)*\])+\/[a-z]*/y;
+/** What follows a property name: `type: "noul"`, `get?: X`. */
+const KEY = /\s*\??:(?!:)/y;
+/** `Schema`, `HttpClient`, `A`; not `URL` or `MAX_LINES`. */
+const TYPE_NAME = /^[A-Z]$|^[A-Z][\w$]*[a-z]/;
+
+const matchAt = (pattern: RegExp, code: string, at: number): RegExpExecArray | null => {
+  pattern.lastIndex = at;
+  return pattern.exec(code);
+};
+
+/** After a name, a literal, or a closing bracket, `/` divides. */
+const regexMayStart = (previous: string | undefined): boolean =>
+  previous === undefined ||
+  (KEYWORDS.has(previous) && previous !== "this" && previous !== "super") ||
+  /[^\w$)\]}"'`]$/.test(previous);
+
+/**
+ * A word after `.` or before `:` names a property, so `cache.get` and
+ * `{ type: "noul" }` are not keywords.
+ */
+const kindOf = (word: string, previous: string | undefined, isKey: boolean): Kind | undefined => {
+  if (TYPE_NAME.test(word)) return "type";
+  if (CONSTANTS.has(word)) return "constant";
+  if (previous?.endsWith(".") === true || (isKey && !NOT_KEYS.has(word))) return undefined;
+  return KEYWORDS.has(word) ? "keyword" : PRIMITIVES.has(word) ? "type" : undefined;
+};
+
+/**
+ * The code's lines, each as tokens. A token that crosses a newline, like a
+ * block comment or a template literal, is cut into one token per line.
+ */
+export const tokenize = (code: string): ReadonlyArray<ReadonlyArray<Token>> => {
+  const lines: Array<Array<Token>> = [[]];
+  // The last token that was not whitespace or a comment.
+  let previous: string | undefined;
+  let at = 0;
+  while (at < code.length) {
+    const regex = regexMayStart(previous) ? matchAt(REGEX, code, at) : null;
+    const match = regex ?? matchAt(TOKEN, code, at);
+    // `punctuation` matches any character the other groups do not.
+    if (match === null) break;
+    const text = match[0];
+    const groups = match.groups ?? {};
+    const kind: Kind | undefined =
+      regex !== null
+        ? "string"
+        : groups.word !== undefined
+          ? kindOf(groups.word, previous, matchAt(KEY, code, at + text.length) !== null)
+          : CLASSES.find((name) => groups[name] !== undefined);
+    for (const [index, piece] of text.split("\n").entries()) {
+      if (index > 0) lines.push([]);
+      if (piece.length > 0) {
+        lines.at(-1)?.push(kind === undefined ? { text: piece } : { text: piece, kind });
+      }
+    }
+    if (groups.comment === undefined && groups.space === undefined) previous = text;
+    at += text.length;
+  }
+  return lines;
+};

package/src/services/Credentials.ts

@@ -0,0 +1,123 @@
+import { Config, Context, Effect, FileSystem, Layer, Option, Path, Redacted, Schema } from "effect";
+
+/** No key to send, or the saved key cannot be read or written. */
+export class CredentialsUnavailable extends Schema.TaggedError<CredentialsUnavailable>()(
+  "CredentialsUnavailable",
+  { message: Schema.String },
+) {}
+
+/** A TypeSafe AI API key is one word: a space or a second line is a bad paste. */
+const ApiKey = Schema.String.pipe(Schema.check(Schema.isPattern(/^\S+$/)));
+
+/** What `adhere login` saves. */
+class SavedCredentials extends Schema.Class<SavedCredentials>("SavedCredentials")({
+  apiKey: Schema.RedactedFromValue(ApiKey),
+}) {}
+
+const SavedCredentialsJson = Schema.fromJsonString(SavedCredentials);
+
+/** The TypeSafe AI API key: where a request gets it, and where `adhere login` keeps it. */
+export class Credentials extends Context.Service<
+  Credentials,
+  {
+    /** `TYPESAFE_API_KEY` when it is set, otherwise the key `adhere login` saved. */
+    readonly apiKey: Effect.Effect<Redacted.Redacted<string>, CredentialsUnavailable>;
+    /** Where the saved key lives, whether or not there is one. */
+    readonly file: Effect.Effect<string, CredentialsUnavailable>;
+    /** Saves a key for later runs, readable only by the user. */
+    readonly save: (
+      apiKey: Redacted.Redacted<string>,
+    ) => Effect.Effect<void, CredentialsUnavailable>;
+    /** Deletes the saved key. False when there was none. */
+    readonly remove: Effect.Effect<boolean, CredentialsUnavailable>;
+  }
+>()("@drkmttr/adhere/services/Credentials") {}
+
+const refused = (message: string) => CredentialsUnavailable.make({ message });
+
+/**
+ * The key lives in `$XDG_CONFIG_HOME/adhere/credentials.json`, or under
+ * `~/.config` without it, on every platform. The file is written whole to a
+ * temporary file created readable only by the user, then renamed over the
+ * old one, so no reader sees half a key or a key with looser permissions.
+ */
+export const CredentialsLive = Layer.effect(Credentials)(
+  Effect.gen(function* () {
+    const fs = yield* FileSystem.FileSystem;
+    const path = yield* Path.Path;
+
+    const file = Config.nonEmptyString("XDG_CONFIG_HOME").pipe(
+      Config.orElse(() =>
+        Config.nonEmptyString("HOME").pipe(
+          Config.orElse(() => Config.nonEmptyString("USERPROFILE")),
+          Config.map((home) => path.join(home, ".config")),
+        ),
+      ),
+      Config.map((configHome) => path.join(configHome, "adhere", "credentials.json")),
+      Effect.mapError(() =>
+        refused("No home directory to keep the API key in: set HOME or XDG_CONFIG_HOME."),
+      ),
+    );
+
+    const exists = (target: string) =>
+      fs
+        .exists(target)
+        .pipe(Effect.mapError((problem) => refused(`Cannot read ${target}: ${problem.message}`)));
+
+    const readSaved = Effect.fn("Credentials.readSaved")(function* (target: string) {
+      const text = yield* fs
+        .readFileString(target)
+        .pipe(Effect.mapError((problem) => refused(`Cannot read ${target}: ${problem.message}`)));
+      const saved = yield* Schema.decodeUnknownEffect(SavedCredentialsJson)(text).pipe(
+        Effect.mapError(() =>
+          refused(`${target} holds no API key. Run \`adhere login\` to save one again.`),
+        ),
+      );
+      return saved.apiKey;
+    });
+
+    // 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(
+        Effect.mapError((problem) => refused(`Cannot read TYPESAFE_API_KEY: ${problem.message}`)),
+      );
+      if (Option.isSome(fromEnvironment)) return fromEnvironment.value;
+      const target = yield* file;
+      if (!(yield* exists(target))) {
+        return yield* refused(
+          "No TypeSafe AI API key. Run `adhere login` to save one, or set TYPESAFE_API_KEY.",
+        );
+      }
+      return yield* readSaved(target);
+    });
+
+    const save = Effect.fn("Credentials.save")(function* (key: Redacted.Redacted<string>) {
+      const saved = yield* Schema.decodeUnknownEffect(SavedCredentials)({
+        apiKey: Redacted.value(key),
+      }).pipe(
+        Effect.mapError(() => refused("An API key is one word, with no spaces or line breaks.")),
+      );
+      const json = yield* Schema.encodeEffect(SavedCredentialsJson)(saved).pipe(Effect.orDie);
+      const target = yield* file;
+      const temporary = `${target}.tmp`;
+      yield* Effect.gen(function* () {
+        yield* fs.makeDirectory(path.dirname(target), { recursive: true, mode: 0o700 });
+        // A mode applies only when a file is created: never reuse a leftover.
+        yield* fs.remove(temporary, { force: true });
+        yield* fs.writeFileString(temporary, `${json}\n`, { mode: 0o600 });
+        yield* fs.rename(temporary, target);
+      }).pipe(Effect.mapError((problem) => refused(`Cannot save ${target}: ${problem.message}`)));
+    });
+
+    const remove = Effect.fn("Credentials.remove")(function* () {
+      const target = yield* file;
+      if (!(yield* exists(target))) return false;
+      yield* fs
+        .remove(target)
+        .pipe(Effect.mapError((problem) => refused(`Cannot delete ${target}: ${problem.message}`)));
+      return true;
+    });
+
+    return Credentials.of({ apiKey: apiKey(), file, save, remove: remove() });
+  }),
+);

package/src/services/Jev.http.ts

@@ -1,15 +1,22 @@
 import { AdhereConfig } from "#services/AdhereConfig.ts";
+import { Credentials } from "#services/Credentials.ts";
 import {
   blockBody,
+  type ComparedRule,
+  conflictBody,
+  contradictBody,
   Jev,
   JevUnavailable,
   judgeBody,
   type Lines,
   locateBody,
+  namedPairs,
   needsBlocks,
+  type Pair,
+  pairProbability,
   type Rules,
 } from "#services/Jev.ts";
-import { Config, Effect, Layer, Record, Schedule, Schema } from "effect";
+import { Effect, Layer, Record, Schedule, Schema } from "effect";
 import { HttpClient, HttpClientResponse } from "effect/unstable/http";
 import * as HttpClientRequest from "effect/unstable/http/HttpClientRequest";
 
@@ -27,6 +34,7 @@ const refused = (message: string) => JevUnavailable.make({ message });
 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,
       HttpClient.transformResponse(Effect.timeout("30 seconds")),
@@ -39,8 +47,8 @@ export const JevLive = Layer.effect(Jev)(
     const ask = <A>(body: unknown, Answers: Schema.Codec<A, unknown, never, never>) =>
       Effect.gen(function* () {
         // Read here, not in the layer: a run with nothing pending needs no key.
-        const apiKey = yield* Config.redacted("TYPESAFE_API_KEY").pipe(
-          Effect.mapError((problem) => refused(`Cannot read TYPESAFE_API_KEY: ${problem.message}`)),
+        const apiKey = yield* credentials.apiKey.pipe(
+          Effect.mapError((problem) => refused(problem.message)),
         );
         const request = yield* HttpClientRequest.bodyJson(
           HttpClientRequest.post(SYSTEM_ONE),
@@ -74,6 +82,28 @@ export const JevLive = Layer.effect(Jev)(
       return chosen(answers);
     });
 
-    return Jev.of({ judge, locate });
+    const conflicts = Effect.fn("Jev.conflicts")(function* (
+      rules: ReadonlyArray<ComparedRule>,
+      partners: ReadonlyArray<ReadonlyArray<number>>,
+    ) {
+      const { answers } = yield* ask(conflictBody(config.model, rules, partners), ChoiceAnswers);
+      return namedPairs(answers, partners);
+    });
+
+    const contradicts = Effect.fn("Jev.contradicts")(function* (
+      rules: ReadonlyArray<ComparedRule>,
+      pairs: ReadonlyArray<Pair>,
+    ) {
+      return yield* Effect.forEach(
+        pairs,
+        (pair) =>
+          Effect.map(ask(contradictBody(config.model, rules, pair), NoulAnswers), ({ answers }) =>
+            pairProbability(answers, pair),
+          ),
+        { concurrency: 8 },
+      );
+    });
+
+    return Jev.of({ judge, locate, conflicts, contradicts });
   }),
 );

package/src/services/Jev.ts

@@ -19,9 +19,35 @@ export class Jev extends Context.Service<
       lines: Lines,
       rules: Rules,
     ) => Effect.Effect<Record<RuleId, number>, JevUnavailable>;
+    /**
+     * 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
+     * left out.
+     */
+    readonly conflicts: (
+      rules: ReadonlyArray<ComparedRule>,
+      partners: ReadonlyArray<ReadonlyArray<number>>,
+    ) => Effect.Effect<ReadonlyArray<Pair>, JevUnavailable>;
+    /**
+     * Per pair, in order, Jev's probability that no code can follow both rules,
+     * each pair asked on its own.
+     */
+    readonly contradicts: (
+      rules: ReadonlyArray<ComparedRule>,
+      pairs: ReadonlyArray<Pair>,
+    ) => Effect.Effect<ReadonlyArray<number>, JevUnavailable>;
   }
 >()("@drkmttr/adhere/services/Jev") {}
 
+/** A rule compared with other rules rather than with a file. */
+export interface ComparedRule {
+  readonly id: RuleId;
+  readonly rule: Rule;
+}
+
+/** Two rules, as indexes into the rules being compared. */
+export type Pair = readonly [number, number];
+
 /** A `choice` question accepts at most this many criteria. */
 const CHOICE_LIMIT = 255;
 const LINES_PER_BLOCK = 20;
@@ -34,15 +60,33 @@ const isBlank = (line: string): boolean => line.trim().length === 0;
 export const needsBlocks = (lines: Lines): boolean =>
   lines.filter((line) => !isBlank(line)).length > CHOICE_LIMIT;
 
+/** A rule's text as Jev reads it. Code a rule lacks is left out, not sent empty. */
+const ruleState = ({ description, reference, avoid }: Rule) => ({
+  description,
+  ...(reference === undefined ? {} : { reference }),
+  ...(avoid === undefined ? {} : { avoid }),
+});
+
 const stateOf = (lines: Lines, rules: Rules) => ({
   code: lines.map((line, index) => `${index + 1} | ${line}`).join("\n"),
-  rules: Record.map(rules, ({ description, reference, avoid }) => ({
-    description,
-    ...(reference === undefined ? {} : { reference }),
-    ...(avoid === undefined ? {} : { avoid }),
-  })),
+  rules: Record.map(rules, (rule) => ruleState(rule)),
 });
 
+/**
+ * The compared rules a question mentions, keyed by index: ids alone would
+ * collide, since a nested rule can share its id with the rule it shadows.
+ */
+const comparedState = (rules: ReadonlyArray<ComparedRule>, mentioned: Iterable<number>) => {
+  const state: Record<string, { readonly id: RuleId } & ReturnType<typeof ruleState>> = {};
+  for (const index of [...new Set(mentioned)].sort((a, b) => a - b)) {
+    const compared = rules[index];
+    if (compared !== undefined) {
+      state[String(index)] = { id: compared.id, ...ruleState(compared.rule) };
+    }
+  }
+  return { rules: state };
+};
+
 const field = (id: RuleId, key: "avoid" | "description" | "reference") =>
   `state.rules["${id}"].${key}`;
 
@@ -123,3 +167,83 @@ export const blockBody = (model: string, lines: Lines, rules: Rules) => {
     })),
   };
 };
+
+/** A choice keeps one criterion for "none", which leaves this many for partners. */
+const PARTNERS_PER_QUESTION = CHOICE_LIMIT - 1;
+
+interface ChoiceQuestion {
+  readonly type: "choice";
+  readonly instructions: string;
+  readonly criteria: Record<string, string>;
+}
+
+/**
+ * Per rule, one `choice` among the rules that apply to the same files: which
+ * of them cannot be followed in the same code, or none. The questions grow
+ * with the rules, not with every pair of them. A rule with more partners than
+ * a choice holds gets one question per chunk, keyed `rule:chunk`.
+ */
+export const conflictBody = (
+  model: string,
+  rules: ReadonlyArray<ComparedRule>,
+  partners: ReadonlyArray<ReadonlyArray<number>>,
+) => {
+  const questions: Record<string, ChoiceQuestion> = {};
+  const mentioned: Array<number> = [];
+  partners.forEach((some, index) => {
+    for (let chunk = 0; chunk * PARTNERS_PER_QUESTION < some.length; chunk++) {
+      const from = chunk * PARTNERS_PER_QUESTION;
+      const offered = some.slice(from, from + PARTNERS_PER_QUESTION);
+      const criteria: Record<string, string> = { none: "None of them" };
+      for (const partner of offered) {
+        criteria[String(partner)] = rules[partner]?.rule.description ?? "";
+      }
+      mentioned.push(index, ...offered);
+      questions[`${index}:${chunk}`] = {
+        type: "choice",
+        instructions: `Each choice other than none is the rule in state.rules under its key. Which of them demands the opposite of what state.rules["${index}"] demands of the same code, so that following one breaks the other? Choose none if code can follow each of them alongside it.`,
+        criteria,
+      };
+    }
+  });
+  return { model, state: comparedState(rules, mentioned), questions };
+};
+
+const pairKey = ([first, second]: Pair): string => `${first}-${second}`;
+
+/**
+ * A `noul` for one pair Jev named: do the two rules demand opposite things of
+ * the same code? One pair per request, with only its two rules in the state.
+ * Other rules beside them dilute the judgment: over the effect preset, a real
+ * contradiction scored 0.89 alone and 0.59 among the other named pairs.
+ */
+export const contradictBody = (model: string, rules: ReadonlyArray<ComparedRule>, pair: Pair) => ({
+  model,
+  state: comparedState(rules, pair),
+  questions: {
+    [pairKey(pair)]: {
+      type: "noul" as const,
+      instructions: `Do state.rules["${pair[0]}"] and state.rules["${pair[1]}"] demand opposite things of the same code, so that following one breaks the other? Answer no if code can follow both, or if they are about different things.`,
+    },
+  },
+});
+
+/**
+ * The pairs a conflict answer names: per question, the partner Jev chose, when
+ * it was one the question offered. "none", or a stray answer, names no pair.
+ */
+export const namedPairs = (
+  answers: Readonly<Record<string, { readonly choice: string }>>,
+  partners: ReadonlyArray<ReadonlyArray<number>>,
+): ReadonlyArray<Pair> =>
+  Object.entries(answers).flatMap(([key, { choice }]): ReadonlyArray<Pair> => {
+    const rule = Number(key.split(":")[0]);
+    const partner = Number(choice);
+    return partners[rule]?.includes(partner) === true ? [[rule, partner]] : [];
+  });
+
+/** The probability a contradiction answer gives its pair; 0 when it gives none. */
+export const pairProbability = (
+  answers: Readonly<Record<string, { readonly noul: number }>>,
+  pair: Pair,
+): number => answers[pairKey(pair)]?.noul ?? 0;

package/src/workflows/format.ts

@@ -1,83 +1,145 @@
+import { type Kind, tokenize } from "#highlight.ts";
 import type { AuditResult, Finding } from "#workflows/audit.ts";
 
-const displayPath = (file: string, root: string | undefined): string =>
-  root !== undefined && file.startsWith(`${root}/`) ? file.slice(root.length + 1) : file;
+/**
+ * The report as data: lines of spans, each span a part of the frame or a
+ * 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;
 
-const counted = (count: number, one: string, many: string): string =>
-  `${count} ${count === 1 ? one : many}`;
+interface Span {
+  readonly text: string;
+  readonly role?: Role;
+}
 
-/** Foreground color. `38;5;N` is a palette index, `38;2;R;G;B` is truecolor. A trailing `;1` is bold. */
-const paint = (code: string, text: string, enabled: boolean): string =>
-  enabled ? `\u001b[${code}m${text}\u001b[0m` : text;
+type Line = ReadonlyArray<Span>;
 
-const red = (text: string, enabled: boolean) => paint("38;2;219;91;81;1", text, enabled);
-const blue = (text: string, enabled: boolean) => paint("38;2;5;125;160;1", text, enabled);
-const dim = (text: string, enabled: boolean) => paint("2", text, enabled);
-const pink = (text: string, enabled: boolean) => paint("38;2;255;0;175", text, enabled);
-const helpTint = (text: string, enabled: boolean) => paint("38;2;180;105;245", text, enabled);
+/**
+ * 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.
+ */
+const THEME: Readonly<Record<Role, string>> = {
+  error: "38;2;219;91;81;1",
+  path: "38;2;5;125;160;1",
+  lineNumber: "2",
+  underline: "38;2;255;0;175",
+  label: "38;2;180;105;245",
+  comment: "2",
+  string: "32",
+  constant: "33",
+  keyword: "34",
+  type: "36",
+};
 
-export interface RenderOptions {
-  /** Color the frame the way `vp lint` does on a terminal. */
-  readonly color?: boolean;
-  readonly root?: string;
-}
+const span = (text: string, role?: Role): Span => (role === undefined ? { text } : { text, role });
+
+const isBlank = (line: Line): boolean => line.every((part) => part.text.trim().length === 0);
+
+/** A line as text, colored by role on a terminal. Whitespace has no color to show. */
+const serialize = (line: Line, color: boolean): string =>
+  line
+    .map(({ text, role }) =>
+      color && role !== undefined && text.trim().length > 0
+        ? `\u001b[${THEME[role]}m${text}\u001b[0m`
+        : text,
+    )
+    .join("");
+
+/** The label, then the first line; the other lines indented to line up under it. */
+const hanging = (label: Span, lines: ReadonlyArray<Line>): ReadonlyArray<Line> => {
+  const [first = [], ...rest] = lines;
+  const indent = span(" ".repeat(label.text.length));
+  return [[label, ...first], ...rest.map((line) => (isBlank(line) ? [] : [indent, ...line]))];
+};
 
-const isBlank = (line: string): boolean => line.trim().length === 0;
+/** Code as lines of spans, each token in the role of its kind. */
+const highlighted = (code: string): ReadonlyArray<Line> =>
+  tokenize(code).map((tokens) => tokens.map(({ text, kind }) => span(text, kind)));
 
-const codeLines = (code: string): ReadonlyArray<string> => {
-  const lines = code.split("\n");
+/** Code as highlighted lines, without the blank lines at either end. */
+const codeLines = (code: string): ReadonlyArray<Line> => {
+  const lines = highlighted(code);
   const first = lines.findIndex((line) => !isBlank(line));
-  if (first < 0) return [];
-  let last = lines.length - 1;
-  while (last > first && isBlank(lines[last] ?? "")) last--;
-  return lines.slice(first, last + 1);
+  const last = lines.findLastIndex((line) => !isBlank(line));
+  return first < 0 ? [] : lines.slice(first, last + 1);
 };
 
-/**
- * One diagnostic, in the frame `vp lint` prints on a terminal: a red header,
- * the offending line, a pink underline, and the reference code as the hint.
- * A rule without a reference shows its code to avoid instead, labeled so.
- */
-const frame = (finding: Finding, options: RenderOptions): ReadonlyArray<string> => {
-  const color = options.color === true;
-  const digits = String(finding.line);
-  const gutter = " ".repeat(digits.length + 2);
-  const [label, code] =
-    finding.reference === undefined ? ["avoid", finding.avoid ?? ""] : ["hint", finding.reference];
-  const prefix = `  ${label}: `;
-  const [hint = "", ...rest] = codeLines(code);
-  const header = `${finding.rule} (${finding.probability.toFixed(2)})`;
+const displayPath = (file: string, root: string | undefined): string =>
+  root !== undefined && file.startsWith(`${root}/`) ? file.slice(root.length + 1) : file;
+
+const counted = (count: number, one: string, many: string): string =>
+  `${count} ${count === 1 ? one : many}`;
+
+const header = (finding: Finding): Line => [
+  span("  "),
+  span("×", "error"),
+  span(" "),
+  span(`${finding.rule} (${finding.probability.toFixed(2)})`, "error"),
+  span(": "),
+  span(finding.description, "error"),
+];
+
+/** The path, the offending line numbered in the gutter, and an underline as long as the line. */
+const excerpt = (finding: Finding, root: string | undefined): ReadonlyArray<Line> => {
+  const number = String(finding.line);
+  const gutter = span(" ".repeat(number.length + 2));
+  // A snippet is one line: `snippetOf` trims it out of the file.
+  const [code = []] = highlighted(finding.snippet);
+  const underline = "─".repeat(Math.max(1, finding.snippet.trim().length));
   return [
-    `  ${red("×", color)} ${red(header, color)}: ${red(finding.description, color)}`,
-    `${gutter}╭─[${blue(displayPath(finding.file, options.root), color)}:${finding.line}:1]`,
-    ` ${dim(digits, color)} │ ${finding.snippet}`,
-    `${gutter}· ${pink("─".repeat(Math.max(1, finding.snippet.trim().length)), color)}`,
-    `${gutter}╰────`,
-    `${helpTint(prefix, color)}${hint}`,
-    ...rest.map((line) => (isBlank(line) ? "" : `${" ".repeat(prefix.length)}${line}`)),
+    [gutter, span("╭─["), span(displayPath(finding.file, root), "path"), span(`:${number}:1]`)],
+    [span(" "), span(number, "lineNumber"), span(" │ "), ...code],
+    [gutter, span("· "), span(underline, "underline")],
+    [gutter, span("╰────")],
   ];
 };
 
+/** The reference as the hint. A rule without one shows its code to avoid instead, labeled so. */
+const hint = (finding: Finding): ReadonlyArray<Line> => {
+  const [label, code] =
+    finding.reference === undefined ? ["avoid", finding.avoid ?? ""] : ["hint", finding.reference];
+  return hanging(span(`  ${label}: `, "label"), codeLines(code));
+};
+
 /**
- * The report, in the default `vp lint` layout. Diagnostics are separated by
- * a blank line. Color is on when the caller is writing to a terminal.
+ * One diagnostic, in the frame `vp lint` prints on a terminal: a red header,
+ * the offending line, a pink underline, and the reference code as the hint.
  */
-export const render = (result: AuditResult, options: RenderOptions = {}): ReadonlyArray<string> => {
-  const lines: Array<string> = [];
-  for (const finding of result.findings) {
-    if (lines.length > 0) lines.push("");
-    lines.push(...frame(finding, options));
-  }
-  if (lines.length > 0) lines.push("");
-  const summary = [
+const frame = (finding: Finding, root: string | undefined): ReadonlyArray<Line> => [
+  header(finding),
+  ...excerpt(finding, root),
+  ...hint(finding),
+];
+
+const summary = (result: AuditResult): ReadonlyArray<Line> => {
+  const counts = [
     counted(result.files, "file", "files"),
     `${result.judged} judged`,
     `${result.cached} cached`,
     ...(result.skipped > 0 ? [`${result.skipped} skipped`] : []),
   ];
-  lines.push(
-    `Found ${counted(result.findings.length, "error", "errors")}.`,
-    `${summary.join(", ")}.`,
-  );
-  return lines;
+  return [
+    [span(`Found ${counted(result.findings.length, "error", "errors")}.`)],
+    [span(`${counts.join(", ")}.`)],
+  ];
 };
+
+export interface RenderOptions {
+  /** Color the frame the way `vp lint` does on a terminal, and highlight the code. */
+  readonly color?: boolean;
+  readonly root?: string;
+}
+
+/**
+ * The report, in the default `vp lint` layout: each diagnostic followed by a
+ * blank line, then the counts. Color is on when the caller is writing to a
+ * terminal.
+ */
+export const render = (result: AuditResult, options: RenderOptions = {}): ReadonlyArray<string> =>
+  [
+    ...result.findings.flatMap((finding) => [...frame(finding, options.root), []]),
+    ...summary(result),
+  ].map((line) => serialize(line, options.color === true));