@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/issue/defect-origin-cli.ts

@@ -0,0 +1,106 @@
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import type { IssueRead } from '#scripts/gh/git-gh-issue-read'
+import { git_spawn } from '#scripts/git/git-spawn'
+import { parse_json } from '#scripts/git/parse-json-array'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { run_prep_locate } from '#scripts/run/run-prep-locate'
+import { z } from 'zod'
+import { defect_origin, type Candidate, type Merge, type TargetMerges } from './defect-origin'
+import { issue_read_cli } from './issue-read-cli'
+import { session_cite } from './session-cite'
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const USAGE = 'Usage: pnpm josh defect:origin <N>'
+const UNREADABLE_MESSAGE = 'Could not read the issue, so no origin candidate is listed:'
+const UNSEARCHABLE_MESSAGE = 'Could not search the merge history for'
+
+const filed_schema = z.object({ createdAt: z.string() })
+
+interface IssueText {
+	text: string
+	filed_at: string | undefined
+}
+
+// A target that git cannot search is named on stderr and contributes nothing, rather than ending the
+// listing or passing for a target no merge touched.
+async function read_merges(
+	target: string,
+	arguments_: Array<string>,
+): Promise<ReadonlyArray<Merge>> {
+	try {
+		return defect_origin.parse_merges(await git_spawn.read(arguments_))
+	} catch {
+		console.error(`${UNSEARCHABLE_MESSAGE} ${target}`)
+
+		return []
+	}
+}
+
+// A path is looked up by pathspec; a name no path matches, by the merges that added or removed it.
+async function merges_for(target: string, before: string | undefined): Promise<TargetMerges> {
+	const by_path = await read_merges(target, defect_origin.path_arguments(target, before))
+	const merges =
+		by_path.length > 0
+			? by_path
+			: await read_merges(target, defect_origin.pickaxe_arguments(target, before))
+
+	return { target, merges }
+}
+
+async function candidates_for(issue: IssueText): Promise<ReadonlyArray<Candidate>> {
+	const targets = run_prep_locate.extract_targets(issue.text)
+	const found = await Promise.all(
+		targets.map(async (target) => await merges_for(target, issue.filed_at)),
+	)
+
+	return defect_origin.rank(found)
+}
+
+async function listing(issue_number: string, issue: IssueText): Promise<string> {
+	return defect_origin.format(issue_number, await candidates_for(issue))
+}
+
+// An unreadable filing time leaves the log unbounded rather than listing nothing.
+function filed_at_of(read: IssueRead): string | undefined {
+	if (read.kind !== 'read') return undefined
+
+	return parse_json.parse_json_object_or_undefined(read.json, filed_schema)?.createdAt
+}
+
+// The body and trusted comments as `issue:read` prints them, and when the issue was filed; the
+// failure kind when the issue could not be read.
+async function read_issue(issue_number: string): Promise<IssueText | string> {
+	const [read, filed] = await Promise.all([
+		issue_read_cli.read_block(issue_number),
+		git_gh_command.issue_view_json_classified(issue_number, 'createdAt'),
+	])
+
+	return read.kind === 'ok' ? { text: read.block, filed_at: filed_at_of(filed) } : read.kind
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const [issue_number = ''] = argv
+
+	if (argv.length !== 1 || !issue_number_shape.is_issue_number(issue_number)) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const issue = await read_issue(issue_number)
+
+	if (typeof issue === 'string') {
+		console.error(`${UNREADABLE_MESSAGE} ${issue}`)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	console.info(session_cite.text(await listing(issue_number, issue)))
+
+	return SUCCESS_EXIT_CODE
+}
+
+const defect_origin_cli = { USAGE, run }
+
+export { defect_origin_cli }

package/scripts/issue/defect-origin-line.ts

@@ -0,0 +1,78 @@
+import { issue_bug_label } from './issue-bug-label'
+import { markdown_section } from './markdown-section'
+import { reproduction_measure } from './reproduction-measure'
+
+// The origin line a bug body declares under its background heading: the merged pull request that
+// introduced the defect, or "unknown" with the reason it could not be traced. `defect:report` groups
+// defects by it, so a bug filed without one is a defect nobody can attribute.
+
+const ORIGIN_PREFIX = '- 原因:'
+const PR_LINE = /^- 原因: #(?<pr>\d+)$/u
+const UNKNOWN_LINE = /^- 原因: 不明（(?<reason>[^）]*)）$/u
+const MISSING_ORIGIN =
+	'missing origin line: a `- 種別: 不具合` body declares `- 原因: #<PR>` or `- 原因: 不明（<reason>）` under ## 背景 (`pnpm josh defect:origin <N>` lists candidates)'
+const MALFORMED_ORIGIN =
+	'malformed origin line: write `- 原因: #<PR>` or `- 原因: 不明（<reason>）` with a non-empty reason'
+const MISSING_REPRODUCTION =
+	'missing reproduction: a `- 原因: 不明（<reason>）` bug carries ## 再現 with a backticked command and its actual output in a fenced block'
+
+type DefectOrigin = { kind: 'pr'; pr: number } | { kind: 'unknown'; reason: string }
+
+function origin_lines(body: string): ReadonlyArray<string> {
+	const background = markdown_section.section_lines(body, '## 背景').join('\n')
+
+	return markdown_section
+		.unfenced_lines(background)
+		.map((line) => line.trim())
+		.filter((line) => line.startsWith(ORIGIN_PREFIX))
+}
+
+function parse_unknown(line: string): DefectOrigin | undefined {
+	const reason = (UNKNOWN_LINE.exec(line)?.groups?.['reason'] ?? '').trim()
+
+	return reason === '' ? undefined : { kind: 'unknown', reason }
+}
+
+function parse_line(line: string): DefectOrigin | undefined {
+	const pr = PR_LINE.exec(line)?.groups?.['pr']
+
+	return pr === undefined ? parse_unknown(line) : { kind: 'pr', pr: Number(pr) }
+}
+
+// The declared origin, or `undefined` when the body carries no well-formed origin line.
+function parse(body: string): DefectOrigin | undefined {
+	const [first] = origin_lines(body)
+
+	return first === undefined ? undefined : parse_line(first)
+}
+
+// Why a bug body's origin line is refused, or `undefined` when it is not a bug or the line is sound.
+function problem(body: string): string | undefined {
+	if (!issue_bug_label.is_bug_fix(body)) return undefined
+
+	const lines = origin_lines(body)
+
+	if (lines.length === 0) return MISSING_ORIGIN
+
+	return lines.every((line) => parse_line(line) !== undefined) ? undefined : MALFORMED_ORIGIN
+}
+
+// An untraced bug owes the lane a way to see it: without a reproduction the run starts by
+// investigating. A traced one (a pull request origin) already names where to look, so it owes none.
+function reproduction_problem(body: string): string | undefined {
+	if (!issue_bug_label.is_bug_fix(body) || parse(body)?.kind !== 'unknown') return undefined
+
+	return reproduction_measure.has_command_output(body) ? undefined : MISSING_REPRODUCTION
+}
+
+const defect_origin_line = {
+	MALFORMED_ORIGIN,
+	MISSING_ORIGIN,
+	MISSING_REPRODUCTION,
+	parse,
+	problem,
+	reproduction_problem,
+}
+
+export type { DefectOrigin }
+export { defect_origin_line }

package/scripts/issue/defect-origin-main.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { defect_origin_cli } from './defect-origin-cli'
+
+// The `josh defect:origin` entry, kept apart from `defect-origin-cli.ts` so a bundle carrying that
+// module never fires this guard (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await defect_origin_cli.run(process.argv.slice(ARGV_OFFSET))
+}

