@joshuafolkken/kit 1.872.0

package/scripts/git/git-epic-close-comment.ts

@@ -0,0 +1,199 @@
+import { git_epic_parse, type ExternalChild } from './git-epic-parse'
+import { git_gh_command } from './git-gh-command'
+import { read_json_listing } from './parse-json-array'
+import { rest_comment_schema, type RestCommentData } from './schemas'
+
+// The comment the epic auto-close announces itself with, and how a run recognizes the one a previous
+// run already posted.
+//
+// Kept apart from `git-epic-close.ts` because the two answer different questions — that file decides
+// *whether* an epic may close, this one decides what the announcement says and whether it is already
+// there — and because the file it was split from is within twenty lines of the three hundred a file
+// may hold (joshuafolkken/kit#1039).
+
+// The epic's children, near and far. Named structurally rather than by importing `EpicIssue`: the
+// dependency runs one way, from the auto-close to here, and a type import back would put a cycle
+// between two files that have no reason to know each other's shapes.
+interface EpicChildren {
+	children: ReadonlyArray<number>
+	external_children: ReadonlyArray<ExternalChild>
+}
+
+// The fixed sentence the announcement's prose ends with. It is what a person reads, and it is no
+// longer what the retry check matches on (joshuafolkken/kit#1068): people and agents quote the
+// auto-close output in ordinary issue comments, and matching prose made any such quote answer
+// "already announced" — the epic then closed with no comment, losing the record of which children it
+// closed against.
+const CLOSE_ANNOUNCEMENT = 'Closing this epic automatically.'
+
+// The marker, which GitHub renders as nothing at all. Quoting the sentence above therefore no longer
+// suppresses anything: what is quoted is the rendered text, and the marker is not in it.
+//
+// **It carries the child set the announcement named.** That is what makes an epic which was
+// reopened, gained a child and completed again announce a *second* time instead of closing silently
+// against a stale list. joshuafolkken/kit#1039 rejected matching the whole composed body for a
+// neighboring reason — the visible child list varies, so an unchanged epic would have been read as
+// "not posted yet" whenever the wording drifted — and the marker keeps that failure out by being
+// built from the child set alone: the prose can be rephrased without moving it, and the set is
+// compared as a set, so reordering the epic's task list does not move it either.
+const MARKER_OPEN = '<!-- josh:epic-auto-close children='
+const MARKER_CLOSE = ' -->'
+
+// Every child, near and far. Listing only the local ones left an all-external epic announcing "All
+// child issues are closed ()" (joshuafolkken/kit#864).
+function child_references(epic: EpicChildren): Array<string> {
+	return [
+		...epic.children.map((child) => `#${String(child)}`),
+		...epic.external_children.map((child) => `${child.repo}#${String(child.number)}`),
+	]
+}
+
+function build_marker(epic: EpicChildren): string {
+	return `${MARKER_OPEN}${child_references(epic).join(',')}${MARKER_CLOSE}`
+}
+
+// Four spaces open a markdown code block, so a line indented that far is quoted text rather than
+// the announcement's own marker — and the announcement never indents its marker at all.
+const INDENTED_CODE_SPACES = 4
+
+function indent_of(line: string): number {
+	return line.length - line.trimStart().length
+}
+
+// The child set a marker line records, or `undefined` for any other line. The empty filter is what
+// keeps an epic tracking nothing from reading as tracking one nameless child.
+function marker_children(line: string): Array<string> | undefined {
+	if (indent_of(line) >= INDENTED_CODE_SPACES) return undefined
+
+	const trimmed = line.trim()
+	if (!trimmed.startsWith(MARKER_OPEN)) return undefined
+	if (!trimmed.endsWith(MARKER_CLOSE)) return undefined
+
+	const listed = trimmed.slice(MARKER_OPEN.length, -MARKER_CLOSE.length)
+
+	return listed.split(',').filter((reference) => reference.length > 0)
+}
+
+// Compared as sets rather than as strings: the marker is written in whatever order the epic happens
+// to list its children, and reordering a task list changes neither the batch nor what was announced
+// about it. Comparing the rendered strings would have needed a canonical order, and every ordering
+// available for `owner/repo#N` text is either locale-dependent or a lint exception — a set says what
+// is actually meant and is the same answer on every machine.
+function is_same_children(left: ReadonlyArray<string>, right: ReadonlyArray<string>): boolean {
+	const left_set = new Set(left)
+	const right_set = new Set(right)
+
+	return left_set.size === right_set.size && [...left_set].every((one) => right_set.has(one))
+}
+
+// The prose the reader sees, then the marker the next run matches on.
+function build_close_comment(epic: EpicChildren): string {
+	return `All child issues are closed (${child_references(epic).join(', ')}). ${CLOSE_ANNOUNCEMENT}\n\n${build_marker(epic)}`
+}
+
+// MIGRATION ONLY (joshuafolkken/kit#1068) — remove together with `is_legacy_announcement`.
+//
+// Announcements posted by v1.179.0 through the release before this one carry no marker, so an epic
+// sitting in the half-succeeded state right now would be read as "not announced" and receive the
+// second comment joshuafolkken/kit#1039 removed. This matches those.
+//
+// **The wording here is a frozen copy of what was released, not a second spelling of the constants
+// above.** Deriving it from them would make a future rephrasing of the announcement silently stop
+// matching comments already on GitHub, which no edit can change.
+//
+// It matches only a comment whose **entire** body is the old announcement — which is what the
+// auto-close posted, and what a quote never is: a quote sits inside prose, or behind `> `, or in a
+// fence, and none of those trim down to this.
+//
+// **When it can be removed:** once no *open* epic can still carry a marker-less announcement. Closed
+// epics do not matter — the auto-close reads its candidates from a `state=open` listing, so they are
+// never considered. Establish it by listing the open epics and looking for one whose comments hold a
+// body matching this pattern:
+//
+//   gh issue list --label epic --state open --json number --jq '.[].number' |
+//     while read -r n; do
+//       gh api "repos/{owner}/{repo}/issues/$n/comments" --paginate --jq '.[].body' |
+//         grep -c '^All child issues are closed (.*)\. Closing this epic automatically\.$'
+//     done
+//
+// A total of zero means every remaining announcement carries the marker; delete this constant,
+// `is_legacy_announcement`, and the tests naming them.
+const LEGACY_ANNOUNCEMENT_PATTERN =
+	/^All child issues are closed \([^)]*\)\. Closing this epic automatically\.$/u
+
+function is_legacy_announcement(body: string): boolean {
+	return LEGACY_ANNOUNCEMENT_PATTERN.test(body.trim())
+}
+
+// Whether the epic already carries the announcement.
+//
+// `unreadable` is deliberately not folded into `absent`, though the caller acts the same way on
+// both: a listing that could not be read says nothing about what is on the issue, and reporting it
+// as "nothing is there" would have the run state a fact it never established — the misread
+// joshuafolkken/kit#973 and joshuafolkken/kit#959 were each about. Keeping it apart is what lets
+// `git-epic-close.ts` say out loud that the duplicate check did not run, which is the whole
+// difference between the two answers there.
+//
+// **Both of `read_json_listing`'s gaps arrive as `unreadable`**, rows the schema rejects included.
+// `parse_json_array_or_undefined` rethrows that one, which is right where a shape change should stay
+// visible — and wrong here: this answer decides whether a *write* posts, so an exception in place of
+// the safe answer is the one outcome the function must not produce.
+type CloseCommentState = 'present' | 'absent' | 'unreadable'
+
+// The marker has to be a line of its own, outside any fence — not merely present in the body. A
+// quote is exactly what must not suppress the next announcement, and the two ways of quoting an
+// announcement carry the raw marker along with everything else: GitHub's "Quote reply" puts every
+// line behind `> `, which the line comparison rejects, and a code block reproduces the marker line
+// verbatim — a fenced one caught by the mask, an indented one by the indent check. `fence_mask` is the same walk every other body predicate
+// in this codebase reads through, rather than a second one written here (joshuafolkken/kit#890).
+function has_marker(body: string, children: ReadonlyArray<string>): boolean {
+	const mask = git_epic_parse.fence_mask(body)
+
+	return body.split('\n').some((line, index) => {
+		if (mask[index] !== true) return false
+
+		const announced = marker_children(line)
+
+		return announced !== undefined && is_same_children(announced, children)
+	})
+}
+
+function has_announcement(
+	comments: ReadonlyArray<RestCommentData>,
+	children: ReadonlyArray<string>,
+): boolean {
+	return comments.some((comment) => {
+		const body = comment.body ?? ''
+
+		return has_marker(body, children) || is_legacy_announcement(body)
+	})
+}
+
+// One request, and it is spent only on a run that is about to close an epic: the caller reaches this
+// after every child has been read and found closed, which happens once in an epic's life. Every
+// other `josh followup` run leaves the epic short of complete and never gets here, so the ordinary
+// path costs nothing.
+//
+// An epic that has already **closed** is a different situation and never arrives here at all: the
+// auto-close reads its candidates from an `state=open` listing (`git-gh-issue-list.ts`), so a closed
+// epic is not among them and no comment of any kind is considered for it.
+async function read_close_comment_state(
+	epic_number: string,
+	epic: EpicChildren,
+): Promise<CloseCommentState> {
+	const raw_json = await git_gh_command.issue_list_comments(epic_number)
+	if (raw_json === undefined) return 'unreadable'
+
+	const listing = read_json_listing(raw_json, rest_comment_schema)
+	if (listing.kind !== 'read') return 'unreadable'
+
+	return has_announcement(listing.rows, child_references(epic)) ? 'present' : 'absent'
+}
+
+const git_epic_close_comment = {
+	build_close_comment,
+	read_close_comment_state,
+}
+
+export type { CloseCommentState, EpicChildren }
+export { git_epic_close_comment, CLOSE_ANNOUNCEMENT }

