@quickchatai/pi-quickreview 0.0.0-stage → 1.1.0

package/dist/src/guards.js

@@ -0,0 +1,306 @@
+// Posting-time guards, all applied at the one moment that matters:
+// immediately before a review reaches GitHub.
+//
+//   1. Never re-block a head a human already approved. A non-author human
+//      approval at the head under review downgrades a REQUEST_CHANGES to a
+//      COMMENT: the bot still reports everything it found, it just stops
+//      holding the gate against a person who has already looked.
+//   2. No-op when there is no new evidence. The mark lives in
+//      `reviewed_heads` (state.ts): same head AND no author reply since ⇒ post
+//      nothing. The same mark is what the post-approval delta recheck reads.
+//   3. Re-check merged/closed state immediately before posting, so no review
+//      lands at or after a merge.
+//   5. The live head must be the head the round actually reviewed, so a push
+//      landing between a round's validation and its posting step never gets
+//      the stale review posted against it. On the gate route the intent's
+//      commit_id is the reviewed head, so a mismatch with the guard-3 live
+//      read refuses; a session's post carries QCR_EXPECTED_HEAD
+//      (cited by its round prompt) as the intent's commit_id, and a post that
+//      names none carries no expectation, so a session whose prompt does not
+//      set it is never wedged.
+//   4. No green CI at this head ⇒ APPROVE is unavailable. The review still
+//      posts — as a COMMENT with the approval withheld and a plain note saying
+//      so — and the PR is re-queued when CI goes green. The classifier lives
+//      in cigate.ts.
+//
+// All of them are installed on the one MutationGate (gate.ts `MutationGuard`),
+// not on a call site, so no posting route in the daemon can reach GitHub
+// around them. The sessions post through scripts/post-review.sh,
+// approve-pr.sh and reply-thread.sh, Node-only clients of the daemon's post
+// endpoint (src/ipc/postshim.ts); the daemon builds the intent and hands it to
+// the same gate, so these guards bind them too. The gate's after-step makes
+// the reviewed-head stamp. tests/guards.test.ts drives the real gate over the
+// cases.
+// Guard 2 never gates an APPROVE. Guard 4 softens rather than refuses: an
+// approval over red CI posts as a COMMENT with the approval withheld.
+//
+// Nothing here dismisses, retracts or edits an existing review. A guard's only
+// powers are to refuse a mutation and to soften its event to COMMENT — a
+// REQUEST_CHANGES a human's approval outranks (guard 1), an APPROVE red CI
+// withholds (guard 4).
+import { ciBlocksApproval, classifyCi, withholdApproval, } from "./cigate.js";
+import { standingReview } from "./standing-review.js";
+/** A bot's login: the App's own, or any `[bot]` account. Bot-authored PRs
+ * never enter the state machine (spec §3, src/statemachine.ts re-exports
+ * this), and a bot's approval is no human's. */
+export function isBotAuthor(author, botLogin) {
+    return author === botLogin || author.endsWith("[bot]");
+}
+/** Mutation kinds that put words on a PR — the ones the guards inspect. */
+export const POSTING_KINDS = new Set([
+    "create_review",
+    "create_review_comment_reply",
+    "create_issue_comment",
+]);
+// ---- guard 1: a human already approved this head --------------------------
+/**
+ * The login of a non-author human whose APPROVED review stands at `head_sha`,
+ * or null. "Stands" means it is that person's LATEST verdict-bearing review:
+ * a later CHANGES_REQUESTED or DISMISSED by the same person retires it.
+ * COMMENTED/PENDING reviews carry no verdict and are ignored.
+ *
+ * Reviews are read in submission order, which is the order the REST endpoint
+ * returns them in.
+ */
+export function humanApprovalAtHead(reviews, opts) {
+    if (!opts.head_sha)
+        return null;
+    const latest = new Map();
+    for (const r of reviews) {
+        const state = (r.state ?? "").toUpperCase();
+        if (state !== "APPROVED" && state !== "CHANGES_REQUESTED" && state !== "DISMISSED")
+            continue;
+        if (!r.user)
+            continue;
+        latest.set(r.user, { state, commit_id: r.commit_id });
+    }
+    for (const [user, r] of latest) {
+        if (r.state !== "APPROVED")
+            continue;
+        if (r.commit_id !== opts.head_sha)
+            continue;
+        if (user === opts.author)
+            continue; // GitHub forbids it, but never trust that
+        if (isBotAuthor(user, opts.botLogin))
+            continue;
+        return user;
+    }
+    return null;
+}
+/** The note the downgraded review carries, so the softer event is never a
+ * silent change of mind. */
+export function downgradeNote(approver, headSha) {
+    return (`_Not blocking: **@${approver}** has already approved this head (\`${headSha.slice(0, 7)}\`). ` +
+        "The findings above are reported for information only — this review does not request changes._");
+}
+/** REQUEST_CHANGES → COMMENT, findings untouched, with the note appended. */
+export function downgradeForHumanApproval(body, approver, headSha) {
+    return {
+        ...body,
+        event: "COMMENT",
+        body: `${body.body ?? ""}\n\n${downgradeNote(approver, headSha)}`,
+    };
+}
+// ---- guard 2: no new evidence ---------------------------------------------
+/**
+ * Is there anything new to review at `head_sha`? True unless the mark sits on
+ * exactly this head and no author reply has landed since it was stamped.
+ * An unknown head (empty string) is always "new": guessing would suppress a
+ * real review.
+ */
+export function hasNewEvidence(mark, headSha) {
+    if (!mark || !headSha)
+        return true;
+    // A NEEDS_HUMAN/ESCALATE mark (legacy vocabulary) is an undecided review:
+    // it must never suppress a re-run or a posting — a re-triggered PR with only
+    // an undecided mark deserves a full round. Read through the one
+    // standing-review interpretation, so this guard and dispatch's skip can
+    // never disagree about what the mark says.
+    if (standingReview(mark).kind === "undecided")
+        return true;
+    if (mark.head_sha !== headSha)
+        return true;
+    // `>=`, not `>`: a reply stamped in the same millisecond as the review is
+    // ambiguous, and the safe reading of an ambiguous reply is "new evidence".
+    // Re-stamping the mark clears the reply, so this cannot loop.
+    if (mark.last_author_reply_at && mark.last_author_reply_at >= mark.reviewed_at)
+        return true;
+    return false;
+}
+/**
+ * Read the checks at a head for guard 4. Null means "cannot see CI" — no
+ * adapter method, no head, or a failed read — and a guard never blocks on what
+ * it cannot see: failing closed here would withhold every approval during a
+ * GitHub outage, turning an outage into a pile of parked PRs. What it CAN see
+ * it enforces without exception, infra failures included.
+ */
+async function readCi(deps, pr, head, log) {
+    if (!deps.adapter.listChecks || !head)
+        return null;
+    try {
+        return classifyCi(await deps.adapter.listChecks(head));
+    }
+    catch (err) {
+        log(`guard: checks read failed on #${pr}`, err);
+        deps.store.logEvent("approval_ci_unreadable", pr, { head_sha: head, error: String(err) });
+        return null;
+    }
+}
+export function makePostingGuard(deps) {
+    const log = deps.log ?? (() => { });
+    const refuse = (intent, pr, reason, extra = {}) => {
+        log(`guard: refused ${intent.kind} on #${pr} — ${reason}`);
+        deps.store.logEvent("posting_guard_blocked", pr, { kind: intent.kind, reason, ...extra });
+        return { block: reason };
+    };
+    return {
+        async before(intent) {
+            if (!POSTING_KINDS.has(intent.kind))
+                return {};
+            const pr = intent.pr;
+            if (!pr)
+                return {}; // no PR to check against — nothing this guard can say
+            const body = (intent.body ?? {});
+            // --- guard 3: is the PR still open, right now? ---
+            let ref;
+            if (deps.guards.recheck_pr_state_before_post) {
+                try {
+                    ref = await deps.adapter.getPr(pr);
+                }
+                catch (err) {
+                    // Fail closed: an unverifiable PR state is exactly when a post-merge
+                    // review could land. The session retries; reconcile re-derives the
+                    // truth.
+                    return refuse(intent, pr, "pr-unreadable", { error: String(err) });
+                }
+                if (ref.merged)
+                    return refuse(intent, pr, "pr-merged");
+                if (ref.state === "closed")
+                    return refuse(intent, pr, "pr-closed");
+            }
+            if (intent.kind !== "create_review")
+                return {};
+            // The head the review is ABOUT: the payload's commit_id when it has one,
+            // otherwise whatever the PR points at now.
+            const head = body.commit_id || ref?.head_sha || "";
+            // --- guard 5: the head the review is about must still BE the head ---
+            // A push landing between a round's validation and its posting step
+            // would otherwise land the stale review against the new head. Fires
+            // only where the data exists —
+            // an intent without a commit_id carries no expectation, and without the
+            // guard-3 read there is no live head to compare against. Shas compare
+            // case-insensitively: git shas are hex, and an LLM-written
+            // commit_id with drifted case must never fake a "moved" head.
+            // A deferred session review the daemon delivers
+            // (`intent.postingRetry`) posts at its ORIGINAL commit_id even when the
+            // PR has moved on; admission pins the key to
+            // that commit_id and marker.
+            if (deps.guards.refuse_on_head_drift &&
+                intent.postingRetry === undefined &&
+                body.commit_id &&
+                ref &&
+                ref.head_sha.toLowerCase() !== body.commit_id.toLowerCase()) {
+                return refuse(intent, pr, "head-drift", {
+                    expected_head: body.commit_id,
+                    live_head: ref.head_sha,
+                });
+            }
+            // --- guard 2: has anything happened since the last review? ---
+            //
+            // The escalation note is exempt, and only it. Guard 2 exists to stop the
+            // bot re-reviewing a head it already reviewed. An escalation note is not
+            // a review of the head: it carries no verdict, claims no head (see
+            // `after` below), and by design lands right after the round's own review
+            // — i.e. always at a head the mark has just been stamped on, so guard 2
+            // would suppress every one of them. Its duplicate-suppression is strictly
+            // narrower than guard 2's: the `escalations` ledger refuses the same
+            // person + the same thing on the same PR forever, and `[escalation]
+            // max_per_pr` caps the rest. Every other guard still binds it —
+            // merged/closed (3) and head drift (5) both ran above, unconditionally.
+            //
+            // An APPROVE is exempt too, as a matter of design. Every approval reaching the gate is a
+            // session's approve-pr.sh POST the daemon delivers, and the one that
+            // meets an already-stamped head is the CI-green retry of a withheld
+            // approval: its COMMENT stamped the head, and refusing the APPROVE here
+            // would strand the approval that withholding promised.
+            const mechanical = intent.reviewPurpose === "escalation";
+            const approval = (body.event ?? "").toUpperCase() === "APPROVE";
+            if (deps.guards.skip_unchanged_head &&
+                !mechanical &&
+                !approval &&
+                !hasNewEvidence(deps.store.reviewedHead(pr), head)) {
+                return refuse(intent, pr, "no-new-evidence", { head_sha: head });
+            }
+            // --- guard 1: a human approved this head; do not hold the gate ---
+            if (deps.guards.downgrade_on_human_approval &&
+                (body.event ?? "").toUpperCase() === "REQUEST_CHANGES") {
+                let approver = null;
+                try {
+                    approver = humanApprovalAtHead(await deps.adapter.listReviews(pr), {
+                        head_sha: head,
+                        author: ref?.author ?? "",
+                        botLogin: deps.botLogin,
+                    });
+                }
+                catch (err) {
+                    // A failed read must not block a review — the worst case here is an
+                    // unsoftened review, not a post-merge or duplicate one.
+                    log(`guard: review listing failed on #${pr}`, err);
+                }
+                if (approver) {
+                    log(`guard: #${pr} REQUEST_CHANGES → COMMENT (@${approver} approved ${head.slice(0, 7)})`);
+                    deps.store.logEvent("posting_guard_downgraded", pr, { approver, head_sha: head });
+                    return {
+                        intent: {
+                            ...intent,
+                            body: downgradeForHumanApproval(body, approver, head),
+                            note: `post COMMENT review on #${pr} (downgraded: @${approver} approved this head)`,
+                        },
+                    };
+                }
+            }
+            // --- guard 4: no green CI at this head ⇒ no approval ---
+            if (deps.guards.block_approve_on_red_ci && (body.event ?? "").toUpperCase() === "APPROVE") {
+                const ci = await readCi(deps, pr, head, log);
+                if (ci && ciBlocksApproval(ci, { noChecksIsRed: deps.guards.no_checks_is_red })) {
+                    log(`guard: #${pr} APPROVE → COMMENT (CI ${ci} at ${head.slice(0, 7)})`);
+                    deps.store.logEvent("approval_withheld_red_ci", pr, { head_sha: head, ci_state: ci });
+                    // The promise this note makes to the author — "waiting on CI alone" —
+                    // is kept by the mark: the `ci_completed` trigger reads it and
+                    // re-queues the PR the moment CI goes green (cigate.ts).
+                    deps.store.recordApprovalWithheld(pr, { head_sha: head, ci_state: ci, reason: "red-ci" });
+                    return {
+                        intent: {
+                            ...intent,
+                            body: withholdApproval(body, ci, head),
+                            note: `post COMMENT review on #${pr} (approval withheld: CI ${ci} at this head)`,
+                        },
+                    };
+                }
+                // Green (or invisible) CI: no approval is being withheld here any more.
+                if (ci === "green")
+                    deps.store.clearApprovalWithheld(pr);
+            }
+            return {};
+        },
+        after(intent, result) {
+            // The mark is stamped only for a substantive review that really reached
+            // GitHub. A mechanically-authored COMMENT — the migration pre-check,
+            // the escalation note — is deterministic mechanics,
+            // not the round's verdict; letting one claim the head makes guard 2
+            // suppress the substantive review that follows. Keyed on the PRESENCE of
+            // a `reviewPurpose` rather than on each spelling, so a future purpose
+            // cannot claim a head by being forgotten here.
+            if (intent.kind !== "create_review" || intent.reviewPurpose || !result.executed || !intent.pr)
+                return;
+            const body = (intent.body ?? {});
+            if (!body.commit_id)
+                return;
+            deps.store.recordReviewedHead(intent.pr, {
+                head_sha: body.commit_id,
+                posted_event: (body.event ?? "").toUpperCase() || null,
+            });
+        },
+    };
+}
+//# sourceMappingURL=guards.js.map

