@joshuafolkken/kit 1.1514.0 → 1.2114.0

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

@@ -1,3 +1,4 @@
+import { lane_child_marker } from '#scripts/lane/lane-child-marker'
 import { git_spawn } from './git-spawn'
 
 // What `josh main:merge` refuses before it merges, and what it tells the run to do instead.
@@ -18,8 +19,12 @@ const UNMERGED_CODES = new Set(['DD', 'AU', 'UD', 'UA', 'DU', 'AA', 'UU'])
 const UNSTAGED_INDEX_CODES = new Set([' ', '?', '!'])
 const DIRECTORY_SUFFIX = '/'
 const COMMIT_COMMAND = '`pnpm josh git -y`'
+// A lane child's push is `josh ship`'s, so the lane-background row refuses a pushing `git -y` there;
+// this is the commit-only form ship's own sync closes a merge with (`run-ship-sync.ts`).
+const LANE_COMMIT_COMMAND = '`pnpm josh git -y --skip-push --skip-pr "<title> #<N>"`'
 const PROCEDURE_POINTER =
 	'`.claude/skills/workflow-commands/chain-rule.md` → "origin/main is merged in before the gate"'
+const MERGE_RERUN = '`pnpm josh main:merge`'
 
 function status_lines(status: string): Array<string> {
 	return status.split('\n').filter((line) => line.length > STATUS_PREFIX_LENGTH)
@@ -57,55 +62,85 @@ function overlapping_paths(status: string, incoming: ReadonlyArray<string>): Arr
 	return uncommitted.filter((path) => incoming.some((changed) => covers(path, changed)))
 }
 
