@joshuafolkken/kit 1.872.0

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

@@ -0,0 +1,60 @@
+#!/usr/bin/env tsx
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { behavior_change_lint } from './behavior-change-lint'
+import { issue_lint } from './issue-lint'
+
+// `josh issue:lint <path>` — read an Issue body from a file and print `ok`, or every template problem
+// one per line, exiting non-zero (joshuafolkken/kit#2123). It reads a path rather than stdin so it can
+// lint a body written to a file before the `gh api … issues` call that files it. A body that declares
+// itself a behavior-change Issue is additionally held to the firing-point, baseline and reproduction
+// rules (joshuafolkken/kit#2212, joshuafolkken/kit#2353).
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const OK_MESSAGE = 'ok'
+const USAGE = 'Usage: josh issue:lint <path-to-issue-body>'
+
+// Every problem a body has: the four base template headings it lacks, then the behavior-change
+// problems (empty for an Issue that does not declare itself one).
+function problems(body: string): ReadonlyArray<string> {
+	const missing = issue_lint.missing_headings(body).map((heading) => `missing heading: ${heading}`)
+
+	return [...missing, ...behavior_change_lint.problems(body)]
+}
+
+function report(found: ReadonlyArray<string>): number {
+	if (found.length === 0) {
+		console.info(OK_MESSAGE)
+
+		return SUCCESS_EXIT_CODE
+	}
+
+	console.error(found.map((problem) => `✖ ${problem}`).join('\n'))
+
+	return FAILURE_EXIT_CODE
+}
+
+async function run(body_path: string | undefined): Promise<number> {
+	if (body_path === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const body = await readFile(body_path, 'utf8')
+
+	return report(problems(body))
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv[0])
+}
+
+const issue_lint_cli = { run, OK_MESSAGE, USAGE }
+
+const ARGV_OFFSET = 2
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { issue_lint_cli }

package/scripts/issue/issue-lint.ts

@@ -0,0 +1,26 @@
+import { markdown_section } from './markdown-section'
+
+// The Issue body template's four headings (`prompts/collaboration-workflow/issue-template.md`) are a
+// fixed shape, but unlike an epic — which `josh epic:check` verifies — nothing checks that a filed
+// Issue carries them. This reports the ones a body is missing (joshuafolkken/kit#2123). The headings
+// are the single source's, and the document test pins that these match it.
+const REQUIRED_HEADINGS: ReadonlyArray<string> = [
+	'## 背景',
+	'## 現象',
+	'## 期待結果',
+	'## 受け入れ条件',
+]
+
+// The required headings a body lacks, in template order; an empty array is a conforming body. A heading
+// is present when a line is exactly it (`markdown_section.has_line`) — one mentioned inside a sentence
+// is not the section heading.
+function missing_headings(body: string): ReadonlyArray<string> {
+	return REQUIRED_HEADINGS.filter((heading) => !markdown_section.has_line(body, heading))
+}
+
+const issue_lint = {
+	missing_headings,
+	REQUIRED_HEADINGS,
+}
+
+export { issue_lint }

package/scripts/issue/issue-logic.ts

@@ -0,0 +1,50 @@
+/**
+ * CJK Unified Ideographs range + Hiragana + Katakana + CJK symbols.
+ * Used to detect non-English issue titles that need translation.
+ */
+const CJK_PATTERN = /[\u{3000}-\u{9FFF}\u{F900}-\u{FAFF}\u{AC00}-\u{D7AF}\u{20000}-\u{2FA1F}]/u
+
+const MAX_BRANCH_SLUG_LENGTH = 50
+
+function has_cjk(text: string): boolean {
+	return CJK_PATTERN.test(text)
+}
+
+function slugify(text: string): string {
+	const slug = text
+		.toLowerCase()
+		.normalize('NFKD')
+		.replaceAll(/[^a-z0-9]+/gu, '-')
+		.replaceAll(/-+/gu, '-')
+		.replaceAll(/(^-)|(-$)/gu, '')
+
+	if (slug.length === 0) return 'update'
+
+	return slug.length > MAX_BRANCH_SLUG_LENGTH
+		? slug.slice(0, MAX_BRANCH_SLUG_LENGTH).replace(/-$/u, '')
+		: slug
+}
+
+function suggest_branch_name(issue_number: number, title: string): string {
+	return `${String(issue_number)}-${slugify(title)}`
+}
+
+interface IssuePrepResult {
+	number: number
+	title: string
+	is_cjk: boolean
+	suggested_branch: string
+}
+
+function prepare(issue_number: number, title: string): IssuePrepResult {
+	return {
+		number: issue_number,
+		title,
+		is_cjk: has_cjk(title),
+		suggested_branch: suggest_branch_name(issue_number, title),
+	}
+}
+
+const issue_logic = { has_cjk, slugify, suggest_branch_name, prepare }
+
+export { issue_logic }

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