package/dist/src/guards.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"guards.js","sourceRoot":"","sources":["../../src/guards.ts"],"names":[],"mappings":"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"}

package/dist/src/heartbeat.d.ts

@@ -0,0 +1,29 @@
+export declare const HEARTBEAT_FILE = "heartbeat.json";
+export interface Beat {
+    /** Counts up with every write. */
+    seq: number;
+    /** When it was written (ms since the epoch). */
+    at: number;
+    pid: number;
+    /** The latest deadline of a turn in flight; null while none runs. */
+    deadline_at: number | null;
+    /** Process groups the driver had running when it wrote this. */
+    pgids: number[];
+}
+/** A turn in flight ends at `at`: the beat carries it until the returned
+ * release is called. Cheap and inert when no heartbeat is running. The beat is
+ * rewritten at once: a driver that freezes in the turn's first moments (a
+ * synchronous loop on the SDK runtime stops the timer too) would otherwise leave
+ * a last beat without the deadline, and the watchdog would never act. */
+export declare function trackDeadline(at: number): () => void;
+/** Read a beat; null when the file is missing or is not one. */
+export declare function readBeat(path: string): Beat | null;
+/** Write a beat now and every `intervalMs` after; returns the stop. The timer
+ * never holds the process open. A write that fails is skipped: a heartbeat that
+ * cannot be written reads as a stopped one, which is what it is. */
+export declare function startHeartbeat(path: string, o?: {
+    intervalMs?: number;
+    now?: () => number;
+    pgids?: () => readonly number[];
+}): () => void;
+//# sourceMappingURL=heartbeat.d.ts.map

