@joshuafolkken/kit 1.872.0

package/scripts/test/test-red.ts

@@ -0,0 +1,154 @@
+import { existsSync } from 'node:fs'
+import { copyFile, mkdir, mkdtemp, readFile, rm, symlink } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { change_base } from '#scripts/git/change-base'
+import { changed_paths } from '#scripts/git/changed-paths'
+import { git_location_environment } from '#scripts/git/git-location-environment'
+import { git_worktree } from '#scripts/git/git-worktree'
+import { execa } from 'execa'
+import { test_red_logic, type RedVerdict } from './test-red-logic'
+
+// `josh test:red` — run the added and changed Vitest files against the pre-fix tree and print `red`,
+// `green` or `no-test` (joshuafolkken/kit#2448).
+//
+// **The pre-fix tree is a detached worktree at the merge-base, never the caller's checkout.** The tests
+// are copied in from the working tree, so what runs is the new test against the old code, and the
+// caller's tree and index are never read back or written. The worktree borrows this checkout's
+// `node_modules` through a symlink rather than installing its own: what is being asked about is the
+// source the fix changed, and an install would add seconds and a network dependency to every commit.
+
+const ARGV_OFFSET = 2
+const TREE_PREFIX = 'josh-test-red-'
+const TREE_NAME = 'tree'
+const REPORT_NAME = 'report.json'
+const NODE_MODULES = 'node_modules'
+const VITEST_BIN = path.join(NODE_MODULES, '.bin', 'vitest')
+const USAGE =
+	'Usage: josh test:red — prints red / green / no-test for the changed tests on the merge-base'
+
+interface RedRun {
+	verdict: RedVerdict
+	files: ReadonlyArray<string>
+}
+
+// The changed Vitest files that still exist — a deleted test has nothing to run.
+async function changed_tests(): Promise<Array<string>> {
+	const paths = await changed_paths.read_changed_paths(false)
+
+	return test_red_logic.unit_test_files(paths).filter((file) => existsSync(file))
+}
+
+async function copy_in(tree: string, files: ReadonlyArray<string>): Promise<void> {
+	for (const file of files) {
+		const target = path.join(tree, file)
+
+		await mkdir(path.dirname(target), { recursive: true })
+		await copyFile(file, target)
+	}
+}
+
+async function prepare(tree: string, base: string, files: ReadonlyArray<string>): Promise<void> {
+	await git_worktree.worktree_add_detached(tree, base)
+	await symlink(path.resolve(NODE_MODULES), path.join(tree, NODE_MODULES), 'dir')
+	await copy_in(tree, files)
+}
+
+function reporter_arguments(report: string): Array<string> {
+	// The plain `--outputFile`, not `--outputFile.json`: a config that sets `test.outputFile` as a string
+	// wins over the keyed form, which would send the report into the tree and read every run `no-test`.
+	return ['--reporter=json', `--outputFile=${report}`]
+}
+
+async function read_report(report: string): Promise<string> {
+	return existsSync(report) ? await readFile(report, 'utf8') : ''
+}
+
+// The verdict of one run. `--passWithNoTests` keeps "the filter matched nothing" from reading as a
+// failure, and the JSON report — written beside the tree, never into it — says whether anything ran at
+// all, so a file the old config excludes is `no-test` rather than a `green` that refuses a correct fix.
+// A test that ran and broke, or a file that could not load against the old code, makes it `red`.
+async function verdict_in(
+	parent: string,
+	tree: string,
+	files: ReadonlyArray<string>,
+): Promise<RedVerdict> {
+	const report = path.join(parent, REPORT_NAME)
+	const vitest_args = ['run', '--passWithNoTests', ...reporter_arguments(report), ...files]
+	const result = await execa(path.join(tree, VITEST_BIN), vitest_args, {
+		cwd: tree,
+		env: git_location_environment.location_free_environment(),
+		extendEnv: true,
+		reject: false,
+	})
+	const ran = test_red_logic.ran_file_count(await read_report(report))
+
+	return test_red_logic.verdict_for(ran, result.exitCode !== 0)
+}
+
+// Best effort: a removal that fails leaves a registration `worktree prune` drops once the directory is
+// gone, so the cleanup never replaces the verdict with its own error.
+async function remove_tree(parent: string, tree: string): Promise<void> {
+	try {
+		await git_worktree.worktree_remove(tree)
+	} catch {
+		// The directory is deleted below and the prune drops the stale registration.
+	}
+
+	await rm(parent, { force: true, recursive: true })
+
+	try {
+		await git_worktree.worktree_prune()
+	} catch {
+		// A failed prune leaves a stale registration the next prune drops; the verdict stands.
+	}
+}
+
+async function verdict_on(base: string, files: ReadonlyArray<string>): Promise<RedVerdict> {
+	const parent = await mkdtemp(path.join(tmpdir(), TREE_PREFIX))
+	const tree = path.join(parent, TREE_NAME)
+
+	try {
+		await prepare(tree, base, files)
+
+		return await verdict_in(parent, tree, files)
+	} finally {
+		await remove_tree(parent, tree)
+	}
+}
+
+// The verdict over the current checkout. No merge-base (not a repository, no default branch) reads as
+// `no-test` — there is no pre-fix tree to run against, and a guard fails open.
+async function run(): Promise<RedRun> {
+	const base = await change_base.resolved()
+	const files = await changed_tests()
+
+	if (base === undefined || files.length === 0) return { verdict: 'no-test', files }
+
+	return { verdict: await verdict_on(base, files), files }
+}
+
+async function main(argv: ReadonlyArray<string>): Promise<number> {
+	if (argv.length > 0) {
+		process.stderr.write(`${USAGE}\n`)
+
+		return argv.includes('--help') ? 0 : 1
+	}
+
+	const { verdict, files } = await run()
+
+	process.stdout.write(`${verdict}\n`)
+	if (files.length > 0) process.stderr.write(`${files.join('\n')}\n`)
+
+	return 0
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await main(process.argv.slice(ARGV_OFFSET))
+}
+
+const test_red = { USAGE, run }
+
+export type { RedRun }
+export { test_red }

