@joshuafolkken/kit 1.1514.0 → 1.2114.0

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

@@ -36,7 +36,6 @@ const LABEL_NAMES_FILTER = '.[].name'
 const LABELS_SEGMENT = '/labels'
 const COMMENTS_SEGMENT = '/comments'
 const CLOSED_STATE = 'closed'
-const NOT_PLANNED_REASON = 'not_planned'
 const COLOR_HASH = '#'
 const UNPROCESSABLE_STATUS = 422
 const ALREADY_EXISTS_CODE = 'already_exists'
@@ -57,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,
 	})
@@ -81,8 +98,12 @@ async function issue_comment(issue_number: string, body: string): Promise<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.
@@ -119,18 +140,6 @@ async function issue_close(issue_number: string, comment: string | undefined): P
 	return await close_with(issue_number, comment, { state: CLOSED_STATE })
 }
 
-// The same close as "not planned" — the reason `issue-merged.ts` reads as no merge, so a closed issue
-// that was withdrawn is never taken for one whose work landed.
-async function issue_close_not_planned(
-	issue_number: string,
-	comment: string | undefined,
-): Promise<boolean> {
-	return await close_with(issue_number, comment, {
-		state: CLOSED_STATE,
-		state_reason: NOT_PLANNED_REASON,
-	})
-}
-
 // 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.
@@ -206,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,
 	}
 }
 
@@ -225,12 +236,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,
 		})
@@ -247,15 +262,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)
@@ -271,8 +290,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
 }
