@joshuafolkken/kit 1.1514.0 → 1.2114.0

package/scripts/lint/rename-cli.ts

@@ -0,0 +1,179 @@
+#!/usr/bin/env tsx
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { format_edited_payload } from '#scripts/hooks/format-edited-file'
+import { rename_identifier, type RenameRequest, type TypeScriptApi } from './rename-identifier'
+
+// `josh rename <old> <new> [--import <old-specifier> <new-specifier>] <file...>` — one identifier, and
+// the import specifier it moved with, renamed across files in one call (joshuafolkken/kit#5236), where
+// a lane would otherwise spend one Read and one Edit per file.
+//
+// **All or nothing**: a file the rename would not touch is named and nothing is written, since a path
+// passed by mistake means the file list is not the one the caller thinks it is. Each written file is
+// then formatted the way the edit hook formats an edited one — a Bash write gets no hook.
+
+const ARGV_OFFSET = 2
+const FAILURE_EXIT_CODE = 1
+const IMPORT_FLAG = '--import'
+const SPECIFIER_COUNT = 2
+// What the TypeScript parser reads whole; a `.svelte` file's markup would be parsed as script.
+const SCRIPT_EXTENSIONS: ReadonlySet<string> = new Set([
+	'.ts',
+	'.tsx',
+	'.mts',
+	'.cts',
+	'.js',
+	'.jsx',
+	'.mjs',
+	'.cjs',
+])
+const IDENTIFIER = /^[$A-Z_a-z][\w$]*$/u
+const USAGE = `Usage: josh rename <old-identifier> <new-identifier> [${IMPORT_FLAG} <old-specifier> <new-specifier>] <file...>`
+
+interface RenameArguments {
+	request: RenameRequest
+	files: ReadonlyArray<string>
+}
+
+interface FileRename {
+	file: string
+	text: string
+	count: number
+	is_taken: boolean
+}
+
+type Formatter = (files: ReadonlyArray<string>) => Promise<void>
+
+interface SplitArguments {
+	specifier: RenameRequest['specifier']
+	rest: ReadonlyArray<string>
+}
+
+function split_import(argv: ReadonlyArray<string>): SplitArguments | undefined {
+	const at = argv.indexOf(IMPORT_FLAG)
+
+	if (at === -1) return { specifier: undefined, rest: argv }
+	const [from, to] = argv.slice(at + 1, at + 1 + SPECIFIER_COUNT)
+	if (from === undefined || to === undefined) return undefined
+
+	return { specifier: [from, to], rest: argv.toSpliced(at, 1 + SPECIFIER_COUNT) }
+}
+
+function arguments_of(split: SplitArguments): RenameArguments | undefined {
+	const [old_name = '', new_name = '', ...files] = split.rest
+
+	if (!IDENTIFIER.test(old_name) || !IDENTIFIER.test(new_name)) return undefined
+
+	return { request: { old_name, new_name, specifier: split.specifier }, files }
+}
+
+function parse(argv: ReadonlyArray<string>): RenameArguments | undefined {
+	const split = split_import(argv)
+	const parsed = split === undefined ? undefined : arguments_of(split)
+
+	return parsed?.files.length === 0 ? undefined : parsed
+}
+
+function refuse(reason: string, files: ReadonlyArray<string>): number {
+	console.error(`josh rename: ${reason}: ${files.join(', ')} — nothing was written`)
+
+	return FAILURE_EXIT_CODE
+}
+
+function rename_all(api: TypeScriptApi, parsed: RenameArguments): ReadonlyArray<FileRename> {
+	return parsed.files.map((file) => ({
+		file,
+		...rename_identifier.rewrite(api, file, readFileSync(file, 'utf8'), parsed.request),
+	}))
+}
+
+async function write_all(
+	renames: ReadonlyArray<FileRename>,
+	formatter: Formatter,
+): Promise<number> {
+	for (const rename of renames) {
+		writeFileSync(rename.file, rename.text)
+		console.info(`${rename.file}: ${String(rename.count)}`)
+	}
+
+	await formatter(renames.map((rename) => rename.file))
+
+	return 0
+}
+
+function file_refusal(files: ReadonlyArray<string>): number | undefined {
+	const missing = files.filter((file) => !existsSync(file))
+	if (missing.length > 0) return refuse('no such file', missing)
+	const unparsed = files.filter((file) => !SCRIPT_EXTENSIONS.has(path.extname(file)))
+
+	return unparsed.length > 0 ? refuse('not a TypeScript or JavaScript file', unparsed) : undefined
+}
+
+function files_where(
+	renames: ReadonlyArray<FileRename>,
+	is_match: (rename: FileRename) => boolean,
+): ReadonlyArray<string> {
+	return renames.filter((rename) => is_match(rename)).map((rename) => rename.file)
+}
+
+// The rename matches by spelling, so a file that already binds the new name could end up with one
+// binding shadowing or merging with another; it is refused rather than guessed at.
+function rename_refusal(renames: ReadonlyArray<FileRename>, new_name: string): number | undefined {
+	const untouched = files_where(renames, (rename) => rename.count === 0)
+	if (untouched.length > 0) return refuse('no replacement', untouched)
+	const taken = files_where(renames, (rename) => rename.is_taken)
+
+	return taken.length > 0 ? refuse(`\`${new_name}\` is already bound`, taken) : undefined
+}
+
+async function apply(
+	api: TypeScriptApi,
+	parsed: RenameArguments,
+	formatter: Formatter,
+): Promise<number> {
+	const file_stop = file_refusal(parsed.files)
+	if (file_stop !== undefined) return file_stop
+	const renames = rename_all(api, parsed)
+
+	return rename_refusal(renames, parsed.request.new_name) ?? (await write_all(renames, formatter))
+}
+
+// The edit hook's own formatter, one file at a time: each run rewrites the file the next may import.
+async function format_files(
+	files: ReadonlyArray<string>,
+	format_one: typeof format_edited_payload = format_edited_payload,
+): Promise<void> {
+	for (const file of files) {
+		const payload = JSON.stringify({ tool_input: { file_path: path.resolve(file) } })
+		// eslint-disable-next-line no-await-in-loop -- formatters rewrite files the next run reads
+		const diagnostics = await format_one(payload, process.cwd())
+
+		if (diagnostics !== undefined) console.info(diagnostics)
+	}
+}
+
+async function run(
+	argv: ReadonlyArray<string>,
+	api: TypeScriptApi,
+	formatter: Formatter = format_files,
+): Promise<number> {
+	const parsed = parse(argv)
+
+	if (parsed !== undefined) return await apply(api, parsed, formatter)
+	console.error(USAGE)
+
+	return FAILURE_EXIT_CODE
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<void> {
+	const typescript = await import('typescript')
+
+	process.exitCode = await run(argv, typescript.default)
+}
+
+const rename_cli = { USAGE, format_files, main, run }
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
+
+export { rename_cli }

package/scripts/lint/rename-identifier.ts

@@ -0,0 +1,192 @@
+import type ts from 'typescript'
+
+// The rewrite behind `josh rename` (joshuafolkken/kit#5236): one identifier and, optionally, one import
+// specifier, renamed through the TypeScript parse tree rather than a pattern.
+//
+// **Only a binding is renamed, never a key.** `obj.old`, `{ old: 1 }` and `{ old: x } = obj` name a
+// property of some other value, so they stay; a shorthand `{ old }` keeps its key and becomes
+// `{ old: new }`. Strings and comments are not identifiers to the parser, so the walk never reaches
+// them — a specifier is rewritten only where the module system reads it.
+
+type TypeScriptApi = typeof ts
+
+interface RenameRequest {
+	old_name: string
+	new_name: string
+	specifier?: readonly [string, string] | undefined
+}
+
+interface Replacement {
+	start: number
+	end: number
+	text: string
+}
+
+// `is_taken`: the new name is already a binding here, so the rename could shadow or merge with it —
+// the rename matches by spelling, not by scope.
+interface RenameResult {
+	text: string
+	count: number
+	is_taken: boolean
+}
+
+// Calls whose first argument is a module specifier the test runner resolves like an import.
+const MODULE_CALLS: ReadonlySet<string> = new Set([
+	'vi.mock',
+	'vi.doMock',
+	'vi.importActual',
+	'vi.importMock',
+])
+const NAME_KEY = 'name'
+
+// The parents whose `name` is a property key rather than a binding.
+function key_parent_kinds(api: TypeScriptApi): ReadonlySet<ts.SyntaxKind> {
+	const kind = api.SyntaxKind
+
+	return new Set([
+		kind.PropertyAccessExpression,
+		kind.PropertyAssignment,
+		kind.PropertyDeclaration,
+		kind.PropertySignature,
+		kind.MethodDeclaration,
+		kind.MethodSignature,
+		kind.GetAccessor,
+		kind.SetAccessor,
+		kind.EnumMember,
+		kind.JsxAttribute,
+	])
+}
+
+function is_key_position(api: TypeScriptApi, node: ts.Identifier): boolean {
+	const { parent } = node
+
+	if (api.isQualifiedName(parent)) return parent.right === node
+	if (api.isBindingElement(parent)) return parent.propertyName === node
+
+	return key_parent_kinds(api).has(parent.kind) && Reflect.get(parent, NAME_KEY) === node
+}
+
+// A shorthand key is also the property's name, so the key is spelled out to keep it.
+function keeps_key(api: TypeScriptApi, node: ts.Identifier): boolean {
+	const { parent } = node
+
+	if (api.isShorthandPropertyAssignment(parent)) return true
+
+	return (
+		api.isBindingElement(parent) &&
+		parent.propertyName === undefined &&
+		parent.dotDotDotToken === undefined &&
+		api.isObjectBindingPattern(parent.parent)
+	)
+}
+
+function identifier_replacement(
+	api: TypeScriptApi,
+	node: ts.Identifier,
+	request: RenameRequest,
+): Replacement | undefined {
+	if (node.text !== request.old_name || is_key_position(api, node)) return undefined
+	const text = keeps_key(api, node) ? `${node.text}: ${request.new_name}` : request.new_name
+
+	return { start: node.getStart(), end: node.getEnd(), text }
+}
+
+function is_module_call(
+	api: TypeScriptApi,
+	call: ts.CallExpression,
+	node: ts.StringLiteral,
+): boolean {
+	if (call.arguments.indexOf(node) !== 0) return false
+
+	return (
+		call.expression.kind === api.SyntaxKind.ImportKeyword ||
+		MODULE_CALLS.has(call.expression.getText())
+	)
+}
+
+function is_module_specifier(api: TypeScriptApi, node: ts.StringLiteral): boolean {
+	const { parent } = node
+
+	if (api.isImportDeclaration(parent) || api.isExportDeclaration(parent)) {
+		return parent.moduleSpecifier === node
+	}
+
+	if (api.isCallExpression(parent)) return is_module_call(api, parent, node)
+
+	return api.isLiteralTypeNode(parent) && api.isImportTypeNode(parent.parent)
+}
+
+function specifier_replacement(
+	api: TypeScriptApi,
+	node: ts.StringLiteral,
+	specifier: RenameRequest['specifier'],
+): Replacement | undefined {
+	if (specifier?.[0] !== node.text || !is_module_specifier(api, node)) return undefined
+	const start = node.getStart()
+	const quote = node.getSourceFile().text.charAt(start)
+
+	return { start, end: node.getEnd(), text: `${quote}${specifier[1]}${quote}` }
+}
+
+function replacement_at(
+	api: TypeScriptApi,
+	node: ts.Node,
+	request: RenameRequest,
+): Replacement | undefined {
+	if (api.isIdentifier(node)) return identifier_replacement(api, node, request)
+	if (api.isStringLiteral(node)) return specifier_replacement(api, node, request.specifier)
+
+	return undefined
+}
+
+// `forEachChild` never descends into JSDoc, so a name inside a doc comment stays as written.
+function collect(
+	api: TypeScriptApi,
+	node: ts.Node,
+	request: RenameRequest,
+	into: Array<Replacement>,
+): void {
+	const replacement = replacement_at(api, node, request)
+
+	if (replacement !== undefined) into.push(replacement)
+	api.forEachChild(node, (child) => {
+		collect(api, child, request, into)
+	})
+}
+
+// Applied from the end of the file backwards, so an earlier offset is never moved by a later edit.
+function apply(text: string, replacements: ReadonlyArray<Replacement>): string {
+	const backwards = replacements.toSorted((first, second) => second.start - first.start)
+	let result = text
+
+	for (const edit of backwards) {
+		result = `${result.slice(0, edit.start)}${edit.text}${result.slice(edit.end)}`
+	}
+
+	return result
+}
+
+function rewrite(
+	api: TypeScriptApi,
+	file_name: string,
+	text: string,
+	request: RenameRequest,
+): RenameResult {
+	const source = api.createSourceFile(file_name, text, api.ScriptTarget.Latest, true)
+	const replacements: Array<Replacement> = []
+	const existing: Array<Replacement> = []
+
+	collect(api, source, request, replacements)
+	collect(api, source, { old_name: request.new_name, new_name: request.new_name }, existing)
+
+	return {
+		text: apply(text, replacements),
+		count: replacements.length,
+		is_taken: existing.length > 0,
+	}
+}
+
+const rename_identifier = { rewrite }
+
+export type { RenameRequest, RenameResult, TypeScriptApi }
+export { rename_identifier }

package/scripts/lint/type-only-imports.ts

@@ -0,0 +1,58 @@
+import type ts from 'typescript'
+
+// The module specifiers a file names only for their types: an `import type` or an
+// `export type … from` declaration, which the transpiler drops whole, so the test runner's module graph
+// never holds the edge (joshuafolkken/kit#5368). An `import { type A }` is left out: under
+// `verbatimModuleSyntax` it stays as a side-effect import. A declaration is matched to the reference
+// `preProcessFile` reports by where its specifier sits, never by its text, so a value import of the
+// same module keeps its edge whichever declarations `preProcessFile` lists.
+type TypeScript = typeof ts
+type ModuleDeclaration = ts.ImportDeclaration | ts.ExportDeclaration
+
+function declaration_of(
+	typescript: TypeScript,
+	statement: ts.Statement,
+): ModuleDeclaration | undefined {
+	if (typescript.isImportDeclaration(statement)) return statement
+	if (typescript.isExportDeclaration(statement)) return statement
+
+	return undefined
+}
+
+function is_type_only(typescript: TypeScript, declaration: ModuleDeclaration): boolean {
+	if (typescript.isExportDeclaration(declaration)) return declaration.isTypeOnly
+
+	return declaration.importClause?.phaseModifier === typescript.SyntaxKind.TypeKeyword
+}
+
+// Where the specifier's literal starts, its opening quote — the `pos` `preProcessFile` reports.
+function type_only_position(
+	typescript: TypeScript,
+	source: ts.SourceFile,
+	statement: ts.Statement,
+): number | undefined {
+	const declaration = declaration_of(typescript, statement)
+	if (declaration === undefined || !is_type_only(typescript, declaration)) return undefined
+	const specifier = declaration.moduleSpecifier
+	if (specifier === undefined || !typescript.isStringLiteral(specifier)) return undefined
+
+	return specifier.getStart(source)
+}
+
+// The specifiers `preProcessFile` finds less the type-only declarations': the edges the test runner
+// follows.
+function runtime_specifiers(typescript: TypeScript, file: string, content: string): Array<string> {
+	const source = typescript.createSourceFile(file, content, typescript.ScriptTarget.Latest)
+	const type_only = new Set(
+		source.statements.map((statement) => type_only_position(typescript, source, statement)),
+	)
+
+	return typescript
+		.preProcessFile(content, true, true)
+		.importedFiles.filter((reference) => !type_only.has(reference.pos))
+		.map((reference) => reference.fileName)
+}
+
+const type_only_imports = { runtime_specifiers }
+
+export { type_only_imports }

package/scripts/notify/confirmation-options.ts

@@ -15,7 +15,6 @@ interface Headings {
 	none: string
 }
 
-const JAPANESE_LANG_PREFIX = 'ja'
 const JAPANESE_HEADINGS: Headings = {
 	recommended: '推奨:',
 	alternatives: '他の選択肢:',
@@ -31,7 +30,7 @@ const ENGLISH_HEADINGS: Headings = {
 function headings(): Headings {
 	const { lang } = session_language.resolve_session_lang()
 
-	return lang.toLowerCase().startsWith(JAPANESE_LANG_PREFIX) ? JAPANESE_HEADINGS : ENGLISH_HEADINGS
+	return session_language.is_japanese(lang) ? JAPANESE_HEADINGS : ENGLISH_HEADINGS
 }
 
 // An empty list is stated as none, so a confirmation with no other option says so rather than

package/scripts/notify/telegram-notify.ts

@@ -1,5 +1,6 @@
 import { gh_spawn } from '#scripts/gh/gh-spawn'
 import { timed_fetch } from '#scripts/lib/timed-fetch'
+import { token_shape } from '#scripts/lib/token-shape'
 import { z } from 'zod'
 import { confirmation_options, type ConfirmationOptions } from './confirmation-options'
 import { notify_opt_in } from './notify-opt-in'
@@ -20,14 +21,14 @@ const telegram_environment_schema = z.object({
 // Sending `failure` (❌) there would say the merge failed, which is false and is
 // the more expensive lie of the two; sending `completion` (✅) twice says nothing went wrong, which
 // is the silence this type exists to end.
-// **`stalled` is not `warning`**. `warning` names a run that *finished* and
-// merged alongside something that did not work; a stall is the opposite — the run is alive and has not
-// finished, it has simply stopped advancing while ready work waits for a free lane. The ⏳ icon says
-// exactly that: not done, not broken, just not moving.
-// **`stranded` is not `stalled`**. A stall is a *live* run that is not
-// dispatching; a strand is the step before it — the run's own driver is gone. The session that cut the
-// budget handed it off and died, no successor claimed it, and no supervisor is watching, so nothing can
-// take the next step at all. The 🚨 icon says a run needs a hand, not that ready work is merely waiting.
+// **`idle` is not `warning`**. `warning` names a run that *finished* and
+// merged alongside something that did not work; an idle run is alive and has not finished — it has
+// nothing left to dispatch and no child running, so what remains waits on a person. The 💤 icon says
+// exactly that: not done, not broken, just waiting for a hand.
+// **`stranded` is not `idle`**. An idle run still has a driver watching the
+// backlog; a stranded one has none. The session that cut the budget handed it off and died, no
+// successor claimed it, and no supervisor is watching, so nothing can take the next step at all. The
+// 🚨 icon says a run needs a hand to keep running at all.
 type TelegramTaskType =
 	| 'planning'
 	| 'completion'
@@ -35,7 +36,7 @@ type TelegramTaskType =
 	| 'warning'
 	| 'kickoff_retry'
 	| 'confirmation'
-	| 'stalled'
+	| 'idle'
 	| 'stranded'
 	| 'progress'
 
@@ -68,7 +69,7 @@ const TASK_DEFINITIONS: Record<TelegramTaskType, TaskDefinition> = {
 	warning: { icon: '⚠️', label: 'Completed with a warning' },
 	kickoff_retry: { icon: '🔄', label: 'Kickoff retry' },
 	confirmation: { icon: '⏸️', label: 'Confirmation required' },
-	stalled: { icon: '⏳', label: 'Ready work is sitting undispatched' },
+	idle: { icon: '💤', label: 'Backlog run idle — nothing left to dispatch' },
 	stranded: { icon: '🚨', label: 'Run stranded — nobody is driving it' },
 	progress: { icon: '📊', label: 'Progress' },
 }
@@ -230,6 +231,14 @@ function build_text(input: TelegramSendInput): string {
 	return join_blocks({ ...input, body: `${head_of(input.body, kept)}${BODY_TRUNCATION_MARK}` })
 }
 
+// The text to send, refused when it holds a credential: the whole text is read, before the cut could
+// leave a head no shape matches.
+function outbound_text(input: TelegramSendInput): string {
+	token_shape.refuse(join_blocks(input), 'The Telegram message')
+
+	return build_text(input)
+}
+
 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, {
@@ -271,7 +280,7 @@ async function send(input: TelegramSendInput): Promise<void> {
 	}
 
 	const config = load_config()
-	const text = build_text(input)
+	const text = outbound_text(input)
 
 	try {
 		await post_message(config, text)
@@ -283,7 +292,7 @@ async function send(input: TelegramSendInput): Promise<void> {
 }
 
 // **The tolerant form**, for a caller whose job is something other than the notification.
-// `followup` sends the completion message on its way to the merge, and a gateway timeout at
+// `followup` sends the completion message beside the merge, and a gateway timeout at
 // Telegram is not a reason to leave a reviewed, green pull request unmerged. So the failure is
 // reported and the run carries on.
 //
@@ -298,7 +307,7 @@ async function send(input: TelegramSendInput): Promise<void> {
 //
 // **Not routed through `git_followup_cleanup`**, which is that Issue's mechanism: it guards the
 // steps a merge has already earned and says "failed after the merge" in its own wording, while this
-// send happens *before* the merge. Borrowing it would print a sentence that is not true.
+// send never happens *after* the merge. Borrowing it would print a sentence that is not true.
 function report_send_failure(error: unknown, recovery: string | undefined): void {
 	console.error('')
 	console.error(`❗ ${describe_symptom(error)}`)
@@ -389,25 +398,25 @@ async function confirm(input: ConfirmInput): Promise<boolean> {
 	)
 }
 
-interface StalledInput {
+interface IdleInput {
 	body: string
 	recovery: string
 }
 
 /**
- * Push the ⏳ stalled type — ready backlog work with a free lane that nothing has dispatched for a while.
- * Off-screen is the whole point: the state is invisible on the terminal until
- * a person asks, so it reaches them where they are not watching.
+ * Push the 💤 idle type — a backlog run with no child running and nothing left to dispatch.
+ * Off-screen is the whole point: what is left waits on a person, and the
+ * terminal shows that only to someone already watching.
  *
  * **`warn`'s shape exactly** — the repository looked up under the shared bound, the tolerant
- * `send_or_report` so a gateway timeout at Telegram never fails the detector that is only reporting, and
+ * `send_or_report` so a gateway timeout at Telegram never fails the loop that is only reporting, and
  * the caller's own `recovery` line. No `issue_title`: the header label already names what this is, and
  * the body carries what is waiting, so a title line would only repeat the header.
  */
-async function stalled(input: StalledInput): Promise<boolean> {
+async function idle(input: IdleInput): Promise<boolean> {
 	return await send_or_report(
 		{
-			task_type: 'stalled',
+			task_type: 'idle',
 			repo_name: gh_spawn.get_repo_name_with_owner_within(REPO_LOOKUP_TIMEOUT_MS),
 			issue_title: undefined,
 			body: input.body,
@@ -425,11 +434,11 @@ interface StrandedInput {
 
 /**
  * Push the 🚨 stranded type — a run whose driver is gone and which nothing can advance.
- * Off-screen is the whole point, as it is for `stalled`: the state is
+ * Off-screen is the whole point, as it is for `idle`: the state is
  * invisible on the terminal because the session that would show it has died, so the person hears about
  * it where they are not watching, rather than by asking.
  *
- * **`stalled`'s shape exactly** — the repository looked up under the shared bound, the tolerant
+ * **`idle`'s shape exactly** — the repository looked up under the shared bound, the tolerant
  * `send_or_report` so a Telegram timeout never fails the detector that is only reporting, and the
  * caller's own `recovery` line naming the command that hands the run to a fresh supervisor. No
  * `issue_title`: the header label already names what this is.
@@ -471,10 +480,10 @@ async function progress(body: string): Promise<boolean> {
 
 const telegram_notify = {
 	confirm,
+	idle,
 	progress,
 	send,
 	send_or_report,
-	stalled,
 	stranded,
 	warn,
 }

package/scripts/notify/telegram-test-logic.ts

@@ -28,7 +28,6 @@ const VALID_TASK_TYPES: ReadonlyArray<TelegramTaskType> = [
 	'warning',
 	'kickoff_retry',
 	'confirmation',
-	'stalled',
 ]
 
 const DEFAULT_TASK_TYPE: TelegramTaskType = 'planning'

package/scripts/notify/telegram-test-main.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { telegram_test } from './telegram-test'
+
+// The `josh notify` entry, kept apart from `telegram-test.ts` because the stop hook and
+// `run-stop-notify.ts` import that one: a bundle is one file, so a main guard there would fire for
+// every command that carries it (joshuafolkken/kit#4186). The flags are read from `process.argv`.
+if (process.argv[1] === fileURLToPath(import.meta.url)) await telegram_test.run_cli()

package/scripts/notify/telegram-test.ts

@@ -1,5 +1,3 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { git_gh_issue_read } from '#scripts/gh/git-gh-issue-read'
 import { git_gh_repo } from '#scripts/gh/git-gh-repo'
 import { github_issue_url, type IssueUrlTarget } from '#scripts/gh/github-issue-url'
@@ -141,8 +139,8 @@ async function main(): Promise<void> {
 // and exits non-zero. Both the message and the `cause` whose text `handle` also prints reach it
 // already free of the bot token and the chat id — `telegram_notify` redacts each before throwing.
 //
-// Separated from the `import.meta.url` guard so the wiring is reachable from a unit test; the guard
-// itself stays the canonical one the in-process dispatcher matches on.
+// The `josh notify` entry is `telegram-test-main.ts`, kept apart because other modules import this one
+// (joshuafolkken/kit#4186).
 async function run_cli(): Promise<void> {
 	try {
 		await main()
@@ -151,8 +149,6 @@ async function run_cli(): Promise<void> {
 	}
 }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await run_cli()
-
 const telegram_test = { fetch_repo_name, fetch_issue_title, resolve_context, run_cli, send_values }
 
 export { telegram_test }

package/scripts/observations/observation-ledger.ts

@@ -89,6 +89,18 @@ function is_ledger_path(file_path: string): boolean {
 	)
 }
 
+// The git pathspec of every path but the ledger — the same paths `is_ledger_path` answers, for a git
+// command to leave out. `:/` and `top` anchor it at the repository root, so a command run from a
+// subdirectory still covers the whole tree and still leaves the root's ledger alone.
+const LEDGER_EXCLUSION_PATHSPEC: ReadonlyArray<string> = [
+	':/',
+	...LEDGER_DIRECTORIES.map((directory) => `:(top,exclude)${directory}`),
+	...LEGACY_OBSERVATION_LEDGER_PATHS.map((legacy) => `:(top,exclude)${legacy}`),
+	...LEGACY_OBSERVATION_LEDGER_PATHS.map(
+		(legacy) => `:(top,exclude,glob)${legacy}.*${MIGRATION_CLAIM_SUFFIX}`,
+	),
+]
+
 function is_ledger_line(line: string): boolean {
 	return is_ledger_path(status_path(line))
 }
@@ -124,6 +136,7 @@ const observation_ledger = {
 
 export {
 	LEDGER_DIRECTORIES,
+	LEDGER_EXCLUSION_PATHSPEC,
 	LEDGER_FILE_EXTENSION,
 	LEGACY_LEDGER_FILE,
 	LEGACY_OBSERVATION_LEDGER_DIRECTORY,