@joshuafolkken/kit 1.872.0

package/scripts/git/git-gh-pr-rest.ts

@@ -0,0 +1,172 @@
+import { z } from 'zod'
+import { MERGED_STATE, to_gh_state } from './git-gh-rest-state'
+import { parse_json_array_or_undefined, parse_json_object_safe } from './parse-json-array'
+import { rest_comment_schema } from './schemas'
+
+// The translation between one REST pull request (`repos/{owner}/{repo}/pulls/{N}`) and the JSON
+// shape `gh pr view --json <fields>` used to answer with.
+//
+// `gh pr view` goes through GraphQL, which a cloud session is answered 403 for while the REST
+// endpoint is served normally (joshuafolkken/kit#1022). The mapping lives here rather than beside
+// the requests because it is pure: given the response, it decides the answer with nothing else to
+// know — the same split `git-gh-issue-rest.ts` already makes (joshuafolkken/kit#1027).
+
+// Only the fields the mapping itself reads are named; every other key passes through untouched.
+//
+// `number` is required so that a 200 carrying something other than a pull request — a proxy's HTML
+// error page, an API message object — fails the parse rather than passing as a pull request whose
+// every field is missing. `pr_view` would otherwise answer a well-formed JSON object with no state
+// in it, which `git-pr.ts` reads as "the state could not be determined".
+//
+// `mergeable` and `mergeable_state` are served by the single-pull endpoint only — the listing omits
+// both — which is why the branch lookup resolves a number and the reads go back for the detail.
+// `repo.full_name` is what tells a fork's head from this repository's own — `head.ref` is a bare
+// branch name that says nothing about which repository holds it (joshuafolkken/kit#1029). Named once
+// because both sides of a pull request carry the same shape.
+const rest_repo_schema = z.looseObject({ full_name: z.string().optional() }).nullish()
+const rest_pull_side_schema = z.looseObject({ repo: rest_repo_schema })
+
+type RestPullSide = z.infer<typeof rest_pull_side_schema>
+
+const rest_pull_schema = z.looseObject({
+	number: z.number(),
+	html_url: z.string().optional(),
+	body: z.string().nullish(),
+	state: z.string().optional(),
+	merged: z.boolean().nullish(),
+	merged_at: z.string().nullish(),
+	mergeable: z.boolean().nullish(),
+	mergeable_state: z.string().optional(),
+	// `sha` is the head commit, which is what both halves of the merge-gate rollup are keyed by —
+	// REST hangs the check runs and the status contexts off the commit rather than off the pull
+	// request (joshuafolkken/kit#1028).
+	head: z
+		.looseObject({ ref: z.string().optional(), sha: z.string().optional(), repo: rest_repo_schema })
+		.nullish(),
+	base: rest_pull_side_schema.nullish(),
+	// `node_id` is what the GraphQL auto-merge mutation addresses a pull request by, and `auto_merge`
+	// is `null` until auto-merge is enabled — both read by `git-gh-pr-auto-merge.ts`
+	// (joshuafolkken/kit#2497).
+	node_id: z.string().optional(),
+	auto_merge: z.looseObject({}).nullish(),
+})
+
+type RestPull = z.infer<typeof rest_pull_schema>
+
+const NOT_A_PULL_MESSAGE = 'gh api answered something other than a pull request object'
+const NOT_A_PULL_LISTING_MESSAGE = 'gh api answered something other than a pull request listing'
+const NOT_A_COMMENT_LISTING_MESSAGE = 'gh api answered something other than a comment listing'
+
+const OPEN_STATE = 'open'
+const EMPTY_BODY = ''
+
+function parse_rest_pull(rest_json: string): RestPull {
+	const parsed = parse_json_object_safe(rest_json, rest_pull_schema)
+	if (parsed === undefined) throw new Error(NOT_A_PULL_MESSAGE)
+
+	return parsed
+}
+
+// A response that is not a listing must not degrade into an empty one: `pr_exists` reads an empty
+// listing as "this branch has no pull request", and `git-pr.ts` answers that by opening a second one
+// (joshuafolkken/kit#950 is the same misread on the issue side).
+function parse_rest_pulls(rest_json: string): Array<RestPull> {
+	const parsed = parse_json_array_or_undefined(rest_json, rest_pull_schema)
+	if (parsed === undefined) throw new Error(NOT_A_PULL_LISTING_MESSAGE)
+
+	return parsed
+}
+
+// Which pull request a branch name means. `gh pr view <branch>` preferred the open one and fell back
+// to the most recent, and the difference is reachable in this repository's own flow: `git-pr.ts`
+// opens a *second* pull request on a branch whose first one merged, so a lookup that answered
+// "newest first, whatever its state" would still be right there while "the first row" alone would
+// not be once GitHub's ordering is left to a default. The caller asks newest-first, so the fallback
+// is the newest.
+function select_pull(pulls: ReadonlyArray<RestPull>): RestPull | undefined {
+	return pulls.find((pull) => pull.state === OPEN_STATE) ?? pulls[0]
+}
+
+// REST reports a merge as a field beside the state rather than as a state, and both spellings of it
+// are accepted: the single-pull endpoint carries `merged`, the listing carries only `merged_at`.
+//
+// Exported since joshuafolkken/kit#1077, because `pr_merge` asks the same question directly: a merge
+// request that failed after the merge landed is settled by reading the pull request back, and the
+// merge-or-not verdict must be the one `to_pr_state` already uses rather than a second spelling of it.
+function is_merged(pull: RestPull): boolean {
+	return pull.merged === true || typeof pull.merged_at === 'string'
+}
+
+// `gh` answered three values where REST answers two. `git-pr.ts` compares against `MERGED` to decide
+// whether the branch needs a fresh pull request, so folding a merged one into `CLOSED` would leave
+// it waiting on checks that will never run again.
+function to_pr_state(pull: RestPull): string | undefined {
+	return is_merged(pull) ? MERGED_STATE : to_gh_state(pull.state)
+}
+
+// Whether the head branch lives in this repository rather than in a fork.
+//
+// `gh pr checkout` reached a fork's head through `refs/pull/<N>/head`, which a plain
+// `git fetch origin <branch>` cannot: the fetch either fails outright, or — where `origin` happens to
+// carry a branch of the same name — succeeds on an unrelated branch. Both halves are read out of the
+// one response, so the test costs no second request (joshuafolkken/kit#1029).
+function to_repo_name(side: RestPullSide | null | undefined): string | undefined {
+	return side?.repo?.full_name
+}
+
+function is_same_repository_head(pull: RestPull): boolean {
+	const head_repo = to_repo_name(pull.head)
+
+	return head_repo !== undefined && head_repo === to_repo_name(pull.base)
+}
+
+// The three fields `gh pr view --json mergeable,mergeStateStatus,state` answered with.
+//
+// `mergeable` was a GraphQL enum (`MERGEABLE` / `CONFLICTING` / `UNKNOWN`) and is a nullable boolean
+// in REST; `pr_info_schema` accepts both, so the boolean passes through as it arrives — including
+// the JSON null GitHub sends while it is still computing.
+//
+// **Nothing reads `mergeable` any more** (joshuafolkken/kit#1232 removed `git-conflict.ts`, its only
+// reader, and the conflict verdict comes off `mergeStateStatus` in `git-pr-checks-eval.ts` now). It
+// stays because this function's contract is *the shape `gh pr view --json …` answered with*, not
+// the subset today's callers happen to read — trimming a wire shape to its current readers is what
+// makes the next one look for a field the mapping silently dropped.
+//
+// `mergeStateStatus` is upper-cased because that is how `gh` spelled it, and because the merge-gate
+// snapshot in `git-pr-checks-eval.ts` compares strictly against that spelling
+// (joshuafolkken/kit#1028 converts the snapshot itself).
+function to_pr_info(pull: RestPull): Record<string, unknown> {
+	return {
+		mergeable: pull.mergeable,
+		mergeStateStatus: to_gh_state(pull.mergeable_state),
+		state: to_pr_state(pull),
+	}
+}
+
+// The conversation comments in the shape `gh pr view --json comments` answered with. A listing that
+// will not parse throws rather than answering an empty one — `git-pr-ai-review.ts` reads an empty
+// listing as "no reviewer left a finding" and merges (joshuafolkken/kit#973).
+function to_pr_comments(rest_json: string): Array<Record<string, unknown>> {
+	const parsed = parse_json_array_or_undefined(rest_json, rest_comment_schema)
+	if (parsed === undefined) throw new Error(NOT_A_COMMENT_LISTING_MESSAGE)
+
+	return parsed.map((comment) => ({
+		body: comment.body ?? EMPTY_BODY,
+		url: comment.html_url,
+		author: { login: comment.user?.login },
+	}))
+}
+
+const git_gh_pr_rest = {
+	parse_rest_pull,
+	parse_rest_pulls,
+	select_pull,
+	is_same_repository_head,
+	is_merged,
+	to_pr_state,
+	to_pr_info,
+	to_pr_comments,
+}
+
+export type { RestPull }
+export { git_gh_pr_rest }

