pr-shepherd 0.53.1 → 0.54.0

package/bin/commands/poll-rate-limit-wait.mjs

@@ -0,0 +1,125 @@
+import { rest } from "../github/rest-http.mjs";
+import { sleep } from "../util/sleep.mjs";
+import { formatRateLimitGiveUpLine, formatRateLimitRetryLine, pollRateLimitRetryAfterMs, } from "./poll-quota.mjs";
+const MAX_NO_PROGRESS_ATTEMPTS = 5;
+const NO_PROGRESS_BACKOFF_MS = [15_000, 30_000, 60_000];
+const MERGE_STATES = new Set([
+    "BEHIND",
+    "BLOCKED",
+    "CLEAN",
+    "DIRTY",
+    "DRAFT",
+    "HAS_HOOKS",
+    "UNKNOWN",
+    "UNSTABLE",
+]);
+export function createUntilTerminalRateLimitRetry() {
+    const state = { armed: false, noProgress: 0 };
+    return {
+        reset() {
+            state.armed = false;
+            state.noProgress = 0;
+            state.lastResetAt = undefined;
+        },
+        wait(err, opts) {
+            return waitForRateLimit(state, err, opts);
+        },
+    };
+}
+function backoffMs(attempt) {
+    return NO_PROGRESS_BACKOFF_MS[Math.min(attempt, NO_PROGRESS_BACKOFF_MS.length) - 1] ?? 60_000;
+}
+async function waitForRateLimit(state, err, opts) {
+    const retry = opts.untilTerminal ? pollRateLimitRetryAfterMs(err) : null;
+    if (!retry)
+        throw err;
+    const elapsed = Math.round((Date.now() - opts.startedAt) / 1000);
+    const progressed = state.armed &&
+        retry.resetAt !== undefined &&
+        (state.lastResetAt === undefined || retry.resetAt > state.lastResetAt);
+    let sleepMs = retry.ms;
+    if (!state.armed || progressed) {
+        state.armed = true;
+        state.noProgress = 0;
+        if (retry.resetAt !== undefined)
+            state.lastResetAt = retry.resetAt;
+    }
+    else {
+        state.noProgress += 1;
+        if (state.noProgress >= MAX_NO_PROGRESS_ATTEMPTS) {
+            process.stderr.write(formatRateLimitGiveUpLine(opts.tickLabel, elapsed, retry));
+            throw err;
+        }
+        // Never sleep less than GitHub asked for. A short no-progress backoff must
+        // not undercut an explicit Retry-After or the secondary-limit default.
+        sleepMs = Math.max(retry.ms, backoffMs(state.noProgress));
+    }
+    process.stderr.write(formatRateLimitRetryLine(opts.tickLabel, elapsed, { ...retry, ms: sleepMs }));
+    return sleepRateLimit(sleepMs, opts, retry.resource);
+}
+async function sleepRateLimit(ms, opts, resource) {
+    const canProbe = resource !== "core" && opts.targets.length > 0;
+    if (ms <= opts.intervalMs || opts.intervalMs <= 0) {
+        await sleep(ms);
+        return undefined;
+    }
+    let remaining = ms;
+    let probesDisabled = !canProbe;
+    while (remaining > 0) {
+        const chunk = Math.min(opts.intervalMs, remaining);
+        await sleep(chunk);
+        remaining -= chunk;
+        if (remaining <= 0 || probesDisabled)
+            continue;
+        try {
+            const found = await probeOpenPulls(opts.targets, opts.onAllTerminal);
+            if (found !== undefined)
+                return found;
+        }
+        catch {
+            // The probe only notices a merge or close early. A 5xx, a 404, or a
+            // secondary limit must not abort the rate-limit sleep.
+            probesDisabled = true;
+        }
+    }
+    return undefined;
+}
+async function probeOpenPulls(targets, onAllTerminal) {
+    const pulls = [];
+    for (const target of targets) {
+        // GraphQL is exhausted for this sleep. REST core is a separate budget, so
+        // GET /repos/{owner}/{repo}/pulls/{n} can still see a merge or close.
+        const data = await rest("GET", `/repos/${target.owner}/${target.repo}/pulls/${target.pr}`);
+        const state = terminalState(data);
+        if (!state)
+            return undefined;
+        pulls.push(toProbePull(target.pr, state, data));
+    }
+    return onAllTerminal?.(pulls);
+}
+function terminalState(pull) {
+    if (!pull)
+        return undefined;
+    if (pull.merged === true || pull.merged_at != null)
+        return "MERGED";
+    if (pull.state?.toLowerCase() === "closed")
+        return "CLOSED";
+    return undefined;
+}
+function toProbePull(pr, state, pull) {
+    const mergeState = pull.mergeable_state?.toUpperCase();
+    return {
+        pr,
+        state,
+        title: pull.title ?? "",
+        url: pull.html_url ?? "",
+        draft: pull.draft === true,
+        mergeable: pull.mergeable === true ? "MERGEABLE" : pull.mergeable === false ? "CONFLICTING" : "UNKNOWN",
+        mergeStateStatus: MERGE_STATES.has(mergeState ?? "")
+            ? mergeState
+            : "UNKNOWN",
+        baseRefName: pull.base?.ref ?? "",
+        headRefName: pull.head?.ref ?? "",
+        headRefOid: pull.head?.sha ?? "",
+    };
+}

