@joshuafolkken/kit 1.872.0

package/scripts/epic/epic-next-read.ts

@@ -0,0 +1,141 @@
+import { epic_cross_repo } from './epic-cross-repo'
+import { epic_fetch, type EpicSnapshot } from './epic-fetch'
+import { epic_graph } from './epic-graph'
+import type { EpicReference } from './epic-issue'
+
+// Reading the epics `josh epic:next` was given, before anything is classified (joshuafolkken/kit#1493).
+//
+// Split from the command itself because naming several epics turned one read into a walk, and a walk
+// has answers a single read did not: an epic that was skipped, and one that stopped everything.
+
+// A qualified epic is read by naming its repository in the read's REST path, so naming one we do
+// not own would send this command to a third party's tracker — which joshuafolkken/kit#869 forbids
+// for a child and forbids here for the same reason (joshuafolkken/kit#1016).
+const FOREIGN_EPIC = 'That epic belongs to another owner; this command only reads our own.'
+const NO_CHILDREN = 0
+
+// One epic as it was read: the reference the caller typed, and what GitHub answered for it. The
+// reference is kept because `EpicSnapshot` carries the repository the epic lives in but not the
+// epic's own number, and a multi-epic report has to say which graph a block came from.
+interface EpicRead {
+	reference: EpicReference
+	snapshot: EpicSnapshot
+}
+
+// What one reference produced: an epic to classify, a reason it was skipped, or a refusal that stops
+// the whole command. Exactly one field is ever set.
+interface ReadOutcome {
+	read?: EpicRead
+	notice?: string
+	refusal?: string
+}
+
+// Every epic that could be read, why any were skipped, and the refusal that stopped the walk.
+interface SnapshotReads {
+	reads: ReadonlyArray<EpicRead>
+	notices: ReadonlyArray<string>
+	refusal?: string
+}
+
+// Where the epic lives, or nothing when it belongs to another owner.
+function epic_repo_of(reference: EpicReference, current_repo: string): string | undefined {
+	const epic_repo = reference.repo ?? current_repo
+	const owner = epic_cross_repo.owner_of(current_repo)
+
+	return epic_cross_repo.is_same_owner_repo(epic_repo, owner) ? epic_repo : undefined
+}
+
+function childless(reference: EpicReference): string {
+	return `#${String(reference.number)} tracks no children in a task list.`
+}
+
+// The same epic named twice is one epic. Removed here rather than left to
+// `epic_lane_offer.dedupe_pools`: that one keeps a *child* from being entered twice, but by then the
+// duplicate epic has already been fetched — and an unattended run pays that fetch every polling
+// round. Keyed through `epic_graph.key_of`, so `858` and `joshuafolkken/kit#858` in one command are
+// recognized as the same epic rather than as two.
+function unique_references(
+	references: ReadonlyArray<EpicReference>,
+	current_repo: string,
+): ReadonlyArray<EpicReference> {
+	const seen = new Set<string>()
+	const unique: Array<EpicReference> = []
+
+	for (const reference of references) {
+		const repo = reference.repo ?? current_repo
+		const key = epic_graph.key_of({ repo, number: reference.number })
+
+		if (seen.has(key)) continue
+		seen.add(key)
+		unique.push(reference)
+	}
+
+	return unique
+}
+
+// **An epic whose body could not be read is not a childless epic.** The two are indistinguishable
+// downstream — a body that never arrived parses to zero children exactly as an unpopulated task list
+// does — and skipping it drops the epic from the views with no anomaly anywhere, so the run reports
+// the backlog empty and ends. Kept as a read instead, so `epic:next` sees the failed body and says so
+// (joshuafolkken/kit#1690).
+function is_childless(snapshot: EpicSnapshot): boolean {
+	if (snapshot.body_failure !== undefined) return false
+
+	return snapshot.child_numbers.length === NO_CHILDREN
+}
+
+// **A childless epic is skipped; a foreign one refuses.** The distinction is what each says about
+// the caller. A reference naming another owner's tracker is a read we must not make at all, so it
+// stops the command. An epic that is simply not populated yet is a valid, readable epic of ours — an
+// epic whose task list has not been filled in is the ordinary case — and refusing the
+// whole command for it would stop every *other* named epic's children being offered, on every
+// polling round, until a person noticed (joshuafolkken/kit#1493).
+async function read_one(reference: EpicReference, current_repo: string): Promise<ReadOutcome> {
+	const epic_repo = epic_repo_of(reference, current_repo)
+	if (epic_repo === undefined) return { refusal: FOREIGN_EPIC }
+	const snapshot = await epic_fetch.fetch_epic(reference.number, epic_repo, current_repo)
+
+	if (is_childless(snapshot)) return { notice: childless(reference) }
+
+	return { read: { reference, snapshot } }
+}
+
+function collect(outcome: ReadOutcome, reads: Array<EpicRead>, notices: Array<string>): void {
+	if (outcome.read !== undefined) reads.push(outcome.read)
+	if (outcome.notice !== undefined) notices.push(outcome.notice)
+}
+
+// **The reads are serial on purpose.** A reference naming another owner has to stop the command
+// before that repository is asked anything, and issuing them together would send every fetch before
+// the first refusal was seen — the read joshuafolkken/kit#1016 exists to prevent. The latency is the
+// price of that guarantee, and `unique_references` above is what keeps it from being paid twice for
+// one epic.
+async function read_snapshots(
+	references: ReadonlyArray<EpicReference>,
+	current_repo: string,
+): Promise<SnapshotReads> {
+	const reads: Array<EpicRead> = []
+	const notices: Array<string> = []
+
+	for (const reference of unique_references(references, current_repo)) {
+		const outcome = await read_one(reference, current_repo)
+
+		if (outcome.refusal !== undefined) return { reads, notices, refusal: outcome.refusal }
+		collect(outcome, reads, notices)
+	}
+
+	return { reads, notices }
+}
+
+const epic_next_read = {
+	FOREIGN_EPIC,
+	epic_repo_of,
+	childless,
+	unique_references,
+	is_childless,
+	read_one,
+	read_snapshots,
+}
+
+export type { EpicRead, ReadOutcome, SnapshotReads }
+export { epic_next_read }

