pr-shepherd 0.56.6 → 0.57.1

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

@@ -0,0 +1,124 @@
+import { readRestPages, restRepoPath, restCollection, restString, restNumber, malformedRest, } from "./rest-reader-core.mjs";
+import { recordRestIdentity } from "./rest-identities.mjs";
+import { readRest as rest } from "./rest-reader-core.mjs";
+export async function readRestCommitChecks(oid, repo, pr = 0) {
+    const prefix = restRepoPath(repo);
+    const checks = await readRestPages(`${prefix}/commits/${encodeURIComponent(oid)}/check-runs?filter=latest`, (body) => restCollection(body, "check_runs"));
+    const suites = await readRestPages(`${prefix}/commits/${encodeURIComponent(oid)}/check-suites`, (body) => restCollection(body, "check_suites"));
+    const statuses = await readRestPages(`${prefix}/commits/${encodeURIComponent(oid)}/statuses`);
+    const workflowRuns = await readRestPages(`${prefix}/actions/runs?head_sha=${encodeURIComponent(oid)}`, (body) => restCollection(body, "workflow_runs"));
+    for (const suite of suites.nodes) {
+        restNumber(suite.id, "check suite id");
+        restString(suite.status, "check suite status");
+        if (suite.conclusion !== null)
+            restString(suite.conclusion, "check suite conclusion");
+    }
+    for (const run of workflowRuns.nodes) {
+        restNumber(run.id, "workflow run id");
+        restNumber(run.check_suite_id, "workflow check suite id");
+        restNumber(run.workflow_id, "workflow id");
+        restString(run.event, "workflow event");
+    }
+    const workflows = new Map(workflowRuns.nodes.map((run) => [run.check_suite_id, run]));
+    const suiteMap = new Map(suites.nodes.map((suite) => [suite.id, suite]));
+    const nodes = [];
+    const checkIds = new Set();
+    for (const check of checks.nodes) {
+        restNumber(check.id, "check run id");
+        restString(check.node_id, "check run node_id");
+        restString(check.name, "check run name");
+        restString(check.status, "check run status");
+        if (!["QUEUED", "IN_PROGRESS", "COMPLETED", "WAITING", "PENDING", "REQUESTED"].includes(check.status.toUpperCase()))
+            malformedRest("unknown check run status");
+        if (check.conclusion !== null &&
+            ![
+                "ACTION_REQUIRED",
+                "CANCELLED",
+                "FAILURE",
+                "NEUTRAL",
+                "SKIPPED",
+                "STALE",
+                "STARTUP_FAILURE",
+                "SUCCESS",
+                "TIMED_OUT",
+            ].includes(restString(check.conclusion, "check conclusion").toUpperCase()))
+            malformedRest("unknown check conclusion");
+        restNumber(check.output?.annotations_count, "check run annotation count");
+        if (checkIds.has(check.node_id))
+            throw new Error("REST check run pagination duplicated an ID");
+        checkIds.add(check.node_id);
+        await recordRestIdentity(repo, pr, check.node_id, String(check.id), "check");
+        const suite = check.check_suite ? suiteMap.get(check.check_suite.id) : undefined;
+        const run = check.check_suite ? workflows.get(check.check_suite.id) : undefined;
+        nodes.push({
+            __typename: "CheckRun",
+            id: check.node_id,
+            name: check.name,
+            status: check.status.toUpperCase(),
+            conclusion: check.conclusion?.toUpperCase() ?? null,
+            detailsUrl: check.details_url,
+            startedAt: check.started_at,
+            completedAt: check.completed_at,
+            title: check.output.title,
+            summary: check.output.summary,
+            annotations: { totalCount: check.output.annotations_count, nodes: [] },
+            checkSuite: suite
+                ? {
+                    createdAt: suite.created_at,
+                    updatedAt: suite.updated_at,
+                    workflowRun: run
+                        ? {
+                            databaseId: run.id,
+                            event: run.event,
+                            createdAt: run.created_at,
+                            updatedAt: run.updated_at,
+                            workflow: { name: run.name, databaseId: run.workflow_id },
+                        }
+                        : null,
+                }
+                : null,
+        });
+    }
+    // REST statuses include history; only the latest status for each context is current.
+    const latest = new Map();
+    for (const status of statuses.nodes) {
+        restString(status.context, "status context");
+        restString(status.state, "status state");
+        if (!["PENDING", "EXPECTED", "SUCCESS", "FAILURE", "ERROR"].includes(status.state.toUpperCase()))
+            malformedRest("unknown status context state");
+        if (!Number.isFinite(Date.parse(status.created_at)))
+            malformedRest("status context created_at");
+        const old = latest.get(status.context);
+        if (!old ||
+            Date.parse(status.created_at) > Date.parse(old.created_at) ||
+            (status.created_at === old.created_at && status.id > old.id))
+            latest.set(status.context, status);
+    }
+    for (const status of latest.values())
+        nodes.push({
+            __typename: "StatusContext",
+            context: status.context,
+            state: status.state.toUpperCase(),
+            targetUrl: status.target_url,
+            description: status.description,
+            createdAt: status.created_at,
+        });
+    return {
+        nodes,
+        suites: suites.nodes,
+        workflowRuns: workflowRuns.nodes,
+        rateLimit: workflowRuns.rateLimit ?? checks.rateLimit,
+    };
+}
+export async function readRestAnnotationCounts(oid, repo) {
+    const checks = await readRestPages(`${restRepoPath(repo)}/commits/${encodeURIComponent(oid)}/check-runs?filter=latest`, (body) => restCollection(body, "check_runs"));
+    return checks.nodes.map((check) => ({
+        __typename: "CheckRun",
+        id: restString(check.node_id, "check node_id"),
+        annotations: { totalCount: restNumber(check.output?.annotations_count, "annotations_count") },
+    }));
+}
+export async function readRestBehind(repo, base, head) {
+    const comparison = await rest("GET", `${restRepoPath(repo)}/compare/${encodeURIComponent(base)}...${encodeURIComponent(head)}`);
+    return restNumber(comparison.behind_by, "compare behind_by");
+}

