pr-shepherd 0.44.0 → 0.45.0

package/bin/exit-codes.mjs

@@ -34,7 +34,7 @@ export const EXIT = Object.freeze({
     UNAVAILABLE: 69,
     /** Unexpected/unclassified internal error — the fallback. */
     SOFTWARE: 70,
-    /** Retryable GitHub failure: 429, 5xx, rate limit exhausted, `Retry-After` present. */
+    /** Retryable GitHub failure: 429, 5xx, rate limit exhausted, Retry-After, GraphQL INTERNAL. */
     TEMPFAIL: 75,
     /** GitHub 401/403 — missing token or insufficient PAT scopes. */
     NOPERM: 77,

package/bin/github/api-telemetry-aggregate.d.mts

@@ -0,0 +1,32 @@
+import type { ApiTelemetryEvent } from "./api-telemetry.mts";
+import type { RateLimitInfo } from "./http-utils.mts";
+export interface TelemetryAggregate {
+    eventCount: number;
+    credentialSources: Map<string, number>;
+    graphql: {
+        requestCount: number;
+        measuredQueryCost: number;
+        unmeasuredRequestCount: number;
+        nodeCount: number;
+        rateLimit?: RateLimitInfo;
+    };
+    rest: Map<string, {
+        requestCount: number;
+        rateLimit?: RateLimitInfo;
+    }>;
+}
+export interface SequencedApiTelemetryEvent extends ApiTelemetryEvent {
+    sequence: number;
+}
+export interface TelemetryStore {
+    events: SequencedApiTelemetryEvent[];
+    compacted: TelemetryAggregate;
+    eventCount: number;
+    clock: {
+        next: number;
+    };
+}
+export declare function emptyAggregate(): TelemetryAggregate;
+export declare function aggregateEvents(events: SequencedApiTelemetryEvent[]): TelemetryAggregate;
+export declare function mergeAggregate(target: TelemetryAggregate, source: TelemetryAggregate): void;
+export declare function aggregateStore(active: TelemetryStore): TelemetryAggregate;

package/bin/github/api-telemetry-aggregate.mjs

@@ -0,0 +1,84 @@
+export function emptyAggregate() {
+    return {
+        eventCount: 0,
+        credentialSources: new Map(),
+        graphql: { requestCount: 0, measuredQueryCost: 0, unmeasuredRequestCount: 0, nodeCount: 0 },
+        rest: new Map(),
+    };
+}
+export function aggregateEvents(events) {
+    const aggregate = emptyAggregate();
+    for (const event of events) {
+        aggregate.eventCount += 1;
+        if (!aggregate.credentialSources.has(event.authSource)) {
+            aggregate.credentialSources.set(event.authSource, event.sequence);
+        }
+        if (event.kind === "GraphQL") {
+            aggregate.graphql.requestCount += 1;
+            if (event.rateLimit?.cost === undefined)
+                aggregate.graphql.unmeasuredRequestCount += 1;
+            else
+                aggregate.graphql.measuredQueryCost += event.rateLimit.cost;
+            aggregate.graphql.nodeCount += event.rateLimit?.nodeCount ?? 0;
+            if (event.rateLimit !== undefined) {
+                aggregate.graphql.rateLimit = selectAuthoritativeRateLimit(aggregate.graphql.rateLimit, event.rateLimit);
+            }
+            continue;
+        }
+        const resource = event.rateLimit?.resource ?? "unknown";
+        const group = aggregate.rest.get(resource) ?? { requestCount: 0 };
+        group.requestCount += 1;
+        if (event.rateLimit !== undefined) {
+            group.rateLimit = selectAuthoritativeRateLimit(group.rateLimit, event.rateLimit);
+        }
+        aggregate.rest.set(resource, group);
+    }
+    return aggregate;
+}
+export function mergeAggregate(target, source) {
+    target.eventCount += source.eventCount;
+    for (const [credentialSource, sequence] of source.credentialSources) {
+        const current = target.credentialSources.get(credentialSource);
+        if (current === undefined || sequence < current) {
+            target.credentialSources.set(credentialSource, sequence);
+        }
+    }
+    target.graphql.requestCount += source.graphql.requestCount;
+    target.graphql.measuredQueryCost += source.graphql.measuredQueryCost;
+    target.graphql.unmeasuredRequestCount += source.graphql.unmeasuredRequestCount;
+    target.graphql.nodeCount += source.graphql.nodeCount;
+    if (source.graphql.rateLimit !== undefined) {
+        target.graphql.rateLimit = selectAuthoritativeRateLimit(target.graphql.rateLimit, source.graphql.rateLimit);
+    }
+    for (const [resource, sourceGroup] of source.rest) {
+        const targetGroup = target.rest.get(resource) ?? { requestCount: 0 };
+        targetGroup.requestCount += sourceGroup.requestCount;
+        if (sourceGroup.rateLimit !== undefined) {
+            targetGroup.rateLimit = selectAuthoritativeRateLimit(targetGroup.rateLimit, sourceGroup.rateLimit);
+        }
+        target.rest.set(resource, targetGroup);
+    }
+}
+export function aggregateStore(active) {
+    const all = emptyAggregate();
+    mergeAggregate(all, active.compacted);
+    mergeAggregate(all, aggregateEvents(active.events));
+    return all;
+}
+function selectAuthoritativeRateLimit(current, candidate) {
+    if (current === undefined)
+        return { ...candidate };
+    if (candidate.resetAt !== current.resetAt) {
+        return candidate.resetAt > current.resetAt ? { ...candidate } : current;
+    }
+    if (candidate.remaining !== current.remaining) {
+        return candidate.remaining < current.remaining ? { ...candidate } : current;
+    }
+    if (candidate.used !== current.used) {
+        if (candidate.used === undefined)
+            return current;
+        if (current.used === undefined || candidate.used > current.used)
+            return { ...candidate };
+    }
+    return current;
+}

package/bin/github/api-telemetry.d.mts

@@ -0,0 +1,13 @@
+import type { ApiUsage } from "../types.mts";
+import type { RateLimitInfo } from "./http-utils.mts";
+export interface ApiTelemetryEvent {
+    kind: "GraphQL" | "REST";
+    method: string;
+    authSource: string;
+    rateLimit?: RateLimitInfo;
+}
+/** Isolates a top-level CLI/MCP command while allowing nested iterate ticks to aggregate. */
+export declare function withApiTelemetryScope<T>(fn: () => Promise<T>): Promise<T>;
+export declare function recordApiTelemetry(event: ApiTelemetryEvent): void;
+export declare function mergeGraphqlRateLimit(headerRateLimit: RateLimitInfo | null, data: unknown): RateLimitInfo | null;
+export declare function summarizeApiTelemetry(): ApiUsage | undefined;

package/bin/github/api-telemetry.mjs

@@ -0,0 +1,128 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { aggregateEvents, aggregateStore, emptyAggregate, mergeAggregate, } from "./api-telemetry-aggregate.mjs";
+const GRAPHQL_RATE_LIMIT_ALIAS = "_shepherdRateLimit";
+const eventStorage = new AsyncLocalStorage();
+function store() {
+    return eventStorage.getStore();
+}
+/** Isolates a top-level CLI/MCP command while allowing nested iterate ticks to aggregate. */
+export function withApiTelemetryScope(fn) {
+    const parent = store();
+    const child = {
+        events: [],
+        compacted: emptyAggregate(),
+        eventCount: 0,
+        clock: parent?.clock ?? { next: 0 },
+    };
+    return eventStorage.run(child, async () => {
+        try {
+            return await fn();
+        }
+        finally {
+            mergeAggregate(child.compacted, aggregateEvents(child.events));
+            child.events = [];
+            if (parent !== undefined) {
+                mergeAggregate(parent.compacted, aggregateEvents(parent.events));
+                parent.events = [];
+                mergeAggregate(parent.compacted, child.compacted);
+                parent.eventCount += child.eventCount;
+            }
+        }
+    });
+}
+export function recordApiTelemetry(event) {
+    const active = store();
+    if (active === undefined)
+        return;
+    active.events.push({
+        ...event,
+        rateLimit: event.rateLimit ? { ...event.rateLimit } : undefined,
+        sequence: active.clock.next++,
+    });
+    active.eventCount += 1;
+}
+export function mergeGraphqlRateLimit(headerRateLimit, data) {
+    const payload = extractGraphqlRateLimit(data);
+    if (headerRateLimit === null && payload === null)
+        return null;
+    const resetAt = payload === null ? undefined : Date.parse(payload.resetAt) / 1000;
+    const fallback = payload !== null && Number.isFinite(resetAt)
+        ? {
+            limit: payload.limit,
+            used: payload.used,
+            remaining: payload.remaining,
+            resetAt: resetAt,
+            resource: "graphql",
+        }
+        : null;
+    const base = headerRateLimit ?? fallback;
+    if (base === null)
+        return null;
+    return {
+        ...base,
+        resource: base.resource ?? "graphql",
+        ...(payload !== null && Number.isFinite(payload.cost) && { cost: payload.cost }),
+        ...(payload !== null && Number.isFinite(payload.nodeCount) && { nodeCount: payload.nodeCount }),
+    };
+}
+export function summarizeApiTelemetry() {
+    const active = store();
+    if (active === undefined)
+        return undefined;
+    const selected = aggregateStore(active);
+    if (selected.eventCount === 0)
+        return undefined;
+    const credentialSources = [...selected.credentialSources.entries()]
+        .sort((left, right) => left[1] - right[1])
+        .map(([source]) => source);
+    const graphql = summarizeGraphql(selected.graphql);
+    const rest = summarizeRest(selected.rest);
+    return {
+        credentialSources,
+        ...(graphql !== undefined && { graphql }),
+        ...(rest.length > 0 && { rest }),
+    };
+}
+function summarizeGraphql(selected) {
+    const rateLimit = selected.rateLimit;
+    if (rateLimit === undefined)
+        return undefined;
+    return {
+        ...resourceUsage(rateLimit, selected.requestCount, "graphql"),
+        measuredQueryCost: selected.measuredQueryCost,
+        unmeasuredRequestCount: selected.unmeasuredRequestCount,
+        nodeCount: selected.nodeCount,
+    };
+}
+function summarizeRest(selected) {
+    return [...selected.entries()].flatMap(([resource, group]) => {
+        return group.rateLimit ? [resourceUsage(group.rateLimit, group.requestCount, resource)] : [];
+    });
+}
+function resourceUsage(rateLimit, requestCount, fallbackResource) {
+    return {
+        resource: rateLimit.resource ?? fallbackResource,
+        requestCount,
+        limit: rateLimit.limit,
+        ...(rateLimit.used !== undefined && { used: rateLimit.used }),
+        remaining: rateLimit.remaining,
+        resetAt: rateLimit.resetAt,
+    };
+}
+function extractGraphqlRateLimit(data) {
+    if (data === null || typeof data !== "object" || Array.isArray(data))
+        return null;
+    const value = data[GRAPHQL_RATE_LIMIT_ALIAS];
+    if (value === null || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const record = value;
+    if (!Number.isFinite(record["cost"]) ||
+        !Number.isFinite(record["limit"]) ||
+        !Number.isFinite(record["nodeCount"]) ||
+        !Number.isFinite(record["remaining"]) ||
+        typeof record["resetAt"] !== "string" ||
+        !Number.isFinite(record["used"])) {
+        return null;
+    }
+    return record;
+}

package/bin/github/check-annotations.d.mts

@@ -1,2 +1,15 @@
+import { type StateKey } from "../state/rest-cache.mts";
 import type { CheckAnnotation } from "../types.mts";
-export declare function fetchCheckRunAnnotations(checkRunId: string): Promise<CheckAnnotation[]>;
+export interface AnnotationCacheOptions {
+    stateKey: StateKey;
+    headSha?: string;
+}
+/**
+ * Fetches all inline annotations for a check run.
+ *
+ * When `cacheOpts` is provided, the result is cached by `checkRunId` — safe
+ * because callers only pass `cacheOpts` for COMPLETED check runs (a re-run
+ * mints a new check-run node id, so a COMPLETED run's annotations are
+ * immutable once fetched).
+ */
+export declare function fetchCheckRunAnnotations(checkRunId: string, cacheOpts?: AnnotationCacheOptions): Promise<CheckAnnotation[]>;

package/bin/github/check-annotations.mjs

@@ -1,11 +1,34 @@
 import { createHash } from "node:crypto";
 import { graphql } from "./client.mjs";
 import { CHECK_RUN_ANNOTATIONS_QUERY } from "./queries.mjs";
+import { loadDerived, storeDerived } from "../state/rest-cache.mjs";
 const ANNOTATIONS_PER_PAGE = 100;
 const MAX_ANNOTATION_PAGES = 10;
 const ANNOTATION_TEXT_MAX_CHARS = 4_000;
 const TRUNCATED_SUFFIX = "\n[truncated]";
-export async function fetchCheckRunAnnotations(checkRunId) {
+/**
+ * Some Checks-API publishers (e.g. SonarCloud) PATCH additional annotations
+ * onto an already-COMPLETED check run without minting a new check-run node
+ * ID, so "COMPLETED" is not a reliable immutability signal on its own. Bound
+ * the cache instead of trusting it forever, so a long-running poll session
+ * eventually revalidates.
+ */
+const ANNOTATION_CACHE_MAX_AGE_MS = 60 * 60 * 1000;
+/**
+ * Fetches all inline annotations for a check run.
+ *
+ * When `cacheOpts` is provided, the result is cached by `checkRunId` — safe
+ * because callers only pass `cacheOpts` for COMPLETED check runs (a re-run
+ * mints a new check-run node id, so a COMPLETED run's annotations are
+ * immutable once fetched).
+ */
+export async function fetchCheckRunAnnotations(checkRunId, cacheOpts) {
+    const cacheName = `annotations-${checkRunId}`;
+    if (cacheOpts) {
+        const cached = await loadDerived(cacheOpts.stateKey, cacheName);
+        if (cached && Date.now() - cached.storedAt < ANNOTATION_CACHE_MAX_AGE_MS)
+            return cached.value;
+    }
     let cursor = null;
     const nodes = [];
     for (let page = 1; page <= MAX_ANNOTATION_PAGES; page++) {
@@ -20,7 +43,11 @@ export async function fetchCheckRunAnnotations(checkRunId) {
         }
         cursor = result.pageInfo.endCursor;
     }
-    return nodes.map((node) => toCheckAnnotation(checkRunId, node));
+    const annotations = nodes.map((node) => toCheckAnnotation(checkRunId, node));
+    if (cacheOpts) {
+        await storeDerived(cacheOpts.stateKey, cacheName, annotations, cacheOpts.headSha);
+    }
+    return annotations;
 }
 async function fetchAnnotationPage(checkRunId, cursor) {
     const res = await graphql(CHECK_RUN_ANNOTATIONS_QUERY, {

package/bin/github/errors.d.mts

@@ -3,17 +3,25 @@ import type { RateLimitInfo } from "./http.mts";
 export interface GitHubGraphQlError {
     message: string;
     path?: unknown;
+    /** GitHub's GraphQL `type` field — `INTERNAL` on engine crashes. */
+    type?: string;
+    /** GraphQL `extensions`; GitHub often sets `{ code: "INTERNAL" }`. */
+    extensions?: unknown;
 }
+/** GitHub GraphQL engine crash: HTTP 200, `data: null`, INTERNAL type/code or message. */
+export declare function isRetryableGraphQlInternal(graphqlErrors?: GitHubGraphQlError[]): boolean;
 export declare class GitHubRequestError extends ShepherdError {
     readonly status: number;
     readonly rateLimit?: RateLimitInfo;
     readonly retryAfterSeconds?: number;
     readonly graphqlErrors?: GitHubGraphQlError[];
+    readonly authSource?: string;
     constructor(message: string, opts: {
         status: number;
         rateLimit?: RateLimitInfo;
         retryAfterSeconds?: number;
         graphqlErrors?: GitHubGraphQlError[];
+        authSource?: string;
         /**
          * Bypasses status-based classification entirely — for callers that already
          * know the failure kind better than the HTTP status can express (e.g. a

package/bin/github/errors.mjs

@@ -5,16 +5,42 @@ import { EXIT, ShepherdError } from "../exit-codes.mjs";
 // be resolved. Status alone can't see this, so classification must also inspect the
 // GraphQL error messages themselves.
 const GRAPHQL_PERMISSION_ERROR = /resource not accessible/i;
+const GRAPHQL_INTERNAL_MESSAGE = /something went wrong while executing your query/i;
+function isInternalToken(value) {
+    return typeof value === "string" && value.toUpperCase() === "INTERNAL";
+}
+function extensionsCode(extensions) {
+    if (typeof extensions !== "object" || extensions === null || Array.isArray(extensions)) {
+        return undefined;
+    }
+    return extensions["code"];
+}
 function hasPermissionError(graphqlErrors) {
     return graphqlErrors?.some((e) => GRAPHQL_PERMISSION_ERROR.test(e.message)) ?? false;
 }
+/** GitHub GraphQL engine crash: HTTP 200, `data: null`, INTERNAL type/code or message. */
+export function isRetryableGraphQlInternal(graphqlErrors) {
+    if (!graphqlErrors?.length)
+        return false;
+    return graphqlErrors.some((error) => {
+        if (isInternalToken(error.type))
+            return true;
+        if (isInternalToken(extensionsCode(error.extensions)))
+            return true;
+        return GRAPHQL_INTERNAL_MESSAGE.test(error.message);
+    });
+}
 function classifyStatus(status, rateLimit, retryAfterSeconds, graphqlErrors) {
     // Retry signals take priority over everything else: GitHub's secondary rate limit
     // returns 403 with a Retry-After header, which is a transient throttle — not the
     // permission-denied 403 a bad/missing token produces. Treat any retry signal as
     // TEMPFAIL first so it isn't shadowed by the checks below.
     const rateLimitExhausted = rateLimit !== undefined && rateLimit.remaining <= 0;
-    if (status === 429 || status >= 500 || retryAfterSeconds !== undefined || rateLimitExhausted) {
+    if (status === 429 ||
+        status >= 500 ||
+        retryAfterSeconds !== undefined ||
+        rateLimitExhausted ||
+        isRetryableGraphQlInternal(graphqlErrors)) {
         return EXIT.TEMPFAIL;
     }
     if (status === 401 || status === 403 || hasPermissionError(graphqlErrors))
@@ -26,6 +52,7 @@ export class GitHubRequestError extends ShepherdError {
     rateLimit;
     retryAfterSeconds;
     graphqlErrors;
+    authSource;
     constructor(message, opts) {
         super(message, opts.exitCodeOverride ??
             classifyStatus(opts.status, opts.rateLimit, opts.retryAfterSeconds, opts.graphqlErrors));
@@ -34,5 +61,6 @@ export class GitHubRequestError extends ShepherdError {
         this.rateLimit = opts.rateLimit;
         this.retryAfterSeconds = opts.retryAfterSeconds;
         this.graphqlErrors = opts.graphqlErrors;
+        this.authSource = opts.authSource;
     }
 }

package/bin/github/gql/batch-pr-page.gql

@@ -18,6 +18,14 @@ query BatchPrPage(
   $includeChecks: Boolean!
   $checksCursor: String
 ) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
   repository(owner: $owner, name: $repo) {
     pullRequest(number: $pr) {
       reviewThreads(last: 100, before: $threadsCursor) @include(if: $includeThreads) {

package/bin/github/gql/batch-pr.gql

@@ -1,6 +1,14 @@
 # First page only. Extra pages use batch-pr-page.gql so follow-ups do not
 # re-select every connection (GraphQL points scale with possible nodes).
 query BatchPr($owner: String!, $repo: String!, $pr: Int!) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
   repository(owner: $owner, name: $repo) {
     viewerPermission
     viewerCanAdminister

package/bin/github/gql/check-run-annotations.gql

@@ -1,4 +1,12 @@
 query CheckRunAnnotations($id: ID!, $cursor: String) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
   node(id: $id) {
     __typename
     ... on CheckRun {

package/bin/github/gql/commit-check-contexts.gql

@@ -1,4 +1,12 @@
 query CommitCheckContexts($owner: String!, $repo: String!, $oid: String!, $cursor: String) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
   repository(owner: $owner, name: $repo) {
     object(expression: $oid) {
       __typename

package/bin/github/gql/get-pr-body.gql

@@ -1,4 +1,12 @@
 query GetPrBody($owner: String!, $repo: String!, $pr: Int!) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
   repository(owner: $owner, name: $repo) {
     pullRequest(number: $pr) {
       id

package/bin/github/gql/get-pr-head-sha.gql

@@ -1,4 +1,12 @@
 query GetPrHeadSha($owner: String!, $repo: String!, $pr: Int!) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
   repository(owner: $owner, name: $repo) {
     pullRequest(number: $pr) {
       headRefOid

package/bin/github/gql/pr-number-by-branch.gql

@@ -1,4 +1,12 @@
 query PrNumberByBranch($owner: String!, $repo: String!, $branch: String!) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
   repository(owner: $owner, name: $repo) {
     pullRequests(headRefName: $branch, states: OPEN, first: 1) {
       nodes {

package/bin/github/gql/review-thread-comments.gql

@@ -1,4 +1,12 @@
 query ReviewThreadComments($threadId: ID!, $commentsCursor: String) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
   node(id: $threadId) {
     __typename
     ... on PullRequestReviewThread {

package/bin/github/gql/suggestion-threads.gql

@@ -1,4 +1,12 @@
 query SuggestionThreads($owner: String!, $repo: String!, $pr: Int!, $threadIds: [ID!]!) {
+  _shepherdRateLimit: rateLimit {
+    cost
+    limit
+    nodeCount
+    remaining
+    resetAt
+    used
+  }
   repository(owner: $owner, name: $repo) {
     pullRequest(number: $pr) {
       headRefOid