package/scripts/epic/epic-next-views.ts

@@ -0,0 +1,144 @@
+import type { ConfirmContext } from './epic-candidate-confirm'
+import { epic_cross_repo } from './epic-cross-repo'
+import { epic_fetch, type EpicSnapshot } from './epic-fetch'
+import { epic_graph } from './epic-graph'
+import type { EpicReference } from './epic-issue'
+import { epic_lane_offer, type RepoPool } from './epic-lane-offer'
+import { epic_report, type EpicNextResult, type EpicVerdict } from './epic-report'
+
+// Several epics, answered as one (joshuafolkken/kit#1493).
+//
+// joshuafolkken/kit#1491 built the lane pool epic-agnostic on purpose: `epic-lane-offer.ts` takes an
+// array of `RepoPool`s and nothing below it knows what an epic is. What was still fixed at one was
+// the *caller* — `epic:next` read a single reference and built a single pool — so a repository with
+// six free lanes could only ever fill them from one graph. This module is that caller's other half:
+// one view per named epic, merged into one pool list and one verdict.
+//
+// **The priority order is the order the epics were named**, and it is a decision rather than a
+// fallback. Dependency depth was the alternative and it does not compare across graphs: depth is
+// measured inside one epic, so a depth-2 child of a five-deep epic and a depth-2 child of a two-deep
+// one make the same claim about entirely different amounts of remaining work, and there is no
+// relation between two epics to normalize against. Argument order is the one ranking a person typed
+// and can change, `epic_lane_offer.collect` already walks pools in the order it is given, and the
+// answer is readable from the output because each epic's block is headed by its own reference.
+// **Inside one epic nothing moves**: that epic's declared chain still decides which of its children
+// is a candidate, and this order only decides whose candidate takes a free lane first.
+
+const COMPLETE_VERDICT: EpicVerdict = 'complete'
+const ERROR_VERDICT: EpicVerdict = 'error'
+const ONE_EPIC = 1
+const BLOCK_SEPARATOR = '\n\n'
+
+// One epic, from its reference through to the classification of its children. The reference is kept
+// beside the snapshot because `EpicSnapshot` carries the repository the epic lives in but not the
+// epic's own number, and a multi-epic report has to say which graph a block came from.
+interface EpicView {
+	reference: EpicReference
+	snapshot: EpicSnapshot
+	result: EpicNextResult
+	// Every issue this invocation may run — the children of all the named epics, plus a backlog's
+	// standalone issues — which a candidate's blockers are re-weighed against at confirmation
+	// (joshuafolkken/kit#1943). Absent, a view confirms against its own epic's children alone.
+	running?: ReadonlySet<string>
+}
+
+// Written exactly as it was typed. A bare number stays bare, because qualifying it here would name
+// this repository in an answer about an epic the caller referred to without one.
+function format_reference(reference: EpicReference): string {
+	return `${reference.repo ?? ''}#${String(reference.number)}`
+}
+
+// What the candidate confirmation reads with. The blockers come from `epic_fetch`'s own reader, so
+// a candidate is addressed exactly as every other read of a child is — a cross-repository child
+// through its own repository, and a local one bare (joshuafolkken/kit#1012).
+function confirm_context(snapshot: EpicSnapshot, running?: ReadonlySet<string>): ConfirmContext {
+	return {
+		children: snapshot.children,
+		running,
+		resolve: epic_cross_repo.resolve_cross_repo,
+		read_blockers: async (child) =>
+			await epic_fetch.read_child_blockers(child, snapshot.current_repo),
+	}
+}
+
+// One pool per epic rather than one merged candidate list, because each pool is confirmed against
+// its own graph — the context is what a candidate's blockers are re-read with, and two epics are two
+// contexts. Merging the candidates into one array would confirm a child of epic B against epic A's
+// children. The de-duplication that keeps a child tracked by both epics out of the second pool is
+// `epic_lane_offer.dedupe_pools`, which runs where the pools are spent.
+function pools_of(views: ReadonlyArray<EpicView>, repo: string): ReadonlyArray<RepoPool> {
+	return views.map((view) => ({
+		candidates: epic_report.candidates_for_repo(view.result, repo),
+		context: confirm_context(view.snapshot, view.running),
+	}))
+}
+
+// The verdict standing in for every named epic when none of them offered a child. Combined through
+// `epic_lane_offer.combine_verdicts` — the same ranking the pool merge uses — so the two halves of a
+// multi-epic answer cannot disagree about which reason wins.
+// `error` is absent from that ranking and therefore outranks everything in it, which is the reading
+// this wants — but `error_view` below is what every caller acts on first, so no decision rests on
+// the absence.
+function combined_verdict(views: ReadonlyArray<EpicView>): EpicVerdict {
+	let verdict: EpicVerdict = COMPLETE_VERDICT
+
+	for (const view of views) verdict = epic_lane_offer.combine_verdicts(verdict, view.result.verdict)
+
+	return verdict
+}
+
+// One unusable graph refuses the whole answer. An anomaly says nothing in that epic may start, and
+// handing out another epic's child in the same breath would report a run as proceeding normally
+// while a graph a person has to look at goes unread.
+function error_view(views: ReadonlyArray<EpicView>): EpicView | undefined {
+	return views.find((view) => view.result.verdict === ERROR_VERDICT)
+}
+
+// The heading is added only where there is more than one epic to tell apart, so a single-epic
+// invocation prints exactly the text it printed before.
+function format_view(view: EpicView, is_many: boolean, current_repo: string): string {
+	const text = epic_report.format_result(view.result, current_repo)
+
+	return is_many ? `${format_reference(view.reference)}\n${text}` : text
+}
+
+function aggregate_text(views: ReadonlyArray<EpicView>, current_repo: string): string {
+	const is_many = views.length > ONE_EPIC
+
+	return views.map((view) => format_view(view, is_many, current_repo)).join(BLOCK_SEPARATOR)
+}
+
+// The running set with every issue that waits on a person taken out, and the views built from it
+// (joshuafolkken/kit#1943). A blocker in another named epic only waits when that blocker itself can
+// finish: one parked, or one that is itself blocked from outside, holds its dependants for a person
+// exactly as a parked blocker inside one epic does. Each pass removes what the previous one sent to a
+// person, so the set only shrinks, and the walk ends at the first pass that removes nothing.
+function settle_views(
+	running: ReadonlySet<string>,
+	build: (running: ReadonlySet<string>) => ReadonlyArray<EpicView>,
+): ReadonlyArray<EpicView> {
+	const views = build(running)
+	const stuck = new Set(
+		views.flatMap((view) => view.result.blocked_on_people.map((child) => epic_graph.key_of(child))),
+	)
+	// Deleted in a loop: `Set#difference` is not in this project's TS lib.
+	const settled = new Set(running)
+
+	for (const key of stuck) settled.delete(key)
+
+	return settled.size === running.size ? views : settle_views(settled, build)
+}
+
+const epic_next_views = {
+	settle_views,
+	format_reference,
+	confirm_context,
+	pools_of,
+	combined_verdict,
+	error_view,
+	format_view,
+	aggregate_text,
+}
+
+export type { EpicView }
+export { epic_next_views }