@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,167 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { parseArgs } from 'node:util'
+import { git_gh_command } from '#scripts/git/git-gh-command'
+import { git_gh_exec } from '#scripts/git/git-gh-exec'
+import { parse_json_array_or_undefined } from '#scripts/git/parse-json-array'
+import { issue_label_schema } from '#scripts/git/schemas'
+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 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`. `--paginate --slurp` hands back every page as one array.
+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 {
+	try {
+		const { values } = parseArgs({ args: [...argv], options: OPTIONS, strict: true })
+		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
+	} catch {
+		return undefined
+	}
+}
+
+function search_path(query: string): string {
+	return `search/issues?${new URLSearchParams({ q: query, per_page: PER_PAGE }).toString()}`
+}
+
+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 }
+}
+
+async function search(query: string): Promise<SearchResult | undefined> {
+	try {
+		const raw = await git_gh_exec.exec_gh_api({
+			path: search_path(query),
+			should_paginate: true,
+			should_slurp: true,
+		})
+		const pages = parse_json_array_or_undefined(raw, search_page_schema)
+
+		return pages === undefined ? undefined : to_result(pages)
+	} catch {
+		return undefined
+	}
+}
+
+// The rate over a window, or `undefined` when either search could not be read. `backlog:next` asks
+// this same measurement (joshuafolkken/kit#2455), so the two cannot disagree about the rate.
+async function measure_window(
+	repo: string,
+	days: number,
+	now_ms: number,
+): 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)),
+	])
+
+	if (filed === undefined || completed === undefined) return undefined
+
+	const is_capped = filed.is_capped || completed.is_capped
+
+	return defect_rate.measure({
+		days,
+		since,
+		filed: filed.issues,
+		completed: completed.issues,
+		is_capped,
+	})
+}
+
+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)
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const defect_rate_cli = { USAGE, read_days, search_path, measure_window, run, main }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { defect_rate_cli }

package/scripts/issue/defect-rate.ts

@@ -0,0 +1,145 @@
+import { has_label_name, INTERRUPT_ROUTE_LABEL } from '#scripts/git/issue-labels'
+import { behavior_change_lint } from './behavior-change-lint'
+import { markdown_section } from './markdown-section'
+
+// The defect rate of merged work over a window (joshuafolkken/kit#2449): issues filed as defects
+// divided by behavior changes completed. Both sides are read from an issue-kind declaration line and
+// the `route:interrupt` label, so nothing here asks for a judgement.
+
+// A body declares itself a defect with this exact line, the sibling of the behavior-change declaration.
+// Filers already write it, but the issue template does not list it yet and no filing lint enforces it,
+// so a defect filed without it is counted only when it carries `route:interrupt`.
+const DEFECT_DECLARATION_LINE = '- 種別: 不具合'
+const DEFAULT_WINDOW_DAYS = 14
+// The rate measured when the command was introduced — 20 / 48 over 2026-09-09 to 2026-09-23, recorded
+// on joshuafolkken/kit#2449 as the rounded 0.42, which is the threshold that issue fixed. `backlog:next` defers new mechanisms while the current rate is above it
+// (joshuafolkken/kit#2455).
+const BASELINE_RATE = 0.42
+const MS_PER_DAY = 86_400_000
+const ISO_DATE_LENGTH = 10
+const RATE_DIGITS = 2
+
+interface RateIssue {
+	body: string
+	labels: ReadonlyArray<string>
+}
+
+interface DefectRate {
+	days: number
+	since: string
+	defects: number
+	behavior_changes: number
+	is_capped: boolean
+}
+
+// What an issue is to the priority `backlog:next` gives while the rate is above the baseline: a defect
+// (or hardening) goes first, a new mechanism is deferred, anything else keeps its place.
+type IssueKind = 'defect' | 'mechanism' | 'other'
+
+interface DefectRateInput {
+	days: number
+	since: string
+	filed: ReadonlyArray<RateIssue>
+	completed: ReadonlyArray<RateIssue>
+	is_capped: boolean
+}
+
+// The first day of the window as `YYYY-MM-DD`, the spelling GitHub's `created:>=` / `closed:>=` read.
+function window_start(now_ms: number, days: number): string {
+	return new Date(now_ms - days * MS_PER_DAY).toISOString().slice(0, ISO_DATE_LENGTH)
+}
+
+function filed_query(repo: string, since: string): string {
+	return `repo:${repo} is:issue created:>=${since}`
+}
+
+function completed_query(repo: string, since: string): string {
+	return `repo:${repo} is:issue is:closed reason:completed closed:>=${since}`
+}
+
+function is_defect(issue: RateIssue): boolean {
+	return (
+		markdown_section.has_line(issue.body, DEFECT_DECLARATION_LINE) ||
+		has_label_name(issue.labels, INTERRUPT_ROUTE_LABEL)
+	)
+}
+
+function is_behavior_change(issue: RateIssue): boolean {
+	return behavior_change_lint.is_target(issue.body)
+}
+
+// A defect declaration or `route:interrupt` wins over a behavior-change declaration, so an issue that
+// is both counts as the fix it is.
+function kind_of(issue: RateIssue): IssueKind {
+	if (is_defect(issue)) return 'defect'
+
+	return is_behavior_change(issue) ? 'mechanism' : 'other'
+}
+
+function measure(input: DefectRateInput): DefectRate {
+	return {
+		days: input.days,
+		since: input.since,
+		defects: input.filed.filter((issue) => is_defect(issue)).length,
+		behavior_changes: input.completed.filter((issue) => is_behavior_change(issue)).length,
+		is_capped: input.is_capped,
+	}
+}
+
+// Undefined when no behavior change completed in the window: a rate over zero is no answer, and
+// printing 0 or Infinity would read as one.
+function rate_of(result: DefectRate): number | undefined {
+	if (result.behavior_changes === 0) return undefined
+
+	return result.defects / result.behavior_changes
+}
+
+// Strictly above: a rate equal to the baseline has not risen, and a window with no rate is no answer.
+function is_above_baseline(result: DefectRate): boolean {
+	const rate = rate_of(result)
+
+	return rate !== undefined && rate > BASELINE_RATE
+}
+
+function rate_text(result: DefectRate): string {
+	const rate = rate_of(result)
+
+	if (rate === undefined) return 'n/a (no behavior change completed in the window)'
+
+	return `${rate.toFixed(RATE_DIGITS)} (${String(result.defects)} / ${String(result.behavior_changes)})`
+}
+
+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)} — declared \`${DEFECT_DECLARATION_LINE}\` or labelled ${INTERRUPT_ROUTE_LABEL}`,
+		`  Behavior changes completed: ${String(result.behavior_changes)} — declared \`${behavior_change_lint.DECLARATION_LINE}\`, 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_behavior_change,
+	is_defect,
+	kind_of,
+	measure,
+	rate_of,
+	rate_text,
+	window_start,
+}
+
+export type { DefectRate, DefectRateInput, IssueKind, RateIssue }
+export { defect_rate }

package/scripts/issue/issue-backlinks-cli.ts

@@ -0,0 +1,97 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { git_gh_command } from '#scripts/git/git-gh-command'
+import { parse_json_object_safe } from '#scripts/git/parse-json-array'
+import { z } from 'zod'
+import { issue_backlinks, type UpstreamEntry } from './issue-backlinks'
+
+// `josh issue:backlinks <N>` — read origin issue N, then the upstream issues it lists, and print one
+// of `ok` / `missing-origin` / `missing-upstream` / `wrong-heading`, exiting non-zero on anything but
+// `ok` so it works as a gate (joshuafolkken/kit#2123).
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
+const REF_PATTERN = /^([\w.-]+\/[\w.-]+)#(\d+)$/u
+const BODY_FIELD = 'body'
+const USAGE = 'Usage: josh issue:backlinks <issue-number>'
+const READ_FAILURE = '✖ could not read an issue body — a rate limit, expired auth, or a bad number'
+const body_schema = z.object({ body: z.string().nullish() })
+
+function parse_body(raw_json: string | undefined): string | undefined {
+	if (raw_json === undefined) return undefined
+	const parsed = parse_json_object_safe(raw_json, body_schema)
+
+	return parsed === undefined ? undefined : (parsed.body ?? '')
+}
+
+async function read_body(issue_number: string, repo?: string): Promise<string | undefined> {
+	return parse_body(await git_gh_command.issue_view_json(issue_number, BODY_FIELD, repo))
+}
+
+async function read_upstream(reference: string): Promise<UpstreamEntry | undefined> {
+	const match = REF_PATTERN.exec(reference)
+	if (match === null) return undefined
+
+	const [, repo, number] = match
+	const body = await read_body(number ?? '', repo)
+
+	return body === undefined ? undefined : { ref: reference, body }
+}
+
+async function read_upstreams(
+	references: ReadonlyArray<string>,
+): Promise<ReadonlyArray<UpstreamEntry> | undefined> {
+	const entries = await Promise.all(
+		references.map(async (reference) => await read_upstream(reference)),
+	)
+
+	return entries.every((entry) => entry !== undefined) ? entries : undefined
+}
+
+async function classify(issue_number: string): Promise<string | undefined> {
+	const origin_body = await read_body(issue_number)
+	if (origin_body === undefined) return undefined
+
+	if (!issue_backlinks.needs_upstreams(origin_body)) {
+		return issue_backlinks.classify_backlinks(origin_body, [])
+	}
+
+	const upstreams = await read_upstreams(issue_backlinks.upstream_refs(origin_body))
+	if (upstreams === undefined) return undefined
+
+	return issue_backlinks.classify_backlinks(origin_body, upstreams)
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const [issue_number] = argv
+
+	if (issue_number === undefined || !ISSUE_NUMBER_PATTERN.test(issue_number)) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const verdict = await classify(issue_number)
+
+	if (verdict === undefined) {
+		console.error(READ_FAILURE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	console.info(verdict)
+
+	return verdict === 'ok' ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const issue_backlinks_cli = { run, USAGE }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { issue_backlinks_cli }

package/scripts/issue/issue-backlinks.ts

@@ -0,0 +1,164 @@
+// The upstream backlink headings (`prompts/collaboration-workflow/issue-template.md`) are fixed so
+// they can be found by grep — the document says so outright — yet nothing greps them, and a
+// one-directional link (an origin that lists an upstream the upstream never points back at) survives
+// undetected. This classifies an origin issue's filed backlinks into one of four fixed words
+// (joshuafolkken/kit#2123). The headings are the single source's, pinned by the document test.
+
+const ORIGIN_HEADING = '## Origin'
+const UPSTREAM_ISSUES_HEADING = '## Upstream issues'
+const UPSTREAM_CANDIDATE_HEADING = '## Upstream candidate'
+const CHECKBOX_PATTERN = /^\s*-\s*\[[ xX]\]/u
+const WRONG_UPSTREAM_HEADING_PATTERN = /^##\s+Upstream\b/iu
+const SUBHEADING_PATTERN = /^##\s/u
+const BARE_REFERENCE_PATTERN = /^#\d+$/u
+const DIGITS_PATTERN = /^\d+$/u
+const REFERENCE_MARK = '#'
+const PATH_SEPARATOR = '/'
+const PATH_SEGMENT_COUNT = 2
+
+type BacklinkVerdict = 'ok' | 'missing-origin' | 'missing-upstream' | 'wrong-heading'
+
+const OK: BacklinkVerdict = 'ok'
+const WRONG_HEADING: BacklinkVerdict = 'wrong-heading'
+const MISSING_UPSTREAM: BacklinkVerdict = 'missing-upstream'
+
+interface UpstreamEntry {
+	ref: string
+	body: string
+}
+
+function trimmed_lines(body: string): ReadonlyArray<string> {
+	return body.split('\n').map((line) => line.trimEnd())
+}
+
+function has_heading(body: string, heading: string): boolean {
+	return trimmed_lines(body).some((line) => line.trim() === heading)
+}
+
+// The lines under `heading`, up to the next `##` heading; `undefined` when the heading is absent.
+function section_lines(body: string, heading: string): ReadonlyArray<string> | undefined {
+	const lines = trimmed_lines(body)
+	const start = lines.findIndex((line) => line.trim() === heading)
+	if (start === -1) return undefined
+
+	const rest = lines.slice(start + 1)
+	const end = rest.findIndex((line) => SUBHEADING_PATTERN.test(line.trim()))
+
+	return end === -1 ? rest : rest.slice(0, end)
+}
+
+// A heading that looks like the upstream one but is not exactly it (`## Upstream`, `## Upstreams`,
+// wrong case) — the grep the template promises would miss it, so it is a wrong-heading rather than a
+// missing one. `## Upstream candidate` is a legitimate separate heading and is excluded.
+function has_wrong_upstream_heading(body: string): boolean {
+	return trimmed_lines(body).some((line) => {
+		const heading = line.trim()
+		if (heading === UPSTREAM_ISSUES_HEADING || heading === UPSTREAM_CANDIDATE_HEADING) return false
+
+		return WRONG_UPSTREAM_HEADING_PATTERN.test(heading)
+	})
+}
+
+function tokens_of(section: ReadonlyArray<string>): ReadonlyArray<string> {
+	return section
+		.join(' ')
+		.split(/\s+/u)
+		.filter((token) => token.length > 0)
+}
+
+function has_two_segments(path: string | undefined): boolean {
+	const segments = (path ?? '').split(PATH_SEPARATOR)
+
+	return segments.length === PATH_SEGMENT_COUNT && segments.every((segment) => segment.length > 0)
+}
+
+// `owner/repo#N` split by structure rather than a nested-quantifier regex: one `#`, and one `/`
+// between two non-empty segments before it. That is the only reference form the template allows.
+function is_qualified_reference(token: string): boolean {
+	const [path, number, ...rest] = token.split(REFERENCE_MARK)
+	if (number === undefined || rest.length > 0) return false
+
+	return DIGITS_PATTERN.test(number) && has_two_segments(path)
+}
+
+function has_bare_reference(section: ReadonlyArray<string>): boolean {
+	return tokens_of(section).some((token) => BARE_REFERENCE_PATTERN.test(token))
+}
+
+function has_checkbox_reference(section: ReadonlyArray<string>): boolean {
+	return section.some((line) => CHECKBOX_PATTERN.test(line) && line.includes(REFERENCE_MARK))
+}
+
+function is_malformed_upstream_section(section: ReadonlyArray<string>): boolean {
+	return has_bare_reference(section) || has_checkbox_reference(section)
+}
+
+// Every upstream body has to point back with `## Origin`; the first that does not makes the pair
+// one-directional.
+function every_upstream_cites_origin(upstreams: ReadonlyArray<UpstreamEntry>): boolean {
+	return upstreams.every((upstream) => has_heading(upstream.body, ORIGIN_HEADING))
+}
+
+// A body with only `## Upstream candidate` (nothing filed yet) is a correct state and reads as `ok`;
+// otherwise a body with no upstream heading at all is missing its upstream link.
+function verdict_without_section(origin_body: string): BacklinkVerdict {
+	return has_heading(origin_body, UPSTREAM_CANDIDATE_HEADING) ? OK : MISSING_UPSTREAM
+}
+
+function verdict_with_section(
+	section: ReadonlyArray<string>,
+	upstreams: ReadonlyArray<UpstreamEntry>,
+): BacklinkVerdict {
+	if (is_malformed_upstream_section(section)) return WRONG_HEADING
+	if (upstreams.length === 0) return MISSING_UPSTREAM
+
+	return every_upstream_cites_origin(upstreams) ? OK : 'missing-origin'
+}
+
+// The origin issue's body, plus the bodies of the upstreams it lists, classified into one word.
+function classify_backlinks(
+	origin_body: string,
+	upstreams: ReadonlyArray<UpstreamEntry>,
+): BacklinkVerdict {
+	if (has_wrong_upstream_heading(origin_body)) return WRONG_HEADING
+
+	const section = section_lines(origin_body, UPSTREAM_ISSUES_HEADING)
+
+	return section === undefined
+		? verdict_without_section(origin_body)
+		: verdict_with_section(section, upstreams)
+}
+
+// The `owner/repo#N` references the upstream section lists, so the CLI knows which upstream bodies to
+// fetch and check for `## Origin`.
+function upstream_references(origin_body: string): ReadonlyArray<string> {
+	const section = section_lines(origin_body, UPSTREAM_ISSUES_HEADING)
+	if (section === undefined) return []
+
+	return tokens_of(section).filter((token) => is_qualified_reference(token))
+}
+
+// Whether classifying the origin needs the upstream bodies fetched. Only the `## Origin` back-check
+// does; a wrong, malformed or missing upstream heading is decided from the origin body alone. So the
+// CLI can skip the network for those, and never mask a `wrong-heading` verdict behind an upstream
+// that happens to be unreadable (joshuafolkken/kit#2123).
+function needs_upstreams(origin_body: string): boolean {
+	if (has_wrong_upstream_heading(origin_body)) return false
+
+	const section = section_lines(origin_body, UPSTREAM_ISSUES_HEADING)
+	if (section === undefined) return false
+
+	return !is_malformed_upstream_section(section)
+}
+
+const issue_backlinks = {
+	classify_backlinks,
+	upstream_refs: upstream_references,
+	needs_upstreams,
+	ORIGIN_HEADING,
+	UPSTREAM_ISSUES_HEADING,
+	UPSTREAM_CANDIDATE_HEADING,
+}
+
+export type { UpstreamEntry }
+export { issue_backlinks }