pr-shepherd 0.47.0 → 0.49.0

package/bin/config/load.mjs

@@ -137,7 +137,30 @@ function parseMergeCommandArgs(value) {
     }
     return strategies.length === 0 ? [...value, "--merge"] : [...value];
 }
-function parseGraphqlQuotaWarnings(value) {
+function parsePollConfig(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        throw new Error("Invalid config: poll must be a plain object");
+    }
+    const record = value;
+    const intervalSeconds = parsePollDuration(record["intervalSeconds"], "intervalSeconds");
+    const timeoutSeconds = parsePollDuration(record["timeoutSeconds"], "timeoutSeconds");
+    const debounceSeconds = parsePollDuration(record["debounceSeconds"], "debounceSeconds", true);
+    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 };
+}
+function parsePollDuration(value, key, allowZero = false) {
+    if (typeof value !== "number" ||
+        !Number.isFinite(value) ||
+        (allowZero ? value < 0 : value <= 0)) {
+        const range = allowZero ? "a non-negative" : "a positive";
+        throw new Error(`Invalid config: poll.${key} must be ${range} finite number, got ${JSON.stringify(value)}`);
+    }
+    return value;
+}
+function parseGraphqlQuotaWarnings(value, pollIntervalSeconds) {
     if (!Array.isArray(value)) {
         throw new Error("Invalid config: watch.graphqlQuotaWarnings must be an array");
     }
@@ -149,22 +172,42 @@ function parseGraphqlQuotaWarnings(value) {
         const record = item;
         const remainingPercent = record["remainingPercent"];
         const pollIntervalMinutes = record["pollIntervalMinutes"];
+        const pollIntervalFactor = record["pollIntervalFactor"];
         if (typeof remainingPercent !== "number" ||
             !Number.isInteger(remainingPercent) ||
             remainingPercent < 1 ||
             remainingPercent > 100) {
             throw new Error(`Invalid config: watch.graphqlQuotaWarnings[${index}].remainingPercent must be an integer from 1 to 100`);
         }
-        if (typeof pollIntervalMinutes !== "number" ||
-            !Number.isFinite(pollIntervalMinutes) ||
-            pollIntervalMinutes <= 0) {
+        if (pollIntervalMinutes === undefined && pollIntervalFactor === undefined) {
+            throw new Error(`Invalid config: watch.graphqlQuotaWarnings[${index}] must define pollIntervalMinutes, pollIntervalFactor, or both`);
+        }
+        if (pollIntervalMinutes !== undefined &&
+            (typeof pollIntervalMinutes !== "number" ||
+                !Number.isFinite(pollIntervalMinutes) ||
+                pollIntervalMinutes <= 0)) {
             throw new Error(`Invalid config: watch.graphqlQuotaWarnings[${index}].pollIntervalMinutes must be a positive number`);
         }
+        if (pollIntervalFactor !== undefined &&
+            (typeof pollIntervalFactor !== "number" ||
+                !Number.isFinite(pollIntervalFactor) ||
+                pollIntervalFactor < 1)) {
+            throw new Error(`Invalid config: watch.graphqlQuotaWarnings[${index}].pollIntervalFactor must be a number greater than or equal to 1`);
+        }
         if (seen.has(remainingPercent)) {
             throw new Error(`Invalid config: watch.graphqlQuotaWarnings has duplicate remainingPercent ${remainingPercent}`);
         }
         seen.add(remainingPercent);
-        return { remainingPercent, pollIntervalMinutes };
+        const factorMinutes = typeof pollIntervalFactor === "number" ? (pollIntervalSeconds * pollIntervalFactor) / 60 : 0;
+        const absoluteMinutes = typeof pollIntervalMinutes === "number" ? pollIntervalMinutes : 0;
+        const resolvedPollIntervalMinutes = Math.max(absoluteMinutes, factorMinutes);
+        if (!Number.isFinite(resolvedPollIntervalMinutes)) {
+            throw new Error(`Invalid config: watch.graphqlQuotaWarnings[${index}] resolves to a non-finite poll interval`);
+        }
+        return {
+            remainingPercent,
+            pollIntervalMinutes: resolvedPollIntervalMinutes,
+        };
     });
     parsed.sort((left, right) => right.remainingPercent - left.remainingPercent);
     for (let index = 1; index < parsed.length; index += 1) {
@@ -183,6 +226,7 @@ const KNOWN_CONFIG_KEYS = new Set([
     "botUsernames",
     "ignoreChecks",
     "iterate",
+    "poll",
     "watch",
     "resolve",
     "checks",
@@ -199,6 +243,7 @@ const KNOWN_NESTED_KEYS = {
         "behindBaseHint",
         "resolveOtherHumanThreads",
     ]),
+    poll: new Set(["intervalSeconds", "timeoutSeconds", "debounceSeconds", "quietStatus"]),
     watch: new Set(["readyDelayMinutes", "graphqlQuotaWarnings"]),
     resolve: new Set(["shaPoll"]),
     checks: new Set(["ciTriggerEvents", "ignoreLogLines"]),
@@ -236,7 +281,23 @@ function warnUnknownConfigKeys(config) {
         }
     }
 }
-const defaults = builtins;
+const rawDefaults = builtins;
+function parseConfig(value, normalizeMergeArgs = true) {
+    const config = value;
+    config.botUsernames = parseBotUsernames(config.botUsernames);
+    config.ignoreChecks = parseIgnoreChecks(config.ignoreChecks);
+    config.actions.neverCancelRuns = parseNeverCancelRuns(config.actions.neverCancelRuns);
+    if (config.merge && normalizeMergeArgs) {
+        config.merge.commandArgs = parseMergeCommandArgs(config.merge.commandArgs);
+    }
+    config.poll = parsePollConfig(config.poll);
+    config.watch.graphqlQuotaWarnings = parseGraphqlQuotaWarnings(config.watch.graphqlQuotaWarnings, config.poll.intervalSeconds);
+    config.iterate.minimizeComments = parseMinimizeCommentsPolicy(config.iterate.minimizeComments);
+    config.iterate.resolveOtherHumanThreads = parseResolveOtherHumanThreads(config.iterate.resolveOtherHumanThreads);
+    config.checks.ignoreLogLines = parseIgnoreLogLines(config.checks.ignoreLogLines);
+    return config;
+}
+const defaults = parseConfig(structuredClone(rawDefaults), false);
 const configCache = new Map();
 function stripDeprecatedActionKeys(parsed) {
     const rawActions = parsed.actions;
@@ -287,24 +348,14 @@ export function loadConfig() {
             configCache.set(cwd, defaults);
             return defaults;
         }
-        const config = deepMerge(structuredClone(defaults), overlay);
-        config.botUsernames = parseBotUsernames(config.botUsernames);
-        config.ignoreChecks = parseIgnoreChecks(config.ignoreChecks);
-        config.actions.neverCancelRuns = parseNeverCancelRuns(config.actions.neverCancelRuns);
-        if (config.merge)
-            config.merge.commandArgs = parseMergeCommandArgs(config.merge.commandArgs);
-        config.watch.graphqlQuotaWarnings = parseGraphqlQuotaWarnings(config.watch.graphqlQuotaWarnings);
-        config.iterate.minimizeComments = parseMinimizeCommentsPolicy(config.iterate.minimizeComments);
-        config.iterate.resolveOtherHumanThreads = parseResolveOtherHumanThreads(config.iterate.resolveOtherHumanThreads);
-        config.checks.ignoreLogLines = parseIgnoreLogLines(config.checks.ignoreLogLines);
+        const config = parseConfig(deepMerge(structuredClone(rawDefaults), overlay));
         configCache.set(cwd, config);
         return config;
     }
     catch (err) {
         process.stderr.write(`pr-shepherd: failed to parse ${rcPaths[0]}: ${err instanceof Error ? err.message : String(err)}\n`);
-        const fallback = { ...defaults };
-        configCache.set(cwd, fallback);
-        return fallback;
+        configCache.set(cwd, defaults);
+        return defaults;
     }
 }
 /** Reset the config cache — for use in tests that change directories. */