package/bin/github/rest-comment-authorship.d.mts

@@ -0,0 +1,7 @@
+import type { RestComment } from "./rest-feedback-read.mts";
+export declare function restCommentAuthorFields(comment: RestComment, viewerLogin?: string | null): {
+    author: string;
+    authorType: import("../types.mts").AuthorType;
+    viewerDidAuthor?: true | undefined;
+    authorAssociation: import("../types.mts").CommentAuthorAssociation;
+};

package/bin/github/rest-comment-authorship.mjs

@@ -0,0 +1,11 @@
+import { mapAuthorType } from "./batch-parser-helpers.mjs";
+export function restCommentAuthorFields(comment, viewerLogin) {
+    const login = typeof comment.user?.login === "string" ? comment.user.login : undefined;
+    return {
+        author: login ?? "unknown",
+        authorType: mapAuthorType(comment.user?.type, login),
+        ...(viewerLogin &&
+            login?.toLowerCase() === viewerLogin.toLowerCase() && { viewerDidAuthor: true }),
+        ...(comment.author_association && { authorAssociation: comment.author_association }),
+    };
+}

package/bin/github/rest-conditional-scope.d.mts

@@ -0,0 +1,20 @@
+import type { StateKey } from "../state/rest-cache.mts";
+export interface RestSnapshotState {
+    /**
+     * True when at least one conditional read answered 304 and every other read was a settled body
+     * without an ETag (fingerprinted by content instead). Any changed ETag-bearing body is fresh.
+     */
+    allNotModified: boolean;
+    /** Stable digest of every (path, validator) the snapshot observed. */
+    digest: string;
+}
+export declare function withRestConditionalScope<T>(key: StateKey, fn: () => Promise<T>): Promise<T>;
+export declare function currentRestConditionalKey(): StateKey | undefined;
+/**
+ * Record how one read was answered. `contentBody` is passed only for a settled 200 that carried
+ * no ETag: a route that cannot answer 304 (the Claude Code cloud proxy's `/ccr/review_threads`
+ * may not send validators) is then validated by a hash of its content, so an unchanged body
+ * still lets the snapshot's digest match. Every other non-304 read is fresh and blocks reuse.
+ */
+export declare function recordRestConditionalRead(path: string, notModified: boolean, etag: string | undefined, contentBody?: unknown): void;
+export declare function restSnapshotState(): RestSnapshotState | undefined;

package/bin/github/rest-conditional-scope.mjs