package/bin/commands/poll-summary.mjs

@@ -5,7 +5,9 @@ import { getRepoInfo } from "../github/client.mjs";
 import { withApiTelemetryScope, summarizeApiTelemetry } from "../github/api-telemetry.mjs";
 import { fetchPollSummary } from "../github/poll-summary.mjs";
 import { sleep } from "../util/sleep.mjs";
-import { aggregateQuotaWarning, formatRateLimitRetryLine, pollRateLimitRetryAfterMs, quotaPollIntervalMs, } from "./poll-quota.mjs";
+import { aggregateQuotaWarning, quotaPollIntervalMs } from "./poll-quota.mjs";
+import { aggregateCancelFromPulls, aggregateRateLimitTargets } from "./poll-rate-limit-cancel.mjs";
+import { createUntilTerminalRateLimitRetry } from "./poll-rate-limit-wait.mjs";
 import { planPollSummary, withPollSummaryInstructions } from "./poll-summary-instructions.mjs";
 import { summaryStatusSignature } from "./poll-summary-signature.mjs";
 import { applyStackStallGuard } from "./stack-stall.mjs";
@@ -42,13 +44,13 @@ async function runAggregatePollCore(opts) {
     let debounceUntil = null;
     let last;
     let lastStatusSignature = null;
-    let rateLimitRetries = 0;
+    const rateLimitRetry = createUntilTerminalRateLimitRetry();
     let pendingQuotaWarning;
     while (true) {
         tick += 1;
         try {
             last = await runPollSummaryCore(opts);
-            rateLimitRetries = 0;
+            rateLimitRetry.reset();
         }
         catch (error) {
             if (last?.selection.kind === "stack" && isMissingStack(error)) {
@@ -83,12 +85,17 @@ async function runAggregatePollCore(opts) {
                     ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
                 }, opts.merge);
             }
-            const retry = opts.untilTerminal ? pollRateLimitRetryAfterMs(error) : null;
-            if (retry === null || rateLimitRetries >= 1)
-                throw error;
-            rateLimitRetries += 1;
-            process.stderr.write(formatRateLimitRetryLine(`aggregate poll tick ${tick}`, Math.round((Date.now() - start) / 1000), retry));
-            await sleep(retry.ms);
+            const early = await rateLimitRetry.wait(error, {
+                untilTerminal: opts.untilTerminal === true,
+                intervalMs,
+                tickLabel: `aggregate poll tick ${tick}`,
+                startedAt: start,
+                targets: aggregateRateLimitTargets(last, opts.targetRepository, opts.prNumbers),
+                onAllTerminal: (pulls) => aggregateCancelFromPulls(last, opts.targetRepository, pulls),
+            });
+            if (early) {
+                return presentProbedCancel(pendingQuotaWarning ? { ...early, quotaWarning: pendingQuotaWarning } : early, opts.merge);
+            }
             continue;
         }
         const allTerminal = last.selection.kind === "stack"
@@ -159,6 +166,11 @@ async function runAggregatePollCore(opts) {
         await sleep(sleepMs);
     }
 }
+function presentProbedCancel(result, merge) {
+    // The stack planner already cancels an all-merged stack and escalates a
+    // closed-unmerged layer. Do not rewrite that into a successful stop.
+    return attachUsage({ ...result, reason: "all_terminal" }, merge);
+}
 function isMissingStack(error) {
     return (error instanceof ShepherdError && error.message.includes("not part of a native GitHub stack"));
 }

package/bin/commands/poll.mjs

@@ -2,7 +2,9 @@ import { runIterate } from "./iterate/index.mjs";
 import { sleep } from "../util/sleep.mjs";
 import { withPollApiUsage } from "./poll-run.mjs";
 import { loadConfig } from "../config/load.mjs";
-import { formatRateLimitRetryLine, pollRateLimitRetryAfterMs, quotaPollIntervalMs, } from "./poll-quota.mjs";
+import { quotaPollIntervalMs } from "./poll-quota.mjs";
+import { onePrCancelFromPulls, onePrRateLimitTargets } from "./poll-rate-limit-cancel.mjs";
+import { createUntilTerminalRateLimitRetry } from "./poll-rate-limit-wait.mjs";
 import { writeDebounceProgress, writeWaitProgress } from "./poll-progress.mjs";
 const DEFAULT_POLL_DEBOUNCE_SECONDS = 60;
 const MAX_TIMER_MS = 2 ** 31 - 1;
