@drkmttr/adhere 0.4.0 → 0.4.1

package/README.md

@@ -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
 ```
 
@@ -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
 
@@ -68,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)
 ```
 
@@ -103,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
@@ -258,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.4.0",
+  "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.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.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

@@ -96,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/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,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/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));