pr-shepherd 0.44.1 → 0.45.0

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

@@ -15,11 +15,13 @@ export declare class GitHubRequestError extends ShepherdError {
     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

@@ -52,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));
@@ -60,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

package/bin/github/graphql-http.mjs

@@ -1,11 +1,14 @@
+/* eslint-disable max-lines */
 import { appendEntry, nextEntry } from "../log/log-file.mjs";
 import { formatRequestEntry, formatResponseEntry } from "../log/session.mjs";
 import { GitHubRequestError } from "./errors.mjs";
 import { withGraphQlInternalRetry } from "./graphql-internal-retry.mjs";
 import { formatGraphQlErrors, parseGraphQlPayload } from "./graphql-response.mjs";
-import { makeHeaders } from "./http-auth.mjs";
+import { makeAuthHeaders } from "./http-auth.mjs";
 import { requestWithTokenRetry } from "./http-request.mjs";
 import { parseRateLimit, parseRetryAfter, redactToken, sanitizeBody, } from "./http-utils.mjs";
+import { mergeGraphqlRateLimit, recordApiTelemetry } from "./api-telemetry.mjs";
+import { recordIntermediateResponse } from "./http-intermediate.mjs";
 const BASE_URL = "https://api.github.com";
 async function graphqlInner(query, vars, opts) {
     const url = `${BASE_URL}/graphql`;
@@ -18,13 +21,26 @@ async function graphqlInner(query, vars, opts) {
         body: { query, variables: vars },
     }));
     const t0 = performance.now();
-    const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => fetch(url, {
+    let authSource = "unknown";
+    const { res, attempt, retryT0 } = await requestWithTokenRetry(async () => {
+        const auth = await makeAuthHeaders();
+        authSource = auth.source;
+        return fetch(url, {
+            method: "POST",
+            headers: auth.headers,
+            body: JSON.stringify({ query, variables: vars }),
+        });
+    }, t0, (response, durationMs) => recordIntermediateResponse({
+        n,
+        kind: "GraphQL",
         method: "POST",
-        headers: await makeHeaders(),
-        body: JSON.stringify({ query, variables: vars }),
-    }), t0, (status, durationMs) => appendEntry(formatResponseEntry({ n, kind: "GraphQL", method: "POST", url, status, durationMs })));
+        url,
+        response,
+        durationMs,
+        authSource,
+    }));
     const durationMs = Math.round(performance.now() - retryT0);
-    const rateLimit = parseRateLimit(res.headers);
+    const headerRateLimit = parseRateLimit(res.headers);
     const retryAfterSeconds = parseRetryAfter(res.headers);
     if (!res.ok) {
         const body = await res.text();
@@ -37,8 +53,22 @@ async function graphqlInner(query, vars, opts) {
             durationMs,
             textBody: redactToken(body),
             attempt: attempt > 1 ? attempt : undefined,
+            authSource,
+            rateLimit: headerRateLimit ?? undefined,
+            retryAfterSeconds,
         }));
-        throw new GitHubRequestError(`GitHub GraphQL request failed: ${res.status} ${sanitizeBody(body)}`, { status: res.status, rateLimit: rateLimit ?? undefined, retryAfterSeconds });
+        recordApiTelemetry({
+            kind: "GraphQL",
+            method: "POST",
+            authSource,
+            rateLimit: headerRateLimit ?? undefined,
+        });
+        throw new GitHubRequestError(`GitHub GraphQL request failed: ${res.status} ${sanitizeBody(body)}`, {
+            status: res.status,
+            rateLimit: headerRateLimit ?? undefined,
+            retryAfterSeconds,
+            authSource,
+        });
     }
     let parsed;
     try {
@@ -55,13 +85,27 @@ async function graphqlInner(query, vars, opts) {
             durationMs,
             textBody: `Invalid JSON response${detail}`,
             attempt: attempt > 1 ? attempt : undefined,
+            authSource,
+            rateLimit: headerRateLimit ?? undefined,
+            retryAfterSeconds,
         }));
+        recordApiTelemetry({
+            kind: "GraphQL",
+            method: "POST",
+            authSource,
+            rateLimit: headerRateLimit ?? undefined,
+        });
         throw new GitHubRequestError(`GitHub GraphQL response was not valid JSON${detail}`, {
             status: res.status,
-            rateLimit: rateLimit ?? undefined,
+            rateLimit: headerRateLimit ?? undefined,
             retryAfterSeconds,
+            authSource,
         });
     }
+    const parsedData = parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)
+        ? parsed["data"]
+        : undefined;
+    const rateLimit = mergeGraphqlRateLimit(headerRateLimit, parsedData);
     appendEntry(formatResponseEntry({
         n,
         kind: "GraphQL",
@@ -71,7 +115,16 @@ async function graphqlInner(query, vars, opts) {
         durationMs,
         body: parsed,
         attempt: attempt > 1 ? attempt : undefined,
+        authSource,
+        rateLimit: rateLimit ?? undefined,
+        retryAfterSeconds,
     }));
+    recordApiTelemetry({
+        kind: "GraphQL",
+        method: "POST",
+        authSource,
+        rateLimit: rateLimit ?? undefined,
+    });
     const payload = parseGraphQlPayload(parsed, res.status, rateLimit, retryAfterSeconds);
     if (payload.data == null) {
         const detail = formatGraphQlErrors(payload.errors);
@@ -80,6 +133,7 @@ async function graphqlInner(query, vars, opts) {
             rateLimit: rateLimit ?? undefined,
             retryAfterSeconds,
             graphqlErrors: payload.errors,
+            authSource,
         });
     }
     if (payload.errors?.length && !opts.allowPartialData) {
@@ -88,6 +142,7 @@ async function graphqlInner(query, vars, opts) {
             rateLimit: rateLimit ?? undefined,
             retryAfterSeconds,
             graphqlErrors: payload.errors,
+            authSource,
         });
     }
     if (payload.errors?.length) {

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

@@ -1,4 +1,12 @@
+export type AuthSource = "GH_TOKEN" | "GITHUB_TOKEN" | "gh auth token" | "GITHUB_PERSONAL_ACCESS_TOKEN";
 export declare function _resetTokenCache(): void;
 export declare function hasCachedToken(): boolean;
 export declare function clearTokenCache(): void;
-export declare function makeHeaders(): Promise<Record<string, string>>;
+/**
+ * `extra` lets callers layer additional headers (e.g. `If-None-Match` for
+ * conditional REST requests) on top of the standard auth/version headers.
+ */
+export declare function makeAuthHeaders(extra?: Record<string, string>): Promise<{
+    headers: Record<string, string>;
+    source: AuthSource;
+}>;