@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/observations/observation-record.ts

@@ -31,17 +31,32 @@ interface RecordRequest {
 	now: Date
 }
 
-type RecordResult =
-	| { verdict: typeof REFUSED_VERDICT; reason: string }
-	| {
-			verdict: typeof FILE_VERDICT | typeof LEDGER_VERDICT
-			earlier: ReadonlyArray<string>
-			line: string
-			target: string
-	  }
+interface Refusal {
+	verdict: typeof REFUSED_VERDICT
+	reason: string
+}
+
+interface Assessment {
+	verdict: typeof FILE_VERDICT | typeof LEDGER_VERDICT
+	earlier: ReadonlyArray<string>
+	line: string
+}
+
+type AssessResult = Refusal | Assessment
+
+type RecordResult = Refusal | (Assessment & { target: string })
+
+// Prettier's markdown pass collapses a whitespace run in a list item (only the whitespace is settled
+// here; emphasis markers in a field are not), so a line keeping one (vitest's
+// padded test names, joshuafolkken/kit#5303) fails a later gate's style check on a file it never wrote.
+// Collapsed before the grammar check, so whitespace around a `|` that Prettier would turn into a
+// separator is refused like a `|` already standing as one.
+function collapsed(field: string): string {
+	return field.replaceAll(/\s+/gu, ' ').trim()
+}
 
 function entry_line(entry: ObservationEntry, date: string): string {
-	return `- k:${entry.slug} | ${entry.depth} | ${date} | ${entry.where} | ${entry.what}`
+	return `- k:${entry.slug} | ${entry.depth} | ${date} | ${collapsed(entry.where)} | ${collapsed(entry.what)}`
 }
 
 function refusal_of(entry: ObservationEntry, line: string): string | undefined {
@@ -58,8 +73,9 @@ function sightings(ledger: string | undefined, slug: string): ReadonlyArray<stri
 	return (ledger ?? '').split('\n').filter((line) => line.startsWith(prefix))
 }
 
