@joshuafolkken/kit 1.1514.0 → 1.1784.0

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

@@ -0,0 +1,60 @@
+import { issue_bug_label } from './issue-bug-label'
+import { markdown_section } from './markdown-section'
+
+// 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'
+
+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
+}
+
+const defect_origin_line = { MALFORMED_ORIGIN, MISSING_ORIGIN, parse, 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,16 +1,11 @@
-#!/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 { shared_cache, type CacheSlot } from '#scripts/josh/shared-cache'
 import { bounded_pool } from '#scripts/lib/bounded-pool'
-import { cli_flags } from '#scripts/lib/cli-flags'
 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
@@ -19,22 +14,23 @@ 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 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,
+}
 
-const ARGV_OFFSET = 2
+const defect_rate_schema = z.object({
+	days: z.number(),
+	since: z.string(),
+	defects: z.number(),
+	enhancements: z.number(),
+	is_capped: z.boolean(),
+})
 
 const search_item_schema = z.object({
 	body: z.string().nullish(),
@@ -55,20 +51,6 @@ interface SearchResult {
 	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 })
 
@@ -136,14 +118,11 @@ async function search(query: string): Promise<SearchResult | undefined> {
 	}
 }
 
-// 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)),
@@ -162,46 +141,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, search_path, 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,

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

@@ -0,0 +1,128 @@
+import { FULL_PAGE_QUERY, git_gh_api_path } from '#scripts/gh/git-gh-api-path'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { parse_json } from '#scripts/git/parse-json-array'
+import { bounded_pool } from '#scripts/lib/bounded-pool'
+import { z } from 'zod'
+import { defect_report, type OriginPr, type ReportIssue } from './defect-report'
+import { defect_report_format } from './defect-report-format'
+import { session_cite } from './session-cite'
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const PR_CONCURRENCY = 4
+const USAGE = 'Usage: pnpm josh defect:report'
+const UNREADABLE_MESSAGE =
+	'Could not read the bug issues from GitHub, so no report is printed — check `gh auth status`.'
+
+const issue_schema = z.object({
+	number: z.number(),
+	created_at: z.string(),
+	body: z.string().nullish(),
+	pull_request: z.unknown().optional(),
+})
+const pull_schema = z.object({ merged_at: z.string().nullish() })
+const file_schema = z.object({
+	filename: z.string(),
+	status: z.string(),
+	additions: z.number(),
+	deletions: z.number(),
+})
+
+// Every issue labelled `bug`, open or closed — the label `issue:file` derives from the declaration.
+// The issues listing carries pull requests too, so those are dropped.
+async function read_issues(repo: string): Promise<ReadonlyArray<ReportIssue> | undefined> {
+	const raw = await git_gh_exec.exec_gh_api({
+		path: `repos/${repo}/issues?labels=bug&state=all&per_page=100`,
+		should_paginate: true,
+	})
+	const issues = parse_json.parse_json_object_or_undefined(raw, z.array(issue_schema))
+
+	return issues
+		?.filter((issue) => issue.pull_request === undefined)
+		.map((issue) => ({
+			number: issue.number,
+			created_at: issue.created_at,
+			body: issue.body ?? '',
+		}))
+}
+
+async function read_pr(repo: string, pr: number): Promise<OriginPr | undefined> {
+	const path = git_gh_api_path.pull_api_path(String(pr), repo)
+	const [pull_raw, files_raw] = await Promise.all([
+		git_gh_exec.exec_gh_api({ path }),
+		git_gh_exec.exec_gh_api({ path: `${path}/files${FULL_PAGE_QUERY}`, should_paginate: true }),
+	])
+	const pull = parse_json.parse_json_object_or_undefined(pull_raw, pull_schema)
+	const files = parse_json.parse_json_object_or_undefined(files_raw, z.array(file_schema))
+
+	if (pull === undefined || files === undefined) return undefined
+
+	return {
+		pr,
+		merged_at: pull.merged_at ?? '',
+		kind: defect_report.change_kind(files),
+		areas: defect_report.areas(files),
+	}
+}
+
+// A pull request that cannot be read contributes nothing, and the report counts it as unread.
+async function read_pr_or_none(repo: string, pr: number): Promise<ReadonlyArray<OriginPr>> {
+	try {
+		const origin = await read_pr(repo, pr)
+
+		return origin === undefined ? [] : [origin]
+	} catch {
+		return []
+	}
+}
+
+async function read_prs(repo: string, prs: ReadonlyArray<number>): Promise<Map<number, OriginPr>> {
+	const read = await bounded_pool.bounded_map(
+		prs,
+		PR_CONCURRENCY,
+		async (pr) => await read_pr_or_none(repo, pr),
+	)
+
+	return new Map(read.flat().map((origin) => [origin.pr, origin]))
+}
+
+function unreadable(): number {
+	console.error(UNREADABLE_MESSAGE)
+
+	return FAILURE_EXIT_CODE
+}
+
+async function report(repo: string): Promise<number> {
+	const issues = await read_issues(repo)
+
+	if (issues === undefined) return unreadable()
+
+	const prs = await read_prs(repo, defect_report.origin_prs(issues))
+
+	const aggregated = defect_report.aggregate(issues, prs)
+
+	console.info(session_cite.text(defect_report_format.format(aggregated)))
+
+	return SUCCESS_EXIT_CODE
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	if (argv.length > 0) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	try {
+		const repo = await git_gh_command.repo_get_name_with_owner()
+
+		return repo === undefined ? unreadable() : await report(repo)
+	} catch {
+		return unreadable()
+	}
+}
+
+const defect_report_cli = { run }
+
+export { defect_report_cli }