package/scripts/git/git-epic-close.ts

@@ -0,0 +1,393 @@
+import { git_epic_close_comment } from './git-epic-close-comment'
+import { git_epic_parse, type ExternalChild } from './git-epic-parse'
+import { git_gh_command } from './git-gh-command'
+import { EPIC_LABEL } from './issue-labels'
+import { cutoff_cause, cutoff_of, type ScanCutoff } from './listing-cutoff'
+import { parse_json_array_or_undefined, parse_json_object_safe } from './parse-json-array'
+import { epic_child_schema, epic_issue_schema, type EpicChildData } from './schemas'
+
+// How many open epics the auto-close will look at. `git-gh-issue-list.ts` pages until `limit` rows
+// have been selected or the backlog runs out, so this is what keeps the ordinary case at exactly one
+// request — 100 is `PER_PAGE`. Since joshuafolkken/kit#1067 the paging's own page ceiling bounds
+// this listing too, but as a backstop rather than as this number's replacement: it stops the request
+// count, not the row count.
+//
+// The listing is newest-first and the surplus is cut off the tail, so a repository holding more open
+// epics than this loses the oldest. It no longer loses them silently: since joshuafolkken/kit#1067
+// both cutoffs are reported, because an epic past the cut is never checked for completion and stays
+// open with nothing saying why — the same silence this file's `undefined`-not-`[]` handling exists
+// to remove. The value still sits well above the number of epics ever open at once, so the report is
+// the exception rather than a line on every merge.
+const EPIC_LIST_LIMIT = 100
+
+// Printed rather than thrown: this runs after the PR has already merged, so nothing here may fail
+// the run. `console.info` is what every other note in this file uses, for that same reason.
+function truncated_epic_list_note(cutoff: ScanCutoff): string | undefined {
+	const cause = cutoff_cause(cutoff, `hit its ${String(EPIC_LIST_LIMIT)}-epic cap`)
+	if (cause === undefined) return undefined
+
+	return `⚠️  The open epic listing ${cause}; an epic past it was not checked for completion.`
+}
+
+interface EpicIssue {
+	number: number
+	children: Array<number>
+	external_children: Array<ExternalChild>
+	has_declared_order: boolean
+}
+
+interface SiblingState {
+	is_closed: boolean
+	has_blocked_by: boolean
+}
+
+function to_epic_issue(raw: { number: number; body?: string | undefined }): EpicIssue {
+	return {
+		number: raw.number,
+		children: git_epic_parse.parse_task_list_issue_numbers(raw.body),
+		external_children: git_epic_parse.parse_external_task_list_children(raw.body),
+		has_declared_order: git_epic_parse.has_declared_dependency_chain(raw.body),
+	}
+}
+
+// `undefined` when the listing could not be read at all — the request failed, or the answer was not
+// a JSON array. Not `[]`, which is a real answer meaning no epic is open.
+//
+// `parse_json_array_safe` returns `[]` for both, and the auto-close then decides there is no epic to
+// close: it stops for a reason that never reaches a log, and the epic stays open with nothing saying
+// why. The failure leans safe — the other direction, taken by `epic:bundle`, invented a second epic
+// (joshuafolkken/kit#950) — but silence is the same defect, so the two are told apart here as well
+// (joshuafolkken/kit#959).
+//
+// The two ways of failing are folded into one answer deliberately. Which one occurred does not
+// change what the auto-close may do — in neither case does it know what the open epics are — and
+// splitting them would put two warnings on one decision.
+async function fetch_open_epics(): Promise<Array<EpicIssue> | undefined> {
+	const { json, is_capped } = await git_gh_command.issue_list_by_label(EPIC_LABEL, EPIC_LIST_LIMIT)
+	if (json === undefined) return undefined
+
+	const rows = parse_json_array_or_undefined(json, epic_issue_schema)
+	if (rows === undefined) return undefined
+	const note = truncated_epic_list_note(cutoff_of(rows.length, EPIC_LIST_LIMIT, is_capped))
+
+	if (note !== undefined) console.info(note)
+
+	return rows.map((raw) => to_epic_issue(raw))
+}
+
+function parse_child(raw_json: string | undefined): EpicChildData | undefined {
+	if (raw_json === undefined) return undefined
+
+	return parse_json_object_safe(raw_json, epic_child_schema)
+}
+
+function has_blocked_by(child: EpicChildData | undefined): boolean {
+	const blocked_by = child?.blockedBy
+
+	return (blocked_by?.totalCount ?? 0) > 0
+}
+
+function to_sibling_state(raw_json: string | undefined): SiblingState {
+	const child = parse_child(raw_json)
+
+	return {
+		is_closed: git_epic_parse.is_state_closed(child?.state),
+		has_blocked_by: has_blocked_by(child),
+	}
+}
+
+async function inspect_sibling(sibling: number, repo?: string): Promise<SiblingState> {
+	return to_sibling_state(await git_gh_command.issue_get_state_and_relations(String(sibling), repo))
+}
+
+// A cross-repository child, read by naming its repository in the read's REST path. `is_readable`
+// is what decides whether the epic may close at all: closing while a child's state is unknown is
+// exactly what the old refusal prevented, and reading them is the only thing that changed
+// (joshuafolkken/kit#864).
+async function inspect_external(
+	child: ExternalChild,
+): Promise<SiblingState & { is_readable: boolean }> {
+	const raw = await git_gh_command.issue_get_state_and_relations(String(child.number), child.repo)
+
+	return { ...to_sibling_state(raw), is_readable: raw !== undefined }
+}
+
+// The merged Issue is excluded rather than queried: GitHub applies `closes #N` asynchronously, so
+// reading its state immediately after the merge races with that propagation.
+async function inspect_siblings(
+	epic: EpicIssue,
+	merged_number: number,
+): Promise<Array<SiblingState>> {
+	const siblings = epic.children.filter((child) => child !== merged_number)
+
+	return await Promise.all(siblings.map(async (sibling) => await inspect_sibling(sibling)))
+}
+
+// `pnpm josh epic --ordered` and `--add` record the declared chain themselves, through the REST
+// dependencies endpoint (`git-epic-relations.ts`, joshuafolkken/kit#1026), so the default route
+// arrives here with the relations already in place. Three routes still reach a declared order with
+// none recorded: an epic body written by hand, the manual fallback in `issue-template.md`, and
+// `apply_relations` failing — it counts the refusals, reports that the body is intact and lets the
+// batch finish. Each is otherwise symptomless, which is what this warning is for. The epic body's
+// declared chain is the trigger: since #713 every split gets an epic, so its existence no longer
+// implies an order, and warning on that alone would fire on every unordered batch. Only a total
+// absence of relations is reported — checking each dependent pair would mean inferring the chain
+// from task-list order, which need not match.
+function warn_when_order_unrecorded(epic: EpicIssue, states: ReadonlyArray<SiblingState>): void {
+	if (
+		states.length === 0 ||
+		!epic.has_declared_order ||
+		states.some((state) => state.has_blocked_by)
+	) {
+		return
+	}
+
+	console.info(
+		`ℹ️  Epic #${String(epic.number)} has no blocked-by relation on any child; ` +
+			'the batch order was never recorded natively (see the epic creation procedure).',
+	)
+}
+
+// The one thing the two refusals below ask for, written once — a child state that could not be read,
+// and a close the API refused (joshuafolkken/kit#1039).
+const CLOSE_MANUALLY = 'close it manually.'
+
+// The nesting cascade's safety valve. A closed child epic is itself a completed child, so the same
+// completion check is re-run for the epics that list *it*, closing a nested parent in the same pass
+// (joshuafolkken/kit#2008). `evaluated` already terminates a cycle or a shared child; this is the
+// backstop for a nesting so deep it is likelier a mistake than a plan. On reaching it the cascade
+// stops and asks for a manual close, exactly as an unreadable or refused child close does.
+const MAX_CASCADE_DEPTH = 10
+
+const CASCADE_DEPTH_NOTE = `⚠️  Epic auto-close cascade reached its ${String(
+	MAX_CASCADE_DEPTH,
+)}-level cap; ${CLOSE_MANUALLY}`
+
+// **An unreadable comment listing does not stop the close.** It is announced and closed exactly as
+// it was before the duplicate check existed, because refusing here would strand the epic: nothing
+// re-triggers the auto-close once every child is closed — `resolve_and_close` only evaluates epics
+// holding the issue that just merged, and that merge has already happened. One rate-limited read
+// would leave a finished epic open until somebody noticed.
+//
+// The direction is chosen on what each mistake costs, and they are not symmetric. Announcing twice
+// costs one redundant comment and nothing else, because the epic *closes* — which is what ends the
+// loop joshuafolkken/kit#1039 is about, where the comment repeated once per attempt for as long as
+// the close kept failing. Refusing costs a manual close on every transient failure.
+const UNREADABLE_COMMENTS_NOTE =
+	"'s comments could not be read; announcing again rather than leaving it open."
+
+// The write, once the announcement has been decided. `comment` is `undefined` when the epic already
+// carries one — which is what stops a run whose comment landed and whose close was refused from
+// posting the same comment again on the next attempt, and again for as long as the close keeps
+// failing (joshuafolkken/kit#1039).
+//
+// The comment-first ordering inside `issue_close` is what produces that half-succeeded state, and it
+// is left exactly as it is: it is what keeps a `false` meaning "the epic is still open" in every
+// branch, which is the answer the second message here is written against (joshuafolkken/kit#1026).
+async function close_epic_with(epic_number: string, comment: string | undefined): Promise<boolean> {
+	const is_closed = await git_gh_command.issue_close(epic_number, comment)
+
+	console.info(
+		is_closed
+			? `🏁 Closed epic #${epic_number} — every child issue is complete.`
+			: `⚠️  Could not close epic #${epic_number}; ${CLOSE_MANUALLY}`,
+	)
+
+	return is_closed
+}
+
+// The comment listing is read **once**: only `present` skips the announcement, so an answer of
+// `absent` and one of `unreadable` both post it, and the second says so.
+async function close_epic(epic: EpicIssue): Promise<boolean> {
+	const epic_number = String(epic.number)
+	const state = await git_epic_close_comment.read_close_comment_state(epic_number, epic)
+
+	if (state === 'unreadable') console.info(`ℹ️  Epic #${epic_number}${UNREADABLE_COMMENTS_NOTE}`)
+
+	const comment = state === 'present' ? undefined : git_epic_close_comment.build_close_comment(epic)
+
+	return await close_epic_with(epic_number, comment)
+}
+
+// The cross-repository children's states, and whether every one of them could be read. An epic with
+// a child whose state is unknown keeps the old handling — left open for manual closing.
+async function inspect_external_children(
+	epic: EpicIssue,
+): Promise<{ states: Array<SiblingState>; is_complete: boolean }> {
+	if (epic.external_children.length === 0) return { states: [], is_complete: true }
+	const results = await Promise.all(
+		epic.external_children.map(async (child) => await inspect_external(child)),
+	)
+
+	return {
+		states: results.map((result) => ({
+			is_closed: result.is_closed,
+			has_blocked_by: result.has_blocked_by,
+		})),
+		is_complete: results.every((result) => result.is_readable),
+	}
+}
+
+async function close_epic_when_complete(epic: EpicIssue, merged_number: number): Promise<boolean> {
+	const external = await inspect_external_children(epic)
+
+	if (!external.is_complete) {
+		console.info(
+			`ℹ️  Epic #${String(epic.number)} has a child in another repository whose state could not be read; ${CLOSE_MANUALLY}`,
+		)
+
+		return false
+	}
+
+	const states = [...(await inspect_siblings(epic, merged_number)), ...external.states]
+
+	warn_when_order_unrecorded(epic, states)
+
+	if (states.some((state) => !state.is_closed)) return false
+
+	return await close_epic(epic)
+}
+
+// Each epic is isolated: one that cannot be read or closed must not stop the others from being
+// evaluated, since they are independent batches that merely share this child. `false` — the epic did
+// not close, whether because a sibling is still open, a read failed or the close was refused — is
+// what stops the cascade from walking past it to a parent (joshuafolkken/kit#2008).
+async function close_epic_isolated(epic: EpicIssue, merged_number: number): Promise<boolean> {
+	try {
+		return await close_epic_when_complete(epic, merged_number)
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error)
+
+		console.info(`⚠️  Skipped epic #${String(epic.number)}: ${message}`)
+
+		return false
+	}
+}
+
+function parents_of(open_epics: ReadonlyArray<EpicIssue>, child_number: number): Array<EpicIssue> {
+	return open_epics.filter((epic) => git_epic_parse.has_child(epic.children, child_number))
+}
+
+// Closes one epic unless a cycle or a shared child already reached it — the closed number, or
+// `undefined`. `evaluated` is marked before the close, so a refused close is not retried by a later
+// path either.
+async function close_if_unseen(
+	epic: EpicIssue,
+	child_number: number,
+	evaluated: Set<number>,
+): Promise<number | undefined> {
+	if (evaluated.has(epic.number)) return undefined
+	evaluated.add(epic.number)
+
+	return (await close_epic_isolated(epic, child_number)) ? epic.number : undefined
+}
+
+// The epics that list `child_number` and close because of it. The numbers returned are the next
+// cascade frontier: each is a closed epic, itself a completed child of whatever lists it.
+async function close_parents_of(
+	open_epics: ReadonlyArray<EpicIssue>,
+	child_number: number,
+	evaluated: Set<number>,
+): Promise<Array<number>> {
+	const closed: Array<number> = []
+
+	for (const epic of parents_of(open_epics, child_number)) {
+		const number = await close_if_unseen(epic, child_number, evaluated)
+		if (number !== undefined) closed.push(number)
+	}
+
+	return closed
+}
+
+async function close_next_level(
+	open_epics: ReadonlyArray<EpicIssue>,
+	frontier: ReadonlyArray<number>,
+	evaluated: Set<number>,
+): Promise<Array<number>> {
+	const next: Array<number> = []
+
+	for (const child_number of frontier) {
+		next.push(...(await close_parents_of(open_epics, child_number, evaluated)))
+	}
+
+	return next
+}
+
+// Breadth-first up the nesting: level 0 closes the epics holding the merged issue, and each closed
+// epic becomes the next level's completed child, so a fully-finished parent closes in the same pass.
+async function cascade_close(
+	open_epics: ReadonlyArray<EpicIssue>,
+	merged_number: number,
+): Promise<void> {
+	const evaluated = new Set<number>()
+	let frontier: ReadonlyArray<number> = [merged_number]
+
+	for (let depth = 0; depth < MAX_CASCADE_DEPTH; depth++) {
+		if (frontier.length === 0) return
+		frontier = await close_next_level(open_epics, frontier, evaluated)
+	}
+
+	if (frontier.length > 0) console.info(CASCADE_DEPTH_NOTE)
+}
+
+const UNREADABLE_EPIC_LIST_MESSAGE =
+	'⚠️  Could not read the open epic listing; skipped the epic auto-close check.'
+
+async function resolve_and_close(merged_number: number): Promise<void> {
+	const open_epics = await fetch_open_epics()
+
+	if (open_epics === undefined) {
+		console.info(UNREADABLE_EPIC_LIST_MESSAGE)
+
+		return
+	}
+
+	await cascade_close(open_epics, merged_number)
+}
+
+// Runs after the PR has already merged, so nothing here may reject: it would make `followup` exit
+// non-zero on an otherwise successful run and read as a merge blocker.
+async function resolve_and_close_safely(merged_number: number): Promise<void> {
+	try {
+		await resolve_and_close(merged_number)
+	} catch (error) {
+		const message = error instanceof Error ? error.message : String(error)
+
+		console.info(`⚠️  Skipped the epic auto-close check: ${message}`)
+	}
+}
+
+/**
+ * Close every open epic whose task list is fully complete once `issue_number` closed.
+ *
+ * Requires `is_merged`: the linked Issue is treated as closed without being queried, which only
+ * holds once the PR actually merged. On a `--no-merge` run that Issue is still open, so skipping
+ * this guard would close an epic whose batch is not finished.
+ */
+async function close_completed_epics(input: {
+	issue_number: string | undefined
+	is_merged: boolean
+}): Promise<void> {
+	if (!input.is_merged) return
+
+	const merged_number = Number(input.issue_number)
+	if (!Number.isSafeInteger(merged_number)) return
+
+	await resolve_and_close_safely(merged_number)
+}
+
+const git_epic_close = {
+	close_completed_epics,
+}
+
+export {
+	git_epic_close,
+	close_completed_epics,
+	truncated_epic_list_note,
+	EPIC_LIST_LIMIT,
+	MAX_CASCADE_DEPTH,
+	CASCADE_DEPTH_NOTE,
+	UNREADABLE_EPIC_LIST_MESSAGE,
+	UNREADABLE_COMMENTS_NOTE,
+}
+export type { EpicIssue }