package/scripts/test/test-related-scope.ts

@@ -0,0 +1,115 @@
+import path from 'node:path'
+import {
+	changed_file_scope,
+	type ChangedFileScope,
+	type ScopeInputs,
+	type ScopeVocabulary,
+} from '#scripts/git/changed-file-scope'
+
+// joshuafolkken/kit#1257: the unit suite always ran whole. Measured warm on kit, that is 384 files
+// and 6,616 tests — 13.9s wall and 110s of CPU, 84% of everything the four gate checks spend, and
+// an implementation loop paid it again on every re-check. The same tree narrowed to one changed
+// file runs 31 files and 566 tests in 2.4s (7.9s of CPU, −93%).
+//
+// **This narrowing is added in front of the whole suite, never in place of it.** A test that breaks
+// without importing what changed — a marker suite reading a document, a fixture compared against a
+// generated file — is invisible to a module graph, so the verification gate keeps running
+// `josh test:unit` over everything before the commit.
+//
+// The decision this file makes is which extensions vitest can walk a module graph back from, and
+// what to print about it. Everything the decision shares with `josh lint:related` — reading the
+// change, dropping what the tree no longer holds, and the two fallbacks — is
+// `changed-file-scope.ts`, so the two commands cannot drift apart about what "changed" means
+// (joshuafolkken/kit#1298).
+
+type RelatedScope = ChangedFileScope
+
+// The extensions vitest can walk a module graph back from. A changed `.md`, `.yaml` or `.json` is
+// dropped rather than passed through: `vitest related` would match no test file for it, and a run
+// narrowed to nothing at all is the one outcome this module exists to prevent.
+const RELATABLE_EXTENSIONS: ReadonlySet<string> = new Set([
+	'.ts',
+	'.tsx',
+	'.mts',
+	'.cts',
+	'.js',
+	'.jsx',
+	'.mjs',
+	'.cjs',
+	'.svelte',
+])
+
+const { UNREADABLE_REASON } = changed_file_scope
+const NOTHING_RELATABLE_REASON = 'no changed file is one a test can import'
+
+// The command this narrowing belongs to, defined once: the guard prints it when it skips, and the
+// line below prints it in front of every decision.
+const COMMAND_NAME = 'test:related'
+const COMMAND_LABEL = `josh ${COMMAND_NAME}`
+const { LISTED_FILE_LIMIT } = changed_file_scope
+
+const VOCABULARY: ScopeVocabulary = {
+	label: COMMAND_LABEL,
+	fallback_suffix: 'running the full unit suite instead',
+	narrowed_suffix: 'running only the tests related to them',
+}
+
+const RUN_FLAG = '--run'
+const RELATED_SUBCOMMAND = 'related'
+const RUN_SUBCOMMAND = 'run'
+
+function is_relatable(file_path: string): boolean {
+	return RELATABLE_EXTENSIONS.has(path.extname(file_path))
+}
+
+// The three inputs that make the shared narrowing this command's, handed over as one value so the
+// CLI and the two functions below cannot disagree about any of them.
+function scope_inputs(is_present: (file_path: string) => boolean): ScopeInputs {
+	return { is_present, is_selectable: is_relatable, nothing_reason: NOTHING_RELATABLE_REASON }
+}
+
+function select_related_files(
+	paths: ReadonlyArray<string>,
+	is_present: (file_path: string) => boolean,
+): Array<string> {
+	return changed_file_scope.select_files(paths, scope_inputs(is_present))
+}
+
+function resolve_scope(
+	paths: ReadonlyArray<string> | undefined,
+	is_present: (file_path: string) => boolean,
+): RelatedScope {
+	return changed_file_scope.resolve_scope(paths, scope_inputs(is_present))
+}
+
+function describe_scope(scope: RelatedScope, root: string): string {
+	return changed_file_scope.describe_scope(scope, root, VOCABULARY)
+}
+
+// `--run` is what keeps `vitest related` out of watch mode; the `run` sub-command already implies it
+// on the full-suite side, which is why only one of the two branches carries the flag.
+function vitest_arguments(
+	scope: RelatedScope,
+	extra_flags: ReadonlyArray<string> = [],
+): ReadonlyArray<string> {
+	if (scope.mode === 'all') return [RUN_SUBCOMMAND, ...extra_flags]
+
+	return [RELATED_SUBCOMMAND, ...scope.files, RUN_FLAG, ...extra_flags]
+}
+
+const related_scope = {
+	COMMAND_LABEL,
+	COMMAND_NAME,
+	LISTED_FILE_LIMIT,
+	NOTHING_RELATABLE_REASON,
+	UNREADABLE_REASON,
+	describe_scope,
+	is_relatable,
+	resolve_scope,
+	scope_inputs,
+	select_related_files,
+	vitest_arguments,
+}
+
+export type { ScopeMode } from '#scripts/git/changed-file-scope'
+export { related_scope }

