pr-shepherd 0.48.0 → 0.49.0

package/bin/cli/poll-targets.mjs

@@ -0,0 +1,114 @@
+import { parseArgs } from "node:util";
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+import { getRepoInfo } from "../github/client.mjs";
+import { parseCliPrReference, normalizeRepositoryIdentity, resolveParsedPrTarget, } from "../pr-reference.mjs";
+const VALUE_FLAGS = new Set([
+    "--format",
+    "--ready-delay",
+    "--stall-timeout",
+    "--interval",
+    "--timeout",
+    "--debounce",
+    "--stack",
+]);
+export function parsePollTargets(args) {
+    const { values } = parseArgs({
+        args,
+        strict: false,
+        allowPositionals: true,
+        options: { format: { type: "string" }, verbose: { type: "boolean" } },
+    });
+    const consumed = new Set();
+    const refs = [];
+    let stack;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (VALUE_FLAGS.has(arg)) {
+            if (arg === "--format" || arg === "--stack") {
+                consumed.add(index);
+                if (index + 1 < args.length)
+                    consumed.add(index + 1);
+            }
+            if (arg === "--stack") {
+                const parsed = parseCliPrReference(args[index + 1] ?? "");
+                if (!parsed)
+                    return usage(`invalid --stack PR reference: ${args[index + 1] ?? "(missing)"}`);
+                if (stack)
+                    return usage("--stack may only be specified once");
+                stack = parsed;
+            }
+            index += 1;
+            continue;
+        }
+        const equals = arg.indexOf("=");
+        const name = equals < 0 ? arg : arg.slice(0, equals);
+        if (VALUE_FLAGS.has(name)) {
+            if (name === "--format" || name === "--stack")
+                consumed.add(index);
+            if (name === "--stack") {
+                const parsed = parseCliPrReference(arg.slice(equals + 1));
+                if (!parsed)
+                    return usage(`invalid --stack PR reference: ${arg.slice(equals + 1)}`);
+                if (stack)
+                    return usage("--stack may only be specified once");
+                stack = parsed;
+            }
+            continue;
+        }
+        if (arg === "--verbose") {
+            consumed.add(index);
+            continue;
+        }
+        if (arg.startsWith("--"))
+            continue;
+        const parsed = parseCliPrReference(arg);
+        if (!parsed)
+            continue;
+        refs.push(parsed);
+        consumed.add(index);
+    }
+    if (stack && refs.length > 0)
+        return usage("--stack cannot be combined with explicit PRs");
+    const format = (values.format ?? "text");
+    return {
+        refs,
+        stack,
+        global: { format, verbose: values.verbose === true },
+        extra: args.filter((_, index) => !consumed.has(index)),
+    };
+}
+export async function resolvePollTargets(parsed) {
+    const all = parsed.stack ? [parsed.stack] : parsed.refs;
+    if (all.length === 0)
+        return { prNumbers: [] };
+    const checkoutRepo = all.some((ref) => ref.repository === undefined)
+        ? await getRepoInfo()
+        : undefined;
+    let selectedRepo;
+    const prNumbers = [];
+    for (const ref of all) {
+        const target = resolveParsedPrTarget(ref);
+        if (target.prNumber === undefined)
+            return usageThrow("PR number is required");
+        const repo = target.targetRepository ?? checkoutRepo;
+        if (selectedRepo &&
+            normalizeRepositoryIdentity(`${selectedRepo.owner}/${selectedRepo.name}`) !==
+                normalizeRepositoryIdentity(`${repo.owner}/${repo.name}`)) {
+            return usageThrow("aggregate poll only supports PRs from one repository");
+        }
+        selectedRepo = repo;
+        if (!prNumbers.includes(target.prNumber))
+            prNumbers.push(target.prNumber);
+    }
+    return parsed.stack
+        ? { prNumbers: [], stackPrNumber: prNumbers[0], targetRepository: selectedRepo }
+        : { prNumbers, targetRepository: selectedRepo };
+}
+function usage(message) {
+    process.stderr.write(`pr-shepherd: ${message}\n`);
+    process.exitCode = EXIT.USAGE;
+    return null;
+}
+function usageThrow(message) {
+    throw new ShepherdError(message, EXIT.USAGE);
+}