@@ -0,0 +1,44 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { createHash } from "node:crypto";
+const storage = new AsyncLocalStorage();
+export function withRestConditionalScope(key, fn) {
+    return storage.run({ key, fresh: 0, notModified: 0, etags: new Map() }, fn);
+}
+export function currentRestConditionalKey() {
+    return storage.getStore()?.key;
+}
+/**
+ * Record how one read was answered. `contentBody` is passed only for a settled 200 that carried
+ * no ETag: a route that cannot answer 304 (the Claude Code cloud proxy's `/ccr/review_threads`
+ * may not send validators) is then validated by a hash of its content, so an unchanged body
+ * still lets the snapshot's digest match. Every other non-304 read is fresh and blocks reuse.
+ */
+export function recordRestConditionalRead(path, notModified, etag, contentBody) {
+    const scope = storage.getStore();
+    if (scope === undefined)
+        return;
+    if (notModified)
+        scope.notModified += 1;
+    else if (etag !== undefined || contentBody === undefined)
+        scope.fresh += 1;
+    scope.etags.set(path, etag ?? (contentBody === undefined ? "" : `content:${contentDigest(contentBody)}`));
+}
+function contentDigest(body) {
+    return createHash("sha256")
+        .update(JSON.stringify(body) ?? "")
+        .digest("hex")
+        .slice(0, 16);
+}
+export function restSnapshotState() {
+    const scope = storage.getStore();
+    if (scope === undefined)
+        return undefined;
+    const hash = createHash("sha256");
+    for (const [path, etag] of [...scope.etags].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) {
+        hash.update(`${path}\0${etag}\0`);
+    }
+    return {
+        allNotModified: scope.fresh === 0 && scope.notModified > 0,
+        digest: hash.digest("hex").slice(0, 16),
+    };
+}

package/bin/github/rest-explicit-summary-read.d.mts

@@ -0,0 +1,3 @@
+import type { RepoInfo } from "./client.mts";
+/** One principal read for this explicit PR chunk, without assuming its PRs are standalone. */
+export declare function readRestExplicitSummary(prs: number[], repo: RepoInfo): Promise<import("./poll-summary-raw.mts").RawSummaryPr[]>;

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

@@ -0,0 +1,8 @@
+import { fetchRestRawSummaryPr } from "./rest-batch-read.mjs";
+import { readRestViewerLogin } from "./rest-viewer-read.mjs";
+import { mapPool } from "../util/pool.mjs";
+/** One principal read for this explicit PR chunk, without assuming its PRs are standalone. */
+export async function readRestExplicitSummary(prs, repo) {
+    const viewerLogin = await readRestViewerLogin();
+    return mapPool(prs, 4, (pr) => fetchRestRawSummaryPr(pr, repo, undefined, viewerLogin));
+}

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

@@ -0,0 +1,36 @@
+import type { RepoInfo } from "./client.mts";
+import type { PrComment, Review, ReviewThread, CommentAuthorAssociation } from "../types.mts";
+export interface RestComment {
+    id: number;
+    node_id: string;
+    body: string;
+    html_url: string;
+    created_at: string;
+    updated_at: string;
+    user: {
+        login: string;
+        type: string;
+    } | null;
+    author_association: CommentAuthorAssociation;
+    in_reply_to_id?: number;
+    pull_request_review_id?: number;
+    path?: string;
+    line?: number | null;
+    start_line?: number | null;
+}
+export interface RestReview extends RestComment {
+    state: string;
+    commit_id: string;
+    submitted_at?: string | null;
+}
+export declare function readRestFeedback(pr: number, repo: RepoInfo, knownViewerLogin?: string | null): Promise<{
+    threads: ReviewThread[];
+    comments: PrComment[];
+    reviews: RestReview[];
+    unavailable: {
+        field: string;
+        reason: string;
+    }[];
+    viewerLogin: string | null;
+}>;
+export declare function restReviewToReview(review: RestReview): Review;

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

