pr-shepherd 0.56.5 → 0.57.0

package/bin/github/rest-summary-read.mjs

@@ -0,0 +1,112 @@
+export function restSummary(data, pull, feedback, checks, baseRef) {
+    const connection = (nodes) => ({
+        nodes,
+        totalCount: nodes.length,
+        pageInfo: { hasPreviousPage: false },
+    });
+    const comments = feedback.comments.map((comment) => ({
+        id: comment.id,
+        body: comment.body,
+        author: { login: comment.author, __typename: comment.authorType },
+        url: comment.url,
+        authorAssociation: comment.authorAssociation,
+    }));
+    return {
+        number: pull.number,
+        title: pull.title,
+        url: pull.html_url,
+        author: pull.user,
+        state: data.state,
+        isDraft: data.isDraft,
+        ...(data.autoMergeRequest && { autoMergeRequest: data.autoMergeRequest }),
+        updatedAt: pull.updated_at,
+        headRefName: data.headRefName,
+        headRefOid: data.headRefOid,
+        baseRefOid: pull.base.sha,
+        baseRefName: data.baseRefName,
+        ...(baseRef && { baseRef }),
+        mergeable: data.mergeable,
+        mergeStateStatus: data.mergeStateStatus,
+        reviewDecision: null,
+        reviewRequests: {
+            nodes: data.reviewRequests.map((request) => ({ requestedReviewer: request })),
+        },
+        latestReviews: {
+            nodes: data.latestReviews.map((review) => ({
+                state: review.state,
+                author: { login: review.login },
+            })),
+        },
+        mergeQueueEntry: null,
+        stack: data.stack
+            ? { number: data.stack.number, size: data.stack.size, baseRefName: data.stack.baseRefName }
+            : null,
+        stackEntry: data.stack ? { position: data.stack.position } : null,
+        comments: connection(comments),
+        reviews: connection(feedback.reviews.map((review) => ({
+            id: review.node_id,
+            body: review.body ?? "",
+            state: review.state,
+            author: review.user ? { login: review.user.login, __typename: review.user.type } : null,
+            authorAssociation: review.author_association,
+            url: review.html_url,
+        }))),
+        reviewThreads: connection(data.reviewThreads.map((thread) => ({
+            id: thread.id,
+            ...(thread.isResolved !== undefined && { isResolved: thread.isResolved }),
+            ...(thread.isOutdated !== undefined && { isOutdated: thread.isOutdated }),
+            path: thread.path,
+            comments: connection((thread.comments ?? []).map((comment) => ({
+                id: comment.id,
+                ...(comment.viewerDidAuthor === true && { viewerDidAuthor: true }),
+                body: comment.body,
+                author: { login: comment.author, __typename: comment.authorType },
+                url: comment.url,
+                authorAssociation: comment.authorAssociation,
+            }))),
+        }))),
+        commits: {
+            nodes: [
+                {
+                    commit: {
+                        oid: data.headRefOid,
+                        statusCheckRollup: {
+                            contexts: connection(checks.nodes.map((check) => check.__typename === "CheckRun"
+                                ? {
+                                    ...check,
+                                    detailsUrl: check.detailsUrl ?? undefined,
+                                    annotations: { totalCount: check.annotations.totalCount },
+                                    checkSuite: check.checkSuite
+                                        ? {
+                                            ...check.checkSuite,
+                                            workflowRun: check.checkSuite.workflowRun
+                                                ? {
+                                                    ...check.checkSuite.workflowRun,
+                                                    workflow: check.checkSuite.workflowRun.workflow
+                                                        ? {
+                                                            ...check.checkSuite.workflowRun.workflow,
+                                                            databaseId: check.checkSuite.workflowRun.workflow.databaseId,
+                                                        }
+                                                        : null,
+                                                }
+                                                : null,
+                                        }
+                                        : null,
+                                }
+                                : check)),
+                        },
+                        checkSuites: {
+                            nodes: checks.suites.map((suite) => ({
+                                status: suite.status.toUpperCase(),
+                                conclusion: suite.conclusion?.toUpperCase() ?? null,
+                                workflowRun: checks.workflowRuns.find((run) => run.check_suite_id === suite.id) ?? null,
+                            })),
+                        },
+                    },
+                },
+            ],
+        },
+        transport: "rest",
+        transportUnavailable: data.transportUnavailable,
+    };
+}

package/bin/github/rest-terminal-batch.d.mts

