@pugi/cli 0.1.0-alpha.9 → 0.1.0-beta.2

package/dist/runtime/commands/review-consensus.js

@@ -0,0 +1,399 @@
+/**
+ * `pugi review --consensus` — customer-facing triple-review (α6.7).
+ *
+ * The differentiator: Claude Code ships single-Claude review, Codex CLI
+ * ships single-GPT review, Gemini CLI ships single-Gemini review. Pugi
+ * ships a 3-model consensus gate as a first-class command so customers
+ * get the same production-readiness signal we use internally - without the
+ * three CLI installs, three OAuth flows, and three subscriptions.
+ *
+ * Flow:
+ *
+ *   1. Resolve diff source from flags (`--commit` / `--pr` / `--branch`
+ *      OR default to merge-base vs `origin/main`).
+ *   2. POST diff to Anvil's `POST /api/pugi/review-consensus`. Anvil
+ *      fans out to 3 reviewer routes server-side and streams an SSE.
+ *   3. Render per-reviewer state inline as the SSE stream emits events.
+ *   4. After the stream closes, recompute the rubric locally (never
+ *      trust the server's verdict - see anvil-fanout.ts) and print:
+ *        - per-reviewer summary
+ *        - rubric verdict + reasoning
+ *        - recommended next action
+ *   5. Exit with 0 PASS / 1 WARN / 2 BLOCK.
+ *
+ * Backend status: at α6.7 ship the admin-api endpoint is not yet
+ * deployed. The handler degrades gracefully — on `endpoint_missing`
+ * the CLI prints an actionable "backend not deployed yet" notice and
+ * exits 0 (the gate didn't run, but failing CI would be wrong because
+ * the operator did nothing wrong). The α6.7.1 sprint lands the server.
+ */
+import { captureDiff } from '../../core/consensus/diff-capture.js';
+import { dispatchConsensus, } from '../../core/consensus/anvil-fanout.js';
+import { aggregate, exitCodeFor, reviewerVerdictFromRaw, } from '../../core/consensus/rubric.js';
+/**
+ * Parse the command-line tail for the consensus selector + base ref. The
+ * arg list excludes the dispatcher's leading `review` keyword.
+ *
+ * Accepted forms:
+ *   `--commit <sha>` / `--commit=<sha>`
+ *   `--pr <number>` / `--pr=<number>`
+ *   `--branch <name>` / `--branch=<name>`
+ *   `--base <ref>` / `--base=<ref>`   (override default origin/main)
+ */
+export function parseConsensusArgs(args) {
+    const spec = {};
+    for (let i = 0; i < args.length; i += 1) {
+        const arg = args[i] ?? '';
+        const equalsIdx = arg.indexOf('=');
+        const key = equalsIdx === -1 ? arg : arg.slice(0, equalsIdx);
+        const inline = equalsIdx === -1 ? null : arg.slice(equalsIdx + 1);
+        const value = inline ?? args[i + 1] ?? '';
+        const consumed = inline !== null ? 0 : 1;
+        if (key === '--commit') {
+            if (!value)
+                throw new Error('--commit requires a SHA');
+            spec.commit = value;
+            i += consumed;
+        }
+        else if (key === '--pr') {
+            if (!value)
+                throw new Error('--pr requires a number');
+            const parsed = Number.parseInt(value, 10);
+            if (!Number.isFinite(parsed) || parsed <= 0) {
+                throw new Error(`--pr expects a positive integer, got "${value}"`);
+            }
+            spec.pr = parsed;
+            i += consumed;
+        }
+        else if (key === '--branch') {
+            if (!value)
+                throw new Error('--branch requires a name');
+            spec.branch = value;
+            i += consumed;
+        }
+        else if (key === '--base') {
+            if (!value)
+                throw new Error('--base requires a ref');
+            spec.baseRef = value;
+            i += consumed;
+        }
+        // Unknown args are dropped — `--consensus` itself, `--remote`, `--json`
+        // and other passthrough flags are interpreted by the cli.ts parser
+        // before this function ever sees them.
+    }
+    return spec;
+}
+/**
+ * Run the consensus review. Returns the intended process exit code so
+ * the caller owns the global `process.exitCode` write. This avoids the
+ * REPL leak where a slash-invocation would otherwise inherit a stale
+ * exit code from a previous consensus run.
+ *
+ * Exit code contract (matches `handleFanoutFailure` + `exitCodeFor`):
+ *
+ *   0 = endpoint_missing (graceful degrade, consensus disabled on tier)
+ *   0 = PASS (rubric clean) OR empty diff (nothing to review)
+ *   1 = WARN (rubric: one reviewer P1, informational)
+ *   2 = BLOCK (rubric: P0 or consensus P1) / failed / capture_failed
+ *   5 = auth_missing (no credentials) / unauthenticated (token rejected)
+ *   7 = rate_limited (quota exhausted, retry after backoff)
+ *
+ * Aligned with the legacy `describeSubmitFailure` in cli.ts so shell
+ * scripts can branch on identical codes across both review surfaces.
+ */
+export async function runReviewConsensus(args, ctx) {
+    if (!ctx.config) {
+        const text = [
+            'pugi review --consensus needs Pugi credentials.',
+            'Run `pugi login --token <PAT>` or export PUGI_API_KEY for CI.',
+        ].join('\n');
+        ctx.writeOutput({
+            command: 'review-consensus',
+            status: 'auth_missing',
+            message: text,
+        }, text);
+        return 5;
+    }
+    // Capture the diff. Failures here are operator-correctable (bad ref,
+    // gh not installed for --pr, etc) so we surface a clean error and
+    // exit 2 — same as BLOCK because the gate could not even run.
+    let captured;
+    try {
+        const spec = parseConsensusArgs(args);
+        captured = captureDiff({ ...spec, cwd: ctx.cwd });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const text = `Failed to capture diff: ${message}`;
+        ctx.writeOutput({ command: 'review-consensus', status: 'capture_failed', message }, text);
+        return 2;
+    }
+    if (captured.diff.trim().length === 0) {
+        const text = [
+            `No diff captured for ${captured.context.ref}.`,
+            'The consensus gate has nothing to review, nothing to do.',
+        ].join('\n');
+        ctx.writeOutput({
+            command: 'review-consensus',
+            status: 'completed',
+            verdict: 'PASS',
+            reasoning: 'Empty diff: trivial PASS.',
+            reviewers: [],
+            ref: captured.context.ref,
+            stats: captured.context.stats,
+            message: text,
+        }, text);
+        return 0;
+    }
+    // Banner — operator sees this immediately so a slow Anvil call does
+    // not look like the CLI hanging.
+    ctx.emit(`Capturing diff (${captured.context.ref})… ${captured.context.stats.filesChanged} files, ` +
+        `+${captured.context.stats.insertions} -${captured.context.stats.deletions}\n`);
+    ctx.emit('Dispatching to 3 reviewers: codex · claude · deepseek\n\n');
+    const reviewerEvents = [];
+    const sink = (event) => {
+        if (event.type === 'consensus') {
+            // Server-side verdict is informational — we recompute below. We
+            // still surface it on the stream so the operator sees activity.
+            return;
+        }
+        reviewerEvents.push(event);
+        ctx.emit(formatReviewerEventLine(event));
+    };
+    const dispatch = ctx.dispatch ?? dispatchConsensus;
+    const fanoutResult = await dispatch(ctx.config, {
+        diff: captured.diff,
+        context: {
+            branch: captured.context.branch,
+            commit: captured.context.commit,
+            title: captured.context.title,
+        },
+    }, sink);
+    if (fanoutResult.status !== 'ok') {
+        return handleFanoutFailure(fanoutResult, ctx);
+    }
+    // Collapse the SSE event stream into one `ReviewerVerdict` per
+    // reviewer. The final `verdict` event for a reviewer wins; earlier
+    // `started` events are scaffolding for the live UI only.
+    const verdicts = collapseVerdicts(reviewerEvents);
+    const result = aggregate(verdicts);
+    ctx.emit('\n────────────────────────────────────────\n');
+    for (const verdict of verdicts) {
+        ctx.emit(formatReviewerSummaryLine(verdict));
+    }
+    ctx.emit('\n────────────────────────────────────────\n');
+    ctx.emit(`Rubric: ${result.verdict}\n`);
+    ctx.emit(`  ${result.reasoning}\n`);
+    ctx.emit('\n');
+    ctx.emit(`Recommended action: ${recommendedAction(result)}\n`);
+    ctx.writeOutput({
+        command: 'review-consensus',
+        status: 'completed',
+        verdict: result.verdict,
+        reasoning: result.reasoning,
+        reviewers: verdicts.map((v) => ({
+            reviewer: v.reviewer,
+            topSeverity: v.topSeverity,
+            findingCount: v.findings.length,
+            errored: v.errored,
+        })),
+        ref: captured.context.ref,
+        stats: captured.context.stats,
+    }, [
+        `Pugi consensus ${result.verdict}`,
+        result.reasoning,
+        `Reviewers: ${verdicts.map((v) => `${v.reviewer}=${v.topSeverity ?? 'CLEAN'}`).join(' · ')}`,
+    ].join('\n'));
+    return exitCodeFor(result.verdict);
+}
+/**
+ * Translate a fanout failure variant to the matching exit code + output
+ * envelope. Returns the exit code so the caller owns `process.exitCode`
+ * (avoiding the REPL-inherited-exit-code leak).
+ */
+function handleFanoutFailure(result, ctx) {
+    if (result.status === 'endpoint_missing') {
+        const message = [
+            'Backend not deployed yet: the consensus endpoint lands in alpha 6.7.1.',
+            'No exit-1/2 gate: this is a CLI-side surface waiting for the server.',
+            'Run `pugi review --triple --remote` for the legacy artifact-based flow.',
+        ].join('\n');
+        ctx.emit('\n');
+        ctx.emit(`${message}\n`);
+        ctx.writeOutput({ command: 'review-consensus', status: 'endpoint_missing', message }, message);
+        // Graceful: operator did nothing wrong, server pending. Exit 0 so
+        // CI does not redden on the deploy-lag window.
+        return 0;
+    }
+    if (result.status === 'unauthenticated') {
+        const message = `${result.message}. Run \`pugi login --token <PAT>\` and retry.`;
+        ctx.emit('\n');
+        ctx.emit(`${message}\n`);
+        ctx.writeOutput({ command: 'review-consensus', status: 'unauthenticated', message }, message);
+        return 5;
+    }
+    if (result.status === 'rate_limited') {
+        const seconds = Math.round(result.retryAfterMs / 1000);
+        const message = `Rate limit: retry after ${seconds}s.`;
+        ctx.emit('\n');
+        ctx.emit(`${message}\n`);
+        ctx.writeOutput({ command: 'review-consensus', status: 'rate_limited', message }, message);
+        // Exit code contract (kept in sync with `runReviewConsensus`):
+        //   0 = endpoint_missing (graceful degrade, consensus disabled on tier)
+        //   0 = PASS / empty diff
+        //   1 = WARN (informational, single asymmetric P1)
+        //   2 = BLOCK / failed / capture_failed (real findings or unrecoverable)
+        //   5 = auth_missing / unauthenticated (token rejected by Anvil)
+        //   7 = rate_limited (quota exhausted, retry with backoff)
+        //
+        // Aligned with the legacy `describeSubmitFailure` in cli.ts so a
+        // shell script branching on exit code behaves identically across
+        // the legacy triple-review and consensus surfaces.
+        return 7;
+    }
+    const message = result.message;
+    ctx.emit('\n');
+    ctx.emit(`Consensus call failed: ${message}\n`);
+    ctx.writeOutput({ command: 'review-consensus', status: 'failed', message }, `Consensus call failed: ${message}`);
+    return 2;
+}
+/**
+ * Map per-reviewer SSE events to the rubric input shape. One reviewer
+ * may emit `started` then `verdict`; the `verdict` event carries the
+ * raw text we feed parseFindings.
+ *
+ * Precedence (verdict wins over error):
+ *
+ *   started -> verdict       => verdict (rubric processes findings)
+ *   started -> error         => error   (errored=true, no signal)
+ *   started -> verdict -> error => verdict (terminal verdict wins; the
+ *     trailing error is a stale retry/transport artifact and must NOT
+ *     silently downgrade a real P0 BLOCK to "all errored")
+ *   started -> error -> verdict => verdict (verdict still wins)
+ *   started (no terminal)    => errored placeholder so the reviewer
+ *                               appears in the output instead of being
+ *                               silently dropped
+ *
+ * The verdict-wins-over-error rule is the fix for a real BLOCK
+ * downgrade: Anvil's SSE emitter can send a verdict frame followed by
+ * an error frame when a retry layer fires after the terminal verdict
+ * already shipped. Without precedence the error would clobber the
+ * real verdict and produce a false "errored=true" -> no findings ->
+ * possible PASS instead of BLOCK.
+ */
+function collapseVerdicts(events) {
+    const byReviewer = new Map();
+    for (const event of events) {
+        const prior = byReviewer.get(event.reviewer);
+        if (event.type === 'verdict') {
+            // Verdict is always the terminal outcome - overwrite anything we
+            // had before (started placeholder, or a stale error frame).
+            byReviewer.set(event.reviewer, event);
+        }
+        else if (event.type === 'error') {
+            // Error only wins if no verdict has arrived yet for this reviewer.
+            // Once we hold a verdict, a trailing error is transport noise and
+            // must not downgrade the verdict to "errored".
+            if (!prior || prior.type !== 'verdict') {
+                byReviewer.set(event.reviewer, event);
+            }
+        }
+        else if (!prior) {
+            // started: hold as placeholder so the reviewer appears in the
+            // output even if the stream cuts off before a terminal frame.
+            byReviewer.set(event.reviewer, event);
+        }
+    }
+    const out = [];
+    for (const [reviewer, event] of byReviewer) {
+        if (event.type === 'verdict' && typeof event.rawContent === 'string') {
+            out.push(reviewerVerdictFromRaw(reviewer, event.rawContent, false));
+        }
+        else if (event.type === 'error' || event.error) {
+            out.push(reviewerVerdictFromRaw(reviewer, '', true));
+        }
+        else {
+            // Stream ended mid-flight for this reviewer - treat as errored
+            // so the rubric's "all errored -> BLOCK" branch fires instead of
+            // a misleading PASS.
+            out.push(reviewerVerdictFromRaw(reviewer, '', true));
+        }
+    }
+    // Deterministic order: codex, claude, deepseek first, then anyone else
+    // alphabetical. Matches the UX preview in the spec and stabilizes JSON
+    // output for snapshot diffs.
+    const priority = { codex: 0, claude: 1, deepseek: 2 };
+    out.sort((a, b) => {
+        const pa = priority[a.reviewer] ?? 99;
+        const pb = priority[b.reviewer] ?? 99;
+        if (pa !== pb)
+            return pa - pb;
+        return a.reviewer.localeCompare(b.reviewer);
+    });
+    return out;
+}
+function formatReviewerEventLine(event) {
+    const name = event.reviewer.padEnd(9);
+    if (event.type === 'started') {
+        return `  ${name} reviewing…\n`;
+    }
+    if (event.type === 'error') {
+        const why = event.error ?? 'unknown';
+        const ms = event.latencyMs ? `  ${event.latencyMs}ms` : '';
+        return `  ${name} ERROR: ${why}${ms}\n`;
+    }
+    const severity = event.severity ?? 'CLEAN';
+    const ms = event.latencyMs ? `  ${event.latencyMs}ms` : '';
+    return `  ${name} ${severity}${ms}\n`;
+}
+function formatReviewerSummaryLine(verdict) {
+    const name = verdict.reviewer.padEnd(9);
+    if (verdict.errored) {
+        return `  ${name} ERROR (no signal)\n`;
+    }
+    if (verdict.findings.length === 0) {
+        return `  ${name} CLEAN\n`;
+    }
+    // Group counts: shows operator the severity breakdown in one line.
+    const counts = countSeverities(verdict);
+    const summary = formatCounts(counts);
+    const top = verdict.findings.slice(0, 3);
+    const tail = verdict.findings.length > 3 ? `\n              … ${verdict.findings.length - 3} more` : '';
+    const findings = top.map((f) => `\n              - [${f.severity}] ${f.summary}`).join('');
+    return `  ${name} ${summary}${findings}${tail}\n`;
+}
+function countSeverities(verdict) {
+    const counts = { P0: 0, P1: 0, P2: 0, P3: 0 };
+    for (const f of verdict.findings)
+        counts[f.severity] += 1;
+    return counts;
+}
+function formatCounts(counts) {
+    const parts = [];
+    if (counts.P0 > 0)
+        parts.push(`${counts.P0}× P0`);
+    if (counts.P1 > 0)
+        parts.push(`${counts.P1}× P1`);
+    if (counts.P2 > 0)
+        parts.push(`${counts.P2}× P2`);
+    if (counts.P3 > 0)
+        parts.push(`${counts.P3}× P3`);
+    if (parts.length === 0)
+        return 'CLEAN';
+    return `[${parts.join(', ')}]`;
+}
+/**
+ * Recommended action surfaced as the last line of the human-readable
+ * UX. Maps to the rubric verdict + finding shape so the operator does
+ * not need to interpret `[P1]` themselves.
+ */
+function recommendedAction(result) {
+    if (result.verdict === 'PASS') {
+        return 'Ship it: no blocking findings.';
+    }
+    if (result.verdict === 'WARN') {
+        return 'Examine the lone P1, decide accept-as-FP or fix, then re-run.';
+    }
+    return 'Fix the blocking findings, then re-run `pugi review --consensus`.';
+}
+//# sourceMappingURL=review-consensus.js.map