@@ -0,0 +1,147 @@
+import { isCcrTransport } from "./transport.mjs";
+import { GitHubRequestError } from "./errors.mjs";
+import { EXIT } from "../exit-codes.mjs";
+import { readRestPages, restRepoPath, restArray, restObject, restNumber, restBoolean, malformedRest, } from "./rest-reader-core.mjs";
+import { recordRestIdentity, recordThreadIdentity, restThreadId } from "./rest-identities.mjs";
+import { parseCreatedAt } from "./batch-parser-helpers.mjs";
+import { restCommentAuthorFields as authorFields } from "./rest-comment-authorship.mjs";
+import { validateRestReviews } from "./rest-review-read.mjs";
+import { validateRestComments, feedbackIdsMatch } from "./rest-feedback-validation.mjs";
+import { readRestViewerLogin } from "./rest-viewer-read.mjs";
+export async function readRestFeedback(pr, repo, knownViewerLogin) {
+    const prefix = restRepoPath(repo);
+    let inline = (await readRestPages(`${prefix}/pulls/${pr}/comments`)).nodes;
+    const issue = (await readRestPages(`${prefix}/issues/${pr}/comments`)).nodes;
+    const reviews = (await readRestPages(`${prefix}/pulls/${pr}/reviews`)).nodes;
+    if (new Set(issue.map((comment) => comment.id)).size !== issue.length ||
+        new Set(reviews.map((review) => review.id)).size !== reviews.length)
+        malformedRest("duplicate feedback IDs");
+    validateRestReviews(reviews);
+    validateRestComments([...inline, ...issue, ...reviews]);
+    let statuses = await readRestThreadStatuses(`${prefix}/pulls/${pr}/ccr/review_threads`);
+    if (statuses && !feedbackIdsMatch(inline, statuses)) {
+        // A reviewer can add or delete comments between these independently paginated reads.
+        // Retry both resources, with thread membership first, before certifying the join.
+        statuses = await readRestThreadStatuses(`${prefix}/pulls/${pr}/ccr/review_threads`);
+        inline = (await readRestPages(`${prefix}/pulls/${pr}/comments`)).nodes;
+        validateRestComments(inline);
+        if (statuses && !feedbackIdsMatch(inline, statuses))
+            throw new GitHubRequestError("Pull request feedback changed while REST snapshot was being read; retry", { status: 409, exitCodeOverride: EXIT.TEMPFAIL });
+    }
+    for (const comment of [...inline, ...issue, ...reviews]) {
+        await recordRestIdentity(repo, pr, comment.node_id, String(comment.id), "state" in comment ? "review" : "comment");
+    }
+    let unavailable = [];
+    if (!statuses && inline.length > 0)
+        unavailable = [
+            {
+                field: "reviewThreads.status",
+                reason: "REST has no resolved/outdated thread state; CCR review_threads is unavailable",
+            },
+        ];
+    const inlineMap = new Map(inline.map((comment) => [comment.id, comment]));
+    if (inlineMap.size !== inline.length)
+        malformedRest("duplicate inline comment IDs");
+    const groups = [];
+    if (statuses) {
+        for (const status of statuses) {
+            const comments = status.comment_ids.map((id) => inlineMap.get(id));
+            const root = comments[0];
+            if (root.in_reply_to_id != null)
+                malformedRest("CCR thread root is a reply");
+            for (const reply of comments.slice(1))
+                if (reply.in_reply_to_id !== root.id)
+                    malformedRest("CCR reply does not belong to its root");
+            groups.push({ id: root.id, comments, status });
+        }
+    }
+    else {
+        for (const comment of inline.filter((comment) => comment.in_reply_to_id == null)) {
+            groups.push({
+                id: comment.id,
+                comments: [comment, ...inline.filter((reply) => reply.in_reply_to_id === comment.id)],
+            });
+        }
+        if (groups.reduce((sum, group) => sum + group.comments.length, 0) !== inline.length)
+            malformedRest("inline comment reply has no root");
+    }
+    const threads = [];
+    const viewerLogin = knownViewerLogin === undefined ? await readRestViewerLogin() : knownViewerLogin;
+    for (const group of groups) {
+        const root = group.comments[0];
+        const id = restThreadId(String(group.id));
+        await recordThreadIdentity(repo, pr, id, String(group.id));
+        const review = reviews.find((review) => review.id === root.pull_request_review_id);
+        threads.push({
+            id,
+            ...(group.status
+                ? { isResolved: group.status.resolved, isOutdated: group.status.outdated }
+                : {}),
+            path: group.status ? group.status.path : (root.path ?? null),
+            line: group.status ? group.status.line : (root.line ?? null),
+            startLine: root.start_line ?? null,
+            ...(review ? { reviewId: review.node_id } : {}),
+            ...authorFields(root, viewerLogin),
+            body: root.body ?? "",
+            url: root.html_url,
+            createdAtUnix: parseCreatedAt(root.created_at),
+            comments: group.comments.map((comment) => ({
+                id: comment.node_id,
+                ...(review ? { reviewId: review.node_id } : {}),
+                ...authorFields(comment, viewerLogin),
+                body: comment.body ?? "",
+                url: comment.html_url,
+                createdAtUnix: parseCreatedAt(comment.created_at),
+            })),
+        });
+    }
+    const comments = issue.map((comment) => ({
+        id: comment.node_id,
+        ...authorFields(comment),
+        body: comment.body ?? "",
+        url: comment.html_url,
+        createdAtUnix: parseCreatedAt(comment.created_at),
+    }));
+    return { threads, comments, reviews, unavailable, viewerLogin };
+}
+async function readRestThreadStatuses(path) {
+    if (!isCcrTransport())
+        return undefined;
+    try {
+        const statuses = (await readRestPages(path)).nodes;
+        for (const status of statuses) {
+            restObject(status, "CCR thread");
+            restBoolean(status.resolved, "CCR thread resolved");
+            restBoolean(status.outdated, "CCR thread outdated");
+            restArray(status.comment_ids, "CCR comment_ids");
+            if (status.path !== null && typeof status.path !== "string")
+                malformedRest("CCR thread path");
+            if (status.line !== null)
+                restNumber(status.line, "CCR thread line");
+            if (status.comment_ids.length === 0)
+                malformedRest("CCR thread has no root comment");
+            for (const id of status.comment_ids)
+                restNumber(id, "CCR comment ID");
+        }
+        return statuses;
+    }
+    catch (error) {
+        if (!(error instanceof GitHubRequestError) || error.status !== 404)
+            throw error;
+        // The proxy answers a missing PR with 404 too; that is not an unavailable route.
+        if (/could not resolve to a pullrequest/i.test(error.responseMessage ?? error.message)) {
+            throw error;
+        }
+        return undefined;
+    }
+}
+export function restReviewToReview(review) {
+    return {
+        id: review.node_id,
+        ...authorFields(review),
+        body: review.body ?? "",
+        url: review.html_url,
+        ...(review.commit_id && { commitOid: review.commit_id }),
+        ...(review.submitted_at && { createdAtUnix: parseCreatedAt(review.submitted_at) }),
+    };
+}

