@drkmttr/adhere 0.3.1 → 0.4.1

package/README.md

@@ -1,9 +1,9 @@
 # adhere
 
-A linter for rules a normal linter cannot check. A rule is a piece of correct
-reference code plus a one-sentence description. For each source file, adhere
-asks [Jev](https://typesafe.ai) (TypeSafe AI's System One model) whether the
-file diverges from each rule's reference, gets a calibrated probability per
+A linter for rules a normal linter cannot check. A rule is a one-sentence
+description plus correct reference code, code to avoid, or both. For each
+source file, adhere asks [Jev](https://typesafe.ai) (TypeSafe AI's System One
+model) whether the file breaks each rule, gets a calibrated probability per
 rule, and reports the ones above a threshold with the line Jev points at. The
 report uses the same frame as `vp lint`.
 
@@ -23,7 +23,8 @@ 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
 
@@ -31,7 +32,7 @@ with a TypeSafe AI API key in `TYPESAFE_API_KEY`.
 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 lint                          # audit the working directory
 ```
 
@@ -54,10 +55,12 @@ Found 1 error.
 ```
 
 The header is the rule id, Jev's probability, and the rule's description. The
-hint is the rule's reference. 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.
+hint is the rule's reference; a rule with only code to avoid shows that code,
+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
 
@@ -67,6 +70,8 @@ adhere lint --preset effect    # add a built-in rule set; the config becomes opt
 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 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)
 ```
 
@@ -102,6 +107,15 @@ 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.
 
+### 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
+`TYPESAFE_API_KEY`, when set, takes precedence, so CI can pass a key without a
+login. `adhere logout` deletes the saved key.
+
 ## Config
 
 A config file is optional. Without one, adhere reads the rule files in
@@ -128,6 +142,7 @@ export default {
 const UserId = Schema.String.pipe(Schema.brand("UserId"))
 type UserId = typeof UserId.Type
 `,
+      avoid: "type UserId = string", // optional: what a violation looks like
       threshold: 0.8, // optional per-rule override
     },
   },
@@ -154,7 +169,8 @@ directory exists, it is read without any config.
 
 A file is front matter, then a body. The first fenced code block in the body
 is the reference; prose around it renders on GitHub and is ignored. Without a
-fence, the whole body is the reference.
+fence, the whole body is the reference. A fence tagged `avoid` after its
+language holds code to avoid instead: what a violation looks like.
 
 ````md
 ---
