@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/issue/issue-not-before.ts

@@ -0,0 +1,111 @@
+import { issue_sample_gate } from './issue-sample-gate'
+import { markdown_section } from './markdown-section'
+
+// joshuafolkken/kit#4007: a follow-up measurement filed with `auto-ok` ("measure three days after #N
+// merges") was offered by `backlog:next` the day it was filed, and its lane could only hand the hold
+// back. The body now names the earliest time the work can start, and the pickup holds the issue until
+// then. One UTC spelling only — a date a reader has to guess the zone of is not a deadline.
+// A body may instead wait on samples recorded after a pull request merged (`issue-sample-gate.ts`);
+// this module answers for both, so every reader holds an issue back the same way.
+
+const BACKGROUND_HEADING = '## 背景'
+const PREFIX = '- 実施可能日:'
+const DATE_PATTERN = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}Z$/u
+// What `toISOString` writes after the minutes the declaration spells.
+const ISO_TAIL = ':00.000Z'
+const MALFORMED = `\`${PREFIX}\` must be a UTC time written YYYY-MM-DDTHH:MMZ`
+const HEADING_MARKS = /^#{1,6}\s+/u
+// joshuafolkken/kit#4438: a start condition written as its own heading is never read — every reader
+// sees only the declaration line under the background heading — so the issue is offered at once.
+const STRAY_HEADINGS = [
+	{ name: '実施可能日', declaration: `${PREFIX} YYYY-MM-DDTHH:MMZ` },
+	{ name: '実施可能条件', declaration: issue_sample_gate.DECLARATION },
+]
+
+// The value after the declaration under the background heading, or `undefined` when the body declares none.
+function declared_value(body: string): string | undefined {
+	const background = markdown_section.section_lines(body, BACKGROUND_HEADING).join('\n')
+	const line = markdown_section
+		.unfenced_lines(background)
+		.map((text) => text.trim())
+		.find((text) => text.startsWith(PREFIX))
+
+	return line?.slice(PREFIX.length).trim()
+}
+
+// The round trip refuses a calendar-impossible value (`2026-02-30T09:30Z`, `T24:00Z`) that
+// `Date.parse` silently rolls over into a different time.
+function is_valid(value: string): boolean {
+	if (!DATE_PATTERN.test(value)) return false
+
+	const time = Date.parse(value)
+
+	return !Number.isNaN(time) && new Date(time).toISOString() === `${value.slice(0, -1)}${ISO_TAIL}`
+}
+
+// The declared time, or `undefined` when there is none or it does not parse. A malformed date reads as
+// absent: `issue:file` refuses it, and holding a hand-edited one forever would lose the issue silently.
+function date_of(body = ''): string | undefined {
+	const value = declared_value(body)
+
+	return value !== undefined && is_valid(value) ? value : undefined
+}
+
+function is_date_due(body: string | undefined, now: number): boolean {
+	const date = date_of(body)
+
+	return date === undefined || Date.parse(date) <= now
+}
+
+// Whether the issue may start: its declared time has arrived and its declared samples are recorded.
+function is_due(body: string | undefined, now: number = Date.now()): boolean {
+	return is_date_due(body, now) && issue_sample_gate.wait_of(body) === undefined
+}
+
+// The declared time as epoch milliseconds while it is still ahead, or `undefined` when it has arrived —
+// for a reader that spells the time its own way (`run:board` in the local zone).
+function waiting_ms(body: string | undefined, now: number = Date.now()): number | undefined {
+	if (is_date_due(body, now)) return undefined
+
+	return Date.parse(String(date_of(body)))
+}
+
+// The declared time as written while it is still ahead, or `undefined` when it has arrived.
+function waiting_date(body: string | undefined, now: number = Date.now()): string | undefined {
+	return is_date_due(body, now) ? undefined : date_of(body)
+}
+
+// Why `backlog:next` holds an issue back, or `undefined` when it is due. The caller cites the issue.
+function waiting_reason(body: string | undefined, now: number = Date.now()): string | undefined {
+	const date = waiting_date(body, now)
+
+	if (date !== undefined) return `not before ${date}`
+
+	const wait = issue_sample_gate.wait_of(body)
+
+	return wait === undefined ? undefined : issue_sample_gate.reason_of(wait)
+}
+
+function stray_heading_problems(body: string): ReadonlyArray<string> {
+	const headings = markdown_section
+		.unfenced_lines(body)
+		.map((line) => line.trim())
+		.filter((line) => HEADING_MARKS.test(line))
+		.map((line) => line.replace(HEADING_MARKS, ''))
+
+	return STRAY_HEADINGS.filter(({ name }) => headings.some((text) => text.startsWith(name))).map(
+		({ name, declaration }) =>
+			`heading \`${name}\` is not read — declare it under \`${BACKGROUND_HEADING}\` as \`${declaration}\``,
+	)
+}
+
+function problems(body: string): ReadonlyArray<string> {
+	const value = declared_value(body)
+	const date_problems = value === undefined || is_valid(value) ? [] : [MALFORMED]
+
+	return [...stray_heading_problems(body), ...date_problems, ...issue_sample_gate.problems(body)]
+}
+
+const issue_not_before = { is_due, problems, waiting_date, waiting_ms, waiting_reason }
+
+export { issue_not_before }