package/bin/github/rest-feedback-validation.d.mts

@@ -0,0 +1,5 @@
+import type { RestComment } from "./rest-feedback-read.mts";
+export declare function validateRestComments(comments: RestComment[]): void;
+export declare function feedbackIdsMatch(inline: RestComment[], statuses: {
+    comment_ids: number[];
+}[]): boolean;

package/bin/github/rest-feedback-validation.mjs

@@ -0,0 +1,28 @@
+import { restObject, restString, restNumber, malformedRest } from "./rest-reader-core.mjs";
+export function validateRestComments(comments) {
+    for (const comment of comments) {
+        restObject(comment, "feedback comment");
+        restString(comment.html_url, "feedback html_url");
+        if (!("state" in comment)) {
+            restString(comment.created_at, "comment created_at");
+            restString(comment.updated_at, "comment updated_at");
+            if (!Number.isFinite(Date.parse(comment.created_at)) ||
+                !Number.isFinite(Date.parse(comment.updated_at)))
+                malformedRest("feedback timestamps");
+        }
+        restNumber(comment.id, "feedback id");
+        restString(comment.node_id, "feedback node_id");
+        if (typeof comment.body !== "string" && comment.body !== null)
+            malformedRest("feedback body");
+    }
+}
+export function feedbackIdsMatch(inline, statuses) {
+    const inlineIds = new Set(inline.map((comment) => comment.id));
+    if (inlineIds.size !== inline.length)
+        malformedRest("duplicate inline comment IDs");
+    const threadIds = statuses.flatMap((status) => status.comment_ids);
+    const covered = new Set(threadIds);
+    if (covered.size !== threadIds.length)
+        malformedRest("repeated CCR thread comment IDs");
+    return covered.size === inlineIds.size && threadIds.every((id) => inlineIds.has(id));
+}

package/bin/github/rest-http.d.mts

@@ -3,6 +3,12 @@ import { type RateLimitInfo } from "./http-utils.mts";
 export interface RestResult<T = unknown> {
     data: T;
     rateLimit?: RateLimitInfo;
+    /** HTTP status, including documented non-2xx statuses accepted by the caller. */
+    status?: number;
+    /** Validator of a conditional read: the stored ETag on a 304, the response ETag on a 200. */
+    etag?: string;
+    /** GitHub pagination header, retained for named REST readers. */
+    link?: string;
 }
 /**
  * Enables `If-None-Match` conditional requests for a REST call, backed by a
@@ -11,11 +17,17 @@ export interface RestResult<T = unknown> {
  * the primary REST rate-limit quota.
  */
 export interface RestRequestOptions {
+    /** Endpoints such as merge-async return useful state on documented non-2xx responses. */
+    acceptStatuses?: readonly number[];
     conditional?: {
         key: StateKey;
         /** Logical cache name; must be unique per distinct resource + page. */
         name: string;
         headSha?: string;
+        /** Return false to keep a 200 body out of the cache (e.g. a still-computing resource). */
+        shouldStore?: (body: unknown) => boolean;
+        /** Send no validator, forcing a fresh body that then replaces the cached entry. */
+        revalidate?: boolean;
     };
 }
 export declare function rest<T = unknown>(method: string, path: string, body?: unknown): Promise<T>;