@@ -170,11 +186,25 @@ const Port = Schema.Int.pipe(
   Schema.brand("Port"),
 );
 ```
+
+Not this:
+
+```ts avoid
+const port: number = Number(process.env.PORT);
+```
 ````
 
-`description` is required. `threshold` is optional. A file that fails
-validation refuses the run with its path in the message. `loadRules(directory)`
-from the package root does the same load for your own tooling.
+`description` is required, with a reference, code to avoid, or both.
+`threshold` is optional. A file that fails validation refuses the run with its
+path in the message. `loadRules(directory)` from the package root does the same
+load for your own tooling.
+
+With a reference, Jev is asked whether the file diverges from it, and code to
+avoid, when there is some, is its example of diverging. With only code to
+avoid, Jev is asked whether the file contains it. That suits a rule with no
+single correct form to show, such as a hand-rolled retry loop or an error
+caught and dropped. Neither goes in the other's place: code to avoid in the
+reference reads to Jev as the pattern to follow.
 
 Nested `.adhere/` directories are also discovered, except under
 `node_modules/`, `dist/`, and the other skipped directories (above). A rule in
@@ -221,8 +251,10 @@ 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. Every
-   question shares the state cost of the request.
+   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.
 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
@@ -239,8 +271,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.3.1",
+  "version": "0.4.1",
   "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.3.1",
-    "@drkmttr/adhere-darwin-x64": "0.3.1",
-    "@drkmttr/adhere-linux-arm64": "0.3.1",
-    "@drkmttr/adhere-linux-x64": "0.3.1",
-    "@drkmttr/adhere-win32-x64": "0.3.1"
+    "@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"
   }
 }

package/skills/adhere/SKILL.md

@@ -61,15 +61,22 @@ Optional prose for readers on GitHub. adhere ignores it.
 ```ts
 // Correct code lifted from this repo, trimmed to the pattern.
 ```
+
+```ts avoid
+// Optional: the incorrect form this rule catches, as it appeared in the repo.
+```
 ````
 
 Rules for the rule:
 
 - `description` is one sentence, positive, specific. Jev reads it with the
   reference; vague words ("properly", "correctly") give it nothing to judge.
-- The reference is real code from the repo, not invented. Never include
-  incorrect code; Jev compares files to the reference, so a "bad" example
-  teaches the wrong thing.
+- The reference is real code from the repo, not invented, and only correct
+  code: Jev compares files to it, so incorrect code there teaches the wrong
+  thing. Incorrect code goes in a fence tagged `avoid`, which Jev reads as what
+  a violation looks like. Add one when violations have a recognizable shape,
+  ideally one found in the repo's history. A rule with no single correct form
+  can be only an `avoid` block.
 - One pattern per file. Two patterns in one reference blur the probability.
 - `threshold` is optional. Start without it; set it in step 5 if needed.
 
@@ -89,8 +96,9 @@ 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
 

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. */
@@ -127,6 +130,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 +200,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/config.ts

@@ -6,9 +6,18 @@ export type RuleId = string;
 
 export const Rule = Schema.Struct({
   description: Schema.String,
-  reference: Schema.String,
+  /** Correct code: the pattern a file should follow. */
+  reference: Schema.optionalKey(Schema.String),
+  /** Incorrect code: what a violation looks like. */
+  avoid: Schema.optionalKey(Schema.String),
   threshold: Schema.optionalKey(Schema.Finite),
-});
+}).check(
+  Schema.makeFilter((rule) =>
+    rule.reference !== undefined || rule.avoid !== undefined
+      ? undefined
+      : "a rule needs a reference, code to avoid, or both",
+  ),
+);
 export interface Rule extends Schema.Schema.Type<typeof Rule> {}
 
 export type Rules = Readonly<Record<RuleId, Rule>>;

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/init.ts

@@ -43,6 +43,16 @@ export const loadCustomerProfile = (customerId: CustomerId) =>
     return yield* CustomerStore.find(customerId);
   });
 \`\`\`
+
+A fence tagged \`avoid\` shows what a violation looks like. It is optional, and
+a rule can have one without the block above.
+
+\`\`\`ts avoid
+export const handle = (id: string) =>
+  Effect.gen(function* () {
+    return yield* CustomerStore.find(id);
+  });
+\`\`\`
 `;
 
 const CONFIG_PATH = CONFIG_FILES[0];

package/src/markdown.ts

