pr-shepherd 0.53.1 → 0.54.1

package/bin/github/check-annotation-cache.d.mts

@@ -0,0 +1,8 @@
+import { type StateKey } from "../state/rest-cache.mts";
+import type { CheckAnnotation } from "../types.mts";
+export interface AnnotationCacheOptions {
+    stateKey: StateKey;
+    headSha?: string;
+}
+export declare function readFreshCheckAnnotations(checkRunId: string, cacheOpts: AnnotationCacheOptions | undefined): Promise<CheckAnnotation[] | undefined>;
+export declare function storeCheckAnnotations(checkRunId: string, annotations: CheckAnnotation[], cacheOpts: AnnotationCacheOptions | undefined): Promise<void>;

package/bin/github/check-annotation-cache.mjs

@@ -0,0 +1,23 @@
+import { loadDerived, storeDerived } from "../state/rest-cache.mjs";
+/**
+ * Some Checks-API publishers PATCH additional annotations onto an already
+ * COMPLETED check run without minting a new node id, so COMPLETED is not a
+ * reliable immutability signal. Bound the cache instead of trusting it forever.
+ */
+const ANNOTATION_CACHE_MAX_AGE_MS = 60 * 60 * 1000;
+function cacheName(checkRunId) {
+    return `annotations-${checkRunId}`;
+}
+export async function readFreshCheckAnnotations(checkRunId, cacheOpts) {
+    if (!cacheOpts)
+        return undefined;
+    const cached = await loadDerived(cacheOpts.stateKey, cacheName(checkRunId));
+    if (cached && Date.now() - cached.storedAt < ANNOTATION_CACHE_MAX_AGE_MS)
+        return cached.value;
+    return undefined;
+}
+export async function storeCheckAnnotations(checkRunId, annotations, cacheOpts) {
+    if (!cacheOpts)
+        return;
+    await storeDerived(cacheOpts.stateKey, cacheName(checkRunId), annotations, cacheOpts.headSha);
+}

package/bin/github/check-annotation-pages.d.mts

@@ -0,0 +1,11 @@
+import { type RawCheckAnnotation } from "./check-annotation-shape.mts";
+import type { CheckAnnotation } from "../types.mts";
+export interface AnnotationPage {
+    pageInfo: {
+        hasNextPage: boolean;
+        endCursor: string | null;
+    };
+    nodes: RawCheckAnnotation[];
+}
+/** Pages a single check run. `firstPage` skips the initial `node(id:)` request. */
+export declare function collectAnnotations(checkRunId: string, firstPage?: AnnotationPage): Promise<CheckAnnotation[]>;

package/bin/github/check-annotation-pages.mjs

@@ -0,0 +1,36 @@
+import { graphql } from "./client.mjs";
+import { toCheckAnnotation } from "./check-annotation-shape.mjs";
+import { CHECK_RUN_ANNOTATIONS_QUERY } from "./queries.mjs";
+const ANNOTATIONS_PER_PAGE = 100;
+const MAX_ANNOTATION_PAGES = 10;
+/** Pages a single check run. `firstPage` skips the initial `node(id:)` request. */
+export async function collectAnnotations(checkRunId, firstPage) {
+    const nodes = [];
+    let cursor = null;
+    let seeded = firstPage;
+    for (let pageNumber = 1; pageNumber <= MAX_ANNOTATION_PAGES; pageNumber++) {
+        // eslint-disable-next-line no-await-in-loop
+        const current = seeded ?? (await fetchAnnotationPage(checkRunId, cursor));
+        seeded = undefined;
+        nodes.push(...current.nodes);
+        if (!current.pageInfo.hasNextPage || !current.pageInfo.endCursor)
+            break;
+        if (pageNumber === 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 = current.pageInfo.endCursor;
+    }
+    return nodes.map((node) => toCheckAnnotation(checkRunId, node));
+}
+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;
+}

package/bin/github/check-annotation-shape.d.mts

@@ -0,0 +1,21 @@
+import type { CheckAnnotation } from "../types.mts";
+export interface RawCheckAnnotation {
+    fullDatabaseId: string | null;
+    path: string;
+    annotationLevel: string;
+    title: string | null;
+    message: string;
+    rawDetails: string | null;
+    blobUrl: string | null;
+    location: {
+        start: {
+            line: number | null;
+            column: number | null;
+        };
+        end: {
+            line: number | null;
+            column: number | null;
+        };
+    } | null;
+}
+export declare function toCheckAnnotation(checkRunId: string, raw: RawCheckAnnotation): CheckAnnotation;

package/bin/github/check-annotation-shape.mjs

@@ -0,0 +1,50 @@
+import { createHash } from "node:crypto";
+const ANNOTATION_TEXT_MAX_CHARS = 4_000;
+const TRUNCATED_SUFFIX = "\n[truncated]";
+export 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/check-annotations-batch.d.mts

@@ -0,0 +1,17 @@
+import type { CheckAnnotation } from "../types.mts";
+import { type AnnotationCacheOptions } from "./check-annotation-cache.mts";
+interface AnnotationBatchFailure {
+    checkRunId: string;
+    error: unknown;
+}
+interface CheckAnnotationBatchResult {
+    annotations: Map<string, CheckAnnotation[]>;
+    failures: AnnotationBatchFailure[];
+}
+/**
+ * First annotation page for every uncached id, in chunks of 20. Further pages
+ * use the single-node query and only run when that first page has `hasNextPage`.
+ * A retryable rate limit aborts the remaining chunks and pages.
+ */
+export declare function fetchCheckRunAnnotationsBatch(checkRunIds: string[], cacheOpts?: AnnotationCacheOptions): Promise<CheckAnnotationBatchResult>;
+export {};

