@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/issue/effect-audit.ts

@@ -0,0 +1,185 @@
+import { expected_effect_lint } from './expected-effect-lint'
+import { issue_cite } from './issue-cite'
+import { has_label_name, MEASURED_LABEL, MEASURED_UNMET_LABEL } from './issue-labels'
+import { issue_sample_gate } from './issue-sample-gate'
+import type { SearchIssue } from './issue-search'
+
+// joshuafolkken/kit#4958: a run-time-shortening issue states its expected effect at filing
+// (`expected-effect-lint.ts`), and nothing read it again once merged. This sets each closed one beside
+// the follow-up measurements of it — issues whose run condition names the pull request that closed it
+// — and their recorded verdict: `measured:unmet` fell short, `measured` alone reached it, anything else
+// is not measured yet. A shortfall is drafted as a retirement candidate for `issue:file`.
+
+const EFFECT_LABELS: ReadonlyArray<string> = ['効く率', '1 回あたりの得', '外れたときの損']
+const NO_VALUE = '—'
+const RESULTS = ['met', 'unmet', 'unmeasured'] as const
+
+type EffectResult = (typeof RESULTS)[number]
+
+interface AuditRow {
+	origin: SearchIssue
+	follow_ups: ReadonlyArray<SearchIssue>
+	result: EffectResult
+}
+
+// A follow-up and the issue it measures: the one its run condition's pull request closes. A body
+// naming other issues (a parent, lanes it compares against) measures none of them.
+interface FollowUp {
+	issue: SearchIssue
+	measures: number | undefined
+}
+
+const RESULT_WORDS: Readonly<Record<EffectResult, string>> = {
+	met: '届いた',
+	unmet: '届かなかった',
+	unmeasured: '未計測',
+}
+
+// Plain: the rows feed an issue body as well as the session, which links them where it prints them.
+function cite(issue: SearchIssue): string {
+	return issue_cite.plain(issue.number)
+}
+
+// The closed time-shortening issues of the window. The search narrows by the declaration's words; the
+// exact line under the background heading is checked on each body, since the search matches the
+// follow-ups' own "confirm the shortening" aim too.
+function origin_query(repo: string, since: string): string {
+	return `repo:${repo} is:issue is:closed reason:completed closed:>=${since} "目的: 時間短縮" in:body`
+}
+
+// Every follow-up measurement, of any date: one may be filed before or long after its origin closed.
+function follow_up_query(repo: string): string {
+	return `repo:${repo} is:issue "実施可能条件" in:body`
+}
+
+// The pull request a follow-up's run condition names, or `undefined` for an issue that declares none
+// or cites the issue whose closing pull request it waits on.
+function cited_pull(issue: SearchIssue): number | undefined {
+	return issue_sample_gate.cited_via(issue.body, 'pull')
+}
+
+// The issue a follow-up's run condition names by the issue form — the issue it measures, unread.
+function cited_issue(issue: SearchIssue): number | undefined {
+	return issue_sample_gate.cited_via(issue.body, 'issue')
+}
+
+// One shortfall outweighs any reach: a mechanism some measurement found wanting is the one to look at.
+function result_of(follow_ups: ReadonlyArray<SearchIssue>): EffectResult {
+	if (follow_ups.some((issue) => has_label_name(issue.labels, MEASURED_UNMET_LABEL))) return 'unmet'
+
+	return follow_ups.some((issue) => has_label_name(issue.labels, MEASURED_LABEL))
+		? 'met'
+		: 'unmeasured'
+}
+
+function row_of(origin: SearchIssue, follow_ups: ReadonlyArray<FollowUp>): AuditRow {
+	const measuring = follow_ups
+		.filter((follow_up) => follow_up.measures === origin.number)
+		.map((follow_up) => follow_up.issue)
+
+	return { origin, follow_ups: measuring, result: result_of(measuring) }
+}
+
+function rows(
+	origins: ReadonlyArray<SearchIssue>,
+	follow_ups: ReadonlyArray<FollowUp>,
+): ReadonlyArray<AuditRow> {
+	return origins
+		.filter((origin) => expected_effect_lint.is_target(origin.body))
+		.map((origin) => row_of(origin, follow_ups))
+}
+
+function effect_text(body: string): string {
+	return EFFECT_LABELS.map(
+		(label) => `${label} ${expected_effect_lint.value_of(body, label) ?? NO_VALUE}`,
+	).join(' · ')
+}
+
+function follow_up_text(follow_ups: ReadonlyArray<SearchIssue>): string {
+	if (follow_ups.length === 0) return 'なし'
+
+	return follow_ups.map((issue) => `${cite(issue)} (${issue.state})`).join(', ')
+}
+
+function format_row(row: AuditRow): string {
+	const effect = `期待効果: ${effect_text(row.origin.body)}`
+	const measured = `後続計測: ${follow_up_text(row.follow_ups)}`
+
+	return `${cite(row.origin)} — ${effect} — ${measured} — 結果: ${RESULT_WORDS[row.result]}`
+}
+
+function tally(audit_rows: ReadonlyArray<AuditRow>, result: EffectResult): string {
+	return `${RESULT_WORDS[result]} ${String(audit_rows.filter((row) => row.result === result).length)}`
+}
+
+function summary(audit_rows: ReadonlyArray<AuditRow>, since: string): string {
+	const tallies = RESULTS.map((result) => tally(audit_rows, result)).join(' · ')
+
+	return `effect:audit — closed since ${since}: ${String(audit_rows.length)} issues · ${tallies}`
+}
+
+function unmet_measurements(row: AuditRow): string {
+	return row.follow_ups
+		.filter((issue) => has_label_name(issue.labels, MEASURED_UNMET_LABEL))
+		.map((issue) => cite(issue))
+		.join(', ')
+}
+
+function draft_title(row: AuditRow): string {
+	return `Retire or shrink the mechanism of ${cite(row.origin)}, which fell short of its expected effect`
+}
+
+function background_lines(origin: string, measurements: string): ReadonlyArray<string> {
+	return [
+		'## 背景',
+		'',
+		'- 種別: 非不具合',
+		'- 目的: 機能改善',
+		'- 人の判断: 不要',
+		'- 優先度: 通常',
+		'- 規模見積もり: 約 <N> ファイル / <M> 行（テスト除く）',
+		`- 出どころ: ${measurements} の計測（\`measured:unmet\`）`,
+		'',
+		`${origin} で足した機構は、後続計測 ${measurements} で期待効果に届かなかった。効かない機構は利用者の実行時間・読む量・保守の負担を増やすので、撤去するか、効く範囲に縮小する。`,
+	]
+}
+
+// The retirement candidate's body. The scale line is what only the filer knows: `issue:lint` refuses
+// it until it is filled, and `issue:file`'s scout stops a duplicate.
+function draft_body(row: AuditRow): string {
+	const origin = cite(row.origin)
+	const measurements = unmet_measurements(row)
+
+	return [
+		...background_lines(origin, measurements),
+		'',
+		'## 現象',
+		'',
+		`- ${origin} の期待効果: ${effect_text(row.origin.body)}`,
+		`- 計測 ${measurements} の結果: 届かなかった`,
+		'',
+		'## 期待結果',
+		'',
+		`- ${origin} で足した機構が撤去されているか、効く範囲に縮小されている`,
+		'',
+		'## 受け入れ条件',
+		'',
+		`- [ ] ${origin} で足した機構を撤去するか縮小し、どちらを選んだかとその理由を記録する`,
+		'',
+	].join('\n')
+}
+
+const effect_audit = {
+	cited_issue,
+	cited_pull,
+	draft_body,
+	draft_title,
+	follow_up_query,
+	format_row,
+	origin_query,
+	rows,
+	summary,
+}
+
+export type { AuditRow, EffectResult, FollowUp }
+export { effect_audit }

