@joshuafolkken/kit 1.872.0

package/scripts/epic/epic-busy.ts

@@ -0,0 +1,204 @@
+import { git_gh_command } from '#scripts/git/git-gh-command'
+import {
+	ALREADY_DONE_LABEL,
+	has_any_label,
+	IN_PROGRESS_LABEL,
+	NEEDS_DECISION_LABEL,
+} from '#scripts/git/issue-labels'
+import { read_json_listing } from '#scripts/git/parse-json-array'
+import { open_issue_schema, type OpenIssueData } from '#scripts/git/schemas'
+
+// How much of a repository's parallelism is already spoken for — asked of the *repository*, never of
+// the epic (joshuafolkken/kit#925), and counted rather than treated as a yes/no since
+// joshuafolkken/kit#1491.
+//
+// `epic-classify.ts` sorts only the children the epic tracks, so an `in-progress` issue belonging to
+// a *different* epic is invisible to it: start two `epicrun`s and both answer "nothing of mine is in
+// progress". This read is what closes that gap, and it is deliberately outside the classification —
+// the question is not about the graph.
+//
+// **What an `in-progress` issue holds is one lane, not the repository.** Until joshuafolkken/kit#1490
+// the contended resource really was one working tree, one `main` and one `pnpm-lock.yaml`, so one
+// holder excluded everything. A lane is its own checkout with its own branch and its own ports, so
+// the question stopped being "is anything running" and became "how many are running" — and the
+// answer is a count the caller compares against `lane_capacity`'s limit.
+//
+// **The count is read from GitHub, never kept in the session.** Two `epicrun`s counting to six in
+// their own memory give twelve lanes; the label on an open issue is the one record both of them
+// read. It is an advisory guard rather than a mutex — the label is applied after the read, so two
+// sessions starting in the same instant can still take one seat twice. What it closes is the window
+// that actually occurs: a lane holding the label for minutes.
+
+// Wide enough that the cap is never what decides the answer: a repository with a hundred issues
+// carrying `in-progress` at once is already the state this guard exists to report.
+const LISTING_LIMIT = 100
+
+// Read through `has_any_label` rather than compared directly, for the casing reason
+// `issue-labels.ts` records: GitHub keeps the spelling a label was created with.
+//
+// `already-done` joins `needs-decision` here for the same reason it joins it in
+// `epic_classify.local_category` (joshuafolkken/kit#1679): the run that applied it committed
+// nothing, so the checkout it ran in is clean and there is no uncommitted work for the next child to
+// start on top of. That is exactly what separates both from `needs-human-review`, which is
+// deliberately not parked because its work is still sitting in the tree.
+const PARKED_LABELS: ReadonlySet<string> = new Set([NEEDS_DECISION_LABEL, ALREADY_DONE_LABEL])
+
+// What one repository answered. `unreadable` is kept apart from `idle` for the reason
+// joshuafolkken/kit#950 records: reading a failed read as an empty listing is a confident absence
+// built on a response nobody parsed — and here that absence *starts* work, which is the one
+// direction a guard must never fail in.
+//
+// **`epic:next` answers `wait` for it, rather than exiting.** The other candidate was an error exit,
+// as an unreadable *child* already produces — but `issue_list` swallows every failure into
+// `undefined`, a passing rate limit included, and this read happens on every poll of every session,
+// so an exit would end an unattended run over a blip. A persistent failure never arrives here: the
+// children are read first, and one that could not be read is already an anomaly that exits 1. What
+// is left at this line is transient, and `wait` self-heals where an exit needs a person.
+//
+// **`truncated` is kept apart from `idle` for the same reason, one step further in**
+// (joshuafolkken/kit#1067). Since the page ceiling applies to every listing, a listing can now come
+// back well-formed, short, and missing the very issue that holds this repository — and "no holder in
+// the rows I was given" is not "no holder". It is grouped with `unreadable` rather than with `idle`
+// because what it authorizes is identical: nothing. It gets its own kind only so the message names
+// the real cause — `unreadable_message` sends a reader to `gh auth status`, which is green here.
+type BusyRead =
+	| { kind: 'idle' }
+	| { kind: 'busy'; issues: ReadonlyArray<OpenIssueData> }
+	| { kind: 'unreadable' }
+	| { kind: 'truncated' }
+
+// Named so the reader can go and look at them: the stale-label rule is what keeps an abandoned
+// `in-progress` from holding a repository forever, and it cannot be applied to an issue nobody was
+// told about.
+function format_holders(issues: ReadonlyArray<OpenIssueData>): string {
+	return issues.map((issue) => `#${String(issue.number)} ${issue.title}`).join(', ')
+}
+
+// How many lanes this read shows occupied. Every kind but `busy` is zero, and the two that could not
+// see the whole listing are held back by their kind rather than by their count — a read that saw
+// nothing is not a repository with nothing running, and the caller checks the kind first.
+function occupied_lanes(read: BusyRead): number {
+	return read.kind === 'busy' ? read.issues.length : 0
+}
+
+// Named holders rather than a bare count, for the reason the stale-label rule needs: it is applied
+// by whoever finds the label stale, and it cannot be applied to an issue nobody was told about.
+function occupancy_message(
+	issues: ReadonlyArray<OpenIssueData>,
+	repo: string,
+	limit: number,
+): string {
+	return `${String(issues.length)} of ${String(limit)} lanes in use in ${repo}: ${format_holders(issues)}.`
+}
+
+// The occupancy said once, with the consequence appended — rather than a second sentence that
+// re-derives the same numbers and can drift from the first.
+function lanes_full_message(
+	issues: ReadonlyArray<OpenIssueData>,
+	repo: string,
+	limit: number,
+): string {
+	return `${occupancy_message(issues, repo, limit)} No lane is free, so nothing is offered here. A lane is released when its child merges or is parked; if a label is stale, remove it and ask again, and \`JOSH_LANE_LIMIT\` is what raises the ceiling.`
+}
+
+function unreadable_message(repo: string): string {
+	return `Could not read the \`${IN_PROGRESS_LABEL}\` listing for ${repo}. That is not "nothing is running" — check \`gh auth status\` and ask again.`
+}
+
+// Said in the `⚠ … cap` shape joshuafolkken/kit#1033 settled on, because it is the same kind of
+// statement: the read happened and covered less than the whole listing. What it means here is
+// stronger than elsewhere, so the message says the consequence out loud rather than leaving a reader
+// to infer it from a warning marker.
+//
+// **It does not tell anyone to clear stale labels, the way `lanes_full_message` does.** The only cut that
+// reaches here is the page ceiling, which needs hundreds of labelled pull requests to fire — nothing
+// an issue label can clear, and nothing asking again will resolve either. So it names what the run
+// is waiting on and sends the reader to the one thing that would change the answer.
+function truncated_message(repo: string): string {
+	return `⚠ The \`${IN_PROGRESS_LABEL}\` listing for ${repo} could not be read to the end, so an issue holding that repository may not be in it. That is not "nothing is running" — nothing is offered here, and asking again will not clear it. Narrow what carries \`${IN_PROGRESS_LABEL}\` in that repository, or run this child there by hand.`
+}
+
+// Which of the three non-idle answers to print, by kind rather than by fall-through. `idle` has no
+// message — it is the branch that offers the child — and a kind added later gets a compile error at
+// the table instead of silently inheriting the unreadable listing's advice, which would send a
+// reader to `gh auth status` for something that has nothing to do with it.
+const BUSY_REASONS: Readonly<
+	Record<Exclude<BusyRead['kind'], 'busy' | 'idle'>, (repo: string) => string>
+> = {
+	unreadable: unreadable_message,
+	truncated: truncated_message,
+}
+
+function busy_reason(read: BusyRead, repo: string, limit: number): string {
+	if (read.kind === 'busy') return lanes_full_message(read.issues, repo, limit)
+	if (read.kind === 'idle') return ''
+
+	return BUSY_REASONS[read.kind](repo)
+}
+
+// A parked issue does not hold a lane, and this is not a special case bolted on: it is the
+// precedence `epic_classify.local_category` already applies, which reads `needs-decision` *before*
+// `in-progress` and so calls a parked child `human` rather than `time`. Two readings of one issue
+// have to agree, and without this they do not — nothing removes `in-progress` when a child is
+// parked, so `park and continue` would spend a lane on the very child it just set aside, and with
+// one lane the run would poll instead of continuing (joshuafolkken/kit#925). A child stopped by
+// `needs-human-review` is deliberately not parked and goes on holding its lane: its uncommitted work
+// is still sitting in that checkout.
+function is_parked(issue: OpenIssueData): boolean {
+	return has_any_label(issue.labels, PARKED_LABELS)
+}
+
+// A listing that arrived, or a gap. The shared reader tells the two gaps apart — output that is not
+// a listing from elements the schema rejects — and both are `unreadable` here: this guard has one
+// safe answer and it is the same for either, while the `auto-ok` pickup names them separately.
+//
+// A holder that *is* visible settles the question whatever the paging did — something is running,
+// which is the answer — so `is_capped` is consulted only when no holder came back.
+//
+// **`is_capped` alone, not the `limit` cap the other callers also report.** A page ceiling here means
+// the paging could not reach `limit` at all, which normal operation does not produce and which
+// nothing the run can do will clear — waiting is the right answer and it is a state a person has to
+// look at. A *filled* `limit` is different: `epicrun` parks a child by adding `needs-decision` and
+// **leaving `in-progress` on**, so parked issues accumulate under this label, and a hundred of them
+// would fill the listing with rows this function then discards as non-holders. Calling that
+// truncated answers `wait` on every ask, for a condition nothing resolves — one stalled repository
+// for every epic, traded against the second run one possibly-hidden holder would allow. The `wait`
+// this guard is built on is the kind a holder finishing clears, and that one is not it.
+function parse_listing(raw: string, is_capped: boolean): BusyRead {
+	const read = read_json_listing(raw, open_issue_schema)
+	if (read.kind !== 'read') return { kind: 'unreadable' }
+
+	const holders = read.rows.filter((row) => !is_parked(row))
+	if (holders.length > 0) return { kind: 'busy', issues: holders }
+
+	return { kind: is_capped ? 'truncated' : 'idle' }
+}
+
+// The label filter is the query's job — membership is what makes the listing the running set, so
+// re-testing it here would be a second definition of "running".
+async function read_repository(repo: string): Promise<BusyRead> {
+	const { json, is_capped } = await git_gh_command.issue_list_by_label_in_repo(
+		IN_PROGRESS_LABEL,
+		LISTING_LIMIT,
+		repo,
+	)
+
+	return json === undefined ? { kind: 'unreadable' } : parse_listing(json, is_capped)
+}
+
+const epic_busy = {
+	LISTING_LIMIT,
+	occupied_lanes,
+	occupancy_message,
+	lanes_full_message,
+	unreadable_message,
+	truncated_message,
+	busy_reason,
+	format_holders,
+	is_parked,
+	parse_listing,
+	read_repository,
+}
+
+export type { BusyRead }
+export { epic_busy }

