@joshuafolkken/kit 1.872.0

package/scripts/epic/epic-audit-cli.ts

@@ -0,0 +1,374 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { git_epic_decision } from '#scripts/git/git-epic-decision'
+import { git_epic_parse, type DependencyLink } from '#scripts/git/git-epic-parse'
+import { git_gh_command } from '#scripts/git/git-gh-command'
+import { issue_read } from '#scripts/issue/issue-read'
+import { epic_audit_logic, type AuditFinding, type ReferenceState } from './epic-audit'
+import { epic_audit_checks, type AuditChild } from './epic-audit-checks'
+import { epic_audit_orphans, type ClaimingSearch } from './epic-audit-orphans'
+import { epic_audit_rationale, type OrderPair } from './epic-audit-rationale'
+import { epic_audit_report, type AuditResult } from './epic-audit-report'
+import { epic_cross_repo } from './epic-cross-repo'
+import { epic_fetch, type EpicSnapshot } from './epic-fetch'
+import { epic_graph, type IssueReference } from './epic-graph'
+import { epic_issue } from './epic-issue'
+import { epic_next } from './epic-next'
+
+// `josh epic:audit <E>` — read an epic's children against each other and report what contradicts
+// what (joshuafolkken/kit#870).
+
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const USAGE = 'Usage: josh epic:audit <epic-number>'
+// Check 3 filters the issues the children cite down to this owner's repositories, so a repository
+// name it could not read silently dropped every qualified reference and reported nothing. A check
+// that disables itself without saying so is worse than one that fails: the report reads clean
+// (joshuafolkken/kit#1016).
+const UNREADABLE_REPO =
+	'Could not read this repository as `owner/name`, so a reference could not be resolved against it — check `gh auth status` and that this checkout has a GitHub remote.'
+
+// Each child again, this time with its body. `epic:next`'s fetch reads state, labels and relations;
+// the bodies are what this command exists to read, so they are fetched here rather than widening
+// that one — a `wait` poll should not pay for prose it never looks at.
+//
+// The scope comes from `epic_fetch.scope_for`, the same convention the state and relation reads
+// follow, rather than a second spelling here. Without it a cross-repository child's body was read
+// from *this* repository's issue of that number, and all four body-reading checks then ran against
+// the wrong text (joshuafolkken/kit#1012).
+async function attach_bodies(
+	children: ReadonlyArray<AuditChild>,
+	repo: string,
+): Promise<Array<AuditChild>> {
+	const bodies = await Promise.all(
+		children.map(
+			async (child) =>
+				await git_gh_command.issue_get_body(
+					String(child.number),
+					epic_fetch.scope_for(child.repo, repo),
+				),
+		),
+	)
+
+	return children.map((child, index) => ({ ...child, body: bodies[index] }))
+}
+
+// Whether each referenced issue is open, closed, or absent. Only issues actually cited are probed,
+// so an epic whose children cite nothing costs no extra calls.
+//
+// Each one is asked of the repository whose body named it, through the same `epic_fetch.scope_for`
+// every other read goes through, and the answers are keyed by that repository and number both. Asked
+// unqualified, a cross-repository child's `#40` was answered by *this* repository's issue 40 — a
+// different issue, whose state then decided the warning (joshuafolkken/kit#1014).
+async function resolve_reference_states(
+	referenced: ReadonlyArray<IssueReference>,
+	current_repo: string,
+): Promise<Map<string, ReferenceState>> {
+	const fetched = await Promise.all(
+		referenced.map(
+			async (reference) =>
+				await epic_fetch.fetch_child(
+					reference.number,
+					reference.repo,
+					epic_fetch.scope_for(reference.repo, current_repo),
+				),
+		),
+	)
+
+	return new Map(
+		referenced.map((reference, index) => [
+			epic_graph.key_of(reference),
+			fetched[index]?.state ?? 'UNRESOLVED',
+		]),
+	)
+}
+
+// The issues the children cite that are not children themselves — the ones check 3 resolves.
+//
+// A reference in a repository this owner does not own is left out rather than probed, inheriting
+// joshuafolkken/kit#869's restriction exactly as `fetch_external_children` does: a body mentioning a
+// third party's issue must not send this command to their tracker.
+function outside_references(
+	children: ReadonlyArray<AuditChild>,
+	current_repo: string,
+): Array<IssueReference> {
+	const own = new Set(children.map((child) => epic_graph.key_of(child)))
+	const known = epic_audit_logic.known_repos(children, current_repo)
+	const cited = children.flatMap((child) =>
+		epic_audit_logic.parse_issue_references(child.body ?? '', child.repo, known),
+	)
+	const owner = epic_cross_repo.owner_of(current_repo)
+
+	return epic_audit_logic
+		.unique_references(cited)
+		.filter((reference) => !own.has(epic_graph.key_of(reference)))
+		.filter((reference) => epic_cross_repo.is_same_owner_repo(reference.repo, owner))
+}
+
+// Everything read from GitHub that the checks need.
+interface AuditInput {
+	epic_number: number
+	// The `owner/repo` the command runs in. A reference is written bare when it names an issue here
+	// and `owner/repo#N` when it does not, so the reader is never handed a number that resolves
+	// somewhere else (joshuafolkken/kit#1014).
+	repo: string
+	children: ReadonlyArray<AuditChild>
+	tracked: ReadonlyArray<number>
+	reference_states: ReadonlyMap<string, ReferenceState>
+	// The orphan search's whole outcome, not just what it found: a listing that failed and a listing
+	// the page ceiling cut short are both reported, because `[]` here is indistinguishable from
+	// "nothing claims this epic" (joshuafolkken/kit#1033).
+	claiming: ClaimingSearch
+	anomalies: ReadonlyArray<AuditFinding>
+	// Computed before the implicit-dependency check so that check can skip the pairs already reported
+	// as errors — the acceptance criteria are part of the body, so every one of them would otherwise
+	// arrive twice.
+	contradictions: ReadonlyArray<AuditFinding>
+	// The declared orders check 6 may speak about, already resolved to children and narrowed to the
+	// open, local pairs (joshuafolkken/kit#1712).
+	order_pairs: ReadonlyArray<OrderPair>
+	// The epic's `## Decisions` section, and the comments on those pairs' ends — the two places a
+	// placement decision is recorded, and therefore the whole of what check 6 reads.
+	decisions: string
+	order_comments: ReadonlyMap<string, ReadonlyArray<string>>
+	// Whether the epic's own state is confirmed closed. An unreadable state is `false`, so the
+	// closed-epic-with-open-children check never fires on a lookup that did not answer
+	// (joshuafolkken/kit#2337).
+	is_epic_closed: boolean
+}
+
+// The checks that read what the children say about each other.
+function body_findings(input: AuditInput): Array<AuditFinding> {
+	return [
+		...epic_audit_checks.find_implicit_dependencies(
+			input.children,
+			input.repo,
+			input.contradictions,
+		),
+		...epic_audit_checks.find_unresolved_references(
+			input.children,
+			input.reference_states,
+			input.repo,
+		),
+		...epic_audit_checks.find_nested_epics(input.children, input.repo),
+	]
+}
+
+// The checks that read the epic's own declaration and its task list.
+function epic_findings(input: AuditInput): Array<AuditFinding> {
+	return [
+		...epic_audit_rationale.find_unjustified_orders({
+			pairs: input.order_pairs,
+			decisions: input.decisions,
+			comments: input.order_comments,
+			current_repo: input.repo,
+		}),
+		...epic_audit_orphans.search_findings(input.claiming),
+		...epic_audit_checks.find_orphans(
+			input.tracked,
+			epic_audit_orphans.claimed_numbers(input.claiming),
+		),
+		...epic_audit_checks.find_closed_epic_open_children(
+			input.is_epic_closed,
+			input.children,
+			input.repo,
+		),
+	]
+}
+
+// The audit itself, from already-gathered data, so the whole decision is testable without GitHub.
+function audit(input: AuditInput): AuditResult {
+	return epic_audit_report.build_result([
+		...input.anomalies,
+		...input.contradictions,
+		...body_findings(input),
+		...epic_findings(input),
+	])
+}
+
+// The graph anomalies, taken from joshuafolkken/kit#860's detection rather than re-derived here —
+// including its rule for whether the body declares an order at all, which is imported rather than
+// restated for exactly the drift this comment warns about.
+function graph_anomalies(
+	snapshot: EpicSnapshot,
+	children: ReadonlyArray<AuditChild>,
+	links: ReadonlyArray<DependencyLink>,
+): Array<AuditFinding> {
+	const is_declared = epic_next.is_order_declared(snapshot.body, links)
+
+	return epic_audit_report.anomaly_findings(
+		epic_graph.find_anomalies(children, links, is_declared, snapshot.repo),
+	)
+}
+
+// The findings that come from the fetch and the graph rather than from reading the bodies.
+function fetch_anomalies(
+	snapshot: EpicSnapshot,
+	children: ReadonlyArray<AuditChild>,
+	links: ReadonlyArray<DependencyLink>,
+): Array<AuditFinding> {
+	return [
+		...epic_audit_report.unreadable_findings(
+			epic_fetch.missing_children(snapshot),
+			snapshot.current_repo,
+		),
+		...graph_anomalies(snapshot, children, links),
+	]
+}
+
+// The comments on the ends of the declared orders check 6 asks about — and on nothing else. Most
+// epics declare no order at all, so this reads nothing; an epic that declares a chain pays one
+// listing per issue in it.
+//
+// A listing that could not be read is left out of the map rather than entered as `[]`, so a
+// transport failure reads as "not asked" instead of "nobody recorded anything" — the finding it
+// would otherwise manufacture is an `error`, which stops the epic.
+async function read_order_comments(
+	pairs: ReadonlyArray<OrderPair>,
+): Promise<Map<string, ReadonlyArray<string>>> {
+	const ends = epic_audit_rationale.pair_ends(pairs)
+	const listings = await Promise.all(
+		ends.map(async (child) => await git_gh_command.issue_list_comments(String(child.number))),
+	)
+
+	return new Map(
+		ends.flatMap((child, index) => {
+			const comments = issue_read.parse_comments(listings[index])
+
+			return comments === undefined
+				? []
+				: [[epic_graph.key_of(child), comments.map((comment) => comment.body)] as const]
+		}),
+	)
+}
+
+// Why a snapshot yields nothing to audit, with the two reasons told apart (joshuafolkken/kit#1690).
+// A body nobody could read parses to zero children exactly as an unpopulated task list does, so
+// without this the audit reported an epic it never read as one tracking no children — and sent the
+// reader to fill in a task list that is already there.
+function no_children_reason(snapshot: EpicSnapshot, epic_number: number): string | undefined {
+	if (snapshot.body_failure !== undefined) {
+		return `Could not read the body of #${String(epic_number)}. Its task list is what names the children — check \`gh auth status\` and the connection.`
+	}
+
+	if (snapshot.child_numbers.length === 0) {
+		return `#${String(epic_number)} tracks no children in a task list.`
+	}
+
+	return undefined
+}
+
+// Whether the epic's own state is confirmed closed. Read through the same `scope_for` every other
+// read goes through, so a cross-repository epic is asked of its own repository rather than this one.
+// A read that came back shaped wrong, or a state that is not `CLOSED`, both answer `false`: the
+// finding it feeds is an error, and one must never be manufactured from a lookup that did not answer
+// (joshuafolkken/kit#2337).
+async function read_epic_closed(epic_number: number, scope?: string): Promise<boolean> {
+	const raw = await git_gh_command.issue_get_state_and_relations(String(epic_number), scope)
+	const parsed = epic_issue.parse_epic_issue(raw)
+
+	return parsed !== undefined && epic_issue.normalize_state(parsed.state) === epic_issue.CLOSED
+}
+
+// Everything the input needs once the children have been read: the declaration is parsed once here
+// and handed to both the graph anomalies and check 6, rather than parsed twice.
+async function to_audit_input(
+	snapshot: EpicSnapshot,
+	children: ReadonlyArray<AuditChild>,
+	epic_number: number,
+	repo: string,
+): Promise<AuditInput> {
+	const links = git_epic_parse.parse_dependency_links(snapshot.body)
+	const order_pairs = epic_audit_rationale.order_pairs(links, children, snapshot.repo, repo)
+
+	return {
+		epic_number,
+		repo,
+		children,
+		tracked: epic_audit_orphans.locally_tracked(snapshot),
+		reference_states: await resolve_reference_states(outside_references(children, repo), repo),
+		claiming: await epic_audit_orphans.find_claiming_issues(epic_number, repo),
+		anomalies: fetch_anomalies(snapshot, children, links),
+		contradictions: epic_audit_checks.find_order_contradictions(children, repo),
+		order_pairs,
+		decisions: git_epic_decision.read_recorded_reasons(snapshot.body),
+		order_comments: await read_order_comments(order_pairs),
+		is_epic_closed: await read_epic_closed(epic_number, epic_fetch.scope_for(snapshot.repo, repo)),
+	}
+}
+
+async function gather(epic_number: number, repo: string): Promise<AuditInput | undefined> {
+	const snapshot = await epic_fetch.fetch_epic(epic_number, repo)
+	const reason = no_children_reason(snapshot, epic_number)
+
+	if (reason !== undefined) {
+		console.error(reason)
+
+		return undefined
+	}
+
+	const children = await attach_bodies(
+		snapshot.children.map((child) => ({ ...child, body: undefined })),
+		repo,
+	)
+
+	if (snapshot.has_external_children) console.info(epic_next.EXTERNAL_NOTICE)
+
+	return await to_audit_input(snapshot, children, epic_number, repo)
+}
+
+async function report_audit(epic_number: number, repo: string): Promise<number> {
+	const input = await gather(epic_number, repo)
+	if (input === undefined) return FAILURE_EXIT_CODE
+	const result = audit(input)
+
+	console.info(epic_audit_report.format_report(result))
+
+	return result.exit_code
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const epic_number = epic_issue.parse_epic_number(argv[0])
+
+	if (epic_number === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const repo = await git_gh_command.repo_get_name_with_owner()
+
+	if (repo === undefined) {
+		console.error(UNREADABLE_REPO)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	return await report_audit(epic_number, repo)
+}
+
+// `process.exitCode` rather than `process.exit()`: the answer goes to standard output and a write to
+// a pipe is asynchronous on macOS, so exiting can tear the process down before it drains. This
+// command's answer is what a workflow reads and acts on, which is exactly that pipe. The same shape
+// is in `scripts/cost-runtime/cost-cli.ts`, which met the truncation first (joshuafolkken/kit#1005).
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const epic_audit_cli = {
+	USAGE,
+	UNREADABLE_REPO,
+	parse_epic_number: epic_issue.parse_epic_number,
+	attach_bodies,
+	resolve_reference_states,
+	outside_references,
+	read_order_comments,
+	audit,
+	run,
+	main,
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export type { AuditInput }
+export { epic_audit_cli }

package/scripts/epic/epic-audit-orphans.ts

@@ -0,0 +1,142 @@
+import { git_epic_parse } from '#scripts/git/git-epic-parse'
+import { git_gh_command } from '#scripts/git/git-gh-command'
+import { cutoff_of, PAGE_CEILING_CAUSE, type ScanCutoff } from '#scripts/git/listing-cutoff'
+import { parse_json_array_safe } from '#scripts/git/parse-json-array'
+import { z } from 'zod'
+import { epic_audit_logic, type AuditFinding, type FindingLevel } from './epic-audit'
+import type { EpicSnapshot } from './epic-fetch'
+
+// Check 4's half of `epic:audit`: an issue that names this epic as its parent but that the epic's
+// task list does not track. It would never be run, and the epic would close without it.
+//
+// Split from the command because it shares nothing with the rest of it — the other three checks read
+// the children the epic already names, while this one searches for issues the epic does *not* name
+// (joshuafolkken/kit#1016).
+
+const SEARCH_LIMIT = 50
+const PARENT_MARKERS: ReadonlyArray<string> = ['親:', 'Parent:', '親：']
+// Named apart from `epic_audit_checks.ORPHAN_CHILD`: that check reports an orphan it found, this one
+// reports that the search for orphans was incomplete, and a reader has to be able to tell them apart.
+const ORPHAN_SEARCH = 'orphan search'
+const UNREADABLE_SEARCH =
+	'Could not list the open issues, so an issue naming this epic as its parent would not have been found.'
+const CAPPED_BY_ISSUES = `The open-issue scan ${PAGE_CEILING_CAUSE}; an issue older than that was not looked at.`
+const CAPPED_BY_MATCHES = `The open-issue scan filled its ${String(SEARCH_LIMIT)}-match cap; an issue mentioning this epic further down the backlog was not looked at.`
+
+const searched_issue_schema = z.object({ number: z.number(), body: z.string().nullable() })
+
+function has_parent_marker(line: string): boolean {
+	return PARENT_MARKERS.some((marker) => line.includes(marker))
+}
+
+// Whether an issue's body names this epic as its parent, in the shape the issue template uses.
+//
+// Both halves must be on the *same line*. An issue parented to a different epic routinely backlinks
+// this one elsewhere in its body, and matching the marker and the number independently reported
+// every such issue as an orphan.
+//
+// The number is read through the same reference parse the checks use, so a parent line (a PARENT_MARKERS
+// prefix) such as `owner/other#858` names that repository's epic and not this one's (joshuafolkken/kit#1014).
+// The known set is this repository alone — a parent line names this epic or it names nothing here —
+// and it is passed rather than omitted so a repository whose own name contains a dot still recognizes
+// `joshuafolkken/site.com#858` (joshuafolkken/kit#1016).
+function names_this_epic(line: string, epic_number: number, repo: string): boolean {
+	return epic_audit_logic
+		.parse_issue_references(line, repo, epic_audit_logic.known_repos([], repo))
+		.some((reference) => reference.repo === repo && reference.number === epic_number)
+}
+
+function claims_parent(body: string | null, epic_number: number, repo: string): boolean {
+	return (body ?? '')
+		.split('\n')
+		.some((line) => has_parent_marker(line) && names_this_epic(line, epic_number, repo))
+}
+
+// Why the scan stopped before the end of the open backlog, or that it did not. Both cutoffs hide the
+// same thing — an older issue naming this epic — and they are told apart only so the report can say
+// which one to raise (joshuafolkken/kit#1033).
+//
+// The vocabulary is `listing-cutoff.ts`'s since joshuafolkken/kit#1067, because every caller of the
+// listing now asks this question and a second definition of "I saw everything" is the clone
+// `CLAUDE.md` prohibits. `page_ceiling` is the paging's; `row_limit` here means `SEARCH_LIMIT` body
+// mentions of `#<epic>` came back and the scan stopped there.
+
+// What the search found, and what it could not cover. The `read` / `unreadable` vocabulary is
+// `git-gh-issue-read.ts`'s, and the union rather than a flag beside the numbers is deliberate: a
+// cutoff on an unreadable search would describe pages that were never fetched.
+type ClaimingSearch =
+	{ kind: 'read'; numbers: Array<number>; cutoff: ScanCutoff } | { kind: 'unreadable' }
+
+// Open issues naming this epic as their parent. Searched rather than derived, because an orphan is
+// by definition absent from the one list that would otherwise name it.
+//
+// A failed search used to yield `[]` on the reasoning that an unavailable search is no evidence of
+// an orphan. That is true of the *finding* and false of the *report*: `[]` is what "no issue claims
+// this epic" looks like, so a rate limit arrived as a clean audit — the same "could not read" read
+// as "there is nothing" that joshuafolkken/kit#925, #950, #973 and #1048 closed elsewhere. The
+// answer is now carried out and reported instead (joshuafolkken/kit#1033).
+async function find_claiming_issues(epic_number: number, repo: string): Promise<ClaimingSearch> {
+	const { json, is_capped } = await git_gh_command.issue_search_body(
+		`#${String(epic_number)}`,
+		SEARCH_LIMIT,
+	)
+	if (json === undefined) return { kind: 'unreadable' }
+	const rows = parse_json_array_safe(json, searched_issue_schema)
+
+	const numbers = rows
+		.filter((issue) => issue.number !== epic_number && claims_parent(issue.body, epic_number, repo))
+		.map((issue) => issue.number)
+
+	return { kind: 'read', numbers, cutoff: cutoff_of(rows.length, SEARCH_LIMIT, is_capped) }
+}
+
+function search_finding(level: FindingLevel, message: string): Array<AuditFinding> {
+	return [{ level, check: ORPHAN_SEARCH, message }]
+}
+
+// The gap the search itself leaves, as findings, so it is never absorbed into "no orphans".
+//
+// An unreadable listing is an **error**: check 4 did not run at all, and an audit that reported a
+// clean bill on that input would contradict itself — the same level `epic:audit` already gives a
+// child it could not read, and the level a rate limit already fails this command at through that
+// check.
+//
+// Either cutoff is a **warning**: the scan *did* run, over the newest issues, and an orphan is
+// normally an issue filed minutes ago. That is something to read rather than a check that did not
+// happen — the level `epic:bundle` reports its own `⚠ … cap` at (joshuafolkken/kit#950).
+function search_findings(search: ClaimingSearch): Array<AuditFinding> {
+	if (search.kind === 'unreadable') return search_finding('error', UNREADABLE_SEARCH)
+	if (search.cutoff === 'page_ceiling') return search_finding('warning', CAPPED_BY_ISSUES)
+	if (search.cutoff === 'row_limit') return search_finding('warning', CAPPED_BY_MATCHES)
+
+	return []
+}
+
+// The numbers the orphan check compares against the task list. Empty when the search failed, which
+// `search_findings` has already reported as an error — so the check contributes nothing rather than
+// asserting that nothing claims the epic.
+function claimed_numbers(search: ClaimingSearch): Array<number> {
+	return search.kind === 'read' ? search.numbers : []
+}
+
+// The task-list numbers that name issues in *this* repository. `snapshot.child_numbers` appends the
+// cross-repository children's numbers, and an orphan is recognized by number alone — so a local
+// issue whose number collided with a child in another repository was accepted as tracked and never
+// reported (joshuafolkken/kit#1014). Read with the same parser `epic_fetch` reads the local rows
+// with, which never matches a `- [ ] owner/repo#N` row.
+function locally_tracked(snapshot: EpicSnapshot): Array<number> {
+	return git_epic_parse.parse_task_list_issue_numbers(snapshot.body)
+}
+
+const epic_audit_orphans = {
+	PARENT_MARKERS,
+	ORPHAN_SEARCH,
+	claimed_numbers,
+	claims_parent,
+	find_claiming_issues,
+	locally_tracked,
+	search_findings,
+}
+
+export type { ClaimingSearch }
+export { epic_audit_orphans }