@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/git/git-merge-conflicts.ts

@@ -0,0 +1,83 @@
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { git_spawn_sync } from './git-spawn-sync'
+
+// The paths merging another branch into this working tree would stop on, read without touching any
+// index or ref (joshuafolkken/kit#4348). **The working tree, not `HEAD`, is ours**: `josh ship` asks
+// before its commit, so the change it is about to ship is still uncommitted. Each path is merged on
+// its own, as `merge-tree` would merge its content: a side left as the merge base had it, or both
+// sides alike, merges cleanly; a side that deleted or added what the other changed differently
+// conflicts; otherwise `git merge-file` decides. Only blob ids are compared, so no content is read.
+
+const CLEAN_EXIT_CODE = 0
+const HEAD = 'HEAD'
+
+interface Sides {
+	base: string | undefined
+	ours: string | undefined
+	theirs: string | undefined
+}
+
+interface Commits {
+	base: string
+	theirs: string
+}
+
+function blob_id(revision: string, file_path: string, cwd: string): string | undefined {
+	return git_spawn_sync.read(['rev-parse', '--verify', '--quiet', `${revision}:${file_path}`], {
+		cwd,
+	})
+}
+
+// Written to the object store so `merge-file --object-id` can read it; no index or ref moves.
+function working_blob_id(file_path: string, cwd: string): string | undefined {
+	if (!existsSync(path.join(cwd, file_path))) return undefined
+
+	return git_spawn_sync.read(['hash-object', '-w', '--', file_path], { cwd })
+}
+
+function is_one_sided(sides: Sides): boolean {
+	return sides.ours === sides.theirs || sides.ours === sides.base || sides.theirs === sides.base
+}
+
+function is_complete(sides: Sides): sides is Record<keyof Sides, string> {
+	return sides.base !== undefined && sides.ours !== undefined && sides.theirs !== undefined
+}
+
+function is_merged(sides: Sides, cwd: string): boolean {
+	if (is_one_sided(sides)) return true
+	if (!is_complete(sides)) return false
+
+	const { base, ours, theirs } = sides
+	const result = git_spawn_sync.run(['merge-file', '-p', '--object-id', ours, base, theirs], {
+		cwd,
+	})
+
+	return result.exit_code === CLEAN_EXIT_CODE
+}
+
+function sides_of(file_path: string, commits: Commits, cwd: string): Sides {
+	return {
+		base: blob_id(commits.base, file_path, cwd),
+		ours: working_blob_id(file_path, cwd),
+		theirs: blob_id(commits.theirs, file_path, cwd),
+	}
+}
+
+// Of `paths` (relative to `cwd`, the working tree's root), the ones merging `theirs` would stop on;
+// `undefined` where the merge base with `theirs` could not be read.
+function working_tree_conflicts(
+	theirs: string,
+	paths: ReadonlyArray<string>,
+	cwd: string,
+): ReadonlyArray<string> | undefined {
+	const base = git_spawn_sync.read(['merge-base', HEAD, theirs], { cwd })
+
+	if (base === undefined) return undefined
+
+	return paths.filter((file_path) => !is_merged(sides_of(file_path, { base, theirs }, cwd), cwd))
+}
+
+const git_merge_conflicts = { working_tree_conflicts }
+
+export { git_merge_conflicts }

package/scripts/git/git-preflight.ts

@@ -13,6 +13,19 @@ import { git_issue, type IssueInfo } from './git-issue'
 // anything changes, and all of them are reported at once.** No rule is new: each
 // answer comes from the function the later stage refuses with, so the two cannot drift apart.
 
