@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/dist/src/compare.js

@@ -0,0 +1,673 @@
+// `qcr compare <pr...>` — the cutover comparison harness.
+//
+// For each PR: hand it to the injected dry-run dispatcher (production
+// `qcr compare` dispatches nothing — it is collect-only, reading what earlier
+// daemon rounds recorded), collect the would-be review out of state/dryrun/,
+// fetch the old flow's actual review from GitHub (reads only), and assemble a
+// side-by-side report per the cutover rubric:
+//
+//   (a) blocker parity      old-flow blockers vs sandbox blockers, matched by
+//                           path + theme; every unmatched row flagged
+//   (b) invariant scan      zero dry-run records of any kind outside the known
+//                           allowlist
+//   (c) anchor validity     every sandbox inline anchor lands on a changed line
+//   (d) settled threads     no finding re-raises a thread the archived ledger
+//                           lists as SETTLED
+//   (e) tone / format       NOT judged here — both summaries are reproduced
+//                           verbatim for the human
+//
+// The harness only assembles evidence. (a)–(d) are mechanical gates; the flip
+// decision, and the flip itself, stay human. Nothing here mutates anything:
+// any dry-run round is injected, GitHub access is read-only through the
+// adapter, and the output is markdown on disk.
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { checkAnchor, runsByPath } from "@quickchatai/pi-quickreview/src/anchors.js";
+import { MUTATION_KINDS } from "@quickchatai/pi-quickreview/src/gate.js";
+import { parseHunkHeader } from "@quickchatai/pi-quickreview/src/hunkheader.js";
+// ---- the known mutation-kind allowlist ---------------------------------------
+/** Every mutation kind the sandbox is allowed to intend. The invariant scan is
+ * an allowlist check, not a keyword hunt: any record whose kind is not on this
+ * list is a violation by construction — a kind gate.ts does not have, or one
+ * of the gate kinds left off it (`NOT_ALLOWED_MUTATION_KINDS`), could only
+ * come from code that must not exist. */
+export const ALLOWED_MUTATION_KINDS = [
+    "add_label",
+    "remove_label",
+    "delete_team_review_request",
+    "create_review",
+    "create_review_comment_reply",
+    "create_issue_comment",
+    // Ping-pong resolves the bot's own finding thread once the author's reply
+    // settles it — an ordinary gated intent, never a review dismissal.
+    "resolve_own_review_thread",
+    "create_issue",
+    "create_pull",
+    "push_branch",
+    // An escalation's review request is a legitimate intent when the operator
+    // switched the feature on (it is off by default, so on a stock install no
+    // such record can appear). A configured, gated mutation must not read as a
+    // structural violation.
+    "request_reviewer",
+];
+const ALLOWED = new Set(ALLOWED_MUTATION_KINDS);
+/** The gate kinds a dry-run record must never carry: the review-superseding
+ * kind, which has no adapter method and no caller, and the app-self-config
+ * class, which the gate executes rather than records
+ * (tests/compare.test.ts pins exactly those two). */
+export const NOT_ALLOWED_MUTATION_KINDS = MUTATION_KINDS.filter((k) => !ALLOWED.has(k));
+// ---- dry-run collection ------------------------------------------------------
+/** Decode one recorded mutation, preserving the malformed-file sentinel. */
+export function decodeDryrunRecord(text, file) {
+    try {
+        if (text === null)
+            throw new Error("unreadable record");
+        return { ...JSON.parse(text), file };
+    }
+    catch {
+        return { kind: "unparseable", method: "?", path: "?", note: `could not parse ${file}`, file };
+    }
+}
+/** Read state/dryrun/ into records (newest last). Tolerates junk files. */
+export function readDryrunDir(dir) {
+    if (!existsSync(dir))
+        return [];
+    return readdirSync(dir)
+        .sort()
+        .filter((file) => file.endsWith(".json"))
+        .map((file) => {
+        let text = null;
+        try {
+            text = readFileSync(join(dir, file), "utf8");
+        }
+        catch {
+            /* Kept as an unparseable record. */
+        }
+        return decodeDryrunRecord(text, file);
+    });
+}
+/** The would-be review for a PR: the last substantive create_review record it
+ * produced. A mechanically authored COMMENT (`reviewPurpose`) is not the
+ * round's review, so it is never the one compared. */
+export function sandboxReviewFrom(records, pr) {
+    const reviews = records.filter((r) => r.kind === "create_review" &&
+        r.reviewPurpose === undefined &&
+        (r.pr === pr || r.path.includes(`/pulls/${pr}/`)));
+    const last = reviews[reviews.length - 1];
+    if (!last)
+        return null;
+    const body = (last.body ?? {});
+    return {
+        source: "sandbox",
+        state: body.event ?? "COMMENT",
+        body: body.body ?? "",
+        commit_id: body.commit_id,
+        submitted_at: last.recorded_at,
+        comments: (body.comments ?? []).map((c) => ({
+            path: c.path ?? "",
+            line: c.line ?? c.position ?? 0,
+            ...(c.side === "LEFT" || c.side === "RIGHT" ? { side: c.side } : {}),
+            ...(typeof c.start_line === "number" ? { start_line: c.start_line } : {}),
+            body: c.body ?? "",
+        })),
+    };
+}
+// ---- (a) blocker parity ------------------------------------------------------
+const STOPWORDS = new Set([
+    "the",
+    "a",
+    "an",
+    "and",
+    "or",
+    "but",
+    "if",
+    "then",
+    "this",
+    "that",
+    "these",
+    "those",
+    "is",
+    "are",
+    "was",
+    "were",
+    "be",
+    "been",
+    "being",
+    "to",
+    "of",
+    "in",
+    "on",
+    "at",
+    "for",
+    "with",
+    "without",
+    "from",
+    "by",
+    "as",
+    "it",
+    "its",
+    "we",
+    "you",
+    "your",
+    "should",
+    "would",
+    "could",
+    "will",
+    "can",
+    "may",
+    "must",
+    "not",
+    "no",
+    "here",
+    "there",
+    "blocker",
+    "blocking",
+    "issue",
+    "problem",
+    "please",
+    "line",
+    "lines",
+    "code",
+    "file",
+    "when",
+    "which",
+    "what",
+    "add",
+    "adds",
+    "added",
+    "use",
+    "uses",
+    "used",
+    "using",
+    "make",
+    "makes",
+    "need",
+    "needs",
+    "needed",
+]);
+const BLOCKER_MARKERS = /(^|[^a-z])(blockers?|blocking|must[- ]fix|severity:\s*blocker|critical)([^a-z]|$)/i;
+const PATH_RE = /(?:^|[\s`(])((?:[\w.-]+\/)+[\w.-]+\.[\w]+)(?::(\d+))?/;
+export function themeWords(text) {
+    return [
+        ...new Set(text
+            .toLowerCase()
+            .replace(/`[^`]*`/g, " ")
+            .replace(/[^a-z0-9_]+/g, " ")
+            .split(" ")
+            .filter((w) => w.length >= 4 && !STOPWORDS.has(w) && !/^\d+$/.test(w))),
+    ];
+}
+function pathFrom(text) {
+    const m = PATH_RE.exec(text);
+    if (!m || !m[1])
+        return { path: "" };
+    return m[2] ? { path: m[1], line: Number(m[2]) } : { path: m[1] };
+}
+/** Pull the blocker-grade findings out of a review: every inline comment that
+ * carries a blocker marker, plus body bullets that do. Deliberately generous —
+ * an over-collected row shows up as an unmatched flag for the human, which is
+ * the safe direction. */
+export function extractBlockers(review) {
+    return extractFindingsWhere(review, true);
+}
+/** Every finding in a review regardless of its posting severity: every inline
+ * comment plus every body bullet. Gate (d) reads this — a question or nit that
+ * re-raises a SETTLED thread breaks the discipline exactly as a blocker does. */
+export function extractAllFindings(review) {
+    return extractFindingsWhere(review, false);
+}
+function extractFindingsWhere(review, blockersOnly) {
+    const found = [];
+    for (const c of review.comments) {
+        if (blockersOnly && !BLOCKER_MARKERS.test(c.body))
+            continue;
+        found.push({
+            path: c.path,
+            line: c.line,
+            text: c.body.trim().split("\n")[0].slice(0, 200),
+            theme: themeWords(c.body),
+            origin: "inline",
+        });
+    }
+    let underBlockerHeading = false;
+    for (const rawLine of review.body.split("\n")) {
+        const line = rawLine.trim();
+        if (/^#{1,6}\s/.test(line)) {
+            underBlockerHeading = BLOCKER_MARKERS.test(line);
+            continue;
+        }
+        const isBullet = /^([-*]|\d+\.)\s+/.test(line);
+        if (!isBullet)
+            continue;
+        if (blockersOnly && !underBlockerHeading && !BLOCKER_MARKERS.test(line))
+            continue;
+        const text = line.replace(/^([-*]|\d+\.)\s+/, "");
+        const { path, line: ln } = pathFrom(text);
+        found.push({
+            path,
+            ...(ln !== undefined ? { line: ln } : {}),
+            text: text.slice(0, 200),
+            theme: themeWords(text),
+            origin: "body",
+        });
+    }
+    return found;
+}
+export function jaccard(a, b) {
+    if (a.length === 0 || b.length === 0)
+        return 0;
+    const setB = new Set(b);
+    const inter = a.filter((w) => setB.has(w)).length;
+    return inter / new Set([...a, ...b]).size;
+}
+function samePath(a, b) {
+    if (!a || !b)
+        return false;
+    if (a === b)
+        return true;
+    const base = (p) => p.split("/").pop() ?? p;
+    return base(a) === base(b);
+}
+/** Match old-flow blockers to sandbox blockers by path + theme overlap. */
+export function blockerParity(oldFindings, sandboxFindings, threshold = 0.2) {
+    const rows = [];
+    const takenSandbox = new Set();
+    for (const o of oldFindings) {
+        let bestIdx = -1;
+        let bestScore = 0;
+        sandboxFindings.forEach((s, i) => {
+            if (takenSandbox.has(i))
+                return;
+            if (o.path && s.path && !samePath(o.path, s.path))
+                return;
+            const score = jaccard(o.theme, s.theme);
+            if (score > bestScore) {
+                bestScore = score;
+                bestIdx = i;
+            }
+        });
+        if (bestIdx >= 0 && bestScore >= threshold) {
+            takenSandbox.add(bestIdx);
+            rows.push({
+                old: o,
+                sandbox: sandboxFindings[bestIdx],
+                score: bestScore,
+                status: "matched",
+            });
+        }
+        else {
+            rows.push({ old: o, score: bestScore, status: "missed-by-sandbox" });
+        }
+    }
+    sandboxFindings.forEach((s, i) => {
+        if (!takenSandbox.has(i))
+            rows.push({ sandbox: s, score: 0, status: "sandbox-only" });
+    });
+    return rows;
+}
+/** Mechanical invariant gate over one PR's dry-run records. */
+export function invariantScan(records, pr) {
+    const violations = [];
+    for (const r of records) {
+        if (!ALLOWED.has(r.kind)) {
+            violations.push({
+                rule: "mutation-kind allowlist",
+                detail: `record ${r.file ?? "?"} carries kind "${r.kind}" — outside the known set`,
+            });
+        }
+        if (r.pr !== undefined && r.pr !== pr) {
+            violations.push({
+                rule: "no unsolicited scope",
+                detail: `record ${r.file ?? "?"} (${r.kind}) targets #${r.pr}, not the PR under comparison (#${pr})`,
+            });
+        }
+    }
+    return violations;
+}
+// ---- (c) anchor validity -----------------------------------------------------
+//
+// The verdict comes from packages/pi-plugin/src/anchors.ts — the same changed-run containment
+// check the posting path uses, so the report cannot disagree with what the
+// daemon would have accepted. The local diff walker below is kept only to
+// classify a *failed* anchor for the human (context line inside a hunk vs
+// nowhere near the diff), which anchors.ts does not distinguish.
+/** Every line number one side of a hunk covers — RIGHT: added + context, in
+ * the new file; LEFT: removed + context, in the old one. */
+export function hunkLineNumbers(patch, side = "RIGHT") {
+    const lines = new Set();
+    // The side's own changed-line marker; the other side's is skipped.
+    const own = side === "RIGHT" ? "+" : "-";
+    const other = side === "RIGHT" ? "-" : "+";
+    let lineNo = 0;
+    for (const line of patch.split("\n")) {
+        const hunk = parseHunkHeader(line);
+        if (hunk) {
+            lineNo = side === "RIGHT" ? hunk.new_start : hunk.old_start;
+            continue;
+        }
+        if (line.startsWith(other) || line.startsWith("\\"))
+            continue;
+        if (lineNo > 0 && (line.startsWith(own) || line.startsWith(" ") || line === "")) {
+            lines.add(lineNo);
+            lineNo++;
+        }
+    }
+    return lines;
+}
+/** Provenance line for the report: which module judged the anchors. */
+export const ANCHOR_SOURCE = "packages/pi-plugin/src/anchors.ts (changed-run containment, on each comment's own side and range)";
+export function checkAnchors(comments, patches) {
+    const byPath = new Map(patches.map((p) => [p.path, p.patch]));
+    const runs = runsByPath(Object.fromEntries(patches.map((p) => [p.path, p.patch])));
+    return comments.map((c) => {
+        const patch = byPath.get(c.path);
+        if (patch === undefined)
+            return { path: c.path, line: c.line, status: "unknown-file" };
+        const side = c.side ?? "RIGHT";
+        const verdict = checkAnchor(runs, {
+            path: c.path,
+            side,
+            line: c.line,
+            ...(c.start_line !== undefined ? { start_line: c.start_line } : {}),
+        });
+        if (verdict.ok)
+            return { path: c.path, line: c.line, status: "on-changed-line" };
+        if (hunkLineNumbers(patch, side).has(c.line))
+            return { path: c.path, line: c.line, status: "context-only" };
+        return { path: c.path, line: c.line, status: "outside-diff" };
+    });
+}
+/** Parse SETTLED rows out of an archived ledger (`archive/pr-<n>/ledger.md`).
+ * A row is any line that carries the SETTLED marker. */
+export function parseSettledThreads(ledgerMd) {
+    const out = [];
+    for (const raw of ledgerMd.split("\n")) {
+        const line = raw.trim();
+        if (!/\bSETTLED\b/.test(line))
+            continue;
+        const text = line
+            .replace(/^[-*|]\s*/, "")
+            .replace(/\|/g, " ")
+            .trim();
+        out.push({
+            path: pathFrom(text).path,
+            text: text.slice(0, 200),
+            theme: themeWords(text.replace(/\bSETTLED\b/g, " ")),
+        });
+    }
+    return out;
+}
+/** Any sandbox finding that re-raises a SETTLED thread. */
+export function settledThreadViolations(findings, settled, threshold = 0.25) {
+    const out = [];
+    for (const f of findings) {
+        for (const s of settled) {
+            if (s.path && f.path && !samePath(s.path, f.path))
+                continue;
+            const score = jaccard(f.theme, s.theme);
+            if (score >= threshold)
+                out.push({ settled: s, finding: f, score });
+        }
+    }
+    return out;
+}
+/** The one place the "nothing was posted" claim is decided. Order matters:
+ * the loudest disproof wins, and absence of evidence is never a pass. */
+export function attestDryRun(obs, records) {
+    const forced = records.filter((r) => r.forceLive === true);
+    if (obs.gateIsDryRun === false) {
+        return {
+            status: "live-gate",
+            substantiated: false,
+            detail: "the gate this run went through reported `dry_run = false` — every mutation it accepted was executed against GitHub for real.",
+        };
+    }
+    if ((obs.executedMutations ?? 0) > 0) {
+        return {
+            status: "executed",
+            substantiated: false,
+            detail: `${obs.executedMutations} mutation(s) came back from the gate as EXECUTED — this run posted.`,
+        };
+    }
+    if (forced.length) {
+        return {
+            status: "force-live",
+            substantiated: false,
+            detail: `${forced.length} record(s) carry \`forceLive\` (${[...new Set(forced.map((r) => r.kind))].join(", ")}), which executes even in dry-run.`,
+        };
+    }
+    if (obs.gateIsDryRun === null) {
+        return {
+            status: "unobserved",
+            substantiated: false,
+            detail: "no gate was observed for this run — the records were collected off disk after the fact, so the harness cannot tell whether the round that produced them posted. Say nothing rather than reassure.",
+        };
+    }
+    // A dry-run gate still executes the app-self-config class, so the flag
+    // alone never proves that nothing executed: an unknown count is unobserved.
+    if (obs.executedMutations === null) {
+        return {
+            status: "unobserved",
+            substantiated: false,
+            detail: "the gate reported `dry_run = true`, but how many of its mutations executed was not observed — a dry-run gate still executes the app-self-config class, so the flag alone cannot say nothing was posted.",
+        };
+    }
+    return {
+        status: "observed-dry",
+        substantiated: true,
+        detail: `the gate reported \`dry_run = true\`, ${records.length} intent(s) were recorded to \`state/dryrun/\` instead of being executed, ${obs.executedMutations} were executed, and no record carries \`forceLive\`.`,
+    };
+}
+/** The report's closing block — one line when the claim holds, a loud warning
+ * when it does not. */
+export function renderDryRunAttestation(a) {
+    if (a.substantiated)
+        return [`**Dry run VERIFIED** — ${a.detail}`];
+    return [
+        `> ⚠ **DRY RUN NOT SUBSTANTIATED (\`${a.status}\`).** ${a.detail}`,
+        ">",
+        "> This report makes **no claim** that nothing was posted. Treat every",
+        "> would-be mutation below as possibly real until you have checked.",
+    ];
+}
+function esc(s) {
+    return s.replace(/\|/g, "\\|").replace(/\n+/g, " ").trim();
+}
+/** A blocker the old flow raised and the sandbox did not: a hard-gate miss. */
+const isMissedBlocker = (r) => r.status === "missed-by-sandbox";
+/** An anchor that does not sit on a changed line: a hard-gate failure. */
+const isBadAnchor = (a) => a.status !== "on-changed-line";
+export function comparePr(input) {
+    const oldFindings = input.oldReview ? extractBlockers(input.oldReview) : [];
+    const sandboxFindings = input.sandboxReview ? extractBlockers(input.sandboxReview) : [];
+    const parity = blockerParity(oldFindings, sandboxFindings);
+    const violations = invariantScan(input.records, input.pr);
+    const anchors = checkAnchors(input.sandboxReview?.comments ?? [], input.patches);
+    const settled = settledThreadViolations(input.sandboxReview ? extractAllFindings(input.sandboxReview) : [], parseSettledThreads(input.ledgerMd));
+    const missed = parity.filter(isMissedBlocker);
+    const badAnchors = anchors.filter(isBadAnchor);
+    const gatesPass = missed.length === 0 &&
+        violations.length === 0 &&
+        badAnchors.length === 0 &&
+        settled.length === 0 &&
+        input.sandboxReview !== null;
+    const dryRun = attestDryRun(input.dryRun ?? { gateIsDryRun: null, executedMutations: null }, input.records);
+    const L = [];
+    L.push(`# PR #${input.pr} — old flow vs sandbox (dry run)`);
+    L.push("");
+    L.push(`Generated by \`qcr compare\`. Gates (a)–(d) are mechanical; (e) tone/format is yours.`);
+    L.push(`Anchor verdicts from ${ANCHOR_SOURCE}.`);
+    L.push("");
+    L.push(`| verdict | old flow | sandbox (dry run) |`);
+    L.push(`| --- | --- | --- |`);
+    L.push(`| state | ${input.oldReview?.state ?? "—"} | ${input.sandboxReview?.state ?? "— (no create_review record)"} |`);
+    L.push(`| inline comments | ${input.oldReview?.comments.length ?? 0} | ${input.sandboxReview?.comments.length ?? 0} |`);
+    L.push(`| blockers | ${oldFindings.length} | ${sandboxFindings.length} |`);
+    L.push("");
+    L.push(`## (a) Blocker parity ${missed.length === 0 ? "— PASS" : `— FAIL (${missed.length} missed)`}`);
+    L.push("");
+    if (parity.length === 0) {
+        L.push("No blockers on either side.");
+    }
+    else {
+        L.push("| status | old flow | sandbox | score |");
+        L.push("| --- | --- | --- | --- |");
+        for (const r of parity) {
+            const flag = r.status === "matched"
+                ? "matched"
+                : r.status === "missed-by-sandbox"
+                    ? "**MISSED**"
+                    : "sandbox-only";
+            L.push(`| ${flag} | ${r.old ? `\`${r.old.path || "—"}\` ${esc(r.old.text)}` : "—"} | ${r.sandbox ? `\`${r.sandbox.path || "—"}\` ${esc(r.sandbox.text)}` : "—"} | ${r.score.toFixed(2)} |`);
+        }
+        L.push("");
+        L.push("`sandbox-only` rows are not failures — judge whether each is a real finding or noise.");
+    }
+    L.push("");
+    L.push(`## (b) Invariant scan ${violations.length === 0 ? "— PASS" : `— FAIL (${violations.length})`}`);
+    L.push("");
+    L.push(`${input.records.length} dry-run record(s); kinds: ${[...new Set(input.records.map((r) => r.kind))].join(", ") || "none"}.`);
+    L.push(`Allowlist: ${ALLOWED_MUTATION_KINDS.join(", ")}.`);
+    if (violations.length) {
+        L.push("");
+        for (const v of violations)
+            L.push(`- **${v.rule}** — ${v.detail}`);
+    }
+    L.push("");
+    L.push(`## (c) Anchor validity ${badAnchors.length === 0 ? "— PASS" : `— FAIL (${badAnchors.length})`}`);
+    L.push("");
+    if (anchors.length === 0) {
+        L.push("No inline anchors.");
+    }
+    else {
+        L.push("| file | line | status |");
+        L.push("| --- | --- | --- |");
+        for (const a of anchors)
+            L.push(`| \`${a.path}\` | ${a.line} | ${a.status === "on-changed-line" ? "ok" : `**${a.status}**`} |`);
+    }
+    L.push("");
+    L.push(`## (d) Settled-thread discipline ${settled.length === 0 ? "— PASS" : `— FAIL (${settled.length})`}`);
+    L.push("");
+    if (settled.length === 0) {
+        L.push("No sandbox finding re-raises a SETTLED thread.");
+    }
+    else {
+        for (const s of settled)
+            L.push(`- re-raised (score ${s.score.toFixed(2)}): sandbox "${esc(s.finding.text)}" vs SETTLED "${esc(s.settled.text)}"`);
+    }
+    L.push("");
+    L.push("## (e) Tone / format — human judgment");
+    L.push("");
+    L.push("### Old-flow review body (verbatim)");
+    L.push("");
+    L.push("```markdown");
+    L.push(input.oldReview?.body ?? "(none)");
+    L.push("```");
+    L.push("");
+    L.push("### Sandbox review body (verbatim, would-be)");
+    L.push("");
+    L.push("```markdown");
+    L.push(input.sandboxReview?.body ?? "(none)");
+    L.push("```");
+    L.push("");
+    L.push(`---`);
+    L.push("");
+    L.push(`**Mechanical gates (a)–(d): ${gatesPass ? "PASS" : "FAIL"}.**`);
+    L.push("");
+    for (const line of renderDryRunAttestation(dryRun))
+        L.push(line);
+    L.push("");
+    return {
+        pr: input.pr,
+        parity,
+        violations,
+        anchors,
+        settled,
+        gatesPass,
+        dryRun,
+        markdown: L.join("\n"),
+    };
+}
+export function renderIndex(results) {
+    const L = [];
+    L.push("# Cutover comparison — index");
+    L.push("");
+    L.push("Cutover rubric: (a) blocker parity, (b) invariant scan, (c) anchor validity,");
+    L.push("(d) settled-thread discipline are hard gates; (e) tone/format is judgment.");
+    L.push("Pass = (a)–(d) clean on all five PRs. The flip itself stays manual.");
+    L.push("");
+    L.push("| PR | gates (a)–(d) | missed blockers | invariant violations | bad anchors | re-raised threads | dry run | report |");
+    L.push("| --- | --- | --- | --- | --- | --- | --- | --- |");
+    for (const r of results) {
+        L.push(`| #${r.pr} | ${r.gatesPass ? "PASS" : "**FAIL**"} | ${r.parity.filter(isMissedBlocker).length} | ${r.violations.length} | ${r.anchors.filter(isBadAnchor).length} | ${r.settled.length} | ${r.dryRun.substantiated ? "verified" : `**${r.dryRun.status}**`} | [\`${r.pr}-compare.md\`](./${r.pr}-compare.md) |`);
+    }
+    L.push("");
+    const failing = results.filter((r) => !r.gatesPass);
+    L.push(failing.length === 0
+        ? `All ${results.length} PR(s) clean on the mechanical gates.`
+        : `${failing.length} PR(s) fail a mechanical gate: ${failing.map((r) => `#${r.pr}`).join(", ")}.`);
+    L.push("");
+    const unverified = results.filter((r) => !r.dryRun.substantiated);
+    if (unverified.length === 0) {
+        L.push(`Dry run VERIFIED on all ${results.length} PR(s): the gate recorded intents and executed none.`);
+    }
+    else {
+        L.push(`⚠ **Dry run NOT substantiated on ${unverified.length} PR(s):** ${unverified.map((r) => `#${r.pr} (\`${r.dryRun.status}\`)`).join(", ")}.`);
+        L.push("This report does not claim nothing was posted for those PRs.");
+    }
+    L.push("");
+    return L.join("\n");
+}
+/** The `qcr compare <pr...>` entrypoint. */
+export async function runCompare(prs, deps, print = console.log) {
+    const results = [];
+    const reportPaths = [];
+    mkdirSync(deps.outDir, { recursive: true });
+    for (const pr of prs) {
+        await deps.dispatchDryRun(pr);
+        const [records, oldReview, patches, ledgerMd] = [
+            await deps.readRecords(pr),
+            await deps.fetchOldReview(pr),
+            await deps.fetchPatches(pr),
+            await deps.readLedger(pr),
+        ];
+        const dryRun = (await deps.observeDryRun?.(pr)) ?? {
+            gateIsDryRun: null,
+            executedMutations: null,
+        };
+        const result = comparePr({
+            pr,
+            oldReview,
+            sandboxReview: sandboxReviewFrom(records, pr),
+            records,
+            patches,
+            ledgerMd,
+            dryRun,
+        });
+        const file = join(deps.outDir, `${pr}-compare.md`);
+        writeFileSync(file, result.markdown);
+        reportPaths.push(file);
+        results.push(result);
+        print(`#${pr}: gates ${result.gatesPass ? "PASS" : "FAIL"} -> ${file}`);
+        if (!result.dryRun.substantiated)
+            print(`#${pr}: ⚠ dry run NOT substantiated (${result.dryRun.status}) — ${result.dryRun.detail}`);
+    }
+    const indexPath = join(deps.outDir, "index.md");
+    writeFileSync(indexPath, renderIndex(results));
+    print(`index -> ${indexPath}`);
+    // A DISPROVED dry-run claim (the gate was live, something executed, or a
+    // record carries forceLive) fails the run outright: the comparison evidence
+    // is void if the "comparison" posted. `unobserved` is loud in the report and
+    // in the printed lines, but collect-only is a legitimate way to run this, so
+    // it does not on its own decide the exit code.
+    const disproved = results.filter((r) => r.dryRun.status === "live-gate" ||
+        r.dryRun.status === "executed" ||
+        r.dryRun.status === "force-live");
+    return {
+        results,
+        reportPaths,
+        indexPath,
+        exitCode: results.every((r) => r.gatesPass) && disproved.length === 0 ? 0 : 1,
+    };
+}
+//# sourceMappingURL=compare.js.map