package/scripts/epic/epic-candidate-confirm.ts

@@ -0,0 +1,279 @@
+import { epic_classify, type ResolveDependency } from './epic-classify'
+import { epic_graph, type EpicChild, type IssueReference } from './epic-graph'
+import type { BlockersReader } from './epic-relation-recheck'
+import { epic_report, type EpicVerdict } from './epic-report'
+
+// joshuafolkken/kit#1121: the other direction of joshuafolkken/kit#1113's defect, checked where it
+// would otherwise start work.
+//
+// `read_blocked_by` answers from the issue's own `issue_dependencies_summary` when that summary says
+// zero, so a child whose counter is stale is read as `blocked_by: []`. joshuafolkken/kit#1113
+// re-reads such a child only when the epic body *declared* the missing link, which is the direction
+// that makes `epic:next` exit 1 on a graph with nothing to fix. A relation recorded but never
+// declared leaves no trace in the body, so nothing marks the child as a suspect — and there the
+// mistake runs the other way: the child is classified runnable and handed to an unattended run,
+// which then implements a deliverable before the thing it needs. That is exactly the ordering
+// joshuafolkken/kit#1005 exists to preserve.
+//
+// So the summary is not trusted for the one child that is about to be offered. The candidate's
+// relations are read from the listing, and a listing that disagrees replaces that child's
+// `blocked_by` before `epic_classify.classify_children` is run again. Re-running the classifier
+// rather than testing the listing for emptiness is what makes a closed blocker and a cross-repository
+// blocker come out right without this module knowing anything about either.
+
+// Everything one confirmation walk needs: the children as the snapshot read them, the resolver the
+// caller classifies with, and how to read one child's relations without consulting the summary.
+interface ConfirmContext {
+	children: ReadonlyArray<EpicChild>
+	resolve: ResolveDependency
+	read_blockers: BlockersReader
+	// The issues this invocation may run, so a re-classified candidate weighs an outside blocker exactly
+	// as `decide` did (joshuafolkken/kit#1943). Absent, the classifier's own default applies.
+	running?: ReadonlySet<string> | undefined
+}
+
+// The answer for one repository: the children to offer, or the verdict that stands in its place when
+// every candidate was withheld.
+//
+// A list rather than one child since joshuafolkken/kit#1491: a repository runs as many children at
+// once as it has free lanes, and how many that is comes from the caller as `wanted`. The type says
+// nothing about lanes or epics — it is a list and a verdict, so the same walk serves one lane, six,
+// or a caller that has not been written yet.
+interface RepoAnswer {
+	children: ReadonlyArray<EpicChild>
+	verdict: EpicVerdict
+}
+
+// What one candidate's confirmation produced: whether it may be offered, and the children with the
+// listing's correction applied. The corrected list is carried forward so a second candidate is
+// classified against what the first read established rather than against the stale snapshot.
+interface CandidateVerdict {
+	is_confirmed: boolean
+	children: ReadonlyArray<EpicChild>
+}
+
+// What a walk of the bundle produced: the children confirmed for a lane, and the graph with every
+// correction the walk learned along the way applied.
+interface ConfirmWalk {
+	children: ReadonlyArray<EpicChild>
+	confirmed: ReadonlyArray<EpicChild>
+}
+
+const NO_ANOMALIES = 0
+const NO_LANES = 0
+const ONE_LANE = 1
+
+// Blocker sets, compared as sets: the listing and the summary-derived read need not agree on order,
+// and a difference in order is not a difference in dependencies.
+function is_same_blockers(
+	left: ReadonlyArray<IssueReference>,
+	right: ReadonlyArray<IssueReference>,
+): boolean {
+	const sorted = (blockers: ReadonlyArray<IssueReference>): string =>
+		blockers
+			.map((blocker) => epic_graph.key_of(blocker))
+			.toSorted((first, second) => first.localeCompare(second))
+			.join(',')
+
+	return sorted(left) === sorted(right)
+}
+
+// The children with one child's relations replaced by what the listing returned. Matched by identity
+// — repository and number — because two children of one epic can share a number across repositories.
+function with_blockers(
+	children: ReadonlyArray<EpicChild>,
+	target: EpicChild,
+	blocked_by: ReadonlyArray<IssueReference>,
+): Array<EpicChild> {
+	const key = epic_graph.key_of(target)
+
+	return children.map((child) =>
+		epic_graph.key_of(child) === key ? { ...child, blocked_by } : child,
+	)
+}
+
+// Whether the corrected graph still calls this child runnable. The whole classifier is re-run rather
+// than the listing tested for emptiness: a blocker that is closed, or one in another repository whose
+// release has published, resolves the dependency, and only the classifier knows that.
+function is_still_runnable(
+	child: EpicChild,
+	children: ReadonlyArray<EpicChild>,
+	context: ConfirmContext,
+): boolean {
+	const key = epic_graph.key_of(child)
+
+	return epic_classify
+		.classify_children(children, context.resolve, context.running)
+		.runnable.some((candidate) => epic_graph.key_of(candidate) === key)
+}
+
+// A read that failed withholds the candidate rather than confirming it. "Could not tell" is not
+// "nothing blocks it", and this is the one direction the guard may not fail in, because that answer
+// *starts* work — the same reason `epic-busy.ts` answers `wait` for a listing it could not read. The
+// caller then offers the next candidate or waits, and the whole-run timeout bounds the wait.
+async function read_or_withhold(
+	candidate: EpicChild,
+	read_blockers: BlockersReader,
+): Promise<Array<IssueReference> | undefined> {
+	try {
+		return await read_blockers(candidate)
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error)
+
+		console.warn(
+			`⚠ could not confirm the blockers of #${String(candidate.number)}: ${reason}\n` +
+				'  it is withheld rather than offered; asking again is what resolves this',
+		)
+
+		return undefined
+	}
+}
+
+// Said out loud for the same reason a failed read is: the caller reports only that every candidate
+// was withheld, and an operator reading that should not have to guess which relation did it.
+function warn_withheld(candidate: EpicChild, listed: ReadonlyArray<IssueReference>): void {
+	const named = listed.map((blocker) => epic_graph.key_of(blocker)).join(', ')
+
+	console.warn(
+		`⚠ #${String(candidate.number)} is withheld: its relations listing names ${named}, ` +
+			'which the dependency summary it was classified from did not count',
+	)
+}
+
+// Relations the listing recovered that this epic does not track as a child.
+//
+// `classify_children` weighs such a blocker since joshuafolkken/kit#1943, so a candidate that is still
+// offered here has only outside blockers the classifier found finished. The relation is still named,
+// because the run has just paid a request to learn it exists and the graph holds nothing to order it
+// against (joshuafolkken/kit#1121).
+function untracked_blockers(
+	listed: ReadonlyArray<IssueReference>,
+	children: ReadonlyArray<EpicChild>,
+): Array<IssueReference> {
+	const index = epic_graph.index_children(children)
+
+	return listed.filter((blocker) => !index.has(epic_graph.blocker_key(blocker)))
+}
+
+function warn_untracked(candidate: EpicChild, untracked: ReadonlyArray<IssueReference>): void {
+	const named = untracked.map((blocker) => epic_graph.key_of(blocker)).join(', ')
+
+	console.warn(
+		`⚠ #${String(candidate.number)} is offered although its relations listing names ${named}: ` +
+			'this epic does not track those, and every one of them is already finished',
+	)
+}
+
+// What the confirmation learned, said out loud. Every disagreement between the listing and the
+// summary produces a line, whichever way it was resolved.
+function warn_recovered(
+	candidate: EpicChild,
+	listed: ReadonlyArray<IssueReference>,
+	children: ReadonlyArray<EpicChild>,
+	is_confirmed: boolean,
+): void {
+	if (!is_confirmed) {
+		warn_withheld(candidate, listed)
+
+		return
+	}
+
+	const untracked = untracked_blockers(listed, children)
+
+	if (untracked.length > 0) warn_untracked(candidate, untracked)
+}
+
+// One candidate, confirmed against its own relations listing.
+async function confirm_one(
+	candidate: EpicChild,
+	context: ConfirmContext,
+): Promise<CandidateVerdict> {
+	const listed = await read_or_withhold(candidate, context.read_blockers)
+	if (listed === undefined) return { is_confirmed: false, children: context.children }
+
+	if (is_same_blockers(candidate.blocked_by, listed)) {
+		return { is_confirmed: true, children: context.children }
+	}
+
+	const children = with_blockers(context.children, candidate, listed)
+	const is_confirmed = is_still_runnable(candidate, children, context)
+
+	warn_recovered(candidate, listed, children, is_confirmed)
+
+	return { is_confirmed, children }
+}
+
+// The bundle walked from its head until `wanted` candidates have confirmed, or the bundle runs out.
+//
+// Walking on rather than making the whole repository wait is the recorded decision on
+// joshuafolkken/kit#1108: a healthy sibling should not be held for one child whose counter is stale,
+// and nobody repairs that counter — so the next poll would put the same child at the head and answer
+// the same way, and the wait would never clear. The worst case is one request per candidate, and it
+// happens only when every candidate is withheld, where the epic is broken and stopping is right.
+//
+// **It stops the moment the caller's appetite is met**, so asking for one child costs exactly what
+// it cost before joshuafolkken/kit#1491: the walk ends at the first confirmation.
+//
+// Recursive rather than a loop with two exits, because the corrected graph has to be threaded from
+// one candidate to the next: a second candidate is classified against what the first read
+// established rather than against the stale snapshot.
+async function confirm_candidates(
+	candidates: ReadonlyArray<EpicChild>,
+	context: ConfirmContext,
+	wanted: number,
+): Promise<ConfirmWalk> {
+	const [candidate, ...rest] = candidates
+
+	if (candidate === undefined || wanted <= NO_LANES) {
+		return { children: context.children, confirmed: [] }
+	}
+
+	const verdict = await confirm_one(candidate, context)
+	const taken = verdict.is_confirmed ? [candidate] : []
+	const next = { ...context, children: verdict.children }
+	const walk = await confirm_candidates(rest, next, wanted - taken.length)
+
+	return { children: walk.children, confirmed: [...taken, ...walk.confirmed] }
+}
+
+// The verdict once every candidate was withheld, read off the corrected graph rather than assumed.
+// `run` is still possible here — another repository may have work — and the caller's own
+// `repo_verdict` maps that to `wait`, exactly as it does for a repository that never had a candidate.
+function withheld_verdict(
+	children: ReadonlyArray<EpicChild>,
+	context: ConfirmContext,
+): EpicVerdict {
+	return epic_report.decide_verdict(
+		epic_classify.classify_children(children, context.resolve, context.running),
+		NO_ANOMALIES,
+	)
+}
+
+// The answer for one repository. An empty bundle costs no request and re-derives the verdict the
+// caller already had, so the path a repository with nothing to offer takes is unchanged.
+//
+// `wanted` defaults to one lane, so a caller written before joshuafolkken/kit#1491 asks for exactly
+// what it used to get.
+async function answer_for_repo(
+	candidates: ReadonlyArray<EpicChild>,
+	context: ConfirmContext,
+	wanted: number = ONE_LANE,
+): Promise<RepoAnswer> {
+	const outcome = await confirm_candidates(candidates, context, wanted)
+	if (outcome.confirmed.length > NO_LANES) return { children: outcome.confirmed, verdict: 'run' }
+
+	return { children: [], verdict: withheld_verdict(outcome.children, context) }
+}
+
+const epic_candidate_confirm = {
+	is_same_blockers,
+	untracked_blockers,
+	with_blockers,
+	is_still_runnable,
+	confirm_candidates,
+	withheld_verdict,
+	answer_for_repo,
+}
+
+export type { ConfirmContext, RepoAnswer }
+export { epic_candidate_confirm }