pr-shepherd 0.56.6 → 0.57.1

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

@@ -1,4 +1,5 @@
 import type { RawBaseRef } from "./batch-raw-rules.mts";
+import type { AutoMergeRequestStatus } from "../types/merge-requirements.mts";
 export interface RawAuthor {
     __typename?: string;
     login: string;
@@ -6,11 +7,24 @@ export interface RawAuthor {
 interface RawSummaryComment {
     id: string;
     body: string;
-    isMinimized: boolean;
+    isMinimized?: boolean;
     viewerDidAuthor?: boolean;
     authorAssociation?: string;
     url?: string;
     author: RawAuthor | null;
+    /** GraphQL handoff fields; absent on REST summaries. */
+    viewerCanMinimize?: boolean;
+    createdAt?: string;
+    updatedAt?: string;
+    pullRequestReview?: {
+        id: string;
+    } | null;
+    path?: string | null;
+    line?: number | null;
+    startLine?: number | null;
+    commit?: {
+        oid: string;
+    } | null;
 }
 interface SummaryConnection<T> {
     totalCount: number;
@@ -25,7 +39,7 @@ type RawCheckContext = {
     name: string;
     status: string;
     conclusion: string | null;
-    detailsUrl?: string;
+    detailsUrl?: string | null;
     startedAt?: string | null;
     completedAt?: string | null;
     annotations?: {
@@ -33,10 +47,12 @@ type RawCheckContext = {
     };
     checkSuite: {
         createdAt?: string | null;
+        updatedAt?: string | null;
         workflowRun: {
             databaseId?: string | number;
             event: string;
             createdAt?: string | null;
+            updatedAt?: string | null;
             workflow?: {
                 name: string;
                 databaseId: string | number;
@@ -47,6 +63,9 @@ type RawCheckContext = {
     __typename: "StatusContext";
     context: string;
     state: string;
+    createdAt?: string;
+    targetUrl?: string | null;
+    description?: string | null;
 };
 interface RawCheckContexts {
     totalCount: number;
@@ -58,6 +77,7 @@ interface RawCheckContexts {
     nodes: RawCheckContext[];
 }
 export interface RawCheckRollup {
+    state?: string | null;
     contexts: RawCheckContexts;
 }
 /** A commit whose status contexts the compact summary reads. */
@@ -66,16 +86,47 @@ export interface RawSummaryCommit {
     committedDate?: string;
     statusCheckRollup: RawCheckRollup | null;
     checkSuites?: {
+        pageInfo?: {
+            hasNextPage: boolean;
+        };
         nodes: Array<{
+            id?: string;
             status?: string | null;
             conclusion: string | null;
             workflowRun: {
+                databaseId?: number | null;
                 event: string | null;
+                url?: string | null;
+                workflow?: {
+                    name: string | null;
+                } | null;
             } | null;
         }>;
     } | null;
 }
 export interface RawSummaryPr {
+    transport?: "rest";
+    transportUnavailable?: Array<{
+        field: string;
+        reason: string;
+    }>;
+    /** GraphQL handoff fields (see `stack-handoff.mts`); absent on REST summaries. */
+    id?: string;
+    viewerDidAuthor?: boolean;
+    viewerCanEnableAutoMerge?: boolean;
+    viewerCanEditFiles?: boolean;
+    headRepository?: {
+        nameWithOwner: string;
+        viewerPermission: string | null;
+    } | null;
+    isMergeQueueEnabled?: boolean;
+    batchAutoMergeRequest?: {
+        enabledAt: string;
+        mergeMethod: string;
+        enabledBy?: {
+            login: string;
+        } | null;
+    } | null;
     number: number;
     title: string;
     url: string;
@@ -91,7 +142,7 @@ export interface RawSummaryPr {
         }>;
     } | null;
     isDraft: boolean;
-    viewerCanUpdate: boolean;
+    viewerCanUpdate?: boolean;
     headRefName: string;
     headRefOid: string;
     baseRefOid: string;
@@ -102,7 +153,9 @@ export interface RawSummaryPr {
     reviewDecision: string | null;
     reviewRequests?: {
         nodes: Array<{
-            requestedReviewer: RawAuthor | null;
+            requestedReviewer: (Partial<RawAuthor> & {
+                name?: string;
+            }) | null;
         }>;
     };
     latestReviews?: {
@@ -111,7 +164,8 @@ export interface RawSummaryPr {
             author: RawAuthor | null;
         }>;
     };
-    isInMergeQueue: boolean;
+    isInMergeQueue?: boolean;
+    autoMergeRequest?: AutoMergeRequestStatus | null;
     mergeQueueAdditions?: {
         nodes: Array<{
             createdAt: string;
@@ -158,15 +212,21 @@ export interface RawSummaryPr {
     }>;
     reviewThreads: SummaryConnection<{
         id: string;
-        isResolved: boolean;
-        isOutdated: boolean;
+        isResolved?: boolean;
+        isOutdated?: boolean;
+        viewerCanReply?: boolean;
+        viewerCanResolve?: boolean;
         path: string | null;
-        rootComments?: {
-            nodes: RawSummaryComment[];
-        };
+        line?: number | null;
+        startLine?: number | null;
+        /**
+         * The first comments from the root. `pageInfo.hasPreviousPage` is GraphQL's
+         * `hasNextPage` (aliased): true when comments exist outside this window.
+         */
         comments: SummaryConnection<RawSummaryComment>;
     }>;
     commits: {
+        totalCount?: number;
         nodes: Array<{
             commit: RawSummaryCommit;
         }>;

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

@@ -1,6 +1,11 @@
 import type { PollSummaryChecks, PollSummaryReview } from "../types.mts";
 import type { RawSummaryPr } from "./poll-summary-raw.mts";
-/** Fresh compact evidence required before a READY receipt can be used. */
+/**
+ * Fresh compact evidence required before a READY receipt can be used.
+ * `allowBlocked` asks whether GitHub's BLOCKED state is the only gap, so a
+ * caller can tell a blocker it cannot clear from missing or stale evidence.
+ */
 export declare function isCurrentSummaryReady(raw: RawSummaryPr, checks: PollSummaryChecks, review: PollSummaryReview, options?: {
     allowQueuedProgress?: boolean;
+    allowBlocked?: boolean;
 }): boolean;

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

@@ -1,8 +1,16 @@
 import { summarizePollSummaryChecks } from "./poll-summary-checks.mjs";
 import { parseBranchRules } from "./batch-parsers-rules.mjs";
 import { rulesComplete } from "./fingerprint-fields.mjs";
-/** Fresh compact evidence required before a READY receipt can be used. */
+import { isKnownMergeStateStatus, transportReadinessGaps } from "./transport-evidence.mjs";
+/**
+ * Fresh compact evidence required before a READY receipt can be used.
+ * `allowBlocked` asks whether GitHub's BLOCKED state is the only gap, so a
+ * caller can tell a blocker it cannot clear from missing or stale evidence.
+ */
 export function isCurrentSummaryReady(raw, checks, review, options = {}) {
+    const blockedStates = options.allowBlocked
+        ? ["DIRTY", "BEHIND", "UNKNOWN", "HAS_HOOKS"]
+        : ["DIRTY", "BEHIND", "UNKNOWN", "BLOCKED", "HAS_HOOKS"];
     const queued = options.allowQueuedProgress === true && raw.isInMergeQueue;
     // Merge-group checks may still be running after the PR earned its receipt;
     // source-commit checks must remain complete. A fresh pending source check is
@@ -16,7 +24,9 @@ export function isCurrentSummaryReady(raw, checks, review, options = {}) {
     // satisfied. BLOCKED is not conversation-specific, and queue progress
     // alone is not that proof.
     const requiresConversationResolution = parseBranchRules(raw.baseRef).requiresConversationResolution;
-    return (checks.incomplete !== true &&
+    return (isKnownMergeStateStatus(raw.mergeStateStatus) &&
+        transportReadinessGaps(raw, raw.mergeStateStatus).length === 0 &&
+        checks.incomplete !== true &&
         sourceChecks.incomplete !== true &&
         (review.incomplete !== true ||
             raw.mergeStateStatus === "CLEAN" ||
@@ -26,8 +36,7 @@ export function isCurrentSummaryReady(raw, checks, review, options = {}) {
         raw.mergeable !== "CONFLICTING" &&
         raw.mergeStateStatus !== "DIRTY" &&
         (queued || raw.mergeable === "MERGEABLE") &&
-        (queued ||
-            !["DIRTY", "BEHIND", "UNKNOWN", "BLOCKED", "HAS_HOOKS"].includes(raw.mergeStateStatus)) &&
+        (queued || !blockedStates.includes(raw.mergeStateStatus)) &&
         (checks.failing ?? 0) === 0 &&
         (sourceChecks.failing ?? 0) === 0 &&
         (sourceChecks.inProgress ?? 0) === 0 &&

package/bin/github/poll-summary-rest-queue.d.mts

@@ -0,0 +1,3 @@
+import type { RawSummaryPr } from "./poll-summary-raw.mts";
+/** Positive rules remain authoritative even when other branch policy is unavailable. */
+export declare function restQueueRequirement(raw: Pick<RawSummaryPr, "baseRef" | "transportUnavailable">): boolean | undefined;

package/bin/github/poll-summary-rest-queue.mjs

@@ -0,0 +1,12 @@
+import { parseBranchRules } from "./batch-parsers-rules.mjs";
+/** Positive rules remain authoritative even when other branch policy is unavailable. */
+export function restQueueRequirement(raw) {
+    if (parseBranchRules(raw.baseRef).requiresMergeQueue)
+        return true;
+    if (!raw.baseRef?.rules ||
+        raw.baseRef.rules.pageInfo?.hasNextPage !== false ||
+        raw.baseRef.branchProtectionRule !== null ||
+        raw.transportUnavailable?.some(({ field }) => ["branchProtection", "branchRules"].includes(field)))
+        return undefined;
+    return false;
+}

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

@@ -1,4 +1,4 @@
 import { type SeenMarker } from "../state/seen-comments.mts";
 import type { PollSummaryReview } from "../types.mts";
 import type { RawSummaryPr } from "./poll-summary-raw.mts";
-export declare function summarizePollSummaryReview(raw: RawSummaryPr, seen: Map<string, SeenMarker>, viewerCanAdminister: boolean): Promise<PollSummaryReview>;
+export declare function summarizePollSummaryReview(raw: RawSummaryPr, seen: Map<string, SeenMarker>, viewerCanAdminister: boolean | undefined): Promise<PollSummaryReview>;

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

@@ -1,14 +1,18 @@
 import { normalizeBotUsernames } from "../comments/authors.mjs";
 import { applyRules } from "../classify/apply.mjs";
-import { discoverRuleFiles, loadRules } from "../classify/loader.mjs";
+import { normalizeAuthorType } from "../comments/authors.mjs";
+import { loadClassifyRules } from "../classify/loader.mjs";
 import { loadConfig } from "../config/load.mjs";
 import { getEffectiveCwd } from "../execution-context.mjs";
 import { classifyItem } from "../state/seen-comments.mjs";
+import { mutationWasDenied } from "../state/seen-comments.mjs";
+import { canGenerateGithubMutation } from "./mutation-policy.mjs";
+import { threadEndedByShepherd } from "../comments/marker.mjs";
 const THREAD_COMMENT_SEPARATOR = "\n\n--- thread comment ---\n\n";
 export async function summarizePollSummaryReview(raw, seen, viewerCanAdminister) {
     const config = loadConfig();
     const bots = normalizeBotUsernames(config.botUsernames);
-    const rules = await loadRules(discoverRuleFiles(getEffectiveCwd()));
+    const rules = await loadClassifyRules(getEffectiveCwd(), config.standardRules);
     let actionable = 0;
     let incomplete = raw.comments.pageInfo.hasPreviousPage ||
         raw.reviews.pageInfo.hasPreviousPage ||
@@ -37,24 +41,35 @@ export async function summarizePollSummaryReview(raw, seen, viewerCanAdminister)
         if (isSuppressed(rules, "changes-requested", review))
             continue;
         const isBot = review.author?.__typename === "Bot" || bots.has(review.author?.login.toLowerCase() ?? "");
-        if ((isBot && viewerCanAdminister) ||
+        if ((isBot &&
+            canGenerateGithubMutation(viewerCanAdminister, "dismiss") &&
+            !mutationWasDenied(review.id, review.body, seen)) ||
             classifyItem(review.id, review.body, seen) !== "unchanged")
             actionable += 1;
     }
     for (const thread of raw.reviewThreads.nodes) {
-        if (thread.comments.pageInfo.hasPreviousPage)
+        // The window holds the first comments. Past it, a new reply leaves the window
+        // unchanged, so a long thread cannot prove it was seen.
+        const truncated = thread.comments.pageInfo.hasPreviousPage;
+        if (truncated)
             incomplete = true;
-        const root = thread.rootComments?.nodes[0] ?? thread.comments.nodes[0];
+        const root = thread.comments.nodes[0];
         const transcript = thread.comments.nodes
             .map((comment) => comment.body)
             .join(THREAD_COMMENT_SEPARATOR);
-        if (isSuppressed(rules, "review-thread", root, thread.id, thread.path, transcript))
+        const completeResolved = thread.isResolved === true && !truncated;
+        if (completeResolved &&
+            threadEndedByShepherd({ body: root?.body ?? "", comments: thread.comments.nodes }))
             continue;
-        const repeatable = root?.viewerDidAuthor === true ||
-            root?.author?.__typename === "Bot" ||
-            bots.has(root?.author?.login.toLowerCase() ?? "");
-        const unseen = classifyItem(thread.id, transcript, seen) !== "unchanged";
-        if ((!thread.isResolved && (repeatable || unseen)) ||
+        if (isSuppressed(rules, "review-thread", root, thread.id, thread.path ?? root?.path ?? null, root?.body ?? "", completeResolved))
+            continue;
+        const repeatable = !mutationWasDenied(thread.id, transcript, seen) &&
+            (root?.viewerDidAuthor === true ||
+                root?.author?.__typename === "Bot" ||
+                bots.has(root?.author?.login.toLowerCase() ?? ""));
+        const unseen = truncated || classifyItem(thread.id, transcript, seen) !== "unchanged";
+        if ((thread.isResolved === false && (repeatable || unseen)) ||
+            (thread.isResolved === undefined && unseen) ||
             ((thread.isResolved || thread.isOutdated) && unseen))
             actionable += 1;
     }
@@ -66,20 +81,20 @@ export async function summarizePollSummaryReview(raw, seen, viewerCanAdminister)
         ...(incomplete && { incomplete: true }),
     };
 }
-function isSuppressed(rules, kind, raw, id = raw?.id ?? "unknown", path, body = raw?.body ?? "") {
+function isSuppressed(rules, kind, raw, id = raw?.id ?? "unknown", path, body = raw?.body ?? "", autoResolveSatisfied = false) {
     const item = {
         kind,
         id,
         author: raw?.author?.login ?? "unknown",
-        authorType: raw?.author?.__typename === "Bot"
-            ? "Bot"
-            : raw?.author?.__typename === "User"
-                ? "User"
-                : "Unknown",
-        ...(raw?.authorAssociation && { authorAssociation: raw.authorAssociation }),
+        authorType: normalizeAuthorType(raw?.author?.__typename, raw?.author?.login),
+        ...(raw?.authorAssociation !== undefined && { authorAssociation: raw.authorAssociation }),
         body,
-        ...(raw?.url && { url: raw.url }),
+        ...(kind === "review-thread" ? { url: raw?.url ?? "" } : raw?.url ? { url: raw.url } : {}),
         ...(kind === "review-thread" && { path }),
     };
-    return applyRules(rules, item).suppress === true;
+    const action = applyRules(rules, item);
+    // An auto-resolve match is hidden only once the full check minimizes or resolves it, or
+    // surfaces a denied mutation once; until then it stays actionable so that check runs.
+    return (action.suppress === true &&
+        (action.autoResolve !== true || kind === "changes-requested" || autoResolveSatisfied));
 }

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

@@ -1,4 +1,7 @@
 import { loadConfig } from "../config/load.mjs";
+import { isKnownMergeStateStatus, transportReadinessGaps } from "./transport-evidence.mjs";
+import { canGenerateGithubMutation } from "./mutation-policy.mjs";
+import { getGithubTransport, isCcrTransport } from "./transport.mjs";
 export function routePollSummary(raw, checks, review, opts) {
     const actions = loadConfig().actions;
     const state = normalizePollSummaryState(raw.state);
@@ -22,7 +25,13 @@ export function routePollSummary(raw, checks, review, opts) {
         return { action: "fix_code", reasons: ["unreported-required-checks"] };
     }
     if ((checks.inProgress ?? 0) > 0 ||
+        !isKnownMergeStateStatus(raw.mergeStateStatus) ||
         raw.mergeable === "UNKNOWN" ||
+        raw.mergeStateStatus === "UNKNOWN")
+        return { action: "wait", reasons: ["pending-or-unknown"] };
+    if (transportReadinessGaps(raw, raw.mergeStateStatus).length > 0)
+        return { action: "escalate", reasons: ["transport-unsupported"] };
+    if (raw.mergeable === "UNKNOWN" ||
         raw.mergeStateStatus === "UNKNOWN" ||
         raw.mergeStateStatus === "BEHIND" ||
         raw.mergeStateStatus === "BLOCKED" ||
@@ -33,15 +42,22 @@ export function routePollSummary(raw, checks, review, opts) {
         const autoMarkReadyDisabled = opts.noAutoMarkReady || actions.autoMarkReady === false;
         // The stack selector asks the agent to mark a disabled draft ready, so
         // that transition needs the same capability as the automatic one.
-        if (!raw.viewerCanUpdate && (!autoMarkReadyDisabled || opts.stackPrNumber !== undefined)) {
+        if (!canGenerateGithubMutation(raw.viewerCanUpdate, "ready") &&
+            (!autoMarkReadyDisabled || opts.stackPrNumber !== undefined)) {
+            const unsupported = getGithubTransport() === "rest" && raw.viewerCanUpdate !== false && !isCcrTransport();
+            if (unsupported)
+                return { action: "escalate", reasons: ["transport-unsupported"] };
             return { action: "escalate", reasons: ["mark-ready-authorization-required"] };
         }
         return autoMarkReadyDisabled
             ? { action: "wait", reasons: ["draft-auto-mark-ready-disabled"] }
             : { action: "mark_ready", reasons: ["draft-appears-ready"] };
     }
-    if (opts.merge && raw.isInMergeQueue) {
-        return { action: "wait", reasons: ["already-in-merge-queue"] };
+    if (opts.merge && (raw.isInMergeQueue || raw.autoMergeRequest)) {
+        return {
+            action: "wait",
+            reasons: [raw.isInMergeQueue ? "already-in-merge-queue" : "already-auto-merging"],
+        };
     }
     if (opts.merge && raw.stack && opts.stackPrNumber === undefined) {
         return { action: "fix_code", reasons: ["authoritative-poll-required"] };

package/bin/github/poll-summary-stack-page.d.mts

@@ -0,0 +1,11 @@
+import type { RepoInfo } from "./client.mts";
+import type { RawSummaryPr } from "./poll-summary-raw.mts";
+import { type StackRead } from "./stack-read.mts";
+/**
+ * Read the hydrated stack in pages of at most `stackSize` entries.
+ * A wide check matrix can blow GitHub's per-query resource limit on the full
+ * page. Halve `first` down to one entry and let `readStack` follow `after`.
+ * The shared summary fragment stays intact: one layer is the same shape as an
+ * explicit summary, and check hydration still completes windows past 100.
+ */
+export declare function readGraphqlStackSummary(anchor: number, repo: RepoInfo, stackSize: number): Promise<StackRead<RawSummaryPr>>;

package/bin/github/poll-summary-stack-page.mjs

@@ -0,0 +1,27 @@
+import { GitHubRequestError, isRetryableGraphQlResourceLimit } from "./errors.mjs";
+import { POLL_STACK_SUMMARY_QUERY } from "./queries.mjs";
+import { MAX_STACK_ENTRIES_PER_PAGE, readStack } from "./stack-read.mjs";
+/**
+ * Read the hydrated stack in pages of at most `stackSize` entries.
+ * A wide check matrix can blow GitHub's per-query resource limit on the full
+ * page. Halve `first` down to one entry and let `readStack` follow `after`.
+ * The shared summary fragment stays intact: one layer is the same shape as an
+ * explicit summary, and check hydration still completes windows past 100.
+ */
+export async function readGraphqlStackSummary(anchor, repo, stackSize) {
+    let ceiling = MAX_STACK_ENTRIES_PER_PAGE;
+    for (;;) {
+        const first = Math.max(1, Math.min(stackSize, ceiling));
+        try {
+            return await readStack(POLL_STACK_SUMMARY_QUERY, anchor, repo, { first }, ceiling);
+        }
+        catch (err) {
+            if (!(err instanceof GitHubRequestError) ||
+                !isRetryableGraphQlResourceLimit(err.graphqlErrors) ||
+                first <= 1) {
+                throw err;
+            }
+            ceiling = Math.floor(first / 2);
+        }
+    }
+}

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

@@ -3,5 +3,7 @@ import type { PollSummaryChecks } from "../types.mts";
 import type { RawSummaryPr } from "./poll-summary-raw.mts";
 /** Current trunk rules may remain available on a merged layer's base ref. */
 export declare function trunkRequiredContexts(ordered: readonly RawSummaryPr[], repo: RepoInfo): Promise<string[] | undefined>;
+/** Required contexts of the layer's merge target: the trunk's for a stack layer when known. */
+export declare function summaryRequiredContexts(raw: RawSummaryPr, mergeTargetContexts: readonly string[] | undefined): string[];
 /** Record missing required contexts. A running Actions workflow does not clear the names. */
-export declare function applyUnreportedRequiredChecks(raw: RawSummaryPr, checks: PollSummaryChecks, mergeTargetContexts: readonly string[] | undefined): void;
+export declare function applyUnreportedRequiredChecks(raw: RawSummaryPr, checks: PollSummaryChecks, required: readonly string[]): void;

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

@@ -16,15 +16,18 @@ export async function trunkRequiredContexts(ordered, repo) {
     const loaded = await loadRefRules(repo.owner, repo.name, `refs/heads/${trunk}`, bottom.headRefOid);
     return loaded.contexts;
 }
-/** Record missing required contexts. A running Actions workflow does not clear the names. */
-export function applyUnreportedRequiredChecks(raw, checks, mergeTargetContexts) {
+/** Required contexts of the layer's merge target: the trunk's for a stack layer when known. */
+export function summaryRequiredContexts(raw, mergeTargetContexts) {
     const trunk = raw.stack?.baseRefName;
-    const required = selectMergeTargetContexts({
+    return selectMergeTargetContexts({
         localContexts: parseBranchRules(raw.baseRef).requiredStatusCheckContexts,
         ...(mergeTargetContexts !== undefined && { trunkContexts: mergeTargetContexts }),
         baseRefName: raw.baseRefName,
         ...(trunk !== undefined && mergeTargetContexts !== undefined && { trunkRefName: trunk }),
     });
+}
+/** Record missing required contexts. A running Actions workflow does not clear the names. */
+export function applyUnreportedRequiredChecks(raw, checks, required) {
     const missing = unreportedRequiredContexts(required, reportedNames(raw));
     if (missing.length === 0)
         return;

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

@@ -1,12 +1,15 @@
 import type { PollSummaryCommandOptions, PollSummaryItem, PollSummarySelection, PollSummaryStackAncestry } from "../types.mts";
 import { type RepoInfo } from "./client.mts";
 import type { RawSummaryPr } from "./poll-summary-raw.mts";
+import type { StackHandoffSource } from "./stack-handoff-page.mts";
 export interface FetchedPollSummary {
     selection: PollSummarySelection;
     prs: PollSummaryItem[];
     stackAncestry?: PollSummaryStackAncestry[];
     allowedMergeMethods?: import("../config/merge-method.mts").MergeMethod[];
+    /** GraphQL stack reads only: the raw layers a routing tick hands to its one-PR sessions. */
+    handoffSource?: StackHandoffSource;
 }
-export declare function fetchPollSummary(opts: PollSummaryCommandOptions, repo: RepoInfo): Promise<FetchedPollSummary>;
 /** Fresh, read-only snapshot used to bind a one-PR READY receipt to stack routing. */
 export declare function fetchRawSummaryPr(pr: number, repo: RepoInfo): Promise<RawSummaryPr>;
+export declare function fetchPollSummary(opts: PollSummaryCommandOptions, repo: RepoInfo): Promise<FetchedPollSummary>;

package/bin/github/poll-summary.mjs

@@ -1,22 +1,29 @@
+import { readRestStackSummary } from "./rest-stack-summary.mjs";
+import { githubOperation, getGithubTransport, runWithGithubTransport } from "./transport.mjs";
+import { readRestExplicitSummary } from "./rest-explicit-summary-read.mjs";
+import { withRestConditionalScope } from "./rest-conditional-scope.mjs";
 import { EXIT, ShepherdError } from "../exit-codes.mjs";
 import { graphqlWithRateLimit } from "./client.mjs";
-import { GitHubRequestError, isRetryableGraphQlResourceLimit, missingRepositoryError, } from "./errors.mjs";
+import { missingRepositoryError } from "./errors.mjs";
 import { hydratePollSummaryChecks } from "./poll-summary-check-hydration.mjs";
 import { refreshUnknownSummaryMergeability } from "./poll-summary-mergeability.mjs";
 import { summarizePollSummaryPr } from "./poll-summary-projector.mjs";
 import { trunkRequiredContexts } from "./poll-summary-unreported.mjs";
-import { POLL_STACK_SUMMARY_QUERY, POLL_SUMMARY_FRAGMENT } from "./queries.mjs";
-import { MAX_STACK_ENTRIES_PER_PAGE, readStack, readStackTopology, stackAncestryGaps, } from "./stack-read.mjs";
+import { loadStackSizeHint, storeStackSizeHint } from "./stack-size-hint.mjs";
+import { POLL_SUMMARY_FRAGMENT } from "./queries.mjs";
+import { stackAncestryGaps } from "./stack-read.mjs";
+import { readGraphqlStackSummary } from "./poll-summary-stack-page.mjs";
+import { stackHandoffSource } from "./stack-handoff.mjs";
 const MAX_EXPLICIT_PRS_PER_QUERY = 50;
-export async function fetchPollSummary(opts, repo) {
+async function fetchSelectedPollSummary(opts, repo) {
     if (opts.stackPrNumber !== undefined)
         return fetchStackSummary(opts, repo);
-    const requested = deduplicate(opts.prNumbers ?? []);
+    const requested = [...new Set(opts.prNumbers ?? [])];
     if (requested.length === 0) {
         throw new ShepherdError("Aggregate poll requires at least two PRs or --stack <PR>", EXIT.USAGE);
     }
     const raw = [];
-    let viewerCanAdminister = false;
+    let viewerCanAdminister;
     for (let offset = 0; offset < requested.length; offset += MAX_EXPLICIT_PRS_PER_QUERY) {
         const chunk = requested.slice(offset, offset + MAX_EXPLICIT_PRS_PER_QUERY);
         const fetched = await fetchExplicitChunk(chunk, repo);
@@ -33,7 +40,7 @@ export async function fetchRawSummaryPr(pr, repo) {
     const fetched = await fetchExplicitChunk([pr], repo);
     return fetched.prs[0];
 }
-async function fetchExplicitChunk(prs, repo) {
+async function fetchGraphqlExplicitChunk(prs, repo) {
     const declarations = prs.map((_, index) => `$pr${index}: Int!`).join(", ");
     const aliases = prs
         .map((_, index) => `pr${index}: pullRequest(number: $pr${index}) { ...PollSummaryPr }`)
@@ -59,18 +66,39 @@ async function fetchExplicitChunk(prs, repo) {
     }
     return { prs: rawPrs, viewerCanAdminister: result.data.repository.viewerCanAdminister };
 }
+async function fetchExplicitChunk(prs, repo) {
+    return githubOperation("PollSummary", () => runWithGithubTransport("graphql", () => fetchGraphqlExplicitChunk(prs, repo)), async () => ({
+        prs: await withSummaryConditionalScope(repo, prs[0], () => readRestExplicitSummary(prs, repo)),
+    }));
+}
+/**
+ * Entries on an unsized first summary page. GitHub prices `first`, not the
+ * nodes returned, and four layers are the most that still price at 1 point.
+ * Larger stacks page on, sized to the entries that remain.
+ */
+const UNSIZED_STACK_SUMMARY_FIRST = 4;
 /**
- * Read the stack's topology first so the hydrated page requests only as many
- * entries as the stack holds: GitHub prices `first`, not the nodes returned.
+ * Size the hydrated page to the stack so it requests only as many entries as the
+ * stack holds. The size comes from the anchor's last summary; the first summary
+ * reads four entries and pages on, which never costs more than reading the
+ * topology first. A stack that has since grown pages on, and one that shrank
+ * overpays once.
  */
 async function fetchStackSummary(opts, repo) {
     const anchor = opts.stackPrNumber;
-    const topology = await readStackTopology(anchor, repo);
-    const { stackNumber, stackSize, viewerLogin, viewerCanAdminister, ordered, allowedMergeMethods } = await readStackSummary(anchor, repo, topology.stackSize);
+    const stateKey = { owner: repo.owner, repo: repo.name, pr: anchor };
+    const graphql = getGithubTransport() !== "rest";
+    const hint = graphql ? await loadStackSizeHint(stateKey) : 0;
+    const sizeHint = hint || UNSIZED_STACK_SUMMARY_FIRST;
+    const read = await readStackSummary(anchor, repo, sizeHint);
+    const { stackNumber, stackSize, viewerLogin, viewerCanAdminister, ordered, allowedMergeMethods } = read;
+    if (graphql && stackSize !== hint)
+        await storeStackSizeHint(stateKey, stackSize);
     for (const pr of ordered) {
         await hydratePollSummaryChecks(pr, repo);
         await refreshUnknownSummaryMergeability(pr, repo);
     }
+    const handoffSource = getGithubTransport() === "rest" ? undefined : stackHandoffSource(read);
     const stackAncestry = stackAncestryGaps(ordered);
     const required = await trunkRequiredContexts(ordered, repo);
     return {
@@ -78,30 +106,16 @@ async function fetchStackSummary(opts, repo) {
         prs: await Promise.all(ordered.map((pr) => summarizePollSummaryPr(pr, repo, opts, viewerCanAdminister, required, viewerLogin))),
         ...(stackAncestry.length > 0 && { stackAncestry }),
         ...(allowedMergeMethods && { allowedMergeMethods }),
+        ...(handoffSource && { handoffSource }),
     };
 }
-/**
- * A wide check matrix can blow GitHub's per-query resource limit on the full
- * page. Halve `first` down to one entry and let `readStack` follow `after`.
- * The shared summary fragment stays intact: one layer is the same shape as an
- * explicit summary, and check hydration still completes windows past 100.
- */
 async function readStackSummary(anchor, repo, stackSize) {
-    let first = Math.min(stackSize, MAX_STACK_ENTRIES_PER_PAGE);
-    for (;;) {
-        try {
-            return await readStack(POLL_STACK_SUMMARY_QUERY, anchor, repo, { first });
-        }
-        catch (err) {
-            if (!(err instanceof GitHubRequestError) ||
-                !isRetryableGraphQlResourceLimit(err.graphqlErrors) ||
-                first <= 1) {
-                throw err;
-            }
-            first = Math.floor(first / 2);
-        }
-    }
+    return githubOperation("PollStackSummary", () => readGraphqlStackSummary(anchor, repo, stackSize), () => withSummaryConditionalScope(repo, anchor, () => readRestStackSummary(anchor, repo)));
+}
+/** REST summary reads are conditional under the anchor PR's state: an unchanged body is a free 304. */
+function withSummaryConditionalScope(repo, pr, read) {
+    return withRestConditionalScope({ owner: repo.owner, repo: repo.name, pr }, read);
 }
-function deduplicate(values) {
-    return [...new Set(values)];
+export function fetchPollSummary(opts, repo) {
+    return githubOperation("PollSummarySelection", () => runWithGithubTransport("graphql", () => fetchSelectedPollSummary(opts, repo)), () => fetchSelectedPollSummary(opts, repo));
 }

package/bin/github/queries.d.mts

@@ -10,11 +10,13 @@
 export declare const BATCH_PR_QUERY: string;
 /** Slim @include follow-up for outstanding batch-query connections. */
 export declare const BATCH_PR_PAGE_QUERY: string;
-/** Cheap PR fingerprint used to skip an unchanged BatchPr snapshot. */
-export declare const PR_FINGERPRINT_QUERY: string;
 /** Compact per-PR fields shared by explicit-list and native-stack summary queries. */
 export declare const POLL_SUMMARY_FRAGMENT: string;
-/** Exact compact summary sibling only when a one-PR READY receipt needs evidence. */
+/**
+ * Exact compact summary sibling only when a one-PR READY receipt needs evidence.
+ * The batch's first context page shrinks to 50 so the sibling still prices at 1 point;
+ * `BatchPrPage` reads any further contexts.
+ */
 export declare const BATCH_PR_RECEIPT_QUERY: string;
 /** Trunk branch rules plus how far `headRef` is behind that branch. */
 export declare const REF_RULES_QUERY: string;
@@ -68,3 +70,5 @@ export declare const MARK_PR_READY_MUTATION: string;
 export declare const GET_PR_BODY_QUERY: string;
 /** Update the PR body. */
 export declare const UPDATE_PR_BODY_MUTATION: string;
+/** CheckRun titles, summaries, and first annotations for routed stack-layer handoffs. */
+export declare const STACK_HANDOFF_CHECK_RUNS_QUERY: string;