package/bin/config.json

@@ -22,12 +22,18 @@
     "behindBaseHint": "",
     "resolveOtherHumanThreads": "none"
   },
+  "poll": {
+    "intervalSeconds": 60,
+    "timeoutSeconds": 270,
+    "debounceSeconds": 60,
+    "quietStatus": false
+  },
   "watch": {
     "readyDelayMinutes": 10,
     "graphqlQuotaWarnings": [
-      { "remainingPercent": 30, "pollIntervalMinutes": 2 },
-      { "remainingPercent": 20, "pollIntervalMinutes": 5 },
-      { "remainingPercent": 10, "pollIntervalMinutes": 10 }
+      { "remainingPercent": 30, "pollIntervalFactor": 2 },
+      { "remainingPercent": 20, "pollIntervalFactor": 5 },
+      { "remainingPercent": 10, "pollIntervalFactor": 10 }
     ]
   },
   "resolve": {

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

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

@@ -0,0 +1,81 @@
+import { loadConfig } from "../config/load.mjs";
+import { updateReadyDelay } from "../commands/ready-delay.mjs";
+import { formatPrUrl } from "../pr-reference.mjs";
+import { buildPrShepherdCommand } from "../cli/runner.mjs";
+import { loadSeenMap } from "../state/seen-comments.mjs";
+import { summarizePollSummaryChecks } from "./poll-summary-checks.mjs";
+import { summarizePollSummaryReview } from "./poll-summary-review.mjs";
+import { normalizePollSummaryState, routePollSummary } from "./poll-summary-route.mjs";
+export async function summarizePollSummaryPr(raw, repo, opts, viewerCanAdminister = false) {
+    const repoName = `${repo.owner}/${repo.name}`;
+    const seen = await loadSeenMap({ owner: repo.owner, repo: repo.name, pr: raw.number });
+    const checks = summarizePollSummaryChecks(raw);
+    const review = await summarizePollSummaryReview(raw, seen, viewerCanAdminister);
+    const blockingReviewerInProgress = detectBlockingReviewer(raw);
+    let { action, reasons } = routePollSummary(raw, checks, review, opts);
+    let remainingSeconds;
+    if (raw.isDraft && blockingReviewerInProgress && action === "mark_ready") {
+        action = "wait";
+        reasons = ["blocking-reviewer-in-progress"];
+    }
+    const appearsReady = reasons.includes("appears-ready");
+    const readyDelaySeconds = opts.readyDelaySeconds ?? (loadConfig().watch?.readyDelayMinutes ?? 10) * 60;
+    const readyState = await updateReadyDelay(raw.number, appearsReady, readyDelaySeconds, repo.owner, repo.name, { retainElapsed: true });
+    if (appearsReady && !readyState.shouldCancel) {
+        action = "wait";
+        reasons = ["ready-delay"];
+        remainingSeconds = readyState.remainingSeconds;
+    }
+    const stack = raw.stack
+        ? {
+            number: raw.stack.number,
+            size: raw.stack.size,
+            position: raw.stackEntry?.position ?? 0,
+            baseRefName: raw.stack.baseRefName,
+        }
+        : undefined;
+    return {
+        pr: raw.number,
+        repo: repoName,
+        title: raw.title,
+        url: raw.url || formatPrUrl(repoName, raw.number),
+        action,
+        reasons,
+        state: normalizePollSummaryState(raw.state),
+        mergeable: raw.mergeable,
+        mergeStateStatus: raw.mergeStateStatus,
+        ...(raw.reviewDecision && { reviewDecision: raw.reviewDecision }),
+        headRefName: raw.headRefName,
+        headRefOid: raw.headRefOid,
+        baseRefName: raw.baseRefName,
+        ...(raw.isDraft && { isDraft: true }),
+        ...(raw.isInMergeQueue && { isInMergeQueue: true }),
+        ...(blockingReviewerInProgress && { blockingReviewerInProgress: true }),
+        ...(remainingSeconds !== undefined && { remainingSeconds }),
+        ...(Object.keys(checks).length > 0 && { checks }),
+        ...(Object.keys(review).length > 0 && { review }),
+        ...(stack && { stack }),
+        ...(!["wait", "cancel"].includes(action) && {
+            pollCommand: buildPollCommand(repoName, raw.number, opts),
+        }),
+    };
+}
+function detectBlockingReviewer(raw) {
+    const prefixes = (loadConfig().mergeStatus?.blockingReviewerLogins ?? []).map((login) => login.toLowerCase());
+    const matches = (author) => author !== null && prefixes.some((prefix) => author.login.toLowerCase().startsWith(prefix));
+    return ((raw.reviewRequests?.nodes ?? []).some((request) => matches(request.requestedReviewer)) ||
+        (raw.latestReviews?.nodes ?? []).some((review) => review.state === "PENDING" && matches(review.author)));
+}
+function buildPollCommand(repo, pr, opts) {
+    const args = [formatPrUrl(repo, pr), "--until-terminal"];
+    if (opts.merge)
+        args.push("--merge");
+    if (opts.readyDelaySeconds !== undefined)
+        args.push("--ready-delay", `${opts.readyDelaySeconds}s`);
+    if (opts.stallTimeoutSeconds !== undefined) {
+        args.push("--stall-timeout", `${opts.stallTimeoutSeconds}s`);
+    }
+    if (opts.noAutoMarkReady)
+        args.push("--no-auto-mark-ready");
+    return buildPrShepherdCommand(args).text;
+}

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

@@ -0,0 +1,134 @@
+export interface RawAuthor {
+    __typename?: string;
+    login: string;
+}
+interface RawSummaryComment {
+    id: string;
+    body: string;
+    isMinimized: boolean;
+    viewerDidAuthor?: boolean;
+    authorAssociation?: string;
+    url?: string;
+    author: RawAuthor | null;
+}
+interface SummaryConnection<T> {
+    totalCount: number;
+    pageInfo: {
+        hasPreviousPage: boolean;
+    };
+    nodes: T[];
+}
+type RawCheckContext = {
+    __typename: "CheckRun";
+    id?: string;
+    name: string;
+    status: string;
+    conclusion: string | null;
+    detailsUrl?: string;
+    checkSuite: {
+        workflowRun: {
+            databaseId?: string | number;
+            event: string;
+            workflow?: {
+                name: string;
+                databaseId: string | number;
+            } | null;
+        } | null;
+    } | null;
+} | {
+    __typename: "StatusContext";
+    context: string;
+    state: string;
+};
+interface RawCheckRollup {
+    contexts: SummaryConnection<RawCheckContext>;
+}
+export interface RawSummaryPr {
+    number: number;
+    title: string;
+    url: string;
+    state: string;
+    isDraft: boolean;
+    viewerCanUpdate: boolean;
+    headRefName: string;
+    headRefOid: string;
+    baseRefName: string;
+    mergeable: string;
+    mergeStateStatus: string;
+    reviewDecision: string | null;
+    reviewRequests?: {
+        nodes: Array<{
+            requestedReviewer: RawAuthor | null;
+        }>;
+    };
+    latestReviews?: {
+        nodes: Array<{
+            state: string;
+            author: RawAuthor | null;
+        }>;
+    };
+    isInMergeQueue: boolean;
+    mergeQueueEntry: {
+        headCommit: {
+            statusCheckRollup: RawCheckRollup | null;
+        } | null;
+    } | null;
+    stack: {
+        number: number;
+        size: number;
+        baseRefName: string;
+    } | null;
+    stackEntry: {
+        position: number;
+    } | null;
+    comments: SummaryConnection<RawSummaryComment>;
+    reviews: SummaryConnection<RawSummaryComment & {
+        state: string;
+    }>;
+    reviewThreads: SummaryConnection<{
+        id: string;
+        isResolved: boolean;
+        isOutdated: boolean;
+        path: string | null;
+        rootComments?: {
+            nodes: RawSummaryComment[];
+        };
+        comments: SummaryConnection<RawSummaryComment>;
+    }>;
+    commits: {
+        nodes: Array<{
+            commit: {
+                statusCheckRollup: RawCheckRollup | null;
+            };
+        }>;
+    };
+}
+export interface RawExplicitResponse {
+    repository: ({
+        viewerCanAdminister: boolean;
+    } & Record<string, RawSummaryPr | boolean | null>) | null;
+}
+export interface RawStackResponse {
+    repository: {
+        viewerCanAdminister: boolean;
+        pullRequest: {
+            stack: {
+                id: string;
+                number: number;
+                size: number;
+                baseRefName: string;
+                entries: {
+                    pageInfo: {
+                        hasNextPage: boolean;
+                        endCursor: string | null;
+                    };
+                    nodes: Array<{
+                        position: number;
+                        pullRequest: RawSummaryPr | null;
+                    }>;
+                };
+            } | null;
+        } | null;
+    } | null;
+}
+export {};

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

@@ -0,0 +1 @@
+export {};