@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,457 @@
+import type { IssueReference } from './git-epic-reference'
+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'
+import { git_gh_helpers } from './git-gh-helpers'
+import {
+	BLOCKED_BY_FIELD,
+	git_gh_issue_rest,
+	type BlockedBy,
+	type RestIssue,
+} from './git-gh-issue-rest'
+import { gh_reachability } from './git-gh-reachability'
+
+// Reading one issue. Split out of `git-gh-issue.ts`, which had grown past the file-length limit
+// while holding both the reads and the writes; the reads are what every epic command goes through,
+// and telling a number that resolves to nothing from a read that failed belongs with them
+// (joshuafolkken/kit#957).
+
+// The blocker relations, which REST serves from their own endpoint rather than inside the issue.
+// `gh issue view --json blockedBy` answered them in the same response because GraphQL selects them
+// as a connection; REST needs a second request (joshuafolkken/kit#1024).
+//
+// One page of a hundred — `FULL_PAGE_QUERY`, the same one every other listing here asks for — where
+// GraphQL asked for `blockedBy(first:50)`, so `nodes` is at least as complete as it was, while
+// `totalCount` comes from the issue's own dependency summary and stays exact whatever the page
+// holds. The endpoint itself is named in `git-gh-api-path.ts`, which the two writes address as well
+// (joshuafolkken/kit#1026).
+//
+// joshuafolkken/kit#1113 split this out for the one caller that may not consult the summary the
+// wrapper below trusts: the summary is GitHub's own count and it can disagree with the listing it
+// counts. Measured on joshuafolkken/kit#1111, whose `issue_dependencies_summary` read
+// `total_blocked_by: 0` while this endpoint returned `#1106` — and re-POSTing that relation was
+// refused with `Target issue has already been taken`, so the relation was real and only the counter
+// was wrong. `epic:next` then called a graph that agreed with itself contradictory and exited 1,
+// which stops an unattended run at its first step with nothing to fix.
+async function read_blocked_by_listing(
+	issue_number: string,
+	repo?: string,
+	exact_total?: number,
+): Promise<BlockedBy> {
+	const json = await git_gh_exec.exec_gh_api({
+		path: `${git_gh_api_path.blocked_by_api_path(issue_number, repo)}${git_gh_api_path.FULL_PAGE_QUERY}`,
+	})
+
+	return git_gh_issue_rest.to_blocked_by(json, exact_total)
+}
+
+// The same relations, with the request skipped when the issue's own summary says the count is zero.
+// That skip is the common case and the one that matters for cost: `epic:bundle` reads relations for
+// the whole open backlog, up to two hundred issues, and every one of those reads names `blockedBy`.
+// Without it the pass would be four hundred requests where `gh` made two hundred — which is why
+// joshuafolkken/kit#1113 left it in place and gave the rare path its own entry point above rather
+// than making every read pay for it.
+//
+// A pull request is skipped ahead of that, structurally rather than on a count. It carries no
+// `issue_dependencies_summary` at all, and an absent summary is deliberately not read as a zero — so
+// the numeric skip cannot fire for one, and the endpoint was asked every time. GitHub answers an
+// empty array today, but a 404 there would fail the whole read and `epic:bundle` would report the
+// reference as `unreadable` **before** the `/pull/` check that drops it (joshuafolkken/kit#947) ever
+// ran. The guard rested on API behavior nobody controls; this makes it a fact about pull requests
+// (joshuafolkken/kit#1066).
+//
+// Exported because the *listings* need exactly this, and for exactly this reason: a listing response
+// carries every row's `issue_dependencies_summary` but no `blockedBy`, so the pickup that asks for
+// the field pays one request per row that declares a blocker and nothing for the rest. A second copy
+// beside the listing requests is the clone `CLAUDE.md` prohibits (joshuafolkken/kit#1025).
+async function read_blocked_by(
+	issue_number: string,
+	rest: RestIssue,
+	repo?: string,
+): Promise<BlockedBy> {
+	if (git_gh_issue_rest.is_pull_request(rest)) return git_gh_issue_rest.empty_blocked_by()
+
+	const exact_total = git_gh_issue_rest.total_blocked_by(rest)
+	if (exact_total === 0) return git_gh_issue_rest.empty_blocked_by()
+
+	return await read_blocked_by_listing(issue_number, repo, exact_total)
+}
+
+// Re-label a failure as belonging to a request made after another had already succeeded. Nothing
+// else about it changes, so a rate limit or a dropped connection still reads exactly as it did.
+function mark_followup(error: unknown): unknown {
+	if (!(error instanceof Error)) return error
+
+	const failure = gh_failure.failure_of(error)
+	if (failure === undefined) return error
+
+	return gh_failure.attach(error, { ...failure, is_followup: true })
+}
+
+// The relations, marked as the follow-up request they are (joshuafolkken/kit#1690).
+//
+// **One read, two requests, one classifier.** The relations endpoint is reached only after the issue
+// itself came back, so by then the number has resolved — and yet the caller catches a single error
+// and cannot tell which of the two produced it. A 404 from the relations endpoint (absent on an
+// older host, which `has_no_relations_endpoint` handles for the other entry point) would otherwise
+// report an issue that exists as `missing`. The mark is set here, where which request failed is
+// still known.
+async function read_relations(
+	issue_number: string,
+	rest: RestIssue,
+	repo?: string,
+): Promise<BlockedBy> {
+	try {
+		return await read_blocked_by(issue_number, rest, repo)
+	} catch (error) {
+		throw mark_followup(error)
+	}
+}
+
+// One issue through REST, answered in the field names `gh issue view --json` used. Every read below
+// goes through it, so the request, the field mapping and the blocker relations are decided once
+// (joshuafolkken/kit#1024).
+//
+// The blocker request is made **only** when `blockedBy` was asked for — the title, body and
+// labels-and-body reads never name it — and, when it was, only when the issue itself reports a
+// blocker to fetch. Both guards are about the same cost: relations are read per issue across the
+// whole open backlog, so an unconditional second request would double that pass.
+async function read_issue_fields(
+	issue_number: string,
+	fields: string,
+	repo?: string,
+): Promise<Record<string, unknown>> {
+	const rest = git_gh_issue_rest.parse_rest_issue(
+		await git_gh_exec.exec_gh_api({ path: git_gh_api_path.issue_api_path(issue_number, repo) }),
+	)
+	const requested = git_gh_issue_rest.split_fields(fields)
+	const blocked_by = requested.includes(BLOCKED_BY_FIELD)
+		? await read_relations(issue_number, rest, repo)
+		: undefined
+
+	return git_gh_issue_rest.to_gh_issue(rest, requested, blocked_by)
+}
+
+// Why a read produced no issue. `missing` is GitHub resolving the number to nothing — a typo, or
+// another repository's number quoted in prose — which is an answer rather than a gap. `unreadable`
+// is a gap: a rate limit, expired auth, a dropped connection. Folding the two together had one
+// non-existent number reported as something the command had failed to read, which stops an
+// unattended run for a reference that never existed (joshuafolkken/kit#957).
+//
+// **`reason` splits the gap into the three answers a caller acts on differently**
+// (joshuafolkken/kit#1690). `unreachable` is retryable — nothing answered, or GitHub answered 429 or
+// 5xx — so the same request a moment later can succeed and an unattended run should ask again rather
+// than report the backlog empty. `rejected` is an answer that will not change on its own: expired
+// auth, an org policy, a 403. `malformed` is a response that arrived and could not be used, which is
+// neither a transport problem nor a permission one. `kind` is unchanged so the callers that only
+// separate "there is nothing at that number" from "the read failed" need no edit.
+type IssueReadReason = 'unreachable' | 'rejected' | 'malformed'
+type IssueReadFailure =
+	{ kind: 'missing' } | { kind: 'unreadable'; reason: IssueReadReason; status: number | undefined }
+type IssueRead = IssueReadFailure | { kind: 'read'; json: string }
+type FieldRead = IssueReadFailure | { kind: 'read'; text: string | undefined }
+
+// 404 is the number resolving to nothing. Every other status — 403 and 429 for a rate limit, 5xx,
+// or no status at all — is a read that failed over something the number is not responsible for.
+//
+// GitHub also answers 404 rather than 403 for an issue the token may not see, so that it does not
+// leak the issue's existence — the two are indistinguishable by design, and no reading of the status
+// could separate them. It does not reach the caller this exists for: `epic:bundle` probes the
+// repository whose open issues it has just listed, so a number it cannot see there is one that is
+// not there.
+const NOT_FOUND_STATUS = 404
+
+// Why the read failed, read off **the failed request** rather than off a second one
+// (joshuafolkken/kit#1690).
+//
+// joshuafolkken/kit#957 answered this by probing the same path again for its status, and
+// joshuafolkken/kit#1024 kept the probe because gh surfaces a failure as stderr text and classifying
+// by that wording is prose-matching. Both premises held; the conclusion did not. `gh api` writes the
+// **response body** to stdout, and GitHub's own error document carries the status there — so the
+// status was on the failed request all along, and `git-gh-failure.ts` takes it from there.
+//
+// **A second request cannot answer about the first.** A connection that dropped for a moment fails
+// the read and answers the probe `reachable`, and the read then keeps the meaning the probe gave it.
+// Removing the probe removes that, and removes the extra request with it: the classification is now
+// free, so `epic:bundle`'s bounded lookup no longer trades accuracy against a rate limit it would
+// deepen.
+//
+// An error carrying no classification at all did not come from the request: `parse_rest_issue` and
+// its schema throw for a response that arrived and could not be used, which is `malformed`.
+function is_number_unresolved(failure: GhFailure): boolean {
+	return failure.status === NOT_FOUND_STATUS && failure.is_followup !== true
+}
+
+function to_unreadable_reason(status: number | undefined): IssueReadReason {
+	return gh_reachability.classify_status(status) === 'unreachable' ? 'unreachable' : 'rejected'
+}
+
+function to_read_failure(error: unknown): IssueReadFailure {
+	const failure = gh_failure.failure_of(error)
+
+	if (failure === undefined) return { kind: 'unreadable', reason: 'malformed', status: undefined }
+	// Only the request that resolves the number can report it as resolving to nothing. A follow-up
+	// request's own 404 is about that endpoint (joshuafolkken/kit#1690).
+	if (is_number_unresolved(failure)) return { kind: 'missing' }
+
+	return {
+		kind: 'unreadable',
+		reason: to_unreadable_reason(failure.status),
+		status: failure.status,
+	}
+}
+
+// The same view as `issue_view_json`, plus why it produced nothing when it did.
+async function issue_view_json_classified(
+	issue_number: string,
+	fields: string,
+	repo?: string,
+): Promise<IssueRead> {
+	try {
+		const issue = await read_issue_fields(issue_number, fields, repo)
+
+		return { kind: 'read', json: JSON.stringify(issue) }
+	} catch (error) {
+		return to_read_failure(error)
+	}
+}
+
+// One field of one issue, with the reason it produced nothing when it did.
+//
+// The unwrapped `string | undefined` below is this same read with the reason dropped, rather than a
+// second read that never had one: a caller that only wants the text keeps its signature, and one
+// that has to tell "the body is empty" from "the body could not be read" now can
+// (joshuafolkken/kit#1690).
+async function issue_view_field_classified(
+	issue_number: string,
+	field: string,
+	repo?: string,
+): Promise<FieldRead> {
+	try {
+		const issue = await read_issue_fields(issue_number, field, repo)
+
+		return { kind: 'read', text: git_gh_issue_rest.to_field_text(issue[field]) }
+	} catch (error) {
+		return to_read_failure(error)
+	}
+}
+
+// One field of one issue, unwrapped so the caller gets the value rather than an object.
+async function issue_view_field(
+	issue_number: string,
+	field: string,
+	repo?: string,
+): Promise<string | undefined> {
+	const read = await issue_view_field_classified(issue_number, field, repo)
+
+	return read.kind === 'read' ? read.text : undefined
+}
+
+// An extracted string arrives raw — nothing quotes it — and an empty answer is not a title
+// (joshuafolkken/kit#993).
+//
+// `repo` reads the title of an issue in another repository — what `josh notify` needs when the
+// `--issue-url` it was given points outside the repository the session runs in
+// (joshuafolkken/kit#903).
+async function issue_get_title(issue_number: string, repo?: string): Promise<string | undefined> {
+	const result = await issue_view_field(issue_number, 'title', repo)
+
+	return result === undefined ? undefined : git_gh_helpers.parse_pr_state_string(result)
+}
+
+async function issue_get_body(issue_number: string, repo?: string): Promise<string | undefined> {
+	return await issue_view_field(issue_number, 'body', repo)
+}
+
+// The body, plus why it produced nothing when it did. An epic's body is the one read whose absence
+// is indistinguishable from a legitimate answer — an epic with no task list and an epic nobody could
+// read both parse to zero children — so the caller that builds the dependency graph takes this one
+// (joshuafolkken/kit#1690).
+async function issue_get_body_classified(issue_number: string, repo?: string): Promise<FieldRead> {
+	return await issue_view_field_classified(issue_number, 'body', repo)
+}
+
+// A JSON view of one issue, for every caller that wants several fields at once. Callers differ only
+// in which fields they ask for, and a helper per field list is how four near-identical functions
+// accumulated (joshuafolkken/kit#862).
+//
+// The field list is still spelled the way `gh issue view --json` spelled it, and so is the answer:
+// the translation to and from REST is `git-gh-issue-rest.ts`, so no caller downstream changed.
+async function issue_view_json(
+	issue_number: string,
+	fields: string,
+	repo?: string,
+): Promise<string | undefined> {
+	const read = await issue_view_json_classified(issue_number, fields, repo)
+
+	return read.kind === 'read' ? read.json : undefined
+}
+
+// State, labels and dependency relations in one read: the epic auto-close needs state and relations
+// per child, `epic:next` needs the labels too, and splitting them would multiply the API calls for
+// no gain (joshuafolkken/kit#860).
+//
+// `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 (joshuafolkken/kit#864).
+const STATE_AND_RELATIONS_FIELDS = 'number,state,labels,blockedBy'
+
+async function issue_get_state_and_relations(
+	issue_number: string,
+	repo?: string,
+): Promise<string | undefined> {
+	return await issue_view_json(issue_number, STATE_AND_RELATIONS_FIELDS, repo)
+}
+
+// The same read, plus why it produced nothing when it did. An epic's children are read this way, and
+// an unattended run has to tell a child it could not reach from one it may never reach
+// (joshuafolkken/kit#1690).
+async function issue_get_state_and_relations_classified(
+	issue_number: string,
+	repo?: string,
+): Promise<IssueRead> {
+	return await issue_view_json_classified(issue_number, STATE_AND_RELATIONS_FIELDS, repo)
+}
+
+// Whether a failed read is one the same request could succeed at a moment later. Defined beside the
+// classification rather than re-derived per caller: a second spelling of "unreadable and retryable"
+// is where the two would drift apart.
+function is_unreachable_read(failure: IssueReadFailure): boolean {
+	return failure.kind === 'unreadable' && failure.reason === 'unreachable'
+}
+
+// Everything the batch decision reads in front of it. Read separately from the poll above
+// because it carries the bodies, which a `wait` poll never looks at.
+//
+// `epic:bundle` reads a referenced issue through the same call rather than adding a helper for its
+// own field list — it needs the body and the state, which is a subset of this one, and a helper per
+// field list is exactly how the four near-identical functions above accumulated
+// (joshuafolkken/kit#947).
+const PLAN_FIELDS = 'number,title,body,state,url,labels,blockedBy'
+
+async function issue_get_plan_fields(issue_number: string): Promise<string | undefined> {
+	return await issue_view_json(issue_number, PLAN_FIELDS)
+}
+
+// The same fields, with a failed read told apart from a number that resolves to nothing.
+// `epic:bundle` reads a reference this way because the two answers belong in different places: a
+// missing number is neither a candidate nor a gap, while an unreadable one is reported so a verdict
+// is never quietly based on data that never arrived (joshuafolkken/kit#957).
+async function issue_get_plan_fields_classified(issue_number: string): Promise<IssueRead> {
+	return await issue_view_json_classified(issue_number, PLAN_FIELDS)
+}
+
+// `state` rides along for `git-epic-add.ts`'s closed-epic refusal (joshuafolkken/kit#2337); every
+// other caller reads only the labels and body and ignores it, so it costs no extra request.
+async function issue_get_labels_and_body(issue_number: string): Promise<string | undefined> {
+	return await issue_view_json(issue_number, 'number,state,labels,body')
+}
+
+// The conversation comments of one issue, as REST serves them. `undefined` — never `'[]'` — when the
+// listing could not be read: the one caller has to tell "this epic carries no closing comment" from
+// "nobody looked", because posting on the second answer is the duplicate it exists to prevent
+// (joshuafolkken/kit#1039).
+//
+// Paged, and for the same reason `pr_get_comments` is: REST answers 30 rows and an epic's
+// conversation outgrows that, while the comment being looked for is the **newest** one — so an
+// unpaged read would miss exactly the comment it is asking about. The endpoint answers a bare array,
+// which `--paginate` merges into one array, so nothing is slurped (`git-gh-exec.ts`).
+//
+// Deliberately not routed through `git-gh-pr-read.ts`'s `read_comments`, near-identical though the
+// request is: that one is keyed by **branch name** and exists to bridge gh's branch argument to
+// REST's number, and it maps the rows into the `gh --json` spelling its own callers read. This one
+// is already keyed by a number and wants the rows as served. What the two genuinely share — the path
+// and the page size — is single-sourced in `git-gh-api-path.ts` and read from there by both.
+//
+// No `repo` parameter, unlike the reads above: the auto-close lists its candidate epics from the
+// repository it runs in, so the epic whose comments are read is always a local one. The path builder
+// takes one when a caller that needs it appears.
+async function issue_list_comments(issue_number: string): Promise<string | undefined> {
+	const path = `${git_gh_api_path.issue_comments_api_path(issue_number)}${git_gh_api_path.FULL_PAGE_QUERY}`
+
+	try {
+		return await git_gh_exec.exec_gh_api({ path, should_paginate: true })
+	} catch {
+		return undefined
+	}
+}
+
+// Whether the relations endpoint has nothing at that number at all. Probed for its status rather
+// than read off `gh`'s stderr wording, because classifying by the message is prose-matching.
+//
+// **This one could read the failed request instead, and deliberately does not** — its caller reaches
+// it from a `catch`, where the error it holds already carries `gh_failure` since
+// joshuafolkken/kit#1690. What is asked here is not "why did that request fail" but "does this
+// endpoint exist on this host", and the answer has to hold for a `read_blocked_by_listing` that
+// failed for some other reason entirely. Reusing the caught failure would fold the two questions
+// into one.
+async function has_no_relations_endpoint(issue_number: string, repo?: string): Promise<boolean> {
+	const status = await git_gh_exec.exec_gh_api_status(
+		git_gh_api_path.blocked_by_api_path(issue_number, repo),
+	)
+
+	return status === NOT_FOUND_STATUS
+}
+
+// The blocker numbers of one issue, read from the relations listing rather than from the issue's own
+// summary count (joshuafolkken/kit#1113). Exposed on the command object so the callers that need the
+// uncounted answer reach it the way they reach every other read, and so a suite that already fakes
+// the command layer does not fall through to a real `gh api`.
+//
+// A 404 is answered as no relations rather than raised. `read_blocked_by` never reaches this
+// endpoint for a pull request — joshuafolkken/kit#1066 skips one structurally, since a PR carries no
+// `issue_dependencies_summary` to skip on — and this entry point has no issue payload to make that
+// judgement from. A PR pasted into an epic's task list would otherwise turn a read of an endpoint
+// that has nothing for it into a warning about a relation nobody lost. Every other failure still
+// raises: a rate limit is a gap, and the caller says so.
+// The same relations, each carrying the repository it lives in (joshuafolkken/kit#1126). A
+// `blocked-by` relation may cross a repository, and a number alone cannot say which one it names —
+// issue numbers are unique per repository — so a caller that orders work has to keep the pair.
+//
+// `own_repo` is what an unqualified relation has always meant: the repository the issue being read
+// lives in. It is the issue's own repository rather than the one the command is running in, which is
+// what `repo` scopes the request to.
+async function issue_blocked_by_references(
+	issue_number: string,
+	own_repo: string,
+	repo?: string,
+): Promise<Array<IssueReference>> {
+	try {
+		const listing = await read_blocked_by_listing(issue_number, repo)
+
+		return listing.nodes.map((blocker) => git_gh_issue_rest.reference_of_blocker(blocker, own_repo))
+	} catch (error) {
+		if (await has_no_relations_endpoint(issue_number, repo)) return []
+
+		throw error
+	}
+}
+
+async function issue_blocked_by_numbers(
+	issue_number: string,
+	repo?: string,
+): Promise<Array<number>> {
+	const references = await issue_blocked_by_references(issue_number, '', repo)
+
+	return references.map((blocker) => blocker.number)
+}
+
+const git_gh_issue_read = {
+	issue_blocked_by_numbers,
+	issue_blocked_by_references,
+	issue_get_title,
+	issue_get_body,
+	issue_get_body_classified,
+	issue_view_json,
+	issue_view_json_classified,
+	issue_get_state_and_relations,
+	issue_get_state_and_relations_classified,
+	is_unreachable_read,
+	issue_get_plan_fields,
+	issue_get_plan_fields_classified,
+	issue_get_labels_and_body,
+	issue_list_comments,
+}
+
+export type { IssueRead, IssueReadFailure }
+export { git_gh_issue_read, read_blocked_by, NOT_FOUND_STATUS }