pr-shepherd 0.53.1 → 0.54.0

package/bin/github/check-annotations.mjs

@@ -1,109 +1,20 @@
-import { createHash } from "node:crypto";
-import { graphql } from "./client.mjs";
-import { CHECK_RUN_ANNOTATIONS_QUERY } from "./queries.mjs";
-import { loadDerived, storeDerived } from "../state/rest-cache.mjs";
-const ANNOTATIONS_PER_PAGE = 100;
-const MAX_ANNOTATION_PAGES = 10;
-const ANNOTATION_TEXT_MAX_CHARS = 4_000;
-const TRUNCATED_SUFFIX = "\n[truncated]";
+import { readFreshCheckAnnotations, storeCheckAnnotations, } from "./check-annotation-cache.mjs";
+import { collectAnnotations } from "./check-annotation-pages.mjs";
 /**
- * Some Checks-API publishers (e.g. SonarCloud) PATCH additional annotations
- * onto an already-COMPLETED check run without minting a new check-run node
- * ID, so "COMPLETED" is not a reliable immutability signal on its own. Bound
- * the cache instead of trusting it forever, so a long-running poll session
- * eventually revalidates.
- */
-const ANNOTATION_CACHE_MAX_AGE_MS = 60 * 60 * 1000;
-/**
- * Fetches all inline annotations for a check run.
+ * Fetches all inline annotations for one check run.
  *
- * When `cacheOpts` is provided, the result is cached by `checkRunId` — safe
- * because callers only pass `cacheOpts` for COMPLETED check runs (a re-run
- * mints a new check-run node id, so a COMPLETED run's annotations are
- * immutable once fetched).
+ * When `cacheOpts` is provided, the result is cached by `checkRunId`. Callers
+ * only pass `cacheOpts` for COMPLETED runs (a re-run mints a new node id).
+ * Prefer `fetchCheckRunAnnotationsBatch` when attaching many checks at once;
+ * this single-node query remains for direct callers and follow-up pages.
  */
-export async function fetchCheckRunAnnotations(checkRunId, cacheOpts) {
-    const cacheName = `annotations-${checkRunId}`;
-    if (cacheOpts) {
-        const cached = await loadDerived(cacheOpts.stateKey, cacheName);
-        if (cached && Date.now() - cached.storedAt < ANNOTATION_CACHE_MAX_AGE_MS)
-            return cached.value;
-    }
-    let cursor = null;
-    const nodes = [];
-    for (let page = 1; page <= MAX_ANNOTATION_PAGES; page++) {
-        // eslint-disable-next-line no-await-in-loop
-        const result = await fetchAnnotationPage(checkRunId, cursor);
-        nodes.push(...result.nodes);
-        if (!result.pageInfo.hasNextPage || !result.pageInfo.endCursor)
-            break;
-        if (page === MAX_ANNOTATION_PAGES) {
-            process.stderr.write(`pr-shepherd: annotation pagination cap (${MAX_ANNOTATION_PAGES * ANNOTATIONS_PER_PAGE} annotations) reached for check run ${checkRunId} — annotation output may be incomplete\n`);
-            break;
-        }
-        cursor = result.pageInfo.endCursor;
-    }
-    const annotations = nodes.map((node) => toCheckAnnotation(checkRunId, node));
-    if (cacheOpts) {
-        await storeDerived(cacheOpts.stateKey, cacheName, annotations, cacheOpts.headSha);
+export async function fetchCheckRunAnnotations(checkRunId, cacheOpts, initialPage) {
+    if (initialPage === undefined) {
+        const cached = await readFreshCheckAnnotations(checkRunId, cacheOpts);
+        if (cached)
+            return cached;
     }
+    const annotations = await collectAnnotations(checkRunId, initialPage);
+    await storeCheckAnnotations(checkRunId, annotations, cacheOpts);
     return annotations;
 }
-async function fetchAnnotationPage(checkRunId, cursor) {
-    const res = await graphql(CHECK_RUN_ANNOTATIONS_QUERY, {
-        id: checkRunId,
-        ...(cursor ? { cursor } : {}),
-    });
-    const node = res.data.node;
-    if (node?.__typename !== "CheckRun" || node.annotations === undefined) {
-        return { pageInfo: { hasNextPage: false, endCursor: null }, nodes: [] };
-    }
-    return node.annotations;
-}
-function toCheckAnnotation(checkRunId, raw) {
-    const id = `check_annotation_${raw.fullDatabaseId ?? fallbackId(checkRunId, raw)}`;
-    const title = raw.title?.trim() || undefined;
-    const rawDetails = raw.rawDetails?.trim() || undefined;
-    const blobUrl = raw.blobUrl?.trim() || undefined;
-    return {
-        id,
-        path: raw.path,
-        startLine: raw.location?.start.line ?? null,
-        endLine: raw.location?.end.line ?? raw.location?.start.line ?? null,
-        ...(raw.location?.start.column !== undefined && {
-            startColumn: raw.location.start.column,
-        }),
-        ...(raw.location?.end.column !== undefined && {
-            endColumn: raw.location.end.column,
-        }),
-        level: raw.annotationLevel,
-        ...(title !== undefined && { title }),
-        message: truncateAnnotationText(raw.message),
-        ...(rawDetails !== undefined && { rawDetails: truncateAnnotationText(rawDetails) }),
-        ...(blobUrl !== undefined && { blobUrl }),
-    };
-}
-function truncateAnnotationText(text) {
-    if (text.length <= ANNOTATION_TEXT_MAX_CHARS)
-        return text;
-    return `${text.slice(0, ANNOTATION_TEXT_MAX_CHARS - TRUNCATED_SUFFIX.length).trimEnd()}${TRUNCATED_SUFFIX}`;
-}
-function fallbackId(checkRunId, raw) {
-    const start = raw.location?.start;
-    const end = raw.location?.end;
-    const parts = [
-        checkRunId,
-        raw.path,
-        raw.annotationLevel,
-        raw.title ?? "",
-        raw.message,
-        raw.rawDetails ?? "",
-        raw.blobUrl ?? "",
-        String(start?.line ?? ""),
-        String(start?.column ?? ""),
-        String(end?.line ?? ""),
-        String(end?.column ?? ""),
-    ];
-    const input = parts.map((part) => `${part.length}:${part}`).join("|");
-    return createHash("sha256").update(input).digest("hex").slice(0, 24);
-}

package/bin/github/gql/batch-pr.gql

@@ -121,7 +121,7 @@ query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
           state
         }
       }