@@ -287,7 +310,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)}`,
@@ -295,6 +318,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.
 //
@@ -354,16 +396,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,
-	issue_close_not_planned,
 	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

@@ -1,9 +1,13 @@
+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'
 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.
@@ -23,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
@@ -31,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
@@ -59,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
@@ -111,7 +121,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 +161,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

@@ -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,16 +10,18 @@ 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
+// 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 +29,22 @@ interface OpenPull {
 	has_auto_merge: boolean
 }
 
-async function pr_enable_auto_merge(branch_name: string): Promise<void> {
-	const pull = await read_pull(await require_pr_number(branch_name))
+// 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_branch_pull(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 },
+		}),
 	})
 }
 
@@ -40,7 +52,7 @@ async function pr_enable_auto_merge(branch_name: string): Promise<void> {
 // 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 }

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

@@ -1,7 +1,10 @@
+import { error_text } from '#scripts/lib/error-message'
 import { FULL_PAGE_QUERY, git_gh_api_path } from './git-gh-api-path'
+import { note_unreadable_comments } from './git-gh-comments-unreadable'
 import { git_gh_exec } from './git-gh-exec'
 import { git_gh_helpers } from './git-gh-helpers'
 import { git_gh_pr_rest, type RestPull } from './git-gh-pr-rest'
+import { git_gh_pr_too_large } from './git-gh-pr-too-large'
 import { to_gh_state } from './git-gh-rest-state'
 
 // Reading pull requests through REST, in the answers `gh pr view` gives.
@@ -61,10 +64,16 @@ function lookup_path(branch_name: string): string {
 	return `${git_gh_api_path.pulls_api_path()}?head=${head}&${LOOKUP_QUERY}`
 }
 
-async function fetch_pr_number(branch_name: string): Promise<number | undefined> {
+async function fetch_branch_pull(branch_name: string): Promise<RestPull | undefined> {
 	const json = await git_gh_exec.exec_gh_api({ path: lookup_path(branch_name) })
 
-	return git_gh_pr_rest.select_pull(git_gh_pr_rest.parse_rest_pulls(json))?.number
+	return git_gh_pr_rest.select_pull(git_gh_pr_rest.parse_rest_pulls(json))
+}
+
+async function fetch_pr_number(branch_name: string): Promise<number | undefined> {
+	const pull = await fetch_branch_pull(branch_name)
+
+	return pull?.number
 }
 
 // Why the resolution produced no number. `missing` is the lookup answering: the listing came back and
@@ -80,7 +89,7 @@ interface PullMergeState {
 	is_merged: boolean
 	merged_at: string | undefined
 	head_sha: string | undefined
-	// `josh ship` reads `DIRTY` here to re-merge a conflicting pull request.
+	// GitHub's merge state (`DIRTY` on a conflict).
 	merge_state_status: string | undefined
 }
 
@@ -100,8 +109,8 @@ const pending_pr_number_by_branch = new Map<string, Promise<PullNumberRead>>()
 // same `GET /pulls/{N}` each time. The promise is stored, so readers in one tick share the request as
 // well as its answer; a read that fails is dropped and re-tried, the rule the number memo holds.
 // **Every write to a pull request clears it** through `forget_pr_numbers`, and the two state readers
-// never read it: `pr_get_merge_state` answers where the pull request stands *now*, which `josh ship`
-// asks again after every merge it pushes, and `pr_view` decides whether `josh git -y` writes onto the
+// never read it: `pr_get_merge_state` answers where the pull request stands *now*, which `josh followup`
+// asks again after every merge `josh ship` pushes, and `pr_view` decides whether `josh git -y` writes onto the
 // pull request — after a commit and a push its preflight read would otherwise outlast.
 const pull_by_number = new Map<number, Promise<RestPull>>()
 
@@ -168,9 +177,12 @@ async function resolve_pr_number(branch_name: string): Promise<number | undefine
 }
 
 // One definition, because both callers that refuse to fold an unreadable lookup raise it —
-// `require_pr_number` and `pr_exists`.
+// `require_pr_number` and `pr_exists`. The cause's first line rides in the message: a reader that
+// prints only the message — the `josh git -y` preflight, a `josh ship` log — still says why.
 function to_unreadable_error(branch_name: string, cause: unknown): Error {
-	return new Error(`${UNREADABLE_PULL_REQUEST_MESSAGE}: ${branch_name}`, { cause })
+	const [gist = ''] = error_text.message_of(cause).split('\n', 1)
+
+	return new Error(`${UNREADABLE_PULL_REQUEST_MESSAGE}: ${branch_name} (${gist})`, { cause })
 }
 
 // The number for a caller that has nothing to fold an absence into. The reads above answer their own
@@ -213,6 +225,36 @@ async function read_remembered_pull(pr_number: number): Promise<RestPull> {
 	}
 }
 
+// The listing row for a detail read GitHub refused as too large (`git-gh-pr-too-large.ts`). The row
+// carries neither `mergeable` nor `mergeable_state`, which every reader of them already takes as
+// "not known yet". Any other failure — and a listing that no longer names the number — stays the
+// detail read's own `unreadable`.
+async function read_listed_pull(
+	detail_error: unknown,
+	branch_name: string,
+	pr_number: number,
+): Promise<RestPull | undefined> {
+	if (!git_gh_pr_too_large.is_too_many_files(detail_error)) return undefined
+	const pull = await fetch_branch_pull(branch_name)
+
+	return pull?.number === pr_number ? pull : undefined
+}
+
+async function read_pull_or_listed(
+	branch_name: string,
+	pr_number: number,
+	read: (pr_number: number) => Promise<RestPull>,
+): Promise<RestPull> {
+	try {
+		return await read(pr_number)
+	} catch (error) {
+		const listed = await read_listed_pull(error, branch_name, pr_number)
+		if (listed === undefined) throw error
+
+		return listed
+	}
+}
+
 // One pull request named by its branch: the resolution, then the detail read that carries
 // `mergeable` and `mergeable_state`, which the lookup listing does not.
 async function read_pull_of_branch(
@@ -223,7 +265,10 @@ async function read_pull_of_branch(
 	if (number_read.kind !== 'read') return number_read
 
 	try {
-		return { kind: 'read', pull: await read(number_read.pr_number) }
+		return {
+			kind: 'read',
+			pull: await read_pull_or_listed(branch_name, number_read.pr_number, read),
+		}
 	} catch (error) {
 		return { kind: 'unreadable', cause: error }
 	}
@@ -301,25 +346,39 @@ async function pr_view(branch_name: string): Promise<string> {
 	return JSON.stringify(git_gh_pr_rest.to_pr_info(read.pull))
 }
 
+// gh's own reason for a lookup that never answered, or that the branch has no pull request at all.
+function unresolved_reason(read: Exclude<PullNumberRead, { kind: 'read' }>): string {
+	return read.kind === 'unreadable' ? error_text.message_of(read.cause) : NO_PULL_REQUEST_MESSAGE
+}
+
 // `undefined` when the listing could not be read — a failed request, or a PR whose number could not
 // be resolved. Not `'[]'`.
 //
 // The two are the same string to a caller, and the callers are the merge gate: a rate limit would
 // arrive as "no reviewer left a finding" and the PR merge with the gate never actually read.
 // The direction is what makes it worse than the epic auto-close's version of
-// the same misread — that one only failed to close something.
+// the same misread — that one only failed to close something. Either failure warns its reason
+// (`git-gh-comments-unreadable.ts`).
 async function read_comments(
 	branch_name: string,
 	to_path: (pr_number: string) => string,
 	to_json: (raw: string) => string,
 ): Promise<string | undefined> {
-	const pr_number = await resolve_pr_number(branch_name)
-	if (pr_number === undefined) return undefined
-	const path = `${to_path(String(pr_number))}${COMMENTS_QUERY}`
+	const read = await read_pr_number(branch_name)
+
+	if (read.kind !== 'read') {
+		note_unreadable_comments(branch_name, unresolved_reason(read))
+
+		return undefined
+	}
+
+	const path = `${to_path(String(read.pr_number))}${COMMENTS_QUERY}`
 
 	try {
 		return to_json(await git_gh_exec.exec_gh_api({ path, should_paginate: true }))
-	} catch {
+	} catch (error) {
+		note_unreadable_comments(branch_name, error_text.message_of(error))
+
 		return undefined
 	}
 }
@@ -362,7 +421,9 @@ export type { PullMergeState }
 export {
 	git_gh_pr_read,
 	forget_pr_numbers,
+	read_listed_pull,
 	read_pull,
+	read_pull_or_listed,
 	require_pr_number,
 	resolve_pr_number,
 	NO_PULL_REQUEST_MESSAGE,