-// The count is read before the append, so it is the sightings *before* this one.
-async function record(request: RecordRequest): Promise<RecordResult> {
+// The line, the earlier sightings and the verdict, with nothing appended — for a caller that keeps the
+// line somewhere other than the tree (`followup-failed-tests.ts` posts it on the issue).
+async function assess(request: RecordRequest): Promise<AssessResult> {
 	const date = observation_ledger_home.ledger_date(request.now)
 	const line = entry_line(request.entry, date)
 	const reason = refusal_of(request.entry, line)
@@ -70,22 +86,32 @@ async function record(request: RecordRequest): Promise<RecordResult> {
 		await observation_ledger_home.read(request.checkout),
 		request.entry.slug,
 	)
-	const target = await observation_ledger_home.writer_path(request.now, request.checkout)
+	const verdict = earlier.length === PROMOTING_COUNT ? FILE_VERDICT : LEDGER_VERDICT
 
-	await observation_ledger_home.append(target, [line])
+	return { verdict, earlier, line }
+}
 
-	const verdict = earlier.length === PROMOTING_COUNT ? FILE_VERDICT : LEDGER_VERDICT
+// The count is read before the append, so it is the sightings *before* this one.
+async function record(request: RecordRequest): Promise<RecordResult> {
+	const assessment = await assess(request)
+
+	if (assessment.verdict === REFUSED_VERDICT) return assessment
+
+	const target = await observation_ledger_home.writer_path(request.now, request.checkout)
+
+	await observation_ledger_home.append(target, [assessment.line])
 
-	return { verdict, earlier, line, target }
+	return { ...assessment, target }
 }
 
-const observation_record = { record }
+const observation_record = { assess, record }
 
 export {
 	FILE_VERDICT,
 	LEDGER_VERDICT,
 	observation_record,
 	REFUSED_VERDICT,
+	type AssessResult,
 	type ObservationEntry,
 	type RecordResult,
 }

package/scripts/observations/observations-flush-landing.ts

@@ -1,6 +1,8 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import type { OpenPull } from '#scripts/gh/git-gh-pr-auto-merge'
 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 { issue_cite } from '#scripts/issue/issue-cite'
 import { error_text } from '#scripts/lib/error-message'
 
@@ -21,9 +23,10 @@ const MERGE_FAILED_REASON =
 // **Best-effort, and the answer says which wait to use.** GraphQL — the only way to enable auto-merge
 // — can be refused in a cloud session, and that loses the safety net rather
 // than the flush: the in-process wait-and-merge still runs, exactly as before auto-merge existed.
+// The checkout's head is the commit this flush just pushed, so that is the one auto-merge may land.
 async function request_auto_merge(branch_name: string): Promise<boolean> {
 	try {
-		await git_gh_command.pr_enable_auto_merge(branch_name)
+		await git_gh_command.pr_enable_auto_merge(branch_name, await git_command.head_commit())
 
 		return true
 	} catch (error) {
@@ -37,8 +40,7 @@ async function request_auto_merge(branch_name: string): Promise<boolean> {
 // the merge gate's wait would run out its budget on a pull request that is already merged.
 async function wait_for_landing(branch_name: string, is_auto_merge: boolean): Promise<void> {
 	if (!is_auto_merge) {
-		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)
 
 		return
 	}

package/scripts/observations/observations-flush.ts

@@ -1,7 +1,9 @@
 import { git_gh_command } from '#scripts/gh/git-gh-command'
 import { git_command } from '#scripts/git/git-command'
 import { main_sync } from '#scripts/git/main-sync'
+import { IGNORE_FOR_RELEASE_LABEL } from '#scripts/issue/issue-labels'
 import { error_text } from '#scripts/lib/error-message'
+import { review_comment_carry } from '#scripts/review/review-comment-carry'
 import { observation_ledger, OBSERVATION_LEDGER_DIRECTORY } from './observation-ledger'
 import type { BrokenLine } from './observation-ledger-line'
 import { observation_ledger_prepare } from './observation-ledger-prepare'
@@ -11,7 +13,8 @@ import { observations_flush_landing } from './observations-flush-landing'
 // a lane's included — commits its appended lines with its own pull request (`scripts/git/
 // git-staging.ts`), and `pnpm josh followup` commits a
 // line appended after that commit before it merges, so what is left here is a line written on the
-// default branch outside any issue's run — the date-named file `observation-ledger-home.ts` resolves.
+// default branch outside any issue's run — the date-named file `observation-ledger-home.ts` resolves —
+// and the closed issues' comment rounds no lane carries (`flush` below).
 //
 // **The shape is `scripts/release/release-publish.ts`'s, deliberately.** Both open a pull request of
 // their own over one path, wait on the same required checks every other pull request waits on, and
@@ -258,7 +261,11 @@ async function push_and_open(branch_name: string): Promise<string> {
 	try {
 		await git_command.push()
 
-		return await git_gh_command.pr_create(COMMIT_MESSAGE, pull_request_body(), 'ignore-for-release')
+		return await git_gh_command.pr_create(
+			COMMIT_MESSAGE,
+			pull_request_body(),
+			IGNORE_FOR_RELEASE_LABEL,
+		)
 	} catch (error) {
 		throw new Error(stranded_branch_message(branch_name, error_text.message_of(error)), {
 			cause: error,
@@ -388,6 +395,27 @@ async function prepare_ledger(): Promise<void> {
 	if (broken.length > 0) throw new Error(broken_lines_message(broken))
 }
 
+// The checkout made safe and caught up: a carried file an earlier flush left uncommitted is discarded
+// first, since it would make git refuse the fast-forward (`review-comment-carry.ts`).
+async function ready_default_branch(status_output: string): Promise<string> {
+	const default_branch = await refuse_unsafe_flush(status_output)
+
+	review_comment_carry.discard_uncommitted(status_output, process.cwd())
+	await catch_up_default(default_branch)
+
+	return default_branch
+}
+
+// **The closed issues' comment rounds are carried only once a flush will go ahead**
+// (joshuafolkken/kit#5326): a lane child leaves them to this flush, so the carried files ride its pull
+// request, and the status is read again so a carry alone is a change to flush. A carry left behind by
+// a later stop is discarded by the next flush's `ready_default_branch`.
+async function carried_status(): Promise<string> {
+	await review_comment_carry.carry_reported(process.cwd())
+
+	return await git_command.status()
+}
+
 // **Nothing pulls in front of the branch, and that is deliberate.** The ledger is dirty by
 // definition at this point, so `git pull --ff-only` aborts on it in exactly the case a pull would
 // have been for — an upstream flush that already advanced the ledger — and reports a failure about
@@ -396,19 +424,19 @@ async function prepare_ledger(): Promise<void> {
 // only where git can do it without touching the ledger: a default branch
 // that predates another merged flush still stops here — before a branch is cut — rather than opening
 // a pull request that cannot merge. An earlier flush pull request still open is checked for the same
-// reason: a branch cut beside it conflicts with it at the ledger's tail.
+// reason: a branch cut beside it conflicts with it at the ledger's tail. So the order is: ready the
+// default branch, defer to an open flush, carry, then check, prepare and land.
 async function flush(now: Date): Promise<string> {
-	const status_output = await git_command.status()
-	const default_branch = await refuse_unsafe_flush(status_output)
-
-	if (!has_ledger_change(status_output)) return CLEAN_MESSAGE
-
-	await prepare_ledger()
+	const default_branch = await ready_default_branch(await git_command.status())
 
 	const deferred = await observations_flush_landing.refuse_open_flush(BRANCH_PREFIX)
 	if (deferred !== undefined) return deferred
 
-	await catch_up_default(default_branch)
+	const status_output = await carried_status()
+
+	if (!has_ledger_change(status_output)) return CLEAN_MESSAGE
+
+	await prepare_ledger()
 
 	const branch_name = branch_name_for(timestamp_for(now))
 

package/scripts/overrides/overrides-check.ts

@@ -11,7 +11,9 @@
 import { readFileSync, writeFileSync } from 'node:fs'
 import { fileURLToPath } from 'node:url'
 import { cli_flags } from '#scripts/lib/cli-flags'
+import { file_reader } from '#scripts/lib/read-file'
 import { overrides_snapshot_schema } from '#scripts/lib/schemas'
+import { development_engines_verdict } from '#scripts/version/development-engines-verdict'
 import { overrides_files } from './overrides-files'
 import { overrides_check, type OverridesDiff } from './overrides-logic'
 
@@ -19,17 +21,13 @@ const ARGV_OFFSET = 2
 const OPTIONS = { save: { type: 'boolean', default: false } } as const
 const USAGE = cli_flags.usage_line(['--save'], 'overrides')
 
-function is_file_not_found(error: unknown): boolean {
-	return error instanceof Error && 'code' in error && error.code === 'ENOENT'
-}
-
 function load_snapshot(): Record<string, string> {
 	try {
 		return overrides_snapshot_schema.parse(
 			JSON.parse(readFileSync(overrides_check.SNAPSHOT_PATH, 'utf8')),
 		)
 	} catch (error) {
-		if (is_file_not_found(error)) {
+		if (file_reader.is_absent(error)) {
 			console.error(`✖ Snapshot not found: ${overrides_check.SNAPSHOT_PATH}`)
 			console.error('  Run with --save first to create a snapshot.')
 		} else {
@@ -74,6 +72,13 @@ function run_overrides_check(should_save: boolean): void {
 	console.info(`✔ overrides unchanged (${summary}).`)
 }
 
+// The `devEngines` verdict rides on every check, whatever the overrides answer, so it is printed
+// before the overrides comparison can exit.
+function run_check(should_save: boolean): void {
+	development_engines_verdict.report()
+	run_overrides_check(should_save)
+}
+
 // A line nobody can read is refused before the snapshot is read or written: a misspelled `--save` that
 // fell through would compare against the record the caller meant to replace.
 function refuse_usage(): never {
@@ -86,7 +91,7 @@ function main(argv: ReadonlyArray<string>): void {
 	const values = cli_flags.values_of(argv, OPTIONS)
 
 	if (values === undefined) refuse_usage()
-	run_overrides_check(values.save)
+	run_check(values.save)
 }
 
 if (process.argv[1] === fileURLToPath(import.meta.url)) main(process.argv.slice(ARGV_OFFSET))

package/scripts/overrides/overrides-files.ts

@@ -1,3 +1,4 @@
+import { PACKAGE_JSON } from '#scripts/lib/package-manifest'
 import { file_reader } from '#scripts/lib/read-file'
 import { overrides_check, type OverridesSources } from './overrides-logic'
 
@@ -5,7 +6,7 @@ import { overrides_check, type OverridesSources } from './overrides-logic'
 // field at all — so a missing file reads as an empty document rather than aborting the check.
 function read_current_sources(): OverridesSources {
 	return {
-		package_json: file_reader.read_file_or_empty(overrides_check.PACKAGE_JSON_PATH),
+		package_json: file_reader.read_file_or_empty(PACKAGE_JSON),
 		workspace_yaml: file_reader.read_file_or_empty(overrides_check.WORKSPACE_YAML_PATH),
 	}
 }

package/scripts/overrides/overrides-logic.ts

@@ -1,3 +1,4 @@
+import { PACKAGE_JSON } from '#scripts/lib/package-manifest'
 import { yaml_document } from '#scripts/lib/yaml-document'
 import {
 	package_pnpm_schema,
@@ -68,7 +69,6 @@ function compare(snapshot: Record<string, string>, current: Record<string, strin
 }
 
 const SNAPSHOT_PATH = '.overrides-snapshot.json'
-const PACKAGE_JSON_PATH = 'package.json'
 const WORKSPACE_YAML_PATH = 'pnpm-workspace.yaml'
 
 // Both source files are optional and either may be absent from a project entirely, so an empty
@@ -109,14 +109,12 @@ function count_entry(path: string, overrides: Record<string, string>): Array<str
 function describe_sources(sources: OverridesSources): string {
 	const counts = [
 		...count_entry(WORKSPACE_YAML_PATH, read_overrides_from_workspace(sources.workspace_yaml)),
-		...count_entry(PACKAGE_JSON_PATH, read_overrides_from_package(sources.package_json)).map(
+		...count_entry(PACKAGE_JSON, read_overrides_from_package(sources.package_json)).map(
 			(entry) => `${entry} (ignored by pnpm)`,
 		),
 	]
 
-	if (counts.length === 0) {
-		return `no overrides found in ${WORKSPACE_YAML_PATH} or ${PACKAGE_JSON_PATH}`
-	}
+	if (counts.length === 0) return `no overrides found in ${WORKSPACE_YAML_PATH} or ${PACKAGE_JSON}`
 
 	return counts.join(', ')
 }
@@ -202,7 +200,6 @@ const overrides_check = {
 	list_excluded_package_names,
 	read_dependency_names,
 	build_update_command,
-	PACKAGE_JSON_PATH,
 	WORKSPACE_YAML_PATH,
 	SNAPSHOT_PATH,
 }

package/scripts/package/verify-optional-eslint-install.ts

@@ -1,16 +1,18 @@
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
 import os from 'node:os'
 import path from 'node:path'
+import { PACKAGE_JSON, package_manifest } from '#scripts/lib/package-manifest'
 import { execaSync } from 'execa'
+import { z } from 'zod'
 
 const root = process.cwd()
 const scratch = mkdtempSync(path.join(os.tmpdir(), 'kit-eslint-install-'))
-const PACKAGE_JSON = 'package.json'
 const IGNORE_SCRIPTS = '--ignore-scripts'
-const manifest = JSON.parse(readFileSync(path.join(root, PACKAGE_JSON), 'utf8')) as {
-	devDependencies: Record<string, string>
-	peerDependencies: Record<string, string>
-}
+const version_map_schema = z.record(z.string(), z.string())
+const manifest = package_manifest.read_manifest(
+	root,
+	z.object({ devDependencies: version_map_schema, peerDependencies: version_map_schema }),
+)
 const eslint_peers = Object.keys(manifest.peerDependencies).filter((name) =>
 	/^(?:@eslint\/|@stylistic\/|eslint|globals$|typescript)/u.test(name),
 )

package/scripts/propagate/propagate-publish.ts

@@ -1,4 +1,5 @@
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
+import { json_value } from '#scripts/lib/json-value'
 import { poll } from '#scripts/lib/poll'
 import { GH_API_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { with_page_size } from '#scripts/version/version-remote'
@@ -63,13 +64,7 @@ function fetch_published_versions(versions_endpoint: string): Array<string> | un
 	})
 	if (stdout === undefined) return undefined
 
-	try {
-		const parsed: unknown = JSON.parse(stdout)
-
-		return Array.isArray(parsed) ? parsed.filter((name) => typeof name === 'string') : undefined
-	} catch {
-		return undefined
-	}
+	return json_value.parse_array(stdout)?.filter((name) => typeof name === 'string')
 }
 
 // The knobs the wait exposes. Every one of them is injectable so the unit suite can drive the loop

package/scripts/propagate/propagate-targets.ts

@@ -1,7 +1,7 @@
-import { existsSync, readFileSync } from 'node:fs'
+import { existsSync } from 'node:fs'
 import path from 'node:path'
 import type { RepoMap } from '#scripts/discovery/repo-map-logic'
-import { json_value } from '#scripts/lib/json-value'
+import { package_manifest } from '#scripts/lib/package-manifest'
 import { z } from 'zod'
 
 // Deciding which repositories a published release should be carried into.
@@ -16,7 +16,6 @@ import { z } from 'zod'
 // us rather than a roster, so a new consumer needs no edit here — and it covers a consumer that is
 // not a published package at all, which a list of downstream package names cannot.
 
-const MANIFEST_NAME = 'package.json'
 const NODE_MODULES = 'node_modules'
 
 // Why a candidate is not going to be processed, or that it is. `not_selected` is the one state set
@@ -64,14 +63,7 @@ function has_checkout(repository_path: string): boolean {
 }
 
 function read_manifest(repository_path: string): Manifest | undefined {
-	const manifest_path = path.join(repository_path, MANIFEST_NAME)
-	if (!existsSync(manifest_path)) return undefined
-
-	try {
-		return json_value.parse_with(readFileSync(manifest_path, 'utf8'), manifest_schema)
-	} catch {
-		return undefined
-	}
+	return package_manifest.read_manifest_if_valid(repository_path, manifest_schema)
 }
 
 // The range a manifest declares for `package_name`, from either dependency field. Undefined when the
@@ -95,7 +87,7 @@ function installed_version(repository_path: string, package_name: string): strin
 // the parent directory), which is an ordinary "not downstream" rather than damage.
 function classify_manifest_absence(repository_path: string): TargetState | undefined {
 	if (!has_checkout(repository_path)) return 'missing_checkout'
-	if (!existsSync(path.join(repository_path, MANIFEST_NAME))) return 'not_downstream'
+	if (!existsSync(package_manifest.manifest_path(repository_path))) return 'not_downstream'
 
 	return undefined
 }

package/scripts/refactor/import-graph.ts

@@ -12,10 +12,12 @@ import { file_reader } from '#scripts/lib/read-file'
 const FROM_PATTERN = /\bfrom[ \t]*['"]([^'"\n]+)['"]/gu
 // A side-effect import carries no `from`: `import './register'`.
 const BARE_IMPORT_PATTERN = /^[ \t]*import[ \t]+['"]([^'"\n]+)['"]/gmu
-// The subpath import this package uses for cross-directory `scripts/` imports; `#scripts/x` resolves
-// to `scripts/x`. Relative specifiers resolve against the importer's directory.
-const SUBPATH_PREFIX = '#scripts/'
-const SCRIPTS_DIR = 'scripts'
+// The subpath imports this package uses for cross-directory imports; `#scripts/x` resolves to
+// `scripts/x` and `#tools/x` to `tools/x`. Relative specifiers resolve against the importer's directory.
+const SUBPATH_DIRECTORIES: ReadonlyArray<readonly [string, string]> = [
+	['#scripts/', 'scripts'],
+	['#tools/', 'tools'],
+]
 const RELATIVE_PREFIX = '.'
 // A specifier omits its extension, so a resolved base is tried against the real files these suffixes
 // would produce — a sibling module or a directory's index, in the order a resolver would.
@@ -38,9 +40,9 @@ function parse_imports(source: string): ReadonlyArray<string> {
 // Where a local specifier points before extension resolution, or `undefined` for a package import
 // this graph does not follow.
 function specifier_base(spec: string, importer: string, root: string): string | undefined {
-	if (spec.startsWith(SUBPATH_PREFIX)) {
-		return path.resolve(root, SCRIPTS_DIR, spec.slice(SUBPATH_PREFIX.length))
-	}
+	const subpath = SUBPATH_DIRECTORIES.find(([prefix]) => spec.startsWith(prefix))
+
+	if (subpath !== undefined) return path.resolve(root, subpath[1], spec.slice(subpath[0].length))
 
 	if (spec.startsWith(RELATIVE_PREFIX)) return path.resolve(path.dirname(importer), spec)
 

package/scripts/release/github-release-runs.ts

@@ -96,20 +96,31 @@ async function is_release_lost(source: RunSource, tag: string): Promise<boolean>
 	return run.status === 'completed' && (await is_release_over(source, tag))
 }
 
+async function publish_run(
+	source: RunSource,
+	workflow: string,
+	tag: string,
+): Promise<Run | undefined> {
+	return await find_run(source, workflow, `Publish ${tag}`)
+}
+
 // A run not listed yet is pending too: the announcement that starts this release also starts the
 // publication, so the release can ask before GitHub has queued that run.
+function run_state(run: Run | undefined): PollState {
+	if (run?.status !== 'completed') return 'pending'
+
+	return run.conclusion === 'success' ? 'ready' : 'failed'
+}
+
 async function publication_state(
 	source: RunSource,
 	workflow: string,
 	tag: string,
 ): Promise<PollState> {
-	const run = await find_run(source, workflow, `Publish ${tag}`)
-	if (run?.status !== 'completed') return 'pending'
-
-	return run.conclusion === 'success' ? 'ready' : 'failed'
+	return run_state(await publish_run(source, workflow, tag))
 }
 
-const github_release_runs = { is_release_lost, publication_state }
+const github_release_runs = { is_release_lost, publication_state, publish_run, run_state }
 
-export type { PollState, RunSource }
+export type { PollState, Run, RunSource }
 export { github_release_runs }

package/scripts/release/release-approval-prune.ts

@@ -0,0 +1,24 @@
+import { git_spawn } from '#scripts/git/git-spawn'
+
+// **A release drops every `josh metrics` approval the default branch holds** (joshuafolkken/kit#4187).
+// The release work tree is cut from `origin/<default>`, so every file it holds under the directory
+// belongs to an issue that already merged. Such a file is read only to tell it apart from a branch's
+// new one (`tools/metrics/metrics-ratchet.ts` → `fresh_approvals`): a branch's merge-base still holds
+// it unchanged, and a branch that merges the release in loses it on both sides, so removing it changes
+// no verdict. `--ignore-unmatch` makes a repository with no approvals a no-op.
+
+const APPROVAL_DIRECTORY = '.josh/metrics-accepted'
+const APPROVAL_PREFIX = `${APPROVAL_DIRECTORY}/`
+
+async function prune(): Promise<void> {
+	await git_spawn.read(['rm', '-r', '-q', '--ignore-unmatch', '--', APPROVAL_DIRECTORY])
+}
+
+// A repository-relative path under the approval directory.
+function is_approval(file: string): boolean {
+	return file.startsWith(APPROVAL_PREFIX)
+}
+
+const release_approval_prune = { APPROVAL_DIRECTORY, is_approval, prune }
+
+export { release_approval_prune }

package/scripts/release/release-history.ts

@@ -1,14 +1,12 @@
 import { git_command } from '#scripts/git/git-command'
 import { json_value } from '#scripts/lib/json-value'
+import { PACKAGE_JSON } from '#scripts/lib/package-manifest'
 import { package_with_version_schema } from '#scripts/lib/schemas'
-import { version_targets } from '#scripts/version/version-targets'
 import { release_plan, type ReleasePlan, type VersionedCommit } from './release-plan'
 
 // Reading main's history for the two numbers a release is made of: where the version last changed,
 // and how many merges have landed since.
 
-const { PACKAGE_JSON } = version_targets
-
 // How far back the search for "the commit that last changed the version" goes, counted in commits
 // that touched `package.json`. Once children stop bumping that file still
 // changes for every dependency update, so the base can sit several entries down — but a repository

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> {