@@ -29,7 +31,7 @@ async function runPollCore(opts) {
     // Pin the PR resolved by the first tick; branch inference only matches OPEN PRs.
     let prNumber = opts.prNumber;
     let debounceUntil = null;
-    let rateLimitRetries = 0;
+    const rateLimitRetry = createUntilTerminalRateLimitRetry();
     while (true) {
         tick += 1;
         const pastDebounce = debounceUntil !== null && Date.now() >= debounceUntil;
@@ -48,21 +50,24 @@ async function runPollCore(opts) {
             quotaWarningMinimumPollIntervalMinutes: intervalSeconds / 60,
         });
         const runTick = async (fingerprintCache) => {
-            try {
-                const result = await iterateTick(fingerprintCache);
-                rateLimitRetries = 0;
-                return result;
-            }
-            catch (err) {
-                const retry = untilTerminal ? pollRateLimitRetryAfterMs(err) : null;
-                if (retry === null || rateLimitRetries >= 1)
-                    throw err;
-                rateLimitRetries += 1;
-                process.stderr.write(formatRateLimitRetryLine(`poll tick ${tick}`, Math.round((Date.now() - start) / 1000), retry));
-                await sleep(retry.ms);
-                const result = await iterateTick(fingerprintCache);
-                rateLimitRetries = 0;
-                return result;
+            while (true) {
+                try {
+                    const result = await iterateTick(fingerprintCache);
+                    rateLimitRetry.reset();
+                    return result;
+                }
+                catch (err) {
+                    const early = await rateLimitRetry.wait(err, {
+                        untilTerminal,
+                        intervalMs,
+                        tickLabel: `poll tick ${tick}`,
+                        startedAt: start,
+                        targets: onePrRateLimitTargets(iterateOpts.targetRepository, prNumber, lastResult?.repo),
+                        onAllTerminal: (pulls) => onePrCancelFromPulls(iterateOpts.targetRepository, lastResult?.repo, pulls),
+                    });
+                    if (early)
+                        return early;
+                }
             }
         };
         lastResult = await runTick(allowCache);

package/bin/config/load.d.mts

@@ -8,6 +8,8 @@ export interface GraphqlQuotaWarningBand {
 }
 interface PollConfig {
     intervalSeconds: number;
+    /** Multiplier for aggregate polls when `--interval` is omitted. Finite and at least 1. */
+    stackIntervalFactor: number;
     timeoutSeconds: number;
     debounceSeconds: number;
     quietStatus: boolean;

package/bin/config/load.mjs

@@ -153,11 +153,27 @@ function parsePollConfig(value) {
     const intervalSeconds = parsePollDuration(record["intervalSeconds"], "intervalSeconds");
     const timeoutSeconds = parsePollDuration(record["timeoutSeconds"], "timeoutSeconds");
     const debounceSeconds = parsePollDuration(record["debounceSeconds"], "debounceSeconds", true);
+    const stackIntervalFactor = parseStackIntervalFactor(record["stackIntervalFactor"]);
+    assertAggregateIntervalFits(intervalSeconds, stackIntervalFactor);
     const quietStatus = record["quietStatus"];
     if (typeof quietStatus !== "boolean") {
         throw new Error(`Invalid config: poll.quietStatus must be a boolean, got ${JSON.stringify(quietStatus)}`);
     }
-    return { intervalSeconds, timeoutSeconds, debounceSeconds, quietStatus };
+    return { intervalSeconds, stackIntervalFactor, timeoutSeconds, debounceSeconds, quietStatus };
+}
+function parseStackIntervalFactor(value) {
+    if (typeof value !== "number" || !Number.isFinite(value) || value < 1) {
+        throw new Error(`Invalid config: poll.stackIntervalFactor must be a finite number greater than or equal to 1, got ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+/** Largest `setTimeout` delay. A bigger aggregate sleep would clamp to ~24.8 days. */
+const MAX_POLL_INTERVAL_MS = 2 ** 31 - 1;
+function assertAggregateIntervalFits(intervalSeconds, factor) {
+    const ms = intervalSeconds * factor * 1000;
+    if (!Number.isFinite(ms) || ms > MAX_POLL_INTERVAL_MS) {
+        throw new Error(`Invalid config: poll.intervalSeconds * poll.stackIntervalFactor must be finite and at most ${MAX_POLL_INTERVAL_MS} milliseconds, got ${JSON.stringify(ms)}`);
+    }
 }
 function parsePollDuration(value, key, allowZero = false) {
     if (typeof value !== "number" ||
@@ -252,7 +268,13 @@ const KNOWN_NESTED_KEYS = {
         "behindBaseHint",
         "resolveOtherHumanThreads",
     ]),
-    poll: new Set(["intervalSeconds", "timeoutSeconds", "debounceSeconds", "quietStatus"]),
+    poll: new Set([
+        "intervalSeconds",
+        "stackIntervalFactor",
+        "timeoutSeconds",
+        "debounceSeconds",
+        "quietStatus",
+    ]),
     watch: new Set(["readyDelayMinutes", "graphqlQuotaWarnings"]),
     resolve: new Set(["shaPoll"]),
     checks: new Set(["ciTriggerEvents", "ignoreLogLines"]),

package/bin/config.json

@@ -25,6 +25,7 @@
   },
   "poll": {
     "intervalSeconds": 60,
+    "stackIntervalFactor": 2,
     "timeoutSeconds": 270,
     "debounceSeconds": 60,
     "quietStatus": false

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[]>;