@joshuafolkken/kit 1.2116.0 → 1.3000.0

package/scripts/review/disposition-batch-filing.ts

@@ -0,0 +1,150 @@
+import { mkdirSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { issue_body_keys } from '#scripts/issue/issue-body-keys'
+import { issue_cite } from '#scripts/issue/issue-cite'
+import { issue_number_shape } from '#scripts/issue/issue-number-shape'
+import { JOSH_TMP_DIRECTORY } from '#scripts/lib/josh-temporary-directory'
+import { disposition_batch, type BatchFinding } from './disposition-batch'
+
+// The branch-2 half of `josh disposition --batch`: for each finding it routes to `file`, a body that
+// `issue:lint` passes and the `issue:file` line that files it — written and printed, never filed, so
+// the run reads the draft before the filing. The origin pull request is unknown when the disposition
+// runs and an untraced bug owes a reproduction this cannot run, so the draft is declared non-bug; the
+// filer reclassifies it once the origin is traced.
+
+const FOUND_DURING_FLAG = '--found-during'
+const SECURITY_CATEGORY = 'security:'
+// A `'` inside a single-quoted shell word: close the quote, an escaped quote, reopen.
+const ESCAPED_QUOTE = String.raw`'\''`
+const MISSING_FOUND_DURING =
+	'a finding routes to `file`: pass `--found-during <N>`, the issue whose review found it'
+const FILE_HEADING = `File commands (bodies drafted under ${JOSH_TMP_DIRECTORY}/ — read each before filing):`
+
+interface Filing {
+	title: string
+	body_path: string
+}
+
+// The issue as GitHub renders it — the title, the body and the `parent:` line all name it this way.
+function cite(issue: number): string {
+	return issue_cite.plain_for('github', issue)
+}
+
+function title_of(finding: BatchFinding, issue: number): string {
+	return `Resolve review-cap finding ${finding.spec} deferred from ${cite(issue)}`
+}
+
+// A security finding declares what it bypasses instead of a priority, so `issue:file` applies the
+// high floor `issue-template.md` → H gives it; any other finding runs at the normal priority.
+function priority_line(finding: BatchFinding): string {
+	return finding.spec.startsWith(SECURITY_CATEGORY)
+		? `${issue_body_keys.prefix('security')} ${finding.description}`
+		: issue_body_keys.line('priority', 'normal')
+}
+
+function background_lines(finding: BatchFinding, issue: number): ReadonlyArray<string> {
+	return [
+		issue_body_keys.heading('background'),
+		'',
+		issue_body_keys.line('kind', 'non_bug'),
+		issue_body_keys.line('purpose', 'improvement'),
+		issue_body_keys.line('judgement', 'not_needed'),
+		priority_line(finding),
+		`${issue_body_keys.prefix('size')} ${issue_body_keys.size_value('1', '20')}`,
+		'',
+		`${cite(issue)} のレビューで確かめた所見 \`${finding.spec}\`。ラウンド上限のため、その場では直さずに持ち越した。`,
+	]
+}
+
+function body_of(finding: BatchFinding, issue: number): string {
+	return [
+		`parent: ${cite(issue)}`,
+		'',
+		...background_lines(finding, issue),
+		'',
+		issue_body_keys.heading('symptom'),
+		'',
+		`- ${finding.description}`,
+		'',
+		issue_body_keys.heading('expected'),
+		'',
+		`- \`${finding.spec}\` の失敗シナリオが起きない`,
+		'',
+		issue_body_keys.heading('criteria'),
+		'',
+		'- [ ] 所見の失敗シナリオを入力と状態で再現するテストが通る',
+		'',
+	].join('\n')
+}
+
+// Single-quoted, so a finding path carrying `$(`, a backtick or `"` stays literal when pasted.
+function shell_quoted(text: string): string {
+	return `'${text.split("'").join(ESCAPED_QUOTE)}'`
+}
+
+function command_of(filing: Filing, issue: number): string {
+	const flags = `--route review-cap --label run:lane --found-during ${String(issue)}`
+	const body_file = shell_quoted(filing.body_path)
+
+	return `pnpm josh issue:file ${shell_quoted(filing.title)} --body-file ${body_file} ${flags}`
+}
+
+function body_path_of(directory: string, issue: number, index: number): string {
+	return path.join(directory, `review-cap-${String(issue)}-${String(index + 1)}.md`)
+}
+
+// Writes each finding's body under `directory` and returns what its filing line names.
+function write_filings(
+	findings: ReadonlyArray<BatchFinding>,
+	issue: number,
+	directory: string = JOSH_TMP_DIRECTORY,
+): ReadonlyArray<Filing> {
+	mkdirSync(directory, { recursive: true })
+
+	return findings.map((finding, index) => {
+		const body_path = body_path_of(directory, issue, index)
+
+		writeFileSync(body_path, body_of(finding, issue))
+
+		return { title: title_of(finding, issue), body_path }
+	})
+}
+
+function found_during_of(argv: ReadonlyArray<string>): number | undefined {
+	const value = argv.includes(FOUND_DURING_FLAG) ? argv[argv.indexOf(FOUND_DURING_FLAG) + 1] : ''
+
+	return issue_number_shape.is_issue_number(value ?? '') ? Number(value) : undefined
+}
+
+// The lines `--batch` prints after the table: each `file` finding's filing line once its body is
+// written, `[]` when none routes to `file`, `undefined` when one does and `argv` names no issue.
+function filing_lines(
+	findings: ReadonlyArray<BatchFinding>,
+	argv: ReadonlyArray<string>,
+	directory: string = JOSH_TMP_DIRECTORY,
+): ReadonlyArray<string> | undefined {
+	const filed = findings.filter((finding) => disposition_batch.branch_of(finding) === 'file')
+
+	if (filed.length === 0) return []
+
+	const issue = found_during_of(argv)
+
+	if (issue === undefined) return undefined
+
+	const filings = write_filings(filed, issue, directory)
+	const commands = filings.map((filing) => command_of(filing, issue))
+
+	return ['', FILE_HEADING, ...commands]
+}
+
+const disposition_batch_filing = {
+	MISSING_FOUND_DURING,
+	body_of,
+	command_of,
+	filing_lines,
+	title_of,
+	write_filings,
+}
+
+export { disposition_batch_filing }
+export type { Filing }

package/scripts/review/disposition-batch.ts

@@ -0,0 +1,103 @@
+import { disposition, type Disposition } from './disposition-logic'
+import { review_finding_text } from './review-finding-text'
+import { review_record_cli } from './review-record-cli'
+
+// `josh disposition --batch <findings-file>` — every finding the run did not fix in place after the
+// review round cap, routed at once. A line is a `review:record` positional,
+// `<category>:<severity>:<file>[:<line>] — <sentence>`, marked `confirmed ` first when the run has
+// stated its failure scenario in concrete inputs and state — the one judgement `disposition` leaves to
+// the run. Branch 1 (fix in place) is a size call this cannot see, so it is made before the file is
+// written; the rest follows `prompts/review.md` → "Three-way disposition after the cap": a confirmed
+// finding that reaches a runtime path is filed, anything else dropped with a note the PR body carries.
+
+const CONFIRMED_MARK = 'confirmed '
+const LINE_SUFFIX = /:\d+(?:-\d+)?$/u
+const HEADER = ['| finding | disposition | confirmed | branch |', '| --- | --- | --- | --- |']
+const LEGEND =
+	'file: `pnpm josh issue:file … --route review-cap`; list only findings not fixed in place'
+const DROP_HEADING = 'Drop notes for the PR body:'
+
+type Branch = 'file' | 'drop'
+
+interface BatchFinding {
+	spec: string
+	description: string
+	is_confirmed: boolean
+	disposition: Disposition
+}
+
+type ParseResult = { findings: ReadonlyArray<BatchFinding> } | { invalid: ReadonlyArray<string> }
+
+function path_of(file: string): string {
+	return file.replace(LINE_SUFFIX, '')
+}
+
+function unmarked(line: string): string {
+	return line.startsWith(CONFIRMED_MARK) ? line.slice(CONFIRMED_MARK.length) : line
+}
+
+function parse_line(line: string): BatchFinding | undefined {
+	const parsed = review_record_cli.parse_positional(unmarked(line))
+
+	if (parsed === undefined) return undefined
+
+	const { category, severity, file } = parsed.finding
+
+	return {
+		spec: `${category}:${severity}:${file}`,
+		description: parsed.description,
+		is_confirmed: line.startsWith(CONFIRMED_MARK),
+		disposition: disposition.disposition_for([path_of(file)]),
+	}
+}
+
+function parse(text: string): ParseResult {
+	const lines = text
+		.split('\n')
+		.map((line) => line.trim())
+		.filter((line) => line.length > 0)
+	const parsed = lines.map((line) => ({ line, finding: parse_line(line) }))
+	const invalid = parsed.filter((entry) => entry.finding === undefined).map((entry) => entry.line)
+
+	if (invalid.length > 0) return { invalid }
+
+	return {
+		findings: parsed.flatMap((entry) => (entry.finding === undefined ? [] : [entry.finding])),
+	}
+}
+
+function branch_of(finding: BatchFinding): Branch {
+	return finding.is_confirmed && finding.disposition === disposition.RUNTIME ? 'file' : 'drop'
+}
+
+function drop_reason(finding: BatchFinding): string {
+	return finding.disposition === disposition.NON_RUNTIME ? 'non-runtime' : 'unconfirmed'
+}
+
+// A dropped finding's PR-body note, itself a `review:record` positional so one parser reads it back.
+function drop_note(finding: BatchFinding): string {
+	const reason = `dropped (${drop_reason(finding)}): ${finding.description}`.trim()
+
+	return `- ${finding.spec}${review_finding_text.DESCRIPTION_SEPARATOR}${reason}`
+}
+
+function table_row(finding: BatchFinding): string {
+	const confirmed = finding.is_confirmed ? 'yes' : 'no'
+
+	return `| ${finding.spec} | ${finding.disposition} | ${confirmed} | ${branch_of(finding)} |`
+}
+
+function render(findings: ReadonlyArray<BatchFinding>): string {
+	const rows = [...HEADER, ...findings.map((finding) => table_row(finding))]
+	const dropped = findings.filter((finding) => branch_of(finding) === 'drop')
+	const notes = dropped.map((finding) => drop_note(finding))
+
+	if (notes.length === 0) return [...rows, '', LEGEND].join('\n')
+
+	return [...rows, '', LEGEND, '', DROP_HEADING, ...notes].join('\n')
+}
+
+const disposition_batch = { branch_of, drop_note, parse, path_of, render }
+
+export { disposition_batch }
+export type { BatchFinding, Branch, ParseResult }

package/scripts/review/disposition-cli.ts

@@ -1,5 +1,8 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
+import { cli_body } from '#scripts/josh/cli-body'
+import { disposition_batch } from './disposition-batch'
+import { disposition_batch_filing } from './disposition-batch-filing'
 import { disposition } from './disposition-logic'
 
 // `josh disposition <path...>` — the machine half of the three-way review disposition.
@@ -7,9 +10,11 @@ import { disposition } from './disposition-logic'
 // runtime code path, a distributed artifact a consumer reads, or the verification guarding either —
 // and `non-runtime` when every path is inert. `prompts/review.md` → "Three-way disposition after the
 // cap" leaves the run one judgement after this: whether the finding is a confirmed defect.
+// `--batch <findings-file>` routes every remaining finding at once (`disposition-batch.ts`).
 
 const ARGV_OFFSET = 2
-const USAGE = 'Usage: josh disposition <path...>'
+const BATCH_FLAG = '--batch'
+const USAGE = 'Usage: josh disposition <path...> | --batch <findings-file>'
 const FAILURE_EXIT_CODE = 1
 
 function reason_line(paths: ReadonlyArray<string>): string {
@@ -20,7 +25,36 @@ function reason_line(paths: ReadonlyArray<string>): string {
 		: `reaches through: ${reaching.join(', ')}`
 }
 
+function refuse(message: string): number {
+	console.error(message)
+
+	return FAILURE_EXIT_CODE
+}
+
+// `<findings-file> [--found-during <N>]`; the issue is needed once a finding routes to `file`.
+function run_batch(argv: ReadonlyArray<string>): number {
+	const [path] = argv
+
+	if (path === undefined) return refuse(USAGE)
+
+	const result = disposition_batch.parse(cli_body.read_file_or_stdin(path))
+
+	if ('invalid' in result) {
+		return refuse(`not in the review:record grammar:\n${result.invalid.join('\n')}`)
+	}
+
+	const filing = disposition_batch_filing.filing_lines(result.findings, argv)
+
+	if (filing === undefined) return refuse(disposition_batch_filing.MISSING_FOUND_DURING)
+
+	process.stdout.write(`${[disposition_batch.render(result.findings), ...filing].join('\n')}\n`)
+
+	return 0
+}
+
 function run(argv: ReadonlyArray<string>): number {
+	if (argv[0] === BATCH_FLAG) return run_batch(argv.slice(1))
+
 	if (argv.length === 0) {
 		console.error(USAGE)
 

package/scripts/review/import-specifiers.ts

@@ -0,0 +1,38 @@
+import type { TypeScriptApi } from './comment-ranges'
+
+// A script's text with every binding import's module specifier emptied, so two versions that differ
+// only in where a binding comes from read as the same text (joshuafolkken/kit#5789).
+//
+// **The bindings stay**: a renamed or added binding still changes the text. **A side-effect import is
+// kept whole** — `import './x'` binds nothing, and its path alone decides what runs. Ranges come from
+// the parse tree, never a pattern, and a `.svelte` file is returned as it is.
+
+type Range = readonly [number, number]
+
+const VIRTUAL_FILE_NAME = 'import-delta.ts'
+const SVELTE_EXTENSION = '.svelte'
+const EMPTY_SPECIFIER = "''"
+
+function specifier_ranges(api: TypeScriptApi, text: string): ReadonlyArray<Range> {
+	const source = api.createSourceFile(VIRTUAL_FILE_NAME, text, api.ScriptTarget.Latest, true)
+
+	return source.statements
+		.filter((statement) => api.isImportDeclaration(statement))
+		.filter((statement) => statement.importClause !== undefined)
+		.map((statement) => [statement.moduleSpecifier.getStart(source), statement.moduleSpecifier.end])
+}
+
+function blank(api: TypeScriptApi, text: string, relative: string): string {
+	if (relative.endsWith(SVELTE_EXTENSION)) return text
+
+	const ranges = specifier_ranges(api, text)
+	const starts = [0, ...ranges.map(([, end]) => end)]
+
+	return starts
+		.map((start, index) => text.slice(start, ranges[index]?.[0] ?? text.length))
+		.join(EMPTY_SPECIFIER)
+}
+
+const import_specifiers = { blank }
+
+export { import_specifiers }

package/scripts/review/prose-stale-cli.ts

@@ -1,11 +1,9 @@
 #!/usr/bin/env tsx
 import { fileURLToPath } from 'node:url'
 import { change_base } from '#scripts/git/change-base'
-import { git_grep_hits } from '#scripts/git/git-grep-hits'
 import { git_spawn } from '#scripts/git/git-spawn'
-import { COMMAND_MAP } from '#scripts/josh/josh-command-map'
-import { test_pinned_logic, type Hunk } from '#scripts/test/test-pinned-logic'
-import { prose_stale_scan, type Reference, type Term } from './prose-stale-scan'
+import { prose_stale_read } from './prose-stale-read'
+import { prose_stale_scan } from './prose-stale-scan'
 
 // `josh prose:stale` — each word the change removed (a declared or exported name, a `josh x:y` command, an
 // `UPPER_CASE` constant, a `.md` heading) that a `.md` line or a comment line under prompts, docs,
@@ -15,40 +13,9 @@ import { prose_stale_scan, type Reference, type Term } from './prose-stale-scan'
 
 const USAGE = 'usage: josh prose:stale'
 const NO_BASE = 'prose:stale: no change base — fetch the default branch, then re-run'
-const SEARCH_PATHS = ['*.md', 'prompts', 'docs', '.claude', 'scripts', ':(exclude)CHANGELOG.md']
 // `process.argv` holds the runtime and the script before the command's own arguments.
 const FIRST_ARGUMENT = 2
 
-async function read_hunks(root: string, base: string): Promise<Array<Hunk>> {
-	const diff = await git_spawn.read([
-		'-C',
-		root,
-		'diff',
-		'-U0',
-		'--no-color',
-		'--no-ext-diff',
-		'--src-prefix=a/',
-		'--dst-prefix=b/',
-		base,
-	])
-
-	return test_pinned_logic.all_hunks(diff)
-}
-
-async function reference_of(term: Term, root: string): Promise<Reference> {
-	const { target, flags } = prose_stale_scan.pattern(term)
-	const { hits, has_failed } = await git_grep_hits.search(target, flags, SEARCH_PATHS, root)
-
-	return { term, hits, has_failed }
-}
-
-async function references(root: string, base: string): Promise<Array<Reference>> {
-	const registered = new Set(Object.keys(COMMAND_MAP))
-	const terms = prose_stale_scan.stale_terms(await read_hunks(root, base), registered)
-
-	return await Promise.all(terms.map(async (term) => await reference_of(term, root)))
-}
-
 function refuse(message: string): number {
 	console.error(message)
 
@@ -63,7 +30,10 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	if (base === undefined) return refuse(NO_BASE)
 
 	const root = await git_spawn.read(['rev-parse', '--show-toplevel'])
-	const { text, exit_code } = prose_stale_scan.report(await references(root, base))
+	const hunks = await prose_stale_read.read_hunks(root, base)
+	const { text, exit_code } = prose_stale_scan.report(
+		await prose_stale_read.references(root, hunks),
+	)
 
 	console.info(text)
 
@@ -83,6 +53,6 @@ if (process.argv[1] === fileURLToPath(import.meta.url)) {
 	process.exitCode = await guarded(process.argv.slice(FIRST_ARGUMENT))
 }
 
-const prose_stale_cli = { guarded, references, run }
+const prose_stale_cli = { guarded, run }
 
 export { prose_stale_cli }

package/scripts/review/prose-stale-read.ts

@@ -0,0 +1,105 @@
+import { existsSync } from 'node:fs'
+import { readFile } from 'node:fs/promises'
+import path from 'node:path'
+import { git_grep_hits } from '#scripts/git/git-grep-hits'
+import { git_spawn } from '#scripts/git/git-spawn'
+import { COMMAND_MAP } from '#scripts/josh/josh-command-map'
+import { test_pinned_logic, type Hunk } from '#scripts/test/test-pinned-logic'
+import { prose_stale_scan, type Reference, type Term, type Tree } from './prose-stale-scan'
+import { review_readers_scan } from './review-readers-scan'
+
+// The git half of `josh prose:stale`: the diff from the change base to the working tree, and the
+// search for each word it removed. Its own module, without a main guard, so `josh review:selfcheck`
+// (joshuafolkken/kit#5540) imports it as well as `prose-stale-cli.ts`.
+
+const SEARCH_PATHS = ['*.md', 'prompts', 'docs', '.claude', 'scripts', ':(exclude)CHANGELOG.md']
+// The code files a live declaration is looked for in, at any depth; a test file names nothing.
+const CODE_PATHSPECS = ['*.ts', '*.js', ':(exclude)*.test.ts', ':(exclude)*.test.js']
+
+async function read_hunks(root: string, base: string): Promise<Array<Hunk>> {
+	const diff = await git_spawn.read([
+		'-C',
+		root,
+		'diff',
+		'-U0',
+		'--no-color',
+		'--no-ext-diff',
+		'--src-prefix=a/',
+		'--dst-prefix=b/',
+		base,
+	])
+
+	return test_pinned_logic.all_hunks(diff)
+}
+
+async function reference_of(term: Term, root: string): Promise<Reference> {
+	const { target, flags } = prose_stale_scan.pattern(term)
+	const { hits, has_failed } = await git_grep_hits.search(target, flags, SEARCH_PATHS, root)
+
+	return { term, hits, has_failed }
+}
+
+async function declared_in(root: string, files: ReadonlyArray<string>): Promise<Array<string>> {
+	const sources = await Promise.all(
+		files.map(async (file) => await readFile(path.join(root, file), 'utf8')),
+	)
+
+	return sources.flatMap((source) =>
+		review_readers_scan.declarations(source).map(({ name }) => name),
+	)
+}
+
+// The working tree's code files that write any of `names`, the deleted ones aside.
+async function files_writing(root: string, names: ReadonlyArray<string>): Promise<Array<string>> {
+	const results = await Promise.all(
+		names.map(async (name) => await git_grep_hits.search(name, ['-w'], CODE_PATHSPECS, root)),
+	)
+	const files = new Set(results.flatMap(({ hits }) => hits.map((hit) => hit.path)))
+
+	return [...files].filter((file) => existsSync(path.join(root, file)))
+}
+
+// A deleted file's reachable name a live module outside the change still declares names that module,
+// not the deleted one (joshuafolkken/kit#7048): a removed namespace's `record` beside `gate-ledger.ts`'s.
+async function declared_elsewhere(
+	root: string,
+	hunks: ReadonlyArray<Hunk>,
+	deleted: ReadonlyArray<string>,
+): Promise<Array<string>> {
+	const gone = hunks.filter((hunk) => deleted.includes(hunk.file))
+	const names = [
+		...new Set(
+			gone.flatMap((hunk) => review_readers_scan.reachable_names(hunk.old_lines.join('\n'))),
+		),
+	]
+	const declared = new Set(await declared_in(root, await files_writing(root, names)))
+
+	return names.filter((name) => declared.has(name))
+}
+
+// The names the change's code files declare in the working tree, an unchanged line included
+// (joshuafolkken/kit#6077), and the files it deleted, which declare none (joshuafolkken/kit#6130).
+async function tree_of(root: string, hunks: ReadonlyArray<Hunk>): Promise<Tree> {
+	const files = [...new Set(hunks.map((hunk) => hunk.file))].filter((file) =>
+		prose_stale_scan.CODE_FILE.test(file),
+	)
+	const present = files.filter((file) => existsSync(path.join(root, file)))
+	const names = await declared_in(root, present)
+	const deleted = files.filter((file) => !present.includes(file))
+	const elsewhere = await declared_elsewhere(root, hunks, deleted)
+
+	return { surviving: new Set([...names, ...elsewhere]), deleted: new Set(deleted) }
+}
+
+// `hunks` is the whole change: a declaration moved into another file of it is kept, not removed.
+async function references(root: string, hunks: ReadonlyArray<Hunk>): Promise<Array<Reference>> {
+	const registered = new Set(Object.keys(COMMAND_MAP))
+	const tree = await tree_of(root, hunks)
+	const terms = prose_stale_scan.stale_terms(hunks, registered, tree)
+
+	return await Promise.all(terms.map(async (term) => await reference_of(term, root)))
+}
+
+const prose_stale_read = { read_hunks, references }
+
+export { prose_stale_read }