package/scripts/issue/issue-number-shape.ts

@@ -22,6 +22,20 @@ function require_issue_number(issue: string): void {
 	if (!is_issue_number(issue)) throw new Error(`${BAD_ISSUE_MESSAGE}${issue}`)
 }
 
-const issue_number_shape = { ISSUE_NUMBER_PATTERN, is_issue_number, require_issue_number }
+// A command whose one positional is the issue it writes to: a missing, malformed or second number
+// answers `undefined`, so the caller refuses the whole call rather than writing to some other issue.
+function single_of(positionals: ReadonlyArray<string>): string | undefined {
+	const [issue_number, ...rest] = positionals
+	const is_single = rest.length === 0 && issue_number !== undefined
+
+	return is_single && ISSUE_NUMBER_PATTERN.test(issue_number) ? issue_number : undefined
+}
+
+const issue_number_shape = {
+	ISSUE_NUMBER_PATTERN,
+	is_issue_number,
+	require_issue_number,
+	single_of,
+}
 
 export { issue_number_shape }

package/scripts/issue/issue-park.ts

@@ -0,0 +1,28 @@
+import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
+
+// A park on GitHub: the label that keeps an issue from being offered again, and the comment that says
+// why. `run:park` (a lane child's `needs-decision`), `run:merge` and the ship relaunch cap (both
+// `run:stalled`) park the same way, so the pair is written once here (joshuafolkken/kit#4132).
+//
+// **The label goes first and the comment only on it.** The label is what every offer reads; a comment
+// on an issue whose label failed would explain a park that did not happen.
+
+interface ParkWrite {
+	is_labelled: boolean
+	is_commented: boolean
+}
+
+async function apply(issue: string, label: string, body: string): Promise<ParkWrite> {
+	const is_labelled = await git_gh_issue_write.issue_add_label(issue, label)
+
+	if (!is_labelled) return { is_labelled, is_commented: false }
+
+	const is_commented = await git_gh_issue_write.issue_try_comment(issue, body)
+
+	return { is_labelled, is_commented }
+}
+
+const issue_park = { apply }
+
+export type { ParkWrite }
+export { issue_park }

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

