@verevoir/review 0.2.0 → 0.3.1

package/dist/tier.js

@@ -0,0 +1,172 @@
+// Enforces the tier in code. A derived lens is told to tag a finding [blocking] only when it
+// quotes the signal it fails, but a model honours that loosely. After parsing, every [blocking]
+// finding of a derived lens is checked against THAT lens's own practices' `_Reject:_` /
+// `_Expect:_` lines; one that quotes none is downgraded to [smell]. The mirror: a [smell]
+// finding that quotes one of the lens's own `_Reject:_` lines (not `_Expect:_`) is promoted to
+// [blocking], because the bar says a Reject blocks anywhere. The lens's outcome is then
+// recomputed. Deterministic: no model call.
+//
+// MATCHING RULE. Both sides are normalised (lower-cased; markdown emphasis `*` `_` and
+// backticks removed; quote marks removed; runs of whitespace collapsed to one space). A
+// finding (summary + detail) quotes a signal line when it contains a contiguous
+// MIN_QUOTE-character (24) run of the signal's normalised text, or the whole normalised line
+// when the line is shorter than that.
+//
+// PRACTICE IDS DO NOT COUNT AS QUOTING. Lens signal lines cross-reference other practices by id
+// (a Reject line may say "see complexity-matches-the-problem"), so a finding that merely NAMES
+// that id would otherwise match 24+ characters without quoting anything. Before matching, every
+// practice id of the corpus (and any backticked kebab-case token) is replaced, in BOTH the
+// signal line and the finding, by a break mark. A run of 24 characters can then never span or
+// consist of an id, and a signal line that is only ids has nothing left to quote. Chosen over
+// "the run must contain a non-id word": stripping is one rule applied to both sides, and it
+// cannot be satisfied by an id plus one filler word.
+//
+// WORD BOUNDARIES. After normalising, every run of characters that are not letters or digits
+// becomes one space, and both sides are padded with a space at each end. So the start or end of
+// a text, and punctuation beside a word, all read as the same single space: a phrase at the
+// start of a finding, after "(", or before ":" matches as it would after a space. The
+// 24-character bar is unchanged; "unpinned/unremarked" is still not "unpinned and unremarked".
+import { aggregate } from './verdict.js';
+/** The shortest verbatim run of a signal line that counts as quoting it. */
+export const MIN_QUOTE = 24;
+/** Appended to the summary of a finding that was downgraded. */
+export const DOWNGRADE_NOTE = ' (downgraded: no signal quoted)';
+/** Appended to the summary of a smell that was promoted. */
+export const PROMOTE_NOTE = ' (promoted: quotes a Reject signal)';
+export function normaliseForQuote(text) {
+    return text
+        .replace(/[*_`]/g, '')
+        .replace(/["'‘’“”«»]/g, '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .toLowerCase();
+}
+/** Stands where an id was; survives normalisation and cannot occur in prose. */
+const ID_MARK = '\u0001';
+const BACKTICKED_ID = /`[a-z0-9]+(?:-[a-z0-9]+)+`/g;
+function escapeRegExp(text) {
+    return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function idPattern(ids) {
+    const sorted = [...new Set(ids.map((id) => id.toLowerCase()).filter((id) => id !== ''))].sort((a, b) => b.length - a.length);
+    if (sorted.length === 0)
+        return undefined;
+    return new RegExp(`(?<![a-z0-9-])(?:${sorted.map(escapeRegExp).join('|')})(?![a-z0-9-])`, 'g');
+}
+function markIds(text, pattern) {
+    const marked = text.toLowerCase().replace(BACKTICKED_ID, ID_MARK);
+    return pattern === undefined ? marked : marked.replace(pattern, ID_MARK);
+}
+/** Normalised, punctuation read as a space, padded with a space each end; '' when nothing is left. */
+function boundaryForm(text) {
+    const spaced = normaliseForQuote(text)
+        .replace(/[^\p{L}\p{N}\u0001]+/gu, ' ')
+        .trim();
+    return spaced === '' ? '' : ` ${spaced} `;
+}
+/** A 24-character run of `needle` in `haystack`; a needle of 24 or fewer only whole, if allowed. */
+function quotesRun(haystack, needle, wholeIfShort) {
+    if (needle === '')
+        return false;
+    if (needle.length <= MIN_QUOTE)
+        return wholeIfShort && haystack.includes(needle);
+    for (let i = 0; i + MIN_QUOTE <= needle.length; i++) {
+        if (haystack.includes(needle.slice(i, i + MIN_QUOTE)))
+            return true;
+    }
+    return false;
+}
+/**
+ * Whether `text` contains a verbatim quote (per the rule above) of any of `signals`.
+ * `practiceIds` are the corpus's practice ids, which are ignored on both sides.
+ */
+export function quotesSignal(text, signals, practiceIds = []) {
+    const pattern = idPattern(practiceIds);
+    const haystack = boundaryForm(markIds(text, pattern));
+    for (const signal of signals) {
+        const marked = markIds(signal, pattern);
+        if (marked.includes(ID_MARK)) {
+            // Each stretch between ids is quoted (or not) on its own; a short one never counts.
+            for (const stretch of marked.split(ID_MARK)) {
+                if (quotesRun(haystack, boundaryForm(stretch), false))
+                    return true;
+            }
+        }
+        else if (quotesRun(haystack, boundaryForm(marked), true)) {
+            return true;
+        }
+    }
+    return false;
+}
+// Same test as verdict.ts's: a [blocking] line whose text begins "none" says "nothing found".
+const NONE_SENTINEL = /^none(?:\s*$|\s*[-—]\s)/;
+function isNone(finding) {
+    return NONE_SENTINEL.test(finding.summary.trim());
+}
+function hasBlocking(findings) {
+    return findings.some((f) => f.blocking && !isNone(f));
+}
+/**
+ * Downgrade unquoted [blocking] findings of every lens that has an entry in `signals`, promote
+ * smells that quote one of the lens's own Reject lines (`context.rejects`), then re-aggregate.
+ * A lens that was `rejected` and is left with no [blocking] finding counts as `approved`; one
+ * that was `approved` and gained a promoted finding counts as `rejected`; either is marked
+ * `tierAdjusted`. Lenses without an entry (bundled lenses) are untouched. With nothing changed
+ * the verdict is returned as it was.
+ */
+export function enforceTier(verdict, signals, context = {}) {
+    const ids = context.practiceIds ?? [];
+    let downgraded = 0;
+    let promoted = 0;
+    const results = verdict.results.map((result) => {
+        if (!Object.prototype.hasOwnProperty.call(signals, result.lens))
+            return result;
+        const own = signals[result.lens] ?? [];
+        const rejectLines = context.rejects !== undefined &&
+            Object.prototype.hasOwnProperty.call(context.rejects, result.lens)
+            ? (context.rejects[result.lens] ?? [])
+            : undefined;
+        let changed = false;
+        let lensPromoted = 0;
+        const findings = result.findings.map((finding) => {
+            if (isNone(finding))
+                return finding;
+            const text = `${finding.summary}\n${finding.detail ?? ''}`;
+            if (finding.blocking) {
+                if (quotesSignal(text, own, ids))
+                    return finding;
+                changed = true;
+                downgraded++;
+                return { ...finding, blocking: false, summary: `${finding.summary}${DOWNGRADE_NOTE}` };
+            }
+            if (rejectLines === undefined || !quotesSignal(text, rejectLines, ids))
+                return finding;
+            changed = true;
+            promoted++;
+            lensPromoted++;
+            return { ...finding, blocking: true, summary: `${finding.summary}${PROMOTE_NOTE}` };
+        });
+        if (!changed)
+            return result;
+        const outcome = result.outcome === 'rejected' && !hasBlocking(findings)
+            ? 'approved'
+            : result.outcome === 'approved' && lensPromoted > 0
+                ? 'rejected'
+                : result.outcome;
+        // The lens's own reason text is not regenerated, so a changed word must say who changed it.
+        return {
+            ...result,
+            outcome,
+            findings,
+            ...(outcome === result.outcome ? {} : { tierAdjusted: true }),
+        };
+    });
+    if (downgraded === 0 && promoted === 0)
+        return { verdict, downgraded, promoted };
+    // Prior-round rulings are carried on each result; the CLI never supplies orphaned ones.
+    return {
+        verdict: aggregate(verdict.results.map((r) => r.lens), results),
+        downgraded,
+        promoted,
+    };
+}

package/dist/verdict.d.ts

@@ -30,6 +30,9 @@ export interface LensResult {
     /** Why this lens could not run, or why it found nothing in scope.
      * Meaningless on `approved` and `rejected`. */
     readonly reason?: string;
+    /** True when tier enforcement (tier.ts) changed this lens's outcome after the model gave it,
+     * so the model's own `reason` text no longer matches. Absent otherwise. */
+    readonly tierAdjusted?: boolean;
     /**
      * This lens's own rulings on whichever prior blocking findings were
      * attributed to it (`Subject.priorFindings`, filtered by lens). Present

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.1",
   "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,88 @@
+// 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;
+}
+
+/** The one line saying how many smells tier enforcement promoted to [blocking]; none for 0. */
+export function promotedLine(promoted: number): string | undefined {
+  return promoted > 0
+    ? `Tier: ${String(promoted)} finding(s) promoted: quotes a Reject signal`
+    : undefined;
+}
+
+export function renderFooter(
+  requested: string,
+  route: RouteName,
+  calls: readonly RawCall[],
+  downgraded = 0,
+  promoted = 0,
+): string {
+  const lines = ['---', '', `Judged with ${modelText(requested, calls)}, route: ${route}.`];
+  const tier = tierLine(downgraded);
+  if (tier !== undefined) lines.push('', tier);
+  const promotion = promotedLine(promoted);
+  if (promotion !== undefined) lines.push('', promotion);
+  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`,
+  );
+}