@@ -14,8 +14,13 @@ import { Effect, Schema } from "effect";
  *     const reference = "the correct code"
  *     ```
  *
- * The reference is the first fenced code block. Without a fence, it is the
- * whole body. `threshold` is optional.
+ *     ```ts avoid
+ *     const avoided = "what a violation looks like"
+ *     ```
+ *
+ * The reference is the first fenced code block; `avoid` in a fence's info
+ * string marks the code to avoid instead. A rule has either or both. Without a
+ * fence, the whole body is the reference. `threshold` is optional.
  */
 const FrontMatter = Schema.Struct({
   description: Schema.String,
@@ -23,7 +28,8 @@ const FrontMatter = Schema.Struct({
 });
 
 const FRONT_MATTER = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
-const FENCE = /^ {0,3}(`{3,}|~{3,})[^\n]*\n([\s\S]*?)\n {0,3}\1[ \t]*$/m;
+const FENCE = /^ {0,3}(`{3,}|~{3,})([^\n]*)\n([\s\S]*?)\n {0,3}\1[ \t]*$/gm;
+const AVOID = "avoid";
 
 const unquote = (value: string): string => {
   const trimmed = value.trim();
@@ -44,9 +50,35 @@ const parseFrontMatter = (block: string): Record<string, string> => {
   return fields;
 };
 
-const referenceOf = (body: string): string => {
-  const fence = FENCE.exec(body);
-  return (fence?.[2] ?? body).trim();
+interface Fence {
+  readonly avoid: boolean;
+  readonly code: string;
+}
+
+const fencesOf = (body: string): ReadonlyArray<Fence> =>
+  Array.from(body.matchAll(FENCE), (match) => ({
+    avoid: (match[2] ?? "")
+      .trim()
+      .split(/\s+/)
+      .some((word) => word.toLowerCase() === AVOID),
+    code: (match[3] ?? "").trim(),
+  }));
+
+/** An empty block counts as no block. */
+const nonEmpty = (code: string | undefined): string | undefined =>
+  code === undefined || code.length === 0 ? undefined : code;
+
+/** The reference and the code to avoid, each left out when the body has none. */
+const codeOf = (body: string): Pick<Rule, "reference" | "avoid"> => {
+  const fences = fencesOf(body);
+  const reference = nonEmpty(
+    fences.length === 0 ? body.trim() : fences.find((fence) => !fence.avoid)?.code,
+  );
+  const avoid = nonEmpty(fences.find((fence) => fence.avoid)?.code);
+  return {
+    ...(reference === undefined ? {} : { reference }),
+    ...(avoid === undefined ? {} : { avoid }),
+  };
 };
 
 export const parseRuleMarkdown = (
@@ -65,11 +97,11 @@ export const parseRuleMarkdown = (
         ConfigUnavailable.make({ message: `${file}: ${problem.message}` }),
       ),
     );
-    const reference = referenceOf(match[2]);
-    if (reference.length === 0) {
+    const code = codeOf(match[2]);
+    if (code.reference === undefined && code.avoid === undefined) {
       return yield* ConfigUnavailable.make({
-        message: `${file}: the body is the reference code and cannot be empty`,
+        message: `${file}: the body needs reference code, a fence tagged avoid, or both`,
       });
     }
-    return { ...front, reference };
+    return { ...front, ...code };
   });

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,4 +1,5 @@
 import { AdhereConfig } from "#services/AdhereConfig.ts";
+import { Credentials } from "#services/Credentials.ts";
 import {
   blockBody,
   Jev,
@@ -9,7 +10,7 @@ import {
   needsBlocks,
   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 +28,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 +41,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),

package/src/services/Jev.ts

@@ -1,4 +1,4 @@
-import type { RuleId, Rules } from "#config.ts";
+import type { Rule, RuleId, Rules } from "#config.ts";
 import { Context, type Effect, Record, Schema } from "effect";
 
 export type { Rules };
@@ -36,12 +36,36 @@ export const needsBlocks = (lines: Lines): boolean =>
 
 const stateOf = (lines: Lines, rules: Rules) => ({
   code: lines.map((line, index) => `${index + 1} | ${line}`).join("\n"),
-  rules: Record.map(rules, ({ description, reference }) => ({
+  rules: Record.map(rules, ({ description, reference, avoid }) => ({
     description,
-    reference,
+    ...(reference === undefined ? {} : { reference }),
+    ...(avoid === undefined ? {} : { avoid }),
   })),
 });
 
+const field = (id: RuleId, key: "avoid" | "description" | "reference") =>
+  `state.rules["${id}"].${key}`;
+
+/**
+ * A rule with a reference asks whether the file diverges from it, with the
+ * code to avoid as an example when there is some. A rule without one asks
+ * whether the file contains the code to avoid.
+ */
+const judgeInstructions = (id: RuleId, rule: Rule): string =>
+  rule.reference === undefined
+    ? `Does state.code contain the pattern shown in ${field(id, "avoid")}, which ${field(id, "description")} rules out? Answer no if nothing in this file resembles it.`
+    : `Does state.code diverge from the pattern shown in ${field(id, "reference")}${
+        rule.avoid === undefined ? "" : `, for example by doing what ${field(id, "avoid")} shows`
+      }, as described by ${field(id, "description")}? Answer no if the pattern does not apply to this file.`;
+
+/** What the offending line does, for the line and block questions. */
+const offense = (id: RuleId, rule: Rule): string =>
+  rule.reference === undefined
+    ? `shows the pattern in ${field(id, "avoid")}`
+    : rule.avoid === undefined
+      ? `diverges from ${field(id, "reference")}`
+      : `diverges from ${field(id, "reference")} or resembles ${field(id, "avoid")}`;
+
 const lineCriteria = (lines: Lines, from: number, to: number): Record<string, string> => {
   const criteria: Record<string, string> = {};
   for (let n = from; n <= Math.min(to, lines.length); n++) {
@@ -54,9 +78,9 @@ const lineCriteria = (lines: Lines, from: number, to: number): Record<string, st
 export const judgeBody = (model: string, lines: Lines, rules: Rules) => ({
   model,
   state: stateOf(lines, rules),
-  questions: Record.map(rules, (_, id) => ({
+  questions: Record.map(rules, (rule, id) => ({
     type: "noul" as const,
-    instructions: `Does state.code diverge from the pattern shown in state.rules["${id}"].reference, as described by state.rules["${id}"].description? Answer no if the pattern does not apply to this file.`,
+    instructions: judgeInstructions(id, rule),
   })),
 });
 
@@ -68,11 +92,11 @@ export const locateBody = (
 ) => ({
   model,
   state: stateOf(lines, rules),
-  questions: Record.map(rules, (_, id) => {
+  questions: Record.map(rules, (rule, id) => {
     const block = blocks?.[id];
     return {
       type: "choice" as const,
-      instructions: `Which line of state.code most clearly diverges from state.rules["${id}"].reference?`,
+      instructions: `Which line of state.code most clearly ${offense(id, rule)}?`,
       criteria:
         block === undefined
           ? lineCriteria(lines, 1, lines.length)
@@ -92,9 +116,9 @@ export const blockBody = (model: string, lines: Lines, rules: Rules) => {
   return {
     model,
     state: stateOf(lines, rules),
-    questions: Record.map(rules, (_, id) => ({
+    questions: Record.map(rules, (rule, id) => ({
       type: "choice" as const,
-      instructions: `Which block of state.code contains the line that most clearly diverges from state.rules["${id}"].reference?`,
+      instructions: `Which block of state.code contains the line that most clearly ${offense(id, rule)}?`,
       criteria,
     })),
   };

package/src/workflows/audit.ts

@@ -10,7 +10,8 @@ import { type Crypto, Effect, Record } from "effect";
 export interface Finding {
   readonly rule: RuleId;
   readonly description: string;
-  readonly reference: string;
+  readonly reference?: string;
+  readonly avoid?: string;
   readonly file: string;
   readonly line: number;
   readonly snippet: string;
@@ -43,6 +44,19 @@ const fileResult = (
 
 const isEmpty = Record.isEmptyReadonlyRecord;
 
+/**
+ * What a judgment depends on besides the file. A rule without code to avoid
+ * hashes what every rule hashed before `avoid` existed, so its cached
+ * judgments survive the upgrade.
+ */
+const fingerprintOf = (model: string, rule: Rule) =>
+  sha256(
+    model +
+      rule.description +
+      (rule.reference ?? "") +
+      (rule.avoid === undefined ? "" : `\u0000avoid\u0000${rule.avoid}`),
+  );
+
 export const runAudit: Effect.Effect<
   AuditResult,
   WalkUnavailable | JevUnavailable,
@@ -66,7 +80,7 @@ export const runAudit: Effect.Effect<
       Object.entries(configuredRules(file.path)),
       ([id, rule]) =>
         Effect.map(
-          sha256(config.model + rule.description + rule.reference),
+          fingerprintOf(config.model, rule),
           (fingerprint) =>
             [
               id,
@@ -116,6 +130,7 @@ export const runAudit: Effect.Effect<
                 rule: id,
                 description: k.rule.description,
                 reference: k.rule.reference,
+                avoid: k.rule.avoid,
                 file: file.path,
                 line: judgment.line,
                 snippet: judgment.snippet ?? "",

package/src/workflows/format.ts

@@ -1,79 +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: string): boolean => line.trim().length === 0;
+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 referenceLines = (reference: string): ReadonlyArray<string> => {
-  const lines = reference.split("\n");
+/** 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)));
+
+/** 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.
- */
-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 [hint = "", ...rest] = referenceLines(finding.reference);
-  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("  hint: ", color)}${hint}`,
-    ...rest.map((line) => (isBlank(line) ? "" : `        ${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));