@@ -0,0 +1,190 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { git_gh_command } from '#scripts/git/git-gh-command'
+import { bounded_pool } from '#scripts/lib/bounded-pool'
+import { issue_read, type IssueComment, type IssueFields } from './issue-read'
+
+// `josh issue:read <N> [<N> ...]` — the body *and* the comments of every issue named, in one call
+// (joshuafolkken/kit#1715).
+//
+// It replaces the two `gh api` reads `.claude/skills/workflow-commands/SKILL.md` §2g tells an agent
+// to type per issue. Measured over four recorded `backlogrun` parents, `issue bookkeeping` was the
+// largest single contributor to the parent's turn count — 110 of 414 turns, 26.6% — and one issue
+// read at a time was its dominant shape: 19 `…/issues/<N>` calls and 5 `…/comments` calls, each its
+// own turn. A parent's cost grows as n²/2 in its own request count, so a turn removed there is worth
+// more than a turn removed anywhere else in the batch.
+//
+// **No `--repo`, deliberately.** The comment listing is `issue_list_comments`, which reads the
+// repository it runs in; a cross-repository read stays the two `gh api` calls it always was, and
+// inventing a repository-aware comment reader here would be a second deliverable. Naming the flag and
+// then ignoring it would be worse than not having it — a confident block for a *different*
+// repository's issue of the same number is the misread `issue:state`'s own `--repo` exists to
+// prevent.
+//
+// **A failed read is never printed as an issue**, and neither is a failed comment listing printed as
+// "no comments" — the block says which of the two it holds, because §2g's rule is that the later text
+// wins, and a comment nobody read cannot win anything.
+
+const SUCCESS_EXIT_CODE = 0
+const FAILURE_EXIT_CODE = 1
+const ARGV_OFFSET = 2
+const ISSUE_NUMBER_PATTERN = /^[1-9]\d*$/u
+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'
+
+type ReadFailureKind = 'missing' | 'unreadable'
+
+interface IssueContent {
+	fields: IssueFields
+	comments: ReadonlyArray<IssueComment> | undefined
+}
+
+type NumberResult = { kind: 'issue'; content: IssueContent } | { kind: ReadFailureKind }
+
+// The formatted block for one issue, or the failure kind — what `run:prep` bundles beside the state
+// and the dependency-update scope (joshuafolkken/kit#1978). 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 }
+
+interface IssueReport {
+	issue_number: string
+	result: NumberResult
+}
+
+// A token that is not an issue number refuses the whole invocation rather than being dropped.
+// Dropping it answers fewer numbers than were asked for and still exits zero — and nothing in the
+// output then says a number went unanswered. `#1262` copied out of a table is exactly that token.
+function parse_numbers(argv: ReadonlyArray<string>): ReadonlyArray<string> | undefined {
+	const numbers = argv.filter((argument) => ISSUE_NUMBER_PATTERN.test(argument))
+
+	if (numbers.length === 0 || numbers.length !== argv.length) return undefined
+
+	// In the order they were typed, with a repeat dropped: repeating a number spends a second read on
+	// an answer already in hand and prints a second block a caller counting rows counts twice.
+	return [...new Set(numbers)]
+}
+
+function report_failure(kind: ReadFailureKind, issue_number: string): void {
+	if (kind === 'missing') {
+		console.error(`✖ issue #${issue_number} does not resolve — check the number and the repository`)
+	} else {
+		console.error(
+			`✖ could not read issue #${issue_number} — a rate limit, expired auth, or a dropped connection. This is not "the issue is empty"`,
+		)
+	}
+}
+
+// The comments are read beside the fields rather than after them: the two requests need nothing from
+// one another, and reading them in sequence would put back one of the two round trips this command
+// exists to remove.
+async function read_issue(issue_number: string): Promise<NumberResult> {
+	const [read, comments_json] = await Promise.all([
+		git_gh_command.issue_view_json_classified(issue_number, ISSUE_FIELDS),
+		git_gh_command.issue_list_comments(issue_number),
+	])
+
+	if (read.kind !== 'read') return { kind: read.kind }
+
+	const fields = 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) } }
+}
+
+// One issue's block for a caller that wants the text rather than the printing — `run:prep` composes it
+// with the state block and the dependency-update line. A failed read is returned as its kind, never as
+// an empty block, so §2g's "a comment nobody read cannot win anything" holds through the bundle too.
+async function read_block(issue_number: string): Promise<BlockRead> {
+	const result = await read_issue(issue_number)
+
+	if (result.kind !== 'issue') return { kind: result.kind }
+
+	const { fields, comments } = result.content
+
+	return { kind: 'ok', block: issue_read.format_issue(issue_number, fields, comments) }
+}
+
+async function read_all(issue_numbers: ReadonlyArray<string>): Promise<ReadonlyArray<IssueReport>> {
+	return await bounded_pool.bounded_map(issue_numbers, READ_CONCURRENCY, async (issue_number) => ({
+		issue_number,
+		result: await read_issue(issue_number),
+	}))
+}
+
+// `[]` for a number that produced no issue, so one unresolvable number costs the others nothing.
+function issue_blocks(report: IssueReport): ReadonlyArray<string> {
+	if (report.result.kind !== 'issue') return []
+
+	const { fields, comments } = report.result.content
+
+	return [issue_read.format_issue(report.issue_number, fields, comments)]
+}
+
+function print_issues(reports: ReadonlyArray<IssueReport>): void {
+	const blocks = reports.flatMap((report) => issue_blocks(report))
+
+	if (blocks.length === 0) return
+
+	console.info(blocks.join(BLOCK_SEPARATOR))
+}
+
+function report_one_failure(report: IssueReport): boolean {
+	if (report.result.kind === 'issue') return false
+
+	report_failure(report.result.kind, report.issue_number)
+
+	return true
+}
+
+// Every number that produced no issue is named, so a caller is told which ones it has no answer for
+// rather than being left to subtract the printed blocks from what it asked.
+function report_failures(reports: ReadonlyArray<IssueReport>): number {
+	let has_failure = false
+
+	for (const report of reports) {
+		has_failure = report_one_failure(report) || has_failure
+	}
+
+	return has_failure ? FAILURE_EXIT_CODE : SUCCESS_EXIT_CODE
+}
+
+async function run(argv: ReadonlyArray<string>): Promise<number> {
+	const issue_numbers = parse_numbers(argv)
+
+	if (issue_numbers === undefined) {
+		console.error(USAGE)
+
+		return FAILURE_EXIT_CODE
+	}
+
+	const reports = await read_all(issue_numbers)
+
+	print_issues(reports)
+
+	return report_failures(reports)
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	process.exitCode = await run(argv)
+}
+
+const issue_read_cli = {
+	BLOCK_SEPARATOR,
+	ISSUE_FIELDS,
+	USAGE,
+	main,
+	parse_numbers,
+	read_block,
+	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.ts

@@ -0,0 +1,145 @@
+import { parse_json_object_safe, read_json_listing } from '#scripts/git/parse-json-array'
+import { z } from 'zod'
+
+// The block `josh issue:read` prints for one issue, kept apart from the reading and the printing so
+// the shape of the report is decided by one pure function — the seam `issue-state.ts` already has
+// (joshuafolkken/kit#1715).
+//
+// **It exists because reading one issue costs a parent two turns.** `.claude/skills/workflow-commands/SKILL.md`
+// §2g requires the body *and* the comments, since a decision recorded after the body was written
+// lives only in a comment; typed by hand that is `gh api repos/{owner}/{repo}/issues/<N>` followed by
+// `gh api repos/{owner}/{repo}/issues/<N>/comments`. Measured over four recorded `backlogrun`
+// parents, `issue bookkeeping` was the single largest contributor to the parent's turn count — 110 of
+// 414 turns, 26.6% — and one-issue-at-a-time `gh api` reads were its dominant shape. A parent's cost
+// grows as n²/2 in its own request count (joshuafolkken/kit#1567), so those turns are the
+// distribution this collapses.
+//
+// **The comments are never silently absent.** A listing that could not be read prints a line saying
+// so, because a block showing no comment where the read failed is exactly the misread §2g exists to
+// prevent: the agreement in force would be taken from a body a comment had already overturned.
+
+const ISSUE_LABEL = 'issue: '
+const TITLE_LABEL = 'title: '
+const STATE_LABEL = 'state: '
+const NO_BODY = '(no body)'
+const NO_COMMENTS = '(no comments)'
+// **Not `(no comments)`.** The two are opposite answers — one is a read that found nothing, the other
+// is nothing having been read — and a caller acting on the first when it holds the second decides
+// from a body a comment may already have superseded.
+const COMMENTS_UNREADABLE = '(comments could not be read — this is not "there are no comments")'
+const COMMENT_SEPARATOR = '\n\n'
+const SECTION_SEPARATOR = '\n\n'
+const COMMENT_HEADING = 'comment by '
+const AT = ' at '
+
+const issue_fields_schema = z.looseObject({
+	title: z.string(),
+	state: z.string(),
+	body: z.string().optional(),
+})
+
+const comment_schema = z.looseObject({
+	user: z.looseObject({ login: z.string() }).optional(),
+	created_at: z.string().optional(),
+	body: z.string().optional(),
+})
+
+interface IssueFields {
+	title: string
+	state: string
+	body: string
+}
+
+interface IssueComment {
+	author: string
+	created_at: string
+	body: string
+}
+
+const UNKNOWN_AUTHOR = '(unknown)'
+const UNKNOWN_TIME = '(undated)'
+
+// `undefined` for anything that is not an issue read — malformed JSON, and equally a well-formed
+// response carrying something else (`{"message":"API rate limit exceeded"}`). Printing either as an
+// issue is what this command exists to prevent, the same rule `issue-state.ts` states for its own
+// parse.
+function parse_issue_fields(json: string): IssueFields | undefined {
+	try {
+		const parsed = parse_json_object_safe(json, issue_fields_schema)
+
+		if (parsed === undefined) return undefined
+
+		return { title: parsed.title, state: parsed.state, body: parsed.body ?? '' }
+	} catch {
+		return undefined
+	}
+}
+
+function to_comment(raw: z.infer<typeof comment_schema>): IssueComment {
+	return {
+		author: raw.user?.login ?? UNKNOWN_AUTHOR,
+		created_at: raw.created_at ?? UNKNOWN_TIME,
+		body: raw.body ?? '',
+	}
+}
+
+// `undefined` — never `[]` — when the listing could not be read, so the block above can say which of
+// the two answers it holds.
+//
+// **Through `read_json_listing`, which is what already reads this very endpoint** — the epic
+// auto-close parses `issue_list_comments`'s output with it. Malformed JSON, a well-formed response
+// carrying something else (`{"message":"API rate limit exceeded"}`) and a schema mismatch are three
+// 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 {
+	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
+}
+
+function format_comment(comment: IssueComment): string {
+	const heading = `${COMMENT_HEADING}${comment.author}${AT}${comment.created_at}`
+
+	return `${heading}\n${comment.body}`
+}
+
+function format_comments(comments: ReadonlyArray<IssueComment> | undefined): string {
+	if (comments === undefined) return COMMENTS_UNREADABLE
+	if (comments.length === 0) return NO_COMMENTS
+
+	return comments.map((comment) => format_comment(comment)).join(COMMENT_SEPARATOR)
+}
+
+// The number, the title, the state, the body and every comment, in one block. **The number is on the
+// block rather than left to position**, for the reason `issue-state.ts` gives: a batch read drops the
+// numbers that resolve to nothing, and a positional reading then attributes every block after the gap
+// to the wrong issue.
+function format_issue(
+	issue_number: string,
+	fields: IssueFields,
+	comments: ReadonlyArray<IssueComment> | undefined,
+): string {
+	const heading = `${ISSUE_LABEL}${issue_number}\n${TITLE_LABEL}${fields.title}\n${STATE_LABEL}${fields.state}`
+	const body = fields.body === '' ? NO_BODY : fields.body
+
+	return [heading, body, format_comments(comments)].join(SECTION_SEPARATOR)
+}
+
+const issue_read = {
+	ISSUE_LABEL,
+	TITLE_LABEL,
+	STATE_LABEL,
+	NO_BODY,
+	NO_COMMENTS,
+	COMMENTS_UNREADABLE,
+	COMMENT_HEADING,
+	format_issue,
+	parse_comments,
+	parse_issue_fields,
+}
+
+export type { IssueComment, IssueFields }
+export { issue_read }