@joshuafolkken/kit 1.1166.0 → 1.1229.0

package/scripts/notify/telegram-notify.ts

@@ -3,6 +3,10 @@ import { timed_fetch } from '#scripts/lib/timed-fetch'
 import { z } from 'zod'
 
 const TELEGRAM_API_BASE = 'https://api.telegram.org'
+// `sendMessage` refuses a text longer than this.
+const TELEGRAM_TEXT_LIMIT = 4096
+const BODY_TRUNCATION_MARK = '\n...'
+const TRAILING_HIGH_SURROGATE = /[\uD800-\uDBFF]$/u
 
 const telegram_environment_schema = z.object({
 	telegram_bot_token: z.string().min(1, { message: 'TELEGRAM_BOT_TOKEN is required' }),
@@ -188,10 +192,31 @@ function build_blocks(input: TelegramSendInput): Array<string> {
 	return blocks
 }
 
-function build_text(input: TelegramSendInput): string {
+function join_blocks(input: TelegramSendInput): string {
 	return build_blocks(input).join('\n\n')
 }
 
+// A cut between the two halves of a surrogate pair leaves a lone surrogate, which is not valid
+// UTF-8 once encoded, so the half is dropped with the rest of the tail.
+function head_of(body: string, kept: number): string {
+	const head = body.slice(0, kept)
+
+	return TRAILING_HIGH_SURROGATE.test(head) ? head.slice(0, -1) : head
+}
+
+// **The body is cut to fit Telegram's length limit, keeping its head** (joshuafolkken/kit#3242). A
+// warning carrying a whole driver stderr ran past 4096 characters and was refused with `400 Bad
+// Request`, so it reached nobody. A caller puts the cause first, so the tail is what is dropped, and the
+// header and the URLs around the body survive.
+function build_text(input: TelegramSendInput): string {
+	const text = join_blocks(input)
+	const overflow = text.length - TELEGRAM_TEXT_LIMIT
+	if (overflow <= 0 || input.body === undefined) return text
+	const kept = Math.max(0, input.body.length - overflow - BODY_TRUNCATION_MARK.length)
+
+	return join_blocks({ ...input, body: `${head_of(input.body, kept)}${BODY_TRUNCATION_MARK}` })
+}
+
 async function post_message(config: TelegramConfig, text: string): Promise<void> {
 	const url = `${TELEGRAM_API_BASE}/bot${config.bot_token}/sendMessage`
 	const response = await timed_fetch(url, {

package/scripts/notify/telegram-test.ts

@@ -6,13 +6,19 @@ import { git_gh_repo } from '#scripts/gh/git-gh-repo'
 import { github_issue_url, type IssueUrlTarget } from '#scripts/gh/github-issue-url'
 import { git_error } from '#scripts/git/git-error'
 import { josh_environment_file } from '#scripts/josh/josh-environment-file'
+import { cli_flags } from '#scripts/lib/cli-flags'
 import { telegram_notify } from './telegram-notify'
 import { telegram_test_logic, type CliValues, type ResolvedContext } from './telegram-test-logic'
 
 const REPO_NAME_SEPARATOR = '/'
+const ARGV_OFFSET = 2
+
+// The free-text values a caller writes, often opening with a Markdown `-` bullet.
+const FREE_TEXT_FLAGS = ['--body', '--issue-title']
 
 function parse_cli_arguments(): CliValues {
 	const { values } = parseArgs({
+		args: [...cli_flags.attach_values(process.argv.slice(ARGV_OFFSET), FREE_TEXT_FLAGS)],
 		options: {
 			'task-type': { type: 'string' },
 			'repo-name': { type: 'string' },

package/scripts/observations/observation-ledger-line.ts

@@ -34,16 +34,16 @@ function slug_of(first_field: string): string {
 
 // The `?? ''` lives in these small helpers rather than in `field_reason`, so that function stays a
 // single lookup with no branching of its own.
-function is_present(field: string | undefined): boolean {
-	return (field ?? '').trim().length > 0
+function is_present(field: string | undefined = ''): boolean {
+	return field.trim().length > 0
 }
 
-function matches(pattern: RegExp, field: string | undefined): boolean {
-	return pattern.test(field ?? '')
+function matches(pattern: RegExp, field: string | undefined = ''): boolean {
+	return pattern.test(field)
 }
 
-function slug_ok(key_field: string | undefined): boolean {
-	return SLUG_PATTERN.test(slug_of(key_field ?? ''))
+function slug_ok(key_field: string | undefined = ''): boolean {
+	return SLUG_PATTERN.test(slug_of(key_field))
 }
 
 // Each field's check paired with the reason it fails, so `field_reason` is a single lookup for the

package/scripts/observations/observation-ledger-migrate.ts

@@ -1,8 +1,18 @@
-import { appendFileSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync } from 'node:fs'
+import {
+	appendFileSync,
+	mkdirSync,
+	readdirSync,
+	readFileSync,
+	renameSync,
+	rmdirSync,
+	rmSync,
+} from 'node:fs'
 import path from 'node:path'
 import { file_reader } from '#scripts/lib/read-file'
 import {
+	LEDGER_FILE_EXTENSION,
 	LEGACY_LEDGER_FILE,
+	LEGACY_OBSERVATION_LEDGER_DIRECTORY,
 	LEGACY_OBSERVATION_LEDGER_PATHS,
 	MIGRATION_CLAIM_SUFFIX,
 	OBSERVATION_LEDGER_DIRECTORY,
@@ -136,14 +146,55 @@ function migrate_one(legacy: string, target: string): boolean {
 	return true
 }
 
+// The ledger file a name in the old directory belongs to — a claim `<name>.md.<pid>.migrating` left by
+// a killed process included, whose `<name>.md` may already be gone.
+function source_name(name: string): string | undefined {
+	const end = name.indexOf(LEDGER_FILE_EXTENSION)
+
+	return end === -1 ? undefined : name.slice(0, end + LEDGER_FILE_EXTENSION.length)
+}
+
+function legacy_directory_names(directory: string): ReadonlyArray<string> {
+	try {
+		const names = readdirSync(directory).map((name) => source_name(name))
+
+		return [...new Set(names.filter((name) => name !== undefined))]
+	} catch {
+		return []
+	}
+}
+
+// **The old directory moves file by file into the same names** (joshuafolkken/kit#3341), so an
+// issue's lines stay in that issue's file; the emptied directory is removed when nothing else is left.
+function migrate_directory(root: string): boolean {
+	const legacy_directory = path.join(root, LEGACY_OBSERVATION_LEDGER_DIRECTORY)
+	const did_move = legacy_directory_names(legacy_directory)
+		.map((name) =>
+			migrate_one(
+				path.join(legacy_directory, name),
+				path.join(root, OBSERVATION_LEDGER_DIRECTORY, name),
+			),
+		)
+		.some(Boolean)
+
+	try {
+		rmdirSync(legacy_directory)
+	} catch {
+		// Absent, or still holding something that is not the ledger's — left where it is.
+	}
+
+	return did_move
+}
+
 // Returns whether anything was moved. `root` is the checkout the ledger lives in. Every old path is
 // tried — `map` before `some`, so one that moved does not leave the next one where it was.
 function migrate(root: string): boolean {
 	const target = path.join(root, OBSERVATION_LEDGER_DIRECTORY, LEGACY_LEDGER_FILE)
-
-	return LEGACY_OBSERVATION_LEDGER_PATHS.map((legacy) =>
+	const moved_files = LEGACY_OBSERVATION_LEDGER_PATHS.map((legacy) =>
 		migrate_one(path.join(root, legacy), target),
-	).some(Boolean)
+	)
+
+	return [...moved_files, migrate_directory(root)].some(Boolean)
 }
 
 const observation_ledger_migrate = { migrate }

package/scripts/observations/observation-ledger.ts

@@ -4,14 +4,24 @@
 // tree, and `observations-flush.ts` commits what no run carried — so a literal in each would be three
 // answers to one question, and a rename reaching only some of them would silently split them.
 //
-// **It sits under `docs/maintainers/`, apart from the reader-facing documents** (joshuafolkken/kit#2724).
+// **It sits outside `docs/`** (joshuafolkken/kit#3341): its files are machine-written data lines, not
+// documents a person reads, and at about forty new files a day they were most of `docs/`.
 //
 // **It is a directory of one file per issue, not one file** (joshuafolkken/kit#2919). One file every
 // run appended to made two lanes' pull requests conflict at its tail, so lanes parked their lines in
 // the primary checkout for a batch-end flush — and another run's stash took them from there, and the
 // flush never saw them. A run now appends to `<issue>.md` in its own work tree and merges it with its
 // own pull request: parallel lanes write different files, so nothing conflicts and nothing waits.
-const OBSERVATION_LEDGER_DIRECTORY = 'docs/maintainers/observations'
+const OBSERVATION_LEDGER_DIRECTORY = '.josh/observations'
+
+// Where the directory lived until joshuafolkken/kit#3341, a migration source for the same reasons as
+// the single-file ledgers below: each `<name>.md` in it moves to the same name in the directory.
+const LEGACY_OBSERVATION_LEDGER_DIRECTORY = 'docs/maintainers/observations'
+
+const LEDGER_DIRECTORIES: ReadonlyArray<string> = [
+	OBSERVATION_LEDGER_DIRECTORY,
+	LEGACY_OBSERVATION_LEDGER_DIRECTORY,
+]
 
 const LEDGER_FILE_EXTENSION = '.md'
 
@@ -51,18 +61,25 @@ function is_ledger_file_name(name: string): boolean {
 // (`observation-ledger-migrate.ts`): `docs/observations.md.<pid>.migrating`.
 const MIGRATION_CLAIM_SUFFIX = '.migrating'
 
+function is_legacy_directory_file(file_path: string): boolean {
+	return file_path.startsWith(`${LEGACY_OBSERVATION_LEDGER_DIRECTORY}/`)
+}
+
 // A claim left by a process killed mid-migration holds ledger lines, so it is the ledger too: never
 // staged by an ordinary commit, and absorbed by the next migration.
 function is_migration_claim(file_path: string): boolean {
-	return LEGACY_OBSERVATION_LEDGER_PATHS.some(
-		(legacy) => file_path.startsWith(`${legacy}.`) && file_path.endsWith(MIGRATION_CLAIM_SUFFIX),
+	if (!file_path.endsWith(MIGRATION_CLAIM_SUFFIX)) return false
+
+	return (
+		is_legacy_directory_file(file_path) ||
+		LEGACY_OBSERVATION_LEDGER_PATHS.some((legacy) => file_path.startsWith(`${legacy}.`))
 	)
 }
 
-// Porcelain status collapses an untracked directory to `docs/maintainers/observations/`, so the
-// directory itself, trailing slash and all, is the ledger as much as any file inside it.
+// Porcelain status collapses an untracked directory to `.josh/observations/`, so the directory
+// itself, trailing slash and all, is the ledger as much as any file inside it — the old directory too.
 function is_in_directory(file_path: string): boolean {
-	return file_path.startsWith(`${OBSERVATION_LEDGER_DIRECTORY}/`)
+	return LEDGER_DIRECTORIES.some((directory) => file_path.startsWith(`${directory}/`))
 }
 
 function is_ledger_path(file_path: string): boolean {
@@ -107,8 +124,10 @@ const observation_ledger = {
 }
 
 export {
+	LEDGER_DIRECTORIES,
 	LEDGER_FILE_EXTENSION,
 	LEGACY_LEDGER_FILE,
+	LEGACY_OBSERVATION_LEDGER_DIRECTORY,
 	LEGACY_OBSERVATION_LEDGER_PATHS,
 	MIGRATION_CLAIM_SUFFIX,
 	OBSERVATION_LEDGER_DIRECTORY,

package/scripts/overrides/lockfile-overrides.ts

@@ -1,6 +1,6 @@
 import { yaml_document } from '#scripts/lib/yaml-document'
 import { overrides_check } from './overrides-logic'
-import { lockfile_importers_schema, type LockfileImporter } from './schemas'
+import { lockfile_importers_schema, type LockfileImporter } from './overrides-schemas'
 
 // The importer sections whose entries pnpm rewrites through `overrides` before resolving.
 const DEPENDENCY_GROUPS = ['dependencies', 'devDependencies', 'optionalDependencies'] as const

package/scripts/overrides/overrides-logic.ts

@@ -3,7 +3,7 @@ import {
 	package_pnpm_schema,
 	package_with_deps_schema,
 	workspace_overrides_schema,
-} from './schemas'
+} from './overrides-schemas'
 
 interface AddedEntry {
 	key: string

package/scripts/propagate/propagate-git.ts

@@ -3,6 +3,7 @@ import path from 'node:path'
 import { git_location_environment } from '#scripts/git/git-location-environment'
 import { ls_remote_branch_arguments } from '#scripts/git/git-ls-remote'
 import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
+import { GIT_TIMEOUT_MS } from '#scripts/lib/timeouts'
 
 // The git probes propagation needs before it writes anything into a working tree.
 //
@@ -11,7 +12,6 @@ import { git_spawn_sync } from '#scripts/git/git-spawn-sync'
 // its remote would propagate the *previous* release, which is already published and would report
 // success (joshuafolkken/kit#863).
 
-const GIT_TIMEOUT_MS = 10_000
 // The probes that talk to the remote get their own budget. Ten seconds is generous for a local
 // `rev-parse` and tight for an ssh handshake, and a probe that times out answers "no" — which for
 // the two below would report a push that never reached origin as a push nobody attempted.

package/scripts/propagate/propagate-publish.ts

@@ -1,5 +1,6 @@
 import { git_gh_exec } from '#scripts/gh/git-gh-exec'
 import { poll } from '#scripts/lib/poll'
+import { GH_API_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { with_page_size } from '#scripts/version/version-remote'
 
 // Waiting for a specific version of this package to actually exist in the registry.
@@ -14,7 +15,6 @@ const VERSIONS_PAGE_SIZE = 100
 const NAMES_JQ = '[.[] | .name]'
 const DEFAULT_TIMEOUT_MS = 600_000
 const DEFAULT_INTERVAL_MS = 15_000
-const GH_TIMEOUT_MS = 20_000
 // How many probes in a row may fail before the registry is called unreadable. One failure is a rate
 // limit, a 5xx or a DNS hiccup — ending a ten-minute wait seconds in, on the first of those, is the
 // opposite of waiting. Only a registry that fails this many times running is a broken one.
@@ -60,7 +60,7 @@ function fetch_published_versions(versions_endpoint: string): Array<string> | un
 	const stdout = git_gh_exec.read_gh_api_sync({
 		path: endpoint,
 		jq_filter: NAMES_JQ,
-		timeout_ms: GH_TIMEOUT_MS,
+		timeout_ms: GH_API_TIMEOUT_MS,
 	})
 	if (stdout === undefined) return undefined
 

package/scripts/propagate/propagate-steps.ts

@@ -4,7 +4,8 @@ import { git_gh_issue_write } from '#scripts/gh/git-gh-issue-write'
 import { OTHER_CHANGE_LABEL } from '#scripts/issue/issue-labels'
 import { GATE_COMMAND } from '#scripts/josh/josh-command-types'
 import { error_text } from '#scripts/lib/error-message'
-import { build_upgrade_shell_command } from '#scripts/version/upgrade-shell-command'
+import { SUITE_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import { build_upgrade_command } from '#scripts/version/upgrade-shell-command'
 import { create_version_command_config } from '#scripts/version/version-command-config'
 import { execaSync } from 'execa'
 import { propagate_git } from './propagate-git'
@@ -20,9 +21,6 @@ import type { PropagateTarget } from './propagate-targets'
 // and the sequencing stays testable (joshuafolkken/kit#863).
 
 const SUCCESS_EXIT_CODE = 0
-// Long enough for a consumer's full unit suite and a `pnpm add`, short enough that a hung step ends
-// the run instead of holding the whole propagation open.
-const STEP_TIMEOUT_MS = 1_800_000
 // The consumer-side gate. `josh gate` is the same command the AI documents require of a person
 // (joshuafolkken/kit#914) — running the four checks concurrently and reporting every failure in one
 // pass — so the chain is not repeated here. It resolves in the consumer's directory, which by this
@@ -54,11 +52,15 @@ function sync_command(bin_name: string): ReadonlyArray<string> {
 // which would defeat the exact-version wait: a release published while the run was in flight would
 // be the one every consumer received. `josh adopt` names `latest` deliberately, because it is pulling
 // whatever is newest inward rather than carrying one known release outward. Built through kit's own
-// upgrade-command builder either way, so the lockfile repair it chains stays single-sourced.
-function upgrade_command(package_name: string, version: string): ReadonlyArray<string> {
+// upgrade-command builder either way, so the lockfile repair it chains stays single-sourced — and
+// its steps are argument vectors, so the version never passes through a shell.
+function upgrade_command(
+	package_name: string,
+	version: string,
+): ReadonlyArray<ReadonlyArray<string>> {
 	const config = create_version_command_config({ package_name })
 
-	return ['sh', '-c', build_upgrade_shell_command(version, true, config)]
+	return build_upgrade_command(version, true, config).steps
 }
 
 const PROPAGATE_ORIGIN =
@@ -149,8 +151,8 @@ const NO_COMMAND = 'no command defined'
 // tail would throw on its first `replaceAll`, and nothing between here and the report catches it:
 // the throw escapes the whole run, so every consumer after this one goes unattempted and the
 // end-of-run block is never printed — "one consumer's failure never stops another", lost to a crash.
-function captured(text: string | undefined): string {
-	return text ?? ''
+function captured(text: string | undefined = ''): string {
+	return text
 }
 
 function step_result(step: string, exit_code: number | undefined): StepResult {
@@ -172,7 +174,7 @@ function spawn_step(
 		cwd: target.path,
 		reject: false,
 		stdio: 'inherit',
-		timeout: STEP_TIMEOUT_MS,
+		timeout: SUITE_TIMEOUT_MS,
 	})
 
 	return step_result(step, spawned.exitCode)
@@ -207,7 +209,7 @@ function spawn_captured(
 		stdin: 'inherit',
 		stdout: ['inherit', 'pipe'],
 		stderr: ['inherit', 'pipe'],
-		timeout: STEP_TIMEOUT_MS,
+		timeout: SUITE_TIMEOUT_MS,
 	})
 
 	return {
@@ -383,11 +385,14 @@ function run_each(
 	return { step, is_ok: true }
 }
 
+// One entry per step, so `run_each` stops a toolkit's lockfile repair after its failed install.
 function upgrade_commands(plan: ReleasePlan): ReadonlyArray<ToolkitCommand> {
-	return plan.releases.map((release) => ({
-		package_name: release.package_name,
-		command: upgrade_command(release.package_name, release.version),
-	}))
+	return plan.releases.flatMap((release) =>
+		upgrade_command(release.package_name, release.version).map((command) => ({
+			package_name: release.package_name,
+			command,
+		})),
+	)
 }
 
 function sync_commands(plan: ReleasePlan): ReadonlyArray<ToolkitCommand> {

package/scripts/propagate/propagate.ts

@@ -24,8 +24,7 @@ const SKIP_PUBLISH_FLAG = '--skip-publish-wait'
 const DRY_RUN_FLAG = '--dry-run'
 const TARGET_FLAG = '--target'
 const KNOWN_FLAGS: ReadonlyArray<string> = [SKIP_PUBLISH_FLAG, DRY_RUN_FLAG]
-// Shown in the usage line only. `--target` carries a value, so it is taken out of argv before the
-// flag-only refusal runs, and this entry never has to match an argument.
+// Shown in the usage line only: `--target` carries a value, so it is spelled with a placeholder.
 const TARGET_USAGE = `${TARGET_FLAG} <repo>`
 const DRY_RUN_REASON = 'would be propagated'
 const UNTOUCHED_NOTE = 'No consumer was touched.'
@@ -40,41 +39,51 @@ interface RunOptions {
 	usage?: string
 }
 
-interface TargetArgument {
-	rest: Array<string>
-	target?: string
-	usage?: string
+// `--target` is read as a list so a second one is seen and refused rather than letting one of the two
+// names win silently.
+const OPTIONS = {
+	'skip-publish-wait': { type: 'boolean' },
+	'dry-run': { type: 'boolean' },
+	target: { type: 'string', multiple: true },
+} as const
+const USAGE = `Usage: josh propagate [${[...KNOWN_FLAGS, TARGET_USAGE].join('] [')}]`
+const TARGET_MISSING = `${TARGET_FLAG} needs a repository name, e.g. ${TARGET_FLAG} app-kit`
+
+type ParsedValues = NonNullable<ReturnType<typeof cli_flags.values_of<typeof OPTIONS>>>
+
+function refused(usage: string): RunOptions {
+	return { is_dry_run: false, is_publish_wait_skipped: false, usage }
 }
 
-// Take `--target <repo>` out of argv. A second `--target` stays in `rest`, where the flag-only
-// refusal rejects it rather than letting one of the two names win silently.
-function split_target(argv: ReadonlyArray<string>): TargetArgument {
-	const index = argv.indexOf(TARGET_FLAG)
-	if (index === -1) return { rest: [...argv] }
-	const target = argv[index + 1]
-	const rest = argv.filter((_, position) => position !== index && position !== index + 1)
+function to_options(values: ParsedValues): RunOptions {
+	const [target] = values.target ?? []
 
-	if (target === undefined || target.startsWith('-')) {
-		return { rest, usage: `${TARGET_FLAG} needs a repository name, e.g. ${TARGET_FLAG} app-kit` }
+	return {
+		is_dry_run: values['dry-run'] ?? false,
+		is_publish_wait_skipped: values['skip-publish-wait'] ?? false,
+		...(target !== undefined && { target }),
 	}
-
-	return { rest, target }
 }
 
 // Reject anything not on the list rather than ignoring it. `--dryrun` silently falling through to
-// the real write path is the mistake this refusal exists to prevent.
+// the real write path is the mistake this refusal exists to prevent. A `--target` with no usable name
+// after it — last on the line, or followed by `--dry-run` — is named on its own, so the caller learns
+// which value is missing rather than reading the generic usage.
+function read_values(argv: ReadonlyArray<string>): ParsedValues | undefined {
+	const values = cli_flags.values_of(argv, OPTIONS)
+
+	return (values?.target?.length ?? 0) > 1 ? undefined : values
+}
+
 function parse_options(argv: ReadonlyArray<string>): RunOptions {
-	const { rest, target, usage: target_usage } = split_target(argv)
-	const options: RunOptions = {
-		is_dry_run: rest.includes(DRY_RUN_FLAG),
-		is_publish_wait_skipped: rest.includes(SKIP_PUBLISH_FLAG),
-		...(target !== undefined && { target }),
+	if (cli_flags.is_value_unusable(argv, TARGET_FLAG)) return refused(TARGET_MISSING)
+	const values = read_values(argv)
+
+	if (values === undefined) {
+		return refused(`Unknown argument(s) or a repeated ${TARGET_FLAG}: ${argv.join(' ')}\n${USAGE}`)
 	}
-	const usage =
-		target_usage ??
-		cli_flags.refuse_unknown_flags(rest, [...KNOWN_FLAGS, TARGET_USAGE], 'propagate')
 
-	return usage === undefined ? options : { ...options, usage }
+	return to_options(values)
 }
 
 // Propagation runs from the supplier's own repository, and only there — kit's, or a toolkit's built

package/scripts/refactor/import-graph.ts

@@ -28,7 +28,7 @@ type FileGraph = ReadonlyMap<string, ReadonlySet<string>>
 function specifiers_of(source: string, pattern: RegExp): ReadonlyArray<string> {
 	const matches = [...source.matchAll(pattern)]
 
-	return matches.flatMap((match) => (match[1] === undefined ? [] : [match[1]]))
+	return matches.flatMap((match) => match[1] ?? [])
 }
 
 function parse_imports(source: string): ReadonlyArray<string> {
@@ -157,6 +157,22 @@ function expand(
 	return included
 }
 
+// Every file `entry` reaches through its own imports, `entry` included, with no stage cap — the whole
+// transitive closure a running script loads, not the §4.3 neighborhood `expand` bounds.
+function reachable(entry: string, forward: FileGraph): ReadonlySet<string> {
+	const included = new Set<string>([entry])
+	const pending = [entry]
+
+	for (let file = pending.pop(); file !== undefined; file = pending.pop()) {
+		const fresh = [...(forward.get(file) ?? [])].filter((target) => !included.has(target))
+
+		for (const target of fresh) included.add(target)
+		pending.push(...fresh)
+	}
+
+	return included
+}
+
 // The whole §4.3 walk: build the graph over the universe, then expand the seed within it.
 function expand_scope(
 	seed: ReadonlyArray<string>,
@@ -174,6 +190,7 @@ const import_graph = {
 	expand_scope,
 	invert,
 	parse_imports,
+	reachable,
 	resolve_spec,
 	MAX_STAGES,
 }

package/scripts/refactor/refactor-lint.ts

@@ -1,5 +1,6 @@
 import path from 'node:path'
 import { find_local_bin_upwards } from '#scripts/build/local-bin'
+import { LINT_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execa } from 'execa'
 import { z } from 'zod'
 
@@ -20,7 +21,6 @@ const PNPM_EXEC = 'exec'
 // `--no-inline-config` so a `/* eslint-disable */` in a file cannot hide a candidate from the scan the
 // way it can from the gate; the scan reports what the rules say, not what a file asked to suppress.
 const FORMAT_FLAGS: ReadonlyArray<string> = ['--format', 'json', '--no-inline-config']
-const PROCESS_TIMEOUT_MS = 180_000
 
 type Priority = 'high' | 'medium' | 'low'
 const HIGH: Priority = 'high'
@@ -188,9 +188,9 @@ function eslint_command(root: string, files: ReadonlyArray<string>): ReadonlyArr
 // `undefined` means the run did not produce parseable eslint JSON — a failure, kept distinct from a
 // valid empty array (a clean scope), so a scan that could not run is never reported as `clear`
 // (joshuafolkken/kit#2180).
-function parse_results(raw: string | undefined): Array<LintResult> | undefined {
+function parse_results(raw: string | undefined = 'null'): Array<LintResult> | undefined {
 	try {
-		const parsed = results_schema.safeParse(JSON.parse(raw ?? 'null'))
+		const parsed = results_schema.safeParse(JSON.parse(raw))
 
 		return parsed.success ? parsed.data : undefined
 	} catch {
@@ -216,7 +216,7 @@ async function run_eslint_json(
 			reject: false,
 			stdout: 'pipe',
 			stderr: 'ignore',
-			timeout: PROCESS_TIMEOUT_MS,
+			timeout: LINT_TIMEOUT_MS,
 		})
 
 		return parse_results(result.stdout)

package/scripts/repo/repository-labels.ts

@@ -52,9 +52,9 @@ function label_names(labels: ReadonlyArray<LabelDefinition>): ReadonlyArray<stri
 
 // An unreadable listing is not an empty one: nothing is created, and every label is reported as
 // unconfirmed rather than as missing. An unresolved repository (no GitHub remote) is the same case.
-function unreadable(repo: string | undefined): ReadonlyArray<string> {
+function unreadable(repo: string | undefined = 'this repository'): ReadonlyArray<string> {
 	const names = label_names(REPOSITORY_LABELS)
-	const target = repo ?? 'this repository'
+	const target = repo
 
 	console.warn(
 		`  ⚠ could not read the labels of ${target}; make sure these exist: ${names.join(', ')}`,

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

@@ -72,9 +72,7 @@ function workflow_job_names(content: string): Array<string> {
 	const parsed = workflow_schema.safeParse(parse_yaml_safe(content))
 	if (!parsed.success) return []
 
-	return Object.values(parsed.data.jobs).flatMap((job) =>
-		job.name === undefined ? [] : [job.name],
-	)
+	return Object.values(parsed.data.jobs).flatMap((job) => job.name ?? [])
 }
 
 // The checks this repository should require: only those a workflow it has actually reports. A file

package/scripts/review/live-evidence.ts

@@ -16,12 +16,10 @@ import { test_declared_logic, type Verdict } from '#scripts/test/test-declared-l
 
 const EVIDENCE_HEADING = '## 実機証跡'
 
-function verdict_for(paths: ReadonlyArray<string>, body: string | undefined): Verdict {
+function verdict_for(paths: ReadonlyArray<string>, body: string | undefined = ''): Verdict {
 	if (test_declared_logic.runtime_files(paths).length === 0) return 'exempt'
 
-	return reproduction_measure.has_command_output(body ?? '', EVIDENCE_HEADING)
-		? 'satisfied'
-		: 'required'
+	return reproduction_measure.has_command_output(body, EVIDENCE_HEADING) ? 'satisfied' : 'required'
 }
 
 // The diff is this checkout's, so it answers for the named branch only when that is the one checked

package/scripts/review/review-brief-cli.ts

@@ -13,7 +13,7 @@ import { find_package_directory } from '#scripts/josh/josh-logic'
 import { path_decision } from '#scripts/josh/path-decision'
 import { stamp_file } from '#scripts/josh/stamp-file'
 import { openai_review_broker } from '#scripts/lane/openai-review-broker'
-import { run_ship_review } from '#scripts/run/run-ship-review'
+import { run_ship_review } from '#scripts/run/ship/run-ship-review'
 import { review_attest } from './review-attest'
 import { review_brief } from './review-brief'
 import { review_checkout, type ReviewCheckout } from './review-checkout'

package/scripts/review/review-finding-ledger.ts

@@ -1,7 +1,7 @@
 // The review-finding line's grammar, its category vocabulary and the aggregation over it — the single
 // place all three are defined (joshuafolkken/kit#2325). A `/code-review` round's findings evaporated
 // the moment they were fixed, so no one could say which category recurred. They now land in the same
-// append-only ledger the observation lines use (`docs/maintainers/observations/`), under a distinct `- rf:`
+// append-only ledger the observation lines use (`.josh/observations/`), under a distinct `- rf:`
 // prefix so `observation-ledger-line.ts`'s `- k:` grammar never treats them as its own — one ledger,
 // one commit path, a second line *type* rather than a second ledger.
 

package/scripts/review/review-findings-cli.ts

@@ -19,9 +19,7 @@ function zero_line(zero_rounds: number): string {
 }
 
 function format_report(counts: ReadonlyArray<CategoryCount>, zero_rounds: number): string {
-	if (counts.length === 0) {
-		return zero_rounds === 0 ? NO_FINDINGS : zero_line(zero_rounds)
-	}
+	if (counts.length === 0) return zero_rounds === 0 ? NO_FINDINGS : zero_line(zero_rounds)
 
 	const body = counts.map((entry) => count_line(entry)).join('\n')