@@ -0,0 +1,14 @@
+import type { BatchPrData } from "../types.mts";
+import { type RestPull } from "./rest-pr-core.mts";
+/**
+ * A merged pull is immutable, so its first read is final. A closed pull is not (it can be
+ * reopened during the snapshot), so it keeps the full snapshot and its closing re-read.
+ */
+export declare function isRestPullMerged(pull: RestPull): boolean;
+/**
+ * Batch data for a merged PR, built from the first pull read alone. A terminal tick reports
+ * only identity and merge state (`buildTerminalReport`), so the feedback, checks, rules, stack
+ * and repository reads of a full snapshot would be discarded unread. The unread resources are
+ * listed as unavailable, not presented as empty, so no merge requirement is derived from them.
+ */
+export declare function restMergedBatchData(pull: RestPull): BatchPrData;

package/bin/github/rest-terminal-batch.mjs

@@ -0,0 +1,45 @@
+import { restPullRefs } from "./rest-pr-core.mjs";
+import { REST_BATCH_UNAVAILABLE } from "./rest-batch-unavailable.mjs";
+/**
+ * A merged pull is immutable, so its first read is final. A closed pull is not (it can be
+ * reopened during the snapshot), so it keeps the full snapshot and its closing re-read.
+ */
+export function isRestPullMerged(pull) {
+    return Boolean(pull.merged_at);
+}
+const NOT_READ = "not read for a merged pull request";
+/**
+ * Batch data for a merged PR, built from the first pull read alone. A terminal tick reports
+ * only identity and merge state (`buildTerminalReport`), so the feedback, checks, rules, stack
+ * and repository reads of a full snapshot would be discarded unread. The unread resources are
+ * listed as unavailable, not presented as empty, so no merge requirement is derived from them.
+ */
+export function restMergedBatchData(pull) {
+    const refs = restPullRefs(pull);
+    return {
+        nodeId: pull.node_id,
+        ...refs,
+        state: "MERGED",
+        isDraft: pull.draft,
+        mergeable: pull.mergeable === true ? "MERGEABLE" : pull.mergeable === false ? "CONFLICTING" : "UNKNOWN",
+        mergeStateStatus: pull.mergeable_state.toUpperCase(),
+        reviewDecision: null,
+        headRepoWithOwner: pull.head.repo?.full_name ?? null,
+        reviewRequests: [],
+        latestReviews: [],
+        reviewThreads: [],
+        comments: [],
+        changesRequestedReviews: [],
+        reviewSummaries: [],
+        approvedReviews: [],
+        checks: [],
+        branchProtection: null,
+        stack: null,
+        transport: "rest",
+        transportUnavailable: [
+            ...REST_BATCH_UNAVAILABLE,
+            { field: "branchProtection", reason: NOT_READ },
+            { field: "mergeRequirements", reason: NOT_READ },
+        ],
+    };
+}

package/bin/github/rest-text.mjs

@@ -1,6 +1,7 @@
 import { appendEntry, nextEntry } from "../log/log-file.mjs";
 import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
 import { GitHubRequestError } from "./errors.mjs";
+import { githubFetch } from "./github-fetch.mjs";
 import { makeAuthHeaders } from "./http-auth.mjs";
 import { requestWithTokenRetry } from "./http-request.mjs";
 import { parseRateLimit, parseRetryAfter, redactUrl, sanitizeBody, } from "./http-utils.mjs";
