@joshuafolkken/kit 1.1514.0 → 1.1784.0

package/scripts/release/release-progress.ts

@@ -1,12 +1,10 @@
-import path from 'node:path'
 import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
-import { json_value } from '#scripts/lib/json-value'
+import { PACKAGE_JSON, package_manifest } from '#scripts/lib/package-manifest'
 import { poll } from '#scripts/lib/poll'
-import { file_reader } from '#scripts/lib/read-file'
 import { npm_registry } from '#scripts/version/npm-registry'
-import { version_targets } from '#scripts/version/version-targets'
 import { z } from 'zod'
+import { release_publish_run } from './release-publish-run'
 import { release_tag } from './release-tag'
 
 // The stage lines `pnpm josh release` prints, and the two stages it waits for after the tag.
@@ -15,9 +13,9 @@ import { release_tag } from './release-tag'
 // `publish-npm` puts the version on npm and `create-release` opens the GitHub Release once the
 // publishing jobs pass. Stopping at the tag would call the release published ahead of both, so the
 // command waits for each, prints one line per stage reached, and prints the completion line only
-// when every stage has — a stage that times out is named with ❌ and the run exits non-zero.
+// when every stage has — a stage that times out, or whose Publish run fails first, is named with ❌
+// and the run exits non-zero.
 
-const { PACKAGE_JSON } = version_targets
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
 const NPM_TIMEOUT_ENV = 'JOSH_RELEASE_NPM_TIMEOUT_SECONDS'
@@ -35,16 +33,10 @@ const manifest_schema = z.looseObject({
 })
 
 type ReleaseManifest = { is_private: true } | { is_private: false; name: string }
-
-function parse_manifest(cwd: string): z.infer<typeof manifest_schema> {
-	const raw = file_reader.read_optional(path.join(cwd, PACKAGE_JSON)) ?? ''
-	const parsed = manifest_schema.safeParse(json_value.parse_or_undefined(raw))
-
-	return parsed.success ? parsed.data : {}
-}
+type NpmState = { kind: 'published' } | { kind: 'failed'; run_id: number } | { kind: 'pending' }
 
 function read_manifest(cwd: string): ReleaseManifest {
-	const manifest = parse_manifest(cwd)
+	const manifest = package_manifest.read_manifest_if_valid(cwd, manifest_schema) ?? {}
 
 	if (manifest.private === true) return { is_private: true }
 	if (manifest.name === undefined) throw new Error(`${PACKAGE_JSON} in ${cwd} has no package name.`)
@@ -85,6 +77,18 @@ function missed_npm_line(package_name: string, version: string): string {
 	].join('\n')
 }
 
