@fullstackhouse/cerber 0.26.0 → 0.27.1

package/README.md

@@ -415,6 +415,12 @@ above: the seven statuses and what sets each, which tab a PR lands in and why,
 when the poll files or archives a row on its own, when a re-review happens and
 what it will not overwrite, and what gets written to disk at each step.
 
+[**SPEC.md**](SPEC.md) is the full service specification — the artifact
+schema, every lifecycle and filing rule, the runner's tool policy and
+credential hygiene, the send path — written precisely enough to reimplement
+cerber from. lifecycle.md is the operator's view of the product; SPEC.md is
+the engineer's.
+
 ## Development
 
 ```bash

package/dist/core/gh.js

@@ -90,8 +90,88 @@ async function membershipCheck(args) {
         throw err;
     }
 }
+/**
+ * GitHub refuses to render a diff past 300 changed files: `gh pr diff` comes
+ * back 406 and the review dies before it starts. The files API answers for ten
+ * times as many, so a too-large diff is re-assembled from it rather than
+ * reported as a broken review — see {@link assembleDiff}.
+ */
 export async function fetchPrDiff(ref) {
-    return gh(["pr", "diff", String(ref.number), "--repo", `${ref.owner}/${ref.repo}`]);
+    try {
+        return await gh(["pr", "diff", String(ref.number), "--repo", `${ref.owner}/${ref.repo}`]);
+    }
+    catch (err) {
+        // Matched on GitHub's own `too_large` signature rather than the bare 406:
+        // 406 is "Not Acceptable" generally, while `too_large` is emitted for this
+        // refusal and nothing else. Matching the meaning survives a status change;
+        // matching the status would fall back on some unrelated 406 one day.
+        const message = err instanceof Error ? err.message : String(err);
+        if (!/too_large|exceeded the maximum number of files/i.test(message))
+            throw err;
+        const files = await fetchPrFiles(ref);
+        const diff = assembleDiff(files);
+        // The files API stops at 3000 too, and says nothing when it does. Hitting
+        // the cap exactly is not proof of truncation — a PR can change exactly
+        // 3000 files — and there is nothing here to tell the two apart, so the
+        // note reports the doubt rather than asserting a loss that may not exist.
+        return files.length < FILES_API_CAP
+            ? diff
+            : `${diff}[GitHub's files API returns at most ${FILES_API_CAP} files and returned exactly that many — if this PR changes more, the rest is missing from this diff. Read the checkout.]\n`;
+    }
+}
+const FILES_API_CAP = 3000;
+async function fetchPrFiles(ref) {
+    const out = await gh([
+        "api",
+        "--paginate",
+        `repos/${ref.owner}/${ref.repo}/pulls/${ref.number}/files?per_page=100`,
+        "--jq",
+        ".[] | {filename, status, previous_filename, additions, deletions, patch}",
+    ]);
+    // --jq streams one object per line rather than a JSON array.
+    return out
+        .split("\n")
+        .filter((line) => line.trim() !== "")
+        .map((line) => JSON.parse(line));
+}
+/**
+ * Put the `diff --git` / `---` / `+++` headers back on the per-file hunks the
+ * files API returns, so the result parses exactly like `gh pr diff` output —
+ * `splitDiffByFile` and the line anchoring read both the same way.
+ *
+ * A file whose patch GitHub withheld still gets its headers and a line saying
+ * so: an unexplained gap would read as "nothing changed here".
+ */
+export function assembleDiff(files) {
+    const out = [];
+    for (const file of files) {
+        const renamed = file.status === "renamed" && file.previous_filename;
+        const oldPath = file.status === "added" ? null : renamed ? file.previous_filename : file.filename;
+        const newPath = file.status === "removed" ? null : file.filename;
+        // The side a file does not have is /dev/null, in the headers and in the
+        // binary line alike — that is how git names it.
+        const a = oldPath ? `a/${oldPath}` : "/dev/null";
+        const b = newPath ? `b/${newPath}` : "/dev/null";
+        out.push(`diff --git a/${oldPath ?? file.filename} b/${newPath ?? file.filename}`);
+        if (renamed)
+            out.push(`rename from ${oldPath}`, `rename to ${newPath}`);
+        if (file.patch) {
+            out.push(`--- ${a}`, `+++ ${b}`, file.patch.replace(/\n$/, ""));
+        }
+        else if (file.additions > 0 || file.deletions > 0) {
+            // GitHub counted the lines and then withheld the patch: a text file it
+            // decided was too big. Say so — an empty file block reads as "unchanged".
+            out.push(`--- ${a}`, `+++ ${b}`, `[GitHub withheld this file's patch — ${file.additions} addition(s), ${file.deletions} deletion(s). Read the file in the checkout.]`);
+        }
+        else if (!renamed) {
+            out.push(`Binary files ${a} and ${b} differ`);
+        }
+        // A pure rename ends here, with no hunks and no ---/+++ pair: nothing about
+        // the content changed, and `rename from`/`rename to` have already said
+        // everything. Calling it binary — which counting lines alone would — is
+        // both wrong and the more alarming of the two ways to be wrong.
+    }
+    return out.length === 0 ? "" : out.join("\n") + "\n";
 }
 /**
  * Map `gh search prs` JSON output to PR refs.
@@ -132,7 +212,7 @@ export async function fetchConversation(ref) {
         "--paginate",
         `repos/${ref.owner}/${ref.repo}/issues/${ref.number}/comments`,
         "--jq",
-        '.[] | {author: .user.login, at: .created_at, bot: (.user.type == "Bot"), url: .html_url}',
+        '.[] | {author: .user.login, at: .created_at, body: (.body // ""), bot: (.user.type == "Bot"), url: .html_url}',
     ]);
     // --jq streams one object per line rather than a JSON array.
     return out
@@ -173,6 +253,39 @@ export function lastWordOfYours(comments, login) {
     const mine = comments.filter((c) => !isBot(c) && c.author === login);
     return mine[mine.length - 1] ?? null;
 }
+/**
+ * Whether a comment speaks to you by name.
+ *
+ * GitHub's own rule, near enough: an `@login` that isn't part of a longer word.
+ * The boundary is "not a login character" rather than `\b`, because logins may
+ * contain hyphens — `@me-bot` is a different account from `@me`, and
+ * `you@me.dev` is an email address, not an ask.
+ *
+ * Deliberately not team mentions. `@org/team` is a room being addressed, and
+ * this is used to undo a decision of yours, which wants somebody naming *you*.
+ */
+export function mentionsYou(body, login) {
+    const name = login.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(^|[^\\w-])@${name}(?![\\w-])`, "i").test(body);
+}
+/**
+ * The last comment somebody addressed to you by name, or null if nobody has.
+ *
+ * The other half of what the conversation can say. `classifyReply` reads it for
+ * whose move it is; this reads the same comments for the ask GitHub's own API
+ * has no event for — "@you this is ready for another look", typed instead of
+ * clicking the re-request button. Your own comments never count, and bots never
+ * do: a bot that @-mentions the assignee on every push would otherwise be an
+ * ask on every push.
+ */
+export function lastMentionOfYou(comments, login) {
+    const theirs = comments.filter((c) => !isBot(c) && c.author !== login && mentionsYou(c.body, login));
+    if (theirs.length === 0)
+        return null;
+    // By date, not by position: this undoes a settle, so it does not lean on the
+    // API happening to return the conversation in order.
+    return theirs.reduce((a, b) => (b.at > a.at ? b : a));
+}
 /**
  * The last review of your own that still stands, or null.
  *

package/dist/server/daemon.js

@@ -1,7 +1,7 @@
 import { SCHEMA_VERSION, artifactId, artifactKey } from "../core/artifact.js";
 import { evaluateAutoSend } from "../core/autosend.js";
 import { loadConfig } from "../core/config.js";
-import { classifyReply, currentLogin, fetchConversation, fetchLastReviewRequest, fetchOwnReview, fetchPrInfo, fetchReviewRequests, lastWordOfYours, searchAwaitingMe, stillRequested, submitReview, } from "../core/gh.js";
+import { classifyReply, currentLogin, fetchConversation, fetchLastReviewRequest, fetchOwnReview, fetchPrInfo, fetchReviewRequests, lastMentionOfYou, lastWordOfYours, searchAwaitingMe, stillRequested, submitReview, } from "../core/gh.js";
 import { withWriter } from "../core/history.js";
 import { notice, notify } from "../core/notify.js";
 import { buildReviewPayload, computeCalibration } from "../core/send.js";
@@ -145,25 +145,40 @@ export function settledAtOf(a) {
     return a.settledAt ?? a.filed?.at ?? a.run?.finishedAt ?? null;
 }
 /**
- * Whether a review request is a *new* ask rather than the one you settled.
+ * Whether an ask is a *new* one rather than the one you settled.
  *
  * A skip says "I am done with this PR", and a push does not undo that — the
  * whole point of `SETTLED_BY_YOU`. Somebody asking you again is a different
- * event: your skip answered the request that was open when you made it, and it
- * cannot have answered one that came after. Withdrawn-then-re-added is the
- * shape this catches, and it is not exotic — an author who pulls the request
- * while you are mid-look and puts it back with the next push leaves the inbox
- * silent about a review someone is now actively waiting on.
+ * event: your skip answered whatever was open when you made it, and it cannot
+ * have answered something that came after. Withdrawn-then-re-added is one shape
+ * this catches, and it is not exotic — an author who pulls the request while
+ * you are mid-look and puts it back with the next push leaves the inbox silent
+ * about a review someone is now actively waiting on. The other shape is the
+ * same author typing it instead (`Ask`).
  *
  * Parsed, not compared as text, for the reason `filedByYourAct` gives: our
  * timestamps carry milliseconds and GitHub's do not, and "…:00.500Z" sorts
  * before "…:00Z".
  */
-export function askedAgainAfterSettling(a, requestedAt) {
-    if (requestedAt === null)
+export function askedAgainAfterSettling(a, askedAt) {
+    if (askedAt === null)
         return false;
     const settled = settledAtOf(a);
-    return settled !== null && Date.parse(requestedAt) > Date.parse(settled);
+    return settled !== null && Date.parse(askedAt) > Date.parse(settled);
+}
+/**
+ * What the daemon says about a reopen, in the log and in the row's history.
+ *
+ * One place, so the line the user reads in the terminal and the line they read
+ * on the review months later cannot tell different stories about why a decision
+ * of theirs was undone — which is the only thing that makes undoing it fair.
+ */
+export function askWording(ask) {
+    const day = ask.at.slice(0, 10);
+    const what = ask.how === "requested"
+        ? `your review was requested again on ${day}`
+        : `${ask.by} asked for you by name on ${day}`;
+    return { log: `${what} — back in the inbox`, history: `back in the inbox: ${what}, after you settled it` };
 }
 /**
  * What a reopened row goes back to being: the draft it has, or a row waiting
@@ -245,6 +260,11 @@ export function startDaemon(opts) {
         // needs it. Undefined is "not asked yet"; null is "gh could not say", which
         // attributes nothing to you rather than guessing.
         let login;
+        async function who() {
+            if (login === undefined)
+                login = await currentLogin().catch(() => null);
+            return login;
+        }
         /**
          * Put a settled row back in the inbox when somebody has asked you again.
          *
@@ -253,9 +273,17 @@ export function startDaemon(opts) {
          * moved *to* it. Both exist because the queue's picture of who is waiting
          * on what is local, and the thing it is a picture of lives on github.com.
          *
-         * Only rows GitHub is asking about right now get here at all — the caller
-         * is looping over the awaiting search — so the extra read is one call for
-         * one question: was that request made after you settled?
+         * Two ways to be asked, because people use both. GitHub's re-request button
+         * leaves a dated event and is read first: it is the strongest evidence and
+         * the cheapest call. Failing that, the conversation is read for the last
+         * comment naming you — "@you this is ready for another look", which is the
+         * same ask with no event behind it. Reading only the button was the bug:
+         * a settled row sat invisible while its author waited, having said so in
+         * plain words on the PR.
+         *
+         * Only rows GitHub is still asking about get here — the caller is looping
+         * over the awaiting search. A row whose request is gone (you reviewed on
+         * github.com) is caught by `reopenIfAskedInWords` on the other loop instead.
          */
         async function reopenIfAskedAgain(artifact) {
             if (settledAtOf(artifact) === null)
@@ -265,26 +293,72 @@ export function startDaemon(opts) {
                 return;
             reopenChecks++;
             requestCheckedAt.set(artifact.id, Date.now());
-            if (login === undefined)
-                login = await currentLogin().catch(() => null);
-            if (login === null)
+            const me = await who();
+            if (me === null)
                 return;
-            let requestedAt;
+            let ask;
             try {
-                requestedAt = await fetchLastReviewRequest(artifact.pr, login);
+                const requestedAt = await fetchLastReviewRequest(artifact.pr, me);
+                const request = requestedAt === null ? null : { at: requestedAt, how: "requested" };
+                // The words are only worth a second call when the button did not
+                // already answer: a live re-request says everything a comment could.
+                ask = askedAgainAfterSettling(artifact, request?.at ?? null)
+                    ? request
+                    : await askedInWords(artifact, me);
             }
             catch {
                 // A read that failed is not evidence of anything, so nothing happens to
                 // the row. It is not re-asked about until the leash above expires: the
                 // stamp is spent before the call on purpose, so gh being down cannot
-                // turn every settled row into a retry on every poll.
+                // turn every settled row into a retry on every poll. Only the reads are
+                // guarded: a write that fails is a real fault and belongs to the caller.
                 return;
             }
-            if (requestedAt === null || !askedAgainAfterSettling(artifact, requestedAt))
+            await reopen(artifact, ask);
+        }
+        /**
+         * The same reopen for a settled row GitHub is *not* asking about.
+         *
+         * The case is ordinary: you reviewed on github.com, which clears the
+         * request and drops the PR out of the awaiting search, and the author then
+         * pushes and writes "@you ready for another look". No request exists to
+         * re-read, so the words are the whole of the evidence — and without this
+         * the mention check would only work for the rows that happen to still carry
+         * an open request, which is a fix that half-works.
+         *
+         * Rides the state-refresh leash rather than one of its own: the caller has
+         * already spent that artifact's slot for this half-hour, and a settled row
+         * never reaches `fileIfSettledElsewhere`, so this costs the poll one call
+         * on rows that were costing it one already.
+         */
+        async function reopenIfAskedInWords(artifact) {
+            if (settledAtOf(artifact) === null)
+                return;
+            const me = await who();
+            if (me === null)
+                return;
+            let ask;
+            try {
+                ask = await askedInWords(artifact, me);
+            }
+            catch {
+                // Same as above: a failed read changes nothing and waits for the leash.
+                return;
+            }
+            await reopen(artifact, ask);
+        }
+        /** The conversation's answer to "has anybody asked for me again", or null. */
+        async function askedInWords(artifact, me) {
+            const mention = lastMentionOfYou(await fetchConversation(artifact.pr), me);
+            return mention === null ? null : { at: mention.at, how: "mentioned", by: mention.author };
+        }
+        /** Undo the settle, if the ask really is newer than it. */
+        async function reopen(artifact, ask) {
+            if (ask === null || !askedAgainAfterSettling(artifact, ask.at))
                 return;
-            const at = requestedAt;
+            const at = ask.at;
             // Re-read from disk: a re-review or a send may have started in the time
-            // that call took, and neither wants its status rewritten underneath it.
+            // those calls took, and neither wants its status rewritten underneath it.
             const saved = await updateArtifactByKey(artifactKey(artifact.id), (a) => askedAgainAfterSettling(a, at)
                 ? // `filed` goes with the status it explained: cerber's account of why
                     // this row was settled is not the story of a row that is back.
@@ -293,10 +367,11 @@ export function startDaemon(opts) {
             // The status is what says the write landed. `settledAt` cannot: a legacy
             // row never had one, so a mutation that declined would read as a reopen.
             if (saved && !SETTLED_BY_YOU.has(saved.status)) {
-                log(`[${artifact.id}] your review was requested again on ${at.slice(0, 10)} — back in the inbox`);
+                const said = askWording(ask);
+                log(`[${artifact.id}] ${said.log}`);
                 // The status change alone says a row moved; this says why it moved,
                 // which is the whole reason a settle is allowed to be undone at all.
-                await noteHistory(artifact.id, `back in the inbox: your review was requested again on ${at.slice(0, 10)}, after you settled it`);
+                await noteHistory(artifact.id, said.history);
             }
         }
         for (const ref of refs) {
@@ -345,11 +420,9 @@ export function startDaemon(opts) {
             // that could never qualify costs no GitHub call at all.
             if (artifact.status !== "ready" || artifact.sent)
                 return;
-            if (login === undefined)
-                login = await currentLogin().catch(() => null);
-            if (login === null)
+            const me = await who();
+            if (me === null)
                 return;
-            const me = login;
             /** Re-reads from disk: a run or a send may have started in the seconds
              *  these reads took, and neither wants filing out from under it. */
             async function file(filed, note, stillFilable) {
@@ -447,8 +520,14 @@ export function startDaemon(opts) {
                 }
                 if (pr.state !== "OPEN")
                     log(`[${artifact.id}] ${pr.state.toLowerCase()} — archived`);
-                else
+                else {
+                    // Exactly one of these two spends a call: the first only looks at
+                    // settled rows, the second only at finished drafts. They are the same
+                    // question from opposite sides — has GitHub moved past this, or back
+                    // to it — and a row can only be on one side of it.
+                    await reopenIfAskedInWords(artifact);
                     await fileIfSettledElsewhere(artifact);
+                }
             }
             catch {
                 // Same: book-keeping can wait for the next poll.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fullstackhouse/cerber",
-  "version": "0.26.0",
+  "version": "0.27.1",
   "description": "AI code-review cockpit: Claude reviews your PRs into local artifacts; nothing reaches GitHub until you say so.",
   "license": "MIT",
   "author": "Full Stack House (https://fullstack.house)",