@verevoir/review 0.2.0 → 0.3.0

package/src/cli/review.ts

@@ -0,0 +1,647 @@
+/// <reference types="node" />
+// The `aigency-review` command line: the v5 antagonistic panel, runnable from
+// any repository (including a public one) with `npx`.
+//
+// PORTED FROM verevoir/aigency-governance (src/cli/review.ts, src/cli/run.ts
+// and src/review/settings.ts), so a repository that cannot call governance's
+// private reusable workflow gets the same behaviour: settings are resolved
+// first, then the diff, then the lens set, and only then does anything reach
+// a model. Every failure before a verdict is `could_not_run` and red -- never
+// a pass. See the README's "Command line" section for what was deliberately
+// not ported.
+//
+// `main` takes everything that touches the world as an argument (`io`,
+// `deps`), so tests drive it with fakes and no process, disk, git or network.
+// The bin wrapper (bin.ts) is the only place real ones are constructed.
+//
+// BUNDLED DEFAULT LENSES: `lenses.default.json` at the package root is a copy
+// of aigency-governance's review/lenses.json at commit de238aa. It is a
+// snapshot, not a live read: refresh it deliberately when governance's set
+// changes.
+
+import { runReviewNode } from '../run-review.js';
+import { parseLensSet } from '../lensSet.js';
+import type { LensSet } from '../lensSet.js';
+import type { Reviewer } from '../panel.js';
+import type { ReviewAccount } from '../review-account.js';
+import type { Outcome } from '../verdict.js';
+import { buildPrompt, renderPrompt } from '../prompt.js';
+import { deriveLensSet, extractBar } from '../practice-lenses.js';
+import { buildFileContext, NO_FILE_CONTEXT_NOTE } from '../context-files.js';
+import { buildReferences } from '../references.js';
+import type { DirEntry } from '../references.js';
+import type { RawCall } from '../raw-call.js';
+import { renderFooter, tierLine, usageLines } from './footer.js';
+import type { RouteName } from './footer.js';
+import type { DerivedLenses } from '../practice-lenses.js';
+
+/** Governance's pinned default, sent to both routes. */
+export const DEFAULT_MODEL = 'claude-opus-5-5';
+/** Governance's default output-token budget (billed route only). */
+export const DEFAULT_MAX_TOKENS = 65536;
+
+/** What the prompt's "## The change" shows when no --description-file was given. */
+export const NO_DESCRIPTION_NOTE = 'No PR description was supplied; do not judge the description.';
+
+/** What the prompt's "## Checks on this change" shows when no --checks-file was given. */
+export const NO_CHECKS_NOTE = 'No check results were supplied; do not assume the tests pass.';
+
+/** Ends the checks section when --checks-file is given, so a red check is reported once. */
+export const RED_CI_NOTE =
+  'If a check fails, report it once, then review the rest of the change on its own merits, ' +
+  'as if that failure were fixed.';
+
+export type ResultWord = Outcome;
+
+export interface ReviewIo {
+  readonly readStdin: () => Promise<string>;
+  readonly stdout: (text: string) => void;
+  readonly stderr: (text: string) => void;
+  /** Read a UTF-8 file. Must reject with an error carrying a `code` like fs does. */
+  readonly readFile: (path: string) => Promise<string>;
+  readonly appendFile: (path: string, text: string) => Promise<void>;
+  /** File names directly under a directory (no recursion, files only). */
+  readonly readDir: (path: string) => Promise<string[]>;
+  /** Resolve symlinks (fs.realpath). Rejects with an fs-style `code` if absent. */
+  readonly realpath: (path: string) => Promise<string>;
+  readonly statFile: (path: string) => Promise<{ readonly size: number; readonly isFile: boolean }>;
+  /** List a directory's entries (for the ADR search). Optional: absent, ADRs are not searched. */
+  readonly listDir?: (path: string) => Promise<DirEntry[]>;
+}
+
+export interface ReviewCliDeps {
+  /** Run git with these args (no shell) and return stdout. Rejects on failure. */
+  readonly git: (args: readonly string[]) => Promise<string>;
+  /** Overrides the reviewer; omitted, the route is selected from the account. */
+  readonly reviewer?: Reviewer;
+  /** The bundled default lens set's JSON text. */
+  readonly defaultLenses: () => Promise<string>;
+}
+
+interface Args {
+  readonly base?: string;
+  readonly title: string;
+  readonly lenses?: string;
+  readonly practices?: string;
+  readonly contextRoot?: string;
+  readonly descriptionFile?: string;
+  readonly checksFile?: string;
+  readonly warmFirst: boolean;
+  readonly dedup: boolean;
+  readonly printLenses: boolean;
+  readonly printPrompt?: string;
+  readonly help: boolean;
+}
+
+const USAGE = [
+  'Usage: aigency-review [--base <ref>] [--title <text>] [--lenses <path>]',
+  '',
+  '  --base <ref>     review `git diff --merge-base <ref> HEAD` (needs full history:',
+  '                   checkout with fetch-depth: 0). Without it the diff is read from stdin.',
+  '  --title <text>   the title shown at the top of the report (default: "this change")',
+  '  --lenses <path>  a lens set JSON file (else AIGENCY_REVIEW_LENSES, else the bundled set)',
+  '  --practices <dir>  derive one lens per `lens:` front-matter value from the practice',
+  '                   markdown files in <dir> (cannot be combined with --lenses)',
+  '  --print-lenses   with --practices: print the derived lenses as JSON and exit 0,',
+  '                   with no reviewer call and no diff',
+  '  --print-prompt <lens-id>  print the exact prompt that lens would be sent for the diff',
+  '                   (stdin or --base) and exit 0, with no reviewer call',
+  "  --context-root <dir>  a tree at the change's head: each file the diff touches is shown",
+  '                   in full (16 KB or smaller). Defaults to the current directory with --base;',
+  '                   with stdin and no --context-root there is no file context',
+  '  --description-file <path>  the PR description, shown under "## The change"; without it the',
+  '                   prompt says no description was supplied',
+  '  --checks-file <path>  CI check results, shown verbatim under "## Checks on this change";',
+  '                   without it the prompt says no check results were supplied',
+  '  --warm-first / --no-warm-first  run the first lens alone so the rest read the prompt cache',
+  '                   it wrote (default: on with 2 or more lenses; slower, cheaper)',
+  '  --no-dedup       skip the extra model call that merges findings describing the same',
+  '                   defect across lenses (default: on when 2 or more findings are raised)',
+  '  -h, --help       print this and exit 0',
+  '',
+  'Environment: ANTHROPIC_API_KEY, ANTHROPIC_API_KEY_FILE, AIGENCY_REVIEW_LENSES,',
+  'AIGENCY_REVIEW_MODEL, AIGENCY_REVIEW_MAX_TOKENS, GITHUB_STEP_SUMMARY.',
+].join('\n');
+
+function parseArgs(argv: readonly string[]): Args | { readonly error: string } {
+  let base: string | undefined;
+  let title = 'this change';
+  let lenses: string | undefined;
+  let help = false;
+  let practices: string | undefined;
+  let printLenses = false;
+  let printPrompt: string | undefined;
+  let contextRoot: string | undefined;
+  let descriptionFile: string | undefined;
+  let checksFile: string | undefined;
+  let warmFirst = true;
+  let dedup = true;
+  for (let i = 0; i < argv.length; i++) {
+    const raw = argv[i] as string;
+    if (raw === '-h' || raw === '--help') {
+      help = true;
+      continue;
+    }
+    if (raw === '--print-lenses') {
+      printLenses = true;
+      continue;
+    }
+    if (raw === '--warm-first' || raw === '--no-warm-first') {
+      warmFirst = raw === '--warm-first';
+      continue;
+    }
+    if (raw === '--no-dedup') {
+      dedup = false;
+      continue;
+    }
+    const eq = raw.startsWith('--') ? raw.indexOf('=') : -1;
+    const name = eq === -1 ? raw : raw.slice(0, eq);
+    if (
+      name !== '--base' &&
+      name !== '--title' &&
+      name !== '--lenses' &&
+      name !== '--practices' &&
+      name !== '--print-prompt' &&
+      name !== '--context-root' &&
+      name !== '--description-file' &&
+      name !== '--checks-file'
+    ) {
+      return { error: `Unknown argument ${JSON.stringify(raw)}.` };
+    }
+    let value: string | undefined;
+    if (eq !== -1) {
+      value = raw.slice(eq + 1);
+    } else {
+      value = argv[i + 1];
+      i++;
+    }
+    if (value === undefined || value === '') {
+      return { error: `${name} needs a value.` };
+    }
+    if (name === '--base') base = value;
+    else if (name === '--title') title = value;
+    else if (name === '--practices') practices = value;
+    else if (name === '--print-prompt') printPrompt = value;
+    else if (name === '--context-root') contextRoot = value;
+    else if (name === '--description-file') descriptionFile = value;
+    else if (name === '--checks-file') checksFile = value;
+    else lenses = value;
+  }
+  return {
+    ...(base === undefined ? {} : { base }),
+    title,
+    ...(lenses === undefined ? {} : { lenses }),
+    ...(practices === undefined ? {} : { practices }),
+    ...(contextRoot === undefined ? {} : { contextRoot }),
+    ...(descriptionFile === undefined ? {} : { descriptionFile }),
+    ...(checksFile === undefined ? {} : { checksFile }),
+    warmFirst,
+    dedup,
+    printLenses,
+    ...(printPrompt === undefined ? {} : { printPrompt }),
+    help,
+  };
+}
+
+function present(value: string | undefined): string | undefined {
+  return value === undefined || value.trim() === '' ? undefined : value;
+}
+
+function defaultKeyFilePath(env: Record<string, string | undefined>): string | undefined {
+  const xdg = present(env['XDG_CONFIG_HOME']);
+  if (xdg !== undefined) return `${xdg}/verevoir/anthropic.key`;
+  const home = present(env['HOME']);
+  return home === undefined ? undefined : `${home}/.config/verevoir/anthropic.key`;
+}
+
+type KeyRead =
+  | { readonly kind: 'text'; readonly text: string }
+  | { readonly kind: 'absent' }
+  | { readonly kind: 'unreadable'; readonly reason: string };
+
+async function readKeyFile(io: ReviewIo, path: string): Promise<KeyRead> {
+  try {
+    return { kind: 'text', text: await io.readFile(path) };
+  } catch (cause) {
+    const code = (cause as { code?: unknown }).code;
+    if (code === 'ENOENT' || code === 'ENOTDIR') return { kind: 'absent' };
+    // Names the failure, never any bytes: a key must not reach a log.
+    const message = cause instanceof Error ? cause.message : String(cause);
+    const label = typeof code === 'string' ? code : 'error';
+    return { kind: 'unreadable', reason: `${label}: ${message}` };
+  }
+}
+
+type AccountResolution =
+  | { readonly kind: 'ok'; readonly account: ReviewAccount; readonly route: RouteName }
+  | { readonly kind: 'problem'; readonly problem: string };
+
+/**
+ * The key, in governance's order: ANTHROPIC_API_KEY (non-blank), then
+ * ANTHROPIC_API_KEY_FILE, then the conventional default key file; nothing
+ * configured selects the claude-cli route. A key file someone configured that
+ * is unreadable or blank -- or a NAMED file that is missing -- blocks rather
+ * than silently falling back to the keyless route.
+ */
+async function resolveAccount(
+  env: Record<string, string | undefined>,
+  io: ReviewIo,
+): Promise<AccountResolution> {
+  const fromEnv = present(env['ANTHROPIC_API_KEY']);
+  if (fromEnv !== undefined) {
+    return { kind: 'ok', account: { kind: 'key', apiKey: fromEnv }, route: 'env' };
+  }
+
+  const named = present(env['ANTHROPIC_API_KEY_FILE']);
+  const path = named ?? defaultKeyFilePath(env);
+  if (path === undefined) {
+    return { kind: 'ok', account: { kind: 'subscription' }, route: 'claude-cli' };
+  }
+
+  const read = await readKeyFile(io, path);
+  if (read.kind === 'absent') {
+    if (named !== undefined) {
+      return {
+        kind: 'problem',
+        problem:
+          `ANTHROPIC_API_KEY_FILE names ${path}, but no file exists there. Check the path, ` +
+          'or unset ANTHROPIC_API_KEY_FILE to use the claude-cli route.',
+      };
+    }
+    return { kind: 'ok', account: { kind: 'subscription' }, route: 'claude-cli' };
+  }
+  if (read.kind === 'unreadable') {
+    return {
+      kind: 'problem',
+      problem: `the API key file at ${path} could not be read: ${read.reason}`,
+    };
+  }
+  const key = read.text.trim();
+  if (key === '') {
+    return {
+      kind: 'problem',
+      problem: `the API key file at ${path} exists but is blank; fill it in or remove it.`,
+    };
+  }
+  return { kind: 'ok', account: { kind: 'key', apiKey: key }, route: 'key-file' };
+}
+
+function couldNotRun(title: string, reason: string, source?: string): string {
+  return [
+    '## Review: Could not run',
+    '',
+    `**${title}**`,
+    '',
+    reason,
+    '',
+    'Nothing was reviewed. This is a red result and not a passing one.',
+    ...(source === undefined ? [] : ['', '---', '', `Lens set: \`${source}\`.`]),
+  ].join('\n');
+}
+
+/**
+ * Run the review. Returns the process exit code; never throws (anything
+ * unexpected is reported as could_not_run).
+ */
+export async function main(
+  argv: readonly string[],
+  env: Record<string, string | undefined>,
+  io: ReviewIo,
+  deps: ReviewCliDeps,
+): Promise<number> {
+  const parsed = parseArgs(argv);
+  if ('error' in parsed) {
+    const reason = `${parsed.error}\n\n${USAGE}`;
+    return finish(io, env, 'could_not_run', couldNotRun('this change', reason));
+  }
+  if (parsed.help) {
+    io.stdout(`${USAGE}\n`);
+    return 0;
+  }
+  const title = parsed.title;
+  const fail = (reason: string, source?: string): Promise<number> =>
+    finish(io, env, 'could_not_run', couldNotRun(title, reason, source));
+
+  try {
+    // 0. Derived lenses (--practices), settled before settings or any diff.
+    if (parsed.practices !== undefined && parsed.lenses !== undefined) {
+      return await fail(
+        '--practices and --lenses cannot be used together; choose one lens source.',
+      );
+    }
+    if (parsed.printLenses && parsed.practices === undefined) {
+      return await fail('--print-lenses needs --practices <dir>.');
+    }
+    let derived: DerivedLenses | undefined;
+    let bar: string | undefined;
+    if (parsed.practices !== undefined) {
+      const dir = parsed.practices;
+      // The grading rules (README), read first so its failure has its own reason.
+      let readme: string;
+      try {
+        readme = await io.readFile(`${dir}/README.md`);
+      } catch (cause) {
+        return await fail(
+          `The practices README at ${dir}/README.md could not be read, so the review has no ` +
+            'grading rules (reject / accept / expect): ' +
+            `${cause instanceof Error ? cause.message : String(cause)}`,
+        );
+      }
+      try {
+        const names = (await io.readDir(dir)).filter(
+          (n) => n.endsWith('.md') && n.toLowerCase() !== 'readme.md',
+        );
+        const files = await Promise.all(
+          names.map(async (name) => ({ name, text: await io.readFile(`${dir}/${name}`) })),
+        );
+        derived = deriveLensSet(files);
+      } catch (cause) {
+        return await fail(
+          `The practices under ${dir} could not be read: ` +
+            `${cause instanceof Error ? cause.message : String(cause)}`,
+        );
+      }
+      if (derived.untagged.length > 0) {
+        io.stderr(
+          `warning: ${String(derived.untagged.length)} practice(s) with no "lens:" tag are ` +
+            `not reviewed: ${derived.untagged.join(', ')}\n`,
+        );
+      }
+      for (const [lensId, own] of Object.entries(derived.signals)) {
+        if (own.length === 0) {
+          io.stderr(
+            `warning: lens ${lensId} has no _Reject:_ / _Expect:_ signal lines, so every ` +
+              'blocking finding it raises will be downgraded to a smell.\n',
+          );
+        }
+      }
+      if (derived.groups.length === 0) {
+        return await fail(
+          `No practice under ${dir} carries a "lens:" front-matter value, so no lens could be ` +
+            'derived. Refusing to review against nothing.',
+        );
+      }
+      const extracted = extractBar(readme);
+      if (!extracted.ok) {
+        return await fail(
+          `The practices README at ${dir}/README.md cannot supply the grading rules: ` +
+            `${extracted.reason}.`,
+        );
+      }
+      bar = extracted.text;
+      if (parsed.printLenses) {
+        const out = {
+          barLength: bar.length,
+          lenses: derived.lensSet.lenses.map((lens) => ({
+            id: lens.id,
+            practices: derived?.groups.find((g) => g.lensId === lens.id)?.practiceIds ?? [],
+            focusLength: lens.focus.length,
+          })),
+          untagged: derived.untagged,
+          missingSensor: derived.missingSensor,
+        };
+        io.stdout(`${JSON.stringify(out, null, 2)}\n`);
+        return 0;
+      }
+      if (derived.missingSensor.length > 0) {
+        return await fail(
+          `Tagged practice(s) have no Sensor / Look for text, so a lens would check them ` +
+            `against nothing: ${derived.missingSensor.join(', ')}.`,
+        );
+      }
+    }
+
+    // 1. Settings, before anything costs money.
+    const problems: string[] = [];
+    // --print-prompt makes no model call, so it needs no key.
+    const resolved: AccountResolution = parsed.printPrompt
+      ? { kind: 'ok', account: { kind: 'subscription' }, route: 'claude-cli' }
+      : await resolveAccount(env, io);
+    if (resolved.kind === 'problem') problems.push(resolved.problem);
+    const model = present(env['AIGENCY_REVIEW_MODEL']) ?? DEFAULT_MODEL;
+    let maxTokens = DEFAULT_MAX_TOKENS;
+    const rawMax = present(env['AIGENCY_REVIEW_MAX_TOKENS']);
+    if (rawMax !== undefined) {
+      const n = Number(rawMax);
+      if (!Number.isSafeInteger(n) || n <= 0) {
+        problems.push(
+          `AIGENCY_REVIEW_MAX_TOKENS must be a positive whole number, got ${JSON.stringify(rawMax)}`,
+        );
+      } else {
+        maxTokens = n;
+      }
+    }
+    if (resolved.kind === 'problem' || problems.length > 0) {
+      return await fail(
+        `The configuration is present and wrong:\n\n${problems.map((p) => `- ${p}`).join('\n')}`,
+      );
+    }
+    const account = resolved.account;
+    const route = resolved.route;
+
+    // 2. The diff.
+    let diff: string;
+    if (parsed.base !== undefined) {
+      try {
+        diff = await deps.git(['diff', '--merge-base', parsed.base, 'HEAD']);
+      } catch (cause) {
+        return await fail(
+          `The diff could not be obtained from \`git diff --merge-base ${parsed.base} HEAD\`: ` +
+            `${cause instanceof Error ? cause.message : String(cause)}\n\n` +
+            'Check the ref exists and that the checkout has full history (fetch-depth: 0).',
+        );
+      }
+    } else {
+      diff = await io.readStdin();
+    }
+    if (diff.trim() === '') {
+      return await fail(
+        'The diff was empty, so there was nothing to review.\n\n' +
+          'This is almost always a wiring problem rather than an empty change: a diff computed ' +
+          'against the wrong base, or a shallow clone with no merge base. Check how the diff was ' +
+          'produced before concluding the change is empty.',
+      );
+    }
+
+    // 2a. The PR description: --description-file, else a one-line note that
+    // none was supplied (so the lenses do not judge an empty description).
+    let description = NO_DESCRIPTION_NOTE;
+    if (parsed.descriptionFile !== undefined) {
+      let text: string;
+      try {
+        text = await io.readFile(parsed.descriptionFile);
+      } catch (cause) {
+        return await fail(
+          `The description file ${parsed.descriptionFile} could not be read: ` +
+            `${cause instanceof Error ? cause.message : String(cause)}`,
+        );
+      }
+      if (text.trim() === '') {
+        return await fail(
+          `The description file ${parsed.descriptionFile} is blank. Omit --description-file ` +
+            'if there is no description.',
+        );
+      }
+      description = text.trim();
+    }
+
+    // 2a'. CI check results: --checks-file, else a one-line note that none were supplied.
+    let checks = NO_CHECKS_NOTE;
+    if (parsed.checksFile !== undefined) {
+      let text: string;
+      try {
+        text = await io.readFile(parsed.checksFile);
+      } catch (cause) {
+        return await fail(
+          `The checks file ${parsed.checksFile} could not be read: ` +
+            `${cause instanceof Error ? cause.message : String(cause)}`,
+        );
+      }
+      if (text.trim() === '') {
+        return await fail(
+          `The checks file ${parsed.checksFile} is blank. Omit --checks-file if there are no ` +
+            'check results.',
+        );
+      }
+      checks = `${text.trim()}\n\n${RED_CI_NOTE}`;
+    }
+
+    // 2b. Whole-file context: --context-root, else the current directory in
+    // --base mode, else none (said in one line, not an error).
+    const contextRoot = parsed.contextRoot ?? (parsed.base !== undefined ? '.' : undefined);
+    let fileContext = NO_FILE_CONTEXT_NOTE;
+    let references: string | undefined;
+    if (contextRoot !== undefined) {
+      try {
+        const fs = {
+          realpath: io.realpath,
+          statFile: io.statFile,
+          readFile: io.readFile,
+        };
+        fileContext = await buildFileContext(diff, contextRoot, fs);
+        references = await buildReferences(diff, contextRoot, {
+          ...fs,
+          ...(io.listDir === undefined ? {} : { listDir: io.listDir }),
+        });
+      } catch (cause) {
+        return await fail(
+          `The file context could not be built: ${
+            cause instanceof Error ? cause.message : String(cause)
+          }`,
+        );
+      }
+    }
+    const subject = {
+      title,
+      description,
+      diff,
+      fileContext,
+      checks,
+      ...(references === undefined ? {} : { references }),
+    };
+
+    // 3. The lens set: --lenses, else AIGENCY_REVIEW_LENSES, else bundled.
+    const lensPath = parsed.lenses ?? present(env['AIGENCY_REVIEW_LENSES']);
+    const source =
+      derived !== undefined
+        ? `practices in ${parsed.practices ?? ''} (derived: one lens per lens: value)`
+        : (lensPath ?? 'bundled default lenses (aigency-governance review/lenses.json @ de238aa)');
+    let lensSet: LensSet;
+    try {
+      if (derived !== undefined) {
+        lensSet = derived.lensSet;
+      } else {
+        const text =
+          lensPath === undefined ? await deps.defaultLenses() : await io.readFile(lensPath);
+        lensSet = parseLensSet(text);
+      }
+    } catch (cause) {
+      return await fail(
+        `The lens set could not be loaded: ${cause instanceof Error ? cause.message : String(cause)}`,
+        source,
+      );
+    }
+
+    // 3b. --print-prompt: the exact prompt one lens would be sent; no reviewer call.
+    if (parsed.printPrompt !== undefined) {
+      const lens = lensSet.lenses.find((l) => l.id === parsed.printPrompt);
+      if (lens === undefined) {
+        return await fail(
+          `--print-prompt names lens ${JSON.stringify(parsed.printPrompt)}, which is not in the ` +
+            `lens set (${lensSet.lenses.map((l) => l.id).join(', ')}).`,
+          source,
+        );
+      }
+      io.stdout(`${renderPrompt(buildPrompt(lens, subject, bar))}\n`);
+      return 0;
+    }
+
+    // 4. The panel.
+    const calls: RawCall[] = [];
+    const result = await runReviewNode(
+      {
+        subject,
+        ...(bar === undefined ? {} : { practices: bar }),
+        lensSet,
+        lensSetSource: source,
+        account,
+        model,
+        maxTokens,
+        ...(deps.reviewer === undefined ? {} : { reviewer: deps.reviewer }),
+        warmFirst: parsed.warmFirst,
+        dedup: parsed.dedup,
+        ...(derived === undefined
+          ? {}
+          : { tierSignals: derived.signals, practiceNames: derived.practiceNames }),
+      },
+      (call) => void calls.push(call),
+    );
+    for (const line of usageLines(calls)) io.stderr(line);
+    const tier = tierLine(result.downgraded);
+    if (tier !== undefined) io.stderr(`${tier}\n`);
+    const footer = `\n\n${renderFooter(model, route, calls, result.downgraded)}`;
+    const note =
+      derived !== undefined && derived.untagged.length > 0
+        ? `\n\n> ${String(derived.untagged.length)} practice(s) had no "lens:" tag and were ` +
+          `not reviewed: ${derived.untagged.join(', ')}`
+        : '';
+    return await finish(
+      io,
+      env,
+      result.verdict.outcome,
+      result.report + note + footer,
+      result.exitCode,
+    );
+  } catch (cause) {
+    // Defect at the boundary, not a verdict about the change.
+    return fail(
+      `Unexpected failure: ${cause instanceof Error ? cause.message : String(cause)}. ` +
+        'This is a defect in the runner, not a verdict about the change.',
+    );
+  }
+}
+
+async function finish(
+  io: ReviewIo,
+  env: Record<string, string | undefined>,
+  outcome: ResultWord,
+  report: string,
+  exitCode: number = 1,
+): Promise<number> {
+  io.stdout(`${report}\n`);
+  const summary = present(env['GITHUB_STEP_SUMMARY']);
+  if (summary !== undefined) {
+    try {
+      await io.appendFile(summary, `${report}\n`);
+    } catch (cause) {
+      // The verdict stands; a summary that could not be written is said, not hidden.
+      io.stderr(
+        `warning: could not append to GITHUB_STEP_SUMMARY: ${
+          cause instanceof Error ? cause.message : String(cause)
+        }\n`,
+      );
+    }
+  }
+  io.stderr(`RESULT: ${outcome}\n`);
+  return exitCode;
+}