+// The run's own failure is known, so the line names the run rather than a stage that never came. It
+// claims no more than the last registry read: a job beside `publish-npm` can fail the run after npm
+// took the version.
+function failed_publish_line(version: string, run_id: number): string {
+	const tag = release_tag.tag_name(version)
+
+	return [
+		`❌ Publish ${tag} failed (run ${String(run_id)}) before npm listed ${tag}.`,
+		`  Inspect it with: gh run view ${String(run_id)} --log-failed`,
+	].join('\n')
+}
+
 function missed_release_line(version: string): string {
 	return [
 		`❌ No GitHub Release: ${release_tag.tag_name(version)} never got one.`,
@@ -109,18 +113,34 @@ async function read_release_url(version: string): Promise<string | undefined> {
 	}
 }
 
+function npm_outcome_line(package_name: string, version: string, state: NpmState): string {
+	if (state.kind === 'published') return npm_line(package_name, version)
+	if (state.kind === 'failed') return failed_publish_line(version, state.run_id)
+
+	return missed_npm_line(package_name, version)
+}
+
+async function npm_state(package_name: string, version: string): Promise<NpmState> {
+	if (npm_registry.has_public_version(package_name, version)) return { kind: 'published' }
+	const run_id = await release_publish_run.failed_run_id(version)
+
+	return run_id === undefined ? { kind: 'pending' } : { kind: 'failed', run_id }
+}
+
 async function wait_for_npm(manifest: ReleaseManifest, version: string): Promise<boolean> {
 	if (manifest.is_private) return true
-	const is_published = await poll.poll_until(
-		async () => npm_registry.has_public_version(manifest.name, version),
-		release_tag.poll_options_for(NPM_TIMEOUT_ENV),
-	)
+	// `poll_until` answers only whether it stopped, so the state the last read found is kept here.
+	const seen: { state: NpmState } = { state: { kind: 'pending' } }
 
-	console.info(
-		is_published ? npm_line(manifest.name, version) : missed_npm_line(manifest.name, version),
-	)
+	await poll.poll_until(async () => {
+		seen.state = await npm_state(manifest.name, version)
+
+		return seen.state.kind !== 'pending'
+	}, release_tag.poll_options_for(NPM_TIMEOUT_ENV))
+
+	console.info(npm_outcome_line(manifest.name, version, seen.state))
 
-	return is_published
+	return seen.state.kind === 'published'
 }
 
 async function wait_for_github_release(version: string): Promise<boolean> {

package/scripts/release/release-publish-run.ts

@@ -0,0 +1,39 @@
+import { git_gh_api_path } from '#scripts/gh/git-gh-api-path'
+import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { json_value } from '#scripts/lib/json-value'
+import { github_release_runs, type RunSource } from './github-release-runs'
+import { release_tag } from './release-tag'
+
+// The tag's Publish run as `pnpm josh release` sees it through `gh`, so the npm wait can end the
+// moment that run fails instead of waiting out its timeout for a version that will never appear.
+
+const PUBLISH_WORKFLOW = 'publish.yml'
+
+function gh_run_source(): RunSource {
+	return {
+		read: async (api_path) =>
+			json_value.parse_or_undefined(
+				await git_gh_exec.exec_gh_api({ path: `${git_gh_api_path.repo_api_path()}${api_path}` }),
+			),
+		workflow: PUBLISH_WORKFLOW,
+		jobs: [],
+		release_run_workflow: undefined,
+	}
+}
+
+// A repository without the workflow, or a read that fails, tells nothing about the run, so the npm
+// wait goes on as it did before the run was asked about.
+async function failed_run_id(version: string): Promise<number | undefined> {
+	try {
+		const tag = release_tag.tag_name(version)
+		const run = await github_release_runs.publish_run(gh_run_source(), PUBLISH_WORKFLOW, tag)
+
+		return run && github_release_runs.run_state(run) === 'failed' ? run.id : undefined
+	} catch {
+		return undefined
+	}
+}
+
+const release_publish_run = { failed_run_id }
+
+export { release_publish_run }

package/scripts/release/release-publish.ts

@@ -1,10 +1,12 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
-import { git_pr_checks } from '#scripts/gh/git-pr-checks'
+import { git_pr_merge_checked } from '#scripts/gh/git-pr-merge-checked'
 import { git_command } from '#scripts/git/git-command'
 import { git_remote_branch } from '#scripts/git/git-remote-branch'
 import { repository_lock } from '#scripts/git/repository-lock'
+import { IGNORE_FOR_RELEASE_LABEL } from '#scripts/issue/issue-labels'
+import { PACKAGE_JSON } from '#scripts/lib/package-manifest'
 import { write_version } from '#scripts/version/bump-version'
-import { version_targets } from '#scripts/version/version-targets'
+import { release_approval_prune } from './release-approval-prune'
 import { release_issue_close } from './release-issue-close'
 import type { ReleasePlan } from './release-plan'
 import { release_progress } from './release-progress'
@@ -19,10 +21,8 @@ import { release_worktree } from './release-worktree'
 // weakening it for a release commit would open exactly the "merge without green CI" path the issue's
 // closing note prohibits.
 
-const { PACKAGE_JSON } = version_targets
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
-const IGNORE_FOR_RELEASE_LABEL = 'ignore-for-release'
 const RELEASE_LOCK_PREFIX = 'josh-release-lock-'
 // A release waits on CI for minutes, so a second run refuses rather than queueing behind it.
 const RELEASE_LOCK_MAX_WAIT_MS = 0
@@ -109,6 +109,7 @@ async function clear_the_way(branch_name: string): Promise<void> {
 async function commit_release(plan: ReleasePlan): Promise<string> {
 	write_version(plan.next_version)
 	await git_command.add_path(PACKAGE_JSON)
+	await release_approval_prune.prune()
 	await git_command.commit(commit_message(plan.next_version))
 	await git_command.push()
 	const pr_url = await git_gh_command.pr_create(
@@ -136,8 +137,7 @@ async function merge_and_tag(
 	branch_name: string,
 	pr_url: string,
 ): Promise<number> {
-	await git_pr_checks.wait_for_pr_success(branch_name)
-	await git_gh_command.pr_merge(branch_name)
+	await git_pr_merge_checked.merge_when_green(branch_name)
 	console.info(release_progress.pr_merged_line(pr_url))
 
 	const is_tagged = await release_tag.wait_for_tag(plan.next_version)

package/scripts/release/release-scope-cli.ts

@@ -1,5 +1,3 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { git_followup_pending } from '#scripts/followup/git-followup-pending'
 import { path_decision } from '#scripts/josh/path-decision'
 import { release_plan } from './release-plan'
@@ -22,7 +20,6 @@ import { release_plan } from './release-plan'
 // The flag parse and the printing come from `path_decision`, the contract every mechanically-decided
 // command here shares. Only its `parse_options` / `run_path_decision` are path-specific, and this
 // decision is not made from changed paths, so those two are the ones left alone.
-const ARGV_OFFSET = 2
 const USAGE = 'Usage: josh release:scope [--json]'
 const JSON_KEY = 'scope'
 // Not `path_decision.KNOWN_FLAGS`: that set carries `--staged`, which means nothing here, and a
@@ -76,13 +73,8 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	return SUCCESS_EXIT_CODE
 }
 
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const release_scope_cli = {
 	decide,
-	main,
 	run,
 	JSON_KEY,
 	NOTHING_PENDING_REASON,
@@ -94,7 +86,5 @@ const release_scope_cli = {
 	USAGE,
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export type { Decision }
 export { release_scope_cli }

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

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

package/scripts/repo/repo-setting.ts

@@ -1,5 +1,6 @@
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
 import { PROJECT_ROOT } from '#scripts/init/init-paths'
+import { json_value } from '#scripts/lib/json-value'
 
 // The shared half of every "report a GitHub repository setting kit cannot write" check.
 //
@@ -49,13 +50,9 @@ function query_repo_api(api_path: string): RepoApiResult {
 function parse_payload(exit_code: number, stdout: string): object | undefined {
 	if (exit_code !== 0) return undefined
 
-	try {
-		const parsed: unknown = JSON.parse(stdout)
+	const parsed = json_value.parse_or_undefined(stdout)
 
-		return typeof parsed === 'object' && parsed !== null ? parsed : undefined
-	} catch {
-		return undefined
-	}
+	return typeof parsed === 'object' && parsed !== null ? parsed : undefined
 }
 
 // Read one field off a parsed body. `Reflect.get` rather than an index signature: the body is

package/scripts/repo/required-checks-logic.ts

@@ -1,3 +1,4 @@
+import { json_value } from '#scripts/lib/json-value'
 import { yaml_document } from '#scripts/lib/yaml-document'
 import { z } from 'zod'
 
@@ -88,17 +89,7 @@ function expected_checks(read_workflow: (workflow: string) => string | undefined
 	})
 }
 
-function parse_json(stdout: string): unknown {
-	try {
-		return JSON.parse(stdout)
-	} catch {
-		return undefined
-	}
-}
-
-function status_check_rules(payload: unknown): Array<BranchRule> {
-	if (!Array.isArray(payload)) return []
-
+function status_check_rules(payload: ReadonlyArray<unknown>): Array<BranchRule> {
 	return payload.flatMap((entry: unknown) => {
 		const parsed = branch_rule_schema.safeParse(entry)
 
@@ -110,8 +101,8 @@ function status_check_rules(payload: unknown): Array<BranchRule> {
 // rulesets. The contexts of all of them are combined, since each is enforced; the first ruleset is the
 // one `--apply` writes to. No `required_status_checks` rule at all reads as `none`.
 function parse_branch_rules(stdout: string | undefined): RequiredSource {
-	const payload = stdout === undefined ? undefined : parse_json(stdout)
-	if (!Array.isArray(payload)) return { kind: 'unreadable' }
+	const payload = stdout === undefined ? undefined : json_value.parse_array(stdout)
+	if (payload === undefined) return { kind: 'unreadable' }
 	const rules = status_check_rules(payload)
 	const [first] = rules
 	if (first === undefined) return { kind: 'none' }
@@ -132,7 +123,7 @@ function parse_protection(read: ApiRead): RequiredSource {
 		return { kind: read.status === NOT_FOUND_STATUS ? 'none' : 'unreadable' }
 	}
 
-	const parsed = protection_schema.safeParse(parse_json(read.stdout))
+	const parsed = protection_schema.safeParse(json_value.parse_or_undefined(read.stdout))
 
 	return parsed.success
 		? { kind: 'protection', contexts: parsed.data.contexts }
@@ -175,7 +166,7 @@ function ruleset_update_body(
 	ruleset_stdout: string,
 	missing: ReadonlyArray<string>,
 ): string | undefined {
-	const parsed = ruleset_schema.safeParse(parse_json(ruleset_stdout))
+	const parsed = ruleset_schema.safeParse(json_value.parse_or_undefined(ruleset_stdout))
 	if (!parsed.success) return undefined
 
 	return JSON.stringify({

package/scripts/report/report-format-reference.ts

@@ -9,6 +9,7 @@ const SUMMARY_RULES_HEADING = '作業前サマリはいつ・どう出すか'
 const SUMMARY_TEMPLATE_HEADING = '作業前サマリ（セッション向け・`JOSH_SESSION_LANG` の言語）'
 const COMPLETION_REPORT_HEADING = '完了報告（セッション向け）'
 const ACCEPTANCE_MAP_HEADING = 'PR 本文の受け入れ条件の対応表'
+const REMOVED_TESTS_HEADING = 'PR 本文の消えたテストの処置'
 
 // The heading goes in single quotes in the runnable form: the template heading carries backticks,
 // which a double-quoted shell argument would run as a command substitution.
@@ -20,6 +21,7 @@ const report_format_reference = {
 	ACCEPTANCE_MAP_HEADING,
 	COMPLETION_REPORT_HEADING,
 	pointer,
+	REMOVED_TESTS_HEADING,
 	REPORT_FORMAT_PATH,
 	SUMMARY_RULES_HEADING,
 	SUMMARY_TEMPLATE_HEADING,

package/scripts/report/report-labels.ts

@@ -0,0 +1,155 @@
+import { session_language } from '#scripts/josh/session-language'
+
+// The labels of the work summary and the completion report, in the two languages the workflow is
+// written in. **This table is their single source**: `report:template` prints the skeletons from it
+// and `report:lint` checks a summary against it, so a session that translates its labels by the
+// table passes the lint in any language. `report-format.md` names the command, never a copy.
+
+interface ReportLabels {
+	overview: string
+	now: string
+	change: string
+	check: string
+	details: string
+	target: string
+	approach: string
+	out_of_scope: string
+	changes: string
+	cases: string
+	case_vocabulary: ReadonlyArray<string>
+	if_it_breaks: string
+	not_applicable: string
+	never_breaks: string
+	completion: string
+	cause: string
+	fix: string
+	result: string
+	changed_files: string
+	test_results: string
+	evidence: string
+	caught_by: string
+	remaining: string
+	handoff: HandoffLabels
+}
+
+// The hand-off report's labels (`run:report --handoff`) — a fourth kind of stop, so it carries none of
+// the completion report's `cause` / `fix` / `result`.
+interface HandoffLabels {
+	title: string
+	done: string
+	remaining: string
+	why_stopped: string
+	next_command: string
+	measurement: string
+	handover: string
+	handover_text: string
+	parked: string
+	pool: string
+	none: string
+}
+
+const JAPANESE_HANDOFF_LABELS: HandoffLabels = {
+	title: '■ 区切り',
+	done: '終わったこと',
+	remaining: '残っていること',
+	why_stopped: '止めた理由',
+	next_command: '次に打つコマンド',
+	measurement: '計測',
+	handover: '引き継ぎ',
+	handover_text: '状態は GitHub とラン記録にあり、会話には何も無い',
+	parked: 'park 済み',
+	pool: '残りの auto-ok プール',
+	none: 'なし',
+}
+
+const ENGLISH_HANDOFF_LABELS: HandoffLabels = {
+	title: '■ Hand-off',
+	done: 'Done',
+	remaining: 'Remaining',
+	why_stopped: 'Why it stopped',
+	next_command: 'Next command',
+	measurement: 'Measurement',
+	handover: 'Handover',
+	handover_text: 'The state is on GitHub and in the run record; nothing is in the conversation',
+	parked: 'parked',
+	pool: 'the rest of the auto-ok pool',
+	none: 'none',
+}
+
+const JAPANESE_LABELS: ReportLabels = {
+	overview: '■ 概要',
+	now: '今こうなっている',
+	change: 'こう直す',
+	check: '確かめ方',
+	details: '技術詳細',
+	target: '対象',
+	approach: '方針',
+	out_of_scope: '副作用 / スコープ外',
+	changes: '変更とテスト',
+	cases: 'ケース',
+	case_vocabulary: ['正常', '空・0件', '1件', '多数', '境界', '不正入力', '重複', '順序', 'null'],
+	if_it_breaks: '壊れるとしたら',
+	not_applicable: '該当なし',
+	never_breaks: 'どう呼ばれても壊れない',
+	completion: '■ 完了報告',
+	cause: '原因',
+	fix: '対応',
+	result: '結果',
+	changed_files: '変更ファイル',
+	test_results: 'テスト結果',
+	evidence: '実行証跡',
+	caught_by: '捕まえられた検証',
+	remaining: '残課題',
+	handoff: JAPANESE_HANDOFF_LABELS,
+}
+
+const ENGLISH_LABELS: ReportLabels = {
+	overview: '■ Overview',
+	now: 'Now',
+	change: 'Change',
+	check: 'Check',
+	details: 'Details',
+	target: 'Target',
+	approach: 'Approach',
+	out_of_scope: 'Side effects / out of scope',
+	changes: 'Changes and tests',
+	cases: 'Cases',
+	case_vocabulary: [
+		'normal',
+		'empty',
+		'one',
+		'many',
+		'boundary',
+		'invalid input',
+		'duplicate',
+		'order',
+		'null',
+	],
+	if_it_breaks: 'If it breaks',
+	// Never `N/A`: the lint splits a case line on `/`, which would cut the marker in two.
+	not_applicable: 'not applicable',
+	never_breaks: 'never breaks however it is called',
+	completion: '■ Completion report',
+	cause: 'Cause',
+	fix: 'Fix',
+	result: 'Result',
+	changed_files: 'Changed files',
+	test_results: 'Test results',
+	evidence: 'Execution evidence',
+	caught_by: 'Caught by',
+	remaining: 'Remaining',
+	handoff: ENGLISH_HANDOFF_LABELS,
+}
+
+function labels_for(lang: string): ReportLabels {
+	return session_language.is_japanese(lang) ? JAPANESE_LABELS : ENGLISH_LABELS
+}
+
+function session_labels(): ReportLabels {
+	return labels_for(session_language.resolve_session_lang().lang)
+}
+
+const report_labels = { ENGLISH_LABELS, JAPANESE_LABELS, labels_for, session_labels }
+
+export type { HandoffLabels, ReportLabels }
+export { report_labels }

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

@@ -1,6 +1,7 @@
 #!/usr/bin/env tsx
 import { text } from 'node:stream/consumers'
 import { fileURLToPath } from 'node:url'
+import { josh_environment_file } from '#scripts/josh/josh-environment-file'
 import { report_lint } from './report-lint'
 
 // `josh report:lint` — read a two-layer work summary candidate from stdin and print `ok`, or the
@@ -38,7 +39,9 @@ async function read_and_run(): Promise<number> {
 	return run(await text(process.stdin))
 }
 
+// `.env` is read here, on the command path alone, so the labels follow the session language.
 async function main(): Promise<void> {
+	josh_environment_file.load_environment_file()
 	process.exitCode = await read_and_run()
 }