package/bin/github/check-annotations-batch.mjs

@@ -0,0 +1,92 @@
+import { pollRateLimitRetryAfterMs } from "../commands/poll-quota.mjs";
+import { readFreshCheckAnnotations, } from "./check-annotation-cache.mjs";
+import {} from "./check-annotation-shape.mjs";
+import { fetchCheckRunAnnotations } from "./check-annotations.mjs";
+import { graphql } from "./client.mjs";
+import { CHECK_RUN_ANNOTATIONS_BATCH_QUERY } from "./queries.mjs";
+/**
+ * One `nodes` connection plus one nested `annotations(first: 100)` per id.
+ * 20 ids are 21 connection-requests, which GitHub prices as 1 point.
+ */
+const ANNOTATION_BATCH_CHUNK_SIZE = 20;
+function chunksOf(items, size) {
+    const chunks = [];
+    for (let index = 0; index < items.length; index += size) {
+        chunks.push(items.slice(index, index + size));
+    }
+    return chunks;
+}
+function retryableRateLimit(err) {
+    return pollRateLimitRetryAfterMs(err) !== null;
+}
+/**
+ * First annotation page for every uncached id, in chunks of 20. Further pages
+ * use the single-node query and only run when that first page has `hasNextPage`.
+ * A retryable rate limit aborts the remaining chunks and pages.
+ */
+export async function fetchCheckRunAnnotationsBatch(checkRunIds, cacheOpts) {
+    const annotations = new Map();
+    const failures = [];
+    const cached = await Promise.all(checkRunIds.map((id) => readFreshCheckAnnotations(id, cacheOpts)));
+    const uncached = [];
+    checkRunIds.forEach((id, index) => {
+        const hit = cached[index];
+        if (hit)
+            annotations.set(id, hit);
+        else
+            uncached.push(id);
+    });
+    for (const chunk of chunksOf(uncached, ANNOTATION_BATCH_CHUNK_SIZE)) {
+        // eslint-disable-next-line no-await-in-loop
+        await fetchChunk(chunk, annotations, failures, cacheOpts);
+    }
+    return { annotations, failures };
+}
+async function fetchChunk(chunk, annotations, failures, cacheOpts) {
+    try {
+        const nodes = await requestFirstPages(chunk);
+        await applyBatchNodes(chunk, nodes, annotations, failures, cacheOpts);
+    }
+    catch (err) {
+        if (retryableRateLimit(err))
+            throw err;
+        // A non-rate-limit batch failure (one NOT_FOUND or FORBIDDEN node rejects
+        // the whole `nodes(ids:)` request) must not drop the other ids.
+        await fetchChunkOneByOne(chunk, annotations, failures, cacheOpts);
+    }
+}
+async function applyBatchNodes(chunk, nodes, annotations, failures, cacheOpts) {
+    for (const id of chunk) {
+        const node = nodes.find((candidate) => candidate?.id === id) ?? null;
+        if (node?.__typename !== "CheckRun" || node.annotations === undefined) {
+            failures.push({ checkRunId: id, error: new Error("check run annotations unavailable") });
+            continue;
+        }
+        try {
+            // eslint-disable-next-line no-await-in-loop
+            annotations.set(id, await fetchCheckRunAnnotations(id, cacheOpts, node.annotations));
+        }
+        catch (err) {
+            if (retryableRateLimit(err))
+                throw err;
+            failures.push({ checkRunId: id, error: err });
+        }
+    }
+}
+async function fetchChunkOneByOne(chunk, annotations, failures, cacheOpts) {
+    for (const id of chunk) {
+        try {
+            // eslint-disable-next-line no-await-in-loop
+            annotations.set(id, await fetchCheckRunAnnotations(id, cacheOpts));
+        }
+        catch (err) {
+            if (retryableRateLimit(err))
+                throw err;
+            failures.push({ checkRunId: id, error: err });
+        }
+    }
+}
+async function requestFirstPages(ids) {
+    const res = await graphql(CHECK_RUN_ANNOTATIONS_BATCH_QUERY, { ids }, { allowPartialData: true });
+    return res.data.nodes ?? [];
+}

package/bin/github/check-annotations.d.mts

@@ -1,15 +1,12 @@
-import { type StateKey } from "../state/rest-cache.mts";
+import { type AnnotationCacheOptions } from "./check-annotation-cache.mts";
+import { type AnnotationPage } from "./check-annotation-pages.mts";
 import type { CheckAnnotation } from "../types.mts";
-export interface AnnotationCacheOptions {
-    stateKey: StateKey;
-    headSha?: string;
-}
 /**
- * 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 declare function fetchCheckRunAnnotations(checkRunId: string, cacheOpts?: AnnotationCacheOptions): Promise<CheckAnnotation[]>;
+export declare function fetchCheckRunAnnotations(checkRunId: string, cacheOpts?: AnnotationCacheOptions, initialPage?: AnnotationPage): Promise<CheckAnnotation[]>;

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/gql/upper-layer-conflict-target.gql

@@ -0,0 +1,36 @@
+query UpperLayerConflictTarget($owner: String!, $name: String!, $number: Int!, $headRef: String!) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
+  repository(owner: $owner, name: $name) {
+    pullRequest(number: $number) {
+      # compare() is invoked on the PR base. behindBy is commits on that base
+      # that the head does not contain — the same direction as REST base...head.
+      baseRef {
+        compare(headRef: $headRef) {
+          behindBy
+        }
+      }
+      stack {
+        entries(first: 100) {
+          pageInfo {
+            hasNextPage
+          }
+          nodes {
+            position
+            pullRequest {
+              number
+              state
+              baseRefName
+            }
+          }
+        }
+      }
+    }
+  }
+}

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;
 }