@drkmttr/adhere 0.7.3 → 0.9.0

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

@@ -1,5 +1,5 @@
 ---
-description: A test that depends on time must use TestClock. Real sleeps and it.live must be used only when real time is required.
+description: A test that depends on time must use TestClock, never a real sleep or it.live, unless the test needs real time.
 ---
 
 ```ts must

package/skills/adhere/SKILL.md

@@ -103,14 +103,15 @@ export default {
 } satisfies Config;
 ```
 
-Add `.adhere/cache/` to `.gitignore`. Uncached files need a TypeSafe AI API
+Commit `.adhere/cache/` with the code, so the team and CI reuse its judgments
+instead of paying for them again. 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, asks Jev about contradictions
+adhere validate              # decodes the config and rules; reports their wording, rules a linter could check, and contradictions
 adhere lint                  # or: adhere lint --preset effect
 adhere lint --threshold 0.9  # re-reads the cache, sends nothing
 ```

package/src/cli.ts

@@ -8,6 +8,7 @@ import {
   executeAudit,
   type FileDone,
   planAudit,
+  pruneCache,
   render,
 } from "#workflows/audit.ts";
 import {
@@ -20,16 +21,20 @@ import {
 import type { Overrides } from "#config.ts";
 import { findContradictions, formatContradictions } from "#contradictions.ts";
 import { initProject } from "#init.ts";
+import { formatLinterCheck, tallyProjectRules } from "#mechanical.ts";
 import { type PresetName, presetNames } from "#presets.ts";
 import { globalRuleSet } from "#rules.ts";
+import { formatStrays, straysAmong } from "#wording.ts";
 import {
   Console,
   Effect,
   Exit,
   Layer,
+  LogLevel,
   Option,
   Path,
   Redacted,
+  References,
   Runtime,
   Schema,
   Stdio,
@@ -58,7 +63,9 @@ class ContradictionsReported extends Schema.TaggedError<ContradictionsReported>(
 
 const preset = Flag.choice("preset", presetNames).pipe(
   Flag.optional,
-  Flag.withDescription("Add a built-in rule set. With a preset, .adhere/config.ts is optional."),
+  Flag.withDescription(
+    "Add a built-in rule set, or one of its topics, such as effect/basics. With a preset, .adhere/config.ts is optional.",
+  ),
 );
 
 const threshold = Flag.float("threshold").pipe(
@@ -118,8 +125,9 @@ const toStderr = (text: string) =>
  * anything else it stays quiet, so a log gets the plan and the report rather
  * than a line per file. A failed run keeps its last count on screen.
  */
-const counterFor = (plan: AuditPlan) => {
-  const live = process.stderr.isTTY === true;
+const counterFor = (plan: AuditPlan, logging: LogLevel.LogLevel) => {
+  // Log lines at debug or below would land between redraws and garble the counter.
+  const live = process.stderr.isTTY === true && LogLevel.isGreaterThan(logging, "Debug");
   let progress: Progress = { files: 0, requests: 0, findings: 0 };
   const draw = () => (live ? toStderr(`\r\u001b[2K${progressLine(progress, plan)}`) : Effect.void);
   return {
@@ -170,11 +178,13 @@ export const lintCommand = Command.make(
           return yield* Cancelled.make({});
         }
       }
-      const counter = counterFor(plan);
+      const counter = counterFor(plan, yield* References.MinimumLogLevel);
       yield* counter.start;
       const result = yield* executeAudit(plan, counter.update).pipe(
         Effect.onExit((exit) => counter.finish(Exit.isFailure(exit))),
       );
+      // Only a run that read every file knows what the cache still needs.
+      if (input.filter.length === 0) yield* pruneCache(plan);
       const color = yield* stdio.stdoutIsTerminal;
       const path = yield* Path.Path;
       // One write: separate Console.log calls have interleaved out of order here.
@@ -201,31 +211,44 @@ export const lintCommand = Command.make(
 
 /** 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)),
-  );
+  Layer.merge(
+    JevLive.pipe(Layer.provide([FetchHttpClient.layer, CredentialsLive])),
+    AuditCacheLive,
+  ).pipe(Layer.provideMerge(AdhereConfigLive(overrides)));
 
 /**
- * `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`.
+ * `adhere validate`: everything `lint` loads, then how each rule's wording
+ * differs from the README's rule writing tips, then the linter check's tallies
+ * from lint, then Jev on whether any two rules that apply to the same files
+ * contradict. Only a contradiction fails the run: the tips and the linter
+ * check are advice. 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 = yield* findContradictions(entries, config.threshold);
+    const root = path.resolve();
+    const entries = config.scopedRules ?? globalRuleSet(config.rules, root);
     const loaded = `${entries.length} ${entries.length === 1 ? "rule" : "rules"} loaded.`;
-    yield* Console.log([loaded, formatContradictions(contradictions)].join("\n"));
+    const tallied = yield* tallyProjectRules(entries, config.model);
+    // The wording and the tallies need no request, so they show before Jev is asked anything.
+    yield* Console.log(
+      [
+        loaded,
+        ...formatStrays(straysAmong(entries), root),
+        ...formatLinterCheck(tallied, root),
+      ].join("\n"),
+    );
+    const contradictions = yield* findContradictions(entries, config.threshold);
+    yield* Console.log(formatContradictions(contradictions));
     if (contradictions.length > 0) {
       return yield* ContradictionsReported.make({ count: contradictions.length });
     }
   }),
 ).pipe(
   Command.withDescription(
-    "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.",
+    "Load the config, rule files, and presets the way lint does, check each rule's wording against the README's rule writing tips, report the rules lint's linter check flags, then ask Jev whether any two rules that apply to the same files contradict each other.",
   ),
   Command.provide((input) => validateLayer({ presets: chosenPresets(input.preset) })),
 );
@@ -312,7 +335,10 @@ export const cli = Command.make("adhere").pipe(
   Command.withDescription("Lint a repository against the rules in .adhere/, judged by Jev."),
   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 validate",
+      description: "Check the rules' wording, and ask Jev whether any contradict",
+    },
     { command: "adhere login", description: "Save your TypeSafe AI API key for later runs" },
     { command: "adhere lint", description: "Audit the working directory" },
     {

package/src/config.ts

@@ -161,11 +161,21 @@ export interface Overrides {
   readonly rpm?: number;
 }
 
-/** The presets a run applies, command-line ones first. */
+/**
+ * The presets a run applies, command-line ones first, each once. A topic such
+ * as `effect/basics` is left out when its whole preset is named too, since
+ * the whole preset already holds its rules.
+ */
 export const presetsOf = (
   config: Pick<AdhereConfig, "presets">,
   overrides: Overrides,
-): ReadonlyArray<PresetName> => [...(overrides.presets ?? []), ...config.presets];
+): ReadonlyArray<PresetName> => {
+  const named = [...new Set([...(overrides.presets ?? []), ...config.presets])];
+  return named.filter((name) => {
+    const [whole] = name.split("/");
+    return whole === name || !named.some((other) => other === whole);
+  });
+};
 
 /**
  * Precedence, highest first: command line, config file, presets in order

package/src/excerpt.ts

@@ -0,0 +1,255 @@
+import { scan } from "#highlight.ts";
+
+/**
+ * The lines a finding shows: the statement its line is in, such as the
+ * function around it, and a few lines on either side of the line.
+ */
+export interface Excerpt {
+  /** The number of the first line, counting from 1. */
+  readonly start: number;
+  readonly lines: ReadonlyArray<string>;
+}
+
+/** How far an excerpt reaches on either side of the finding's line, in whole statements. */
+const AROUND = 3;
+/** The most lines a statement can have and still be shown whole. */
+const WHOLE = 30;
+
+/** Lines of the code, first to last, counting from 1. */
+interface Range {
+  readonly first: number;
+  readonly last: number;
+}
+
+const holds = (range: Range, line: number): boolean => range.first <= line && line <= range.last;
+
+/**
+ * A token that shapes the code: a bracket, a separator, an operator, or a
+ * value, such as a name, a keyword, or a literal. Only a template literal
+ * ends on a later line than the one it starts on.
+ */
+interface Piece {
+  readonly text: string;
+  readonly role: "open" | "close" | "separator" | "operator" | "value";
+  readonly line: number;
+  readonly end: number;
+  /** Whether whitespace or a comment comes right before it. */
+  readonly spaced: boolean;
+}
+
+const ROLES: Readonly<Record<string, Piece["role"]>> = {
+  "(": "open",
+  "[": "open",
+  "{": "open",
+  ")": "close",
+  "]": "close",
+  "}": "close",
+  ";": "separator",
+  ",": "separator",
+};
+
+/**
+ * The code as pieces, without whitespace and comments, and the comments and
+ * literals that span lines: a line that starts inside one does not read as
+ * code on its own.
+ */
+const piecesOf = (code: string) => {
+  const pieces: Array<Piece> = [];
+  const spans: Array<Range> = [];
+  let line = 1;
+  let spaced = true;
+  for (const { text, kind } of scan(code)) {
+    const end = line + text.split("\n").length - 1;
+    if (kind !== undefined && end > line) spans.push({ first: line, last: end });
+    if (kind === "comment" || text.trim().length === 0) {
+      spaced = true;
+    } else if (kind !== undefined || /^[\w$]/.test(text)) {
+      pieces.push({ text, role: "value", line, end, spaced });
+      spaced = false;
+    } else {
+      // A run of punctuation, like `});` or `=>{`: each bracket and separator is a piece.
+      for (const part of text.match(/[()[\]{};,]|[^()[\]{};,]+/g) ?? []) {
+        pieces.push({ text: part, role: ROLES[part] ?? "operator", line, end, spaced });
+        spaced = false;
+      }
+    }
+    line = end;
+  }
+  return { pieces, spans };
+};
+
+/**
+ * Where each group closes: the index of the piece that opens it, mapped to
+ * the index of the one that closes it. Type arguments broken over lines, from
+ * a `Type<` that ends a line to a `>` that starts one, are a group too, so
+ * their commas do not end a statement; a `<` that no such `>` closes was a
+ * comparison. A bracket left open runs to the end.
+ */
+const closesOf = (pieces: ReadonlyArray<Piece>): ReadonlyMap<number, number> => {
+  const closes = new Map<number, number>();
+  const opened: Array<number> = [];
+  const isAngle = (index: number | undefined): index is number =>
+    index !== undefined && pieces[index]?.text === "<";
+  pieces.forEach((piece, index) => {
+    const before = pieces[index - 1];
+    const after = pieces[index + 1];
+    const top = opened.at(-1);
+    if (piece.role === "open") {
+      opened.push(index);
+    } else if (piece.text === "<") {
+      const endsLine = after === undefined || after.line > piece.line;
+      if (endsLine && !piece.spaced && before?.role === "value") opened.push(index);
+    } else if (piece.text === ">" && isAngle(top) && (before?.end ?? 0) < piece.line) {
+      opened.pop();
+      closes.set(top, index);
+    } else if (piece.role === "close" || piece.text === ";") {
+      while (isAngle(opened.at(-1))) opened.pop();
+      const opener = piece.role === "close" ? opened.pop() : undefined;
+      if (opener !== undefined) closes.set(opener, index);
+    }
+  });
+  for (const opener of opened) {
+    if (!isAngle(opener)) closes.set(opener, pieces.length - 1);
+  }
+  return closes;
+};
+
+/** Operators that leave an expression open at the end of a line: `=`, `=>`, `&&`, `.`. */
+const LEAVES_OPEN = /[-+*/%&|^<>=?:.]$/;
+/** Operators that carry the expression above on at the start of a line: `.pipe(`, `? a`, `| B`. */
+const CARRIES_ON = /^[-+*/%&|^>=?:.]/;
+/** Words that need more after them at the end of a line. */
+const OPEN_WORDS = new Set(["as", "await", "extends", "implements", "keyof", "new", "satisfies"]);
+/** Words that go on with the statement above at the start of a line. */
+const ON_WORDS = new Set(["as", "catch", "else", "extends", "finally", "implements", "satisfies"]);
+
+const isStep = (text: string): boolean => text === "++" || text === "--";
+
+const leavesOpen = (piece: Piece): boolean =>
+  piece.role === "operator"
+    ? LEAVES_OPEN.test(piece.text) && !isStep(piece.text)
+    : piece.role === "value" && OPEN_WORDS.has(piece.text);
+
+const carriesOn = (piece: Piece): boolean =>
+  piece.role === "operator"
+    ? CARRIES_ON.test(piece.text) && !isStep(piece.text)
+    : piece.role === "value" && ON_WORDS.has(piece.text);
+
+/** A statement's lines, and the groups directly inside it, as the pieces that open and close each. */
+interface Statement extends Range {
+  readonly groups: ReadonlyArray<readonly [number, number]>;
+}
+
+/**
+ * The statements in the pieces from `from` up to `to`, each group inside one
+ * taken whole. A statement ends at a `;` or `,`, or at a line break that
+ * neither side carries across: about where JavaScript inserts a semicolon.
+ */
+const statementsIn = (
+  pieces: ReadonlyArray<Piece>,
+  closes: ReadonlyMap<number, number>,
+  from: number,
+  to: number,
+): ReadonlyArray<Statement> => {
+  const statements: Array<Statement> = [];
+  let current:
+    | { first: number; last: number; groups: Array<readonly [number, number]> }
+    | undefined;
+  let open = false;
+  let index = from;
+  while (index < to) {
+    const piece = pieces[index];
+    if (piece === undefined) break;
+    if (current !== undefined && piece.line > current.last && !open && !carriesOn(piece)) {
+      statements.push(current);
+      current = undefined;
+    }
+    const close = Math.min(closes.get(index) ?? index, to - 1);
+    const end = pieces[close]?.end ?? piece.end;
+    current ??= { first: piece.line, last: end, groups: [] };
+    current.last = end;
+    if (close > index) current.groups.push([index, close]);
+    // A group's closing bracket leaves nothing open.
+    open = close === index && leavesOpen(piece);
+    if (piece.role === "separator") {
+      statements.push(current);
+      current = undefined;
+    }
+    index = close + 1;
+  }
+  if (current !== undefined) statements.push(current);
+  return statements;
+};
+
+/**
+ * The statements `line` is in, outermost first: the one at the top level,
+ * then the one around `line` inside the group of that statement it is in,
+ * and so on inward. A line where two statements meet is in both, together.
+ */
+const statementsAround = (
+  pieces: ReadonlyArray<Piece>,
+  closes: ReadonlyMap<number, number>,
+  line: number,
+  from = 0,
+  to = pieces.length,
+): ReadonlyArray<Range> => {
+  const around = statementsIn(pieces, closes, from, to).filter((statement) =>
+    holds(statement, line),
+  );
+  const [outer, inner] = [around[0], around.at(-1)];
+  if (outer === undefined || inner === undefined) return [];
+  const group = around
+    .flatMap((statement) => statement.groups)
+    .find(
+      ([open, close]) => (pieces[open]?.line ?? line) < line && line <= (pieces[close]?.line ?? 0),
+    );
+  return [
+    { first: outer.first, last: inner.last },
+    ...(group === undefined ? [] : statementsAround(pieces, closes, line, group[0] + 1, group[1])),
+  ];
+};
+
+/**
+ * The excerpt for a finding on `line`: the outermost statement around it
+ * with at most `WHOLE` lines, such as the function it is in, and up to
+ * `AROUND` lines on either side of `line`. A comment or template literal
+ * that spans lines counts as a statement inside the one it is in.
+ *
+ * Around `line`, the excerpt shows only whole statements, never the end of
+ * the one above or the start of the one below, so it cannot start partway
+ * through a comment, whose lines do not read as code on their own. What
+ * `line` itself is in can show in part: a long function's first line, above
+ * the statement of its body. It ends at code, since a comment at the end
+ * would be about code the excerpt leaves out.
+ */
+export const excerptOf = (lines: ReadonlyArray<string>, line: number): Excerpt => {
+  const { pieces, spans } = piecesOf(lines.join("\n"));
+  const closes = closesOf(pieces);
+  /** What a line is in, outermost first. */
+  const around = (at: number): ReadonlyArray<Range> => [
+    ...statementsAround(pieces, closes, at),
+    ...spans.filter((span) => holds(span, at)),
+  ];
+  const scope = around(line).find((range) => range.last - range.first < WHOLE);
+  const top = Math.max(1, Math.min(scope?.first ?? line, line - AROUND));
+  const bottom = Math.min(lines.length, Math.max(scope?.last ?? line, line + AROUND));
+  /** What a line is in that `line` is not, which an edge shows whole or not at all. */
+  const beside = (at: number) => around(at).filter((range) => !holds(range, line));
+  let first = Math.max(
+    top,
+    ...beside(top)
+      .filter((range) => range.first < top)
+      .map((range) => range.last + 1),
+  );
+  let last = Math.min(
+    bottom,
+    ...beside(bottom)
+      .filter((range) => range.last > bottom)
+      .map((range) => range.first - 1),
+  );
+  const isBlank = (at: number) => (lines[at - 1] ?? "").trim().length === 0;
+  const hasCode = (at: number) => pieces.some((piece) => piece.line <= at && at <= piece.end);
+  while (first < line && isBlank(first)) first += 1;
+  while (last > line && !hasCode(last)) last -= 1;
+  return { start: first, lines: lines.slice(first - 1, last) };
+};

package/src/highlight.ts

@@ -27,11 +27,11 @@ 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. */
+/** One group per token class, tried in order at each position. A template literal is read apart. */
 const TOKEN = new RegExp(
   [
     /(?<comment>\/\/[^\n]*|\/\*[\s\S]*?(?:\*\/|$))/,
-    /(?<string>"(?:[^"\\\n]|\\.)*"?|'(?:[^'\\\n]|\\.)*'?|`(?:[^`\\]|\\[\s\S])*`?)/,
+    /(?<string>"(?:[^"\\\n]|\\.)*"?|'(?:[^'\\\n]|\\.)*'?)/,
     /(?<constant>0[box][\da-f_]+n?|\d[\d_]*(?:\.\d[\d_]*)?(?:e[+-]?\d+)?n?)/,
     /(?<word>[a-z_$][\w$]*)/,
     /(?<space>\s+)/,
@@ -71,36 +71,98 @@ const kindOf = (word: string, previous: string | undefined, isKey: boolean): Kin
   return KEYWORDS.has(word) ? "keyword" : PRIMITIVES.has(word) ? "type" : undefined;
 };
 
+/** Whether a token is what the next one reads as before it: not whitespace or a comment. */
+const counts = (token: Token): boolean => token.kind !== "comment" && token.text.trim().length > 0;
+
+/** The token at `at`, after `previous`, the last one that counts. */
+const tokenAt = (code: string, at: number, previous: string | undefined): Token | undefined => {
+  if (code[at] === "`") return { text: code.slice(at, templateEnd(code, at)), kind: "string" };
+  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) return undefined;
+  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);
+  return kind === undefined ? { text } : { text, kind };
+};
+
+/**
+ * Where the template literal that opens at `at` closes: past its closing
+ * backtick, or at the end of the code. The code in each `${…}` is read as
+ * tokens, so a brace or a template in it, as in `${xs.map((x) => `${x}`)}`,
+ * does not close the template early.
+ */
+const templateEnd = (code: string, at: number): number => {
+  let index = at + 1;
+  while (index < code.length && code[index] !== "`") {
+    if (code[index] === "\\") index += 2;
+    else if (code.startsWith("${", index)) index = substitutionEnd(code, index + 2);
+    else index += 1;
+  }
+  return Math.min(index + 1, code.length);
+};
+
+/** Where the code of a `${…}` that starts at `at` ends: past the brace that closes it. */
+const substitutionEnd = (code: string, at: number): number => {
+  let depth = 0;
+  let previous: string | undefined;
+  let index = at;
+  while (index < code.length) {
+    const token = tokenAt(code, index, previous);
+    if (token === undefined) break;
+    // Braces are punctuation; one in a string or a nested template is text.
+    if (token.kind === undefined) {
+      for (let offset = 0; offset < token.text.length; offset += 1) {
+        if (token.text[offset] === "{") depth += 1;
+        else if (token.text[offset] === "}") {
+          if (depth === 0) return index + offset + 1;
+          depth -= 1;
+        }
+      }
+    }
+    if (counts(token)) previous = token.text;
+    index += token.text.length;
+  }
+  return code.length;
+};
+
+/**
+ * The code's tokens, in order. A token that crosses a newline, like a block
+ * comment or a template literal, stays whole.
+ */
+export const scan = (code: string): ReadonlyArray<Token> => {
+  const tokens: Array<Token> = [];
+  let previous: string | undefined;
+  let at = 0;
+  while (at < code.length) {
+    const token = tokenAt(code, at, previous);
+    if (token === undefined) break;
+    tokens.push(token);
+    if (counts(token)) previous = token.text;
+    at += token.text.length;
+  }
+  return tokens;
+};
+
 /**
  * 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 { text, kind } of scan(code)) {
     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

@@ -20,18 +20,24 @@ export default {
 `;
 
 const SMALL_FILES = `---
-description: A file should be small and focused, with one primary responsibility.
+description: A file should be small and focused, with one primary responsibility, and should not mix unrelated concerns.
 threshold: 0.8
 ---
 
-A guideline, so its description and its code say should. A rule that must
-hold says must and never instead, as name-domain-actions does. Use this rule
-as a template for repository-specific conventions.
+A guideline, so its description and its code say should and should not. A
+rule that must hold says must and never instead, as name-domain-actions does.
+Use this rule as a template for repository-specific conventions.
 
 \`\`\`ts should
 export const parsePort = (value: string) =>
   Port.make(Number.parseInt(value, 10));
 \`\`\`
+
+\`\`\`ts should not
+export const parsePort = (value: string) => Port.make(Number.parseInt(value, 10));
+export const sendWelcomeEmail = (to: Email) => Mailer.send(to, welcomeTemplate);
+export const renderInvoice = (invoice: Invoice) => Html.table(invoice.lines);
+\`\`\`
 `;
 
 const NAME_EFFECTS = `---

package/src/main.ts

@@ -4,7 +4,7 @@ import * as adhere from "#index.ts";
 import { version } from "#version.ts";
 import { BunRuntime, BunServices } from "@effect/platform-bun";
 import { plugin } from "bun";
-import { Effect } from "effect";
+import { Cause, Effect, Layer, Logger, References, Runtime } from "effect";
 import { Command } from "effect/unstable/cli";
 
 // A config file may import `@drkmttr/adhere`, for `defineConfig`. The compiled
@@ -17,8 +17,39 @@ plugin({
   },
 });
 
+/**
+ * Every log on stderr, so stdout carries the report and nothing else. The
+ * pretty logger picks its stream from `LogToStderr`, not from an option.
+ */
+const logger = Layer.merge(
+  Logger.layer([Logger.consolePretty()]),
+  Layer.succeed(References.LogToStderr, true),
+);
+
+/**
+ * How a failed run says so, through the logger above: runMain's own report
+ * goes to stdout. A failure adhere declares, such as a refused request or a
+ * config that does not decode, is its message alone; its stack would only
+ * point into adhere. A defect, which is a bug, keeps its whole cause.
+ */
+const report = (cause: Cause.Cause<unknown>): Effect.Effect<void> => {
+  if (Cause.hasInterruptsOnly(cause)) return Effect.void;
+  const error = Cause.squash(cause);
+  const marked = typeof error === "object" && error !== null && Runtime.errorReported in error;
+  if (
+    marked &&
+    (error as { readonly [Runtime.errorReported]: boolean })[Runtime.errorReported] === false
+  ) {
+    return Effect.void;
+  }
+  return !Cause.hasDies(cause) && error instanceof Error
+    ? Effect.logError(error.message)
+    : Effect.logError(cause);
+};
+
 Command.run(cli, { version }).pipe(
-  // oxlint-disable-next-line effecttsgo/strict-effect-provide -- this executable entrypoint supplies Bun's process services.
-  Effect.provide(BunServices.layer),
-  BunRuntime.runMain,
+  Effect.tapCause(report),
+  // oxlint-disable-next-line effecttsgo/strict-effect-provide -- this executable entrypoint supplies Bun's process services and the logger.
+  Effect.provide(Layer.merge(BunServices.layer, logger)),
+  (program) => BunRuntime.runMain(program, { disableErrorReporting: true }),
 );