@joshuafolkken/kit 1.1514.0 → 1.1784.0

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 }

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

@@ -0,0 +1,13 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { issue_release_cli } from './issue-release-cli'
+
+// The `josh issue:release` entry, kept apart from `issue-release-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). `process.exitCode` rather than `process.exit()`, so the report on standard
+// output drains first.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await issue_release_cli.run(process.argv.slice(ARGV_OFFSET))
+}

package/scripts/issue/issue-release.ts

@@ -1,4 +1,5 @@
-import { DEPTH_0_LABEL, RELEASE_LABEL } from './issue-labels'
+import { json_value } from '#scripts/lib/json-value'
+import { RELEASE_LABEL } from './issue-labels'
 
 // The decisions behind `josh issue:release`, kept apart from the command
 // that reads the network so each is a pure answer a test can pin. An Issue whose change reaches a
@@ -20,14 +21,9 @@ function is_listing_row(value: unknown): value is ListingRow {
 // release Issue at a time; were a person to open a second, the oldest is the one the next release
 // closes, so it is the one every new blocker joins.
 function open_release_of(json: string): number | undefined {
-	try {
-		const parsed: unknown = JSON.parse(json)
-		const rows = Array.isArray(parsed) ? parsed.filter((row) => is_listing_row(row)) : []
-
-		return rows.length === 0 ? undefined : Math.min(...rows.map((row) => row.number))
-	} catch {
-		return undefined
-	}
+	const rows = (json_value.parse_array(json) ?? []).filter((row) => is_listing_row(row))
+
+	return rows.length === 0 ? undefined : Math.min(...rows.map((row) => row.number))
 }
 
 function title_of(repo: string): string {
@@ -51,9 +47,8 @@ function body_of(repo: string): string {
 	].join('\n')
 }
 
-// The release label and a depth: the subject of a release is what a consumer touches.
-// Never `auto-ok`.
-const RELEASE_LABELS: ReadonlyArray<string> = [RELEASE_LABEL, DEPTH_0_LABEL]
+// The release label alone — never `auto-ok`.
+const RELEASE_LABELS: ReadonlyArray<string> = [RELEASE_LABEL]
 
 const issue_release = { RELEASE_LABELS, open_release_of, title_of, body_of }
 

package/scripts/issue/issue-sample-gate.ts

@@ -0,0 +1,192 @@
+import { read_pull } from '#scripts/gh/git-gh-pr-read'
+import { git_closes_keyword } from '#scripts/git/git-closes-keyword'
+import { lane_ledger } from '#scripts/lane/lane-ledger'
+import { issue_cite } from './issue-cite'
+import { markdown_section } from './markdown-section'
+
+// joshuafolkken/kit#4414: a follow-up measurement waits on samples, not on the calendar — a busy day
+// collects enough merges before a dated start time, a quiet one not even after it. The body names the
+// pull request whose effect it measures and how many merges the lane ledger must record after that
+// pull request merged; the pickup holds the issue until then. The pull request's own merge is not a
+// sample: `run:merge` records it, keyed by the issue it closes, after GitHub stamps `merged_at`.
+//
+// The readers that hold an issue back are synchronous and see only the body, so the one network fact
+// the wait needs — when the pull request merged — is read ahead by `prime`, once per pull request per
+// process, wherever bodies first arrive. A body nobody primed reads as waiting: offering it early is
+// the defect this guards, and the next primed read releases it.
+
+const BACKGROUND_HEADING = '## 背景'
+const PREFIX = '- 実施可能条件:'
+const CONDITION_PATTERN = /^#(?<pr>[1-9]\d*) のマージ後 (?<count>[1-9]\d*) マージ$/u
+const VALUE_FORMAT = '#<PR> のマージ後 <K> マージ'
+const DECLARATION = `${PREFIX} ${VALUE_FORMAT}`
+const MALFORMED = `\`${PREFIX}\` must read \`${VALUE_FORMAT}\` with K at least 1`
+
+interface Condition {
+	pr: number
+	count: number
+}
+
+type SampleWait =
+	| { kind: 'unread'; pr: number }
+	| { kind: 'unmerged'; pr: number }
+	| { kind: 'short'; pr: number; counted: number; needed: number }
+
+// One pull request as read: `merged_at` absent is one found unmerged, read again as it may merge since.
+// `closes` is the issue its body closes, whose ledger merge is the pull request's own.
+interface PullRead {
+	merged_at: string | undefined
+	closes: number | undefined
+}
+
+interface PrimePorts {
+	pull: (pr: number) => Promise<PullRead>
+	ledger_path: () => Promise<string | undefined>
+}
+
+interface LedgerState {
+	path: string | undefined
+}
+
+// A pull request with no entry was never read.
+
+const pull_by_number = new Map<number, PullRead>()
+const ledger: LedgerState = { path: undefined }
+
+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 declared condition, or `undefined` when there is none or it does not parse — a malformed one is
+// refused by `issue:lint`, and holding a hand-edited one forever would lose the issue silently.
+function condition_of(body = ''): Condition | undefined {
+	const groups = CONDITION_PATTERN.exec(declared_value(body) ?? '')?.groups
+
+	if (groups === undefined) return undefined
+
+	return { pr: Number(groups['pr']), count: Number(groups['count']) }
+}
+
+// The number the declared condition cites, or `undefined` when there is none or it does not parse.
+function cited_number(body: string): number | undefined {
+	return condition_of(body)?.pr
+}
+
+function problems(body: string): ReadonlyArray<string> {
+	const value = declared_value(body)
+
+	return value === undefined || CONDITION_PATTERN.test(value) ? [] : [MALFORMED]
+}
+
+async function read_source(pr: number): Promise<PullRead> {
+	const pull = await read_pull(pr)
+	const closes = git_closes_keyword.parse_closes_issue_number(pull.body ?? undefined)
+
+	return {
+		merged_at: pull.merged_at ?? undefined,
+		closes: closes === undefined ? undefined : Number(closes),
+	}
+}
+
+const DEFAULT_PORTS: PrimePorts = { pull: read_source, ledger_path: lane_ledger.target }
+
+// A failed read stays unread, so the next prime asks again.
+async function remember(pr: number, ports: PrimePorts): Promise<void> {
+	try {
+		pull_by_number.set(pr, await ports.pull(pr))
+	} catch {
+		pull_by_number.delete(pr)
+	}
+}
+
+function is_merge_known(pr: number): boolean {
+	return pull_by_number.get(pr)?.merged_at !== undefined
+}
+
+// Reads ahead what the bodies' conditions need. Nothing is read for bodies that declare none.
+async function prime(
+	bodies: ReadonlyArray<string | undefined>,
+	ports: PrimePorts = DEFAULT_PORTS,
+): Promise<void> {
+	const unread = bodies
+		.map((body) => condition_of(body)?.pr)
+		.filter((pr): pr is number => pr !== undefined && !is_merge_known(pr))
+
+	if (unread.length === 0) return
+
+	ledger.path = await ports.ledger_path()
+	await Promise.all(
+		[...new Set(unread)].map(async (pr) => {
+			await remember(pr, ports)
+		}),
+	)
+}
+
+function merges_after({ merged_at, closes }: PullRead & { merged_at: string }): number {
+	if (ledger.path === undefined) return 0
+
+	const since = Date.parse(merged_at)
+
+	return lane_ledger
+		.read_entries(ledger.path)
+		.filter(
+			(entry) =>
+				entry.kind === lane_ledger.KIND.MERGE &&
+				entry.issue !== closes &&
+				Date.parse(entry.at) > since,
+		).length
+}
+
+// What the body still waits on, or `undefined` when it declares nothing or has its samples.
+function wait_of(body?: string): SampleWait | undefined {
+	const condition = condition_of(body)
+
+	if (condition === undefined) return undefined
+
+	const { pr, count } = condition
+	const pull = pull_by_number.get(pr)
+
+	if (pull === undefined) return { kind: 'unread', pr }
+
+	const { merged_at, closes } = pull
+
+	if (merged_at === undefined) return { kind: 'unmerged', pr }
+
+	const counted = merges_after({ merged_at, closes })
+
+	return counted >= count ? undefined : { kind: 'short', pr, counted, needed: count }
+}
+
+// Why the body waits, for a reader that cites the issue itself.
+function reason_of(wait: SampleWait): string {
+	const pr = issue_cite.plain(wait.pr)
+
+	if (wait.kind === 'unread') return `until the merge of ${pr} is read`
+	if (wait.kind === 'unmerged') return `until ${pr} merges`
+
+	return `${String(wait.counted)}/${String(wait.needed)} merges after ${pr}`
+}
+
+function reset(): void {
+	pull_by_number.clear()
+	ledger.path = undefined
+}
+
+const issue_sample_gate = {
+	DECLARATION,
+	cited_number,
+	prime,
+	problems,
+	reason_of,
+	reset,
+	wait_of,
+}
+
+export type { PrimePorts, SampleWait }
+export { issue_sample_gate }

package/scripts/issue/issue-sample-source.ts

@@ -0,0 +1,76 @@
+import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
+import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { git_gh_issue_rest } from '#scripts/gh/git-gh-issue-rest'
+import { issue_closing_pr } from './issue-closing-pr'
+import { issue_sample_gate } from './issue-sample-gate'
+import { session_cite } from './session-cite'
+
+// joshuafolkken/kit#4460: the start condition cites the pull request whose merge it waits on. An issue
+// number passes the format check, then reads as a pull request that is never found, so the issue waits
+// forever. The filing reads what the number names and refuses an issue, citing the merged pull request
+// that closed it when there is one. An unreadable number passes — an outage is no reason to stop.
+//
+// `repo` is the filing's target, `undefined` for this checkout. The closing pull request is looked up
+// only here: `issue_closing_pr` reads this checkout's timeline, so a foreign target gets the plain hint.
+
+interface SourcePorts {
+	is_pull: (number: number, repo: string | undefined) => Promise<boolean | undefined>
+	closing_pr: (issue: number) => Promise<string | undefined>
+}
+
+async function read_is_pull(
+	number: number,
+	repo: string | undefined,
+): Promise<boolean | undefined> {
+	try {
+		const json = await git_gh_exec.exec_gh_api({
+			path: git_gh_api_path.issue_api_path(String(number), repo),
+		})
+
+		return git_gh_issue_rest.is_pull_request(git_gh_issue_rest.parse_rest_issue(json))
+	} catch {
+		return undefined
+	}
+}
+
+// The closing pull request's number, read off the URL `read_closing_pr` answers.
+async function read_closing_pr(issue: number): Promise<string | undefined> {
+	const url = await issue_closing_pr.read_closing_pr(String(issue))
+
+	return url?.slice(url.lastIndexOf('/') + 1)
+}
+
+const DEFAULT_PORTS: SourcePorts = { is_pull: read_is_pull, closing_pr: read_closing_pr }
+
+async function hint_of(
+	issue: number,
+	repo: string | undefined,
+	ports: SourcePorts,
+): Promise<string> {
+	const closing = repo === undefined ? await ports.closing_pr(issue) : undefined
+
+	if (closing === undefined) return 'cite the pull request whose merge it waits on'
+
+	return `cite the pull request that closed it: ${session_cite.issue(closing)}`
+}
+
+// The refusal for a condition citing an issue, or `undefined` when it cites a pull request, cites
+// nothing, or cannot be read.
+async function problem(
+	body: string,
+	repo?: string,
+	ports: SourcePorts = DEFAULT_PORTS,
+): Promise<string | undefined> {
+	const number = issue_sample_gate.cited_number(body)
+
+	if (number === undefined || (await ports.is_pull(number, repo)) !== false) return undefined
+	const cited = session_cite.issue(number, undefined, repo)
+	const hint = await hint_of(number, repo, ports)
+
+	return `\`- 実施可能条件:\` cites ${cited}, an issue, not a pull request — ${hint}`
+}
+
+const issue_sample_source = { problem }
+
+export type { SourcePorts }
+export { issue_sample_source }

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

@@ -1,6 +1,4 @@
-#!/usr/bin/env tsx
 import { readFile } from 'node:fs/promises'
-import { fileURLToPath } from 'node:url'
 import { epic_audit_logic } from '#scripts/epic/epic-audit'
 import { epic_bundle, type BacklogIssue, type BundleDecision } from '#scripts/epic/epic-bundle'
 import { epic_bundle_cli } from '#scripts/epic/epic-bundle-cli'
@@ -34,7 +32,6 @@ const { CLOSED_CEILING_LINE, CLOSED_UNREADABLE_LINE, read_recently_closed, warn_
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
-const ARGV_OFFSET = 2
 const SCORE_DIGITS = 2
 const USAGE = 'Usage: josh issue:scout "<title>" [--body "<draft>" | --body-file <path>]'
 const UNKNOWN_REPO_MESSAGE =
@@ -394,12 +391,6 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	return await report(args, repo)
 }
 
-// `process.exitCode` rather than `process.exit()`: the answer goes to standard output and a write to
-// a pipe is asynchronous on macOS, so exiting can tear the process down before it drains.
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const issue_scout_cli = {
 	USAGE,
 	UNKNOWN_REPO_MESSAGE,
@@ -415,7 +406,5 @@ const issue_scout_cli = {
 	run,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export type { ScoutArguments, ScoutOutcome }
 export { issue_scout_cli }

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

@@ -0,0 +1,14 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { issue_scout_cli } from './issue-scout-cli'
+
+// The `josh issue:scout` entry, kept apart from `issue-scout-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). `process.exitCode` rather than `process.exit()`: the answer goes to
+// standard output and a write to a pipe is asynchronous on macOS, so exiting can tear the process
+// down before it drains.
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	const ARGV_OFFSET = 2
+
+	process.exitCode = await issue_scout_cli.run(process.argv.slice(ARGV_OFFSET))
+}

package/scripts/issue/issue-state-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 { IssueReadReason } from '#scripts/gh/git-gh-issue-read'
 import { issue_number_shape } from '#scripts/issue/issue-number-shape'
@@ -29,7 +27,6 @@ import { issue_state, type IssueState } from './issue-state'
 // are told apart here and neither is a state.
 
 const FAILURE_EXIT_CODE = 1
-const ARGV_OFFSET = 2
 const USAGE = 'Usage: josh issue:state <issue-number> [<issue-number> ...] [--repo <owner/repo>]'
 // A blank line between the blocks of a multi-number report, so a person sees where one issue ends
 // while a reader matching `issue: ` still finds each block by its first line.
@@ -172,21 +169,14 @@ 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_state_cli = {
 	READ_CONCURRENCY,
 	STATE_FIELDS,
 	USAGE,
-	main,
 	parse_request,
 	read_issue,
 	run,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export type { StateRead }
 export { issue_state_cli }

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

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