-      reviewThreads(last: 100) {
+      reviewThreads(last: 20) {
         totalCount
         pageInfo {
           hasPreviousPage

package/bin/github/gql/check-run-annotations-batch.gql

@@ -0,0 +1,41 @@
+query CheckRunAnnotationsBatch($ids: [ID!]!) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
+  nodes(ids: $ids) {
+    id
+    __typename
+    ... on CheckRun {
+      annotations(first: 100) {
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+        nodes {
+          fullDatabaseId
+          path
+          annotationLevel
+          title
+          message
+          rawDetails
+          blobUrl
+          location {
+            start {
+              line
+              column
+            }
+            end {
+              line
+              column
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/bin/github/pagination.d.mts

@@ -33,7 +33,7 @@ export declare function paginateForward<T>(fetchFn: (cursor: string | null) => P
 /**
  * Paginate backward through a GraphQL connection (`last` / `before` cursors).
  *
- * Used for `reviewThreads(last: 100, before: $before)`.
+ * Used for `reviewThreads(last: 100, before: $before)` follow-up pages.
  *
  * @param fetchFn       Called once per page. Receives the cursor (or null for
  *                      the very first page). Returns a Connection<T> with

package/bin/github/pagination.mjs

@@ -35,7 +35,7 @@ export async function paginateForward(fetchFn, initialCursor) {
 /**
  * Paginate backward through a GraphQL connection (`last` / `before` cursors).
  *
- * Used for `reviewThreads(last: 100, before: $before)`.
+ * Used for `reviewThreads(last: 100, before: $before)` follow-up pages.
  *
  * @param fetchFn       Called once per page. Receives the cursor (or null for
  *                      the very first page). Returns a Connection<T> with

package/bin/github/poll-summary-check-blockers.d.mts

@@ -0,0 +1,16 @@
+import type { PollSummaryChecks, PollSummaryItem, PollSummaryReview } from "../types.mts";
+import type { RawSummaryPr } from "./poll-summary-raw.mts";
+type Routed = Pick<PollSummaryItem, "action" | "reasons">;
+/**
+ * A layer whose only failing checks are deferred on open blockers waits.
+ * Review work, conflicts, an incomplete rollup, or any check that is not
+ * deferred stay on the routed action. Stack rows are probed so the planner
+ * does not start a one-PR session for a wait it would otherwise shepherd.
+ */
+export declare function applyOpenCheckBlockers(raw: RawSummaryPr, repo: {
+    owner: string;
+    name: string;
+}, routed: Routed, checks: PollSummaryChecks, review: PollSummaryReview, stack: boolean): Promise<Routed & {
+    pollProbe?: true;
+}>;
+export {};

package/bin/github/poll-summary-check-blockers.mjs

@@ -0,0 +1,25 @@
+import { resolveCheckBlockerGate } from "../commands/iterate/check-blocker-gate.mjs";
+import { failingSummaryCheckNames } from "./poll-summary-checks.mjs";
+/**
+ * A layer whose only failing checks are deferred on open blockers waits.
+ * Review work, conflicts, an incomplete rollup, or any check that is not
+ * deferred stay on the routed action. Stack rows are probed so the planner
+ * does not start a one-PR session for a wait it would otherwise shepherd.
+ */
+export async function applyOpenCheckBlockers(raw, repo, routed, checks, review, stack) {
+    if (routed.action !== "fix_code" || !routed.reasons.includes("failing-checks"))
+        return routed;
+    if ((review.actionable ?? 0) > 0 || checks.incomplete)
+        return routed;
+    const names = failingSummaryCheckNames(raw);
+    if (names.length === 0)
+        return routed;
+    const gate = await resolveCheckBlockerGate({ owner: repo.owner, repo: repo.name, pr: raw.number }, names.map((name) => ({ name })));
+    if (!gate || !names.every((name) => gate.deferredNames.has(name)))
+        return routed;
+    return {
+        action: "wait",
+        reasons: gate.openBlockers.map((ref) => `blocked-by:${ref}`),
+        ...(stack ? { pollProbe: true } : {}),
+    };
+}

package/bin/github/poll-summary-checks.d.mts

@@ -1,3 +1,5 @@
 import type { PollSummaryChecks } from "../types.mts";
 import type { RawSummaryPr } from "./poll-summary-raw.mts";
 export declare function summarizePollSummaryChecks(raw: RawSummaryPr): PollSummaryChecks;
+/** Names of failing checks in the loaded summary rollup. */
+export declare function failingSummaryCheckNames(raw: RawSummaryPr): string[];

package/bin/github/poll-summary-checks.mjs

@@ -1,10 +1,43 @@
 import { classifyChecks } from "../checks/classify.mjs";
 export function summarizePollSummaryChecks(raw) {
-    const rollups = [
+    const rollups = summaryRollups(raw);
+    const counts = {};
+    for (const check of classifyChecks(checkRuns(rollups), {
+        additionalRelevantEvents: ["merge_group"],
+    })) {
+        const key = {
+            passed: "passing",
+            failing: "failing",
+            in_progress: "inProgress",
+            skipped: "skipped",
+            filtered: "filtered",
+            ignored: "ignored",
+            superseded: "superseded",
+        }[check.category];
+        counts[key] = (counts[key] ?? 0) + 1;
+    }
+    const summary = counts;
+    if (rollups.some((rollup) => rollup.contexts.pageInfo.hasPreviousPage)) {
+        summary.incomplete = true;
+    }
+    return summary;
+}
+/** Names of failing checks in the loaded summary rollup. */
+export function failingSummaryCheckNames(raw) {
+    return classifyChecks(checkRuns(summaryRollups(raw)), {
+        additionalRelevantEvents: ["merge_group"],
+    })
+        .filter((check) => check.category === "failing")
+        .map((check) => check.name);
+}
+function summaryRollups(raw) {
+    return [
         raw.commits.nodes[0]?.commit.statusCheckRollup,
         raw.mergeQueueEntry?.headCommit?.statusCheckRollup,
     ].filter((rollup) => rollup !== null && rollup !== undefined);
-    const checks = rollups.flatMap((rollup, rollupIndex) => rollup.contexts.nodes.map((context) => {
+}
+function checkRuns(rollups) {
+    return rollups.flatMap((rollup, rollupIndex) => rollup.contexts.nodes.map((context) => {
         if (context.__typename === "StatusContext") {
             return {
                 name: context.context,
@@ -40,22 +73,4 @@ export function summarizePollSummaryChecks(raw) {
             ...(rollupIndex === 1 && { scope: "merge_group" }),
         };
     }));
-    const counts = {};
-    for (const check of classifyChecks(checks, { additionalRelevantEvents: ["merge_group"] })) {
-        const key = {
-            passed: "passing",
-            failing: "failing",
-            in_progress: "inProgress",
-            skipped: "skipped",
-            filtered: "filtered",
-            ignored: "ignored",
-            superseded: "superseded",
-        }[check.category];
-        counts[key] = (counts[key] ?? 0) + 1;
-    }
-    const summary = counts;
-    if (rollups.some((rollup) => rollup.contexts.pageInfo.hasPreviousPage)) {
-        summary.incomplete = true;
-    }
-    return summary;
 }

package/bin/github/poll-summary-projector.mjs

@@ -9,6 +9,7 @@ import { summarizePollSummaryReview } from "./poll-summary-review.mjs";
 import { fingerprintRawSummaryPr } from "./poll-summary-fingerprint.mjs";
 import { currentQueueRemovalEvent } from "./poll-summary-queue-removal.mjs";
 import { isCurrentSummaryReady } from "./poll-summary-readiness.mjs";
+import { applyOpenCheckBlockers } from "./poll-summary-check-blockers.mjs";
 import { normalizePollSummaryState, routePollSummary } from "./poll-summary-route.mjs";
 export async function summarizePollSummaryPr(raw, repo, opts, viewerCanAdminister = false) {
     const repoName = `${repo.owner}/${repo.name}`;
@@ -69,6 +70,9 @@ export async function summarizePollSummaryPr(raw, repo, opts, viewerCanAdministe
         : removalEvent
             ? projectQueueRemoval(removalEvent)
             : undefined;
+    const blocked = await applyOpenCheckBlockers(raw, repo, { action, reasons }, checks, review, opts.stackPrNumber !== undefined);
+    action = blocked.action;
+    reasons = blocked.reasons;
     return {
         pr: raw.number,
         repo: repoName,
@@ -97,6 +101,7 @@ export async function summarizePollSummaryPr(raw, repo, opts, viewerCanAdministe
                 !(opts.stackPrNumber !== undefined && raw.stack && action === "merge"))
             ? pollCommandFields(repoName, raw.number, raw.isDraft, opts)
             : {}),
+        ...(blocked.pollProbe ? { pollProbe: true } : {}),
     };
 }
 function projectQueueRemoval(removal) {

package/bin/github/queries.d.mts

@@ -29,6 +29,12 @@ export declare const SUGGESTION_THREADS_QUERY: string;
 export declare const REVIEW_THREAD_COMMENTS_QUERY: string;
 /** Fetch inline annotations for a single CheckRun by node ID. */
 export declare const CHECK_RUN_ANNOTATIONS_QUERY: string;
+/**
+ * First annotation page for many CheckRuns. Chunked at 20 ids so the nested
+ * `annotations` connections stay a 1-point query. Further pages use
+ * `CHECK_RUN_ANNOTATIONS_QUERY`.
+ */
+export declare const CHECK_RUN_ANNOTATIONS_BATCH_QUERY: string;
 /** Fetches additional status contexts for a merge queue synthetic commit. */
 export declare const COMMIT_CHECK_CONTEXTS_QUERY: string;
 /** Returns the current head commit SHA for a PR. Used by waitForSha polling. */

package/bin/github/queries.mjs

@@ -34,6 +34,12 @@ export const SUGGESTION_THREADS_QUERY = gql("suggestion-threads.gql");
 export const REVIEW_THREAD_COMMENTS_QUERY = gql("review-thread-comments.gql");
 /** Fetch inline annotations for a single CheckRun by node ID. */
 export const CHECK_RUN_ANNOTATIONS_QUERY = gql("check-run-annotations.gql");
+/**
+ * First annotation page for many CheckRuns. Chunked at 20 ids so the nested
+ * `annotations` connections stay a 1-point query. Further pages use
+ * `CHECK_RUN_ANNOTATIONS_QUERY`.
+ */
+export const CHECK_RUN_ANNOTATIONS_BATCH_QUERY = gql("check-run-annotations-batch.gql");
 /** Fetches additional status contexts for a merge queue synthetic commit. */
 export const COMMIT_CHECK_CONTEXTS_QUERY = gql("commit-check-contexts.gql");
 /** Returns the current head commit SHA for a PR. Used by waitForSha polling. */

package/bin/state/check-blockers.d.mts

@@ -0,0 +1,30 @@
+/**
+ * Per-PR records that a failing check is blocked on an external PR or issue.
+ *
+ * `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/<pr>/check-blockers.json`
+ */
+export interface CheckBlockerRef {
+    owner: string;
+    name: string;
+    number: number;
+    kind: "pull" | "issue";
+}
+export interface CheckBlockerRecord {
+    checkName: string;
+    blocker: CheckBlockerRef;
+    /** Unix seconds. */
+    recordedAt: number;
+}
+interface StateKey {
+    owner: string;
+    repo: string;
+    pr: number;
+}
+export declare function formatCheckBlockerRef(blocker: CheckBlockerRef): string;
+/** Missing, unreadable, or malformed state is an empty list. Does not throw. */
+export declare function readCheckBlockers(key: StateKey): Promise<CheckBlockerRecord[]>;
+/** Insert or replace the record for `checkName`. Returns false when the file cannot be written. */
+export declare function writeCheckBlocker(key: StateKey, record: CheckBlockerRecord): Promise<boolean>;
+/** Drop one check's record. A missing record is success and does not create a file. */
+export declare function clearCheckBlocker(key: StateKey, checkName: string): Promise<boolean>;
+export {};

package/bin/state/check-blockers.mjs

@@ -0,0 +1,88 @@
+/**
+ * Per-PR records that a failing check is blocked on an external PR or issue.
+ *
+ * `$PR_SHEPHERD_STATE_DIR/<owner>/<repo>/<pr>/check-blockers.json`
+ */
+import { readFile, writeFile, rename, unlink, mkdir } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { dirname } from "node:path";
+import { resolvePrStatePath } from "./base.mjs";
+const FILE = "check-blockers.json";
+export function formatCheckBlockerRef(blocker) {
+    return `${blocker.owner}/${blocker.name}#${blocker.number}`;
+}
+/** Missing, unreadable, or malformed state is an empty list. Does not throw. */
+export async function readCheckBlockers(key) {
+    try {
+        const parsed = JSON.parse(await readFile(resolvePrStatePath(key, FILE), "utf8"));
+        if (parsed === null || typeof parsed !== "object")
+            return [];
+        const blockers = parsed.blockers;
+        if (!Array.isArray(blockers))
+            return [];
+        return blockers.filter(isRecord);
+    }
+    catch {
+        return [];
+    }
+}
+/** Insert or replace the record for `checkName`. Returns false when the file cannot be written. */
+export async function writeCheckBlocker(key, record) {
+    const blockers = (await readCheckBlockers(key)).filter((item) => item.checkName !== record.checkName);
+    blockers.push(record);
+    return writeAll(key, blockers);
+}
+/** Drop one check's record. A missing record is success and does not create a file. */
+export async function clearCheckBlocker(key, checkName) {
+    const current = await readCheckBlockers(key);
+    const blockers = current.filter((item) => item.checkName !== checkName);
+    if (blockers.length === current.length)
+        return true;
+    return writeAll(key, blockers);
+}
+async function writeAll(key, blockers) {
+    let tmp;
+    try {
+        const path = resolvePrStatePath(key, FILE);
+        tmp = `${path}.${randomUUID()}.tmp`;
+        await mkdir(dirname(path), { recursive: true });
+        await writeFile(tmp, `${JSON.stringify({ blockers })}\n`, "utf8");
+        await rename(tmp, path);
+        tmp = undefined;
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        if (tmp !== undefined) {
+            try {
+                await unlink(tmp);
+            }
+            catch {
+                // The failed write may not have created the temp file.
+            }
+        }
+    }
+}
+function isRecord(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const record = value;
+    return (typeof record.checkName === "string" &&
+        record.checkName.length > 0 &&
+        typeof record.recordedAt === "number" &&
+        Number.isFinite(record.recordedAt) &&
+        isBlocker(record.blocker));
+}
+function isBlocker(value) {
+    if (value === null || typeof value !== "object")
+        return false;
+    const blocker = value;
+    return ((blocker.kind === "pull" || blocker.kind === "issue") &&
+        typeof blocker.owner === "string" &&
+        typeof blocker.name === "string" &&
+        typeof blocker.number === "number" &&
+        Number.isInteger(blocker.number) &&
+        blocker.number > 0);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.53.1",
+  "version": "0.54.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for agentic coding tools",
   "keywords": [
     "automation",

package/plugins/pr-shepherd/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "pr-shepherd",
-  "version": "0.53.1",
+  "version": "0.54.0",
   "description": "Autonomous PR CI monitor and review-comment resolver for Codex.",
   "author": {
     "name": "Jonathan Ong",

package/plugins/pr-shepherd/.codex.mcp.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "pr-shepherd": {
       "command": "npx",
-      "args": ["--yes", "--package", "pr-shepherd@0.53.1", "pr-shepherd-mcp"]
+      "args": ["--yes", "--package", "pr-shepherd@0.54.0", "pr-shepherd-mcp"]
     }
   }
 }

package/plugins/pr-shepherd/.mcp.json

@@ -1,6 +1,6 @@
 {
   "pr-shepherd": {
     "command": "npx",
-    "args": ["--yes", "--package", "pr-shepherd@0.53.1", "pr-shepherd-mcp"]
+    "args": ["--yes", "--package", "pr-shepherd@0.54.0", "pr-shepherd-mcp"]
   }
 }