package/scripts/issue/expected-effect-lint.ts

@@ -9,7 +9,18 @@ import { markdown_section } from './markdown-section'
 const DECLARATION_LINE = '- 目的: 時間短縮'
 const BACKGROUND_HEADING = '## 背景'
 const HEADING = '## 期待効果'
-const ITEM_LABELS: ReadonlyArray<string> = ['効く率', '1 回あたりの得', '外れたときの損', '出典']
+const RATE_LABEL = '効く率'
+const GAIN_LABEL = '1 回あたりの得'
+const ITEM_LABELS: ReadonlyArray<string> = [RATE_LABEL, GAIN_LABEL, '外れたときの損', '出典']
+// The numbers the backlog ranking reads off the rate and the gain (joshuafolkken/kit#5302).
+const WEEK = '週'
+const COUNT = /(?<![\d.])(?<count>\d+) ?回/gu
+const SPAN = /(?<![\d.])(?<weeks>\d+) ?週/u
+const ONE_WEEK = 1
+const DURATION = /(?<![\d.])(?<amount>\d+(?:\.\d+)?) ?(?<unit>[分秒])/u
+const SECONDS_UNIT = '秒'
+const SECONDS_PER_MINUTE = 60
+const NONE = 0
 // A template placeholder value — the `<...>` guidance a filed Issue replaces. It is not an estimate, but a
 // value that only opens with `<` (an upper bound such as `<1 min`) is one, so the placeholder must close with `>` too.
 const PLACEHOLDER = /^<.*>$/u
