@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/gh/git-ai-review-scan.ts

@@ -20,8 +20,10 @@ interface ClassifiedFindings {
 	infos: ReadonlyArray<ClassifiedFinding>
 }
 
-const CLAUDE_AUTHORS: ReadonlySet<string> = new Set(['claude', 'claude[bot]'])
-const CODERABBIT_AUTHORS: ReadonlySet<string> = new Set(['coderabbitai', 'coderabbitai[bot]'])
+// Only the app accounts (`type: Bot`): a bare `claude` / `coderabbitai` is an ordinary user login
+// anyone could register, and its comment is not an AI review.
+const CLAUDE_AUTHORS: ReadonlySet<string> = new Set(['claude[bot]'])
+const CODERABBIT_AUTHORS: ReadonlySet<string> = new Set(['coderabbitai[bot]'])
 
 const CLAUDE_BLOCKER_HEADINGS: ReadonlyArray<RegExp> = [
 	/^#{2,4}\s+Issues\b/mu,

package/scripts/gh/git-gh-api-path.ts

@@ -28,6 +28,13 @@ function issue_api_path(issue_number: string, repo?: string): string {
 	return `${issues_api_path(repo)}/${issue_number}`
 }
 
+// One issue's labels — a pull request is an issue to this endpoint. Named here because the label
+// writes and reads in `git-gh-issue-write.ts` and the CI classification read in `pr-classification.ts`
+// all address it.
+function issue_labels_api_path(issue_number: string, repo?: string): string {
+	return `${issue_api_path(issue_number, repo)}/labels`
+}
+
 // The dependency relations, which REST serves from their own endpoint rather than inside the issue.
 // Named here because three call sites address it — the read in `git-gh-issue-read.ts` and both
 // writes in `git-gh-issue-write.ts`.
@@ -90,6 +97,12 @@ function commit_status_api_path(commit_sha: string, repo?: string): string {
 	return `${commit_api_path(commit_sha, repo)}/status`
 }
 
+// The rules that apply to one branch, from every ruleset that targets it — readable without the
+// admin access the classic branch protection endpoint needs.
+function branch_rules_api_path(branch_name: string, repo?: string): string {
+	return `${repo_api_path(repo)}/rules/branches/${branch_name}`
+}
+
 // A single tag reference. REST answers 404 when the tag does not exist, which is the whole of the
 // question the release command's tag watch asks.
 function tag_reference_api_path(tag: string, repo?: string): string {
@@ -109,6 +122,7 @@ const git_gh_api_path = {
 	release_by_tag_api_path,
 	issues_api_path,
 	issue_api_path,
+	issue_labels_api_path,
 	blocked_by_api_path,
 	issue_comments_api_path,
 	pulls_api_path,
@@ -119,6 +133,7 @@ const git_gh_api_path = {
 	commit_api_path,
 	commit_check_runs_api_path,
 	commit_status_api_path,
+	branch_rules_api_path,
 }
 
 export { git_gh_api_path, FULL_PAGE_QUERY }

package/scripts/gh/git-gh-branch-rules.ts

@@ -0,0 +1,73 @@
+import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
+import { z } from 'zod'
+import { FULL_PAGE_QUERY, git_gh_api_path } from './git-gh-api-path'
+import { git_gh_exec } from './git-gh-exec'
+
+// The status check contexts the base branch's rules require, which is what lets the merge gate tell
+// a pull request held only by a slow optional check — GitHub's default-setup `CodeQL` — from one
+// still waiting on a check that guards the merge (joshuafolkken/kit#4351).
+//
+// **An empty answer keeps the gate strict, so every gap folds into it.** With no required context
+// known, `git-pr-checks-eval.ts` waits for `CLEAN` exactly as it did before, so a repository with no
+// ruleset, a token the endpoint answers 403 to, or a rate limit costs the wait time it always did and
+// never a merge past a check nobody declared optional.
+
+const REQUIRED_STATUS_CHECKS_RULE = 'required_status_checks'
+
+const required_check_schema = z.looseObject({ context: z.string() })
+
+const rule_parameters_schema = z.looseObject({
+	required_status_checks: z.array(required_check_schema).optional(),
+})
+
+const branch_rule_schema = z.looseObject({
+	type: z.string(),
+	parameters: rule_parameters_schema.nullish(),
+})
+
+type BranchRule = z.infer<typeof branch_rule_schema>
+
+// A branch's rules do not change while one command waits on a pull request, so a read is remembered
+// for the life of the command; one that failed is not, and the next poll asks again.
+const required_contexts_by_branch = new Map<string, Array<string>>()
+
+function forget_branch_rules(): void {
+	required_contexts_by_branch.clear()
+}
+
+function to_required_contexts(rules: ReadonlyArray<BranchRule>): Array<string> {
+	return rules
+		.filter((rule) => rule.type === REQUIRED_STATUS_CHECKS_RULE)
+		.flatMap((rule) => rule.parameters?.required_status_checks ?? [])
+		.map((check) => check.context)
+}
+
+async function fetch_required_contexts(branch_name: string): Promise<Array<string> | undefined> {
+	const raw_json = await git_gh_exec.exec_gh_api({
+		path: `${git_gh_api_path.branch_rules_api_path(branch_name)}${FULL_PAGE_QUERY}`,
+		should_paginate: true,
+	})
+	const rules = parse_json_array_or_undefined(raw_json, branch_rule_schema)
+
+	return rules === undefined ? undefined : to_required_contexts(rules)
+}
+
+async function read_required_contexts(branch_name: string | undefined): Promise<Array<string>> {
+	if (branch_name === undefined) return []
+	const cached = required_contexts_by_branch.get(branch_name)
+	if (cached !== undefined) return cached
+
+	try {
+		const contexts = await fetch_required_contexts(branch_name)
+		if (contexts === undefined) return []
+		required_contexts_by_branch.set(branch_name, contexts)
+
+		return contexts
+	} catch {
+		return []
+	}
+}
+
+const git_gh_branch_rules = { read_required_contexts }
+
+export { git_gh_branch_rules, read_required_contexts, forget_branch_rules }

package/scripts/gh/git-gh-conditional.ts

@@ -19,7 +19,8 @@ const ETAG_HEADER = /^etag: *(?<etag>[^\r\n]+)/imu
 type ConditionalRead =
 	| { kind: 'unchanged' }
 	| { kind: 'changed'; etag: string | undefined; body: string }
-	| { kind: 'unreadable' }
+	// `cause` is gh's own failure where there was one, for a caller that reports it.
+	| { kind: 'unreadable'; cause?: unknown }
 
 const UNCHANGED: ConditionalRead = { kind: 'unchanged' }
 const UNREADABLE: ConditionalRead = { kind: 'unreadable' }
@@ -56,7 +57,9 @@ async function read_conditional(
 	try {
 		return to_read(await git_gh_exec.exec_gh_command(to_args(path, etag), timeout_ms))
 	} catch (error) {
-		return failure_status(error) === NOT_MODIFIED_STATUS ? UNCHANGED : UNREADABLE
+		return failure_status(error) === NOT_MODIFIED_STATUS
+			? UNCHANGED
+			: { kind: 'unreadable', cause: error }
 	}
 }
 

package/scripts/gh/git-gh-issue-read.ts

@@ -281,7 +281,11 @@ async function issue_view_json(
 // `repo` reads a child in another repository. Cross-repository children are read this way rather
 // than from a local checkout: their state is a GitHub fact, and requiring a clone to learn it is
 // what kept the auto-close from ever running on such an epic.
-const STATE_AND_RELATIONS_FIELDS = 'number,state,labels,blockedBy'
+//
+// `body` rides along because `epic:next` holds a child until its declared start time
+// (joshuafolkken/kit#4007); the REST issue endpoint answers it in the same response, so it costs no
+// request.
+const STATE_AND_RELATIONS_FIELDS = 'number,state,labels,blockedBy,body'
 
 async function issue_get_state_and_relations(
 	issue_number: string,

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

@@ -71,6 +71,7 @@ const REST_FIELD_NAMES = new Map<string, string>([
 	['url', 'html_url'],
 	['createdAt', 'created_at'],
 	['closedAt', 'closed_at'],
+	['stateReason', 'state_reason'],
 	['updatedAt', 'updated_at'],
 ])
 

package/scripts/gh/git-gh-issue-write.ts

@@ -56,21 +56,39 @@ async function did_write_succeed(write: () => Promise<unknown>): Promise<boolean
 	}
 }
 
-async function issue_edit_body(issue_number: string, body: string): Promise<string> {
+async function issue_patch(
+	issue_number: string,
+	fields: Readonly<Record<string, string>>,
+	repo?: string,
+): Promise<string> {
 	return await git_gh_exec.exec_gh_api({
-		path: git_gh_api_path.issue_api_path(issue_number),
+		path: git_gh_api_path.issue_api_path(issue_number, repo),
 		method: PATCH_METHOD,
-		body: JSON.stringify({ body }),
+		body: JSON.stringify(fields),
 		jq_filter: HTML_URL_FILTER,
 	})
 }
 
+// The optional `repo` (`owner/name`) on these writes addresses an issue in another repository; left
+// out, the path keeps gh's `{owner}/{repo}` placeholder — the checkout's own repository.
+async function issue_edit_body(issue_number: string, body: string, repo?: string): Promise<string> {
+	return await issue_patch(issue_number, { body }, repo)
+}
+
+async function issue_edit_title(
+	issue_number: string,
+	title: string,
+	repo?: string,
+): Promise<string> {
+	return await issue_patch(issue_number, { title }, repo)
+}
+
 // **Every comment josh posts carries `RUN_MARKER`**, an HTML comment GitHub does not render. A run
 // posts under the person's own `gh` login, so the marker is the only thing that tells the issue watch
 // (`issue-watch-diff.ts`) a run's comment from a person's update.
-async function issue_comment(issue_number: string, body: string): Promise<string> {
+async function issue_comment(issue_number: string, body: string, repo?: string): Promise<string> {
 	return await git_gh_exec.exec_gh_api({
-		path: `${git_gh_api_path.issue_api_path(issue_number)}${COMMENTS_SEGMENT}`,
+		path: `${git_gh_api_path.issue_api_path(issue_number, repo)}${COMMENTS_SEGMENT}`,
 		body: JSON.stringify({ body: `${body}\n\n${issue_watch_diff.RUN_MARKER}` }),
 		jq_filter: HTML_URL_FILTER,
 	})
@@ -99,17 +117,25 @@ async function issue_try_comment(issue_number: string, body: string): Promise<bo
 // It is a required parameter that may be `undefined` rather than an optional one: skipping the
 // announcement is a decision the caller makes from what it read, never something a call site can
 // fall into by leaving an argument off.
-async function issue_close(issue_number: string, comment: string | undefined): Promise<boolean> {
+async function close_with(
+	issue_number: string,
+	comment: string | undefined,
+	state: Readonly<Record<string, string>>,
+): Promise<boolean> {
 	return await did_write_succeed(async () => {
 		if (comment !== undefined) await issue_comment(issue_number, comment)
 		await git_gh_exec.exec_gh_api({
 			path: git_gh_api_path.issue_api_path(issue_number),
 			method: PATCH_METHOD,
-			body: JSON.stringify({ state: CLOSED_STATE }),
+			body: JSON.stringify(state),
 		})
 	})
 }
 
+async function issue_close(issue_number: string, comment: string | undefined): Promise<boolean> {
+	return await close_with(issue_number, comment, { state: CLOSED_STATE })
+}
+
 // REST answers 422 `{"resource":"Label","code":"invalid","field":"color"}` for a color carrying a
 // leading `#`. The one caller passes the hash form (`EPIC_LABEL_COLOR`), so dropping it here is what
 // keeps that call site unchanged.
@@ -204,12 +230,16 @@ async function issue_create_with_label(input: {
 // say why it refused.
 type LabelWrite = { is_applied: true } | { is_applied: false; reason: string }
 
-// The issue's label names, read back after a failed write. A read that itself fails answers
-// `undefined`, which the caller treats as "not applied" — the write's own error is the reason then.
-async function read_label_names(issue_number: string): Promise<Array<string> | undefined> {
+// The issue's label names, every page of them — read back after a failed write, and by a pull
+// request's classification read. A read that itself fails answers `undefined`, which the write
+// treats as "not applied" — its own error is the reason then.
+async function read_label_names(
+	issue_number: string,
+	repo?: string,
+): Promise<Array<string> | undefined> {
 	try {
 		const raw = await git_gh_exec.exec_gh_api({
-			path: `${git_gh_api_path.issue_api_path(issue_number)}${LABELS_SEGMENT}`,
+			path: git_gh_api_path.issue_labels_api_path(issue_number, repo),
 			should_paginate: true,
 			jq_filter: LABEL_NAMES_FILTER,
 		})
@@ -226,15 +256,19 @@ async function read_label_names(issue_number: string): Promise<Array<string> | u
 // after the write or a secondary rate limit can each throw after the label landed — which refused a
 // lane dispatch whose label was in fact applied. So a throw is confirmed by
 // reading the labels back, and only a label that is really absent answers `is_applied: false`.
-async function issue_apply_label(issue_number: string, label: string): Promise<LabelWrite> {
-	const labels_path = `${git_gh_api_path.issue_api_path(issue_number)}${LABELS_SEGMENT}`
+async function issue_apply_label(
+	issue_number: string,
+	label: string,
+	repo?: string,
+): Promise<LabelWrite> {
+	const labels_path = git_gh_api_path.issue_labels_api_path(issue_number, repo)
 
 	try {
 		await git_gh_exec.exec_gh_api({ path: labels_path, body: JSON.stringify({ labels: [label] }) })
 
 		return { is_applied: true }
 	} catch (error) {
-		const names = await read_label_names(issue_number)
+		const names = await read_label_names(issue_number, repo)
 
 		if (names?.includes(label) === true) return { is_applied: true }
 		error_text.trace_swallowed('git_gh_issue_write.issue_apply_label', error)
@@ -250,8 +284,12 @@ async function issue_apply_label(issue_number: string, label: string): Promise<L
 // Applied after the body edit so a failure leaves an issue with the epic sections and no label,
 // which `epic:check` reports — rather than a labelled issue with nothing to track. The caller checks
 // the return: the label is what the auto-close filters on.
-async function issue_add_label(issue_number: string, label: string): Promise<boolean> {
-	const write = await issue_apply_label(issue_number, label)
+async function issue_add_label(
+	issue_number: string,
+	label: string,
+	repo?: string,
+): Promise<boolean> {
+	const write = await issue_apply_label(issue_number, label, repo)
 
 	return write.is_applied
 }
@@ -266,7 +304,7 @@ async function issue_add_label(issue_number: string, label: string): Promise<boo
 // a `false` swallowed here would reach that guard as a success and the step would be reported as
 // done.
 async function issue_remove_label(issue_number: string, label: string): Promise<void> {
-	const labels_path = `${git_gh_api_path.issue_api_path(issue_number)}${LABELS_SEGMENT}`
+	const labels_path = git_gh_api_path.issue_labels_api_path(issue_number)
 
 	await git_gh_exec.exec_gh_api({
 		path: `${labels_path}/${encodeURIComponent(label)}`,
@@ -274,6 +312,25 @@ async function issue_remove_label(issue_number: string, label: string): Promise<
 	})
 }
 
+// **The removal for a caller that wants the label gone, not removed by this call** — a release that
+// may find the label already off. A failed DELETE is confirmed against the labels the issue carries,
+// the read `issue_apply_label` confirms an addition with, so an absent label answers `true` and a
+// failure that left the label on answers `false`.
+async function issue_clear_label(issue_number: string, label: string): Promise<boolean> {
+	try {
+		await issue_remove_label(issue_number, label)
+
+		return true
+	} catch (error) {
+		const names = await read_label_names(issue_number)
+
+		if (names?.includes(label) === false) return true
+		error_text.trace_swallowed('git_gh_issue_write.issue_clear_label', error)
+
+		return false
+	}
+}
+
 // The blocker's **database id**, which is the only thing the dependencies endpoint accepts — and the
 // reason this resolution exists rather than the issue number being sent straight through.
 //
@@ -333,15 +390,18 @@ async function issue_remove_blocked_by(issue_number: string, blocker: string): P
 
 const git_gh_issue_write = {
 	issue_edit_body,
+	issue_edit_title,
 	issue_comment,
 	issue_try_comment,
 	issue_close,
 	label_ensure,
 	issue_create_request,
 	issue_create_with_label,
+	read_label_names,
 	issue_apply_label,
 	issue_add_label,
 	issue_remove_label,
+	issue_clear_label,
 	issue_add_blocked_by,
 	issue_remove_blocked_by,
 }

package/scripts/gh/git-gh-issue.ts

@@ -4,6 +4,9 @@ import { BLOCKED_BY_COUNT_FIELD } from './git-gh-issue-rest'
 import { git_gh_issue_write } from './git-gh-issue-write'
 
 const NUMBER_AND_BODY_FIELDS = 'number,body'
+// The label listing's fields. `stateReason` rides along on the same response: the epic auto-close
+// reads `reopened` off it, so its sweep leaves an epic a person reopened to them (#4564).
+const LABELLED_FIELDS = 'number,body,stateReason'
 // The backlog scan's fields. The title rides along because the pre-filing scan compares titles
 // and it costs nothing: the same listing request already carries it, so the
 // two consumers share one read rather than each making their own.
@@ -111,7 +114,7 @@ async function issue_search_body(term: string, limit: number): Promise<IssueList
 }
 
 async function issue_list_by_label(label: string, limit: number): Promise<IssueListOutcome> {
-	return await issue_list({ json_fields: NUMBER_AND_BODY_FIELDS, limit, label })
+	return await issue_list({ json_fields: LABELLED_FIELDS, limit, label })
 }
 
 // The same filter with the fields the `auto-ok` pickup needs: it orders by
@@ -151,8 +154,9 @@ async function issue_list_by_label_in_repo(
 }
 
 // Every open issue with what `josh auto-ok:judge` judges it by — its labels and body — and `updatedAt`,
-// so the backlog driver's resident check reads an issue's comments again only once it has moved.
-const JUDGEMENT_FIELDS = 'number,title,body,labels,updatedAt'
+// so the backlog driver's resident check reads an issue's comments again only once it has moved; and
+// `author_association` and `user`, so an issue a third party filed is never judged.
+const JUDGEMENT_FIELDS = 'number,title,body,labels,updatedAt,author_association,user'
 
 async function issue_list_open_for_judgement(limit: number): Promise<IssueListOutcome> {
 	return await issue_list({ json_fields: JUDGEMENT_FIELDS, limit })

package/scripts/gh/git-gh-poll-read.ts

@@ -0,0 +1,89 @@
+import { error_text } from '#scripts/lib/error-message'
+import { json_value } from '#scripts/lib/json-value'
+import { z } from 'zod'
+import { FULL_PAGE_QUERY } from './git-gh-api-path'
+import { git_gh_conditional, type ConditionalRead } from './git-gh-conditional'
+import { git_gh_exec } from './git-gh-exec'
+
+// The merge gate's per-poll reads, each sent with the ETag of this process's previous answer
+// (joshuafolkken/kit#4550).
+//
+// **Never a pull request's detail**: GitHub computes its `mergeable_state` lazily, under an unchanged
+// ETag, so a 304 would keep a stale state (joshuafolkken/kit#4589).
+//
+// **`pnpm josh followup` reads the same pull request every 10 seconds** while its checks run, and
+// every lane waiting on its merge does so at once. A `304 Not Modified` does not count against the
+// rate limit, so a poll that finds nothing changed costs only its pull detail read.
+//
+// **A listing is read one page at a time only while it fits in one.** A listing longer than a page is
+// read through `--paginate --slurp` as before; the conditional read cannot page, and a partial
+// listing would drop checks from the verdict.
+
+const UNREADABLE_POLL_MESSAGE = 'gh api could not read a merge-gate poll'
+const PAGE_SIZE = 100
+
+interface KeptAnswer {
+	etag: string
+	body: string
+}
+
+const kept_by_path = new Map<string, KeptAnswer>()
+
+const page_schema = z.object({ total_count: z.number() })
+
+// gh's own failure rides along as the cause and in the message: the poll loop's warning prints the
+// message alone, and a rate limit must read differently there from expired auth.
+function unreadable(path: string, answer: ConditionalRead): Error {
+	const cause = answer.kind === 'unreadable' ? answer.cause : undefined
+	const reason = cause === undefined ? '' : `: ${error_text.message_of(cause)}`
+
+	return new Error(`${UNREADABLE_POLL_MESSAGE}: ${path}${reason}`, { cause })
+}
+
+function to_body(path: string, answer: ConditionalRead): string {
+	const previous = kept_by_path.get(path)
+
+	if (previous !== undefined && answer.kind === 'unchanged') return previous.body
+	if (answer.kind !== 'changed') throw unreadable(path, answer)
+	if (answer.etag !== undefined) kept_by_path.set(path, { etag: answer.etag, body: answer.body })
+
+	return answer.body
+}
+
+// The answer for `path`, or the previous one where GitHub says it has not changed. A failure throws,
+// the contract the unconditional read had.
+async function read(path: string): Promise<string> {
+	const answer = await git_gh_conditional.read_conditional(path, kept_by_path.get(path)?.etag)
+
+	return to_body(path, answer)
+}
+
+// A page that does not parse as a listing is not taken as the whole one: the full read answers it, and
+// its own parser reports what it was.
+function is_whole_listing(page: string): boolean {
+	const total = json_value.parse_with(page, page_schema)?.total_count
+
+	return total !== undefined && total <= PAGE_SIZE
+}
+
+// A commit listing in the `--slurp` shape — an array of pages — however it was read.
+async function read_object_pages(path: string): Promise<string> {
+	const full_path = `${path}${FULL_PAGE_QUERY}`
+	const page = await read(full_path)
+
+	if (is_whole_listing(page)) return `[${page}]`
+
+	return await git_gh_exec.exec_gh_api({
+		path: full_path,
+		should_paginate: true,
+		should_slurp: true,
+	})
+}
+
+function forget_poll_reads(): void {
+	kept_by_path.clear()
+}
+
+const git_gh_poll_read = { UNREADABLE_POLL_MESSAGE, forget_poll_reads, read, read_object_pages }
+
+export { git_gh_poll_read }

package/scripts/gh/git-gh-pr-auto-merge.ts

@@ -17,8 +17,10 @@ import { git_gh_pr_rest, type RestPull } from './git-gh-pr-rest'
 const GRAPHQL_PATH = 'graphql'
 const OPEN_PULLS_QUERY = `${git_gh_api_path.FULL_PAGE_QUERY}&state=open`
 const MISSING_NODE_ID_MESSAGE = 'gh api answered a pull request without a node_id'
+// **`expectedHeadOid` binds the auto-merge to the commit the caller pushed** (#4036): GitHub then
+// refuses it if the head has moved, rather than landing a commit nobody here pushed or checked.
 const ENABLE_AUTO_MERGE_MUTATION =
-	'mutation($id: ID!) { enablePullRequestAutoMerge(input: { pullRequestId: $id, mergeMethod: MERGE }) { clientMutationId } }'
+	'mutation($id: ID!, $head: GitObjectID!) { enablePullRequestAutoMerge(input: { pullRequestId: $id, mergeMethod: MERGE, expectedHeadOid: $head }) { clientMutationId } }'
 
 interface OpenPull {
 	number: number
@@ -26,13 +28,16 @@ interface OpenPull {
 	has_auto_merge: boolean
 }
 
-async function pr_enable_auto_merge(branch_name: string): Promise<void> {
+async function pr_enable_auto_merge(branch_name: string, head_sha: string): Promise<void> {
 	const pull = await read_pull(await require_pr_number(branch_name))
 	if (pull.node_id === undefined) throw new Error(MISSING_NODE_ID_MESSAGE)
 
 	await git_gh_exec.exec_gh_api({
 		path: GRAPHQL_PATH,
-		body: JSON.stringify({ query: ENABLE_AUTO_MERGE_MUTATION, variables: { id: pull.node_id } }),
+		body: JSON.stringify({
+			query: ENABLE_AUTO_MERGE_MUTATION,
+			variables: { id: pull.node_id, head: head_sha },
+		}),
 	})
 }
 

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

@@ -27,7 +27,7 @@ import { MERGED_STATE, to_gh_state } from './git-gh-rest-state'
 // branch name that says nothing about which repository holds it. 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 })
+const rest_pull_side_schema = z.looseObject({ ref: z.string().optional(), repo: rest_repo_schema })
 
 type RestPullSide = z.infer<typeof rest_pull_side_schema>
 

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

@@ -1,7 +1,9 @@
 import { FULL_PAGE_QUERY, git_gh_api_path } from './git-gh-api-path'
+import { git_gh_branch_rules } from './git-gh-branch-rules'
 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_poll_read } from './git-gh-poll-read'
+import { require_pr_number } from './git-gh-pr-read'
+import { git_gh_pr_rest, 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'
@@ -19,17 +21,6 @@ import { to_gh_state } from './git-gh-rest-state'
 
 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> {
@@ -47,11 +38,12 @@ function read_head_sha(pull: RestPull): string {
 }
 
 // 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.
+// merged back into the single array `gh` answered with. Both endpoints answer an *object* wrapping the
+// listing, so their pages arrive slurped into one outer array (`git-gh-poll-read.ts`).
 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)),
+		git_gh_poll_read.read_object_pages(git_gh_api_path.commit_check_runs_api_path(commit_sha)),
+		git_gh_poll_read.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 })
@@ -69,10 +61,24 @@ async function pr_get_review_decision(pr_number: number): Promise<string> {
 // `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 CodeRabbit non-blocking exemption
 // keyed on `UNSTABLE`. The rule is shared with `to_pr_info` rather than written twice.
+//
+// **`headRefOid` is the commit the rollup was read from**, in `gh`'s spelling, so a merge can be bound
+// to the head whose checks passed rather than to whatever the branch points at by then (#4036).
+//
+// **`requiredContexts` is the base branch's required checks** (`git-gh-branch-rules.ts`), which the
+// merge gate reads to accept an `UNSTABLE` pull request held only by an optional check.
 async function build_checks_fields(pull: RestPull): Promise<Record<string, unknown>> {
+	const head_sha = read_head_sha(pull)
+	const [rollup, required_contexts] = await Promise.all([
+		read_status_check_rollup(head_sha),
+		git_gh_branch_rules.read_required_contexts(pull.base?.ref),
+	])
+
 	return {
-		statusCheckRollup: await read_status_check_rollup(read_head_sha(pull)),
+		statusCheckRollup: rollup,
 		mergeStateStatus: to_gh_state(pull.mergeable_state),
+		headRefOid: head_sha,
+		requiredContexts: required_contexts,
 	}
 }
 
@@ -81,12 +87,19 @@ interface ResolvedPull {
 	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.
+// The resolution and the detail read, which every path below needs. The branch → number memo in
+// `git-gh-pr-read.ts` makes the first free after the first poll.
+//
+// **The detail is read without an ETag.** GitHub computes `mergeable_state` lazily and can change it
+// under an unchanged ETag, so a 304 answered from the poll cache kept the gate reading a stale
+// `blocked` on a pull request that had turned `clean` (joshuafolkken/kit#4589).
 async function resolve_pull(branch_name: string): Promise<ResolvedPull> {
 	const pr_number = await require_pr_number(branch_name)
+	const json = await git_gh_exec.exec_gh_api({
+		path: git_gh_api_path.pull_api_path(String(pr_number)),
+	})
 
-	return { pr_number, pull: await read_pull(pr_number) }
+	return { pr_number, pull: git_gh_pr_rest.parse_rest_pull(json) }
 }
 
 // Everything the snapshot carries except the review decision: three requests rather than four.