package/scripts/issue/defect-origin.ts

@@ -0,0 +1,114 @@
+import { issue_cite } from './issue-cite'
+
+// Candidate origins for a defect: the merged pull requests that last changed what its issue names.
+// Each backticked path or identifier is looked up in the first-parent merge history — a path by
+// pathspec, anything else by `-S` — and the merges are folded per pull request, newest first. The
+// command only proposes; the filer decides which line to write.
+
+const FIELD = '\u{1F}'
+const RECORD = '\u{1E}'
+const LOG_FORMAT = `--format=%cI${FIELD}%s${FIELD}%b${RECORD}`
+const MERGE_RECORD = new RegExp(
+	String.raw`^(?<merged_at>[^${FIELD}]*)${FIELD}Merge pull request #(?<pr>\d+) from [^${FIELD}]*${FIELD}(?<title>[^\n]*)`,
+	'u',
+)
+const LOG_LIMIT = '--max-count=5'
+const MAX_CANDIDATES = 5
+const DATE_LENGTH = 'YYYY-MM-DD'.length
+const ORIGIN_HINT = '`- 原因: #<PR>`'
+const NO_CANDIDATES = '(no merged pull request changed what the issue names)'
+
+interface Merge {
+	pr: number
+	merged_at: string
+	title: string
+}
+
+interface Candidate extends Merge {
+	targets: ReadonlyArray<string>
+}
+
+interface TargetMerges {
+	target: string
+	merges: ReadonlyArray<Merge>
+}
+
+const BASE_ARGUMENTS = ['log', '--first-parent', '--merges', '--diff-merges=first-parent', '-s']
+
+// A merge after the issue was filed cannot have introduced what it reports, so `before` bounds the log.
+function base_arguments(before: string | undefined): Array<string> {
+	const bound = before === undefined ? [] : [`--before=${before}`]
+
+	return [...BASE_ARGUMENTS, ...bound, LOG_LIMIT, LOG_FORMAT]
+}
+
+function path_arguments(target: string, before?: string): Array<string> {
+	return [...base_arguments(before), '--', `:(glob)**/${target}`]
+}
+
+function pickaxe_arguments(target: string, before?: string): Array<string> {
+	return [...base_arguments(before), `-S${target}`]
+}
+
+// The merge's date, its pull request read off the subject, and the title — the body's first line.
+function parse_record(record: string): Merge | undefined {
+	const groups = MERGE_RECORD.exec(record.trim())?.groups
+
+	if (groups === undefined) return undefined
+
+	return {
+		pr: Number(groups['pr']),
+		merged_at: String(groups['merged_at']),
+		title: String(groups['title']),
+	}
+}
+
+function parse_merges(output: string): ReadonlyArray<Merge> {
+	return output
+		.split(RECORD)
+		.map((record) => parse_record(record))
+		.filter((merge) => merge !== undefined)
+}
+
+function fold(found: ReadonlyArray<TargetMerges>): Map<number, Candidate> {
+	const by_pr = new Map<number, Candidate>()
+
+	for (const { target, merges } of found) {
+		for (const merge of merges) {
+			const targets = by_pr.get(merge.pr)?.targets ?? []
+
+			by_pr.set(merge.pr, { ...merge, targets: [...targets, target] })
+		}
+	}
+
+	return by_pr
+}
+
+// The pull requests behind every target's merges, newest merge first, at most five.
+function rank(found: ReadonlyArray<TargetMerges>): ReadonlyArray<Candidate> {
+	return [...fold(found).values()]
+		.toSorted((left, right) => right.merged_at.localeCompare(left.merged_at))
+		.slice(0, MAX_CANDIDATES)
+}
+
+function format_candidate(candidate: Candidate): string {
+	const date = candidate.merged_at.slice(0, DATE_LENGTH)
+	const changed = candidate.targets.join(', ')
+
+	return `${issue_cite.plain(candidate.pr)}  ${date}  ${candidate.title}\n  changed: ${changed}`
+}
+
+function format(issue_number: string, candidates: ReadonlyArray<Candidate>): string {
+	const header = `origin candidates for ${issue_cite.plain(issue_number)} (newest first; declare one as ${ORIGIN_HINT}):`
+	const lines =
+		candidates.length === 0
+			? [NO_CANDIDATES]
+			: candidates.map((candidate) => format_candidate(candidate))
+
+	return [header, ...lines].join('\n')
+}
+
+const defect_origin = { format, parse_merges, path_arguments, pickaxe_arguments, rank }
+
+export type { Candidate, Merge, TargetMerges }
+export { defect_origin }

