@joshuafolkken/kit 1.2116.0 → 1.3000.0

package/scripts/issue/issue-cite.ts

@@ -36,11 +36,28 @@ interface CiteTarget {
 // assembled. It is for text GitHub renders or a program reads: an Issue or PR
 // body, a comment, a commit message, a pattern, a key. GitHub links that text itself, so it needs no
 // link of its own; what a session reads goes through `session_cite.issue` instead, and the scan in
-// `session-cite-scan.test.ts` refuses a bare `#${…}` assembled anywhere else.
+// `session-cite-scan.test.ts` refuses a bare `#${…}` assembled anywhere else. It is not exported: a
+// caller reaches it through `plain_for`, which makes it say why (joshuafolkken/kit#6810).
 function plain(number: number | string, repo = ''): string {
 	return `${repo}#${String(number)}`
 }
 
+// Why a bare `#N` is right where it is assembled, declared at the call rather than in a central list
+// (joshuafolkken/kit#6807):
+// - `github`: GitHub renders it — a commit message, a PR or Issue title or body, a comment, a query.
+// - `telegram`: a person reads it on Telegram.
+// - `program`: a program reads it back — the run event stream, a process pattern, a child prompt, a
+//   parse key, a stash name.
+// - `terminal`: a person reads it in a terminal frame or a detached driver's stderr, unlinked.
+// - `linked`: the caller prints it through `session_cite.text` or `issue_citation.linkify`.
+type PlainReason = 'github' | 'linked' | 'program' | 'telegram' | 'terminal'
+
+// `plain` with its reason required, so a call that does not say why its text stays plain does not
+// compile; the reason is the declaration, so it is not read here.
+function plain_for(_reason: PlainReason, number: number | string, repo = ''): string {
+	return plain(number, repo)
+}
+
 function issue_url(slug: string, number: string): string {
 	return `${GITHUB_URL_PREFIX}${slug}${ISSUE_PATH}${number}`
 }
@@ -125,10 +142,10 @@ const issue_cite = {
 	missing_line,
 	no_repo_line,
 	parse_target,
-	plain,
+	plain_for,
 	reference,
 	unreadable_line,
 }
 
-export type { CiteTarget, IssueCiter }
+export type { CiteTarget, IssueCiter, PlainReason }
 export { issue_cite }

package/scripts/issue/issue-classification.ts

@@ -1,11 +1,30 @@
+import { pr_classification } from '#scripts/ci/pr-classification'
+import { error_text } from '#scripts/lib/error-message'
 import { defect_origin_line } from './defect-origin-line'
+import { issue_body_keys } from './issue-body-keys'
 import { issue_bug_label } from './issue-bug-label'
-import { BREAKING_CHANGE_LABEL, BUG_LABEL, ENHANCEMENT_LABEL, has_label_name } from './issue-labels'
+import {
+	BREAKING_CHANGE_LABEL,
+	BUG_LABEL,
+	ENHANCEMENT_LABEL,
+	has_label_name,
+	OTHER_CHANGE_LABEL,
+} from './issue-labels'
 import { markdown_section } from './markdown-section'
 
-const FEATURE_DECLARATIONS = ['- 目的: 機能追加', '- 目的: 機能改善', '- 目的: 時間短縮']
-const BREAKING_DECLARATION = '- 互換性: 破壊的変更'
-const NON_BUG_DECLARATION = '- 種別: 非不具合'
+const BACKGROUND_HEADING = issue_body_keys.heading('background')
+const FEATURE_DECLARATIONS = [
+	issue_body_keys.line('purpose', 'feature'),
+	issue_body_keys.line('purpose', 'improvement'),
+	issue_body_keys.line('purpose', 'time_saving'),
+]
+const BREAKING_DECLARATION = issue_body_keys.line('compatibility', 'breaking')
+const NON_BUG_DECLARATION = issue_body_keys.line('kind', 'non_bug')
+// The non-bug line as the filer wrote it, in either language (joshuafolkken/kit#7210).
+const NON_BUG_LINE = new RegExp(
+	String.raw`^ {0,3}(?:${issue_body_keys.line_variants('kind', 'non_bug').join('|')})[ \t]*$`,
+	'mu',
+)
 const CLASSIFICATION_LABELS = [BUG_LABEL, ENHANCEMENT_LABEL, BREAKING_CHANGE_LABEL]
 const CONFLICT = 'bug and enhancement declarations cannot be combined'
 const MISSING_BUG_CLASSIFICATION = 'missing bug classification'
@@ -13,7 +32,7 @@ const CONFLICTING_BUG_CLASSIFICATIONS = 'conflicting bug classifications'
 
 function required_labels(body: string): ReadonlyArray<string> {
 	const labels: Array<string> = []
-	const background = markdown_section.section_lines(body, '## 背景').join('\n')
+	const background = markdown_section.section_lines(body, BACKGROUND_HEADING).join('\n')
 
 	if (issue_bug_label.is_bug_fix(body)) labels.push(BUG_LABEL)
 
@@ -35,7 +54,7 @@ function labels_for(body: string, existing: ReadonlyArray<string>): ReadonlyArra
 }
 
 function bug_classification_problem(body: string): string | undefined {
-	const background = markdown_section.section_lines(body, '## 背景').join('\n')
+	const background = markdown_section.section_lines(body, BACKGROUND_HEADING).join('\n')
 	const has_bug = issue_bug_label.is_bug_fix(body)
 	const has_non_bug = markdown_section.has_unfenced_line(background, NON_BUG_DECLARATION)
 
@@ -51,10 +70,49 @@ function label_conflict(body: string): string | undefined {
 	return labels.includes(BUG_LABEL) && labels.includes(ENHANCEMENT_LABEL) ? CONFLICT : undefined
 }
 
-function problems(body: string): ReadonlyArray<string> {
+// The refusal `josh pr` would give this body filed with `labels`, so a body that cannot ship is
+// refused here.
+function selection_problem(body: string, labels: ReadonlyArray<string>): string | undefined {
+	try {
+		pr_classification.select_classification(labels, body)
+
+		return undefined
+	} catch (error) {
+		return error_text.message_of(error)
+	}
+}
+
+// A non-bug body whose declarations and `labels` (the ones it is filed with; the body's own when
+// left out) resolve to no release classification can only mean `other-change`, so it is written in
+// under the non-bug line. Any other body is returned unchanged.
+function with_release_classification(
+	body: string,
+	labels: ReadonlyArray<string> = required_labels(body),
+): string {
+	const line = pr_classification.declaration(OTHER_CHANGE_LABEL)
+	const amended = body.replace(NON_BUG_LINE, (non_bug) => `${non_bug}\n${line}`)
+
+	if (selection_problem(body, labels) === undefined) return body
+
+	return selection_problem(amended, labels) === undefined ? amended : body
+}
+
+function release_problem(body: string, labels: ReadonlyArray<string>): string | undefined {
+	if (bug_classification_problem(body) !== undefined || label_conflict(body) !== undefined) {
+		return undefined
+	}
+
+	return selection_problem(with_release_classification(body, labels), labels)
+}
+
+function problems(
+	body: string,
+	labels: ReadonlyArray<string> = required_labels(body),
+): ReadonlyArray<string> {
 	const found = [
 		bug_classification_problem(body),
 		label_conflict(body),
+		release_problem(body, labels),
 		defect_origin_line.problem(body),
 		defect_origin_line.reproduction_problem(body),
 	]
@@ -67,6 +125,7 @@ const issue_classification = {
 	labels_for,
 	problems,
 	required_labels,
+	with_release_classification,
 }
 
 export { issue_classification }

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

@@ -24,32 +24,46 @@ import { z } from 'zod'
 // number closes a different issue — its cross-reference here is a mention, not a close.
 
 const LINE_SEPARATOR = '\n'
-// One compact JSON object per merged pull request that cross-references the issue, and a
+// One compact JSON object per pull request that cross-references the issue, and a
 // `{"reopened":true}` marker per reopen, in timeline order.
 const TIMELINE_FILTER = [
 	'.[]',
-	'| if .event == "cross-referenced" and .source.issue.pull_request.merged_at != null',
-	'then {url: .source.issue.html_url, repo: .source.issue.repository.full_name, body: (.source.issue.body // "")}',
+	'| if .event == "cross-referenced" and .source.issue.pull_request != null',
+	'then {url: .source.issue.html_url, repo: .source.issue.repository.full_name, body: (.source.issue.body // ""), state: (if .source.issue.pull_request.merged_at != null then "merged" else .source.issue.state end)}',
 	'elif .event == "reopened" then {reopened: true}',
 	'else empty end',
 ].join(' ')
 
-const reference_schema = z.object({ url: z.string(), repo: z.string(), body: z.string() })
+const reference_schema = z.object({
+	url: z.string(),
+	repo: z.string(),
+	body: z.string(),
+	state: z.enum(['open', 'closed', 'merged']).default('merged'),
+})
 const reopen_schema = z.object({ reopened: z.literal(true) })
 const row_schema = z.union([reference_schema, reopen_schema])
 
 type MergedReference = z.infer<typeof reference_schema>
 type TimelineRow = z.infer<typeof row_schema>
+type ClosingRead = { kind: 'read'; url: string | undefined } | { kind: 'unreadable' }
+type ClosingNumberRead = { kind: 'read'; number: number | undefined } | { kind: 'unreadable' }
 
 function is_reference(row: TimelineRow): row is MergedReference {
 	return 'url' in row
 }
 
+function parse_row(line: string): TimelineRow {
+	const row = parse_json_object_or_undefined(line, row_schema)
+	if (row === undefined) throw new Error('the issue timeline contains an unreadable row')
+
+	return row
+}
+
 function parse_references(raw: string): Array<MergedReference> {
 	const rows = raw
 		.split(LINE_SEPARATOR)
-		.map((line) => parse_json_object_or_undefined(line, row_schema))
-		.filter((row) => row !== undefined)
+		.filter((line) => line.trim() !== '')
+		.map((line) => parse_row(line))
 	const last_reopen = rows.findLastIndex((row) => !is_reference(row))
 
 	return rows.slice(last_reopen + 1).filter((row) => is_reference(row))
@@ -63,38 +77,59 @@ function pick_closing_pr(
 	return references.find(
 		(reference) =>
 			reference.repo === repo &&
+			reference.state === 'merged' &&
 			git_closes_keyword.parse_closes_issue_number(reference.body) === issue,
 	)?.url
 }
 
-// Every doubt falls to `undefined` — an unreadable timeline or repository name leaves the child
-// judged as it was, never closed on a guess.
-async function read_closing_pr(issue: string): Promise<string | undefined> {
+async function read_closing_result(issue: string): Promise<ClosingRead> {
 	try {
+		// The canonical name, not the remote as typed: the timeline names the repository GitHub's way
+		// (joshuafolkken/kit#6752).
 		const [raw, repo] = await Promise.all([
 			git_gh_exec.exec_gh_api({
 				path: `${git_gh_api_path.issue_api_path(issue)}/timeline?per_page=100`,
 				should_paginate: true,
 				jq_filter: TIMELINE_FILTER,
 			}),
-			git_gh_repo.repo_get_name_with_owner(),
+			git_gh_repo.repo_get_canonical_name_with_owner(),
 		])
 
-		if (repo === undefined) return undefined
+		if (repo === undefined) return { kind: 'unreadable' }
 
-		return pick_closing_pr(parse_references(raw), issue, repo)
+		return { kind: 'read', url: pick_closing_pr(parse_references(raw), issue, repo) }
 	} catch {
-		return undefined
+		return { kind: 'unreadable' }
 	}
 }
 
+// Legacy callers leave the child unchanged when discovery is unavailable.
+async function read_closing_pr(issue: string): Promise<string | undefined> {
+	const result = await read_closing_result(issue)
+
+	return result.kind === 'read' ? result.url : undefined
+}
+
+async function read_closing_number_result(issue: number): Promise<ClosingNumberRead> {
+	const result = await read_closing_result(String(issue))
+	if (result.kind === 'unreadable') return result
+	const number =
+		result.url === undefined ? undefined : Number(result.url.slice(result.url.lastIndexOf('/') + 1))
+
+	return { kind: 'read', number }
+}
+
 // 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))
+	const result = await read_closing_number_result(issue)
 
-	return url === undefined ? undefined : Number(url.slice(url.lastIndexOf('/') + 1))
+	return result.kind === 'read' ? result.number : undefined
 }
 
-const issue_closing_pr = { read_closing_number, read_closing_pr }
+const issue_closing_pr = {
+	read_closing_number,
+	read_closing_number_result,
+	read_closing_pr,
+}
 
 export { issue_closing_pr }

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

@@ -0,0 +1,81 @@
+import { fileURLToPath } from 'node:url'
+import { cli_body } from '#scripts/josh/cli-body'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { error_text } from '#scripts/lib/error-message'
+import { issue_consolidate, type ConsolidateRequest } from './issue-consolidate'
+import { issue_number_shape } from './issue-number-shape'
+
+const USAGE =
+	'Usage: josh issue:consolidate <target> <duplicate>... [--title <title>] [--body-file <path>] [--demote]'
+const FAILURE = 1
+const ARGV_OFFSET = 2
+
+const OPTIONS = {
+	'body-file': { type: 'string' },
+	title: { type: 'string' },
+	demote: { type: 'boolean' },
+} as const
+
+// Every positional an issue number, the target not among the duplicates, and none named twice — a
+// repeat would close an issue that is already closed and report it as a failure.
+function issue_numbers_of(positionals: ReadonlyArray<string>): ReadonlyArray<number> | undefined {
+	if (positionals.some((value) => !issue_number_shape.is_issue_number(value))) return undefined
+	const numbers = positionals.map(Number)
+
+	return new Set(numbers).size === numbers.length ? numbers : undefined
+}
+
+// A flag given blank refuses rather than being dropped: the caller meant to write something.
+function text_of(value: string | undefined): string | undefined {
+	if (value === undefined) return undefined
+	if (value.trim().length === 0) throw new Error(USAGE)
+
+	return value
+}
+
+function issues_of(
+	positionals: ReadonlyArray<string>,
+): Pick<ConsolidateRequest, 'target' | 'duplicates'> {
+	const [target, ...duplicates] = issue_numbers_of(positionals) ?? []
+
+	if (target === undefined || duplicates.length === 0) throw new Error(USAGE)
+
+	return { target, duplicates }
+}
+
+function body_of(body_file: string | undefined): string | undefined {
+	return body_file === undefined ? undefined : text_of(cli_body.read_file_or_stdin(body_file))
+}
+
+function request_of(argv: ReadonlyArray<string>): ConsolidateRequest {
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
+
+	if (parsed === undefined) throw new Error(USAGE)
+
+	return {
+		...issues_of(parsed.positionals),
+		title: text_of(parsed.values.title)?.trim(),
+		body: body_of(text_of(parsed.values['body-file'])),
+		is_demote: parsed.values.demote === true,
+	}
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	try {
+		return await issue_consolidate.consolidate(request_of(argv))
+	} catch (error) {
+		console.error(error_text.message_of(error))
+
+		return FAILURE
+	}
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const issue_consolidate_cli = { main, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { issue_consolidate_cli }

package/scripts/issue/issue-consolidate.ts

@@ -0,0 +1,246 @@
+import { epic_index } from '#scripts/epic/epic-index'
+import { epic_promote } from '#scripts/epic/epic-promote'
+import { epic_untrack } from '#scripts/epic/epic-untrack'
+import { gh_author_association } from '#scripts/gh/gh-author-association'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_label_schema } from '#scripts/git/git-schemas'
+import { parse_json_object_or_undefined } from '#scripts/git/parse-json-array'
+import { error_text } from '#scripts/lib/error-message'
+import { z } from 'zod'
+import { issue_body_or_comment } from './issue-body-or-comment'
+import { EPIC_LABEL, label_name_of } from './issue-labels'
+import { session_cite } from './session-cite'
+
+// `josh issue:consolidate` — fold duplicate issues into one target through the existing write
+// primitives: each duplicate leaves the epics that track it and is closed as not planned with a
+// pointer to the target; the target takes the new title and body, and `--demote` turns it back
+// from an epic into a plain issue.
+//
+// **Every read comes before the first write**, so a missing target, an untrusted author or an
+// incomplete epic listing refuses with nothing written. A write that fails after that stops the run
+// and names the writes that already landed, since GitHub keeps them.
+
+interface ConsolidateRequest {
+	target: number
+	duplicates: ReadonlyArray<number>
+	title: string | undefined
+	body: string | undefined
+	is_demote: boolean
+}
+
+const TARGET_FIELDS = `body,labels,${gh_author_association.AUTHOR_FIELDS}`
+const EPIC_LIMIT = 200
+const COMPLETE_LISTING = 'none'
+const SUCCESS = 0
+const NOTHING_WRITTEN = 'nothing was written'
+const PROMOTED_LINE = new RegExp(String.raw`^${epic_promote.PROMOTED_HEADING}\s*$`, 'mu')
+
+const target_schema = z.looseObject({
+	body: z.string().nullish(),
+	labels: z.array(issue_label_schema).optional(),
+	...gh_author_association.author_fields_schema,
+})
+
+type Target = z.infer<typeof target_schema>
+type Tracking = ReadonlyMap<number, ReadonlyArray<number>>
+
+function parse_target(json: string | undefined): Target | undefined {
+	return json === undefined ? undefined : parse_json_object_or_undefined(json, target_schema)
+}
+
+async function read_target(request: ConsolidateRequest): Promise<Target> {
+	const cite = session_cite.issue(request.target)
+	const target = parse_target(
+		await git_gh_command.issue_view_json(String(request.target), TARGET_FIELDS),
+	)
+
+	if (target === undefined) throw new Error(`Could not read ${cite} — ${NOTHING_WRITTEN}.`)
+
+	if (request.body === undefined || (await issue_body_or_comment.is_author_trusted(target))) {
+		return target
+	}
+
+	throw new Error(`${cite} was filed by an author without write access — ${NOTHING_WRITTEN}.`)
+}
+
+// An epic past the listing's cut would keep tracking a closed duplicate, so a short read refuses.
+async function read_tracking(): Promise<Tracking> {
+	const fetched = await epic_index.fetch_epics(EPIC_LIMIT)
+
+	if (fetched?.cutoff !== COMPLETE_LISTING) {
+		throw new Error(`The open epics could not be read in full — ${NOTHING_WRITTEN}.`)
+	}
+
+	return epic_index.build_tracking_index(fetched.epics)
+}
+
+// The epic sections `epic --promote` appends start at its heading and run to the end of the body.
+function demoted(body: string): string {
+	const at = body.search(PROMOTED_LINE)
+
+	return at === -1 ? body : `${body.slice(0, at).trimEnd()}\n`
+}
+
+function next_body(request: ConsolidateRequest, current: string): string | undefined {
+	const base = request.body ?? current
+	const body = request.is_demote ? demoted(base) : base
+
+	return body === current ? undefined : body
+}
+
+function landed(action: () => Promise<unknown>): () => Promise<boolean> {
+	return async () => {
+		await action()
+
+		return true
+	}
+}
+
+async function is_landed(did_land: () => Promise<boolean>): Promise<boolean> {
+	try {
+		return await did_land()
+	} catch (error) {
+		console.error(error_text.message_of(error))
+
+		return false
+	}
+}
+
+async function write(
+	done: Array<string>,
+	step: string,
+	did_land: () => Promise<boolean>,
+): Promise<void> {
+	if (!(await is_landed(did_land))) throw new Error(`Failed: ${step}.`)
+	done.push(step)
+}
+
+async function demote_label(
+	request: ConsolidateRequest,
+	target: Target,
+	done: Array<string>,
+): Promise<void> {
+	if (!request.is_demote) return
+	const names = (target.labels ?? []).map((label) => label.name)
+	const stored = label_name_of(names, EPIC_LABEL)
+
+	if (stored === undefined) return
+	const issue = String(request.target)
+
+	await write(
+		done,
+		`${session_cite.issue(issue)} \`${EPIC_LABEL}\` label removed`,
+		landed(async () => {
+			await git_gh_command.issue_remove_label(issue, stored)
+		}),
+	)
+}
+
+async function rewrite_target(
+	request: ConsolidateRequest,
+	target: Target,
+	done: Array<string>,
+): Promise<void> {
+	const issue = String(request.target)
+	const cite = session_cite.issue(issue)
+	const { title } = request
+	const body = next_body(request, target.body ?? '')
+
+	if (title !== undefined) {
+		await write(
+			done,
+			`${cite} title`,
+			landed(async () => await git_gh_command.issue_edit_title(issue, title)),
+		)
+	}
+
+	if (body !== undefined) {
+		await write(
+			done,
+			`${cite} body`,
+			landed(async () => await git_gh_command.issue_edit_body(issue, body)),
+		)
+	}
+
+	await demote_label(request, target, done)
+}
+
+async function untrack_duplicate(
+	duplicate: number,
+	tracking: Tracking,
+	done: Array<string>,
+): Promise<void> {
+	const cite = session_cite.issue(duplicate)
+	const epics = new Set(tracking.get(duplicate))
+
+	for (const epic of epics) {
+		// eslint-disable-next-line no-await-in-loop -- a failed write stops the run before the next one
+		await write(done, `${cite} untracked from epic ${session_cite.issue(epic)}`, async () => {
+			return (await epic_untrack.untrack(epic, [duplicate])) === SUCCESS
+		})
+	}
+}
+
+async function close_duplicate(
+	target: number,
+	duplicate: number,
+	done: Array<string>,
+): Promise<void> {
+	const comment = `Consolidated into ${session_cite.issue(target)}.`
+
+	await write(done, `${session_cite.issue(duplicate)} closed as not planned`, async () => {
+		return await git_gh_command.issue_close(String(duplicate), comment, 'not_planned')
+	})
+}
+
+// The epic rows go first, before the target is rewritten: a demoted or rewritten target epic no
+// longer tracks its duplicates, so its untrack would refuse. A failed untrack leaves every duplicate
+// open, so a re-run finds them again.
+async function apply(request: ConsolidateRequest, done: Array<string>): Promise<void> {
+	const target = await read_target(request)
+	const tracking = await read_tracking()
+
+	for (const duplicate of request.duplicates) {
+		// eslint-disable-next-line no-await-in-loop -- a failed write stops the run before the next one
+		await untrack_duplicate(duplicate, tracking, done)
+	}
+
+	await rewrite_target(request, target, done)
+
+	for (const duplicate of request.duplicates) {
+		// eslint-disable-next-line no-await-in-loop -- a failed write stops the run before the next one
+		await close_duplicate(request.target, duplicate, done)
+	}
+}
+
+function step_lines(done: ReadonlyArray<string>): string {
+	return done.map((step) => `  - ${step}`).join('\n')
+}
+
+function report_failure(error: unknown, done: ReadonlyArray<string>): void {
+	console.error(`✖ ${error_text.message_of(error)}`)
+	if (done.length === 0) return
+	console.error(`Already written — not undone:\n${step_lines(done)}`)
+}
+
+// Exit code: 0 when every write landed, 1 when a read refused or a write failed.
+async function consolidate(request: ConsolidateRequest): Promise<number> {
+	const done: Array<string> = []
+
+	try {
+		await apply(request, done)
+	} catch (error) {
+		report_failure(error, done)
+
+		return 1
+	}
+
+	console.info(`✔ Consolidated into ${session_cite.issue(request.target)}:\n${step_lines(done)}`)
+
+	return SUCCESS
+}
+
+const issue_consolidate = { consolidate }
+
+export { issue_consolidate }
+export type { ConsolidateRequest }

package/scripts/issue/issue-declared-size.ts

@@ -0,0 +1,21 @@
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import type { DeclaredSize } from '#scripts/split/split-assess'
+import { size_estimate } from './size-estimate'
+
+// An Issue's declared size estimate (`size_estimate.declared_size`), read from its body: what the split notice's bar
+// grows from (`split-resolution.ts`) and what `lane:stats` calibrates against (`lane-size-record.ts`).
+// A body with no estimate is `undefined`; a read that failed (missing, rate-limited, unreachable)
+// throws, so a caller that keeps the answer never keeps a passing failure as "no declaration".
+async function read(issue: string): Promise<DeclaredSize | undefined> {
+	const body = await git_gh_command.issue_get_body_classified(issue)
+
+	if (body.kind !== 'read') throw new Error(`issue ${issue} body: ${body.kind}`)
+	if (body.text === undefined) return undefined
+	const estimate = size_estimate.declared_size(body.text)
+
+	return estimate === undefined ? undefined : { files: estimate.files, lines: estimate.lines }
+}
+
+const issue_declared_size = { read }
+
+export { issue_declared_size }

package/scripts/issue/issue-evidence-exit.ts

@@ -22,10 +22,11 @@ interface EvidenceRequest {
 }
 
 // `admit`, when given, runs once the request parsed and before the first write: an exit that does not
-// fit the Issue refuses there, with nothing written.
+// fit the Issue refuses there, with nothing written. `finish` reads the posted evidence too, for an
+// exit whose write depends on what the evidence cites (`issue-already-done-cli.ts`).
 interface EvidenceExit {
 	command: string
-	finish: (issue_number: string) => Promise<boolean>
+	finish: (issue_number: string, evidence: string) => Promise<boolean>
 	admit?: (issue_number: string) => Promise<boolean>
 }
 
@@ -78,7 +79,9 @@ async function post_evidence(request: EvidenceRequest): Promise<boolean> {
 
 // Each write runs only once the one before it landed: `&&` stops at the first that did not.
 async function write_exit(request: EvidenceRequest, exit: EvidenceExit): Promise<boolean> {
-	return (await post_evidence(request)) && (await exit.finish(request.issue_number))
+	const { issue_number, evidence } = request
+
+	return (await post_evidence(request)) && (await exit.finish(issue_number, evidence))
 }
 
 async function is_admitted(request: EvidenceRequest, exit: EvidenceExit): Promise<boolean> {