@joshuafolkken/kit 1.1514.0 → 1.2114.0

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

@@ -0,0 +1,60 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { session_cite } from '#scripts/issue/session-cite'
+import { issue_priority_raise, type RaiseResult } from './issue-priority-raise'
+
+// `josh issue:priority <N>` — apply `priority:high` to an open issue whose body reached the high
+// floor after filing, as a recurrence's appended cause-loss line does (joshuafolkken/kit#4960).
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const USAGE = 'Usage: josh issue:priority <issue-number>'
+
+const REPORTS: Readonly<Record<RaiseResult, string>> = {
+	raised: 'applied `priority:high` — its body reaches the high floor.',
+	labelled: 'already carries a priority label — left as it is.',
+	below: 'stays below the high floor — no label applied.',
+	unreadable: 'could not be read — no label applied.',
+	failed: 'reaches the high floor, but applying `priority:high` failed.',
+}
+
+const FAILURES: ReadonlySet<RaiseResult> = new Set(['unreadable', 'failed'])
+
+function parse_number(argv: ReadonlyArray<string>): string | undefined {
+	const [first] = argv
+
+	if (first === undefined || argv.length !== 1) return undefined
+
+	return issue_number_shape.ISSUE_NUMBER_PATTERN.test(first) ? first : undefined
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const issue_number = parse_number(argv)
+
+	if (issue_number === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const result = await issue_priority_raise.raise(issue_number)
+	const line = `Issue ${session_cite.issue(issue_number)} ${REPORTS[result]}`
+	const is_failure = FAILURES.has(result)
+
+	if (is_failure) console.error(line)
+	else console.info(line)
+
+	return is_failure ? FAILURE_EXIT_CODE : SUCCESS_EXIT_CODE
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const issue_priority_cli = { run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { issue_priority_cli }

package/scripts/issue/issue-priority-raise.ts

@@ -0,0 +1,55 @@
+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 { z } from 'zod'
+import { PRIORITY_HIGH_LABEL } from './issue-labels'
+import { issue_priority } from './issue-priority'
+
+// joshuafolkken/kit#4960: an open Issue's body can reach the high floor after it was filed — a
+// recurrence appends a cause-loss line to it — and the body edit applies no label. This re-reads the
+// body and applies `priority:high` once its floor is high, as `josh issue:file` would have.
+
+type RaiseResult = 'raised' | 'labelled' | 'below' | 'unreadable' | 'failed'
+
+const read_schema = z.object({
+	labels: z.array(issue_label_schema).optional(),
+	body: z.string().nullish(),
+})
+
+interface LabelsAndBody {
+	labels: ReadonlyArray<string>
+	body: string
+}
+
+async function read_issue(issue_number: string): Promise<LabelsAndBody | undefined> {
+	const raw = await git_gh_command.issue_get_labels_and_body(issue_number)
+	const parsed = raw === undefined ? undefined : parse_json_object_or_undefined(raw, read_schema)
+
+	if (parsed === undefined) return undefined
+
+	return { labels: (parsed.labels ?? []).map((label) => label.name), body: parsed.body ?? '' }
+}
+
+// A priority label already on the issue wins, as a typed one does at filing.
+function decision(read: LabelsAndBody): RaiseResult | undefined {
+	if (issue_priority.is_typed(read.labels)) return 'labelled'
+
+	return issue_priority.floor_of(read.body) === 'high' ? undefined : 'below'
+}
+
+async function raise(issue_number: string): Promise<RaiseResult> {
+	const read = await read_issue(issue_number)
+
+	if (read === undefined) return 'unreadable'
+	const decided = decision(read)
+
+	if (decided !== undefined) return decided
+	const is_applied = await git_gh_command.issue_add_label(issue_number, PRIORITY_HIGH_LABEL)
+
+	return is_applied ? 'raised' : 'failed'
+}
+
+const issue_priority_raise = { raise }
+
+export type { RaiseResult }
+export { issue_priority_raise }

package/scripts/issue/issue-priority.ts

@@ -0,0 +1,282 @@
+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 security-finding or
+// caused-park line sets a high floor (joshuafolkken/kit#4767), and so do cause-loss lines summing to
+// `LOSS_HIGH_MINUTES` (joshuafolkken/kit#4960): each recurrence appends one, so their sum is time the
+// cause lost for certain. A declaration below the floor is refused, and a body that declares none is
+// filed at it. A run-time-shortening Issue's share of the median lane time sets neither a floor nor a
+// refusal (joshuafolkken/kit#4928), and its causing-lane minutes, one lane's estimate, only rank it. 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
+}
+
+// A background line that sets a floor or ranks, its well-formed shape, and the refusal for a malformed one.
+interface FloorLine {
+	prefix: string
+	accepts: (line: string) => boolean
+	problem: string
+}
+
+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`); a reduction is no basis (joshuafolkken/kit#4928).
+const CRITICAL_BASIS = /条件 ?[1-3]/u
+const PLACEHOLDER = /^<.*>$/u
+const LANE_PREFIX = '- 原因のレーン:'
+// The minutes are the lane's net time (`josh lane:net`), the number its Issue.
+const LANE_LINE = /^- 原因のレーン: (?<minutes>\d+(?:\.\d+)?) 分（#[1-9]\d*）$/u
+// The minutes one cause of an overrun lost, ranked ahead of its causing lane's (joshuafolkken/kit#4861).
+const CAUSE_PREFIX = '- 原因の損失:'
+const CAUSE_LINE = /^- 原因の損失: (?<minutes>\d+(?:\.\d+)?) 分$/u
+// The summed cause-loss minutes that set the high floor; provisional, tuned from use.
+const LOSS_HIGH_MINUTES = 30
+const SECURITY_PREFIX = '- セキュリティ:'
+const PARK_PREFIX = '- 原因の park:'
+const PARK_LINE = /^- 原因の park: #[1-9]\d*$/u
+// Queues the Issue behind every undeclared one of its pool (joshuafolkken/kit#5310).
+const ORDER_PREFIX = '- 実施順:'
+const LAST_LINE = '- 実施順: 最後'
+const LEVELS: ReadonlyArray<PriorityLevel> = ['normal', 'high', 'critical']
+const RAISED_LEVELS: ReadonlySet<PriorityLevel> = new Set(['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 one names its condition, a high one its basis (\`issue-template.md\`)`
+
+const LANE_PROBLEM = `state a causing lane under \`${BACKGROUND_HEADING}\` as \`${LANE_PREFIX} <分> 分（#<N>）\` — the lane's net minutes from \`josh lane:net <N>\` (\`issue-template.md\`)`
+
+const CAUSE_PROBLEM = `state a cause's lost minutes under \`${BACKGROUND_HEADING}\` as \`${CAUSE_PREFIX} <分> 分\` (\`issue-template.md\`)`
+
+const SECURITY_PROBLEM = `state a security finding under \`${BACKGROUND_HEADING}\` as \`${SECURITY_PREFIX} <迂回される gate・ガード・権限>\` (\`issue-template.md\`)`
+
+const PARK_PROBLEM = `state a caused park under \`${BACKGROUND_HEADING}\` as \`${PARK_PREFIX} #<N>\` — the Issue the defect parked or whose run it stopped (\`issue-template.md\`)`
+
+const LAST_PROBLEM = `\`${LAST_LINE}\` queues this Issue last, and an urgent or high priority runs it first — keep one of the two (\`issue-template.md\`)`
+
+const HIGH_DECLARATION = '高（セキュリティ … / 原因の park … / 原因の損失 …）'
+
+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)
+}
+
+function background_lines(body: string, prefix: string): ReadonlyArray<string> {
+	return unfenced_lines(body, BACKGROUND_HEADING).filter((line) => line.startsWith(prefix))
+}
+
+// `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 = background_lines(body, DECLARATION_PREFIX)
+
+	if (lines.length === 0) return 'normal'
+
+	return lines.length === 1 ? level_of(lines[0] ?? '') : undefined
+}
+
+function is_lane_line(line: string): boolean {
+	return LANE_LINE.test(line)
+}
+
+function is_cause_line(line: string): boolean {
+	return CAUSE_LINE.test(line)
+}
+
+function is_security_line(line: string): boolean {
+	return has_basis(line.slice(SECURITY_PREFIX.length))
+}
+
+function is_park_line(line: string): boolean {
+	return PARK_LINE.test(line)
+}
+
+// Read for ranking, not a floor: one lane's estimate (joshuafolkken/kit#4960).
+const LANE_RANK_LINE: FloorLine = {
+	prefix: LANE_PREFIX,
+	accepts: is_lane_line,
+	problem: LANE_PROBLEM,
+}
+// H and I of `issue-template.md`'s criteria: either line ranks the Issue high.
+const HIGH_FLOOR_LINES: ReadonlyArray<FloorLine> = [
+	{ prefix: SECURITY_PREFIX, accepts: is_security_line, problem: SECURITY_PROBLEM },
+	{ prefix: PARK_PREFIX, accepts: is_park_line, problem: PARK_PROBLEM },
+]
+
+// Its sum ranks and sets the high floor; a malformed one would count as undeclared without a word.
+const CAUSE_RANK_LINE: FloorLine = {
+	prefix: CAUSE_PREFIX,
+	accepts: is_cause_line,
+	problem: CAUSE_PROBLEM,
+}
+
+// The refusal for the first floor or rank line written in the wrong shape, or `undefined`.
+function malformed_problem(body: string): string | undefined {
+	return [LANE_RANK_LINE, CAUSE_RANK_LINE, ...HIGH_FLOOR_LINES].find((entry) =>
+		background_lines(body, entry.prefix).some((line) => !entry.accepts(line)),
+	)?.problem
+}
+
+// The minutes each background line of `prefix` declares in `pattern`'s shape.
+function declared_minutes(body: string, prefix: string, pattern: RegExp): ReadonlyArray<number> {
+	return background_lines(body, prefix)
+		.map((line) => Number(pattern.exec(line)?.groups?.['minutes']))
+		.filter((value) => Number.isFinite(value))
+}
+
+// The cause-loss lines summed, as each recurrence appends one (joshuafolkken/kit#4928).
+function cause_loss_minutes(body: string): number {
+	return declared_minutes(body, CAUSE_PREFIX, CAUSE_LINE).reduce((sum, value) => sum + value, 0)
+}
+
+function is_marked(body: string): boolean {
+	return HIGH_FLOOR_LINES.some((entry) => background_lines(body, entry.prefix).length > 0)
+}
+
+function has_loss_floor(body: string): boolean {
+	return cause_loss_minutes(body) >= LOSS_HIGH_MINUTES
+}
+
+// The lowest level the Issue may declare: high when it marks a security finding or a caused park, or
+// its cause lost `LOSS_HIGH_MINUTES` or more.
+function floor_of(body: string): PriorityLevel {
+	return is_marked(body) || has_loss_floor(body) ? 'high' : 'normal'
+}
+
+// What sets the body's high floor, named in the refusal of a declaration below it.
+function floor_reason(body: string): string {
+	const loss = `the cause-loss lines' sum of ${String(cause_loss_minutes(body))} minutes (${String(LOSS_HIGH_MINUTES)} or more)`
+	const reasons = [
+		is_marked(body) ? 'the security finding or caused park' : undefined,
+		has_loss_floor(body) ? loss : undefined,
+	]
+
+	return reasons.filter((reason) => reason !== undefined).join(' and ')
+}
+
+// The longest causing lane the body declares, in minutes; `0` when it declares none.
+function lane_minutes(body = ''): number {
+	return Math.max(0, ...declared_minutes(body, LANE_PREFIX, LANE_LINE))
+}
+
+// The minutes the body's cause lost, the rank backlog ordering reads: its cause-loss lines summed,
+// else its causing lane, whose net time bounds the loss from above; `0` when it declares neither.
+function lost_minutes(body = ''): number {
+	const cause = cause_loss_minutes(body)
+
+	return cause > 0 ? cause : lane_minutes(body)
+}
+
+// The level the Issue is filed at: its declaration, else its floor.
+function filed_level(body: string): PriorityLevel | undefined {
+	return background_lines(body, DECLARATION_PREFIX).length === 0
+		? floor_of(body)
+		: declared_level(body)
+}
+
+function is_typed(labels: ReadonlyArray<string>): boolean {
+	return (
+		has_label_name(labels, PRIORITY_CRITICAL_LABEL) || has_label_name(labels, PRIORITY_HIGH_LABEL)
+	)
+}
+
+function floor_problem(body: string, level: PriorityLevel): string | undefined {
+	const floor = floor_of(body)
+
+	if (LEVELS.indexOf(level) >= LEVELS.indexOf(floor)) return undefined
+
+	return `${floor_reason(body)} ranks this Issue \`${floor}\`, above its declared \`${level}\` — declare \`- 優先度: ${HIGH_DECLARATION}\`, or drop the declaration to file at the floor (\`issue-template.md\`)`
+}
+
+// Whether the body declares `LAST_LINE`; any other value is no declaration.
+function is_last(body = ''): boolean {
+	return background_lines(body, ORDER_PREFIX).includes(LAST_LINE)
+}
+
+// The refusal for a body that queues itself last and is filed urgent or high as well, by its
+// declaration or its floor, or `undefined`. `josh issue:lint` reads it, so `josh issue:file` does too.
+function order_problem(body: string): string | undefined {
+	return is_last(body) && RAISED_LEVELS.has(filed_level(body) ?? 'normal')
+		? LAST_PROBLEM
+		: undefined
+}
+
+// Why the filing is refused for its priority, or `undefined`. `typed` is the `--label` list; a typed
+// label is refused only beside a run-last line, as the body's own raise is `order_problem`'s.
+function problem(body: string, typed: ReadonlyArray<string>): string | undefined {
+	if (is_typed(typed)) return is_last(body) ? LAST_PROBLEM : undefined
+	const level = filed_level(body)
+
+	if (level === undefined) return DECLARATION_PROBLEM
+
+	return malformed_problem(body) ?? floor_problem(body, level)
+}
+
+// The labels a new Issue is filed with — the filed level's label added unless one was typed.
+function with_label(labels: ReadonlyArray<string>, body: string): ReadonlyArray<string> {
+	const label = LABELS[filed_level(body) ?? 'normal']
+
+	if (label === undefined || is_typed(labels)) return labels
+
+	return [...labels, label]
+}
+
+const issue_priority = {
+	CAUSE_PREFIX,
+	LANE_PREFIX,
+	LOSS_HIGH_MINUTES,
+	declared_level,
+	floor_of,
+	is_last,
+	is_typed,
+	lane_minutes,
+	lost_minutes,
+	order_problem,
+	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,16 +10,29 @@ 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
-// `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.
+// First, an issue whose body declares it runs last (`issue_priority.is_last`) follows every
+// undeclared one, so a wide-reach upgrade queues behind the rest of its pool (joshuafolkken/kit#5310);
+// declared ones rank among themselves by the keys below.
+//
+// Then, in order: `priority:critical`, then `priority:high`, then a defect on the verification path (`bug` with `run:solo`, or
+// `route:interrupt`), then the minutes its cause lost (`issue_priority.lost_minutes`: the body's
+// cause-loss lines summed over its recurrences (joshuafolkken/kit#4928), else its causing-lane line,
+// so causes of one lane are told apart (joshuafolkken/kit#4861); `0` when neither is declared, so an
+// undeclared issue follows every declared one of its priority), then the minutes a week its declared
+// speed-up saves (`expected_effect_lint.weekly_minutes`, on the same minute scale; `0` when undeclared,
+// so a measured time-saver runs ahead of an unmeasured feature (joshuafolkken/kit#5302)), 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.
 //
 // **`run:solo` alone is not a key.** It means "runs alone", not "runs first": tidying that only touches
 // the verification path carries it too, and a low-priority one is not owed a place ahead of the queue.
 // Only a defect on that path is, because `backlogrun-lanes.md` holds a batch until it has merged.
 
 interface RankRow {
+	is_last: boolean
 	labels: ReadonlyArray<string>
+	lost_minutes: number
+	gain_minutes: number
 	dependents: number
 }
 
@@ -35,6 +49,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)
 }