package/scripts/git/git-gh-pr-review.ts

@@ -0,0 +1,103 @@
+import { z } from 'zod'
+import { parse_json_array_or_undefined } from './parse-json-array'
+
+// GraphQL's `reviewDecision`, rebuilt from the review history REST serves.
+//
+// **REST has no field for it.** `repos/{owner}/{repo}/pulls/{N}/reviews` answers every review ever
+// submitted, so the one value `gh pr view --json reviewDecision` gave has to be folded out of that
+// listing (joshuafolkken/kit#1028).
+//
+// The only consumer is `is_review_blocked` in `git-pr-checks-eval.ts`, which asks one question: is
+// `CHANGES_REQUESTED` standing? `APPROVED` and the empty string are therefore interchangeable to the
+// merge gate, and both are produced anyway so the value stays readable next to what `gh` answered.
+//
+// One value cannot be reproduced and is not attempted: GraphQL answers `REVIEW_REQUIRED` when branch
+// protection demands a review nobody has left, which is a repository setting rather than anything in
+// this listing. The gate never distinguished it from the empty string, so nothing downstream moves.
+
+const REVIEW_APPROVED = 'APPROVED'
+const REVIEW_CHANGES_REQUESTED = 'CHANGES_REQUESTED'
+// `gh` answered the empty string when no decision stood, and `read_string` in
+// `git-pr-checks-parse.ts` folds it to `undefined` — the same answer a missing field would give.
+const REVIEW_NONE = ''
+
+// **Only these two change the decision.** `COMMENTED` leaves it untouched, which is not a corner
+// case here: CodeRabbit posts its review as `COMMENTED` on every pull request this tooling opens, so
+// counting it would make each reviewer's last review a comment and lose a standing change request.
+// `PENDING` is a draft that was never submitted. `DISMISSED` is excluded for a subtler reason —
+// GitHub rewrites the *original* review's state to `DISMISSED` rather than appending a record, so
+// skipping it leaves the reviewer's last surviving verdict standing. A dismissed approval
+// therefore falls back to an earlier change request (blocked, matching GitHub), where treating
+// `DISMISSED` as a reset would open the gate — the one direction this file must never be wrong in.
+const STATE_CHANGING_REVIEWS = new Set([REVIEW_APPROVED, REVIEW_CHANGES_REQUESTED])
+
+const rest_review_schema = z.looseObject({
+	state: z.string().optional(),
+	user: z.looseObject({ login: z.string().optional() }).nullish(),
+})
+
+type RestReview = z.infer<typeof rest_review_schema>
+
+const NOT_A_REVIEW_LISTING = 'gh api answered something other than a review listing'
+
+// A listing that will not parse throws rather than answering "nobody requested changes" — the
+// merge-gate direction of joshuafolkken/kit#973 again.
+function parse_rest_reviews(reviews_json: string): Array<RestReview> {
+	const parsed = parse_json_array_or_undefined(reviews_json, rest_review_schema)
+	if (parsed === undefined) throw new Error(NOT_A_REVIEW_LISTING)
+
+	return parsed
+}
+
+// A review with no author still counts. GitHub serves `user: null` for a review left by an account
+// that has since been deleted, and dropping it would take a standing `CHANGES_REQUESTED` out of the
+// decision — the one direction this file must never be wrong in. The sentinel cannot collide with a
+// real login (GitHub logins hold no spaces or parentheses), so an unattributable review folds with
+// the other unattributable ones and never overwrites a named reviewer's verdict.
+const UNATTRIBUTED_REVIEWER = '(no author)'
+
+function read_reviewer(review: RestReview): string {
+	const login = review.user?.login
+
+	return typeof login === 'string' && login.length > 0 ? login : UNATTRIBUTED_REVIEWER
+}
+
+function read_state_changing(review: RestReview): string | undefined {
+	const state = review.state?.toUpperCase()
+
+	return state !== undefined && STATE_CHANGING_REVIEWS.has(state) ? state : undefined
+}
+
+// The listing is chronological, so a later entry overwrites the same reviewer's earlier one and the
+// map ends holding each reviewer's latest verdict. This is what keeps a reviewer who requested
+// changes and then approved from leaving the pull request blocked.
+function fold_latest_states(reviews: ReadonlyArray<RestReview>): Map<string, string> {
+	const latest = new Map<string, string>()
+
+	for (const review of reviews) {
+		const state = read_state_changing(review)
+		if (state !== undefined) latest.set(read_reviewer(review), state)
+	}
+
+	return latest
+}
+
+function to_review_decision(reviews_json: string): string {
+	const latest = new Set(fold_latest_states(parse_rest_reviews(reviews_json)).values())
+
+	if (latest.has(REVIEW_CHANGES_REQUESTED)) return REVIEW_CHANGES_REQUESTED
+
+	return latest.has(REVIEW_APPROVED) ? REVIEW_APPROVED : REVIEW_NONE
+}
+
+const git_gh_pr_review = { to_review_decision, parse_rest_reviews }
+
+export {
+	git_gh_pr_review,
+	to_review_decision,
+	NOT_A_REVIEW_LISTING,
+	UNATTRIBUTED_REVIEWER,
+	REVIEW_APPROVED,
+	REVIEW_CHANGES_REQUESTED,
+	REVIEW_NONE,
+}

