pr-shepherd 0.48.0 → 0.50.0

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

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

@@ -0,0 +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>;

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

@@ -0,0 +1,85 @@
+import { normalizeBotUsernames } from "../comments/authors.mjs";
+import { applyRules } from "../classify/apply.mjs";
+import { discoverRuleFiles, loadRules } from "../classify/loader.mjs";
+import { loadConfig } from "../config/load.mjs";
+import { getEffectiveCwd } from "../execution-context.mjs";
+import { classifyItem } from "../state/seen-comments.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()));
+    let actionable = 0;
+    let incomplete = raw.comments.pageInfo.hasPreviousPage ||
+        raw.reviews.pageInfo.hasPreviousPage ||
+        raw.reviewThreads.pageInfo.hasPreviousPage;
+    for (const comment of raw.comments.nodes) {
+        if (!comment.isMinimized &&
+            !isSuppressed(rules, "pr-comment", comment) &&
+            classifyItem(comment.id, comment.body, seen) !== "unchanged")
+            actionable += 1;
+    }
+    const latestStateByAuthor = new Map((raw.latestReviews?.nodes ?? []).flatMap((review) => review.author ? [[review.author.login.toLowerCase(), review.state]] : []));
+    for (const review of raw.reviews.nodes) {
+        if (review.state === "COMMENTED") {
+            if (review.body.trim() !== "" &&
+                !review.isMinimized &&
+                !isSuppressed(rules, "review-summary", review) &&
+                classifyItem(review.id, review.body, seen) !== "unchanged")
+                actionable += 1;
+            continue;
+        }
+        if (review.state !== "CHANGES_REQUESTED")
+            continue;
+        const login = review.author?.login.toLowerCase();
+        if (login && latestStateByAuthor.get(login) === "APPROVED")
+            continue;
+        if (isSuppressed(rules, "changes-requested", review))
+            continue;
+        const isBot = review.author?.__typename === "Bot" || bots.has(review.author?.login.toLowerCase() ?? "");
+        if ((isBot && viewerCanAdminister) ||
+            classifyItem(review.id, review.body, seen) !== "unchanged")
+            actionable += 1;
+    }
+    for (const thread of raw.reviewThreads.nodes) {
+        if (thread.comments.pageInfo.hasPreviousPage)
+            incomplete = true;
+        const root = thread.rootComments?.nodes[0] ?? 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))
+            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)) ||
+            ((thread.isResolved || thread.isOutdated) && unseen))
+            actionable += 1;
+    }
+    return {
+        ...(raw.comments.totalCount > 0 && { comments: raw.comments.totalCount }),
+        ...(raw.reviews.totalCount > 0 && { reviews: raw.reviews.totalCount }),
+        ...(raw.reviewThreads.totalCount > 0 && { threads: raw.reviewThreads.totalCount }),
+        ...(actionable > 0 && { actionable }),
+        ...(incomplete && { incomplete: true }),
+    };
+}
+function isSuppressed(rules, kind, raw, id = raw?.id ?? "unknown", path, body = raw?.body ?? "") {
+    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 }),
+        body,
+        ...(raw?.url && { url: raw.url }),
+        ...(kind === "review-thread" && { path }),
+    };
+    return applyRules(rules, item).suppress === true;
+}

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

@@ -0,0 +1,4 @@
+import type { PollSummaryChecks, PollSummaryCommandOptions, PollSummaryItem, PollSummaryReview } from "../types.mts";
+import type { RawSummaryPr } from "./poll-summary-raw.mts";
+export declare function routePollSummary(raw: RawSummaryPr, checks: PollSummaryChecks, review: PollSummaryReview, opts: PollSummaryCommandOptions): Pick<PollSummaryItem, "action" | "reasons">;
+export declare function normalizePollSummaryState(state: string): PollSummaryItem["state"];

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

@@ -0,0 +1,47 @@
+import { loadConfig } from "../config/load.mjs";
+export function routePollSummary(raw, checks, review, opts) {
+    const actions = loadConfig().actions;
+    const state = normalizePollSummaryState(raw.state);
+    if (state === "MERGED" || state === "CLOSED") {
+        return { action: "cancel", reasons: [state.toLowerCase()] };
+    }
+    if (raw.mergeable === "CONFLICTING" || raw.mergeStateStatus === "DIRTY") {
+        return { action: "fix_code", reasons: ["merge-conflicts"] };
+    }
+    if ((checks.failing ?? 0) > 0)
+        return { action: "fix_code", reasons: ["failing-checks"] };
+    if ((review.actionable ?? 0) > 0) {
+        if (opts.merge && raw.isInMergeQueue && actions.workWhileQueued !== true) {
+            return { action: "wait", reasons: ["review-work-deferred-while-queued"] };
+        }
+        return { action: "fix_code", reasons: ["review-work"] };
+    }
+    if ((checks.inProgress ?? 0) > 0 ||
+        raw.mergeable === "UNKNOWN" ||
+        raw.mergeStateStatus === "UNKNOWN" ||
+        raw.mergeStateStatus === "BEHIND" ||
+        raw.mergeStateStatus === "BLOCKED" ||
+        raw.mergeStateStatus === "HAS_HOOKS") {
+        return { action: "wait", reasons: ["pending-or-unknown"] };
+    }
+    if (raw.isDraft) {
+        if (opts.noAutoMarkReady || actions.autoMarkReady === false) {
+            return { action: "wait", reasons: ["draft-auto-mark-ready-disabled"] };
+        }
+        return raw.viewerCanUpdate
+            ? { action: "mark_ready", reasons: ["draft-appears-ready"] }
+            : { action: "escalate", reasons: ["mark-ready-authorization-required"] };
+    }
+    if (opts.merge && raw.isInMergeQueue) {
+        return { action: "wait", reasons: ["already-in-merge-queue"] };
+    }
+    if (opts.merge && raw.stack) {
+        return { action: "fix_code", reasons: ["authoritative-poll-required"] };
+    }
+    if (opts.merge && !raw.stack)
+        return { action: "merge", reasons: ["appears-ready"] };
+    return { action: "cancel", reasons: ["appears-ready"] };
+}
+export function normalizePollSummaryState(state) {
+    return state === "OPEN" || state === "CLOSED" || state === "MERGED" ? state : "UNKNOWN";
+}

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

@@ -0,0 +1,7 @@
+import type { PollSummaryCommandOptions, PollSummaryItem, PollSummarySelection } from "../types.mts";
+import { type RepoInfo } from "./client.mts";
+export interface FetchedPollSummary {
+    selection: PollSummarySelection;
+    prs: PollSummaryItem[];
+}
+export declare function fetchPollSummary(opts: PollSummaryCommandOptions, repo: RepoInfo): Promise<FetchedPollSummary>;