-function unmerged_message(paths: ReadonlyArray<string>): string {
+function commit_command(is_lane_child = lane_child_marker.is_child_of(process.cwd())): string {
+	return is_lane_child ? LANE_COMMIT_COMMAND : COMMIT_COMMAND
+}
+
+// `prefix` names the refusing command, `rerun` what to run once the merge is closed — `josh stash:push`
+// refuses the same index, since `git stash` cannot set unresolved paths aside.
+function unresolved_message(
+	prefix: string,
+	paths: ReadonlyArray<string>,
+	rerun: string,
+	commit = commit_command(),
+): string {
 	return (
-		`main:merge: the index still holds unresolved paths (${paths.join(', ')}). Remove the conflict ` +
-		`markers, then finish through ${COMMIT_COMMAND} — it stages and commits them, so no \`git add\` ` +
-		`permission is needed, and inside a lane this is Tier A. Rerun \`pnpm josh main:merge\` after it ` +
+		`${prefix}: the index still holds unresolved paths (${paths.join(', ')}). Remove the conflict ` +
+		`markers, then finish through ${commit} — it stages and commits them, so no \`git add\` ` +
+		`permission is needed, and inside a lane this is Tier A. Rerun ${rerun} after it ` +
 		`(${PROCEDURE_POINTER}).`
 	)
 }
 
-function staged_message(paths: ReadonlyArray<string>): string {
+function staged_message(paths: ReadonlyArray<string>, commit: string): string {
 	return (
 		`main:merge: the index holds staged changes (${paths.join(', ')}), which git refuses to merge ` +
-		`over. Commit them first through ${COMMIT_COMMAND}, then rerun \`pnpm josh main:merge\` ` +
+		`over. Commit them first through ${commit}, then rerun \`pnpm josh main:merge\` ` +
 		`(${PROCEDURE_POINTER}).`
 	)
 }
 
-function overlap_message(default_branch: string, paths: ReadonlyArray<string>): string {
+function overlap_message(
+	default_branch: string,
+	paths: ReadonlyArray<string>,
+	commit: string,
+): string {
 	return (
 		`main:merge: uncommitted changes touch files origin/${default_branch} also changed ` +
-		`(${paths.join(', ')}). Commit the work first through ${COMMIT_COMMAND}, then rerun ` +
+		`(${paths.join(', ')}). Commit the work first through ${commit}, then rerun ` +
 		`\`pnpm josh main:merge\`. Never stash around the merge — a stash reapplied over it leaves the ` +
 		`conflict half-recorded in the index (${PROCEDURE_POINTER}).`
 	)
 }
 
 // Appended to git's own report when the merge itself stops on a conflict.
-const CONFLICT_HINT =
-	`main:merge: finish a conflicted merge by removing the conflict markers, then ${COMMIT_COMMAND} ` +
-	`records the merge commit — no \`git add\` permission is needed (${PROCEDURE_POINTER}).`
+function conflict_hint(commit = commit_command()): string {
+	return (
+		`main:merge: finish a conflicted merge by removing the conflict markers, then ${commit} ` +
+		`records the merge commit — no \`git add\` permission is needed (${PROCEDURE_POINTER}).`
+	)
+}
 
-function refusal(
+function merge_refusal(
 	status: string,
 	incoming: ReadonlyArray<string>,
 	default_branch: string,
+	commit: string,
 ): string | undefined {
-	const unmerged = unmerged_paths(status)
-
-	if (unmerged.length > 0) return unmerged_message(unmerged)
 	// Nothing incoming means git answers "Already up to date" whatever the index holds.
 	if (incoming.length === 0) return undefined
 
 	const staged = staged_paths(status)
 
-	if (staged.length > 0) return staged_message(staged)
+	if (staged.length > 0) return staged_message(staged, commit)
 
 	const overlap = overlapping_paths(status, incoming)
 
-	return overlap.length > 0 ? overlap_message(default_branch, overlap) : undefined
+	return overlap.length > 0 ? overlap_message(default_branch, overlap, commit) : undefined
+}
+
+// `commit` is the command the message names, resolved from the lane mark unless a caller passes it.
+function refusal(
+	status: string,
+	incoming: ReadonlyArray<string>,
+	default_branch: string,
+	commit = commit_command(),
+): string | undefined {
+	const unmerged = unmerged_paths(status)
+
+	if (unmerged.length > 0) return unresolved_message('main:merge', unmerged, MERGE_RERUN, commit)
+
+	return merge_refusal(status, incoming, default_branch, commit)
 }
 
 // The paths the default branch changed since this branch left it — what the merge would bring in.
@@ -122,12 +157,14 @@ async function incoming_paths(default_branch: string): Promise<Array<string>> {
 }
 
 const main_merge_guard = {
-	CONFLICT_HINT,
+	commit_command,
+	conflict_hint,
 	incoming_paths,
 	overlapping_paths,
 	refusal,
 	staged_paths,
 	unmerged_paths,
+	unresolved_message,
 }
 
 export { main_merge_guard }

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

@@ -1,64 +1,89 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import path from 'node:path'
 import { SUITE_TIMEOUT_MS } from '#scripts/lib/timeouts'
 import { execa } from 'execa'
 import { git_command } from './git-command'
 import { git_spawn } from './git-spawn'
+import { main_merge_budget_conflict } from './main-merge-budget-conflict'
 
-// 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.
+// A merge of the default branch that stops only on the files below is finished here rather than by a
+// resumed session, with no conflict marker for anyone to read. A generated file is the output of a
+// command, so running that command on the merged tree writes the one correct resolution. A rewritten
+// file is resolved by a rule that keeps both sides of the merge, and throws on any hunk it cannot.
 //
-// **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: `scripts/test/pure-files.ts` is not, so regenerating it would
-// rewrite far more than the conflict.
+// **This table is the single list of what is resolved that way** — a file a person writes belongs in
+// it only with a rewrite rule, 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 is regenerated 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> = [
+interface RewrittenFile {
+	path: string
+	rewrite: (content: string) => string
+}
+
+type ResolvedFile = RegeneratedFile | RewrittenFile
+
+const RESOLVED_FILES: ReadonlyArray<ResolvedFile> = [
 	{
 		path: 'docs/josh-command-catalog.md',
-		command: ['pnpm', 'exec', 'tsx', 'scripts/document/generate-catalog.ts'],
+		command: ['pnpm', 'exec', 'tsx', 'tools/document/generate-catalog-main.ts'],
+	},
+	{
+		path: main_merge_budget_conflict.BUDGET_TABLE_PATH,
+		rewrite: main_merge_budget_conflict.resolve,
 	},
 ]
 
-function regenerated_for(
+function resolved_for(
 	files: ReadonlyArray<string>,
-	table: ReadonlyArray<RegeneratedFile>,
-): ReadonlyArray<RegeneratedFile> {
+	table: ReadonlyArray<ResolvedFile>,
+): ReadonlyArray<ResolvedFile> {
 	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> {
+async function rewrite_file(entry: RewrittenFile, cwd: string): Promise<void> {
+	const file = path.join(cwd, entry.path)
+
+	await writeFile(file, entry.rewrite(await readFile(file, 'utf8')))
+}
+
+async function regenerate_file(entry: RegeneratedFile, cwd: string): Promise<void> {
+	const [binary = '', ...command_arguments] = entry.command
+
+	await execa(binary, command_arguments, { cwd })
+}
+
+// Each entry writes only its own file, so they run side by side.
+async function regenerate(entries: ReadonlyArray<ResolvedFile>, cwd: string): Promise<void> {
 	await Promise.all(
 		entries.map(async (entry) => {
-			const [binary = '', ...command_arguments] = entry.command
-
-			await execa(binary, command_arguments, { cwd })
+			await ('rewrite' in entry ? rewrite_file(entry, cwd) : regenerate_file(entry, 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> {
+async function conclude_merge(entries: ReadonlyArray<ResolvedFile>): 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.
+// Whether the merge that stopped on `files` was finished. A command that fails, or a rewrite that
+// refuses a hunk, 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,
+	table: ReadonlyArray<ResolvedFile> = RESOLVED_FILES,
 ): Promise<boolean> {
-	const entries = regenerated_for(files, table)
+	const entries = resolved_for(files, table)
 
 	if (entries.length === 0) return false
 
@@ -72,7 +97,16 @@ async function resolve(
 	return true
 }
 
-const main_merge_regenerate = { REGENERATED_FILES, resolve }
+// Whether a merge stopping on exactly `files` is one `resolve` would try to finish — asked before any
+// merge, by `josh ship`'s conflict probe, so it never stops on a conflict the sync resolves.
+function is_resolvable(
+	files: ReadonlyArray<string>,
+	table: ReadonlyArray<ResolvedFile> = RESOLVED_FILES,
+): boolean {
+	return resolved_for(files, table).length > 0
+}
+
+const main_merge_regenerate = { RESOLVED_FILES, is_resolvable, resolve }
 
-export type { RegeneratedFile }
+export type { RegeneratedFile, ResolvedFile, RewrittenFile }
 export { main_merge_regenerate }

package/scripts/git/main-merge.ts

@@ -1,9 +1,11 @@
-#!/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 { lane_install } from '#scripts/lane/lane-install'
 import { error_text } from '#scripts/lib/error-message'
+import { split_assess } from '#scripts/split/split-assess'
+import { split_early_notice } from '#scripts/split/split-early-notice'
+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'
@@ -30,8 +32,12 @@ import { main_merge_regenerate } from './main-merge-regenerate'
 
 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`'
+const LOCKFILE = 'pnpm-lock.yaml'
+const INSTALL_OWED =
+	'the merge brought in a lockfile change, but installing it failed — run `pnpm install --frozen-lockfile`'
 
 // 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
@@ -46,7 +52,7 @@ function merge_message(default_branch: string, current_branch: string): string |
 }
 
 // What one merge of the default branch came to. `josh ship` merges it again
-// before the commit and on a conflicting pull request, and branches on the answer rather than on an
+// before the gate, before the push and on a followup failed on its checks, and branches on the answer rather than on an
 // exit code: `current` brought nothing in, so the tree is unchanged; `merged` changed it; `refused`
 // is the guard's answer, nothing attempted; `conflict` names the paths git left unmerged, so a resumed
 // session goes straight to them instead of asking git again.
@@ -64,7 +70,7 @@ 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 only on
-// generated files is regenerated and committed (`main-merge-regenerate.ts`), so it answers `undefined`
+// the files `main-merge-regenerate.ts` resolves is resolved and committed, 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())
@@ -88,6 +94,32 @@ async function merge_into(target: MergeTarget): Promise<MergeOutcome> {
 	return { kind: target.is_current ? 'current' : 'merged', branch: default_branch }
 }
 
+// joshuafolkken/kit#4777: a merge that brings in a lockfile change leaves `node_modules` on the old
+// one, so the next check fails on files this branch never touched. Only a finished merge installs — a
+// conflict or a refusal changed no dependency yet. A failed install does not fail the merge; it says
+// the install is still owed, with pnpm's output. A throw is caught for the same reason: the merge is
+// already committed, so `josh ship` must not read it as refused.
+async function install_failure(): Promise<string | undefined> {
+	try {
+		const result = await lane_install.install_dependencies(await git_command.repository_root())
+
+		return result.is_installed ? undefined : result.output
+	} catch (error) {
+		return error_text.message_of(error)
+	}
+}
+
+async function install_merged_lockfile(
+	outcome: MergeOutcome,
+	incoming: ReadonlyArray<string>,
+): Promise<void> {
+	if (outcome.kind !== 'merged' || !incoming.includes(LOCKFILE)) return
+
+	const failure = await install_failure()
+
+	if (failure !== undefined) console.warn(`${INSTALL_OWED}\n${failure}`)
+}
+
 // The fetch is what makes `origin/<default>` current before the merge reads it. `git pull` did the
 // two together, which is the only thing it was doing here that is worth keeping. The refusal is read
 // after the fetch, so the incoming paths are the ones the merge would bring in.
@@ -103,18 +135,54 @@ async function merge(): Promise<MergeOutcome> {
 
 	if (message !== undefined) return { kind: 'refused', message }
 
-	return await merge_into({ default_branch, current_branch, is_current: incoming.length === 0 })
+	const outcome = await merge_into({
+		default_branch,
+		current_branch,
+		is_current: incoming.length === 0,
+	})
+
+	await install_merged_lockfile(outcome, incoming)
+
+	return outcome
 }
 
 // A merge that stops on a conflict keeps git's report and adds how to finish it, so the next step is
 // the sanctioned commit rather than a request for `git add`.
 function failure_text(outcome: MergeOutcome): string | undefined {
 	if (outcome.kind === 'refused') return outcome.message
-	if (outcome.kind === 'conflict') return main_merge_guard.CONFLICT_HINT
+	if (outcome.kind === 'conflict') return main_merge_guard.conflict_hint()
 
 	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 measured_notice(): Promise<string | undefined> {
+	const measurement = await split_measure.read_branch()
+	const notice = split_assess.notice(measurement)
+
+	if (notice !== undefined) await split_early_notice.record(measurement)
+
+	return notice
+}
+
+async function split_notice(): Promise<string | undefined> {
+	try {
+		return await measured_notice()
+	} 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)
@@ -127,6 +195,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
 }
 
@@ -154,13 +224,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/no-base-checkout.ts

@@ -0,0 +1,127 @@
+import {
+	copyFileSync,
+	existsSync,
+	mkdirSync,
+	mkdtempSync,
+	rmSync,
+	statSync,
+	symlinkSync,
+	writeFileSync,
+} from 'node:fs'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { repo_discovery } from '#scripts/discovery/repo-discovery'
+import { execa } from 'execa'
+import { changed_paths } from './changed-paths'
+import { git_command } from './git-command'
+import { git_location_environment } from './git-location-environment'
+
+// **A checkout of this tree as CI's `actions/checkout` hands it over** — a detached, depth-one `HEAD`
+// with no local default branch and no remote-tracking ref (joshuafolkken/kit#4710). Code that passes
+// `main` to git reads the local branch every lane has and passes here, then fails in CI with
+// `bad revision 'main'`; run inside this checkout, it fails here too. **The `origin` remote is kept**,
+// as CI keeps it: code that reads the repository's owner from it reads it here too
+// (joshuafolkken/kit#4738).
+//
+// **No object is copied**: the objects are borrowed through `objects/info/alternates`, and only the
+// tree is checked out. The work in progress is copied over it, and `node_modules` is linked, so the
+// tests read what the lane's own run reads.
+
+const CHECKOUT_PREFIX = 'josh-no-base-'
+const NODE_MODULES = 'node_modules'
+const ORIGIN_URL_KEY = 'remote.origin.url'
+
+// Cleared rather than inherited: under a git hook `GIT_DIR` beats `cwd`, and every command here must
+// act on the new checkout.
+async function git(cwd: string, arguments_: ReadonlyArray<string>): Promise<string> {
+	const { stdout } = await execa('git', arguments_, {
+		cwd,
+		env: git_location_environment.location_free_environment(),
+		extendEnv: true,
+	})
+
+	return stdout.trim()
+}
+
+// A file the work deleted is deleted from the checkout too. A directory git names as one path — a
+// nested repository, a submodule — is not the work's to copy.
+function copy_work(root: string, directory: string, file: string): void {
+	const source = path.join(root, file)
+	const target = path.join(directory, file)
+
+	if (!existsSync(source)) {
+		rmSync(target, { force: true })
+
+		return
+	}
+
+	if (statSync(source).isDirectory()) return
+
+	mkdirSync(path.dirname(target), { recursive: true })
+	copyFileSync(source, target)
+}
+
+async function borrow_objects(root: string, directory: string): Promise<void> {
+	const common = await git(root, ['rev-parse', '--path-format=absolute', '--git-common-dir'])
+	const alternates = path.join(directory, '.git', 'objects', 'info', 'alternates')
+
+	writeFileSync(alternates, `${path.join(common, 'objects')}\n`)
+}
+
+// The remote is declared and never fetched, so it names the repository without bringing a
+// remote-tracking ref along. A repository with no `origin` hands none over. Written with `git config`
+// rather than `git remote add`, which the unit suite's network guard refuses whole.
+async function add_origin(root: string, directory: string): Promise<void> {
+	const origin_url = repo_discovery.read_origin_url(root)
+
+	if (origin_url !== undefined) await git(directory, ['config', ORIGIN_URL_KEY, origin_url])
+}
+
+function link_dependencies(root: string, directory: string): void {
+	const source = path.join(root, NODE_MODULES)
+
+	if (existsSync(source)) symlinkSync(source, path.join(directory, NODE_MODULES))
+}
+
+// `root` is the repository the checkout is cut from; the work in progress is read from the process's
+// own repository, which is the same one wherever `josh test:related` calls this.
+async function check_out(root: string, directory: string, head: string): Promise<void> {
+	await git(directory, ['init', '--quiet'])
+	await add_origin(root, directory)
+	await borrow_objects(root, directory)
+	await git(directory, ['checkout', '--quiet', '--detach', head])
+	writeFileSync(path.join(directory, '.git', 'shallow'), `${head}\n`)
+}
+
+async function fill(root: string, directory: string): Promise<void> {
+	const head = await git_command.head_commit()
+
+	await check_out(root, directory, head)
+	link_dependencies(root, directory)
+
+	const work = await changed_paths.read_changed_since(head)
+
+	for (const file of work) copy_work(root, directory, file)
+}
+
+function remove(directory: string): void {
+	rmSync(directory, { force: true, recursive: true })
+}
+
+// A checkout that could not be finished is removed before the failure is passed on.
+async function create(root: string): Promise<string> {
+	const directory = mkdtempSync(path.join(tmpdir(), CHECKOUT_PREFIX))
+
+	try {
+		await fill(root, directory)
+	} catch (error) {
+		remove(directory)
+		throw error
+	}
+
+	return directory
+}
+
+const no_base_checkout = { create, remove }
+
+export { no_base_checkout }