package/scripts/git/git-gh-pr-rollup.ts

@@ -0,0 +1,91 @@
+import { z } from 'zod'
+import { parse_json_array_or_undefined } from './parse-json-array'
+
+// The two REST listings `gh pr view --json statusCheckRollup` served as one array, merged back into
+// that one array.
+//
+// `gh` answered a single `statusCheckRollup` whose elements were of two kinds; REST splits them
+// across `commits/{sha}/check-runs` (`status` / `conclusion` / `name`) and `commits/{sha}/status`
+// (`state` / `context`). The merge is pure — given the two responses it decides the answer with
+// nothing else to know — so it lives here rather than beside the requests (joshuafolkken/kit#1028).
+
+// `__typename` is what `git-pr-checks-parse.ts` distinguishes the two kinds by, and only the status
+// contexts carry it: the parser's default branch is the check run, so a check run needs no marker
+// while a status context without one is read as a check run, finds no `status`, and reports as
+// `pending` forever.
+const STATUS_CONTEXT_TYPE_NAME = 'StatusContext'
+const TYPE_NAME_KEY = '__typename'
+
+// Every field passes through untouched — the parser reads five of them and lower-cases each, so the
+// REST spelling (`completed` / `success`) needs no conversion to match what `gh` sent in upper case.
+const rollup_element_schema = z.looseObject({})
+
+// Both endpoints answer an *object* wrapping the listing, so the reads page them with `--paginate
+// --slurp` and each arrives as an array of pages (`git-gh-exec.ts` → `GhApiRequest`). A repository
+// with more checks than one page holds is the case this exists for: without the concatenation the
+// merge gate would judge a pull request on its first 30 checks.
+const check_runs_page_schema = z.looseObject({
+	// Required, not optional: GitHub always names the key, and accepting a page without one would
+	// answer an empty rollup — which `git-pr-followup.ts` reports as "this branch has no checks".
+	check_runs: z.array(rollup_element_schema),
+})
+
+const status_page_schema = z.looseObject({
+	statuses: z.array(rollup_element_schema),
+})
+
+type RollupElement = z.infer<typeof rollup_element_schema>
+
+const NOT_A_CHECK_RUNS_LISTING = 'gh api answered something other than a check run listing'
+const NOT_A_STATUS_LISTING = 'gh api answered something other than a commit status listing'
+
+// A response that will not parse throws rather than degrading to an empty rollup. The direction is
+// what makes it worth the throw: an empty rollup reads as "this pull request has no checks", and
+// `git-pr-followup.ts` treats that as a reason to stop watching rather than as a failure — so a rate
+// limit would arrive as a pull request nothing was ever required to pass (joshuafolkken/kit#973).
+function read_pages<T>(raw_json: string, schema: z.ZodType<T>, message: string): Array<T> {
+	const pages = parse_json_array_or_undefined(raw_json, schema)
+	if (pages === undefined) throw new Error(message)
+
+	return pages
+}
+
+function to_check_run_items(check_runs_json: string): Array<RollupElement> {
+	const pages = read_pages(check_runs_json, check_runs_page_schema, NOT_A_CHECK_RUNS_LISTING)
+
+	return pages.flatMap((page) => page.check_runs)
+}
+
+function to_status_context_items(status_json: string): Array<RollupElement> {
+	const pages = read_pages(status_json, status_page_schema, NOT_A_STATUS_LISTING)
+
+	return pages
+		.flatMap((page) => page.statuses)
+		.map((status) => ({ ...status, [TYPE_NAME_KEY]: STATUS_CONTEXT_TYPE_NAME }))
+}
+
+// Check runs first, then the status contexts — the order `gh` used, and the order
+// `read_required_statuses` reads when two entries share a name.
+function to_status_check_rollup(input: {
+	check_runs_json: string
+	status_json: string
+}): Array<RollupElement> {
+	return [
+		...to_check_run_items(input.check_runs_json),
+		...to_status_context_items(input.status_json),
+	]
+}
+
+const git_gh_pr_rollup = {
+	to_check_run_items,
+	to_status_context_items,
+	to_status_check_rollup,
+}
+
+export {
+	git_gh_pr_rollup,
+	to_status_check_rollup,
+	NOT_A_CHECK_RUNS_LISTING,
+	NOT_A_STATUS_LISTING,
+	STATUS_CONTEXT_TYPE_NAME,
+}