package/scripts/issue/defect-report-format.ts

@@ -0,0 +1,56 @@
+import { defect_report, type DefectReport } from './defect-report'
+import { issue_cite } from './issue-cite'
+
+// The printed `defect:report`: each grouping as a table of counts, largest first.
+
+const INDENT = '  '
+const NONE = `${INDENT}(none)`
+
+function sorted_rows<K>(counts: ReadonlyMap<K, number>, label: (key: K) => string): Array<string> {
+	return [...counts]
+		.toSorted((left, right) => right[1] - left[1])
+		.map(([key, count]) => `${INDENT}${label(key)}  ${String(count)}`)
+}
+
+function section<K>(
+	title: string,
+	counts: ReadonlyMap<K, number>,
+	label: (key: K) => string,
+): Array<string> {
+	const rows = sorted_rows(counts, label)
+
+	return [title, ...(rows.length === 0 ? [NONE] : rows)]
+}
+
+function pr_label(pr: number): string {
+	return issue_cite.plain(pr)
+}
+
+function summary(report: DefectReport): string {
+	let traced = 0
+
+	for (const count of report.by_pr.values()) traced += count
+	const parts = [
+		`traced to a pull request: ${String(traced)}`,
+		`不明: ${String(report.unknown)}`,
+		`no origin line: ${String(report.undeclared)}`,
+	]
+
+	return `defects by origin — ${parts.join(' · ')}`
+}
+
+function format(report: DefectReport): string {
+	const week = `pull requests that added a mechanism — defects filed within ${String(defect_report.WEEK_DAYS)} days of the merge:`
+
+	return [
+		summary(report),
+		...section('by pull request:', report.by_pr, pr_label),
+		...section('by change kind (add / fix / remove):', report.by_kind, String),
+		...section('by area:', report.by_area, String),
+		...section(week, report.added_within_week, pr_label),
+	].join('\n')
+}
+
+const defect_report_format = { format }
+
+export { defect_report_format }

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

@@ -0,0 +1,11 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { defect_report_cli } from './defect-report-cli'
+
+// The `josh defect:report` entry, kept apart from `defect-report-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_report_cli.run(process.argv.slice(ARGV_OFFSET))
+}