@@ -0,0 +1,151 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { git_gh_command } from '#scripts/gh/git-gh-command'
+import { issue_body_or_comment } from '#scripts/issue/issue-body-or-comment'
+import { PLANNED_LABEL } from '#scripts/issue/issue-labels'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { plan_consumers_section } from '#scripts/issue/plan-consumers-section'
+import { cli_body } from '#scripts/josh/cli-body'
+import { cli_flags } from '#scripts/lib/cli-flags'
+import { error_text } from '#scripts/lib/error-message'
+
+// `josh issue:plan <N> --body-file <path> [--title <title>] [--planned]` — record a plan on an issue
+// in one call: the title normalized, the plan written into a blank body or posted as a comment, and
+// `run:planned` applied.
+//
+// **`kickoff` and `fullrun` spelled those three writes out by hand** — a `gh api -X PATCH` for the
+// title, a second one for a blank body or `issue:comment` otherwise, and a third `gh api` for the
+// label — so the blank-body decision lived in three documents. It now lives in
+// `issue-body-or-comment.ts`, which `followup`'s completion notice shares.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const USAGE =
+	'Usage: josh issue:plan <issue-number> --body-file <path> [--title <title>] [--planned] [--repo <owner/name>]'
+
+interface PlanRequest {
+	issue_number: string
+	plan: string
+	title: string | undefined
+	is_planned: boolean
+	repo: string | undefined
+}
+
+const OPTIONS = {
+	'body-file': { type: 'string' },
+	title: { type: 'string' },
+	planned: { type: 'boolean' },
+	repo: { type: 'string' },
+} as const
+
+// The plan is read last, from the path the flags named; an empty plan refuses like a missing one. A
+// plan without its existing-consumers section throws its refusal, printed as-is like a read failure,
+// before any write (`plan-consumers-section.ts`).
+function with_plan(
+	flags: Omit<PlanRequest, 'plan'>,
+	file_path: string | undefined,
+): PlanRequest | undefined {
+	if (file_path === undefined) return undefined
+	const plan = cli_body.read_file_or_stdin(file_path)
+
+	if (plan.trim().length === 0) return undefined
+	const refusal = plan_consumers_section.refusal_of(plan)
+
+	if (refusal !== undefined) throw new Error(refusal)
+
+	return { ...flags, plan }
+}
+
+// An optional string flag, trimmed; given blank it is `''`, which the caller refuses.
+function trimmed(value: string | undefined): string | undefined {
+	return value?.trim()
+}
+
+// A `--title` or `--repo` given blank refuses rather than being dropped: the caller meant to rename
+// the issue, or to address another repository's — a dropped `--repo` would write to this one's.
+function parse_request(argv: ReadonlyArray<string>): PlanRequest | undefined {
+	const parsed = cli_flags.arguments_of(argv, OPTIONS)
+
+	if (parsed === undefined) return undefined
+	const issue_number = issue_number_shape.single_of(parsed.positionals)
+	const [title, repo] = [trimmed(parsed.values.title), trimmed(parsed.values.repo)]
+
+	if (issue_number === undefined || [title, repo].includes('')) return undefined
+	const is_planned = parsed.values.planned === true
+
+	return with_plan({ issue_number, title, is_planned, repo }, parsed.values['body-file'])
+}
+
+// A file-read failure surfaces as an `Error` naming the resolved path, printed as-is; `undefined` is
+// a malformed call, which `USAGE` explains.
+function resolve_request(argv: ReadonlyArray<string>): PlanRequest | undefined {
+	try {
+		const request = parse_request(argv)
+
+		if (request === undefined) console.error(USAGE)
+
+		return request
+	} catch (error) {
+		console.error(error_text.message_of(error))
+
+		return undefined
+	}
+}
+
+// The title goes first, so the plan and the label land on an issue already carrying the name the
+// plan was written under; the label goes last, so `run:planned` never marks an issue whose plan
+// failed to post.
+async function apply_planned_label(issue_number: string, repo?: string): Promise<boolean> {
+	const is_applied = await git_gh_command.issue_add_label(issue_number, PLANNED_LABEL, repo)
+
+	if (is_applied) console.info(`label: ${PLANNED_LABEL}`)
+	else console.error(`Could not apply ${PLANNED_LABEL} to issue ${issue_number}.`)
+
+	return is_applied
+}
+
+// `--repo` addresses every write — the title, the plan and the label — so `kickoff kit#<N>` run from
+// another checkout records the plan on the named repository's issue, never on this one's.
+async function record_plan(request: PlanRequest): Promise<boolean> {
+	const { issue_number, title, repo } = request
+
+	if (title !== undefined) {
+		console.info(`title: ${await git_gh_command.issue_edit_title(issue_number, title, repo)}`)
+	}
+
+	const posted = await issue_body_or_comment.post(issue_number, request.plan, repo)
+
+	console.info(`${posted.destination}: ${posted.url}`)
+
+	return request.is_planned ? await apply_planned_label(issue_number, repo) : true
+}
+
+// A refused write prints as one line, like a file-read failure, rather than escaping as a stack trace.
+async function try_record_plan(request: PlanRequest): Promise<boolean> {
+	try {
+		return await record_plan(request)
+	} catch (error) {
+		console.error(error_text.message_of(error))
+
+		return false
+	}
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const request = resolve_request(argv)
+
+	if (request === undefined) return FAILURE_EXIT_CODE
+
+	return (await try_record_plan(request)) ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const issue_plan_cli = { USAGE, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { issue_plan_cli }

package/scripts/issue/issue-priority.ts

@@ -0,0 +1,151 @@
+import { expected_effect_lint } from './expected-effect-lint'
+import { has_label_name, PRIORITY_CRITICAL_LABEL, PRIORITY_HIGH_LABEL } from './issue-labels'
+import { markdown_section } from './markdown-section'
+
+// joshuafolkken/kit#4383: the priority `josh issue:file` applies, read from the body's one priority
+// declaration under its background heading (`issue-template.md` holds the criteria). An urgent or high
+// declaration must name its basis, so neither label is applied on a bare word. A run-time-shortening
+// Issue's reduction-per-merge line sets a floor — its share of the median lane time per merge — and
+// a declaration below that floor is refused. A priority label the filer typed (`kickoff new critical`)
+// wins: the body is then not judged at all.
+
+type PriorityLevel = 'critical' | 'high' | 'normal'
+
+interface LevelParser {
+	pattern: RegExp
+	level: PriorityLevel
+	accepts: (basis: string) => boolean
+}
+
+const BACKGROUND_HEADING = '## 背景'
+const DECLARATION_PREFIX = '- 優先度:'
+const NORMAL_LINE = '- 優先度: 通常'
+const CRITICAL_PATTERN = /^- 優先度: 緊急（(?<basis>.*)）$/u
+const HIGH_PATTERN = /^- 優先度: 高（(?<basis>.*)）$/u
+// An interrupt-filing condition number (`wip-cap.md`) or a stated reduction.
+const CRITICAL_BASIS = /条件 ?[1-3]|短縮 ?\d/u
+const PLACEHOLDER = /^<.*>$/u
+const REDUCTION_PREFIX = '- 1 マージあたりの短縮:'
+// A number with its percent sign, half- or full-width, glued to the word before it or not, one space
+// before the sign or none.
+const PERCENT = /(?<![\d.])(?<value>[\d.]+) ?[%％]/gu
+const CRITICAL_PERCENT = 10
+const HIGH_PERCENT = 3
+const LEVELS: ReadonlyArray<PriorityLevel> = ['normal', 'high', 'critical']
+const LABELS: Readonly<Record<PriorityLevel, string | undefined>> = {
+	critical: PRIORITY_CRITICAL_LABEL,
+	high: PRIORITY_HIGH_LABEL,
+	normal: undefined,
+}
+const DECLARATION_PROBLEM = `declare at most one priority under \`${BACKGROUND_HEADING}\`: \`- 優先度: 緊急（条件 <1-3> / 短縮 <値>）\`, \`- 優先度: 高（<根拠>）\` or \`${NORMAL_LINE}\` — an urgent or high one names its basis (\`issue-template.md\`)`
+
+const REDUCTION_PROBLEM = `a \`${expected_effect_lint.DECLARATION_LINE}\` Issue states \`${REDUCTION_PREFIX} <分>（レーン中央値 <分> の <%>）\` under \`${expected_effect_lint.HEADING}\` with its percentage filled in (\`issue-template.md\`)`
+
+function unfenced_lines(body: string, heading: string): ReadonlyArray<string> {
+	const section = markdown_section.section_lines(body, heading).join('\n')
+
+	return markdown_section.unfenced_lines(section).map((line) => line.trim())
+}
+
+function has_basis(basis: string): boolean {
+	const trimmed = basis.trim()
+
+	return trimmed.length > 0 && !PLACEHOLDER.test(trimmed)
+}
+
+function has_critical_basis(basis: string): boolean {
+	return CRITICAL_BASIS.test(basis)
+}
+
+const PARSERS: ReadonlyArray<LevelParser> = [
+	{ pattern: CRITICAL_PATTERN, level: 'critical', accepts: has_critical_basis },
+	{ pattern: HIGH_PATTERN, level: 'high', accepts: has_basis },
+]
+
+function parsed_level(parser: LevelParser, line: string): PriorityLevel | undefined {
+	const basis = parser.pattern.exec(line)?.groups?.['basis'] ?? ''
+
+	return parser.accepts(basis) ? parser.level : undefined
+}
+
+// The level one declaration line states, or `undefined` when it is malformed or names no basis.
+function level_of(line: string): PriorityLevel | undefined {
+	if (line === NORMAL_LINE) return 'normal'
+	const parser = PARSERS.find((entry) => entry.pattern.test(line))
+
+	return parser === undefined ? undefined : parsed_level(parser, line)
+}
+
+// `normal` when the body declares nothing, `undefined` when it declares more than one line or a bad one.
+function declared_level(body: string): PriorityLevel | undefined {
+	const lines = unfenced_lines(body, BACKGROUND_HEADING).filter((line) =>
+		line.startsWith(DECLARATION_PREFIX),
+	)
+
+	if (lines.length === 0) return 'normal'
+
+	return lines.length === 1 ? level_of(lines[0] ?? '') : undefined
+}
+
+// The share of the median lane time per merge the reduction line states, the last percentage on it.
+function reduction_percent(body: string): number | undefined {
+	const line = unfenced_lines(body, expected_effect_lint.HEADING).find((text) =>
+		text.startsWith(REDUCTION_PREFIX),
+	)
+	const values = [...(line ?? '').matchAll(PERCENT)].map((match) => Number(match.groups?.['value']))
+
+	return values.findLast((value) => Number.isFinite(value))
+}
+
+// The lowest level a run-time-shortening Issue may declare, from its stated reduction.
+function floor_of(body: string): PriorityLevel {
+	const percent = expected_effect_lint.is_target(body) ? reduction_percent(body) : undefined
+
+	if (percent === undefined || percent < HIGH_PERCENT) return 'normal'
+
+	return percent >= CRITICAL_PERCENT ? 'critical' : 'high'
+}
+
+function is_typed(labels: ReadonlyArray<string>): boolean {
+	return (
+		has_label_name(labels, PRIORITY_CRITICAL_LABEL) || has_label_name(labels, PRIORITY_HIGH_LABEL)
+	)
+}
+
+// A run-time-shortening Issue must state its reduction as a percentage, or its floor could not be judged.
+function has_missing_reduction(body: string): boolean {
+	return expected_effect_lint.is_target(body) && reduction_percent(body) === undefined
+}
+
+function floor_problem(body: string, level: PriorityLevel): string | undefined {
+	const floor = floor_of(body)
+
+	if (LEVELS.indexOf(level) >= LEVELS.indexOf(floor)) return undefined
+
+	return `the stated reduction per merge ranks this Issue \`${floor}\`, above its declared \`${level}\` — declare \`- 優先度: ${floor === 'critical' ? '緊急' : '高'}（短縮 …）\` (\`issue-template.md\`)`
+}
+
+// Why the filing is refused for its priority, or `undefined`. `typed` is the `--label` list.
+function problem(body: string, typed: ReadonlyArray<string>): string | undefined {
+	if (is_typed(typed)) return undefined
+	const level = declared_level(body)
+
+	if (level === undefined) return DECLARATION_PROBLEM
+	if (has_missing_reduction(body)) return REDUCTION_PROBLEM
+
+	return floor_problem(body, level)
+}
+
+// The labels a new Issue is filed with — the declared priority's label added unless one was typed.
+function with_label(labels: ReadonlyArray<string>, body: string): ReadonlyArray<string> {
+	const label = LABELS[declared_level(body) ?? 'normal']
+
+	if (label === undefined || is_typed(labels)) return labels
+
+	return [...labels, label]
+}
+
+const issue_priority = { declared_level, floor_of, problem, with_label }
+
+export type { PriorityLevel }
+export { issue_priority }

package/scripts/issue/issue-rank.ts

@@ -2,6 +2,7 @@ import {
 	BUG_LABEL,
 	has_label_name,
 	INTERRUPT_ROUTE_LABEL,
+	PRIORITY_CRITICAL_LABEL,
 	PRIORITY_HIGH_LABEL,
 	RUN_SOLO_LABEL,
 } from './issue-labels'
@@ -9,7 +10,7 @@ import {
 // The keys that decide which open issue is offered first, defined once for
 // every ranking that asks: the `🗒 Next issues` display, the `auto-ok` pickup and `backlog:next`.
 //
-// In order: `priority:high`, then a defect on the verification path (`bug` with `run:solo`, or
+// In order: `priority:critical`, then `priority:high`, then a defect on the verification path (`bug` with `run:solo`, or
 // `route:interrupt`), then how many other open issues wait on it. Below those, the caller's own order
 // stands — the sort is stable, so recency and the defect-rate adjustment survive as the last key.
 //
@@ -35,6 +36,10 @@ function flag(is_set: boolean): number {
 	return is_set ? 1 : 0
 }
 
+function is_critical(labels: ReadonlyArray<string>): boolean {
+	return has_label_name(labels, PRIORITY_CRITICAL_LABEL)
+}
+
 function is_priority(labels: ReadonlyArray<string>): boolean {
 	return has_label_name(labels, PRIORITY_HIGH_LABEL)
 }
@@ -48,6 +53,7 @@ function is_verification_defect(labels: ReadonlyArray<string>): boolean {
 // Negated so that the larger value sorts first under an ascending comparison.
 function keys_of(row: RankRow): ReadonlyArray<number> {
 	return [
+		-flag(is_critical(row.labels)),
 		-flag(is_priority(row.labels)),
 		-flag(is_verification_defect(row.labels)),
 		-row.dependents,

package/scripts/issue/issue-read-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 { bounded_pool } from '#scripts/lib/bounded-pool'
@@ -27,7 +25,6 @@ import { issue_report_failures, type ReadFailureKind } from './issue-report-fail
 // wins, and a comment nobody read cannot win anything.
 
 const FAILURE_EXIT_CODE = 1
-const ARGV_OFFSET = 2
 const USAGE = 'Usage: josh issue:read <issue-number> [<issue-number> ...]'
 const BLOCK_SEPARATOR = '\n\n---\n\n'
 // The same bound `issue:state` puts on its batch read, for the same reason: every read is a `gh`
@@ -82,7 +79,9 @@ async function read_issue(issue_number: string): Promise<NumberResult> {
 
 	if (fields === undefined) return { kind: 'unreadable' }
 
-	return { kind: 'issue', content: { fields, comments: issue_read.parse_comments(comments_json) } }
+	const comments = await issue_read.parse_comments(comments_json)
+
+	return { kind: 'issue', content: { fields, comments } }
 }
 
 // One issue's block for a caller that wants the text rather than the printing — `run:prep` composes it
@@ -134,10 +133,6 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	return issue_report_failures.report_failures(reports, FAILURE_TERMS)
 }
 
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const issue_read_cli = {
 	USAGE,
 	parse_numbers,
@@ -145,7 +140,5 @@ const issue_read_cli = {
 	run,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export type { BlockRead }
 export { issue_read_cli }

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

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

package/scripts/issue/issue-read.ts

@@ -1,3 +1,4 @@
+import { gh_author_association } from '#scripts/gh/gh-author-association'
 import { parse_json_object_or_undefined, read_json_listing } from '#scripts/git/parse-json-array'
 import { z } from 'zod'
 
@@ -30,6 +31,10 @@ const COMMENT_SEPARATOR = '\n\n'
 const SECTION_SEPARATOR = '\n\n'
 const COMMENT_HEADING = 'comment by '
 const AT = ' at '
+// **A comment from an author without write access is shown but never read** (joshuafolkken/kit#4021):
+// on a public repository anyone can comment, and `issue-comments.md` takes the later text as the
+// agreement in force, so a third party's comment printed whole would be an instruction to the run.
+const UNTRUSTED_COMMENT = `(body withheld — the author is not ${gh_author_association.TRUSTED_LIST}, so it is not an instruction)`
 
 const issue_fields_schema = z.looseObject({
 	title: z.string(),
@@ -41,6 +46,7 @@ const comment_schema = z.looseObject({
 	user: z.looseObject({ login: z.string() }).optional(),
 	created_at: z.string().optional(),
 	body: z.string().optional(),
+	author_association: z.string().nullish(),
 })
 
 interface IssueFields {
@@ -53,6 +59,7 @@ interface IssueComment {
 	author: string
 	created_at: string
 	body: string
+	is_trusted: boolean
 }
 
 const UNKNOWN_AUTHOR = '(unknown)'
@@ -74,11 +81,17 @@ function parse_issue_fields(json: string): IssueFields | undefined {
 	}
 }
 
-function to_comment(raw: z.infer<typeof comment_schema>): IssueComment {
+async function to_comment(raw: z.infer<typeof comment_schema>): Promise<IssueComment> {
+	const login = raw.user?.login
+
 	return {
-		author: raw.user?.login ?? UNKNOWN_AUTHOR,
+		author: login ?? UNKNOWN_AUTHOR,
 		created_at: raw.created_at ?? UNKNOWN_TIME,
 		body: raw.body ?? '',
+		is_trusted: await gh_author_association.is_trusted({
+			login,
+			association: raw.author_association,
+		}),
 	}
 }
 
@@ -91,18 +104,27 @@ function to_comment(raw: z.infer<typeof comment_schema>): IssueComment {
 // outcomes it already tells apart; a `JSON.parse` plus `safeParse` pair here would be the clone
 // `CLAUDE.md` prohibits, on the one endpoint two modules would then parse two ways. All three collapse
 // to `undefined` here, because the block above draws only one distinction: read, or not read.
-function parse_comments(json: string | undefined): ReadonlyArray<IssueComment> | undefined {
+async function parse_comments(
+	json: string | undefined,
+): Promise<ReadonlyArray<IssueComment> | undefined> {
 	if (json === undefined) return undefined
 
 	const listing = read_json_listing(json, comment_schema)
 
-	return listing.kind === 'read' ? listing.rows.map((row) => to_comment(row)) : undefined
+	if (listing.kind !== 'read') return undefined
+
+	return await Promise.all(listing.rows.map(async (row) => await to_comment(row)))
+}
+
+// The bodies a caller may act on — the comments of authors with write access, in order.
+function trusted_bodies(comments: ReadonlyArray<IssueComment>): ReadonlyArray<string> {
+	return comments.filter((comment) => comment.is_trusted).map((comment) => comment.body)
 }
 
 function format_comment(comment: IssueComment): string {
 	const heading = `${COMMENT_HEADING}${comment.author}${AT}${comment.created_at}`
 
-	return `${heading}\n${comment.body}`
+	return `${heading}\n${comment.is_trusted ? comment.body : UNTRUSTED_COMMENT}`
 }
 
 function format_comments(comments: ReadonlyArray<IssueComment> | undefined): string {
@@ -133,9 +155,11 @@ const issue_read = {
 	NO_COMMENTS,
 	COMMENTS_UNREADABLE,
 	COMMENT_HEADING,
+	UNTRUSTED_COMMENT,
 	format_issue,
 	parse_comments,
 	parse_issue_fields,
+	trusted_bodies,
 }
 
 export type { IssueComment, IssueFields }

package/scripts/issue/issue-release-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 { git_gh_exec } from '#scripts/gh/git-gh-exec'
 import { git_gh_issue_list, MAX_SCANNED } from '#scripts/gh/git-gh-issue-list'
@@ -27,7 +25,6 @@ import { session_cite } from './session-cite'
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
-const ARGV_OFFSET = 2
 const USAGE = 'Usage: josh issue:release <issue-number> [--wait]'
 const NONE = 'none'
 const UNKNOWN_REPO_MESSAGE =
@@ -199,13 +196,6 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	return (await record(request, current)) ? SUCCESS_EXIT_CODE : FAILURE_EXIT_CODE
 }
 
-// `process.exitCode` rather than `process.exit()`, so the report on standard output drains first.
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const issue_release_cli = { find_open, link, run }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export { issue_release_cli, NONE }