package/bin/cli/validate-default-args.mjs

@@ -5,7 +5,6 @@ import { parsePrNumber } from "./args.mjs";
  * offending arg so callers can print their own usage message.
  */
 export function validateDefaultArgs(args, flagsWithValues, booleanFlags, onError) {
-    let sawPr = false;
     for (let i = 0; i < args.length; i += 1) {
         const arg = args[i];
         if (flagsWithValues.has(arg)) {
@@ -21,10 +20,8 @@ export function validateDefaultArgs(args, flagsWithValues, booleanFlags, onError
             continue;
         if (booleanFlags.has(arg))
             continue;
-        if (parsePrNumber(arg) !== null && !sawPr) {
-            sawPr = true;
+        if (parsePrNumber(arg) !== null)
             continue;
-        }
         onError(arg);
         return false;
     }

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

@@ -0,0 +1,10 @@
+import type { PollSummaryCommandOptions, PollSummaryResult } from "../types.mts";
+export interface AggregatePollCommandOptions extends PollSummaryCommandOptions {
+    intervalSeconds: number;
+    timeoutSeconds: number;
+    debounceSeconds?: number;
+    quietStatus?: boolean;
+    untilTerminal?: boolean;
+}
+export declare function runPollSummary(opts: PollSummaryCommandOptions): Promise<PollSummaryResult>;
+export declare function runAggregatePoll(opts: AggregatePollCommandOptions): Promise<PollSummaryResult>;

package/bin/commands/poll-summary.mjs

@@ -0,0 +1,163 @@
+import { loadConfig } from "../config/load.mjs";
+import { ShepherdError } from "../exit-codes.mjs";
+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 { graphqlQuotaPollIntervalMs, pollGraphQlRetryAfterMs } from "./poll-quota.mjs";
+import { evaluateWorktreeGraphqlQuotaWarning } from "../state/graphql-quota-warnings.mjs";
+const MAX_TIMER_MS = 2 ** 31 - 1;
+const TIMER_DRIFT_TOLERANCE_MS = 500;
+export function runPollSummary(opts) {
+    return withApiTelemetryScope(async () => attachUsage(await runPollSummaryCore(opts)));
+}
+export function runAggregatePoll(opts) {
+    return withApiTelemetryScope(() => runAggregatePollCore(opts));
+}
+async function runPollSummaryCore(opts) {
+    const repo = opts.targetRepository ?? (await getRepoInfo());
+    const fetched = await fetchPollSummary(opts, repo);
+    const allTerminal = fetched.prs.every((item) => item.action === "cancel");
+    const actionable = fetched.prs.some((item) => item.action !== "wait" && item.action !== "cancel");
+    return {
+        mode: "summary",
+        repo: `${repo.owner}/${repo.name}`,
+        selection: fetched.selection,
+        reason: allTerminal ? "all_terminal" : actionable ? "actionable" : "waiting",
+        prs: fetched.prs,
+    };
+}
+async function runAggregatePollCore(opts) {
+    const intervalMs = Math.min(opts.intervalSeconds * 1000, MAX_TIMER_MS);
+    const timeoutMs = Math.min(opts.timeoutSeconds * 1000, MAX_TIMER_MS);
+    const debounceMs = Math.min((opts.debounceSeconds ?? 60) * 1000, MAX_TIMER_MS);
+    const quotaBands = loadConfig().watch.graphqlQuotaWarnings;
+    const start = Date.now();
+    let tick = 0;
+    let debounceUntil = null;
+    let last;
+    let lastStatusSignature = null;
+    let rateLimitRetries = 0;
+    let pendingQuotaWarning;
+    while (true) {
+        tick += 1;
+        try {
+            last = await runPollSummaryCore(opts);
+            rateLimitRetries = 0;
+        }
+        catch (error) {
+            if (last?.selection.kind === "stack" && isMissingStack(error)) {
+                const explicit = await runPollSummaryCore({
+                    ...opts,
+                    stackPrNumber: undefined,
+                    prNumbers: last.prs.map((item) => item.pr),
+                });
+                if (explicit.prs.every((item) => item.action === "cancel")) {
+                    const warning = await aggregateQuotaWarning(explicit, quotaBands, opts.intervalSeconds);
+                    if (warning)
+                        pendingQuotaWarning = warning;
+                    return attachUsage({
+                        ...explicit,
+                        reason: "all_terminal",
+                        ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
+                    });
+                }
+            }
+            const retryMs = opts.untilTerminal ? pollGraphQlRetryAfterMs(error) : null;
+            if (retryMs === null || rateLimitRetries >= 1)
+                throw error;
+            rateLimitRetries += 1;
+            process.stderr.write(`[aggregate poll tick ${tick} / +${Math.round((Date.now() - start) / 1000)}s] GraphQL rate limit — retrying in ${Math.round(retryMs / 1000)}s\n`);
+            await sleep(retryMs);
+            continue;
+        }
+        const allTerminal = last.prs.every((item) => item.action === "cancel");
+        const immediate = last.prs.some((item) => ["escalate", "merge", "mark_ready"].includes(item.action));
+        const hasFix = last.prs.some((item) => item.action === "fix_code");
+        const warning = await aggregateQuotaWarning(last, quotaBands, opts.intervalSeconds);
+        if (warning)
+            pendingQuotaWarning = warning;
+        if (allTerminal) {
+            return attachUsage({
+                ...last,
+                reason: "all_terminal",
+                ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
+            });
+        }
+        if (immediate) {
+            return attachUsage({
+                ...last,
+                reason: "actionable",
+                ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
+            });
+        }
+        if (hasFix) {
+            if (debounceMs === 0)
+                return attachUsage({
+                    ...last,
+                    reason: "actionable",
+                    ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
+                });
+            debounceUntil ??= Date.now() + debounceMs;
+            if (Date.now() >= debounceUntil)
+                return attachUsage({
+                    ...last,
+                    reason: "actionable",
+                    ...(pendingQuotaWarning && { quotaWarning: pendingQuotaWarning }),
+                });
+        }
+        else {
+            debounceUntil = null;
+            if (opts.untilTerminal && pendingQuotaWarning) {
+                return attachUsage({ ...last, quotaWarning: pendingQuotaWarning });
+            }
+        }
+        const elapsedMs = Date.now() - start;
+        const sleepMs = debounceUntil
+            ? Math.min(intervalMs, Math.max(debounceUntil - Date.now(), 0))
+            : graphqlQuotaPollIntervalMs(quotaBands, summarizeApiTelemetry()?.graphql, intervalMs, MAX_TIMER_MS);
+        if (!opts.untilTerminal && debounceUntil === null) {
+            const remainingMs = timeoutMs - elapsedMs;
+            if (remainingMs <= 0 || remainingMs + TIMER_DRIFT_TOLERANCE_MS < sleepMs) {
+                return attachUsage({ ...last, reason: "timeout" });
+            }
+        }
+        const statusSignature = summaryStatusSignature(last);
+        if (!opts.quietStatus || hasFix || statusSignature !== lastStatusSignature) {
+            process.stderr.write(`[aggregate poll tick ${tick} / +${Math.round(elapsedMs / 1000)}s] ${last.prs
+                .map((item) => `#${item.pr} ${item.action.toUpperCase()}`)
+                .join(", ")}\n`);
+        }
+        lastStatusSignature = statusSignature;
+        await sleep(sleepMs);
+    }
+}
+async function aggregateQuotaWarning(result, bands, intervalSeconds) {
+    const usage = summarizeApiTelemetry()?.graphql;
+    const [owner, repo] = result.repo.split("/");
+    if (!usage || !owner || !repo)
+        return undefined;
+    return evaluateWorktreeGraphqlQuotaWarning({ owner, repo }, bands.map((band) => ({
+        ...band,
+        pollIntervalMinutes: Math.max(band.pollIntervalMinutes, intervalSeconds / 60),
+    })), usage, true);
+}
+function summaryStatusSignature(result) {
+    return JSON.stringify(result.prs.map((item) => ({
+        pr: item.pr,
+        action: item.action,
+        state: item.state,
+        mergeable: item.mergeable,
+        mergeStateStatus: item.mergeStateStatus,
+        reviewDecision: item.reviewDecision,
+        checks: item.checks,
+        review: item.review,
+    })));
+}
+function isMissingStack(error) {
+    return (error instanceof ShepherdError && error.message.includes("not part of a native GitHub stack"));
+}
+function attachUsage(result) {
+    const apiUsage = summarizeApiTelemetry();
+    return apiUsage ? { ...result, apiUsage } : result;
+}

package/bin/commands/ready-delay.d.mts

@@ -25,5 +25,7 @@ interface ReadyDelayState {
  * When `shouldCancel == true`, the formatter tells loop-capable agents to cancel
  * the loop and tells one-shot agents to stop.
  */
-export declare function updateReadyDelay(prNumber: number, isReady: boolean, readyDelaySeconds: number, owner: string, repo: string): Promise<ReadyDelayState>;
+export declare function updateReadyDelay(prNumber: number, isReady: boolean, readyDelaySeconds: number, owner: string, repo: string, options?: {
+    retainElapsed?: boolean;
+}): Promise<ReadyDelayState>;
 export {};

package/bin/commands/ready-delay.mjs

@@ -18,7 +18,7 @@ import { resolvePrStatePath } from "../state/base.mjs";
  * When `shouldCancel == true`, the formatter tells loop-capable agents to cancel
  * the loop and tells one-shot agents to stop.
  */
-export async function updateReadyDelay(prNumber, isReady, readyDelaySeconds, owner, repo) {
+export async function updateReadyDelay(prNumber, isReady, readyDelaySeconds, owner, repo, options = {}) {
     const markerPath = readySincePath(prNumber, owner, repo);
     if (!isReady) {
         // Reset the timer.
@@ -47,7 +47,8 @@ export async function updateReadyDelay(prNumber, isReady, readyDelaySeconds, own
     const elapsed = now - readySince;
     const remaining = readyDelaySeconds - elapsed;
     if (remaining <= 0) {
-        await safeUnlink(markerPath);
+        if (!options.retainElapsed)
+            await safeUnlink(markerPath);
         return { isReady: true, shouldCancel: true, remainingSeconds: 0 };
     }
     return { isReady: true, shouldCancel: false, remainingSeconds: remaining };

package/bin/github/gql/poll-stack-summary.gql

@@ -0,0 +1,33 @@
+query PollStackSummary($owner: String!, $repo: String!, $anchor: Int!, $after: String) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
+  repository(owner: $owner, name: $repo) {
+    viewerCanAdminister
+    pullRequest(number: $anchor) {
+      stack {
+        id
+        number
+        size
+        baseRefName
+        entries(first: 50, after: $after) {
+          pageInfo {
+            hasNextPage
+            endCursor
+          }
+          nodes {
+            position
+            pullRequest {
+              ...PollSummaryPr
+            }
+          }
+        }
+      }
+    }
+  }
+}

package/bin/github/gql/poll-summary-fragment.gql

@@ -0,0 +1,198 @@
+fragment PollSummaryPr on PullRequest {
+  number
+  title
+  url
+  state
+  isDraft
+  viewerCanUpdate
+  headRefName
+  headRefOid
+  baseRefName
+  mergeable
+  mergeStateStatus
+  reviewDecision
+  reviewRequests(last: 50) {
+    nodes {
+      requestedReviewer {
+        __typename
+        ... on User {
+          login
+        }
+        ... on Bot {
+          login
+        }
+        ... on Mannequin {
+          login
+        }
+      }
+    }
+  }
+  latestReviews(last: 50) {
+    nodes {
+      state
+      author {
+        __typename
+        login
+      }
+    }
+  }
+  isInMergeQueue
+  mergeQueueEntry {
+    headCommit {
+      statusCheckRollup {
+        contexts(last: 100) {
+          totalCount
+          pageInfo {
+            hasPreviousPage
+          }
+          nodes {
+            __typename
+            ... on CheckRun {
+              id
+              name
+              status
+              conclusion
+              detailsUrl
+              checkSuite {
+                workflowRun {
+                  databaseId
+                  event
+                  workflow {
+                    databaseId
+                    name
+                  }
+                }
+              }
+            }
+            ... on StatusContext {
+              context
+              state
+            }
+          }
+        }
+      }
+    }
+  }
+  stack {
+    number
+    size
+    baseRefName
+  }
+  stackEntry {
+    position
+  }
+  comments(last: 100) {
+    totalCount
+    pageInfo {
+      hasPreviousPage
+    }
+    nodes {
+      id
+      body
+      isMinimized
+      url
+      authorAssociation
+      author {
+        __typename
+        login
+      }
+    }
+  }
+  reviews(last: 100) {
+    totalCount
+    pageInfo {
+      hasPreviousPage
+    }
+    nodes {
+      id
+      body
+      state
+      isMinimized
+      authorAssociation
+      author {
+        __typename
+        login
+      }
+    }
+  }
+  reviewThreads(last: 20) {
+    totalCount
+    pageInfo {
+      hasPreviousPage
+    }
+    nodes {
+      id
+      isResolved
+      isOutdated
+      path
+      rootComments: comments(first: 1) {
+        nodes {
+          id
+          body
+          url
+          viewerDidAuthor
+          authorAssociation
+          author {
+            __typename
+            login
+          }
+        }
+      }
+      comments(last: 5) {
+        totalCount
+        pageInfo {
+          hasPreviousPage
+        }
+        nodes {
+          id
+          body
+          url
+          authorAssociation
+          viewerDidAuthor
+          author {
+            __typename
+            login
+          }
+        }
+      }
+    }
+  }
+  commits(last: 1) {
+    nodes {
+      commit {
+        statusCheckRollup {
+          contexts(last: 100) {
+            totalCount
+            pageInfo {
+              hasPreviousPage
+            }
+            nodes {
+              __typename
+              ... on CheckRun {
+                id
+                name
+                status
+                conclusion
+                detailsUrl
+                checkSuite {
+                  workflowRun {
+                    databaseId
+                    event
+                    workflow {
+                      databaseId
+                      name
+                    }
+                  }
+                }
+              }
+              ... on StatusContext {
+                context
+                state
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,3 @@
+import type { PollSummaryChecks } from "../types.mts";
+import type { RawSummaryPr } from "./poll-summary-raw.mts";
+export declare function summarizePollSummaryChecks(raw: RawSummaryPr): PollSummaryChecks;

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

@@ -0,0 +1,61 @@
+import { classifyChecks } from "../checks/classify.mjs";
+export function summarizePollSummaryChecks(raw) {
+    const rollups = [
+        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) => {
+        if (context.__typename === "StatusContext") {
+            return {
+                name: context.context,
+                status: context.state === "PENDING" || context.state === "EXPECTED"
+                    ? "IN_PROGRESS"
+                    : "COMPLETED",
+                conclusion: context.state === "SUCCESS"
+                    ? "SUCCESS"
+                    : context.state === "FAILURE" || context.state === "ERROR"
+                        ? "FAILURE"
+                        : null,
+                source: "status_context",
+                detailsUrl: "",
+                event: null,
+                runId: null,
+                ...(rollupIndex === 1 && { scope: "merge_group" }),
+            };
+        }
+        const run = context.checkSuite?.workflowRun;
+        return {
+            id: context.id,
+            name: context.name,
+            status: context.status,
+            conclusion: context.conclusion,
+            source: "check_run",
+            detailsUrl: context.detailsUrl ?? "",
+            event: run?.event ?? null,
+            runId: run?.databaseId != null ? String(run.databaseId) : null,
+            ...(run?.workflow?.name && { workflowName: run.workflow.name }),
+            ...(run?.workflow?.databaseId != null && {
+                workflowId: String(run.workflow.databaseId),
+            }),
+            ...(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.d.mts

@@ -0,0 +1,4 @@
+import type { PollSummaryCommandOptions, PollSummaryItem } from "../types.mts";
+import type { RepoInfo } from "./client.mts";
+import type { RawSummaryPr } from "./poll-summary-raw.mts";
+export declare function summarizePollSummaryPr(raw: RawSummaryPr, repo: RepoInfo, opts: PollSummaryCommandOptions, viewerCanAdminister?: boolean): Promise<PollSummaryItem>;