+// Which precondition a problem leaves unmet, so a stopped `josh ship` records the kind beside the text
+// (joshuafolkken/kit#4166).
+const PRECONDITION = {
+	ISSUE: 'issue',
+	BRANCH: 'branch',
+	CLASSIFICATION: 'classification',
+} as const
+
+interface Unmet {
+	kind: string
+	problem: string
+}
+
 interface PreflightInput {
 	cli_input: string | undefined
 	will_open_pr: boolean
@@ -26,14 +39,20 @@ interface Target {
 
 interface Resolution {
 	target: Target | undefined
-	problems: Array<string>
+	problems: Array<Unmet>
+}
+
+function unmet(kind: string, problem: string): Unmet {
+	return { kind, problem }
 }
 
 function resolve_from_branch(current_branch: string): Resolution {
 	const number = git_issue.branch_number(current_branch)
 
 	if (number === undefined) {
-		return { target: undefined, problems: [git_issue.branch_derivation_error(current_branch)] }
+		const problem = unmet(PRECONDITION.ISSUE, git_issue.branch_derivation_error(current_branch))
+
+		return { target: undefined, problems: [problem] }
 	}
 
 	return { target: { number, branch_name: current_branch }, problems: [] }
@@ -55,7 +74,10 @@ function resolve_parsed(
 	return {
 		target,
 		problems: [
-			`Branch mismatch: on "${current_branch}", but the title resolves to "${parsed.branch_name}".`,
+			unmet(
+				PRECONDITION.BRANCH,
+				`Branch mismatch: on "${current_branch}", but the title resolves to "${parsed.branch_name}".`,
+			),
 		],
 	}
 }
@@ -68,7 +90,10 @@ function resolve_from_title(
 	try {
 		return resolve_parsed(git_issue.parse(cli_input), current_branch, default_branch)
 	} catch (error) {
-		return { target: undefined, problems: [error_text.message_of(error)] }
+		return {
+			target: undefined,
+			problems: [unmet(PRECONDITION.ISSUE, error_text.message_of(error))],
+		}
 	}
 }
 
@@ -80,13 +105,13 @@ async function resolve_target(cli_input: string | undefined): Promise<Resolution
 	return resolve_from_title(cli_input, current_branch, await git_command.get_default_branch())
 }
 
-async function classification_problems(target: Target): Promise<Array<string>> {
+async function classification_problems(target: Target): Promise<Array<Unmet>> {
 	try {
 		await git_pr.release_classification(target.number, target.branch_name)
 
 		return []
 	} catch (error) {
-		return [error_text.message_of(error)]
+		return [unmet(PRECONDITION.CLASSIFICATION, error_text.message_of(error))]
 	}
 }
 
@@ -106,8 +131,8 @@ async function announce_evidence(branch_name: string): Promise<void> {
 	)
 }
 
-function refusal(problems: ReadonlyArray<string>): Error {
-	const lines = problems.map((problem) => `  - ${problem}`)
+function refusal(problems: ReadonlyArray<Unmet>): Error {
+	const lines = problems.map(({ problem }) => `  - ${problem}`)
 
 	return new Error(
 		[
@@ -119,7 +144,7 @@ function refusal(problems: ReadonlyArray<string>): Error {
 
 interface PreflightAnswer {
 	pr_target: Target | undefined
-	problems: Array<string>
+	problems: Array<Unmet>
 }
 
 async function answer(input: PreflightInput): Promise<PreflightAnswer> {
@@ -131,9 +156,9 @@ async function answer(input: PreflightInput): Promise<PreflightAnswer> {
 	return { pr_target, problems: [...problems, ...pr_problems] }
 }
 
-// The unmet preconditions as a list, so `josh ship` can ask them before its
+// The unmet preconditions as a list, each with its kind, so `josh ship` can ask them before its
 // review and gate start instead of meeting the refusal at the commit stage.
-async function problems_of(input: PreflightInput): Promise<Array<string>> {
+async function problems_of(input: PreflightInput): Promise<Array<Unmet>> {
 	const { problems } = await answer(input)
 
 	return problems
@@ -149,5 +174,5 @@ async function check(input: PreflightInput): Promise<void> {
 
 const git_preflight = { check, problems_of }
 
-export type { PreflightInput }
+export type { PreflightInput, Unmet }
 export { git_preflight }

package/scripts/git/git-push-transport.ts

@@ -1,3 +1,4 @@
+import { MS_PER_SECOND } from '#scripts/lib/timeouts'
 import { execa } from 'execa'
 import { git_utilities } from './constants'
 import {
@@ -8,8 +9,6 @@ import {
 } from './git-execa-error'
 import { git_ssh_keepalive } from './git-ssh-keepalive'
 
-const MS_PER_SECOND = 1000
-
 // The budget for one `git push`, and the reason a push can no longer wait without end.
 // Measured on PR #1244: the commit itself took 0.6 seconds and the push
 // then sat silent for 8 minutes 13 seconds before it was found by hand and killed — about 9 minutes

package/scripts/git/git-schemas.ts

@@ -2,21 +2,28 @@ import { z } from 'zod'
 
 const package_name_schema = z.object({ name: z.string().min(1) })
 
+// REST answers `null` for a field it has no value for yet — a running check run's `conclusion` above
+// all — and one rejected element fails the whole snapshot, which then reads as an empty rollup until
+// the last check completes (joshuafolkken/kit#4351). Every string field is `nullish` for that reason.
 const rollup_item_schema = z.looseObject({
 	// eslint-disable-next-line @typescript-eslint/naming-convention -- GraphQL field name from GitHub API
-	__typename: z.string().optional(),
-	state: z.string().optional(),
-	status: z.string().optional(),
-	conclusion: z.string().optional(),
-	name: z.string().optional(),
-	context: z.string().optional(),
+	__typename: z.string().nullish(),
+	state: z.string().nullish(),
+	status: z.string().nullish(),
+	conclusion: z.string().nullish(),
+	name: z.string().nullish(),
+	context: z.string().nullish(),
 	description: z.string().nullish(),
 })
 
 const pr_raw_schema = z.object({
 	statusCheckRollup: z.array(rollup_item_schema).optional(),
+	// The base branch's required status check contexts, read from its rules — empty where none are
+	// set or they could not be read (`git-gh-branch-rules.ts`).
+	requiredContexts: z.array(z.string()).optional(),
 	mergeStateStatus: z.string().optional(),
 	reviewDecision: z.string().optional(),
+	headRefOid: z.string().optional(),
 })
 
 const pull_comment_schema = z.object({
@@ -40,6 +47,8 @@ const pr_info_schema = z.object({
 const epic_issue_schema = z.object({
 	number: z.number(),
 	body: z.string().optional(),
+	// REST answers null for an issue never closed and `reopened` for one a person reopened.
+	stateReason: z.string().nullish(),
 })
 
 // One blocker as `gh` reports it inside the `blockedBy` connection. `state` comes back with the
@@ -140,6 +149,7 @@ const open_issue_schema = z.object({
 
 type RollupItemData = z.infer<typeof rollup_item_schema>
 type EpicChildData = z.infer<typeof epic_child_schema>
+type EpicIssueData = z.infer<typeof epic_issue_schema>
 type OpenIssueData = z.infer<typeof open_issue_schema>
 type RestCommentData = z.infer<typeof rest_comment_schema>
 
@@ -159,4 +169,4 @@ export {
 	blocking_issue_schema,
 	blocked_by_schema,
 }
-export type { RollupItemData, EpicChildData, OpenIssueData, RestCommentData }
+export type { RollupItemData, EpicChildData, EpicIssueData, OpenIssueData, RestCommentData }

package/scripts/git/git-spawn.ts

@@ -1,4 +1,4 @@
-import { GIT_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import { GIT_TIMEOUT_MS, MS_PER_SECOND } from '#scripts/lib/timeouts'
 import { execa } from 'execa'
 import { git_utilities } from './constants'
 import {
@@ -47,7 +47,6 @@ async function read(
 // still takes this one. The push's budget is reused rather than a second number chosen: both transfer
 // objects over the same transport, and that one is already read off what a healthy transfer costs here.
 const REMOTE_TIMEOUT_MS = PUSH_TIMEOUT_MS
-const MS_PER_SECOND = 1000
 
 // A budget kill is reported as a timeout, never as whatever the killed process printed first, and
 // `cause` carries the same `TIMEOUT_EXIT_CODE` a timed-out push does. Unlike the push it is not

package/scripts/git/git-status.ts

@@ -1,9 +1,9 @@
 import { animation_helpers, type AnimationOptions } from '#scripts/lib/animation-helpers'
+import { PACKAGE_JSON } from '#scripts/lib/package-manifest'
 import { REQUIRED_STATUS_LENGTH, STAGED_STATUS_INDEX, UNTRACKED_FILE_PREFIX } from './constants'
 import { git_command } from './git-command'
 
 const WARNING_ICON = '🔔'
-const PACKAGE_JSON_FILE = 'package.json'
 const STATUS_PREFIX_LENGTH = 2
 const VERSION_NOT_UPDATED = 'Not updated'
 
@@ -62,7 +62,7 @@ function is_package_json_staged(status_output: string): boolean {
 
 		const filename = extract_filename(line)
 
-		return filename === PACKAGE_JSON_FILE
+		return filename === PACKAGE_JSON
 	})
 }
 
@@ -148,7 +148,7 @@ async function check_package_json_version(): Promise<boolean> {
 	return await animation_helpers.execute_with_animation(
 		'Checking if package.json version is updated...',
 		async () => {
-			const diff_output: string = await git_command.diff_cached(PACKAGE_JSON_FILE)
+			const diff_output: string = await git_command.diff_cached(PACKAGE_JSON)
 
 			return is_version_updated_in_diff(diff_output)
 		},
@@ -166,7 +166,7 @@ async function check_branch_version(): Promise<boolean> {
 	return await animation_helpers.execute_with_animation(
 		'Checking if version is already updated on this branch...',
 		async () => {
-			const diff_output: string = await git_command.diff_main(PACKAGE_JSON_FILE)
+			const diff_output: string = await git_command.diff_main(PACKAGE_JSON)
 
 			return is_version_updated_in_diff(diff_output)
 		},

package/scripts/git/main-merge-main.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { main_merge } from './main-merge'
+
+// The `josh main:merge` entry, kept apart from `main-merge.ts` because `run-ship-sync.ts` imports
+// 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 main_merge.run(process.argv.slice(ARGV_OFFSET))
+}

package/scripts/git/main-merge-regenerate.ts

@@ -0,0 +1,78 @@
+import { SUITE_TIMEOUT_MS } from '#scripts/lib/timeouts'
+import { execa } from 'execa'
+import { git_command } from './git-command'
+import { git_spawn } from './git-spawn'
+
+// A merge of the default branch that stops only on generated files is finished here rather than by a
+// resumed session: each such file is the output of a command, so running that command on the merged
+// tree writes the one correct resolution, with no conflict marker for anyone to read.
+//
+// **This table is the single list of what is resolved that way** — a file a person writes never
+// belongs in it, because regenerating would discard that person's side of the merge. A conflict on any
+// path not listed here still stops as `conflict`. A file belongs here only once its committed content
+// is exactly what its command writes: `tools/test/pure-files.ts` is not, so regenerating it would
+// rewrite far more than the conflict.
+
+interface RegeneratedFile {
+	path: string
+	command: ReadonlyArray<string>
+}
+
+const REGENERATED_FILES: ReadonlyArray<RegeneratedFile> = [
+	{
+		path: 'docs/josh-command-catalog.md',
+		command: ['pnpm', 'exec', 'tsx', 'tools/document/generate-catalog.ts'],
+	},
+]
+
+function regenerated_for(
+	files: ReadonlyArray<string>,
+	table: ReadonlyArray<RegeneratedFile>,
+): ReadonlyArray<RegeneratedFile> {
+	const entries = files.map((file) => table.find((entry) => entry.path === file))
+
+	return entries.every((entry) => entry !== undefined) ? entries : []
+}
+
+// Each generator writes only its own file, so they run side by side.
+async function regenerate(entries: ReadonlyArray<RegeneratedFile>, cwd: string): Promise<void> {
+	await Promise.all(
+		entries.map(async (entry) => {
+			const [binary = '', ...command_arguments] = entry.command
+
+			await execa(binary, command_arguments, { cwd })
+		}),
+	)
+}
+
+// `--no-edit` keeps the message the merge was started with — the one carrying the issue number the
+// `commit-msg` hook asks for.
+async function conclude_merge(entries: ReadonlyArray<RegeneratedFile>): Promise<void> {
+	await git_spawn.with_output('add', ['--', ...entries.map((entry) => entry.path)])
+	await git_spawn.with_output('commit', ['--no-edit'], { timeout_ms: SUITE_TIMEOUT_MS })
+}
+
+// Whether the merge that stopped on `files` was finished. A command that fails leaves the merge in
+// progress and answers `false`, so the stop is the `conflict` it would have been without this table.
+async function resolve(
+	files: ReadonlyArray<string>,
+	table: ReadonlyArray<RegeneratedFile> = REGENERATED_FILES,
+): Promise<boolean> {
+	const entries = regenerated_for(files, table)
+
+	if (entries.length === 0) return false
+
+	try {
+		await regenerate(entries, await git_command.repository_root())
+		await conclude_merge(entries)
+	} catch {
+		return false
+	}
+
+	return true
+}
+
+const main_merge_regenerate = { REGENERATED_FILES, resolve }
+
+export type { RegeneratedFile }
+export { main_merge_regenerate }

package/scripts/git/main-merge.ts

@@ -1,11 +1,12 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { extract_issue_number } from '#scripts/hooks/check-commit-message'
 import { issue_cite } from '#scripts/issue/issue-cite'
 import { composite_arguments, USAGE_ERROR_EXIT_CODE } from '#scripts/josh/josh-composite-arguments'
 import { error_text } from '#scripts/lib/error-message'
+import { split_assess } from '#scripts/split/split-assess'
+import { split_measure } from '#scripts/split/split-measure'
 import { git_command } from './git-command'
 import { main_merge_guard } from './main-merge-guard'
+import { main_merge_regenerate } from './main-merge-regenerate'
 
 // `josh main:merge` (`josh mm`) — bring the default branch into the branch this checkout is on.
 //
@@ -29,8 +30,9 @@ import { main_merge_guard } from './main-merge-guard'
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
-const ARGV_OFFSET = 2
 const COMMAND_NAME = 'main:merge'
+const SPLIT_UNMEASURED =
+	'split notice: the diff could not be measured — run `pnpm josh split:assess`'
 
 // git's default merge message carries no `#N`, so on an issue branch the `commit-msg` hook refuses
 // it and leaves the index mid-merge. The number is read with the hook's
@@ -62,18 +64,26 @@ interface MergeTarget {
 }
 
 // A failure that left no unmerged path — a remote that cannot be reached, a hook that refused — is not
-// a conflict, so it is rethrown rather than reported as one with nothing to resolve.
+// a conflict, so it is rethrown rather than reported as one with nothing to resolve. A conflict only on
+// generated files is regenerated and committed (`main-merge-regenerate.ts`), so it answers `undefined`
+// and the merge reads as finished.
+async function unresolved_conflict(error: unknown): Promise<MergeOutcome | undefined> {
+	const files = main_merge_guard.unmerged_paths(await git_command.status())
+
+	if (files.length === 0) throw error
+
+	return (await main_merge_regenerate.resolve(files)) ? undefined : { kind: 'conflict', files }
+}
+
 async function merge_into(target: MergeTarget): Promise<MergeOutcome> {
 	const { default_branch, current_branch } = target
 
 	try {
 		await git_command.merge_branch(default_branch, merge_message(default_branch, current_branch))
 	} catch (error) {
-		const files = main_merge_guard.unmerged_paths(await git_command.status())
-
-		if (files.length === 0) throw error
+		const conflict = await unresolved_conflict(error)
 
-		return { kind: 'conflict', files }
+		if (conflict !== undefined) return conflict
 	}
 
 	return { kind: target.is_current ? 'current' : 'merged', branch: default_branch }
@@ -106,6 +116,25 @@ function failure_text(outcome: MergeOutcome): string | undefined {
 	return undefined
 }
 
+// joshuafolkken/kit#4302: every implementing run merges the default branch immediately before the
+// gate, so this is where a diff that outgrew the entry's split estimate is told so. The notice is
+// advisory: a finished merge never fails on it, and an unreadable diff says so rather than reading as
+// under the guide. It sits on the command, not on `merge()`, because `josh ship` merges again past the
+// point a run can act on it.
+async function split_notice(): Promise<string | undefined> {
+	try {
+		return split_assess.notice(await split_measure.read_branch())
+	} catch (error) {
+		return `${SPLIT_UNMEASURED}: ${error_text.message_of(error)}`
+	}
+}
+
+async function warn_over_split_guide(): Promise<void> {
+	const notice = await split_notice()
+
+	if (notice !== undefined) console.warn(notice)
+}
+
 async function merge_default_branch(): Promise<number> {
 	const outcome = await merge()
 	const failure = failure_text(outcome)
@@ -118,6 +147,8 @@ async function merge_default_branch(): Promise<number> {
 
 	if ('branch' in outcome) console.info(outcome.branch)
 
+	await warn_over_split_guide()
+
 	return SUCCESS_EXIT_CODE
 }
 
@@ -145,13 +176,7 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	}
 }
 
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const main_merge = { merge, run }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export { main_merge }
 export type { MergeOutcome }

package/scripts/git/main-sync-main.ts

@@ -0,0 +1,12 @@
+#!/usr/bin/env tsx
+import { fileURLToPath } from 'node:url'
+import { main_sync } from './main-sync'
+
+// The `josh main:sync` entry, kept apart from `main-sync.ts` because `observations-flush.ts` imports
+// 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 main_sync.run(process.argv.slice(ARGV_OFFSET))
+}

package/scripts/git/main-sync.ts

@@ -1,5 +1,3 @@
-#!/usr/bin/env tsx
-import { fileURLToPath } from 'node:url'
 import { composite_arguments, USAGE_ERROR_EXIT_CODE } from '#scripts/josh/josh-composite-arguments'
 import { error_text } from '#scripts/lib/error-message'
 import { git_command } from './git-command'
@@ -27,7 +25,6 @@ import { lockfile_sync } from './lockfile-sync'
 
 const SUCCESS_EXIT_CODE = 0
 const FAILURE_EXIT_CODE = 1
-const ARGV_OFFSET = 2
 const COMMAND_NAME = 'main:sync'
 const INSTALL_FAILURE =
 	'node_modules is behind pnpm-lock.yaml and `pnpm install --frozen-lockfile` failed; run `pnpm josh ms` again, or the install here by hand.'
@@ -144,12 +141,6 @@ async function run(argv: ReadonlyArray<string>): Promise<number> {
 	}
 }
 
-async function main(argv: ReadonlyArray<string>): Promise<void> {
-	process.exitCode = await run(argv)
-}
-
 const main_sync = { run }
 
-if (process.argv[1] === fileURLToPath(import.meta.url)) await main(process.argv.slice(ARGV_OFFSET))
-
 export { main_sync }

package/scripts/git/stash/git-stash.ts

@@ -1,4 +1,5 @@
 import { git_spawn } from '#scripts/git/git-spawn'
+import { LEDGER_EXCLUSION_PATHSPEC } from '#scripts/observations/observation-ledger'
 
 // The one place a sanctioned `git stash pop` is targeted by its message rather than its stack
 // position. The stash is a single repository-wide stack shared by every
@@ -97,14 +98,34 @@ async function has_conflict(directory?: string): Promise<boolean> {
 
 // Uncommitted work is anything `git status --porcelain` lists — untracked files included, which is what
 // `push` below carries with `-u`, so the two agree on what "work" means.
-async function has_changes(directory?: string): Promise<boolean> {
-	return (await git_spawn.read(git_args(directory, ['status', '--porcelain']))) !== ''
+// A `pathspec` narrows both to the same paths, so a push never finds nothing where this found work.
+async function has_changes(
+	directory?: string,
+	pathspec: ReadonlyArray<string> = [],
+): Promise<boolean> {
+	const status = await git_spawn.read(git_args(directory, ['status', '--porcelain', ...pathspec]))
+
+	return status !== ''
+}
+
+// What `josh stash:push` sets aside: everything but the observation ledger, whose lines ride on the
+// run's own commit (`stash-push-cli.ts`).
+const STASHABLE_PATHSPEC: ReadonlyArray<string> = ['--', ...LEDGER_EXCLUSION_PATHSPEC]
+
+// Whether `josh stash:push` would push anything — the question to ask before telling someone to run it,
+// so a ledger-only tree is never sent to a push that answers `clean`.
+async function has_stashable_changes(directory?: string): Promise<boolean> {
+	return await has_changes(directory, STASHABLE_PATHSPEC)
 }
 
 // Push with a message `josh stash:pop` can later target — the stack is shared by every work tree, so an
 // entry pushed from a lane outlives the lane's own tree.
-async function push(message: string, directory?: string): Promise<void> {
-	await git_spawn.read(git_args(directory, ['stash', 'push', '-u', '-m', message]))
+async function push(
+	message: string,
+	directory?: string,
+	pathspec: ReadonlyArray<string> = [],
+): Promise<void> {
+	await git_spawn.read(git_args(directory, ['stash', 'push', '-u', '-m', message, ...pathspec]))
 }
 
 // The stack keyed by commit rather than position: a sweep that reads the
@@ -181,6 +202,7 @@ const git_stash = {
 	drop_by_hash,
 	has_changes,
 	has_conflict,
+	has_stashable_changes,
 	list,
 	list_by_hash,
 	matches,
@@ -188,6 +210,7 @@ const git_stash = {
 	pop,
 	push,
 	select,
+	STASHABLE_PATHSPEC,
 	work_message,
 }
 

package/scripts/git/stash/{stash-pop-args.ts → stash-args.ts}

@@ -1,13 +1,12 @@
 import { cli_flags } from '#scripts/lib/cli-flags'
 
-// `josh stash:pop` turns its `argv` into a single request: the message of the stash to pop. Parsing
-// lives here, acting on the stack lives in `stash-pop-cli.ts`, and a malformed command line is
-// `undefined` rather than a guessed intent — a pop run on a misread argument would take the wrong
-// entry off a stack shared by every lane.
+// `josh stash:push` and `josh stash:pop` turn their `argv` into a single request: the message of the
+// stash to push or pop. Parsing lives here, acting on the stack lives in each command's cli, and a
+// malformed command line is `undefined` rather than a guessed intent — a pop run on a misread argument
+// would take the wrong entry off a stack shared by every lane, and a push without its message would
+// leave an entry nothing can target.
 
-const USAGE = 'Usage: josh stash:pop "<message>" [--dir <path>]'
-
-// `--dir` points the pop at a lane's work tree; without it the pop lands in the current checkout.
+// `--dir` points the command at a lane's work tree; without it, it acts on the current checkout.
 const OPTIONS = { dir: { type: 'string' } } as const
 
 interface ParsedValues {
@@ -20,12 +19,16 @@ interface Request {
 	dir: string | undefined
 }
 
+function usage(command: string): string {
+	return `Usage: josh ${command} "<message>" [--dir <path>]`
+}
+
 function read_arguments(argv: ReadonlyArray<string>): ParsedValues | undefined {
 	return cli_flags.arguments_of(argv, OPTIONS)
 }
 
 // The message is the sole positional and must be a non-empty string: an empty message matches every
-// stash pushed without a message, which is exactly the ambiguity this command exists to refuse.
+// stash pushed without a message, which is exactly the ambiguity `stash:pop` exists to refuse.
 function message_of(positionals: ReadonlyArray<string>): string | undefined {
 	if (positionals.length !== 1) return undefined
 
@@ -42,7 +45,7 @@ function to_request(parsed: ParsedValues): Request | undefined {
 	return { message, dir: parsed.values.dir }
 }
 
-const stash_pop_args = { USAGE, read_arguments, to_request }
+const stash_args = { read_arguments, to_request, usage }
 
 export type { Request }
-export { stash_pop_args }
+export { stash_args }