@joshuafolkken/kit 1.1784.0 → 1.2114.0

package/scripts/gate/verification-inputs.ts

@@ -2,7 +2,7 @@ import { readFileSync } from 'node:fs'
 import path from 'node:path'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
 import { lint_related_scope } from '#scripts/lint/lint-related-scope'
-import { gate_plan } from './gate-plan'
+import { gate_labels } from './gate-labels'
 import { input_fingerprint } from './input-fingerprint'
 import { toolchain_inputs } from './toolchain-inputs'
 
@@ -169,12 +169,27 @@ function compiled(is_input: FileTest): InputDeclaration {
 	}
 }
 
+// **cspell reads every file with dotfiles**, so any moved file — its config and word lists among
+// them — answers "run again" (joshuafolkken/kit#5156).
+async function is_any_file(): Promise<boolean> {
+	return true
+}
+
+const SPELLING: InputDeclaration = {
+	is_input: is_any_file,
+	reads: 'matched',
+	is_config: configures_toolchain,
+	tools: ['cspell'],
+	env: COMMON_ENV,
+}
+
 const DECLARATIONS: ReadonlyMap<string, InputDeclaration> = new Map([
-	[gate_plan.LINT_LABEL, LINT],
-	[gate_plan.TYPE_CHECK_LABEL, compiled(is_source_input)],
-	[gate_plan.EXPORTS_LABEL, compiled(is_source_input)],
-	[gate_plan.METRICS_LABEL, compiled(is_metrics_input)],
-	[gate_plan.UNIT_LABEL, UNIT],
+	[gate_labels.LINT_LABEL, LINT],
+	[gate_labels.SPELL_CHECK_LABEL, SPELLING],
+	[gate_labels.TYPE_CHECK_LABEL, compiled(is_source_input)],
+	[gate_labels.EXPORTS_LABEL, compiled(is_source_input)],
+	[gate_labels.METRICS_LABEL, compiled(is_metrics_input)],
+	[gate_labels.UNIT_LABEL, UNIT],
 ])
 
 function declaration_of(label: string): InputDeclaration | undefined {

package/scripts/gate/verification-tail.ts

@@ -0,0 +1,52 @@
+import { status_icons } from '#scripts/lib/status-icons'
+import { gate_log } from './gate-log'
+
+// The end every josh verification check prints, in one place (joshuafolkken/kit#5162).
+//
+// **A run pipes a check into `tail` because the end is the answer.** Over 4,145 piped calls, 85% were a
+// `tail -N` and most of the rest a `grep` for `FAIL`, `error` or a `✓`/`✗` — the run wanted to know
+// whether the check passed and what to look at if it did not. `josh gate` already ended that way, while
+// `lint:related` printed no verdict at all and `test:related` printed one only on a failure, so the run
+// kept inventing the filter. Every check now ends with the same three parts, built here:
+//
+// 1. what failed and what to run next — nothing on a green run;
+// 2. where the whole output was kept (`gate-log.ts`), for a check that keeps one;
+// 3. the verdict, always the last line, for the reason `josh-verdict.ts` gives.
+
+const { FAIL_ICON, PASS_ICON } = status_icons
+
+// Where the whole output went: `path` is `undefined` when the write failed, which the notice says.
+interface KeptLog {
+	path: string | undefined
+}
+
+interface VerificationTail {
+	// The lines above the log notice, each ending in a newline; empty on a green run.
+	failures: string
+	// Absent where the console is the only copy of the output.
+	log?: KeptLog | undefined
+	verdict: string
+}
+
+// `✓ <command> passed` or `✗ <command> failed: <what failed>`.
+function format_verdict(command: string, failed: ReadonlyArray<string>): string {
+	if (failed.length === 0) return `${PASS_ICON} ${command} passed`
+
+	return `${FAIL_ICON} ${command} failed: ${failed.join(', ')}`
+}
+
+// One failure and the command that reproduces it, as `josh gate` names its failed checks.
+function format_rerun(label: string, command: string): string {
+	return `  ${FAIL_ICON} ${label} — re-run: ${command}`
+}
+
+function format_tail(tail: VerificationTail): string {
+	const notice = tail.log === undefined ? '' : gate_log.format_log_notice(tail.log.path)
+
+	return `${tail.failures}${notice}${tail.verdict}\n`
+}
+
+const verification_tail = { format_rerun, format_tail, format_verdict }
+
+export type { KeptLog, VerificationTail }
+export { verification_tail }

package/scripts/gh/gh-author-association.ts

@@ -1,5 +1,6 @@
 import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { author_fields_schema } from '#scripts/git/git-schemas'
 import { parse_json } from '#scripts/git/parse-json-array'
 import { z } from 'zod'
 
@@ -20,6 +21,9 @@ const WRITE_ROLES: ReadonlySet<string> = new Set(['admin', 'maintain', 'write'])
 // path, so anything else (a `[bot]` login, a slash) is refused before a request is made.
 const LOGIN_PATTERN = /^[\da-z](?:[\w-]*[\da-z])?$/iu
 const TRUSTED_LIST = 'OWNER, or MEMBER / COLLABORATOR with write access'
+// The REST fields that name who wrote an issue, asked beside its body by every reader that decides
+// whether to act on that body; `author_fields_schema` is the shape they parse to.
+const AUTHOR_FIELDS = 'author_association,user'
 
 const permission_schema = z.looseObject({
 	permission: z.string().nullish(),
@@ -33,6 +37,11 @@ interface Author {
 	timeout_ms?: number | undefined
 }
 
+interface AuthorFields {
+	author_association?: string | null | undefined
+	user?: { login: string } | null | undefined
+}
+
 const answers = new Map<string, Promise<boolean | undefined>>()
 
 function permission_path(login: string): string {
@@ -95,7 +104,19 @@ async function is_trusted(author: Author): Promise<boolean> {
 	return (await trust_of(author)) === true
 }
 
-const gh_author_association = { TRUSTED_LIST, is_trusted, trust_of }
+// The author of a row read with `AUTHOR_FIELDS`.
+function author_of(row: AuthorFields, timeout_ms?: number): Author {
+	return { login: row.user?.login, association: row.author_association, timeout_ms }
+}
+
+const gh_author_association = {
+	AUTHOR_FIELDS,
+	TRUSTED_LIST,
+	author_fields_schema,
+	author_of,
+	is_trusted,
+	trust_of,
+}
 
-export type { Author }
+export type { Author, AuthorFields }
 export { gh_author_association }

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

@@ -149,5 +149,5 @@ function classify_ai_review_comments(comments: ReadonlyArray<ReviewComment>): Cl
 	}
 }
 
-export { classify_ai_review_comments }
+export { classify_ai_review_comments, is_coderabbit_author, is_coderabbit_rate_limit }
 export type { ReviewComment, ClassifiedFinding, ClassifiedFindings, FindingKind }

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

@@ -99,20 +99,28 @@ function commit_status_api_path(commit_sha: string, repo?: string): string {
 
 // The rules that apply to one branch, from every ruleset that targets it — readable without the
 // admin access the classic branch protection endpoint needs.
+// Ref names are encoded as one segment: a `?` or `#` would otherwise end the path, and GitHub reads
+// an encoded `/` back as part of the branch name.
 function branch_rules_api_path(branch_name: string, repo?: string): string {
-	return `${repo_api_path(repo)}/rules/branches/${branch_name}`
+	return `${repo_api_path(repo)}/rules/branches/${encodeURIComponent(branch_name)}`
+}
+
+// The status checks classic branch protection requires — the half of the required checks rulesets
+// do not carry.
+function branch_protection_checks_api_path(branch_name: string, repo?: string): string {
+	return `${repo_api_path(repo)}/branches/${encodeURIComponent(branch_name)}/protection/required_status_checks`
 }
 
 // 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 {
-	return `${repo_api_path(repo)}/git/ref/tags/${tag}`
+	return `${repo_api_path(repo)}/git/ref/tags/${encodeURIComponent(tag)}`
 }
 
 // The GitHub Release published for one tag. REST answers 404 until `publish.yml`'s `create-release`
 // job has run, which is what the release command's progress watch asks.
 function release_by_tag_api_path(tag: string, repo?: string): string {
-	return `${repo_api_path(repo)}/releases/tags/${tag}`
+	return `${repo_api_path(repo)}/releases/tags/${encodeURIComponent(tag)}`
 }
 
 const git_gh_api_path = {
@@ -134,6 +142,7 @@ const git_gh_api_path = {
 	commit_check_runs_api_path,
 	commit_status_api_path,
 	branch_rules_api_path,
+	branch_protection_checks_api_path,
 }
 
 export { git_gh_api_path, FULL_PAGE_QUERY }

package/scripts/gh/git-gh-comments-unreadable.ts

@@ -0,0 +1,36 @@
+// A pull request comment listing that could not be read (joshuafolkken/kit#5012).
+//
+// The reader warns with gh's reason, never swallowing it. Only the AI review gate stops on the
+// unreadable listing — a CodeRabbit listing that could not be read is a note the followup carries
+// past — so the gate alone prints `UNREADABLE_COMMENTS_STOP` on the standard output, which `josh ship`
+// reads as the infrastructure and re-runs the followup on in place rather than relaunching the lane.
+// Its own module, so the ship's stop classification reads the note without loading the gate.
+
+const UNREADABLE_COMMENTS_STOP = 'the merge gate stopped on reviewer comments it could not read'
+
+// Set by `josh ship` around an attempt it will run again on an infrastructure stop
+// (`run-ship-infra-retry.ts`): the gate's `confirmation` then waits for the final attempt, so a read
+// that recovers sends none and one that never does sends one.
+const RETRY_PENDING_KEY = 'JOSH_SHIP_RETRY_PENDING'
+const RETRY_PENDING_VALUE = '1'
+
+function note_unreadable_comments(branch_name: string, reason: string): void {
+	console.warn(`⚠ pull request comments could not be read for ${branch_name}: ${reason}`)
+}
+
+function note_unreadable_stop(): void {
+	console.info(`⚠️ ${UNREADABLE_COMMENTS_STOP}`)
+}
+
+function is_retry_pending(): boolean {
+	return process.env[RETRY_PENDING_KEY] === RETRY_PENDING_VALUE
+}
+
+export {
+	is_retry_pending,
+	note_unreadable_comments,
+	note_unreadable_stop,
+	RETRY_PENDING_KEY,
+	RETRY_PENDING_VALUE,
+	UNREADABLE_COMMENTS_STOP,
+}

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

@@ -1,9 +1,11 @@
 import { has_timed_out } from '#scripts/git/git-execa-error'
 import { agent_session_environment } from '#scripts/josh/agent-session-environment'
 import { error_text } from '#scripts/lib/error-message'
+import { token_shape } from '#scripts/lib/token-shape'
 import { execa, execaSync } from 'execa'
 import { check_gh_installed } from './git-gh-check'
 import { gh_failure } from './git-gh-failure'
+import { gh_retry } from './git-gh-retry'
 
 const BODY_FROM_STDIN = '-'
 
@@ -258,6 +260,7 @@ const INPUT_FLAG = '--input'
 const PAGINATE_FLAG = '--paginate'
 const SLURP_FLAG = '--slurp'
 const JQ_FLAG = '--jq'
+const ALLOW_ESCAPES_FLAG = '--allow-escape-sequences'
 
 // One REST request through `gh api`. `path` is the only required field: a read names nothing else,
 // because `gh api` sends GET when neither `--method` nor a request body is given. **A `body` alone
@@ -292,16 +295,32 @@ interface GhApiRequest {
 	// The checkout gh runs in, which is what `{owner}/{repo}` in `path` resolves against. Absent means
 	// the process's own directory.
 	cwd?: string
+	// `false` for a write that must not be sent twice: a transient failure may follow a write that
+	// already landed, and nothing reads it back (`git-gh-retry.ts`). Absent means retried.
+	should_retry?: boolean
+	// `true` for a plain-text body that carries terminal colors, such as an Actions job log: gh refuses
+	// to print one off a terminal without `--allow-escape-sequences`.
+	should_allow_escapes?: boolean
 }
 
 function optional_flag(flag: string, value?: string): Array<string> {
 	return value === undefined ? [] : [flag, value]
 }
 
+// Every Issue and pull-request body kit writes travels through the two entries below, so a credential
+// pasted into one is refused here, once, before it reaches a public tracker. The writers pass the body
+// JSON-encoded, so it is scanned decoded.
+function refuse_credential_body(request: GhApiRequest): void {
+	if (request.body !== undefined) {
+		token_shape.refuse(token_shape.decoded(request.body), `The gh api ${request.path} body`)
+	}
+}
+
 function to_gh_api_args(request: GhApiRequest): Array<string> {
 	const body_args = request.body === undefined ? [] : [INPUT_FLAG, BODY_FROM_STDIN]
 	const paginate_args = request.should_paginate === true ? [PAGINATE_FLAG] : []
 	const slurp_args = request.should_slurp === true ? [SLURP_FLAG] : []
+	const escape_args = request.should_allow_escapes === true ? [ALLOW_ESCAPES_FLAG] : []
 
 	return [
 		'api',
@@ -310,6 +329,7 @@ function to_gh_api_args(request: GhApiRequest): Array<string> {
 		...body_args,
 		...paginate_args,
 		...slurp_args,
+		...escape_args,
 		...optional_flag(JQ_FLAG, request.jq_filter),
 	]
 }
@@ -320,8 +340,9 @@ function to_gh_api_args(request: GhApiRequest): Array<string> {
 // `read_gh_api_sync` below.
 //
 // Failure handling funnels through `to_gh_error` on both paths below, so a failed request throws
-// with gh's stderr summary *and* the JSON error body it wrote to stdout.
-async function exec_gh_api(request: GhApiRequest): Promise<string> {
+// with gh's stderr summary *and* the JSON error body it wrote to stdout. A transient failure — a 5xx
+// or no answer at all — is asked again a bounded number of times first (`git-gh-retry.ts`).
+async function send_gh_api(request: GhApiRequest): Promise<string> {
 	const args = to_gh_api_args(request)
 
 	if (request.body === undefined) {
@@ -336,6 +357,14 @@ async function exec_gh_api(request: GhApiRequest): Promise<string> {
 	})
 }
 
+async function exec_gh_api(request: GhApiRequest): Promise<string> {
+	refuse_credential_body(request)
+
+	if (request.should_retry === false) return await send_gh_api(request)
+
+	return await gh_retry.with_retry(async () => await send_gh_api(request))
+}
+
 // The synchronous twin of `exec_gh_api`, for a caller that cannot await. `josh propagate` runs each
 // consumer's steps as a sequential chain of `execaSync` spawns with inherited stdio, and that shape
 // reaches from `open_issue` up through `RunStep`, `run_target` and `run_targets` — so the issue it
@@ -357,6 +386,7 @@ async function exec_gh_api(request: GhApiRequest): Promise<string> {
 // the spawn's own failure and is reported like any other, which is what the direct spawn this
 // replaced already did.
 function exec_gh_api_sync(request: GhApiRequest): string {
+	refuse_credential_body(request)
 	const body_option = request.body === undefined ? {} : { input: request.body }
 	const options = { ...body_option, ...to_spawn_options(request.timeout_ms, request.cwd) }
 

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

@@ -1,4 +1,5 @@
 import type { IssueReference } from '#scripts/issue/issue-reference'
+import { gh_author_association } from './gh-author-association'
 import { git_gh_api_path } from './git-gh-api-path'
 import { git_gh_exec } from './git-gh-exec'
 import { gh_failure, type GhFailure } from './git-gh-failure'
@@ -284,8 +285,9 @@ async function issue_view_json(
 //
 // `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'
+// request. The author rides along for the same reason: `backlog:next` runs a child's body only when
+// its author has write access (joshuafolkken/kit#4633), and the same response already names them.
+const STATE_AND_RELATIONS_FIELDS = `number,state,labels,blockedBy,body,${gh_author_association.AUTHOR_FIELDS}`
 
 async function issue_get_state_and_relations(
 	issue_number: string,

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

@@ -26,6 +26,7 @@ import { MERGED_STATE, to_gh_state } from './git-gh-rest-state'
 // readily as an issue, so it stays optional and tolerates an explicit null.
 const rest_issue_schema = z.looseObject({
 	number: z.number(),
+	body: z.string().nullish(),
 	issue_dependencies_summary: z.looseObject({ total_blocked_by: z.number().optional() }).nullish(),
 	// Present only on a pull request, which this endpoint serves as readily as an issue.
 	pull_request: z.looseObject({ merged_at: z.string().nullish() }).nullish(),

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

@@ -98,8 +98,12 @@ async function issue_comment(issue_number: string, body: string, repo?: string):
 // **after** the epic body already carries the record, so a refused comment costs that child's copy and
 // nothing else — an exception there would leave the caller unable to tell a landed insertion from one
 // that wrote nothing.
-async function issue_try_comment(issue_number: string, body: string): Promise<boolean> {
-	return await did_write_succeed(async () => await issue_comment(issue_number, body))
+async function issue_try_comment(
+	issue_number: string,
+	body: string,
+	repo?: string,
+): Promise<boolean> {
+	return await did_write_succeed(async () => await issue_comment(issue_number, body, repo))
 }
 
 // `gh issue close --comment` posted the comment and closed the issue in one call; REST splits them.
@@ -211,6 +215,8 @@ function issue_create_request(input: {
 			body: input.body,
 		}),
 		jq_filter: HTML_URL_FILTER,
+		// A 502 can follow an issue GitHub already opened, and a retry would open a second one.
+		should_retry: false,
 	}
 }
 

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

@@ -1,3 +1,4 @@
+import { gh_author_association } from './gh-author-association'
 import { git_gh_issue_list, type IssueListOutcome } from './git-gh-issue-list'
 import { git_gh_issue_read } from './git-gh-issue-read'
 import { BLOCKED_BY_COUNT_FIELD } from './git-gh-issue-rest'
@@ -26,7 +27,8 @@ const BACKLOG_SCAN_FIELDS = `number,title,body,labels,${BLOCKED_BY_COUNT_FIELD}`
 // gets that from the epic listing, which by construction holds no closed epic.
 const NUMBER_TITLE_AND_LABELS_FIELDS = 'number,title,labels'
 // The fields every listing that is *ranked* asks for: `createdAt` to order by and `labels` to
-// exclude by. Shared by the next-issues display and the `auto-ok` pickup, which rank identically.
+// exclude by. Shared by the next-issues display and the `auto-ok` pickup, which rank identically —
+// each adds `body` for the causing-lane key.
 const SUMMARY_FIELDS = 'number,title,labels,createdAt'
 // The pickup's list, which is the display's plus the native blocker relation. Kept apart from
 // `SUMMARY_FIELDS` on purpose: a listing carries no `blockedBy`, so the field is answered from each
@@ -34,8 +36,9 @@ const SUMMARY_FIELDS = 'number,title,labels,createdAt'
 // behind the next-issues display too — where a refused one becomes a failure with no message at all,
 // since the listing swallows the error. `body` costs
 // no request — the REST listing row already carries it — and is what the backlog offer reads for
-// the paths each issue declares.
-const PICKUP_FIELDS = `${SUMMARY_FIELDS},blockedBy,body`
+// the paths each issue declares. The author fields are the same row's too, and decide whether an
+// unattended run may act on that body at all.
+const PICKUP_FIELDS = `${SUMMARY_FIELDS},blockedBy,body,${gh_author_association.AUTHOR_FIELDS}`
 
 // Every listing below goes through the one REST invocation in `git-gh-issue-list.ts`. It kept the
 // `json_fields` / `limit` contract it had as a `gh issue list` wrapper, so these callers changed
@@ -62,9 +65,13 @@ const PICKUP_FIELDS = `${SUMMARY_FIELDS},blockedBy,body`
 const { issue_list } = git_gh_issue_list
 
 // The newest open issues, for the next-issues display at workflow completion. `createdAt`
-// rides along because the caller re-sorts explicitly rather than inheriting the listing's order.
+// rides along because the caller re-sorts explicitly rather than inheriting the listing's order, and
+// `body` because the ranking reads its causing-lane minutes — without it the display would order a
+// priority differently from the pickup (joshuafolkken/kit#4859). It adds no listing request, as
+// above; `backlog:plan`'s read now also hands the bodies to `issue_sample_prime.prime`, which reads
+// the pull requests they cite.
 async function issue_list_recent(limit: number): Promise<IssueListOutcome> {
-	return await issue_list({ json_fields: SUMMARY_FIELDS, limit })
+	return await issue_list({ json_fields: `${SUMMARY_FIELDS},body`, limit })
 }
 
 // Every open issue with its title and body. Used by `epic:bundle` to scan the backlog and by

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

@@ -1,7 +1,8 @@
 import { error_text } from '#scripts/lib/error-message'
 import { 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 { GRAPHQL_PATH } from './git-gh-pr-graphql-state'
+import { read_pull, read_pull_or_listed, require_pr_number } from './git-gh-pr-read'
 import { git_gh_pr_rest, type RestPull } from './git-gh-pr-rest'
 
 // Auto-merge for a pull request a josh command opens and would otherwise have to stay alive to land.
@@ -9,12 +10,12 @@ import { git_gh_pr_rest, type RestPull } from './git-gh-pr-rest'
 // inside its own wait, so a wait that ended early — a session cut, a killed process — left a green
 // pull request open with nobody to merge it.
 //
-// **This is the one GraphQL request in the pull-request layer, because REST has no equivalent.**
-// Enabling auto-merge is `enablePullRequestAutoMerge` and nothing else. A cloud session can be
+// **This is a GraphQL request because REST has no equivalent** — the pull-request layer's only other
+// one is `git-gh-pr-graphql-state.ts`. Enabling auto-merge is `enablePullRequestAutoMerge` and
+// nothing else. A cloud session can be
 // answered 403 for GraphQL, so the caller treats a failure here as a lost
 // safety net rather than a failed command — the in-process wait still merges as it always did.
 
-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
@@ -28,8 +29,14 @@ interface OpenPull {
 	has_auto_merge: boolean
 }
 
+// The listing row stands in for a detail GitHub refuses as too many files changed: both carry
+// `node_id` and `merged_at`, which is all the two readers below need (`git-gh-pr-too-large.ts`).
+async function read_branch_pull(branch_name: string): Promise<RestPull> {
+	return await read_pull_or_listed(branch_name, await require_pr_number(branch_name), read_pull)
+}
+
 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))
+	const pull = await read_branch_pull(branch_name)
 	if (pull.node_id === undefined) throw new Error(MISSING_NODE_ID_MESSAGE)
 
 	await git_gh_exec.exec_gh_api({
@@ -45,7 +52,7 @@ async function pr_enable_auto_merge(branch_name: string, head_sha: string): Prom
 // next attempt asks again, and running out of attempts is what ends the wait.
 async function pr_is_merged(branch_name: string): Promise<boolean> {
 	try {
-		return git_gh_pr_rest.is_merged(await read_pull(await require_pr_number(branch_name)))
+		return git_gh_pr_rest.is_merged(await read_branch_pull(branch_name))
 	} catch (error) {
 		error_text.trace_swallowed('git_gh_pr_auto_merge.pr_is_merged', error)
 

package/scripts/gh/git-gh-pr-graphql-state.ts

@@ -0,0 +1,56 @@
+import { parse_json_object_or_undefined } from '#scripts/git/parse-json-array'
+import { z } from 'zod'
+import { git_gh_exec } from './git-gh-exec'
+import type { RestPull } from './git-gh-pr-rest'
+
+// `mergeStateStatus` for a pull request whose single-pull REST read GitHub refuses as too many files
+// changed (`git-gh-pr-too-large.ts`). The listing row that stands in for that read carries no
+// `mergeable_state`, and the merge gate never reads an unknown state as clean — it would wait out its
+// whole budget. GraphQL still answers for the same pull request, so the state is read there.
+//
+// **A failure is a stop with its reason, never a guess.** A cloud session is answered 403 for
+// GraphQL; the merge gate then has no way to judge the pull request, and says so.
+
+const GRAPHQL_PATH = 'graphql'
+
+const MERGE_STATE_QUERY =
+	'query($id: ID!) { node(id: $id) { ... on PullRequest { mergeStateStatus } } }'
+
+const NO_MERGE_STATE_MESSAGE =
+	'The merge state cannot be judged: GitHub refuses this pull request as too many files changed, and GraphQL did not answer its mergeStateStatus'
+
+const merge_state_node_schema = z.looseObject({ mergeStateStatus: z.string() })
+const merge_state_data_schema = z.looseObject({ node: merge_state_node_schema })
+const merge_state_response_schema = z.looseObject({ data: merge_state_data_schema })
+
+async function query_merge_state(node_id: string): Promise<string | undefined> {
+	const json = await git_gh_exec.exec_gh_api({
+		path: GRAPHQL_PATH,
+		body: JSON.stringify({ query: MERGE_STATE_QUERY, variables: { id: node_id } }),
+	})
+
+	return parse_json_object_or_undefined(json, merge_state_response_schema)?.data.node
+		.mergeStateStatus
+}
+
+async function try_query_merge_state(node_id: string | undefined): Promise<string | undefined> {
+	if (node_id === undefined) return undefined
+
+	try {
+		return await query_merge_state(node_id)
+	} catch {
+		return undefined
+	}
+}
+
+// `detail_error` is the 422 that sent the read here, kept as the cause so the stop names it.
+async function read_merge_state_status(listed: RestPull, detail_error: unknown): Promise<string> {
+	const state = await try_query_merge_state(listed.node_id)
+	if (state === undefined) throw new Error(NO_MERGE_STATE_MESSAGE, { cause: detail_error })
+
+	return state
+}
+
+const git_gh_pr_graphql_state = { read_merge_state_status }
+
+export { git_gh_pr_graphql_state, GRAPHQL_PATH, MERGE_STATE_QUERY, NO_MERGE_STATE_MESSAGE }