package/scripts/issue/defect-rate-cli.ts

@@ -1,152 +1,34 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
-import { git_gh_command } from '#scripts/gh/git-gh-command'
-import { git_gh_exec } from '#scripts/gh/git-gh-exec'
-import { issue_label_schema } from '#scripts/git/git-schemas'
-import { parse_json } from '#scripts/git/parse-json-array'
-import { bounded_pool } from '#scripts/lib/bounded-pool'
-import { cli_flags } from '#scripts/lib/cli-flags'
+import { shared_cache, type CacheSlot } from '#scripts/josh/shared-cache'
 import { z } from 'zod'
-import { defect_rate, type DefectRate, type RateIssue } from './defect-rate'
-
-const SUCCESS_EXIT_CODE = 0
-const FAILURE_EXIT_CODE = 1
-const PER_PAGE = '100'
-const FIRST_PAGE = 1
-const SECOND_PAGE = 2
-// The search API serves at most this many results, so a window past it holds no further page.
-const SEARCH_RESULT_CEILING = 1000
-// The search API allows 30 requests a minute; both searches together stay at the ~10 requests the
-// sequential walk made, so this bounds only how many are in flight at once.
-const PAGE_CONCURRENCY = 4
-const USAGE = 'Usage: pnpm josh defect:rate [--days <n>]'
-const UNKNOWN_REPO_MESSAGE =
-	'Could not read this repository from `git remote`, so no issue can be searched — check `gh auth status` and that this is a checkout with an `origin` remote.'
-const UNREADABLE_SEARCH_MESSAGE =
-	'Could not read the issue search from GitHub, so no rate is printed.'
-
-const OPTIONS = { days: { type: 'string' } } as const
-
-// A positive whole number of days and nothing else — `0`, an empty string from an unset shell
-// variable and `1.5` are refused rather than read as a window nobody asked for.
-const DAYS_PATTERN = /^[1-9]\d*$/u
-// Ten years — far past any window worth asking for, and far inside the Date range, so an absurd value
-// is refused with the usage instead of crashing the window's date conversion.
-const MAX_WINDOW_DAYS = 3650
-
-const ARGV_OFFSET = 2
-
-const search_item_schema = z.object({
-	body: z.string().nullish(),
-	labels: z.array(issue_label_schema),
-})
-
-// One page of `search/issues`.
-const search_page_schema = z.object({
-	total_count: z.number(),
-	incomplete_results: z.boolean(),
-	items: z.array(search_item_schema),
-})
-
-type SearchPage = z.infer<typeof search_page_schema>
-
-interface SearchResult {
-	issues: ReadonlyArray<RateIssue>
-	is_capped: boolean
-}
-
-function read_days(argv: ReadonlyArray<string>): number | undefined {
-	const values = cli_flags.values_of(argv, OPTIONS)
-
-	if (values === undefined) return undefined
-
-	const raw = values.days ?? String(defect_rate.DEFAULT_WINDOW_DAYS)
-
-	if (!DAYS_PATTERN.test(raw)) return undefined
-
-	const days = Number(raw)
-
-	return days <= MAX_WINDOW_DAYS ? days : undefined
-}
-
-function search_path(query: string, page: number = FIRST_PAGE): string {
-	const parameters = new URLSearchParams({ q: query, per_page: PER_PAGE })
-
-	if (page !== FIRST_PAGE) parameters.set('page', String(page))
-
-	return `search/issues?${parameters.toString()}`
-}
-
-// How many pages the search holds, read off the first page's own count. Bounded by the API's
-// ceiling, past which GitHub serves no page at all — so this asks for exactly the pages `gh api
-// --paginate` would walk to.
-function page_count(first: SearchPage): number {
-	return Math.ceil(Math.min(first.total_count, SEARCH_RESULT_CEILING) / Number(PER_PAGE))
-}
-
-async function read_page(query: string, page: number): Promise<SearchPage | undefined> {
-	const raw = await git_gh_exec.exec_gh_api({ path: search_path(query, page) })
-
-	return parse_json.parse_json_object_or_undefined(raw, search_page_schema)
-}
-
-// Every page of one search. Not `gh api --paginate`: it follows each page's `next` link one page
-// after another, at about 1.5 s a page, on every `backlog:plan`. The first page names the total, so
-// the rest are fetched together; any page that does not read fails the whole search.
-async function read_pages(query: string): Promise<ReadonlyArray<SearchPage> | undefined> {
-	const first = await read_page(query, FIRST_PAGE)
-
-	if (first === undefined) return undefined
-
-	const rest_numbers = Array.from(
-		{ length: Math.max(page_count(first) - FIRST_PAGE, 0) },
-		(_value, index) => index + SECOND_PAGE,
-	)
-	const rest = await bounded_pool.bounded_map(
-		rest_numbers,
-		PAGE_CONCURRENCY,
-		async (page) => await read_page(query, page),
-	)
-
-	return rest.every((page) => page !== undefined) ? [first, ...rest] : undefined
-}
-
-function to_result(pages: ReadonlyArray<SearchPage>): SearchResult {
-	const issues = pages.flatMap((page) =>
-		page.items.map((item) => ({
-			body: item.body ?? '',
-			labels: item.labels.map((label) => label.name),
-		})),
-	)
-	// The search API serves at most 1000 results, and says so only by a total larger than what it
-	// handed back — a window past that ceiling is measured on part of itself.
-	const total = pages[0]?.total_count ?? 0
-	const is_incomplete = pages.some((page) => page.incomplete_results)
-
-	return { issues, is_capped: is_incomplete || total > issues.length }
+import { defect_rate, type DefectRate } from './defect-rate'
+import { issue_search } from './issue-search'
+
+const MS_PER_MINUTE = 60_000
+const CACHE_TTL_MINUTES = 15
+// A 14-day rate does not move within a quarter of an hour, and every `backlog:next` / `backlog:plan`
+// a backlogrun's drive, probe and board make asks it — each costing two or more search requests
+// against the 30-a-minute limit (joshuafolkken/kit#4550).
+const RATE_CACHE: CacheSlot = {
+	prefix: 'josh-defect-rate-',
+	ttl_ms: CACHE_TTL_MINUTES * MS_PER_MINUTE,
 }
 
-async function search(query: string): Promise<SearchResult | undefined> {
-	try {
-		const pages = await read_pages(query)
-
-		return pages === undefined ? undefined : to_result(pages)
-	} catch {
-		return undefined
-	}
-}
+const defect_rate_schema = z.object({
+	days: z.number(),
+	since: z.string(),
+	defects: z.number(),
+	enhancements: z.number(),
+	is_capped: z.boolean(),
+})
 
-// The rate over a window, or `undefined` when either search could not be read. `backlog:next` asks
-// this same measurement, so the two cannot disagree about the rate.
-async function measure_window(
+async function measure_uncached(
 	repo: string,
 	days: number,
-	now_ms: number,
+	since: string,
 ): Promise<DefectRate | undefined> {
-	const since = defect_rate.window_start(now_ms, days)
 	const [filed, completed] = await Promise.all([
-		search(defect_rate.filed_query(repo, since)),
-		search(defect_rate.completed_query(repo, since)),
+		issue_search.search(defect_rate.filed_query(repo, since)),
+		issue_search.search(defect_rate.completed_query(repo, since)),
 	])
 
 	if (filed === undefined || completed === undefined) return undefined
@@ -162,46 +44,23 @@ async function measure_window(
 	})
 }
 
-async function report(repo: string, days: number, now_ms: number): Promise<number> {
-	const measured = await measure_window(repo, days, now_ms)
-
-	if (measured === undefined) {
-		console.error(UNREADABLE_SEARCH_MESSAGE)
-
-		return FAILURE_EXIT_CODE
-	}
-
-	for (const line of defect_rate.format(measured)) console.info(line)
-
-	return SUCCESS_EXIT_CODE
-}
-
-async function run(argv: ReadonlyArray<string>, now_ms: number = Date.now()): Promise<number> {
-	const days = read_days(argv)
-
-	if (days === undefined) {
-		console.error(USAGE)
-
-		return FAILURE_EXIT_CODE
-	}
-
-	const repo = await git_gh_command.repo_get_name_with_owner()
-
-	if (repo === undefined) {
-		console.error(UNKNOWN_REPO_MESSAGE)
-
-		return FAILURE_EXIT_CODE
-	}
-
-	return await report(repo, days, now_ms)
-}
+// The rate over a window, or `undefined` when either search could not be read. `backlog:next` asks it.
+// Shared across processes for `CACHE_TTL_MINUTES`; an unread rate is not kept.
+async function measure_window(
+	repo: string,
+	days: number,
+	now_ms: number,
+): Promise<DefectRate | undefined> {
+	const since = defect_rate.window_start(now_ms, days)
+	const key = [repo, String(days), since].join(' ')
 
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
+	return await shared_cache.remember(
+		{ slot: RATE_CACHE, key, schema: defect_rate_schema },
+		async () => await measure_uncached(repo, days, since),
+		now_ms,
+	)
 }
 
-const defect_rate_cli = { USAGE, read_days, search_path, measure_window, run }
-
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+const defect_rate_cli = { RATE_CACHE, measure_window }
 
 export { defect_rate_cli }

package/scripts/issue/defect-rate.ts

@@ -119,28 +119,12 @@ function rate_text(result: DefectRate): string {
 	return `${rate.toFixed(RATE_DIGITS)} (${String(result.defects)} / ${String(result.enhancements)})`
 }
 
-function format(result: DefectRate): ReadonlyArray<string> {
-	const lines = [
-		`Defect rate over the last ${String(result.days)} days (since ${result.since}): ${rate_text(result)}`,
-		`  Defects filed: ${String(result.defects)} — labelled ${DEFECT_LABELS.join(' / ')} or declared \`${DEFECT_DECLARATION_LINE}\``,
-		`  Enhancements completed: ${String(result.enhancements)} — labelled ${ENHANCEMENT_LABEL}, closed as completed`,
-	]
-
-	if (!result.is_capped) return lines
-
-	return [
-		...lines,
-		'⚠ The search stopped before the end of the window; both counts are lower bounds.',
-	]
-}
-
 const defect_rate = {
 	BASELINE_RATE,
 	DEFAULT_WINDOW_DAYS,
 	DEFECT_DECLARATION_LINE,
 	completed_query,
 	filed_query,
-	format,
 	is_above_baseline,
 	is_defect,
 	kind_of,