@@ -45,11 +63,16 @@ function is_verification_defect(labels: ReadonlyArray<string>): boolean {
 	return has_label_name(labels, BUG_LABEL) && has_label_name(labels, RUN_SOLO_LABEL)
 }
 
-// Negated so that the larger value sorts first under an ascending comparison.
+// Negated so that the larger value sorts first under an ascending comparison; `is_last` alone is not,
+// so a declared row sorts last.
 function keys_of(row: RankRow): ReadonlyArray<number> {
 	return [
+		flag(row.is_last),
+		-flag(is_critical(row.labels)),
 		-flag(is_priority(row.labels)),
 		-flag(is_verification_defect(row.labels)),
+		-row.lost_minutes,
+		-row.gain_minutes,
 		-row.dependents,
 	]
 }

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

@@ -1,5 +1,4 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
+import { gh_author_association } from '#scripts/gh/gh-author-association'
 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,13 +26,12 @@ 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`
 // process, and an unbounded fan-out is answered with secondary rate limiting rather than with issues.
 const READ_CONCURRENCY = 8
-const ISSUE_FIELDS = 'title,state,body'
+const ISSUE_FIELDS = `title,state,body,${gh_author_association.AUTHOR_FIELDS}`
 const FAILURE_TERMS = { success_kind: 'issue', misreading: 'the issue is empty' } as const
 
 interface IssueContent {
@@ -46,8 +44,15 @@ type NumberResult = { kind: 'issue'; content: IssueContent } | { kind: ReadFailu
 // The formatted block for one issue, or the failure kind — what `run:prep` bundles beside the state
 // and the dependency-update scope. It reuses this file's read and the shared
 // `format_issue` rather than reproducing either, so the two `gh` reads and the block shape stay
-// single-sourced here.
-type BlockRead = { kind: 'ok'; block: string } | { kind: ReadFailureKind }
+// single-sourced here. `trust` carries what the read already decided about its authors, so
+// `run:entry` gates an untrusted issue without a second read (joshuafolkken/kit#4663). `undefined` is
+// a read that failed — a write-access lookup, or the comment listing — never an untrusted author (#4703).
+interface BlockTrust {
+	is_body_trusted: boolean | undefined
+	has_trusted_comment: boolean | undefined
+}
+
+type BlockRead = { kind: 'ok'; block: string; trust: BlockTrust } | { kind: ReadFailureKind }
 
 interface IssueReport {
 	issue_number: string
@@ -78,11 +83,27 @@ async function read_issue(issue_number: string): Promise<NumberResult> {
 
 	if (read.kind !== 'read') return { kind: read.kind }
 
-	const fields = issue_read.parse_issue_fields(read.json)
+	const fields = await issue_read.parse_issue_fields(read.json)
 
 	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 } }
+}
+
+// A trusted comment is an answer whatever else failed; without one, a listing or a lookup that failed
+// leaves the question unanswered rather than answered no.
+function has_trusted_comment(
+	comments: ReadonlyArray<IssueComment> | undefined,
+): boolean | undefined {
+	if (comments?.some((comment) => comment.is_trusted === true) === true) return true
+
+	if (comments === undefined || comments.some((comment) => comment.is_trusted === undefined)) {
+		return undefined
+	}
+
+	return false
 }
 
 // One issue's block for a caller that wants the text rather than the printing — `run:prep` composes it
@@ -94,8 +115,12 @@ async function read_block(issue_number: string): Promise<BlockRead> {
 	if (result.kind !== 'issue') return { kind: result.kind }
 
 	const { fields, comments } = result.content
+	const trust = {
+		is_body_trusted: fields.is_body_trusted,
+		has_trusted_comment: has_trusted_comment(comments),
+	}
 
-	return { kind: 'ok', block: issue_read.format_issue(issue_number, fields, comments) }
+	return { kind: 'ok', block: issue_read.format_issue(issue_number, fields, comments), trust }
 }
 
 async function read_all(issue_numbers: ReadonlyArray<string>): Promise<ReadonlyArray<IssueReport>> {
@@ -134,10 +159,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 +166,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 type { BlockRead, BlockTrust }
 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))
+}