@jitsusama/agentic-harness.core 0.1.0

package/dist/review/providers/github/conversation.js

@@ -0,0 +1,455 @@
+/**
+ * Reading and writing the conversation on a GitHub change.
+ *
+ * Three of GitHub's habits are absorbed here rather than
+ * leaked. It calls the two sides of a diff LEFT and RIGHT,
+ * which is a display convention, so the neutral old and new
+ * are translated at this boundary. It keeps review threads in
+ * GraphQL and reactions in REST, with different id systems, so
+ * message ids are minted with a prefix saying which route they
+ * belong to. And it pages review threads a hundred at a time,
+ * so the reader keeps asking until GitHub says there is no
+ * more; stopping at the first page silently loses the tail of
+ * a long review.
+ */
+import { unlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { run } from "../../../exec/index.js";
+import { GHOST, ownerRepoFromKey } from "./claims.js";
+/** Message id prefixes, naming which REST route owns the id. */
+const REVIEW_COMMENT = "rc:";
+const ISSUE_COMMENT = "ic:";
+/** How many threads to ask for per page. GitHub's own cap. */
+const THREAD_PAGE_SIZE = 100;
+const THREADS_QUERY = `query PrReviewThreads($owner: String!, $repo: String!, $number: Int!, $after: String) {
+  repository(owner: $owner, name: $repo) {
+    pullRequest(number: $number) {
+      reviewThreads(first: ${THREAD_PAGE_SIZE}, after: $after) {
+        pageInfo { hasNextPage endCursor }
+        nodes {
+          id
+          isResolved
+          resolvedBy { login name }
+          isOutdated
+          subjectType
+          path
+          line
+          startLine
+          diffSide
+          comments(first: 50) {
+            nodes {
+              id
+              databaseId
+              author { login }
+              body
+              createdAt
+              url
+            }
+          }
+        }
+      }
+    }
+  }
+}`;
+const REPLY_MUTATION = `mutation AddThreadReply($threadId: ID!, $body: String!) {
+  addPullRequestReviewThreadReply(input: {
+    pullRequestReviewThreadId: $threadId
+    body: $body
+  }) {
+    comment { id url }
+  }
+}`;
+const RESOLVE_MUTATION = `mutation ResolveThread($threadId: ID!) {
+  resolveReviewThread(input: { threadId: $threadId }) {
+    thread { id isResolved }
+  }
+}`;
+const UNRESOLVE_MUTATION = `mutation UnresolveThread($threadId: ID!) {
+  unresolveReviewThread(input: { threadId: $threadId }) {
+    thread { id isResolved }
+  }
+}`;
+/** GitHub's review event for each neutral verdict. */
+const REVIEW_EVENT = {
+    approve: "APPROVE",
+    "request-changes": "REQUEST_CHANGES",
+    comment: "COMMENT",
+};
+/** The neutral verdict for each of GitHub's review states. */
+function verdictOf(state) {
+    if (state === "APPROVED")
+        return "approve";
+    if (state === "CHANGES_REQUESTED")
+        return "request-changes";
+    return "comment";
+}
+/** Reaction names GitHub accepts, which match the model's. */
+const REACTION_NAMES = [
+    "+1",
+    "-1",
+    "laugh",
+    "confused",
+    "heart",
+    "hooray",
+    "rocket",
+    "eyes",
+];
+function slugOf(repo) {
+    const owned = ownerRepoFromKey(repo.key);
+    if (!owned)
+        throw new Error(`${repo.key} is not a GitHub repo key`);
+    return `${owned.owner}/${owned.repo}`;
+}
+function record(value) {
+    return typeof value === "object" && value !== null
+        ? value
+        : {};
+}
+/**
+ * Walk into a response, refusing rather than defaulting.
+ *
+ * `record` above answers `{}` for anything it does not recognize,
+ * which is right for a field that may be absent and wrong for the
+ * envelope itself. Walked with it, a renamed field, a schema change
+ * or a partial error payload all arrive as a change with no threads
+ * on it, and that is the worst way a read can fail: the person
+ * concludes nobody commented and moves on, with nothing anywhere
+ * saying the question went unanswered.
+ *
+ * Absence is the test, not emptiness. A change with no comments is
+ * ordinary and answers with the field present and its list empty, so
+ * only a missing key is a refusal.
+ */
+function into(value, path, what) {
+    let at = value;
+    const walked = [];
+    for (const key of path) {
+        if (typeof at !== "object" || at === null || !(key in at)) {
+            const missing = [...walked, key].join(".");
+            throw new Error(`GitHub answered ${what} without ${missing}. Reading on would ` +
+                "report nothing found, which is indistinguishable from a change " +
+                "that genuinely has none.");
+        }
+        at = at[key];
+        walked.push(key);
+    }
+    return record(at);
+}
+function str(value) {
+    return typeof value === "string" ? value : undefined;
+}
+function list(value) {
+    return Array.isArray(value) ? value : [];
+}
+/** The counted reactions on a REST comment. */
+function reactionsOf(value) {
+    const raw = record(value);
+    const counts = [];
+    for (const name of REACTION_NAMES) {
+        const count = raw[name];
+        if (typeof count === "number" && count > 0) {
+            counts.push({ reaction: name, count });
+        }
+    }
+    return counts;
+}
+/** A top-level comment, in the neutral shape. */
+function messageFromIssueComment(raw) {
+    const reactions = reactionsOf(raw.reactions);
+    return {
+        id: `${ISSUE_COMMENT}${String(raw.id ?? "")}`,
+        author: { id: str(record(raw.user).login) ?? GHOST },
+        body: str(raw.body) ?? "",
+        ...(str(raw.created_at) ? { createdAt: str(raw.created_at) } : {}),
+        ...(str(raw.html_url) ? { url: str(raw.html_url) } : {}),
+        ...(reactions.length > 0 ? { reactions } : {}),
+    };
+}
+/** A thread comment from GraphQL, keyed for the REST routes. */
+function messageFromThreadComment(raw) {
+    const databaseId = raw.databaseId;
+    const id = typeof databaseId === "number"
+        ? `${REVIEW_COMMENT}${databaseId}`
+        : (str(raw.id) ?? "");
+    return {
+        id,
+        author: { id: str(record(raw.author).login) ?? GHOST },
+        body: str(raw.body) ?? "",
+        ...(str(raw.createdAt) ? { createdAt: str(raw.createdAt) } : {}),
+        ...(str(raw.url) ? { url: str(raw.url) } : {}),
+    };
+}
+/** The anchor a thread carries, when it still has one. */
+function anchorOf(raw) {
+    const path = str(raw.path);
+    if (!path)
+        return undefined;
+    // A remark about the whole file says so, and GitHub answers `line: 1` for
+    // one anyway. Reading the line first made a file-level remark come back as
+    // a remark on the first line: we would post one, read it back, and report
+    // it somewhere it was never aimed. Nobody would notice from the listing,
+    // since line 1 of a file is a plausible place to have said something.
+    if (str(raw.subjectType) === "FILE")
+        return { subject: "file", path };
+    const line = raw.line;
+    if (typeof line !== "number") {
+        // GitHub nulls the line when a force-push strands the
+        // thread; the file is all that is left of the anchor.
+        return { subject: "file", path };
+    }
+    const startLine = raw.startLine;
+    const blob = str(raw.diffSide) === "LEFT" ? "old" : "new";
+    return {
+        subject: "line",
+        path,
+        blob,
+        line,
+        ...(typeof startLine === "number" && startLine !== line
+            ? { startLine }
+            : {}),
+    };
+}
+/**
+ * A person, from a GraphQL actor node, or nobody.
+ *
+ * Nobody rather than the ghost user: an absent actor here means the field was not
+ * selected or the thread is open, and naming a placeholder would assert somebody acted.
+ */
+function actorFrom(raw) {
+    const login = str(record(raw).login);
+    if (login === undefined)
+        return undefined;
+    const name = str(record(raw).name);
+    return { id: login, ...(name === undefined ? {} : { name }) };
+}
+function threadFrom(raw) {
+    const anchor = anchorOf(raw);
+    const closedBy = actorFrom(raw.resolvedBy);
+    return {
+        id: str(raw.id) ?? "",
+        resolved: raw.isResolved === true,
+        // Who closed it. The follow-up view reads this to say a thread was
+        // resolved by somebody other than you, which is the attribution that
+        // whole feature exists to give, and it was asking for a field the query
+        // never selected, so every follow-up degraded to "resolved with no
+        // reply" and never named anyone.
+        ...(closedBy === undefined ? {} : { resolvedBy: closedBy }),
+        stale: raw.isOutdated === true,
+        ...(anchor ? { anchor } : {}),
+        comments: list(record(raw.comments).nodes).map((node) => messageFromThreadComment(record(node))),
+    };
+}
+/** GitHub's wire shape for one anchored comment. */
+function wireComment(anchor, body) {
+    // GitHub has nowhere to attach a remark about the change
+    // itself, so the plan spills those into the review body long
+    // before here. Reaching this with one is a bug in the plan,
+    // and saying so beats posting a comment against no path.
+    if (anchor.subject === "change") {
+        throw new Error("a remark about the whole change cannot be an anchored comment");
+    }
+    if (anchor.subject === "file") {
+        return { path: anchor.path, body, subject_type: "file" };
+    }
+    const side = anchor.blob === "old" ? "LEFT" : "RIGHT";
+    return {
+        path: anchor.path,
+        body,
+        line: anchor.line,
+        side,
+        ...(anchor.startLine !== undefined && anchor.startLine !== anchor.line
+            ? { start_line: anchor.startLine, start_side: side }
+            : {}),
+    };
+}
+/** Which REST route a message id belongs to. */
+function reactionRoute(slug, message) {
+    if (message.id.startsWith(REVIEW_COMMENT)) {
+        const id = message.id.slice(REVIEW_COMMENT.length);
+        return `repos/${slug}/pulls/comments/${id}/reactions`;
+    }
+    if (message.id.startsWith(ISSUE_COMMENT)) {
+        const id = message.id.slice(ISSUE_COMMENT.length);
+        return `repos/${slug}/issues/comments/${id}/reactions`;
+    }
+    throw new Error(`cannot tell what kind of comment ${message.id} is, so it cannot be reacted to`);
+}
+/** Build the conversation facet. */
+export function githubConversation(exec) {
+    async function api(args, what) {
+        const stdout = await run(exec, "gh", ["api", ...args], what);
+        return (stdout.trim() ? JSON.parse(stdout) : {});
+    }
+    /**
+     * Read a REST list in full.
+     *
+     * GitHub answers a list request with thirty records and says
+     * nothing about the rest, so a plain read of a busy pull
+     * request quietly loses its tail, which is where the recent
+     * argument is. `--paginate` walks every page and merges them
+     * into one array; asking for a hundred at a time is what
+     * keeps that from being a dozen round trips.
+     */
+    async function apiList(route, what) {
+        const joiner = route.includes("?") ? "&" : "?";
+        return api(["--paginate", `${route}${joiner}per_page=100`], what);
+    }
+    async function graphql(query, variables, what) {
+        const args = ["graphql", "-f", `query=${query}`];
+        for (const [name, value] of Object.entries(variables)) {
+            // gh uses -F for numbers and -f for raw strings.
+            args.push(typeof value === "number" ? "-F" : "-f", `${name}=${value}`);
+        }
+        return api(args, what);
+    }
+    /** Post a JSON payload through a temp file. */
+    async function postJson(route, payload, what) {
+        const file = join(tmpdir(), `pi-review-${Date.now()}-${Math.random()}.json`);
+        try {
+            await writeFile(file, JSON.stringify(payload), "utf8");
+            const raw = await api(["--method", "POST", route, "--input", file], what);
+            const answer = record(raw);
+            return {
+                ...(answer.id !== undefined ? { id: String(answer.id) } : {}),
+                ...(str(answer.html_url) ? { url: str(answer.html_url) } : {}),
+            };
+        }
+        finally {
+            // A leftover temp file is harmless; failing to clean one
+            // up must not fail the operation that succeeded.
+            await unlink(file).catch(() => { });
+        }
+    }
+    return {
+        async reviews(ref) {
+            const raw = await apiList(`repos/${slugOf(ref.repo)}/pulls/${ref.id}/reviews`, `reading reviews on pull request ${ref.id}`);
+            return list(raw).map((entry) => {
+                const review = record(entry);
+                const state = str(review.state) ?? "COMMENTED";
+                return {
+                    id: String(review.id ?? ""),
+                    author: { id: str(record(review.user).login) ?? GHOST },
+                    verdict: verdictOf(state),
+                    nativeVerdict: state,
+                    body: str(review.body) ?? "",
+                    ...(str(review.submitted_at)
+                        ? { submittedAt: str(review.submitted_at) }
+                        : {}),
+                    ...(str(review.html_url) ? { url: str(review.html_url) } : {}),
+                };
+            });
+        },
+        async threads(ref) {
+            const owned = ownerRepoFromKey(ref.repo.key);
+            if (!owned)
+                throw new Error(`${ref.repo.key} is not a GitHub repo key`);
+            const threads = [];
+            let after;
+            // Keep asking. A long review has more than one page, and
+            // the tail is exactly where the unresolved threads are.
+            for (;;) {
+                const raw = await graphql(THREADS_QUERY, {
+                    owner: owned.owner,
+                    repo: owned.repo,
+                    number: Number.parseInt(ref.id, 10),
+                    ...(after ? { after } : {}),
+                }, `reading threads on pull request ${ref.id}`);
+                const page = into(raw, ["data", "repository", "pullRequest", "reviewThreads"], `threads on pull request ${ref.id}`);
+                for (const node of list(page.nodes)) {
+                    threads.push(threadFrom(record(node)));
+                }
+                const info = record(page.pageInfo);
+                const cursor = str(info.endCursor);
+                if (info.hasNextPage !== true || !cursor)
+                    break;
+                after = cursor;
+            }
+            return threads;
+        },
+        async messages(ref) {
+            const raw = await apiList(`repos/${slugOf(ref.repo)}/issues/${ref.id}/comments`, `reading comments on pull request ${ref.id}`);
+            return list(raw).map((entry) => messageFromIssueComment(record(entry)));
+        },
+        async postReview(ref, review) {
+            return postJson(`repos/${slugOf(ref.repo)}/pulls/${ref.id}/reviews`, {
+                event: REVIEW_EVENT[review.verdict],
+                body: review.body,
+                comments: review.comments.map((comment) => wireComment(comment.anchor, comment.body)),
+            }, `posting a review on pull request ${ref.id}`);
+        },
+        /**
+         * One anchored remark, posted on its own rather than in a review.
+         *
+         * This is where a remark about a whole file has to go. The batch route
+         * refuses one with `0.position (Expected value to not be null)` and
+         * rejects the entire review with it, so a single file-level remark used
+         * to cost every other remark beside it; adding `subject_type` to the
+         * batch is refused too, as `0.subjectType (Field is not defined on
+         * DraftPullRequestReviewComment)`. This route takes the same comment
+         * without complaint.
+         *
+         * It needs a commit to hang the comment from, which a review does not,
+         * so the change is read first to learn its head.
+         */
+        async commentOn(ref, anchor, body) {
+            const change = record(await api([`repos/${slugOf(ref.repo)}/pulls/${ref.id}`], `reading pull request ${ref.id} for the commit to anchor a comment to`));
+            const head = str(record(change.head).sha);
+            if (!head) {
+                throw new Error(`GitHub did not say what commit pull request ${ref.id} is at, and a comment posted on its own has to name one.`);
+            }
+            return postJson(`repos/${slugOf(ref.repo)}/pulls/${ref.id}/comments`, { ...wireComment(anchor, body), commit_id: head }, `posting a remark on ${anchor.subject === "file" ? anchor.path : "a line"} in pull request ${ref.id}`);
+        },
+        async reply(_ref, thread, body) {
+            const raw = await graphql(REPLY_MUTATION, { threadId: thread.id, body }, `replying to thread ${thread.id}`);
+            const comment = record(record(record(record(raw).data).addPullRequestReviewThreadReply)
+                .comment);
+            return {
+                ...(str(comment.id) ? { id: str(comment.id) } : {}),
+                ...(str(comment.url) ? { url: str(comment.url) } : {}),
+            };
+        },
+        async resolve(_ref, thread) {
+            await graphql(RESOLVE_MUTATION, { threadId: thread.id }, `resolving thread ${thread.id}`);
+        },
+        async unresolve(_ref, thread) {
+            await graphql(UNRESOLVE_MUTATION, { threadId: thread.id }, `reopening thread ${thread.id}`);
+        },
+        async comment(ref, body) {
+            const raw = await api([
+                "--method",
+                "POST",
+                `repos/${slugOf(ref.repo)}/issues/${ref.id}/comments`,
+                "-f",
+                `body=${body}`,
+            ], `commenting on pull request ${ref.id}`);
+            const answer = record(raw);
+            return {
+                ...(answer.id !== undefined ? { id: String(answer.id) } : {}),
+                ...(str(answer.html_url) ? { url: str(answer.html_url) } : {}),
+            };
+        },
+        async react(ref, subject, reaction) {
+            await api([
+                "--method",
+                "POST",
+                reactionRoute(slugOf(ref.repo), subject),
+                "-f",
+                `content=${reaction}`,
+            ], `reacting to ${subject.id}`);
+        },
+        async viewer() {
+            // The login, which is how every other GitHub payload names an
+            // author, so a comparison against a comment's author is comparing
+            // like with like. The display name is carried for a listing and
+            // never used to decide identity.
+            const answer = await api(["user"], "asking who you are");
+            const login = str(answer.login);
+            if (login === undefined) {
+                throw new Error("GitHub did not say who you are, so a question about your own remarks cannot be answered about the right person");
+            }
+            const name = str(answer.name);
+            return { id: login, ...(name === undefined ? {} : { name }) };
+        },
+    };
+}

package/dist/review/providers/github/fields.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Fields two GitHub readers both need.
+ *
+ * There are two places that turn a REST pull request into a
+ * {@link Proposal}: the proposals facet, which reads changes, and the
+ * authoring facet, which reads back the change it just wrote. They are
+ * near-duplicates and predate this file, and merging them is a real
+ * refactor rather than a detail of adding a field.
+ *
+ * What this file refuses to do is make the duplication worse. A reader
+ * added to one and forgotten in the other means a label that appears
+ * when you fetch a change and vanishes when you edit it, which reads as
+ * the edit having removed it.
+ */
+import type { Actor } from "../../change.js";
+/**
+ * Labels and assignees, when GitHub reported them.
+ *
+ * Both are carried on the pull request representation itself, so reading
+ * them costs nothing extra even though writing them takes a separate
+ * call to the issue routes.
+ *
+ * Each field is present only when GitHub sent the array. An empty array
+ * and an absent field are different facts: the first says this change
+ * has no labels, the second says nobody looked.
+ */
+export declare function labelsAndAssignees(raw: Record<string, unknown>): {
+    labels?: string[];
+    assignees?: Actor[];
+};

package/dist/review/providers/github/fields.js

@@ -0,0 +1,47 @@
+/**
+ * Fields two GitHub readers both need.
+ *
+ * There are two places that turn a REST pull request into a
+ * {@link Proposal}: the proposals facet, which reads changes, and the
+ * authoring facet, which reads back the change it just wrote. They are
+ * near-duplicates and predate this file, and merging them is a real
+ * refactor rather than a detail of adding a field.
+ *
+ * What this file refuses to do is make the duplication worse. A reader
+ * added to one and forgotten in the other means a label that appears
+ * when you fetch a change and vanishes when you edit it, which reads as
+ * the edit having removed it.
+ */
+/** Every string in an array of records under one key. */
+function names(value, key) {
+    if (!Array.isArray(value))
+        return undefined;
+    const found = [];
+    for (const entry of value) {
+        if (typeof entry !== "object" || entry === null)
+            continue;
+        const held = entry[key];
+        if (typeof held === "string" && held !== "")
+            found.push(held);
+    }
+    return found;
+}
+/**
+ * Labels and assignees, when GitHub reported them.
+ *
+ * Both are carried on the pull request representation itself, so reading
+ * them costs nothing extra even though writing them takes a separate
+ * call to the issue routes.
+ *
+ * Each field is present only when GitHub sent the array. An empty array
+ * and an absent field are different facts: the first says this change
+ * has no labels, the second says nobody looked.
+ */
+export function labelsAndAssignees(raw) {
+    const labels = names(raw.labels, "name");
+    const logins = names(raw.assignees, "login");
+    return {
+        ...(labels ? { labels } : {}),
+        ...(logins ? { assignees: logins.map((id) => ({ id })) } : {}),
+    };
+}

package/dist/review/providers/github/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * The GitHub provider.
+ *
+ * Reaches GitHub through the `gh` CLI, which is where the
+ * authentication already lives. Capabilities are declared from
+ * what GitHub actually does rather than what would be
+ * convenient: it flags a stranded anchor instead of pinning
+ * one, it cannot thread a reply onto a top-level comment, and
+ * it records no stack at all, so any stack it reports is
+ * derived and says so.
+ */
+import type { ProviderDeps } from "../../../exec/index.js";
+import type { ReviewProvider } from "../../provider.js";
+/** Build the GitHub provider. */
+export declare function createGitHubProvider(deps: ProviderDeps): ReviewProvider;

package/dist/review/providers/github/index.js

@@ -0,0 +1,110 @@
+/**
+ * The GitHub provider.
+ *
+ * Reaches GitHub through the `gh` CLI, which is where the
+ * authentication already lives. Capabilities are declared from
+ * what GitHub actually does rather than what would be
+ * convenient: it flags a stranded anchor instead of pinning
+ * one, it cannot thread a reply onto a top-level comment, and
+ * it records no stack at all, so any stack it reports is
+ * derived and says so.
+ */
+import { githubAuthoring } from "./authoring.js";
+import { claimGitHubReference, claimGitHubRepo, GITHUB_PROVIDER_ID, } from "./claims.js";
+import { githubConversation } from "./conversation.js";
+import { githubProposals } from "./proposals.js";
+import { githubStacking } from "./stacking.js";
+/**
+ * Claim priority. A generalist: any backend that specializes
+ * in a repo GitHub also mirrors should be asked first.
+ */
+const GITHUB_PRIORITY = 100;
+/** The reactions GitHub accepts, in its own order. */
+const GITHUB_REACTIONS = [
+    "+1",
+    "-1",
+    "laugh",
+    "confused",
+    "heart",
+    "hooray",
+    "rocket",
+    "eyes",
+];
+/** What GitHub can do, which does not vary by repo. */
+function githubCapabilities() {
+    return {
+        proposals: { fetchAsRef: true, checks: true, list: true },
+        stacking: { provenance: "derived", fanOut: true },
+        conversation: {
+            anchoredBatchReview: true,
+            // On its own, not in a review. The batch route refuses a
+            // file-level comment and rejects the whole review with it, and
+            // declaring this as a bare `true` beside `anchoredBatchReview:
+            // true` said the pair was possible when only each half was.
+            fileLevelComments: "standalone",
+            multiLineRanges: true,
+            unresolve: true,
+            reactions: GITHUB_REACTIONS,
+            // A reply must target a review thread; issue comments
+            // have no thread to hang from.
+            topLevelThreading: false,
+            // A force-push strands a thread and GitHub marks it,
+            // rather than keeping the anchor's commit reachable.
+            staleness: "flagged",
+            selfVerdicts: ["comment"],
+        },
+        authoring: {
+            propose: true,
+            // One change at a time. GitHub has no notion of a stack, so
+            // there is nothing to submit as one.
+            proposeStack: false,
+            reviewersAt: "any-time",
+            // A base is a field on the change here, so retargeting one
+            // change moves that change and nothing else.
+            retarget: "change",
+            setDraft: true,
+            close: true,
+            reopen: true,
+            merge: true,
+            labels: true,
+            assignees: true,
+            // A login, not an email. The REST routes take `assignees` as an
+            // array of logins and answer 422 for anything else, and an email
+            // address is not derivable from a login here: the address on a
+            // commit belongs to the commit, not to the account.
+            identifies: "login",
+            // True because Actions runs can be reposted, not because every
+            // check on a GitHub change can be. A check contributed by some
+            // other app has no run behind it, and the implementation
+            // declines by name rather than pretending it started one.
+            rerunChecks: true,
+            // This said false, on the belief that a merge queue was
+            // something a backend layered on top of GitHub added. GitHub
+            // has its own: `MergeQueueEntry` is on the GraphQL pull
+            // request, it reports a position and whether the change is
+            // being tested `solo`, and pushing to a queued change ejects
+            // it the same way. Saying false here made the queue gate dead
+            // on GitHub as well as unreachable everywhere.
+            //
+            // Declaring true is not the same as refusing: the proposals
+            // facet reports the posture, and a change with no queue entry
+            // reads as unqueued and is permitted. The gate bites only when
+            // there is really something to eject.
+            refusesWhileEnqueued: true,
+        },
+    };
+}
+/** Build the GitHub provider. */
+export function createGitHubProvider(deps) {
+    return {
+        id: GITHUB_PROVIDER_ID,
+        priority: GITHUB_PRIORITY,
+        claimReference: claimGitHubReference,
+        claimRepo: claimGitHubRepo,
+        capabilities: githubCapabilities,
+        proposals: githubProposals(deps.exec),
+        conversation: githubConversation(deps.exec),
+        stacking: githubStacking(deps.exec),
+        authoring: githubAuthoring(deps.exec),
+    };
+}

package/dist/review/providers/github/proposals.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Reading changes from GitHub.
+ *
+ * GitHub says a merged pull request is `closed` with a
+ * `merged_at` timestamp, and calls a draft a state in one API
+ * and a flag in another. The neutral model says merged is its
+ * own state and draft is a flag, so the translation happens
+ * here, once, rather than in every caller that has to decide
+ * what `closed` meant.
+ */
+import type { Exec } from "../../../exec/index.js";
+import type { ProposalsFacet } from "../../provider.js";
+/** Build the proposals facet. */
+export declare function githubProposals(exec: Exec): ProposalsFacet;