@verevoir/review 0.2.0 → 0.3.0

package/dist/warm-first.d.ts

@@ -0,0 +1,2 @@
+import type { Reviewer } from './panel.js';
+export declare function warmFirst(reviewer: Reviewer): Reviewer;

package/dist/warm-first.js

@@ -0,0 +1,21 @@
+// Cache warm-up for the fan. runPanel dispatches every lens at once, so with a
+// provider prompt cache each lens writes the same shared prefix and none reads
+// it. `warmFirst` wraps a Reviewer so the FIRST call made runs alone, and every
+// later call waits for it to settle (success or failure) before starting: the
+// rest then read the prefix the first one wrote.
+//
+// The seam is the Reviewer itself, so runPanel is untouched. The first caller
+// is whichever lens runPanel invokes first (the first lens in the set); the
+// check-and-set below runs synchronously within that first call, before any
+// await, so no later call can also believe it is first.
+export function warmFirst(reviewer) {
+    let first;
+    return (lensId, prompt) => {
+        if (first === undefined) {
+            const call = reviewer(lensId, prompt);
+            first = call.then(() => undefined, () => undefined);
+            return call;
+        }
+        return first.then(() => reviewer(lensId, prompt));
+    };
+}

package/lenses.default.json

@@ -0,0 +1,30 @@
+{
+  "version": 1,
+  "lenses": [
+    {
+      "id": "correctness",
+      "title": "Correctness",
+      "focus": "Does the change do what the diff, its comments and its description say it does? Read the claim and the code as two independent assertions and look for the gap between them. Prefer a concrete failing input over a description of a risk. This dimension judges work performed against a claim about it, not a description of a requirement: where the change under review is itself a description of a requirement, there is no behaviour yet for this lens to check — answer out_of_scope rather than manufacturing a gap between a description and work that does not exist yet."
+    },
+    {
+      "id": "honesty",
+      "title": "Honesty of the record",
+      "focus": "Anything that reports a state it did not observe: a comment claiming a property the code does not have, a log line or return value describing work that did not happen, a success reported over an empty result, documentation asserting a behaviour the implementation lacks. This still applies in full where a description of a requirement makes a false claim about the system's CURRENT state — that is exactly as dishonest there as anywhere else. But a description of a requirement is not dishonest merely for reporting no success — the absence of a completion claim is not itself a finding, and must not be written up as one."
+    },
+    {
+      "id": "failure-modes",
+      "title": "Failure distinguishable from silence",
+      "focus": "Where the change can fail, can a reader tell which failure happened? Missing, empty and broken must stay three answers. A swallowed error, a catch that returns a default, or a single word covering two outcomes belongs here. This judges error handling that exists in the change. A description of a requirement has no catch, return or logged outcome yet — answer out_of_scope, not a review of prose about intended handling as though it were the handling itself."
+    },
+    {
+      "id": "verification",
+      "title": "Verification that verifies",
+      "focus": "Would each new or changed test fail if the code it covers were wrong? Look for assertions that hold vacuously, suites that pass because they found nothing to run, and guards whose only test exercises the pure function underneath rather than the guard. This judges a test that exists in the change. A description of a requirement — including one describing what a future test must prove — has no test yet for this lens to check against; answer out_of_scope, not a verdict on a stated intention."
+    },
+    {
+      "id": "blast-radius",
+      "title": "Scope, collateral and credentials",
+      "focus": "What does this change touch that it did not need to touch? Reformatting, drive-by renames, widened permissions, a credential reaching a wider process than before, or a bound that moved without being named."
+    }
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@verevoir/review",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "The review panel: lens-based diff review. One implementation, consumed by pump-internal review, local preflight, eval-review, and CI.",
   "license": "Apache-2.0",
   "type": "module",
@@ -12,8 +12,12 @@
       "import": "./dist/index.js"
     }
   },
+  "bin": {
+    "aigency-review": "./dist/cli/bin.js"
+  },
   "files": [
     "dist",
+    "lenses.default.json",
     "src",
     "tsconfig.json",
     "tsconfig.build.json",

package/src/cli/bin.ts

@@ -0,0 +1,61 @@
+#!/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: NodeJS.ReadableStream): Promise<string> {
+  const chunks: string[] = [];
+  stream.setEncoding('utf8');
+  for await (const chunk of stream) chunks.push(chunk as string);
+  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: unknown) => {
+    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/src/cli/footer.ts

@@ -0,0 +1,78 @@
+// 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.
+
+import type { RawCall } from '../raw-call.js';
+
+export type RouteName = 'env' | 'key-file' | 'claude-cli';
+
+function seconds(ms: number): string {
+  return `${(ms / 1000).toFixed(1)}s`;
+}
+
+function byLens(calls: readonly RawCall[]): RawCall[] {
+  return calls.slice().sort((a, b) => (a.lens < b.lens ? -1 : a.lens > b.lens ? 1 : 0));
+}
+
+function tokens(call: RawCall): string {
+  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: string, calls: readonly RawCall[]): string {
+  const resolved = [
+    ...new Set(calls.map((c) => c.resolved).filter((m): m is string => 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: number): string | undefined {
+  return downgraded > 0
+    ? `Tier: ${String(downgraded)} blocking finding(s) downgraded: no Reject/Expect signal quoted`
+    : undefined;
+}
+
+export function renderFooter(
+  requested: string,
+  route: RouteName,
+  calls: readonly RawCall[],
+  downgraded = 0,
+): string {
+  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: readonly RawCall[]): string[] {
+  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`,
+  );
+}