@@ -29,22 +40,64 @@ function item_value(line: string, label: string): string | undefined {
 	return line.slice(prefix.length).trim()
 }
 
-function has_item(lines: ReadonlyArray<string>, label: string): boolean {
-	return lines.some((line) => {
-		const value = item_value(line.trim(), label)
+function is_stated(value: string | undefined): value is string {
+	return value !== undefined && value.length > 0 && !PLACEHOLDER.test(value)
+}
+
+function stated_value(lines: ReadonlyArray<string>, label: string): string | undefined {
+	return lines.map((line) => item_value(line.trim(), label)).find((value) => is_stated(value))
+}
+
+function effect_lines(body: string): ReadonlyArray<string> {
+	const section = markdown_section.section_lines(body, HEADING).join('\n')
+
+	return markdown_section.unfenced_lines(section)
+}
+
+// The value the body's expected-effect section states for one item, or undefined when it states none.
+function value_of(body: string, label: string): string | undefined {
+	return stated_value(effect_lines(body), label)
+}
+
+// The weeks a rate is counted over: its stated span ("10 in 2 weeks", "1 every 2 weeks"), else one.
+function weeks_of(rate: string): number {
+	const weeks = SPAN.exec(rate)?.groups?.['weeks']
 
-		return value !== undefined && value.length > 0 && !PLACEHOLDER.test(value)
-	})
+	return Math.max(Number(weeks ?? ONE_WEEK), ONE_WEEK)
+}
+
+// The hits a week a rate states: its last count, so "5 of 23 a week" reads the 5 the speed-up applies to,
+// over its span of weeks. `0` when the rate names no week or no count.
+function weekly_hits(rate: string | undefined): number {
+	if (!rate?.includes(WEEK)) return NONE
+	const counts = [...rate.matchAll(COUNT)].map((match) => Number(match.groups?.['count']))
+
+	return (counts.at(-1) ?? NONE) / weeks_of(rate)
+}
+
+// The minutes one hit saves: the first number the gain states in seconds or minutes — a range written
+// with one closing unit ("3-6 min") reads its upper bound. `0` when it states none.
+function minutes_per_hit(gain = ''): number {
+	const groups = DURATION.exec(gain)?.groups
+	if (groups === undefined) return NONE
+	const amount = Number(groups['amount'])
+
+	return groups['unit'] === SECONDS_UNIT ? amount / SECONDS_PER_MINUTE : amount
+}
+
+// The minutes a week the declared speed-up saves — hits a week times the gain per hit — on the same
+// minute scale as `issue_priority.lost_minutes`. `0` when the rate or the gain is not a number.
+function weekly_minutes(body = ''): number {
+	return weekly_hits(value_of(body, RATE_LABEL)) * minutes_per_hit(value_of(body, GAIN_LABEL))
 }
 
 // Every expected-effect problem a body has, or an empty array. A body without the declaration has none.
 function problems(body: string): ReadonlyArray<string> {
 	if (!is_target(body)) return []
 	if (!markdown_section.has_line(body, HEADING)) return [`missing heading: ${HEADING}`]
-	const section = markdown_section.section_lines(body, HEADING).join('\n')
-	const lines = markdown_section.unfenced_lines(section)
+	const lines = effect_lines(body)
 
-	return ITEM_LABELS.filter((label) => !has_item(lines, label)).map(
+	return ITEM_LABELS.filter((label) => stated_value(lines, label) === undefined).map(
 		(label) => `missing expected-effect item: - ${label}: <value>`,
 	)
 }
@@ -53,7 +106,10 @@ const expected_effect_lint = {
 	DECLARATION_LINE,
 	HEADING,
 	ITEM_LABELS,
+	is_target,
 	problems,
+	value_of,
+	weekly_minutes,
 }
 
 export { expected_effect_lint }

package/scripts/issue/git-next-issues.ts

@@ -1,7 +1,9 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { open_issue_schema, type OpenIssueData } from '#scripts/git/git-schemas'
 import { parse_json_array_safe } from '#scripts/git/parse-json-array'
+import { expected_effect_lint } from './expected-effect-lint'
 import { has_any_label, NOT_DIRECTLY_RUNNABLE_LABELS } from './issue-labels'
+import { issue_priority } from './issue-priority'
 import { issue_rank, type DependencyRow } from './issue-rank'
 import { session_cite } from './session-cite'
 
@@ -63,7 +65,10 @@ function order(
 	const dependents = issue_rank.count_dependents(candidates.map((issue) => dependency_row(issue)))
 
 	return issue_rank.rank(candidates, (issue) => ({
+		is_last: issue_priority.is_last(issue.body),
 		labels: (issue.labels ?? []).map((label) => label.name),
+		lost_minutes: issue_priority.lost_minutes(issue.body),
+		gain_minutes: expected_effect_lint.weekly_minutes(issue.body),
 		dependents: dependents.get(String(issue.number)) ?? 0,
 	}))
 }

package/scripts/issue/issue-already-done-cli.ts

@@ -0,0 +1,62 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_evidence_exit } from '#scripts/issue/issue-evidence-exit'
+import { ALREADY_DONE_LABEL } from '#scripts/issue/issue-labels'
+import { issue_sample_gate } from '#scripts/issue/issue-sample-gate'
+import { session_cite } from '#scripts/issue/session-cite'
+
+// `josh issue:already-done <N> --evidence-file <path>` — the exit for an Issue whose work is already
+// merged (`issue-comments.md` → "When the work turns out to be already merged"): the evidence
+// comment, the `already-done` label and the `run:release`, in that order (`issue-evidence-exit.ts`).
+//
+// The label is provisioned by `josh start`, so nothing here creates it.
+// **The Issue is never closed**: closing is a person's (Tier C), and the label is the run's exit.
+//
+// **A follow-up measurement is refused before anything is written** (joshuafolkken/kit#4504): its body
+// declares the sample wait (`issue_sample_gate.DECLARATION`, read as `not-before` reads it), and its
+// exit is `josh issue:measured`, which closes it — this one would leave it OPEN and the lane parked.
+
+const ARGV_OFFSET = 2
+
+function refusal_of(issue_number: string, body: string | undefined): string | undefined {
+	const cite = session_cite.issue(issue_number)
+	if (body === undefined) return `Issue ${cite} body not read; nothing written`
+	if (issue_sample_gate.cited_number(body) === undefined) return undefined
+
+	return `Issue ${cite} is a follow-up measurement (\`${issue_sample_gate.DECLARATION}\`): run \`josh issue:measured ${issue_number} --evidence-file <path>\` instead; nothing written`
+}
+
+async function admit(issue_number: string): Promise<boolean> {
+	const refusal = refusal_of(issue_number, await git_gh_command.issue_get_body(issue_number))
+
+	if (refusal !== undefined) console.error(refusal)
+
+	return refusal === undefined
+}
+
+async function apply_label(issue_number: string): Promise<boolean> {
+	const write = await git_gh_command.issue_apply_label(issue_number, ALREADY_DONE_LABEL)
+
+	if (!write.is_applied) console.error(`${ALREADY_DONE_LABEL} not applied: ${write.reason}`)
+
+	return write.is_applied
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	return await issue_evidence_exit.run(argv, {
+		command: 'issue:already-done',
+		finish: apply_label,
+		admit,
+	})
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const issue_already_done_cli = { run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { issue_already_done_cli }

package/scripts/issue/issue-body-or-comment.ts

@@ -0,0 +1,74 @@
+import { gh_author_association, type AuthorFields } from '#scripts/gh/gh-author-association'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { parse_json_object_or_undefined } from '#scripts/git/parse-json-array'
+import { z } from 'zod'
+
+// One text written to an issue: **into the body when the body is blank, as a comment otherwise.**
+// Two writers make this decision — `followup`'s completion notice and `issue:plan`'s plan — and a copy
+// per caller is how the two would come to disagree about what "blank" means.
+//
+// A body that could not be read is not blank: overwriting a body nobody saw could erase a person's
+// text, so an unreadable body falls to a comment, which loses nothing.
+//
+// **A blank body filed by an author without write access is not written into either**
+// (joshuafolkken/kit#4663). Readers judge a body by the issue's author, not by who last edited it, so
+// a trusted `kickoff` plan written there would read as untrusted text, and `run:entry` — which waits
+// for a trusted comment on such an issue — would never see the plan it waits for.
+
+type Destination = 'body' | 'comment'
+
+interface PostOutcome {
+	destination: Destination
+	url: string
+}
+
+const BODY_FIELDS = `body,${gh_author_association.AUTHOR_FIELDS}`
+
+const body_schema = z.looseObject({
+	body: z.string().nullish(),
+	...gh_author_association.author_fields_schema,
+})
+
+function is_blank_body(body: string | null | undefined): boolean {
+	return body?.trim().length === 0
+}
+
+// The write-access lookup asks *this* repository's collaborators, which says nothing about access to
+// another one — so an issue elsewhere is asked with no login, which `trust_of` answers for `OWNER`
+// alone (the rule `auto-ok-author.ts` applies to an epic child in another repository).
+async function is_author_trusted(row: AuthorFields, repo?: string): Promise<boolean> {
+	const author = gh_author_association.author_of(row)
+
+	return await gh_author_association.is_trusted(
+		repo === undefined ? author : { ...author, login: undefined },
+	)
+}
+
+// Whether the body is blank *and* its author has write access — a failed read is neither.
+async function is_writable_body(issue_number: string, repo?: string): Promise<boolean> {
+	const json = await git_gh_command.issue_view_json(issue_number, BODY_FIELDS, repo)
+	const parsed = json === undefined ? undefined : parse_json_object_or_undefined(json, body_schema)
+
+	if (parsed === undefined || !is_blank_body(parsed.body ?? '')) return false
+
+	return await is_author_trusted(parsed, repo)
+}
+
+// `repo` (`owner/name`) addresses an issue in another repository; left out, the checkout's own.
+async function post(issue_number: string, text: string, repo?: string): Promise<PostOutcome> {
+	if (await is_writable_body(issue_number, repo)) {
+		const url = await git_gh_command.issue_edit_body(issue_number, text, repo)
+
+		return { destination: 'body', url }
+	}
+
+	return {
+		destination: 'comment',
+		url: await git_gh_command.issue_comment(issue_number, text, repo),
+	}
+}
+
+const issue_body_or_comment = { post }
+
+export { issue_body_or_comment }
+export type { Destination, PostOutcome }

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

@@ -1,5 +1,3 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import type { IssueRead } from '#scripts/gh/git-gh-issue-read'
 import { bounded_pool } from '#scripts/lib/bounded-pool'
@@ -24,7 +22,6 @@ import { issue_cite, type CiteTarget } from './issue-cite'
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
-const ARGV_OFFSET = 2
 // The same bound `issue:read` puts on its batch read: every read is a `gh` process, and an unbounded
 // fan-out is answered with secondary rate limiting rather than with titles.
 const READ_CONCURRENCY = 8
@@ -132,8 +129,7 @@ function read_targets(args: ReadonlyArray<string>): ReadonlyArray<CiteTarget> |
 	return parse_targets(parsed.positionals, parsed.values.repo)
 }
 
-// The lines `issue:cite` prints for `args`, without printing them — the `Stop` hook shows them itself
-// (`stop-actions.ts`). `undefined` for a line nobody can read.
+// The lines `issue:cite` prints for `args`, or `undefined` for a line nobody can read.
 async function cite(args: ReadonlyArray<string>): Promise<CiteReport | undefined> {
 	const targets = read_targets(args)
 	if (targets === undefined) return undefined
@@ -160,17 +156,10 @@ async function run(args: ReadonlyArray<string>): Promise<number> {
 	return report(cited)
 }
 
-async function main(args: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(args)
-}
-
 const issue_cite_cli = {
 	USAGE,
-	cite,
 	parse_targets,
 	run,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export { issue_cite_cli }

package/scripts/issue/issue-cite-main.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { issue_cite_cli } from './issue-cite-cli'
+
+// The `josh issue:cite` entry, kept apart from `issue-cite-cli.ts` because other modules import that
+// one: a bundle is one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await issue_cite_cli.run(process.argv.slice(ARGV_OFFSET))
+}

package/scripts/issue/issue-classification.ts

@@ -1,3 +1,4 @@
+import { defect_origin_line } from './defect-origin-line'
 import { issue_bug_label } from './issue-bug-label'
 import { BREAKING_CHANGE_LABEL, BUG_LABEL, ENHANCEMENT_LABEL, has_label_name } from './issue-labels'
 import { markdown_section } from './markdown-section'
@@ -44,16 +45,21 @@ function bug_classification_problem(body: string): string | undefined {
 	return undefined
 }
 
-function problems(body: string): ReadonlyArray<string> {
-	const classification_problem = bug_classification_problem(body)
-	const found: Array<string> = []
-
-	if (classification_problem !== undefined) found.push(classification_problem)
+function label_conflict(body: string): string | undefined {
 	const labels = required_labels(body)
 
-	if (labels.includes(BUG_LABEL) && labels.includes(ENHANCEMENT_LABEL)) found.push(CONFLICT)
+	return labels.includes(BUG_LABEL) && labels.includes(ENHANCEMENT_LABEL) ? CONFLICT : undefined
+}
 
-	return found
+function problems(body: string): ReadonlyArray<string> {
+	const found = [
+		bug_classification_problem(body),
+		label_conflict(body),
+		defect_origin_line.problem(body),
+		defect_origin_line.reproduction_problem(body),
+	]
+
+	return found.filter((problem) => problem !== undefined)
 }
 
 const issue_classification = {

package/scripts/issue/issue-closing-pr.ts

@@ -88,6 +88,13 @@ async function read_closing_pr(issue: string): Promise<string | undefined> {
 	}
 }
 
-const issue_closing_pr = { read_closing_pr }
+// The closing pull request's number, read off the URL `read_closing_pr` answers.
+async function read_closing_number(issue: number): Promise<number | undefined> {
+	const url = await read_closing_pr(String(issue))
+
+	return url === undefined ? undefined : Number(url.slice(url.lastIndexOf('/') + 1))
+}
+
+const issue_closing_pr = { read_closing_number, read_closing_pr }
 
 export { issue_closing_pr }

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

@@ -1,5 +1,3 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
 import { cli_body } from '#scripts/josh/cli-body'
@@ -19,7 +17,6 @@ import { error_text } from '#scripts/lib/error-message'
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
-const ARGV_OFFSET = 2
 const BODY_FLAG = '--body'
 const BODY_FILE_FLAG = '--body-file'
 const USAGE = `Usage: josh issue:comment <issue-number> ${BODY_FLAG} <text> | ${BODY_FILE_FLAG} <path>`
@@ -33,23 +30,12 @@ interface CommentRequest {
 // ignored. `cli_body.resolve` owns the both-flags-at-once refusal and the file read.
 const OPTIONS = { body: { type: 'string' }, 'body-file': { type: 'string' } } as const
 
-// The number is the one positional, and it must be a real issue number: a missing, malformed or
-// second one refuses the whole call rather than posting to some other issue.
-function single_issue_number(positionals: ReadonlyArray<string>): string | undefined {
-	const [issue_number, ...rest] = positionals
-	const is_single = rest.length === 0 && issue_number !== undefined
-
-	return is_single && issue_number_shape.ISSUE_NUMBER_PATTERN.test(issue_number)
-		? issue_number
-		: undefined
-}
-
 // `resolve` may throw when both body flags are given, which `run` reports — the message names the two
 // flags a caller must pick between.
 function parse_request(argv: ReadonlyArray<string>): CommentRequest | undefined {
 	const parsed = cli_flags.arguments_of(argv, OPTIONS)
 	if (parsed === undefined) return undefined
-	const issue_number = single_issue_number(parsed.positionals)
+	const issue_number = issue_number_shape.single_of(parsed.positionals)
 	if (issue_number === undefined) return undefined
 
 	const body = cli_body.resolve({
@@ -67,11 +53,16 @@ function parse_request(argv: ReadonlyArray<string>): CommentRequest | undefined
 // A both-flags refusal and a file-read failure both surface as an `Error` from `resolve`, and its
 // message already names the flags or the resolved path — so it is printed as-is and `USAGE` is
 // withheld. `undefined` is the other refusal: a bad number or an empty body, which `USAGE` explains.
-function resolve_request(argv: ReadonlyArray<string>): CommentRequest | undefined {
+// `usage` is the caller's: `run:park` parks with the same issue number and body, so it reads them here
+// and prints its own usage on a refusal.
+function resolve_request(
+	argv: ReadonlyArray<string>,
+	usage: string = USAGE,
+): CommentRequest | undefined {
 	try {
 		const request = parse_request(argv)
 
-		if (request === undefined) console.error(USAGE)
+		if (request === undefined) console.error(usage)
 
 		return request
 	} catch (error) {
@@ -93,12 +84,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	return SUCCESS_EXIT_CODE
 }
 
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
-const issue_comment_cli = { USAGE, run }
-
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+const issue_comment_cli = { USAGE, resolve_request, run }
 
+export type { CommentRequest }
 export { issue_comment_cli }

package/scripts/issue/issue-comment-main.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { issue_comment_cli } from './issue-comment-cli'
+
+// The `josh issue:comment` entry, kept apart from `issue-comment-cli.ts` because other modules import
+// that one: a bundle is one file, so a main guard there would fire for every command that carries it
+// (joshuafolkken/kit#4186).
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await issue_comment_cli.run(process.argv.slice(ARGV_OFFSET))
+}