@@ -13,10 +14,12 @@ export async function restText(path, onRateLimit) {
     appendEntry(formatRequestEntry({ n, kind: "restText", method: "GET", url }));
     const t0 = performance.now();
     let authSource = "unknown";
+    let credentialFingerprint;
     const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => {
         const auth = await makeAuthHeaders();
         authSource = auth.source;
-        return fetch(url, { method: "GET", headers: auth.headers, redirect: "manual" });
+        credentialFingerprint = auth.fingerprint;
+        return githubFetch(url, { method: "GET", headers: auth.headers, redirect: "manual" });
     }, t0, (response, durationMs) => recordIntermediateResponse({
         n,
         kind: "restText",
@@ -25,12 +28,13 @@ export async function restText(path, onRateLimit) {
         response,
         durationMs,
         authSource,
+        credentialFingerprint,
     }));
     const durationMs = Math.round(performance.now() - retryT0);
     const rateLimit = parseRateLimit(res.headers) ?? undefined;
     onRateLimit?.(rateLimit);
     const retryAfterSeconds = parseRetryAfter(res.headers);
-    recordApiTelemetry({ kind: "REST", method: "GET", authSource, rateLimit });
+    recordApiTelemetry({ kind: "REST", method: "GET", authSource, credentialFingerprint, rateLimit });
     if ([301, 302, 307, 308].includes(res.status)) {
         const redirected = await followRestTextRedirect(res, {
             n,
@@ -101,7 +105,7 @@ async function followRestTextRedirect(res, entry) {
     const logUrl = redactUrl(location);
     appendEntry(formatRequestEntry({ n: n2, kind: "restText", method: "GET", url: logUrl }));
     const t1 = performance.now();
-    const redirectRes = await fetch(location);
+    const redirectRes = await githubFetch(location);
     appendEntry(formatResponseEntry({
         n: n2,
         kind: "restText",

package/bin/github/rest-thread-read.d.mts

@@ -0,0 +1,4 @@
+import type { RepoInfo } from "./client.mts";
+import type { RawThread } from "./batch-raw-types.mts";
+/** Complete REST reply chain, keeping the caller's opaque thread ID. */
+export declare function readRestRawThread(id: string, repo?: RepoInfo, pr?: number): Promise<RawThread>;

package/bin/github/rest-thread-read.mjs

@@ -0,0 +1,35 @@
+import { readRestFeedback } from "./rest-feedback-read.mjs";
+import { resolveRestIdentity, resolveRestThreadRoot, restThreadId } from "./rest-identities.mjs";
+/** Complete REST reply chain, keeping the caller's opaque thread ID. */
+export async function readRestRawThread(id, repo, pr) {
+    const identity = repo && pr ? { repo, pr } : await resolveRestIdentity(id, "thread");
+    const root = await resolveRestThreadRoot(identity.repo, identity.pr, id);
+    const feedback = await readRestFeedback(identity.pr, identity.repo);
+    const thread = feedback.threads.find((thread) => thread.id === restThreadId(root));
+    if (!thread)
+        throw new Error(`Review thread ${id} is absent from the REST snapshot`);
+    const comments = (thread.comments ?? []).map((comment) => ({
+        id: comment.id,
+        body: comment.body,
+        url: comment.url,
+        author: { login: comment.author, __typename: comment.authorType },
+        ...(comment.viewerDidAuthor === true && { viewerDidAuthor: true }),
+        ...(comment.authorAssociation && { authorAssociation: comment.authorAssociation }),
+        ...(comment.reviewId && { pullRequestReview: { id: comment.reviewId } }),
+        path: thread.path,
+        line: thread.line,
+        startLine: thread.startLine,
+        ...(comment.createdAtUnix && {
+            createdAt: new Date(comment.createdAtUnix * 1000).toISOString(),
+        }),
+    }));
+    return {
+        id,
+        ...(thread.isResolved !== undefined && { isResolved: thread.isResolved }),
+        ...(thread.isOutdated !== undefined && { isOutdated: thread.isOutdated }),
+        path: thread.path,
+        line: thread.line,
+        startLine: thread.startLine,
+        comments: { pageInfo: { hasNextPage: false, endCursor: null }, nodes: comments },
+    };
+}

package/bin/github/rest-viewer-read.d.mts

@@ -0,0 +1,2 @@
+/** Installation tokens may read PRs without supporting authenticated-user identity. */
+export declare function readRestViewerLogin(): Promise<string | null>;

package/bin/github/rest-viewer-read.mjs

@@ -0,0 +1,41 @@
+import { readRest } from "./rest-reader-core.mjs";
+import { GitHubRequestError } from "./errors.mjs";
+import { rateLimitKind } from "./rate-limit-kind.mjs";
+import { isRestSessionRefusal } from "./rest-session-refusal.mjs";
+import { currentRestConditionalKey } from "./rest-conditional-scope.mjs";
+import { makeAuthHeaders } from "./http-auth.mjs";
+import { loadDerived, storeDerived } from "../state/rest-cache.mjs";
+/**
+ * GitHub never answers an error status with 304, so a token that cannot read `/user` would be
+ * charged for the same denial on every poll tick. The denial is remembered per credential for
+ * an hour; a token change, or the hour passing, asks GitHub again.
+ */
+const UNAVAILABLE_TTL_MS = 60 * 60 * 1000;
+/** Installation tokens may read PRs without supporting authenticated-user identity. */
+export async function readRestViewerLogin() {
+    const key = currentRestConditionalKey();
+    const name = key && `viewer-unavailable:${(await makeAuthHeaders()).fingerprint}`;
+    if (key && name) {
+        const denied = await loadDerived(key, name);
+        if (denied && Date.now() - denied.storedAt < UNAVAILABLE_TTL_MS)
+            return null;
+    }
+    try {
+        const viewer = await readRest("GET", "/user");
+        if (!viewer || typeof viewer !== "object" || Array.isArray(viewer))
+            return null;
+        const login = viewer.login;
+        return typeof login === "string" && login.length > 0 ? login : null;
+    }
+    catch (error) {
+        if (error instanceof GitHubRequestError &&
+            [401, 403, 404].includes(error.status) &&
+            rateLimitKind(error) === null &&
+            !isRestSessionRefusal(error)) {
+            if (key && name)
+                await storeDerived(key, name, true);
+            return null;
+        }
+        throw error;
+    }
+}

package/bin/github/stack-bottom.d.mts

@@ -0,0 +1,3 @@
+import type { StackMemberRefs } from "./stack-read.mts";
+/** The first open member can replace merged lower layers only after a fully merged prefix. */
+export declare function verifiedBottomOpenLayer<Pr extends StackMemberRefs>(ordered: readonly Pr[], anchor: number): Pr;

package/bin/github/stack-bottom.mjs

@@ -0,0 +1,14 @@
+import { EXIT, ShepherdError } from "../exit-codes.mjs";
+/** The first open member can replace merged lower layers only after a fully merged prefix. */
+export function verifiedBottomOpenLayer(ordered, anchor) {
+    const index = ordered.findIndex((member) => member.state === "OPEN");
+    const bottom = ordered[index];
+    if (!bottom) {
+        throw new ShepherdError(`Native stack for PR #${anchor} has no open layer`, EXIT.TEMPFAIL);
+    }
+    const predecessor = ordered.slice(0, index).find((member) => member.state !== "MERGED");
+    if (predecessor) {
+        throw new ShepherdError(`Native stack for PR #${anchor} has PR #${predecessor.number} in state ${predecessor.state} before open PR #${bottom.number}; cannot verify the bottom open layer`, EXIT.TEMPFAIL);
+    }
+    return bottom;
+}

package/bin/github/stack-handoff-context.d.mts

@@ -0,0 +1,25 @@
+interface RepositoryHandoffFields {
+    viewerPermission?: string | null;
+    mergeCommitAllowed?: boolean;
+    squashMergeAllowed?: boolean;
+    rebaseMergeAllowed?: boolean;
+}
+/** What a routed-layer handoff needs from a stack read besides the layers themselves. */
+export interface StackHandoffContext {
+    /** Stack identity and each ordered layer's entry position. */
+    stack?: {
+        id: string;
+        positions: number[];
+    };
+    viewerPermission?: string | null;
+    mergeSettings?: Omit<RepositoryHandoffFields, "viewerPermission">;
+}
+export declare function stackHandoffContext(repository: RepositoryHandoffFields, id: string, entries: Array<{
+    position: number;
+    pullRequest: {
+        number: number;
+    };
+}>, ordered: Array<{
+    number: number;
+}>): StackHandoffContext;
+export {};

package/bin/github/stack-handoff-context.mjs

@@ -0,0 +1,12 @@
+import { readAllowedMergeMethods } from "../config/merge-method.mjs";
+export function stackHandoffContext(repository, id, entries, ordered) {
+    const position = new Map(entries.map((entry) => [entry.pullRequest.number, entry.position]));
+    const { viewerPermission, mergeCommitAllowed, squashMergeAllowed, rebaseMergeAllowed } = repository;
+    return {
+        stack: { id, positions: ordered.map((pr) => position.get(pr.number)) },
+        ...(viewerPermission !== undefined && { viewerPermission }),
+        ...(readAllowedMergeMethods(repository) && {
+            mergeSettings: { mergeCommitAllowed, squashMergeAllowed, rebaseMergeAllowed },
+        }),
+    };
+}

package/bin/github/stack-handoff-page.d.mts

@@ -0,0 +1,17 @@
+import type { RawBatchResponse, RawContextNode } from "./batch-raw-types.mts";
+import type { RawSummaryPr } from "./poll-summary-raw.mts";
+import type { StackRead } from "./stack-read.mts";
+/** The routing tick's summary read: every layer as read, before projection. */
+export interface StackHandoffSource {
+    read: Omit<StackRead<RawSummaryPr>, "ordered">;
+    layers: RawSummaryPr[];
+    readAt: number;
+}
+export type CheckRunDetail = Pick<Extract<RawContextNode, {
+    __typename: "CheckRun";
+}>, "title" | "summary" | "annotations">;
+export declare function checkRunIds(layer: RawSummaryPr): string[];
+/** True when every window `BatchPr`'s first page reads is complete in this summary. */
+export declare function summaryComplete(layer: RawSummaryPr, source: StackHandoffSource): boolean;
+/** The `BatchPr` first page this layer's summary answers, field by field; null if incomplete. */
+export declare function batchResponseFromSummary(layer: RawSummaryPr, source: StackHandoffSource, runs: ReadonlyMap<string, CheckRunDetail>): RawBatchResponse | null;