@verevoir/review 0.2.0 → 0.3.0

package/README.md

@@ -19,8 +19,8 @@ own header, and the seed commit message, for exactly what moved and why.
 
 **Known gaps in this PR**, named rather than silently absorbed:
 
-- No CLI bin yet (no consumer needs it until the preflight/eval-review/CI
-  Action cutover PRs).
+- The CLI (`aigency-review`, below) is a port of governance's; see "Command
+  line" for what was deliberately not ported.
 
 All nine of v5's review test suites are ported (see "Tests" below, not
 two), and the ported-file doc debt (stale README/ownership references) is
@@ -298,6 +298,136 @@ aigency-runtime-v2, from round 2 of an implement↔review loop onward) is
 responsible for assembling the array from its own prior verdict's
 blocking findings before calling `runPanel`/`runReviewNode` again.
 
+## Command line
+
+`aigency-review` runs the panel over a diff from any repository, including a
+public one that cannot call governance's private reusable workflow:
+
+```sh
+npx -y @verevoir/review aigency-review --base origin/main --title "My change"
+git diff origin/main...HEAD | npx -y @verevoir/review aigency-review
+```
+
+**Flags**
+
+- `--base <ref>` -- review `git diff --merge-base <ref> HEAD` (run via
+  `execFile`, no shell). Needs full history. Without it, the diff is read from
+  stdin.
+- `--title <text>` -- shown at the top of the report (default `this change`).
+- `--lenses <path>` -- a lens set JSON file. Else `AIGENCY_REVIEW_LENSES`, else
+  the bundled default.
+- `--description-file <path>` -- the PR description, shown under `## The change`.
+  Unreadable or blank is `could_not_run`. Without it the prompt says, in one
+  line, that no description was supplied and not to judge it.
+- `--checks-file <path>` -- CI check results, rendered verbatim in the shared prompt under
+  `## Checks on this change` (after `## The change`, before `## The diff`). Unreadable or
+  blank is `could_not_run`. Without it the prompt says, in one line, that no check results
+  were supplied and not to assume the tests pass.
+- References in added lines (automatic with a context root) -- ADR citations (`ADR 009`,
+  `ADR-009`, `ADR 9`) and repo-relative file paths in the diff's ADDED lines are resolved
+  deterministically (no model call) and rendered under `## References in added lines`, after
+  `## Changed files in full`. An ADR is looked up in directories named `adrs` or `adr` (depth
+  4, skipping `node_modules`, `.git`, `dist`) and shown with its path and first heading, or
+  "not found in this repository"; a path is reported as existing or not. At most 40 are
+  resolved. `..`, absolute paths and root-escaping symlinks are refused.
+- With `--practices`, every lens also gets a tier anchor (tag `[blocking]` only when quoting
+  the signal failed) and is asked for a `REASON:` line; the report shows every lens as
+  `#### <lens>: <verdict>: <reason>`, approving lenses included.
+- With `--practices`, the tier is enforced in code. After each lens's reply is parsed, every
+  `[blocking]` finding must contain a verbatim quote of one of THAT lens's practices'
+  `_Reject:_` / `_Expect:_` lines: after lower-casing and removing markdown emphasis, quote
+  marks and extra whitespace on both sides, a contiguous run of at least 24 characters of the
+  signal line (or all of a shorter line). Otherwise it becomes `[smell]` with
+  " (downgraded: no signal quoted)", and a lens left with no blocking finding counts as
+  approved. Bundled lenses are unchanged.
+- De-duplication: after the panel, ONE extra call through the same reviewer asks which findings
+  (ids `lens:index`) describe the same defect. The reply must put every id in exactly one
+  group; otherwise (or if the call fails) the un-merged report is kept with a line saying
+  de-duplication was skipped and why. Each group is shown once, at its highest tier, with its
+  first member's text and `raised by: <lens> (<practices>), ...`. Per-lens verdict lines are
+  unchanged, and the call's usage appears in the footer as `dedup`. `--no-dedup` skips it. It is
+  also skipped when fewer than two findings were raised.
+- With `--checks-file`, the checks section ends with: "If a check fails, report it once, then
+  review the rest of the change on its own merits, as if that failure were fixed."
+- `--warm-first` / `--no-warm-first` -- run the first lens alone, then fan out
+  the rest, so they read the prompt cache the first wrote instead of every lens
+  writing the same prefix. On by default with 2 or more lenses; costs roughly one
+  extra lens-latency of wall time. A first lens that fails does not stop the rest.
+- `--context-root <dir>` -- a tree at the change's head. Each file the diff
+  touches (paths from the `+++` headers) that still exists there is shown in
+  full, post-change, if it is 16 KB or smaller, in a shared
+  `## Changed files in full` section after `## The diff`; skipped files are listed with the reason
+  (too large, deleted, not present, binary). Paths with `..` or absolute paths
+  are refused, and so is any file whose resolved real path (symlinks followed)
+  leaves the root. With `--base` it defaults to the current directory (run from
+  the repo root); with stdin and no `--context-root` the prompt says in one line
+  that there is no file context.
+- `-h`, `--help`.
+
+**Environment**
+
+- `ANTHROPIC_API_KEY` -- billed route. Else `ANTHROPIC_API_KEY_FILE`, else
+  `$XDG_CONFIG_HOME/verevoir/anthropic.key` (or `~/.config/verevoir/anthropic.key`).
+  With no key anywhere the logged-in `claude` CLI is used. A key file that is
+  unreadable or blank, or a named `ANTHROPIC_API_KEY_FILE` that does not exist,
+  blocks the run rather than silently falling back.
+- `AIGENCY_REVIEW_LENSES` -- lens set path (see above).
+- `AIGENCY_REVIEW_MODEL` -- default `claude-opus-5-5`.
+- `AIGENCY_REVIEW_MAX_TOKENS` -- positive integer, default `65536`.
+- `GITHUB_STEP_SUMMARY` -- when set, the report is appended to that file.
+
+**Report footer.** The report ends with what judged it: the model (the id the
+transport reported, else the requested one, said as such), the reviewer route by
+name only (`env`, `key-file` or `claude-cli` -- never a key or a path), and one
+per-lens line with input/output tokens (and cache tokens when non-zero) and wall
+time. The same per-lens lines go to stderr. A route that reports no usage says
+`usage not reported`.
+
+**Output.** The markdown report goes to stdout; `RESULT: approved|out_of_scope|rejected|could_not_run`
+goes to stderr.
+
+**Exit codes** (from `exitCodeFor`, as in governance): `approved` and
+`out_of_scope` exit `0`; `rejected` and `could_not_run` exit `1`. Anything
+that stops a verdict (bad config, no diff, empty diff, unreadable lens set, a
+bad flag) is `could_not_run`: red, never a pass.
+
+**Bundled lenses.** `lenses.default.json` is a copy of
+`verevoir/aigency-governance` `review/lenses.json` at commit `de238aa`. It is a
+snapshot, refreshed deliberately.
+
+**Not ported from governance's CLI**: fetching the lens set over HTTP
+(`AIGENCY_REVIEW_LENSES_TOKEN`/`GITHUB_TOKEN`; paths only here), the
+cited-file context built from the checkout (`citations`/`readers`), and
+governance's `practices` fetch. The title is `--title`, not `argv[2]`.
+
+**Derived lenses (trial, BL-424).** `--practices <dir>` reads the `*.md`
+files directly under `<dir>` (a guardrails checkout's `corpus/practices`),
+groups them by their front-matter `lens:` value, and makes one lens per value
+(id and title are the value; focus is a fixed adversarial sentence plus the
+group's `**Sensor**` / `**Look for**` text). Practices with no `lens:` are
+warned about on stderr, reviewed by nothing, and counted in the report. A
+tagged practice with no sensor text is `could_not_run`. It cannot be combined
+with `--lenses`. `--print-lenses` (needs `--practices`) prints each lens's id,
+practice ids and focus length as JSON and exits 0 with no diff and no model
+call. `<dir>/README.md` must exist: its "Signals: reject / accept / expect" section and
+the "keyed to different tiers" provenance paragraph are sent to every lens as the
+bar (missing or without those headings is `could_not_run`). Each practice's sensor
+is headed `### <id>: <title>`. `--print-prompt <lens-id>` prints the exact prompt
+that lens would be sent for the diff and exits 0 with no model call.
+Front-matter is parsed by a minimal reader (only the `lens:` line, as in
+v2); no YAML library.
+
+**GitHub Actions**
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+- run: npx -y @verevoir/review@<next> aigency-review --base origin/${{ github.base_ref }} --title "${{ github.event.pull_request.title }}"
+  env:
+    ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
+```
+
 ## Merge policy
 
 Merges on green, same as this organisation's other rebuild repos. "Green"

package/dist/cli/bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/bin.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+/// <reference types="node" />
+// The process boundary for `aigency-review`: construct the real adapters and
+// hand them to `main` (review.ts). No decision lives here.
+import { execFile } from 'node:child_process';
+import { appendFile, readFile, readdir, realpath, stat } from 'node:fs/promises';
+import process from 'node:process';
+import { promisify } from 'node:util';
+import { main } from './review.js';
+const execFileAsync = promisify(execFile);
+async function readAll(stream) {
+    const chunks = [];
+    stream.setEncoding('utf8');
+    for await (const chunk of stream)
+        chunks.push(chunk);
+    return chunks.join('');
+}
+main(process.argv.slice(2), process.env, {
+    readStdin: () => readAll(process.stdin),
+    stdout: (text) => void process.stdout.write(text),
+    stderr: (text) => void process.stderr.write(text),
+    readFile: (path) => readFile(path, 'utf8'),
+    appendFile: (path, text) => appendFile(path, text, 'utf8'),
+    readDir: async (path) => (await readdir(path, { withFileTypes: true })).filter((e) => e.isFile()).map((e) => e.name),
+    listDir: async (path) => (await readdir(path, { withFileTypes: true })).map((e) => ({
+        name: e.name,
+        isDir: e.isDirectory(),
+    })),
+    realpath: (path) => realpath(path),
+    statFile: async (path) => {
+        const s = await stat(path);
+        return { size: s.size, isFile: s.isFile() };
+    },
+}, {
+    // execFile, no shell: a ref is an argument, never parsed as a command.
+    git: async (args) => (await execFileAsync('git', [...args], { maxBuffer: 512 * 1024 * 1024 })).stdout,
+    // dist/cli/bin.js and src/cli/bin.ts both sit two levels under the package root.
+    defaultLenses: () => readFile(new URL('../../lenses.default.json', import.meta.url), 'utf8'),
+}).then((code) => {
+    process.exitCode = code;
+}, (cause) => {
+    const message = cause instanceof Error ? cause.message : String(cause);
+    process.stderr.write('RESULT: could_not_run\n');
+    process.stderr.write(`Unexpected failure: ${message}\n`);
+    process.exitCode = 1;
+});

package/dist/cli/footer.d.ts

@@ -0,0 +1,9 @@
+import type { RawCall } from '../raw-call.js';
+export type RouteName = 'env' | 'key-file' | 'claude-cli';
+/** The model(s) the transport reported, else the requested one, said as such. */
+export declare function modelText(requested: string, calls: readonly RawCall[]): string;
+/** The one line saying how many [blocking] findings tier enforcement downgraded; none for 0. */
+export declare function tierLine(downgraded: number): string | undefined;
+export declare function renderFooter(requested: string, route: RouteName, calls: readonly RawCall[], downgraded?: number): string;
+/** One stderr line per lens. */
+export declare function usageLines(calls: readonly RawCall[]): string[];

package/dist/cli/footer.js

@@ -0,0 +1,59 @@
+// What judged a review: the model, the route (by NAME only -- never a key or a
+// path), and per-lens token usage and wall time, from runReviewNode's `onCall`
+// records. Pure formatting.
+function seconds(ms) {
+    return `${(ms / 1000).toFixed(1)}s`;
+}
+function byLens(calls) {
+    return calls.slice().sort((a, b) => (a.lens < b.lens ? -1 : a.lens > b.lens ? 1 : 0));
+}
+function tokens(call) {
+    const u = call.usage;
+    if (u === undefined)
+        return 'usage not reported';
+    const cache = u.cacheReadInputTokens > 0 || u.cacheCreationInputTokens > 0
+        ? ` (cache read ${String(u.cacheReadInputTokens)}, cache write ` +
+            `${String(u.cacheCreationInputTokens)})`
+        : '';
+    return `${String(u.inputTokens)} input / ${String(u.outputTokens)} output tokens${cache}`;
+}
+/** The model(s) the transport reported, else the requested one, said as such. */
+export function modelText(requested, calls) {
+    const resolved = [
+        ...new Set(calls.map((c) => c.resolved).filter((m) => m !== null)),
+    ].sort();
+    if (resolved.length === 0) {
+        return `model \`${requested}\` (as requested; the transport reported none)`;
+    }
+    const names = resolved.map((m) => `\`${m}\``).join(', ');
+    return resolved.length === 1 && resolved[0] === requested
+        ? `model ${names}`
+        : `model ${names} (requested \`${requested}\`)`;
+}
+/** The one line saying how many [blocking] findings tier enforcement downgraded; none for 0. */
+export function tierLine(downgraded) {
+    return downgraded > 0
+        ? `Tier: ${String(downgraded)} blocking finding(s) downgraded: no Reject/Expect signal quoted`
+        : undefined;
+}
+export function renderFooter(requested, route, calls, downgraded = 0) {
+    const lines = ['---', '', `Judged with ${modelText(requested, calls)}, route: ${route}.`];
+    const tier = tierLine(downgraded);
+    if (tier !== undefined)
+        lines.push('', tier);
+    if (calls.length > 0) {
+        lines.push('', 'Per-lens usage and wall time:', '');
+        for (const call of byLens(calls)) {
+            lines.push(call.failure === undefined
+                ? `- \`${call.lens}\`: ${tokens(call)}, ${seconds(call.durationMs)}`
+                : `- \`${call.lens}\`: failed after ${seconds(call.durationMs)}`);
+        }
+    }
+    return lines.join('\n');
+}
+/** One stderr line per lens. */
+export function usageLines(calls) {
+    return byLens(calls).map((call) => call.failure === undefined
+        ? `lens ${call.lens}: ${tokens(call)}, ${seconds(call.durationMs)}\n`
+        : `lens ${call.lens}: failed after ${seconds(call.durationMs)}\n`);
+}

package/dist/cli/review.d.ts

@@ -0,0 +1,45 @@
+import type { Reviewer } from '../panel.js';
+import type { Outcome } from '../verdict.js';
+import type { DirEntry } from '../references.js';
+/** Governance's pinned default, sent to both routes. */
+export declare const DEFAULT_MODEL = "claude-opus-5-5";
+/** Governance's default output-token budget (billed route only). */
+export declare const DEFAULT_MAX_TOKENS = 65536;
+/** What the prompt's "## The change" shows when no --description-file was given. */
+export declare 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 declare 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 declare const RED_CI_NOTE: string;
+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>;
+}
+/**
+ * Run the review. Returns the process exit code; never throws (anything
+ * unexpected is reported as could_not_run).
+ */
+export declare function main(argv: readonly string[], env: Record<string, string | undefined>, io: ReviewIo, deps: ReviewCliDeps): Promise<number>;