@quickchatai/quickreview 0.0.0-stage → 1.1.0

package/dist/src/github.js

@@ -0,0 +1,1063 @@
+// The GitHub adapter. Reads run directly on the installation token; every
+// mutation is expressed as a MutationIntent and pushed through the gate
+// (dry-run writes it to state/dryrun/ instead of executing). There is no
+// review-dismissal function in this adapter, by design — never add one.
+import { GitHubRequestError, } from "@quickchatai/pi-quickreview/src/githubcore.js";
+import { ThreadResolutionRefusal } from "./thread-resolution-refusal.js";
+import { reviewTeamSlug } from "./config.js";
+import { CHECK_THIS_RE, DEFERRED_RE } from "@quickchatai/pi-quickreview/src/severity.js";
+import { APP_SELF_CONFIG_KINDS, } from "@quickchatai/pi-quickreview/src/gate.js";
+import { appActorAlias, GITHUB_REQUEST_TIMEOUT_MS, } from "@quickchatai/pi-quickreview/src/githubAuth.js";
+/** A pulls-endpoint PR as a `PrRef`. `merged` is the caller's: the single-PR
+ * read carries it, the open-PR list does not. */
+function toPrRef(pr, merged) {
+    return {
+        number: pr.number,
+        title: pr.title,
+        author: pr.user.login,
+        head_sha: pr.head.sha,
+        base_ref: pr.base?.ref ?? "",
+        body: pr.body ?? "",
+        updated_at: pr.updated_at,
+        state: pr.state,
+        draft: pr.draft,
+        merged,
+        labels: (pr.labels ?? []).map((l) => l.name),
+    };
+}
+function toReviewCommentFull(c) {
+    return {
+        id: c.id,
+        user: c.user?.login ?? "",
+        user_type: c.user?.type ?? "User",
+        body: c.body ?? "",
+        path: c.path ?? "",
+        line: c.line ?? c.original_line ?? null,
+        pull_request_review_id: c.pull_request_review_id ?? null,
+        in_reply_to_id: c.in_reply_to_id ?? null,
+        created_at: c.created_at ?? null,
+        original_line: c.original_line ?? null,
+    };
+}
+/** How many newest-first pages `listRecentReviewComments` reads to reach the
+ * comment a lost reply answered. */
+const RECENT_COMMENTS_MAX_PAGES = 10;
+/** GitHub search serves at most 1,000 hits: ten pages of 100. */
+const TRIGGER_SEARCH_MAX_PAGES = 10;
+/** The trigger events the history importer reconstructs — one list for the
+ * first query and every follow-up page. */
+const HISTORY_TIMELINE_TYPES = "[LABELED_EVENT, REVIEW_REQUESTED_EVENT, HEAD_REF_FORCE_PUSHED_EVENT]";
+/** Hard stop for a connection walk — a server that keeps answering
+ * hasNextPage with a cursor that never ends cannot loop forever. */
+const MAX_CONNECTION_PAGES = 50;
+/** Every node of a connection: the first page as already fetched, then each
+ * `next(cursor)` until GitHub says there is no next page. A connection still
+ * going after `MAX_CONNECTION_PAGES` throws rather than answer a partial
+ * history as the whole of it. */
+async function walkConnection(first, next) {
+    const out = [];
+    let conn = first;
+    for (let page = 1; conn; page++) {
+        out.push(...(conn.nodes ?? []).filter((n) => n !== null && n !== undefined));
+        const info = conn.pageInfo;
+        if (!info?.hasNextPage || !info.endCursor)
+            break;
+        if (page >= MAX_CONNECTION_PAGES)
+            throw new Error(`connection exceeded ${MAX_CONNECTION_PAGES} pages — history would be partial`);
+        conn = await next(info.endCursor);
+    }
+    return out;
+}
+/** Selection sets shared by a history query's first page and its follow-ups,
+ * so the two can never request different fields. */
+const HISTORY_REVIEWS_BODY = "pageInfo { hasNextPage endCursor } nodes { databaseId state submittedAt body commit { oid } }";
+const HISTORY_TIMELINE_BODY = `pageInfo { hasNextPage endCursor }
+              nodes {
+                __typename
+                ... on LabeledEvent { createdAt label { name } actor { login } }
+                ... on ReviewRequestedEvent { createdAt requestedReviewer { ... on Team { slug } ... on User { login } } }
+                ... on HeadRefForcePushedEvent { createdAt }
+              }`;
+const DIGEST_COMMENTS_BODY = "pageInfo { hasNextPage endCursor } nodes { author { __typename login } path body }";
+const DIGEST_REVIEWS_BODY = `pageInfo { hasNextPage endCursor }
+              nodes {
+                id author { __typename login } state submittedAt body
+                comments(first: 100) { ${DIGEST_COMMENTS_BODY} }
+              }`;
+/** GitHub serves a compare's changed files on its first page only, capped at
+ * this many. A list that long is a floor, not the delta. */
+export const COMPARE_FILES_CAP = 300;
+/** GitHub serves at most this many pages of 100 from `pulls/<n>/files`. */
+const PR_FILES_MAX_PAGES = 30;
+// The error a refused request throws is the review core's (packages/pi-plugin/src/githubcore.ts).
+export { GitHubRequestError };
+/** A response body as UTF-8 text, at most `max` bytes of it, read as a stream so
+ * a large log never sits in memory whole: the first `max` bytes, or with `tail`
+ * the last. A cut that splits a character loses that character only. */
+export async function cappedText(res, max, tail) {
+    if (res.body === null)
+        return { text: "", truncated: false };
+    const chunks = [];
+    let held = 0;
+    let truncated = false;
+    const reader = res.body.getReader();
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        let chunk = Buffer.from(value);
+        if (!tail) {
+            if (held + chunk.length > max) {
+                chunk = chunk.subarray(0, max - held);
+                truncated = true;
+            }
+            chunks.push(chunk);
+            held += chunk.length;
+            if (truncated) {
+                await reader.cancel().catch(() => { });
+                break;
+            }
+            continue;
+        }
+        chunks.push(chunk);
+        held += chunk.length;
+        while (held > max && chunks.length > 0) {
+            truncated = true;
+            const first = chunks[0];
+            const over = held - max;
+            if (first.length <= over) {
+                chunks.shift();
+                held -= first.length;
+            }
+            else {
+                chunks[0] = first.subarray(over);
+                held -= over;
+            }
+        }
+    }
+    return { text: Buffer.concat(chunks).toString("utf8"), truncated };
+}
+/** One files-API entry (pulls/files and compare share the shape). */
+function fileEntry(f) {
+    return {
+        filename: f.filename,
+        additions: f.additions,
+        deletions: f.deletions,
+        status: f.status,
+        ...(typeof f.patch === "string" ? { patch: f.patch } : {}),
+        ...(typeof f.previous_filename === "string" ? { previous_filename: f.previous_filename } : {}),
+    };
+}
+export class GitHubAdapter {
+    cfg;
+    minter;
+    gate;
+    fetchFn;
+    apiBase;
+    owner;
+    repo;
+    constructor(cfg, minter, gate, fetchFn = fetch, apiBase = "https://api.github.com") {
+        this.cfg = cfg;
+        this.minter = minter;
+        this.gate = gate;
+        this.fetchFn = fetchFn;
+        this.apiBase = apiBase;
+        const [owner, repo] = cfg.github.repo.split("/");
+        if (!owner || !repo)
+            throw new Error(`bad repo: ${cfg.github.repo}`);
+        this.owner = owner;
+        this.repo = repo;
+    }
+    // ---- plumbing ----------------------------------------------------------
+    async request(method, path, body, auth = "installation") {
+        const send = (token) => this.fetchFn(`${this.apiBase}${path}`, {
+            method,
+            signal: AbortSignal.timeout(GITHUB_REQUEST_TIMEOUT_MS),
+            headers: {
+                authorization: `Bearer ${token}`,
+                accept: "application/vnd.github+json",
+                "x-github-api-version": "2022-11-28",
+                ...(body !== undefined ? { "content-type": "application/json" } : {}),
+            },
+            body: body !== undefined ? JSON.stringify(body) : undefined,
+        });
+        const res = auth === "jwt" ? await send(this.minter.appJwt()) : await this.sendInstallation(send);
+        if (!res.ok) {
+            const retryAfter = res.headers?.get("retry-after");
+            const reset = res.headers?.get("x-ratelimit-reset");
+            const retryAfterMs = retryAfter
+                ? /^\d+$/.test(retryAfter)
+                    ? Number(retryAfter) * 1000
+                    : Math.max(0, Date.parse(retryAfter) - Date.now())
+                : reset
+                    ? Math.max(0, Number(reset) * 1000 - Date.now())
+                    : undefined;
+            throw new GitHubRequestError(method, path, res.status, (await res.text()).slice(0, 300), Number.isFinite(retryAfterMs) ? retryAfterMs : undefined);
+        }
+        if (res.status === 204)
+            return undefined;
+        return (await res.json());
+    }
+    /** Send with an installation token; on a 401 drop the rejected response
+     * body, invalidate the cached token and send once more with a fresh one.
+     * The one owner of the installation-token 401 policy. */
+    async sendInstallation(send) {
+        let res = await send(await this.minter.installationToken());
+        if (res.status === 401) {
+            await res.body?.cancel().catch(() => { });
+            this.minter.invalidate();
+            res = await send(await this.minter.installationToken());
+        }
+        return res;
+    }
+    graphqlFetch(token, query, variables) {
+        return this.fetchFn(`${this.apiBase}/graphql`, {
+            method: "POST",
+            signal: AbortSignal.timeout(GITHUB_REQUEST_TIMEOUT_MS),
+            headers: { authorization: `Bearer ${token}`, "content-type": "application/json" },
+            body: JSON.stringify({ query, variables }),
+        });
+    }
+    /** One GraphQL query, with REST's deadline and its one re-mint on a 401. */
+    async graphql(query, variables) {
+        const res = await this.sendInstallation((token) => this.graphqlFetch(token, query, variables));
+        if (!res.ok) {
+            let detail = "";
+            try {
+                detail = (await res.text()).slice(0, 300);
+            }
+            catch {
+                // No readable body: the status alone.
+            }
+            throw new Error(`graphql → ${res.status}${detail ? `: ${detail}` : ""}`);
+        }
+        const payload = (await res.json());
+        if (payload.errors?.length)
+            throw new Error(`graphql errors: ${JSON.stringify(payload.errors).slice(0, 300)}`);
+        return payload.data;
+    }
+    /**
+     * A session helper's read, served by the daemon (src/ghread.ts): one
+     * GET of `path` with the installation token, redirects followed (fetch drops
+     * the Authorization header on a cross-origin hop, which is what the Actions
+     * log storage wants), answered as GitHub answered it — the status and at most
+     * `maxBytes` of the body as text, the head or, with `tail`, the end. An HTTP
+     * error status is an answer, not a throw; only a request that never got one
+     * throws. The caller has already checked `path` is a read of the reviewed repo.
+     */
+    async readText(path, o) {
+        return this.rawAnswer(o, (token) => this.fetchFn(`${this.apiBase}${path}`, {
+            method: "GET",
+            redirect: "follow",
+            signal: AbortSignal.timeout(GITHUB_REQUEST_TIMEOUT_MS),
+            headers: {
+                authorization: `Bearer ${token}`,
+                accept: "application/vnd.github+json",
+                "x-github-api-version": "2022-11-28",
+            },
+        }));
+    }
+    /** The same for one GraphQL read: the caller supplies a query it holds itself
+     * (src/ghread.ts GH_READ_QUERIES), never one a session wrote. */
+    async graphqlText(query, variables, o) {
+        return this.rawAnswer(o, (token) => this.graphqlFetch(token, query, variables));
+    }
+    /** One raw request with REST's one re-mint on a 401, its body capped. */
+    async rawAnswer(o, send) {
+        const res = await this.sendInstallation(send);
+        const { text, truncated } = await cappedText(res, o.maxBytes, o.tail === true);
+        return { status: res.status, body: text, truncated };
+    }
+    /** The mutation executor the gate runs when it decides a mutation is real —
+     * every kind in live mode, and the app-self-config class in dry-run too.
+     * The gate, never a call site, makes that decision. */
+    executeMutation = async (intent) => {
+        if (intent.method === "git")
+            throw new Error("git pushes are executed by the caller, not the REST executor");
+        if (intent.path === "/graphql") {
+            const body = intent.body;
+            if (typeof body?.query !== "string" ||
+                typeof body.variables !== "object" ||
+                body.variables === null) {
+                throw new Error(`invalid GraphQL mutation intent for ${intent.kind}`);
+            }
+            return this.graphql(body.query, body.variables);
+        }
+        // App-self-config intents address the App's own configuration:
+        // GitHub authenticates those routes with the App JWT, not an installation
+        // token — the same auth split request() already carries for the
+        // /app/hook/deliveries read.
+        const auth = APP_SELF_CONFIG_KINDS.includes(intent.kind)
+            ? "jwt"
+            : "installation";
+        return this.request(intent.method, intent.path, intent.body, auth);
+    };
+    // ---- triggered-set queries (reads) -------------------------------------
+    /** One page of issue search (100 hits). GitHub's search may time out and
+     * answer a partial set; absence read from it would be invented, so the read
+     * fails with `incompleteMessage` rather than answers. */
+    async searchIssuePage(q, page, incompleteMessage) {
+        const res = await this.request("GET", `/search/issues?q=${encodeURIComponent(q)}&per_page=100&page=${page}`);
+        if (res.incomplete_results === true)
+            throw new Error(incompleteMessage);
+        return res.items ?? [];
+    }
+    /** Every hit, not the first 100: the reconcile pass reads a PR missing from
+     * this list as trigger-ABSENT, so a truncated page would fake an absent →
+     * present edge the moment search order reshuffled it back in. */
+    async searchIssues(q) {
+        const out = [];
+        for (let page = 1; page <= TRIGGER_SEARCH_MAX_PAGES; page++) {
+            const items = await this.searchIssuePage(q, page, `trigger search "${q}" answered incomplete results`);
+            out.push(...items);
+            if (items.length < 100)
+                return out;
+        }
+        throw new Error(`trigger search "${q}" exceeded ${TRIGGER_SEARCH_MAX_PAGES} pages`);
+    }
+    /** Every page of a list endpoint that answers a bare JSON array. `path`
+     * carries `per_page=100`; a short page ends the read and `maxPages` bounds
+     * it — `truncated` says the bound, not the list, ended it. */
+    async pagedArray(path, maxPages = 30) {
+        const rows = [];
+        for (let page = 1; page <= maxPages; page++) {
+            const batch = await this.request("GET", `${path}&page=${page}`);
+            rows.push(...batch);
+            if (batch.length < 100)
+                return { rows, truncated: false };
+        }
+        return { rows, truncated: true };
+    }
+    /** Paginated issue search — read-only, used by the history importer.
+     * Stops on a short page or after `maxPages` (search caps at 1,000 hits). */
+    async searchIssuesPaged(q, maxPages = 10) {
+        const out = [];
+        for (let page = 1; page <= maxPages; page++) {
+            const items = await this.searchIssuePage(q, page, "incomplete history search results");
+            out.push(...items);
+            if (items.length < 100)
+                break;
+        }
+        return out;
+    }
+    /** Read-only GraphQL per PR: the reviews `author` submitted plus the
+     * timeline items the backfill importer reconstructs triggers from — one
+     * query, then one more per further page of either connection. Returns null
+     * when the PR is gone. */
+    async prReviewHistory(n, author) {
+        const data = await this.graphql(`query ($owner: String!, $repo: String!, $number: Int!, $author: String!) {
+        repository(owner: $owner, name: $repo) {
+          pullRequest(number: $number) {
+            number title createdAt closedAt mergedAt merged
+            author { login }
+            reviews(author: $author, first: 100) { ${HISTORY_REVIEWS_BODY} }
+            timelineItems(itemTypes: ${HISTORY_TIMELINE_TYPES}, first: 100) { ${HISTORY_TIMELINE_BODY} }
+          }
+        }
+      }`, { owner: this.owner, repo: this.repo, number: n, author });
+        const pr = data.repository?.pullRequest;
+        if (!pr)
+            return null;
+        // A long PR's bot reviews run past 100 (every thread reply is a review):
+        // follow the cursors, or the importer silently loses the NEWEST ones.
+        const vars = { owner: this.owner, repo: this.repo, number: n, author };
+        const reviews = await walkConnection(pr.reviews, async (after) => {
+            const d = await this.graphql(`query ($owner: String!, $repo: String!, $number: Int!, $author: String!, $after: String!) {
+          repository(owner: $owner, name: $repo) {
+            pullRequest(number: $number) {
+              reviews(author: $author, first: 100, after: $after) { ${HISTORY_REVIEWS_BODY} }
+            }
+          }
+        }`, { ...vars, after });
+            return d.repository?.pullRequest?.reviews;
+        });
+        const timeline = await walkConnection(pr.timelineItems, async (after) => {
+            const d = await this.graphql(`query ($owner: String!, $repo: String!, $number: Int!, $after: String!) {
+          repository(owner: $owner, name: $repo) {
+            pullRequest(number: $number) {
+              timelineItems(itemTypes: ${HISTORY_TIMELINE_TYPES}, first: 100, after: $after) { ${HISTORY_TIMELINE_BODY} }
+            }
+          }
+        }`, { owner: this.owner, repo: this.repo, number: n, after });
+            return d.repository?.pullRequest?.timelineItems;
+        });
+        return {
+            number: pr.number ?? n,
+            title: pr.title ?? "",
+            author: pr.author?.login ?? "",
+            created_at: pr.createdAt ?? "",
+            closed_at: pr.closedAt ?? null,
+            merged_at: pr.mergedAt ?? null,
+            merged: Boolean(pr.merged),
+            reviews: reviews.map((r) => ({
+                database_id: r.databaseId ?? 0,
+                state: r.state ?? "",
+                submitted_at: r.submittedAt ?? null,
+                body: r.body ?? "",
+                commit_oid: r.commit?.oid ?? null,
+            })),
+            timeline: timeline
+                .filter((t) => Boolean(t.createdAt))
+                .map((t) => ({
+                type: t.__typename ?? "",
+                created_at: t.createdAt,
+                label: t.label?.name ?? null,
+                actor: t.actor?.login ?? null,
+                requested_team: t.requestedReviewer?.slug ?? null,
+                requested_user: t.requestedReviewer?.login ?? null,
+            })),
+        };
+    }
+    /** Read-only GraphQL per PR for the review history digest: every author's
+     * reviews, each with its inline comments, and the author's type so the
+     * digest can keep people and drop Apps — one query, then one more per
+     * further page of reviews or of one review's comments. Returns null when
+     * the PR is gone. */
+    async prReviews(n) {
+        const data = await this.graphql(`query ($owner: String!, $repo: String!, $number: Int!) {
+        repository(owner: $owner, name: $repo) {
+          pullRequest(number: $number) {
+            number title mergedAt
+            author { login }
+            reviews(first: 100) { ${DIGEST_REVIEWS_BODY} }
+          }
+        }
+      }`, { owner: this.owner, repo: this.repo, number: n });
+        const pr = data.repository?.pullRequest;
+        if (!pr)
+            return null;
+        // Reviews come oldest-first, so a truncated read drops the NEWEST human
+        // feedback — follow the cursors, and each long review's comment cursor.
+        const rawReviews = await walkConnection(pr.reviews, async (after) => {
+            const d = await this.graphql(`query ($owner: String!, $repo: String!, $number: Int!, $after: String!) {
+          repository(owner: $owner, name: $repo) {
+            pullRequest(number: $number) {
+              reviews(first: 100, after: $after) { ${DIGEST_REVIEWS_BODY} }
+            }
+          }
+        }`, { owner: this.owner, repo: this.repo, number: n, after });
+            return d.repository?.pullRequest?.reviews;
+        });
+        const commentsOf = (r) => walkConnection(r.comments, async (after) => {
+            if (!r.id)
+                return null;
+            const d = await this.graphql(`query ($id: ID!, $after: String!) {
+            node(id: $id) { ... on PullRequestReview { comments(first: 100, after: $after) { ${DIGEST_COMMENTS_BODY} } } }
+          }`, { id: r.id, after });
+            return d.node?.comments;
+        });
+        const reviews = [];
+        for (const r of rawReviews)
+            reviews.push({ r, comments: await commentsOf(r) });
+        const author = (a) => a ? { login: a.login ?? "", type: a.__typename ?? "" } : null;
+        return {
+            number: pr.number ?? n,
+            title: pr.title ?? "",
+            author: pr.author?.login ?? "",
+            merged_at: pr.mergedAt ?? null,
+            reviews: reviews.map(({ r, comments }) => ({
+                author: author(r.author),
+                state: r.state ?? "",
+                submitted_at: r.submittedAt ?? null,
+                body: r.body ?? "",
+                comments: comments.map((c) => ({
+                    author: author(c.author),
+                    path: c.path ?? null,
+                    body: c.body ?? "",
+                })),
+            })),
+        };
+    }
+    /** PRs carrying the trigger label. Bot-authored PRs are excluded — the app
+     * can never approve its own PRs. */
+    async searchLabelTriggered() {
+        const q = `repo:${this.cfg.github.repo} is:open is:pr label:"${this.cfg.github.trigger_label}" -author:app/${this.cfg.github.app_slug}`;
+        return this.searchIssues(q);
+    }
+    /** PRs with a pending review-team request. */
+    async searchTeamTriggered() {
+        const q = `repo:${this.cfg.github.repo} is:open is:pr team-review-requested:${this.cfg.github.review_team} -author:app/${this.cfg.github.app_slug}`;
+        return this.searchIssues(q);
+    }
+    // ---- authoritative per-PR reads ----------------------------------------
+    async getPr(n) {
+        const pr = await this.request("GET", `/repos/${this.owner}/${this.repo}/pulls/${n}`);
+        return toPrRef(pr, Boolean(pr.merged));
+    }
+    /** Authoritative terminality read for operator debt cleanup. A PR-endpoint
+     * 404 is not enough by itself: GitHub also conceals inaccessible private
+     * repositories as 404. Absence therefore requires a second installation-
+     * authenticated read proving access to this exact repository. */
+    async getPrDisposition(n) {
+        const path = `/repos/${this.owner}/${this.repo}/pulls/${n}`;
+        try {
+            const raw = await this.request("GET", path);
+            if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+                throw new Error(`malformed PR #${n} response`);
+            }
+            const pr = raw;
+            if (pr.number !== n)
+                throw new Error(`PR endpoint #${n} returned number ${String(pr.number)}`);
+            if (pr.state !== "open" && pr.state !== "closed")
+                throw new Error(`unexpected PR #${n} state ${String(pr.state)}`);
+            const head = pr.head?.sha;
+            if (typeof head !== "string" || head.length === 0)
+                throw new Error(`malformed PR #${n} head sha`);
+            return { kind: pr.state, head_sha: head };
+        }
+        catch (error) {
+            if (!(error instanceof GitHubRequestError &&
+                error.method === "GET" &&
+                error.path === path &&
+                error.status === 404))
+                throw error;
+            const repoPath = `/repos/${this.owner}/${this.repo}`;
+            const rawRepo = await this.request("GET", repoPath);
+            if (typeof rawRepo !== "object" || rawRepo === null || Array.isArray(rawRepo)) {
+                throw new Error(`malformed repository proof for ${this.owner}/${this.repo}`, {
+                    cause: error,
+                });
+            }
+            const fullName = rawRepo.full_name;
+            const expected = `${this.owner}/${this.repo}`;
+            if (typeof fullName !== "string" || fullName.toLowerCase() !== expected.toLowerCase()) {
+                throw new Error(`repository proof mismatch for ${expected}`, { cause: error });
+            }
+            return { kind: "absent" };
+        }
+    }
+    /** Read-only conversation surface for the TUI detail pane:
+     * PR description, labels, and the newest issue comments, oldest-first.
+     *
+     * The per-issue comments endpoint ignores `sort`/`direction` (those belong
+     * to the repo-wide listing) and always answers oldest-first, so the newest
+     * comments are on the LAST page: its index comes off the PR's own comment
+     * count, and the page before it is read too when the last one is short. */
+    async prConversation(n, commentCount = 3) {
+        const pr = await this.request("GET", `/repos/${this.owner}/${this.repo}/pulls/${n}`);
+        const path = `/repos/${this.owner}/${this.repo}/issues/${n}/comments?per_page=100`;
+        let comments;
+        if (typeof pr.comments === "number") {
+            const last = Math.max(1, Math.ceil(pr.comments / 100));
+            comments = await this.request("GET", `${path}&page=${last}`);
+            if (comments.length < commentCount && last > 1)
+                comments = [...(await this.request("GET", `${path}&page=${last - 1}`)), ...comments];
+        }
+        else {
+            comments = (await this.pagedArray(path)).rows;
+        }
+        return {
+            body: pr.body ?? "",
+            labels: (pr.labels ?? []).map((l) => l.name),
+            comments: comments.slice(-commentCount).map((c) => ({
+                author: c.user?.login ?? "?",
+                body: c.body ?? "",
+                created_at: c.created_at ?? "",
+            })),
+        };
+    }
+    /** EVERY open PR: the list is newest-first, so a first-page read drops the
+     * oldest tracked PRs out of reconcile step 1 entirely. */
+    async listOpenPrs() {
+        const { rows: prs, truncated } = await this.pagedArray(`/repos/${this.owner}/${this.repo}/pulls?state=open&per_page=100`);
+        // A PR past the bound would silently miss every head refresh: a partial
+        // list fails the read instead.
+        if (truncated)
+            throw new Error("open PRs exceeded the pagination bound");
+        // An open PR is not merged; the list endpoint does not carry `merged`.
+        return prs.map((pr) => toPrRef(pr, false));
+    }
+    async getRequestedReviewers(n) {
+        const res = await this.request("GET", `/repos/${this.owner}/${this.repo}/pulls/${n}/requested_reviewers`);
+        return { users: res.users.map((u) => u.login), teams: res.teams.map((t) => t.slug) };
+    }
+    /** Every file GitHub will list for the PR (it serves 3,000 at most). A list
+     * that reaches that cap is flagged `truncated`: it is a floor, and ownership
+     * decisions made off it must not treat a missing file as not-the-PR's. */
+    async listPrFiles(n) {
+        const { rows, truncated } = await this.pagedArray(`/repos/${this.owner}/${this.repo}/pulls/${n}/files?per_page=100`, PR_FILES_MAX_PAGES);
+        const out = rows.map(fileEntry);
+        if (truncated)
+            out.truncated = true;
+        return out;
+    }
+    /**
+     * Files a commit range changed (`GET /compare/<base>...<head>`) — the delta
+     * source for the post-approval recheck. Read-only. GitHub serves
+     * the files on the FIRST page only (later pages page the commits) and caps
+     * them at COMPARE_FILES_CAP, so a list that long is flagged `truncated`: the
+     * classifier must not read an unseen remainder as "nothing PR-owned".
+     * A behind/diverged comparison is merge-base-relative rather than the two
+     * reviewed trees; it also cannot prove an empty post-approval delta.
+     */
+    async compareFiles(base, head) {
+        const res = await this.request("GET", `/repos/${this.owner}/${this.repo}/compare/${encodeURIComponent(base)}...${encodeURIComponent(head)}?per_page=100&page=1`);
+        const files = res.files ?? [];
+        const out = files.map(fileEntry);
+        if (files.length >= COMPARE_FILES_CAP || res.status === "behind" || res.status === "diverged")
+            out.truncated = true;
+        return out;
+    }
+    /**
+     * Checks at a ref — check-runs plus the legacy commit statuses, since a repo
+     * can gate on either (guard 4). Read-only: CI is consulted, never
+     * triggered or re-run. Both endpoints are paginated the way listPrFiles is:
+     * guard 4 classifies what it is handed, so a failing or pending check past
+     * the first 100 rows must reach it, or a truncated list reads green.
+     */
+    async listChecks(ref) {
+        const out = [];
+        const enc = encodeURIComponent(ref);
+        const runs = await this.completeCheckPages(`/repos/${this.owner}/${this.repo}/commits/${enc}/check-runs`, "check_runs");
+        for (const r of runs)
+            out.push({
+                name: r.name ?? "check",
+                source: "check_run",
+                status: r.status ?? "",
+                conclusion: r.conclusion ?? null,
+                started_at: r.started_at ?? null,
+            });
+        const statuses = await this.completeCheckPages(`/repos/${this.owner}/${this.repo}/commits/${enc}/status`, "statuses");
+        for (const s of statuses)
+            out.push({
+                name: s.context ?? "status",
+                source: "status",
+                status: s.state === "pending" ? "pending" : "completed",
+                conclusion: s.state === "pending" ? null : s.state === "success" ? "success" : "failure",
+            });
+        return out;
+    }
+    /** Complete CI evidence, or an unreadable result that callers classify unknown. */
+    async completeCheckPages(path, field) {
+        const rows = [];
+        let expected;
+        for (let page = 1; page <= 10; page++) {
+            const result = await this.request("GET", `${path}?per_page=100&page=${page}`);
+            const count = result.total_count;
+            if (count !== undefined) {
+                if (typeof count !== "number" || !Number.isInteger(count) || count < 0)
+                    throw new Error(`unreadable ${field} total_count`);
+                if (expected !== undefined && expected !== count)
+                    throw new Error(`incomplete ${field}: count changed while reading`);
+                expected = count;
+            }
+            const batch = result[field];
+            if (!Array.isArray(batch))
+                throw new Error(`unreadable ${field} page`);
+            rows.push(...batch);
+            if (expected !== undefined && rows.length > expected)
+                throw new Error(`incomplete ${field}: rows exceed advertised count`);
+            if (batch.length < 100 || (expected !== undefined && rows.length === expected)) {
+                if (expected !== undefined && rows.length !== expected)
+                    throw new Error(`incomplete ${field}: advertised count not reached`);
+                return rows;
+            }
+        }
+        throw new Error(`incomplete ${field}: page limit reached`);
+    }
+    async listReviews(n) {
+        // Every page, with no page bound: reviews are oldest-first and every
+        // thread reply is one, so on a long PR the human approval at the head is
+        // exactly what a bounded read misses — and guard 1 would then not soften
+        // over it. A short page ends the read, as for listReviewsFull.
+        return (await this.listReviewsFull(n)).map((r) => ({
+            id: r.id,
+            user: r.user,
+            state: r.state,
+            commit_id: r.commit_id,
+        }));
+    }
+    /** Full review rows (bodies included) — read-only, for compare and
+     * posting-marker reconciliation. Paginated so long-lived PRs cannot hide the
+     * accepted review beyond the first 100 rows. */
+    async listReviewsFull(n) {
+        const { rows } = await this.pagedArray(`/repos/${this.owner}/${this.repo}/pulls/${n}/reviews?per_page=100`, Number.POSITIVE_INFINITY);
+        return rows.map((r) => ({
+            id: r.id,
+            user: r.user?.login ?? "",
+            user_type: r.user?.type ?? "User",
+            state: r.state,
+            body: r.body ?? "",
+            commit_id: r.commit_id,
+            submitted_at: r.submitted_at ?? null,
+        }));
+    }
+    /** Top-level PR conversation comments — read-only, the feedback capture
+     * sweep's third source (the issues API is where GitHub keeps them). */
+    async listIssueComments(n) {
+        const { rows: res, truncated } = await this.pagedArray(`/repos/${this.owner}/${this.repo}/issues/${n}/comments?per_page=100`);
+        // A conversation retry must not read a partial list as proof that its
+        // earlier POST did not land. Capture callers already treat failure as unknown.
+        if (truncated)
+            throw new Error(`issue comments on #${n} exceeded the pagination bound`);
+        return res.map((c) => ({
+            id: c.id,
+            user: c.user?.login ?? "",
+            user_type: c.user?.type ?? "User",
+            body: c.body ?? "",
+            created_at: c.created_at ?? null,
+        }));
+    }
+    /** Every inline review comment, oldest first — read-only: the reconcile
+     * comment sweep, the case writer's backfill, the compare harness. A list
+     * past the pagination bound throws rather than answer its oldest part as
+     * the whole: a sweep that read a partial list would stamp its watermark and
+     * never look for the newer comments again. */
+    async listReviewCommentsFull(n) {
+        const { rows: res, truncated } = await this.pagedArray(`/repos/${this.owner}/${this.repo}/pulls/${n}/comments?per_page=100`);
+        if (truncated)
+            throw new Error(`inline comments on #${n} exceeded the pagination bound`);
+        return res.map(toReviewCommentFull);
+    }
+    /** The NEWEST inline review comments, newest first — read-only. The
+     * ping-pong retry path reads this to learn whether a reply whose POST
+     * response was lost actually landed, so the newest comments are the ones
+     * it needs. With `newerThan`, pages continue until one reaches a comment at
+     * or below that id (ids grow with creation, so every comment created after
+     * it has then been read) — or throw past `RECENT_COMMENTS_MAX_PAGES`, never
+     * answer a window that may have missed the reply. Without it, one page. */
+    async listRecentReviewComments(n, newerThan) {
+        const out = [];
+        for (let page = 1; page <= RECENT_COMMENTS_MAX_PAGES; page++) {
+            const res = await this.request("GET", `/repos/${this.owner}/${this.repo}/pulls/${n}/comments?sort=created&direction=desc&per_page=100&page=${page}`);
+            out.push(...res.map(toReviewCommentFull));
+            if (newerThan === undefined || res.length < 100)
+                return out;
+            if (res.some((c) => typeof c.id === "number" && c.id <= newerThan))
+                return out;
+        }
+        throw new Error(`inline comments on #${n} newer than ${newerThan} exceeded ${RECENT_COMMENTS_MAX_PAGES} pages`);
+    }
+    /** Review comments the bot authored on a PR — the registry backfill source.
+     * Read newest first, so a PR past the page bound loses its OLDEST comments
+     * (registered by earlier passes), never the newest. */
+    async listBotReviewComments(n) {
+        const { rows: res } = await this.pagedArray(`/repos/${this.owner}/${this.repo}/pulls/${n}/comments?sort=created&direction=desc&per_page=100`);
+        return res.filter((c) => c.user?.login === this.cfg.github.bot_login).map((c) => c.id);
+    }
+    // ---- staleness scan (GraphQL) -------------------------------------------
+    /** Open PRs whose latest bot APPROVED review no longer matches the head:
+     * `first: 100`, `UPDATED_AT DESC`, review author the configured
+     * `[github] bot_login`. */
+    async stalenessScan() {
+        const q = `repo:${this.cfg.github.repo} is:pr is:open sort:updated-desc`;
+        const data = await this.graphql(`query ($q: String!, $author: String!) {
+        search(query: $q, type: ISSUE, first: 100) {
+          nodes {
+            ... on PullRequest {
+              number
+              headRefOid
+              reviews(author: $author, states: [APPROVED], last: 1) {
+                nodes { state submittedAt commit { oid } }
+              }
+            }
+          }
+        }
+      }`, { q, author: this.cfg.github.bot_login });
+        const stale = [];
+        for (const node of data.search.nodes) {
+            if (!node.number || !node.headRefOid)
+                continue;
+            const review = node.reviews?.nodes?.[0];
+            if (!review?.commit)
+                continue;
+            if (review.commit.oid !== node.headRefOid) {
+                stale.push({
+                    number: node.number,
+                    head_sha: node.headRefOid,
+                    approved_sha: review.commit.oid,
+                    approved_at: review.submittedAt,
+                });
+            }
+        }
+        return stale;
+    }
+    // ---- webhook redeliveries (JWT) ----------------------------------------
+    async listWebhookDeliveries(perPage = 100) {
+        return this.request("GET", `/app/hook/deliveries?per_page=${perPage}`, undefined, "jwt");
+    }
+    // ---- the App's own webhook configuration -------------------------------
+    /** The App's own webhook config — the self-heal's read-back source. Direct
+     * JWT read, like the deliveries listing above. */
+    async getAppWebhookConfig() {
+        const res = await this.request("GET", "/app/hook/config", undefined, "jwt");
+        return {
+            url: res.url ?? "",
+            content_type: res.content_type ?? "",
+            insecure_ssl: res.insecure_ssl ?? "",
+        };
+    }
+    /**
+     * Re-point the App's OWN webhook URL (`PATCH /app/hook/config`, JWT-authed).
+     * The one member of the app-self-config gate class (AGENTS.md invariant 6): it
+     * touches only the App's own
+     * configuration, never the reviewed repo, and the gate executes it for real
+     * even in dry-run — loudly logged, with the note naming old and new URL.
+     */
+    async updateOwnWebhookUrl(newUrl, oldUrl) {
+        return this.gate.execute({
+            kind: "update_own_webhook_url",
+            method: "PATCH",
+            path: "/app/hook/config",
+            body: { url: newUrl },
+            note: `re-point own App webhook URL ${oldUrl || "(unknown)"} → ${newUrl}`,
+        });
+    }
+    // ---- mutations (all through the gate) ----------------------------------
+    async addLabel(n, label) {
+        return this.gate.execute({
+            kind: "add_label",
+            method: "POST",
+            path: `/repos/${this.owner}/${this.repo}/issues/${n}/labels`,
+            body: { labels: [label] },
+            note: `add label "${label}" to #${n}`,
+            pr: n,
+        });
+    }
+    async removeLabel(n, label) {
+        try {
+            return await this.gate.execute({
+                kind: "remove_label",
+                method: "DELETE",
+                path: `/repos/${this.owner}/${this.repo}/issues/${n}/labels/${encodeURIComponent(label)}`,
+                note: `remove label "${label}" from #${n}`,
+                pr: n,
+            });
+        }
+        catch (err) {
+            // Removing an already-absent label is the outcome we wanted — GitHub's
+            // 404 ("Label does not exist") is idempotent success, not an error —
+            // e.g. a label consumed by an earlier failed-dispatch cycle.
+            if (err instanceof GitHubRequestError && err.status === 404)
+                return { executed: false, response: { already_absent: label } };
+            throw err;
+        }
+    }
+    /** Consume the team trigger: DELETE with the JSON body, then verify. */
+    async deleteTeamReviewRequest(n) {
+        const teamSlug = reviewTeamSlug(this.cfg.github.review_team);
+        const result = await this.gate.execute({
+            kind: "delete_team_review_request",
+            method: "DELETE",
+            path: `/repos/${this.owner}/${this.repo}/pulls/${n}/requested_reviewers`,
+            body: { reviewers: [], team_reviewers: [teamSlug] },
+            note: `clear team review request (${teamSlug}) on #${n}`,
+            pr: n,
+        });
+        if (result.executed) {
+            const after = await this.getRequestedReviewers(n);
+            if (after.teams.includes(teamSlug))
+                throw new Error(`team request on #${n} survived DELETE`);
+        }
+        return result;
+    }
+    /**
+     * Put named people in this PR's review-requested queue — the second
+     * delivery shape of the optional escalation feature (the never-hand-to-a-human rule), an
+     * ordinary gated mutation.
+     *
+     * Three things this is not:
+     *   * It is not a way to hand the review back. `src/escalation.ts` calls it
+     *     only after the round's verdict has been decided and applied, and only
+     *     alongside a comment that names the ONE thing being asked about —
+     *     GitHub words the queue entry "review this pull request", which is
+     *     exactly the framing the comment exists to correct.
+     *   * It is not a dry-run exception. `request_reviewer` is an ordinary
+     *     `MutationKind`: suppressed to `state/dryrun/` like everything else,
+     *     `forceLive` throws on it, and it is not in `APP_SELF_CONFIG_KINDS`.
+     *   * It is not review-dismissing. Rule 2 is untouched; requesting a review
+     *     adds a reviewer and changes no existing review.
+     *
+     * Needs no new App permission: this is a POST on the same
+     * `/pulls/{n}/requested_reviewers` route the team-request DELETE already
+     * uses, and both are Pull requests: write, which the App manifest grants.
+     */
+    async requestEscalationReview(n, logins) {
+        const reviewers = logins.map((l) => l.trim().replace(/^@/, "")).filter(Boolean);
+        return this.gate.execute({
+            kind: "request_reviewer",
+            method: "POST",
+            path: `/repos/${this.owner}/${this.repo}/pulls/${n}/requested_reviewers`,
+            body: { reviewers },
+            note: `escalation: request review from ${reviewers.map((r) => `@${r}`).join(", ")} on #${n}`,
+            pr: n,
+        });
+    }
+    async createReview(n, payload, options) {
+        return this.gate.execute({
+            kind: "create_review",
+            method: "POST",
+            path: `/repos/${this.owner}/${this.repo}/pulls/${n}/reviews`,
+            body: payload,
+            note: `post ${payload.event} review on #${n}${options?.postingRetry ? " (deferred delivery)" : ""}`,
+            pr: n,
+            reviewPurpose: options?.purpose,
+            ...(options?.postingRetry !== undefined ? { postingRetry: options.postingRetry } : {}),
+        });
+    }
+    /** A claimed PR-level author response; ordinary posting guards and dry-run apply. */
+    async createIssueComment(n, body) {
+        return this.gate.execute({
+            kind: "create_issue_comment",
+            method: "POST",
+            path: `/repos/${this.owner}/${this.repo}/issues/${n}/comments`,
+            body: { body },
+            note: `answer the author in PR #${n}'s conversation`,
+            pr: n,
+        });
+    }
+    async createReviewCommentReply(n, commentId, body) {
+        return this.gate.execute({
+            kind: "create_review_comment_reply",
+            method: "POST",
+            path: `/repos/${this.owner}/${this.repo}/pulls/${n}/comments/${commentId}/replies`,
+            body: { body },
+            note: `reply in thread ${commentId} on #${n}`,
+            pr: n,
+        });
+    }
+    /** Resolve one inline review thread, but only after a read verifies that the
+     * numeric root comment belongs to this PR and was authored by this app.
+     * There is intentionally no generic resolve-thread mutation surface. */
+    async resolveOwnReviewThread(n, rootCommentId) {
+        const query = `query ($owner: String!, $repo: String!, $number: Int!, $after: String) {
+      repository(owner: $owner, name: $repo) {
+        pullRequest(number: $number) {
+          reviewThreads(first: 100, after: $after) {
+            nodes { id isResolved comments(first: 1) { nodes { databaseId author { login } body } } }
+            pageInfo { hasNextPage endCursor }
+          }
+        }
+      }
+    }`;
+        let after = null;
+        let found;
+        do {
+            const data = await this.graphql(query, {
+                owner: this.owner,
+                repo: this.repo,
+                number: n,
+                after,
+            });
+            const threads = data.repository?.pullRequest?.reviewThreads;
+            if (!threads)
+                throw new Error(`review threads unavailable for #${n}`);
+            for (const thread of threads.nodes) {
+                const root = thread.comments.nodes[0];
+                if (root?.databaseId === rootCommentId) {
+                    found = {
+                        id: thread.id,
+                        isResolved: thread.isResolved,
+                        author: root.author?.login ?? "",
+                        body: root.body ?? "",
+                    };
+                    break;
+                }
+            }
+            if (found || !threads.pageInfo.hasNextPage)
+                break;
+            after = threads.pageInfo.endCursor;
+        } while (after);
+        if (!found)
+            throw new ThreadResolutionRefusal(`comment ${rootCommentId} is not a review-thread root on #${n}`);
+        // GitHub exposes the same App actor with two spellings: review-author
+        // filters use the `[bot]` login, while review-thread GraphQL actors use the
+        // bare App slug. Both values are independently configured; recognize
+        // exactly that pair here and nowhere else. Every unrelated identity stays
+        // structurally refused.
+        const bareAppActor = appActorAlias(this.cfg.github.bot_login, this.cfg.github.app_slug);
+        const ownActors = new Set([this.cfg.github.bot_login, bareAppActor].filter((v) => v !== undefined));
+        if (!ownActors.has(found.author)) {
+            throw new ThreadResolutionRefusal(`refusing to resolve thread ${rootCommentId} on #${n}: root author is ${found.author || "unknown"}`);
+        }
+        // A "[check this]" thread exists to force a human's eyes before merge (repo
+        // rule: every conversation must be resolved). The reviewer never resolves
+        // one — the author or another human only.
+        if (CHECK_THIS_RE.test(found.body))
+            return { skipped: "check-this-human-only" };
+        // A "[deferred]" thread says this finding is real and this PR is not where
+        // it gets fixed. If the author ignores the drafted ticket, the reviewer
+        // must not be able to tidy the thread away — that would make a deferral
+        // free again, which is the exact thing this mechanism exists to stop. So it
+        // takes the same structural refusal as "[check this]", and the repo's merge
+        // rule (every conversation resolved) puts a person in front of it. Distinct
+        // marker, distinct reason string: the two are never conflated, here or
+        // anywhere.
+        if (DEFERRED_RE.test(found.body))
+            return { skipped: "deferred-human-only" };
+        // An "[ask your human]" thread is deliberately not refused here. It is the
+        // sibling marker, not a second spelling of the one above: it addresses the
+        // PR author's AI implementer ("do not answer this yourself — ask a person
+        // and bring the answer back"), so what a human owes the thread is the
+        // answer, not the resolution. Making it human-only would force a person
+        // into every such thread, and the ordinary path already lands in the right
+        // place — ping-pong resolves such a thread only after the author replied
+        // and the session judged the reply settles it, and the prior-finding
+        // resolver only for a finding a later round reported fixed or obsolete.
+        // Rule 2 is
+        // unaffected: this resolves the bot's OWN finding thread and never
+        // dismisses or edits any review, anyone's.
+        if (found.isResolved)
+            return { skipped: "already-resolved" };
+        const mutation = `mutation ($threadId: ID!) {
+      resolveReviewThread(input: {threadId: $threadId}) { thread { id isResolved } }
+    }`;
+        const result = await this.gate.execute({
+            kind: "resolve_own_review_thread",
+            method: "POST",
+            path: "/graphql",
+            body: { query: mutation, variables: { threadId: found.id } },
+            note: `resolve own review thread ${rootCommentId} on #${n}`,
+            pr: n,
+        });
+        return { skipped: null, result };
+    }
+    async createIssue(title, body, labels) {
+        return this.gate.execute({
+            kind: "create_issue",
+            method: "POST",
+            path: `/repos/${this.owner}/${this.repo}/issues`,
+            body: { title, body, labels },
+            note: `file issue "${title}"`,
+        });
+    }
+    /** Every open issue carrying the configured label, whoever filed it. */
+    async listOpenLabelledIssues() {
+        const q = `repo:${this.cfg.github.repo} is:open is:issue label:"${this.cfg.github.issue_label}"`;
+        return (await this.searchIssues(q)).map((i) => ({ number: i.number, title: i.title }));
+    }
+    /** Recover only an exact daemon marker posted by our configured identity.
+     * Absence is not permission to repeat an uncertain creation. */
+    async findFiledItem(kind, marker, branch) {
+        const path = kind === "issue"
+            ? `/repos/${this.owner}/${this.repo}/issues?state=all&per_page=100`
+            : `/repos/${this.owner}/${this.repo}/pulls?state=all&per_page=100&head=${encodeURIComponent(`${this.owner}:${branch.head}`)}&base=${encodeURIComponent(branch.base)}`;
+        const { rows, truncated } = await this.pagedArray(path);
+        if (truncated)
+            throw new Error("filing reconciliation exceeded pagination bound");
+        const matches = rows.filter((row) => row.user?.login === this.cfg.github.bot_login &&
+            typeof row.body === "string" &&
+            row.body.split(/\r?\n/).includes(marker) &&
+            (kind === "issue"
+                ? !row.pull_request
+                : row.head?.ref === branch?.head && row.base?.ref === branch?.base));
+        if (matches.length > 1)
+            throw new Error("ambiguous filing markers");
+        if (matches.length === 0)
+            return null;
+        const number = matches[0].number;
+        if (typeof number !== "number" || !Number.isSafeInteger(number) || number <= 0)
+            throw new Error("invalid filing receipt number");
+        return number;
+    }
+    async createPull(head, base, title, body) {
+        return this.gate.execute({
+            kind: "create_pull",
+            method: "POST",
+            path: `/repos/${this.owner}/${this.repo}/pulls`,
+            body: { head, base, title, body },
+            note: `open PR ${head} → ${base}: "${title}"`,
+        });
+    }
+}
+//# sourceMappingURL=github.js.map