package/dist/src/heartbeat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.d.ts","sourceRoot":"","sources":["../../src/heartbeat.ts"],"names":[],"mappings":"AAWA,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAE/C,MAAM,WAAW,IAAI;IACnB,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,gDAAgD;IAChD,EAAE,EAAE,MAAM,CAAC;IACX,GAAG,EAAE,MAAM,CAAC;IACZ,qEAAqE;IACrE,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,gEAAgE;IAChE,KAAK,EAAE,MAAM,EAAE,CAAC;CACjB;AAMD;;;;yEAIyE;AACzE,wBAAgB,aAAa,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,IAAI,CAQpD;AAQD,gEAAgE;AAChE,wBAAgB,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,CAclD;AAED;;oEAEoE;AACpE,wBAAgB,cAAc,CAC5B,IAAI,EAAE,MAAM,EACZ,CAAC,GAAE;IACD,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,SAAS,MAAM,EAAE,CAAC;CAC5B,GACL,MAAM,IAAI,CA2BZ"}

package/dist/src/heartbeat.js

@@ -0,0 +1,87 @@
+// The heartbeat of a detached review run: a small file its driver rewrites on
+// a timer, which an OUTSIDE process (the watchdog in reviewdetach.ts) reads.
+//
+// An in-process deadline cannot cover a frozen event loop: a synchronous loop
+// stops every timer, the budget's included, and the signal handlers with them.
+// What the driver cannot say for itself, a file that stops advancing says for
+// it. The beat also names the latest deadline of the turns in flight and the
+// process groups of the pi children, so the watchdog can reach the children
+// the driver's own group does not hold.
+import { renameSync, readFileSync, writeFileSync } from "node:fs";
+export const HEARTBEAT_FILE = "heartbeat.json";
+const deadlines = new Set();
+/** Writes a beat now: set while a heartbeat runs. */
+let beatNow = null;
+/** A turn in flight ends at `at`: the beat carries it until the returned
+ * release is called. Cheap and inert when no heartbeat is running. The beat is
+ * rewritten at once: a driver that freezes in the turn's first moments (a
+ * synchronous loop on the SDK runtime stops the timer too) would otherwise leave
+ * a last beat without the deadline, and the watchdog would never act. */
+export function trackDeadline(at) {
+    const entry = { at };
+    deadlines.add(entry);
+    beatNow?.();
+    return () => {
+        deadlines.delete(entry);
+        beatNow?.();
+    };
+}
+function latestDeadline() {
+    let max = null;
+    for (const d of deadlines)
+        if (max === null || d.at > max)
+            max = d.at;
+    return max;
+}
+/** Read a beat; null when the file is missing or is not one. */
+export function readBeat(path) {
+    try {
+        const b = JSON.parse(readFileSync(path, "utf8"));
+        if (typeof b.at !== "number" || typeof b.seq !== "number")
+            return null;
+        return {
+            seq: b.seq,
+            at: b.at,
+            pid: typeof b.pid === "number" ? b.pid : 0,
+            deadline_at: typeof b.deadline_at === "number" ? b.deadline_at : null,
+            pgids: Array.isArray(b.pgids) ? b.pgids.filter((p) => Number.isInteger(p)) : [],
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/** Write a beat now and every `intervalMs` after; returns the stop. The timer
+ * never holds the process open. A write that fails is skipped: a heartbeat that
+ * cannot be written reads as a stopped one, which is what it is. */
+export function startHeartbeat(path, o = {}) {
+    const now = o.now ?? Date.now;
+    let seq = 0;
+    const beat = () => {
+        const b = {
+            seq: ++seq,
+            at: now(),
+            pid: process.pid,
+            deadline_at: latestDeadline(),
+            pgids: [...(o.pgids?.() ?? [])],
+        };
+        try {
+            // renamed into place: the watchdog never reads half a beat
+            writeFileSync(`${path}.tmp`, JSON.stringify(b));
+            renameSync(`${path}.tmp`, path);
+        }
+        catch {
+            // see above
+        }
+    };
+    beat();
+    beatNow = beat;
+    const timer = setInterval(beat, o.intervalMs ?? 2_000);
+    timer.unref();
+    return () => {
+        clearInterval(timer);
+        if (beatNow === beat)
+            beatNow = null;
+    };
+}
+//# sourceMappingURL=heartbeat.js.map

package/dist/src/heartbeat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat.js","sourceRoot":"","sources":["../../src/heartbeat.ts"],"names":[],"mappings":"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"}