package/scripts/test/test-related.ts

@@ -0,0 +1,73 @@
+#!/usr/bin/env tsx
+import { existsSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import type { GateTree } from '#scripts/gate/gate-tree'
+import { scoped_green } from '#scripts/gate/scoped-green'
+import { changed_file_scope } from '#scripts/git/changed-file-scope'
+import { review_stamps } from '#scripts/review/review-stamps'
+import { related_scope } from './test-related-scope'
+import { test_unit_guard } from './test-unit-guard'
+
+// `josh test:related` — the unit check an implementation loop runs between edits
+// (joshuafolkken/kit#1257). The narrowing itself is `test-related-scope.ts` over the shared
+// decision in `changed-file-scope.ts`; this is the process around it — how the run reaches vitest
+// through the same guard `josh test:unit` goes through.
+//
+// **A green run leaves a record of the tree it was green on** (joshuafolkken/kit#1511), so
+// `josh review:brief` can tell a tree this check has read from one it has not. What the record means,
+// and the three states in which it is withheld, are `scoped-green.ts`.
+
+// **A skipped vitest exits 0, and a zero from a run that started nothing must vouch for no tree.**
+// `test_unit_guard.report_no_run` returns 0 on its skip branch — vitest not installed — so in a
+// project with no unit suite the record would say the tests were green over a run in which none
+// executed, and `josh review:brief` would stop refusing on the strength of it. **The guard's own
+// decision is asked again rather than re-derived here**, so the two can never disagree; it is asked
+// only when a record is otherwise due, since the question costs a project-wide glob.
+function conclusive_tree(before: GateTree | undefined): GateTree | undefined {
+	if (before === undefined) return undefined
+
+	const action = test_unit_guard.resolve_guard_action(
+		test_unit_guard.is_vitest_installed(process.cwd()),
+		test_unit_guard.has_unit_tests(process.cwd()),
+	)
+
+	return action === 'run' ? before : undefined
+}
+
+async function run_related_tests(command_arguments: ReadonlyArray<string>): Promise<number> {
+	const root = await changed_file_scope.repository_root_or_cwd()
+	const scope = await changed_file_scope.resolve_command_scope({
+		command_arguments,
+		root,
+		inputs: related_scope.scope_inputs(existsSync),
+	})
+
+	changed_file_scope.report_unusable_arguments(
+		command_arguments,
+		scope,
+		related_scope.COMMAND_LABEL,
+	)
+
+	const before = await scoped_green.read_before(command_arguments)
+	const exit_code = await test_unit_guard.run_guarded_vitest(
+		process.cwd(),
+		related_scope.vitest_arguments(scope, changed_file_scope.flags_of(command_arguments)),
+		related_scope.COMMAND_NAME,
+		related_scope.describe_scope(scope, root),
+	)
+
+	await scoped_green.record_if_green(review_stamps.test_related_stamp, {
+		before: conclusive_tree(before),
+		exit_code,
+	})
+
+	return exit_code
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	process.exitCode = await run_related_tests(process.argv.slice(changed_file_scope.ARGV_START))
+}
+
+const test_related = { run_related_tests }
+
+export { test_related }

package/scripts/test/test-repository-guard.ts

@@ -0,0 +1,317 @@
+import { execFileSync } from 'node:child_process'
+import { shim_shell } from '#scripts/build/shim-shell'
+import {
+	git_location_environment,
+	GIT_LOCATION_VARIABLES,
+} from '#scripts/git/git-location-environment'
+
+// **A unit test must not write into the repository the suite is running in**, and until
+// joshuafolkken/kit#1530 nothing said so out loud.
+//
+// `lane-change-base.test.ts` builds a real git topology in a temp directory and hands its helper
+// `{ cwd }` and nothing else. Run from the pre-push hook it inherited `GIT_DIR` and `GIT_INDEX_FILE`
+// from the hook environment — both of which beat `cwd` — so the fixture's own commits landed on the
+// branch being pushed. `1085-lane`'s reflog carries three of them, titled `base` and
+// `another lane merged`, 26 seconds after the run's real commit; `1080-lane` took one. The same
+// helper's `git config user.email` wrote a fixture identity into `--local` config, which every
+// linked work tree of the repository shares, so all five checkouts on the machine started authoring
+// commits as `Lane Fixture <lane@example.test>`.
+//
+// **This is the second instance of one class in a day.** joshuafolkken/kit#1515 fixed the first, in
+// `propagate-git`'s probes, by clearing the location variables — and fixing the instance is all it
+// did. The class recurred within hours, in a file written after it, arriving the same way: silently,
+// with the only evidence a reflog someone had to go and read.
+//
+// **So the guard is built one dimension over from #1515's own network guard, on the same mechanism**
+// (`test-network-guard.ts` arms the `PATH` shim, holds the record and fails the run from
+// `globalSetup`'s teardown; this module contributes the `sh` that decides). Reusing it rather than
+// writing a second guard is `CLAUDE.md` → "No clones", and it is also the only way the two can share
+// one record: a run that both reached the network and wrote to the repository reports both.
+//
+// **What it refuses, and why that is narrower than "any command touching the repository".** Reads
+// are the suite's business — half of it reads the repository it is running in, and refusing that
+// would stop the suite rather than the defect. A read also cannot move a branch. So the arm is the
+// *writing* subcommands, and it refuses one on either of two findings:
+//
+// 1. **Any git location variable is set.** A fixture is targeted by clearing the environment, never
+//    by out-arguing it, so a writing command reaching git with `GIT_DIR` or `GIT_INDEX_FILE` still
+//    in its environment is refused whatever it was aimed at. This is the exact shape of both
+//    instances, and it is decided without spawning anything.
+// 2. **The command resolves into the guarded repository.** The environment can be clean and the
+//    write still land here, by way of an ambient `cwd` — a test that `process.chdir`s into the
+//    checkout and commits. The resolution is git's own `rev-parse --absolute-git-dir`, **asked with
+//    the caller's own global options in front of it**, so `-C <fixture>` is not refused for the
+//    directory the shim happens to sit in and `--git-dir <checkout>` is not let through for it.
+//
+// The two lists below say which finding a subcommand faces: an unambiguous writer faces both, and
+// one whose reading spelling this suite uses faces the first only.
+//
+// **It fails closed on the second finding**: a resolution that fails means the command is not inside
+// any repository at all — that is an answer, not an unknown, and the first finding has already
+// refused every environment that could have redirected it elsewhere.
+//
+// **The one deliberate fail-open** is a `PROJECT_ROOT` that is not a git repository, where there is
+// no repository for a test to damage and the second finding is left out of the generated shim. The
+// first finding is generated unconditionally, so an inherited environment is refused either way.
+//
+// **What it names.** The shim cannot see which test called it — it is a `PATH` shim, and vitest puts
+// no test identity in the environment. It does not need to: it refuses **at the call**, with `exit 1`
+// and the command and the finding on stderr, so `execa` throws inside the test and vitest names the
+// file and the test itself. The record read at teardown is the backstop for a test that swallows the
+// error, and it carries the command and the finding for the same reason — so nobody has to
+// reconstruct it from a reflog the way joshuafolkken/kit#1530 was.
+
+// The `git` subcommands that can write to a repository, an index or a config. Absent from it are the
+// reads the suite lives on (`status`, `log`, `diff`, `rev-parse`, `merge-base`, `show`,
+// `ls-files`, `cat-file`, `describe`) and the network subcommands, which `test-network-guard.ts`
+// refuses outright before this arm is reached.
+//
+// **`symbolic-ref` is deliberately absent**: its writing spelling takes a second argument and its
+// reading spelling does not, and splitting that inside a shell `case` fails open when it gets it
+// wrong. Nothing in this suite writes a symbolic ref, and the branch-moving spellings that matter
+// (`update-ref`, `checkout`, `switch`, `reset`) are all here.
+const GIT_WRITING_SUBCOMMANDS: ReadonlyArray<string> = [
+	'add',
+	'am',
+	'checkout',
+	'cherry-pick',
+	'clean',
+	'commit',
+	'gc',
+	'init',
+	'merge',
+	'mv',
+	'prune',
+	'rebase',
+	'reset',
+	'restore',
+	'revert',
+	'rm',
+	'switch',
+	'update-index',
+	'update-ref',
+]
+
+// The subcommands whose **reading** spelling this suite actually uses — `worktree list`,
+// `branch --show-current`, `config --get`, `stash list`, `tag -l`, `notes list`, `apply --check`.
+// They are refused on the inherited-environment finding only.
+//
+// **Which is not a hole, but the line between the two findings drawn where it belongs.** An
+// inherited environment is wrong for a read as surely as for a write — it is the other half of what
+// joshuafolkken/kit#1530 did, where `git_command`'s readings answered about the repository being
+// pushed — so finding 1 covers these whole, `config user.email <value>` and `worktree add` included.
+// Finding 2 is the one that cannot tell them apart: an ambient `cwd` inside the checkout is exactly
+// how a legitimate read of the real repository is spelled, and refusing that would stop the suite
+// rather than the defect (`test-network-guard.ts` names the worktree machinery as a read that has to
+// keep working). Splitting them on their flags instead was rejected for the reason the network list
+// refuses `remote` whole: getting a flag `case` wrong in `sh` fails **open**.
+const GIT_AMBIGUOUS_SUBCOMMANDS: ReadonlyArray<string> = [
+	'apply',
+	'branch',
+	'config',
+	'notes',
+	'stash',
+	'tag',
+	'worktree',
+]
+
+// The word every recorded write violation starts with, so one shared record still says which guard
+// caught which call and `describe_violations` can report each kind under its own heading.
+const WRITE_MARKER = 'repository write:'
+// **The headline states the rule and the detail line states the finding**, because the two findings
+// have different fixes: clearing the environment is the answer to the first and gives the second a
+// misleading instruction, which is what the same sentence said for both until review round 1.
+const BLOCKED_WRITE_MESSAGE =
+	'josh: a unit test must not run a writing git command against the repository the suite is running in'
+// Finding-neutral, like the stderr message and for the same reason: each recorded line carries its
+// own `— via …`, and a run failed on the working-directory finding must not be told to clear an
+// environment that was already clean (review round 2).
+const WRITE_VIOLATION_HEADING =
+	'The unit suite ran a writing git command against the repository it is running in. Each line names what took it there:'
+
+// The record and the stderr detail both read as prose and both expand in `sh`: `$*` is the arguments
+// the shim stood in for, `$guard_via` the finding that refused them.
+const REFUSED_COMMAND = 'git $* — via $guard_via'
+const RECORDED_WRITE = `${WRITE_MARKER} ${REFUSED_COMMAND}`
+
+const GIT_DIRECTORY_ARGUMENTS = ['rev-parse', '--path-format=absolute', '--git-common-dir']
+
+// **The one failure that is an answer rather than an unknown.** There is no repository at
+// `PROJECT_ROOT`, so finding 2 has nothing to protect and is left out of the generated shim while
+// finding 1 stays armed. Every other failure — an unreadable directory, a git that cannot run — is a
+// guard that does not know what it is guarding, and a guard that cannot answer must not report the
+// run clean (review round 1 of joshuafolkken/kit#1530).
+const NOT_A_REPOSITORY = 'not a git repository'
+const RESOLUTION_HEADING =
+	'The unit-suite repository guard could not work out which repository it protects, so the run proves nothing:'
+
+function text_of(value: unknown): string {
+	return typeof value === 'string' ? value : ''
+}
+
+// What git said, plus what node said when git never ran — the two places the reason can be, joined
+// so one `includes` decides between them.
+function stderr_of(error: unknown): string {
+	if (typeof error !== 'object' || error === null) return ''
+
+	const stderr = 'stderr' in error ? text_of(error.stderr) : ''
+	const message = 'message' in error ? text_of(error.message) : ''
+
+	return `${stderr} ${message}`.trim()
+}
+
+function is_absent_repository(error: unknown): boolean {
+	return stderr_of(error).includes(NOT_A_REPOSITORY)
+}
+
+// The repository this guard protects, as git itself resolves it — the **common** directory rather
+// than the per-work-tree one, so a lane's shim refuses a write into any of the repository's linked
+// work trees and not only into its own.
+function guarded_git_directory(git_binary: string | undefined, from: string): string | undefined {
+	if (git_binary === undefined) return undefined
+
+	try {
+		return execFileSync(git_binary, GIT_DIRECTORY_ARGUMENTS, {
+			cwd: from,
+			encoding: 'utf8',
+			// **Cleared here too, and not belt-and-braces.** The guard is armed from `globalSetup`, and
+			// under the pre-push hook that process has itself inherited `GIT_DIR` — so asking without
+			// clearing it answers about whatever the hook was pointed at, and the shim would be built
+			// to protect a repository this suite has nothing to do with.
+			env: { ...process.env, ...git_location_environment.location_free_environment() },
+			stdio: ['ignore', 'pipe', 'pipe'],
+		}).trim()
+	} catch (error) {
+		if (!is_absent_repository(error)) {
+			throw new Error(`${RESOLUTION_HEADING} ${stderr_of(error)}`, { cause: error })
+		}
+
+		return undefined
+	}
+}
+
+// Finding 1, one line per variable. `${NAME-}` rather than `$NAME` so an unset name is the empty
+// string under `set -u` as readily as without it.
+function environment_lines(): Array<string> {
+	return GIT_LOCATION_VARIABLES.map(
+		(name) => `[ -z "\${${name}-}" ] || guard_env="$guard_env ${name}"`,
+	)
+}
+
+// The `sh` function finding 2 resolves through, emitted once at the top of the shim.
+//
+// **It keeps the caller's own global options** — the words the scan counted before the subcommand —
+// and asks git where *that* command would act. `cwd` alone is not that answer, in both directions:
+// `git -C <fixture>` moves it away from the directory the shim was spawned in, and
+// `git --git-dir <checkout>` moves it towards the guarded one. A resolution taken from `cwd` refused
+// the first and let the second straight through, which is the bypass review round 1 demonstrated.
+//
+// The rotation is how a POSIX shell function keeps only its first `n` arguments: each of the first
+// `n` is moved to the end, and everything left in front of them is then dropped. A function has its
+// own positional parameters, so the shim's `$@` is untouched and still `exec`s intact.
+function resolver_lines(git_binary: string): Array<string> {
+	return [
+		'guard_dir_of() {',
+		'\tguard_kept=$1',
+		'\tshift',
+		'\tguard_i=0',
+		'\twhile [ "$guard_i" -lt "$guard_kept" ]; do',
+		'\t\tguard_head=$1',
+		'\t\tshift',
+		'\t\tset -- "$@" "$guard_head"',
+		'\t\tguard_i=$((guard_i + 1))',
+		'\tdone',
+		'\twhile [ "$#" -gt "$guard_kept" ]; do shift; done',
+		`\t${shim_shell.quoted(git_binary)} "$@" rev-parse --absolute-git-dir 2>/dev/null`,
+		'}',
+	]
+}
+
+// Finding 2, asked only when finding 1 found nothing — a contaminated environment is already a
+// refusal, and asking git where it would write costs a process.
+function target_lines(guarded_directory: string): Array<string> {
+	const quoted_directory = shim_shell.quoted(guarded_directory)
+
+	return [
+		'if [ -z "$guard_via" ]; then',
+		'\tguard_dir=$(guard_dir_of "$guard_seen" "$@")',
+		'\tcase "$guard_dir" in',
+		`\t\t${quoted_directory}|${quoted_directory}/*) guard_via="a working directory inside $guard_dir" ;;`,
+		'\tesac',
+		'fi',
+	]
+}
+
+function refusal_lines(log_file: string): Array<string> {
+	return [
+		'if [ -n "$guard_via" ]; then',
+		`\t${shim_shell.record_line(log_file, RECORDED_WRITE)}`,
+		`\techo ${shim_shell.quoted(BLOCKED_WRITE_MESSAGE)} >&2`,
+		`\techo "  refused: ${REFUSED_COMMAND}" >&2`,
+		'\texit 1',
+		'fi',
+	]
+}
+
+interface WriteGuard {
+	log_file: string
+	guarded_directory: string | undefined
+}
+
+// Finding 1, with the two variables it answers through declared empty first.
+function environment_findings(): Array<string> {
+	return [
+		"guard_env=''",
+		...environment_lines(),
+		"guard_via=''",
+		'[ -z "$guard_env" ] || guard_via="an inherited git environment:$guard_env"',
+	]
+}
+
+// Finding 1 on its own, which is also the whole of the ambiguous arm.
+function environment_guard_lines(log_file: string): Array<string> {
+	return [...environment_findings(), ...refusal_lines(log_file)]
+}
+
+// The whole `sh` body of the shim's writing-subcommand arm, unindented — the caller indents it into
+// the `case` the way it does the blocking lines it already had. Finding 1 then finding 2, with the
+// refusal after both, so the cheap one answers first and the process is spawned only when it must be.
+function write_guard_lines(guard: WriteGuard): Array<string> {
+	const { guarded_directory } = guard
+
+	if (guarded_directory === undefined) return environment_guard_lines(guard.log_file)
+
+	return [
+		...environment_findings(),
+		...target_lines(guarded_directory),
+		...refusal_lines(guard.log_file),
+	]
+}
+
+// The shim's prelude: the resolver, where there is a repository to resolve against.
+function prelude_lines(git_binary: string, guarded_directory: string | undefined): Array<string> {
+	return guarded_directory === undefined ? [] : resolver_lines(git_binary)
+}
+
+// Which heading a recorded line belongs under. The record is shared with the network guard, so the
+// marker is what tells the two apart at teardown.
+function is_write_violation(call: string): boolean {
+	return call.startsWith(WRITE_MARKER)
+}
+
+const test_repository_guard = {
+	BLOCKED_WRITE_MESSAGE,
+	GIT_AMBIGUOUS_SUBCOMMANDS,
+	GIT_WRITING_SUBCOMMANDS,
+	RESOLUTION_HEADING,
+	WRITE_MARKER,
+	WRITE_VIOLATION_HEADING,
+	environment_guard_lines,
+	guarded_git_directory,
+	is_write_violation,
+	prelude_lines,
+	write_guard_lines,
+}
+
+export { test_repository_guard }
+export type { WriteGuard }