package/scripts/git/git-gh-pr-snapshot.ts

@@ -0,0 +1,138 @@
+import { FULL_PAGE_QUERY, git_gh_api_path } from './git-gh-api-path'
+import { git_gh_exec } from './git-gh-exec'
+import { read_pull, require_pr_number } from './git-gh-pr-read'
+import type { RestPull } from './git-gh-pr-rest'
+import { git_gh_pr_review } from './git-gh-pr-review'
+import { git_gh_pr_rollup } from './git-gh-pr-rollup'
+import { to_gh_state } from './git-gh-rest-state'
+
+// The merge gate's pull request state snapshot, rebuilt from REST.
+//
+// `gh pr view --json mergeStateStatus,reviewDecision,statusCheckRollup` is answered 403 in a cloud
+// session (joshuafolkken/kit#1022), and all three fields are GraphQL-only: one has no REST
+// counterpart at all, one is spelled differently, and one is two endpoints that `gh` merged.
+// `pnpm josh followup` decides a pull request is green from this value, so a mistake here
+// ships as a merge no gate ever cleared rather than as a command that stops working
+// (joshuafolkken/kit#1028).
+//
+// The answer stays the JSON string `parse_pr_state_snapshot` already parses. Nothing downstream —
+// `git-pr-checks-parse.ts`, `git-pr-checks-eval.ts`, `git-pr-followup.ts` — changes.
+
+const NO_HEAD_SHA_MESSAGE = 'gh api answered a pull request with no head commit'
+
+// Both commit endpoints answer an *object* wrapping the listing, so `--paginate` alone would emit
+// one document per page and `JSON.parse` would reject the pair; `--slurp` wraps the pages in one
+// outer array instead (`git-gh-exec.ts` → `GhApiRequest`).
+async function read_object_pages(path: string): Promise<string> {
+	return await git_gh_exec.exec_gh_api({
+		path: `${path}${FULL_PAGE_QUERY}`,
+		should_paginate: true,
+		should_slurp: true,
+	})
+}
+
+// The reviews endpoint answers a bare array, whose pages `gh` merges into one array on its own —
+// slurping it would produce `[[…],[…]]`, which the listing schema then rejects.
+async function read_array_pages(path: string): Promise<string> {
+	return await git_gh_exec.exec_gh_api({
+		path: `${path}${FULL_PAGE_QUERY}`,
+		should_paginate: true,
+	})
+}
+
+function read_head_sha(pull: RestPull): string {
+	const sha = pull.head?.sha
+	if (sha === undefined) throw new Error(NO_HEAD_SHA_MESSAGE)
+
+	return sha
+}
+
+// One pull request's rollup: the check runs and the status contexts, read from the head commit and
+// merged back into the single array `gh` answered with.
+async function read_status_check_rollup(commit_sha: string): Promise<Array<object>> {
+	const [check_runs_json, status_json] = await Promise.all([
+		read_object_pages(git_gh_api_path.commit_check_runs_api_path(commit_sha)),
+		read_object_pages(git_gh_api_path.commit_status_api_path(commit_sha)),
+	])
+
+	return git_gh_pr_rollup.to_status_check_rollup({ check_runs_json, status_json })
+}
+
+// The review history, folded into GraphQL's `reviewDecision`. One request, and the only one of the
+// four the merge gate does not need on every poll — see `is_review_decision_decisive`
+// (joshuafolkken/kit#1043).
+async function pr_get_review_decision(pr_number: number): Promise<string> {
+	const path = git_gh_api_path.pull_reviews_api_path(String(pr_number))
+
+	return git_gh_pr_review.to_review_decision(await read_array_pages(path))
+}
+
+// `mergeStateStatus` is upper-cased because that is the spelling `gh` used and the spelling
+// `git-pr-checks-eval.ts` compares strictly against: `MERGE_STATE_CLEAN` never matches a lower-case
+// `clean`, which would also take every pull request out of the kit#753 escape hatch keyed on
+// `UNSTABLE`. The rule is shared with `to_pr_info` rather than written twice.
+async function build_checks_fields(pull: RestPull): Promise<Record<string, unknown>> {
+	return {
+		statusCheckRollup: await read_status_check_rollup(read_head_sha(pull)),
+		mergeStateStatus: to_gh_state(pull.mergeable_state),
+	}
+}
+
+interface ResolvedPull {
+	pr_number: number
+	pull: RestPull
+}
+
+// The resolution and the detail read, which every path below needs and which the branch → number
+// memo in `git-gh-pr-read.ts` makes free after the first poll.
+async function resolve_pull(branch_name: string): Promise<ResolvedPull> {
+	const pr_number = await require_pr_number(branch_name)
+
+	return { pr_number, pull: await read_pull(pr_number) }
+}
+
+// Everything the snapshot carries except the review decision: three requests rather than four.
+// `pr_number` travels with it so a caller that then *does* want the review decision needs no second
+// resolution (joshuafolkken/kit#1043).
+interface PrChecksSnapshot {
+	pr_number: number
+	snapshot_json: string
+}
+
+async function pr_get_checks_snapshot(branch_name: string): Promise<PrChecksSnapshot> {
+	const { pr_number, pull } = await resolve_pull(branch_name)
+
+	return { pr_number, snapshot_json: JSON.stringify(await build_checks_fields(pull)) }
+}
+
+// Throws where the branch has no pull request or a read fails, which is the contract `gh pr view`
+// had: `git-pr-followup.ts` catches it and falls through to the poll, and folding a failure into an
+// empty snapshot instead would read as "no checks, nothing requested" — green.
+//
+// **This is the definition the two halves above must compose to.** The merge gate reads them
+// separately so it can skip the review listing on a poll that cannot conclude anything, but the
+// three-field value `gh pr view --json …` answered with is still one thing, and it is asserted here
+// rather than reassembled inside a test (joshuafolkken/kit#1043).
+async function pr_get_state_snapshot(branch_name: string): Promise<string> {
+	const { pr_number, pull } = await resolve_pull(branch_name)
+	const [fields, review_decision] = await Promise.all([
+		build_checks_fields(pull),
+		pr_get_review_decision(pr_number),
+	])
+
+	return JSON.stringify({ ...fields, reviewDecision: review_decision })
+}
+
+const git_gh_pr_snapshot = {
+	pr_get_state_snapshot,
+	pr_get_checks_snapshot,
+	pr_get_review_decision,
+}
+
+export {
+	git_gh_pr_snapshot,
+	pr_get_state_snapshot,
+	pr_get_checks_snapshot,
+	pr_get_review_decision,
+	NO_HEAD_SHA_MESSAGE,
+}