@joshuafolkken/kit 1.1471.0 → 1.1784.0

package/scripts/gh/git-gh-pr.ts

@@ -1,9 +1,9 @@
 import { pr_classification, type ReleaseClassification } from '#scripts/ci/pr-classification'
 import { git_command } from '#scripts/git/git-command'
 import { poll } from '#scripts/lib/poll'
-import { z } from 'zod'
 import { git_gh_api_path } from './git-gh-api-path'
 import { git_gh_exec } from './git-gh-exec'
+import { gh_failure } from './git-gh-failure'
 import { git_gh_helpers } from './git-gh-helpers'
 import { git_gh_issue_write } from './git-gh-issue-write'
 import { forget_pr_numbers, git_gh_pr_read, read_pull, require_pr_number } from './git-gh-pr-read'
@@ -49,25 +49,27 @@ const MERGE_UNCONFIRMED_MESSAGE =
 	'gh api could not read the pull request back after the merge request failed'
 const MERGE_READ_BACK_ATTEMPTS = 3
 const MERGE_READ_BACK_INTERVAL_MS = 1000
+// `PUT pulls/{N}/merge` with a `sha` that is no longer the branch head.
+const HEAD_MOVED_STATUS = 409
 const PR_NUMBER_PATTERN = /\/pull\/([1-9]\d*)$/u
-const LABELS_SEGMENT = '/labels'
-const PR_LABELS = z.array(z.object({ name: z.string() }))
 
+// A pull request is an issue to the labels endpoint, so the write is the issue one: a failed answer
+// is confirmed by reading the labels back before it is reported as a failed write.
 async function add_pr_classification(number: string, label: ReleaseClassification): Promise<void> {
-	await git_gh_exec.exec_gh_api({
-		path: `${git_gh_api_path.issue_api_path(number)}${LABELS_SEGMENT}`,
-		body: JSON.stringify({ labels: [label] }),
-	})
+	const write = await git_gh_issue_write.issue_apply_label(number, label)
+
+	if (!write.is_applied) throw new Error(write.reason)
 }
 
+// Labels that could not be read are not "no classification": answering that would add a second
+// classification beside the one a person already put on the pull request.
 async function pr_get_classification(
 	branch_name: string,
 ): Promise<ReleaseClassification | undefined> {
 	const number = await require_pr_number(branch_name)
-	const response = await git_gh_exec.exec_gh_api({
-		path: `${git_gh_api_path.issue_api_path(String(number))}${LABELS_SEGMENT}`,
-	})
-	const names = PR_LABELS.parse(JSON.parse(response)).map((label) => label.name.toLowerCase())
+	const labels = await git_gh_issue_write.read_label_names(String(number))
+	if (labels === undefined) throw new Error(`Unreadable labels on branch ${branch_name}`)
+	const names = labels.map((name) => name.toLowerCase())
 	const selected = names.filter((name) => pr_classification.is_classification(name))
 	if (selected.length === 0) return undefined
 
@@ -166,16 +168,25 @@ async function pr_update_body(branch_name: string, body: string): Promise<void>
 }
 
 // A merge moves the remembered detail read's state, so it is cleared first.
-async function put_merge(pr_number: number): Promise<void> {
+//
+// **`sha` binds the merge to the head the checks passed on** (#4036): without it GitHub merges
+// whatever the branch points at, so a commit pushed after the gate went green would land unverified.
+// A head that moved is answered 409 (`is_head_moved`).
+async function put_merge(pr_number: number, head_sha: string): Promise<void> {
 	forget_pr_numbers()
 	await git_gh_exec.exec_gh_api({
 		path: git_gh_api_path.pull_merge_api_path(String(pr_number)),
 		method: PUT_METHOD,
-		body: JSON.stringify({ merge_method: MERGE_COMMIT_METHOD }),
+		body: JSON.stringify({ merge_method: MERGE_COMMIT_METHOD, sha: head_sha }),
 		timeout_ms: MERGE_REQUEST_TIMEOUT_MS,
 	})
 }
 
+// GitHub's answer to a merge whose `sha` is no longer the branch head.
+function is_head_moved(error: unknown): boolean {
+	return gh_failure.failure_of(error)?.status === HEAD_MOVED_STATUS
+}
+
 // `undefined` is "nobody read it", kept apart from the `false` that means "the pull request is not
 // merged". Folding the two would report an unread state as a settled answer.
 async function read_merge_state(pr_number: number): Promise<boolean | undefined> {
@@ -240,11 +251,11 @@ async function has_merge_landed(pr_number: number, merge_error: unknown): Promis
 // made by hand between the failure and the read leaves `followup` with exactly the same work to
 // finish. REST offers nothing that would tell the two apart without keeping the merge commit's SHA
 // across a request that never answered.
-async function pr_merge(branch_name: string): Promise<void> {
+async function pr_merge(branch_name: string, head_sha: string): Promise<void> {
 	const pr_number = await require_pr_number(branch_name)
 
 	try {
-		await put_merge(pr_number)
+		await put_merge(pr_number, head_sha)
 	} catch (error) {
 		if (!(await has_merge_landed(pr_number, error))) throw error
 	}
@@ -259,6 +270,7 @@ const git_gh_pr = {
 	pr_comment,
 	pr_merge,
 	pr_update_body,
+	is_head_moved,
 }
 
 export { git_gh_pr, MERGE_COMMIT_METHOD, MERGE_REQUEST_TIMEOUT_MS, MERGE_UNCONFIRMED_MESSAGE }

package/scripts/gh/git-pr-checks-eval.ts

@@ -2,6 +2,7 @@ import {
 	CHECK_STATUS_FAIL,
 	CHECK_STATUS_MISSING,
 	CHECK_STATUS_PASS,
+	CHECK_STATUS_PENDING,
 	type PrStateSnapshot,
 	type RollupCheck,
 } from './git-pr-checks-parse'
@@ -12,7 +13,7 @@ import {
 // to restore the old behavior. Revert once the fresh-context review subagent replaces it.
 const DEFAULT_REQUIRED_CHECKS = ['SonarQube']
 // The single source of the check name every CodeRabbit exemption is keyed on — the merge gate's
-// `is_unstable_only_from_coderabbit`, the look-ahead's `is_awaited_check`, and the fixtures the two
+// `is_unstable_only_from_optional`, the look-ahead's `is_awaited_check`, and the fixtures the two
 // are tested from. A second literal spelling of it anywhere is how one of them silently stops
 // matching after CodeRabbit renames its context.
 const CODERABBIT_CHECK_NAME = 'CodeRabbit'
@@ -131,15 +132,46 @@ function is_coderabbit_rate_limited(check: RollupCheck): boolean {
 	)
 }
 
-// Temporary: a pending or failing CodeRabbit check makes GitHub report UNSTABLE even
-// though CodeRabbit is not required. Accept that state only when CodeRabbit checks are the
-// sole non-passing ones — any other non-passing check keeps the gate strict.
-function is_unstable_only_from_coderabbit(snapshot: PrStateSnapshot): boolean {
+function matches_any(check_name: string, required_names: ReadonlyArray<string>): boolean {
+	return required_names.some((required) => is_required_match(check_name, required))
+}
+
+// A check still running that the base branch's rules do not require — GitHub's default-setup
+// `CodeQL`, which runs for about thirty minutes beside a six-minute CI (joshuafolkken/kit#4351).
+// With no required context known nothing qualifies, so the gate waits for `CLEAN` as it always did.
+function is_optional_pending(
+	check: RollupCheck,
+	required_contexts: ReadonlyArray<string>,
+): boolean {
+	if (required_contexts.length === 0 || check.status !== CHECK_STATUS_PENDING) return false
+
+	return !matches_any(check.name, required_contexts)
+}
+
+function is_every_context_passing(
+	checks: ReadonlyArray<RollupCheck>,
+	contexts: ReadonlyArray<string>,
+): boolean {
+	return contexts.every(
+		(context) => find_required_check(checks, context)?.status === CHECK_STATUS_PASS,
+	)
+}
+
+// GitHub reports UNSTABLE for a pull request whose required checks are green while a check outside
+// them is pending or failing. Accept that state when every non-passing check is CodeRabbit's
+// (temporary: CodeRabbit is not required) or an optional one still running, and every context the
+// base branch requires has passed in the rollup itself — any other non-passing check keeps the gate
+// strict. A failed optional check never reaches here: `collect_blocking_failures` ends the wait first.
+function is_unstable_only_from_optional(snapshot: PrStateSnapshot): boolean {
 	if (snapshot.merge_state_status !== MERGE_STATE_UNSTABLE) return false
+	const required_contexts = snapshot.required_contexts ?? []
 	const non_passing = snapshot.rollup.filter((check) => check.status !== CHECK_STATUS_PASS)
 	if (non_passing.length === 0) return false
+	const is_tolerated = non_passing.every(
+		(check) => is_coderabbit_check(check.name) || is_optional_pending(check, required_contexts),
+	)
 
-	return non_passing.every((check) => is_coderabbit_check(check.name))
+	return is_tolerated && is_every_context_passing(snapshot.rollup, required_contexts)
 }
 
 function is_required_check(check_name: string): boolean {
@@ -169,7 +201,7 @@ function collect_blocking_failures(snapshot: PrStateSnapshot): Array<string> {
 function is_mergeable_state(snapshot: PrStateSnapshot): boolean {
 	if (is_merge_state_clean(snapshot.merge_state_status)) return true
 
-	return is_unstable_only_from_coderabbit(snapshot)
+	return is_unstable_only_from_optional(snapshot)
 }
 
 // The wait's own error text: naming the checks that failed is what turns a red `followup` into

package/scripts/gh/git-pr-checks-parse.ts

@@ -1,5 +1,6 @@
 import { pr_raw_schema, type RollupItemData } from '#scripts/git/git-schemas'
 import { json_value } from '#scripts/lib/json-value'
+import type { z } from 'zod'
 
 const CHECK_STATUS_PASS = 'pass'
 const CHECK_STATUS_PENDING = 'pending'
@@ -9,8 +10,8 @@ const CHECK_STATUS_MISSING = 'missing'
 // GitHub reports a job whose `if:` condition was false as COMPLETED with conclusion `skipped`, and
 // counts it as satisfied for branch protection — a pull request reaches CLEAN with such jobs in its
 // rollup. Recording them as `fail` would disagree with GitHub itself, and it would disable the
-// CodeRabbit non-blocking exemption: `is_unstable_only_from_coderabbit` opens the gate only when
-// every non-passing check is CodeRabbit's, so kit's own conditional jobs (`auto-merge`, `E2E`,
+// CodeRabbit non-blocking exemption: `is_unstable_only_from_optional` opens the gate only when
+// every non-passing check is CodeRabbit's or an optional one still running, so kit's own conditional jobs (`auto-merge`, `E2E`,
 // `Notify Auto Tag`) would keep a slow review blocking the merge until the wait loop timed out. That
 // is invisible on fast reviews, where CLEAN short-circuits the predicate — it surfaces only on the
 // exact path the exemption exists to protect.
@@ -45,6 +46,12 @@ interface PrStateSnapshot {
 	rollup: Array<RollupCheck>
 	merge_state_status: string | undefined
 	review_decision: string | undefined
+	// The commit `rollup` was read from — the head a merge has to name so that it lands what passed and
+	// nothing pushed since (#4036). Absent where the snapshot carried none.
+	head_sha?: string
+	// The base branch's required status check contexts (joshuafolkken/kit#4351). Absent where the
+	// branch requires none or they could not be read, which keeps the merge gate waiting for `CLEAN`.
+	required_contexts?: Array<string>
 }
 
 function read_string(value: unknown): string | undefined {
@@ -118,16 +125,39 @@ function parse_rollup_checks(raw_json: string): Array<RollupCheck> {
 	return checks
 }
 
-function parse_pr_state_snapshot(raw_json: string): PrStateSnapshot {
-	const parsed = json_value.parse_or_undefined(raw_json)
-	const result = pr_raw_schema.safeParse(parsed)
-	const data = result.success ? result.data : undefined
+function with_head_sha(snapshot: PrStateSnapshot, head_sha: string | undefined): PrStateSnapshot {
+	return head_sha === undefined ? snapshot : { ...snapshot, head_sha }
+}
+
+function with_required_contexts(
+	snapshot: PrStateSnapshot,
+	required_contexts: Array<string> | undefined,
+): PrStateSnapshot {
+	if (required_contexts === undefined || required_contexts.length === 0) return snapshot
+
+	return { ...snapshot, required_contexts }
+}
 
-	return {
+type PrRawData = Partial<z.infer<typeof pr_raw_schema>>
+
+function read_pr_raw_data(raw_json: string): PrRawData {
+	const result = pr_raw_schema.safeParse(json_value.parse_or_undefined(raw_json))
+
+	return result.success ? result.data : {}
+}
+
+function parse_pr_state_snapshot(raw_json: string): PrStateSnapshot {
+	const data = read_pr_raw_data(raw_json)
+	const snapshot = {
 		rollup: parse_rollup_checks(raw_json),
-		merge_state_status: read_string(data?.mergeStateStatus),
-		review_decision: read_string(data?.reviewDecision),
+		merge_state_status: read_string(data.mergeStateStatus),
+		review_decision: read_string(data.reviewDecision),
 	}
+
+	return with_required_contexts(
+		with_head_sha(snapshot, read_string(data.headRefOid)),
+		data.requiredContexts,
+	)
 }
 
 export {

package/scripts/gh/git-pr-merge-checked.ts

@@ -0,0 +1,80 @@
+import { git_gh_command } from './git-gh-command'
+import { git_pr_checks, type PrStateSnapshot } from './git-pr-checks'
+
+// **A merge lands the head the merge gate passed, and nothing pushed after it** (#4036).
+//
+// The gate reads the checks of one commit, and the merge request names that commit as its `sha`. A
+// push between the two moves the head, GitHub answers 409, and the wait starts over on the new head
+// — so the push is merged once its own checks pass, with nobody having to re-run anything. The
+// retries are bounded: a branch that keeps moving under every wait is not one to merge unattended.
+
+const MAX_HEAD_MOVES = 3
+const NO_CHECKED_HEAD_MESSAGE =
+	'The merge gate answered without the head commit it checked, so there is no commit to bind the merge to'
+const HEAD_MOVED_NOTE =
+	'The pull request head moved after its checks passed — waiting on the new head'
+const HEAD_KEPT_MOVING_MESSAGE = `The pull request head moved after its checks passed ${String(MAX_HEAD_MOVES)} times, so it was not merged`
+
+type WaitForGreen = () => Promise<PrStateSnapshot>
+
+interface CheckedMerge {
+	branch_name: string
+	// The wait to go back to when the head moved — the caller's own, so a re-wait watches what the
+	// first wait watched.
+	wait_for_green: WaitForGreen
+	// The snapshot the gate already passed. Absent, the merge waits for one first.
+	checked?: PrStateSnapshot | undefined
+}
+
+function checked_head(snapshot: PrStateSnapshot): string {
+	if (snapshot.head_sha === undefined) throw new Error(NO_CHECKED_HEAD_MESSAGE)
+
+	return snapshot.head_sha
+}
+
+// `false` is "the head moved"; every other failure is the caller's to see.
+async function try_merge(branch_name: string, snapshot: PrStateSnapshot): Promise<boolean> {
+	const head_sha = checked_head(snapshot)
+
+	try {
+		await git_gh_command.pr_merge(branch_name, head_sha)
+
+		return true
+	} catch (error) {
+		if (!git_gh_command.is_head_moved(error)) throw error
+
+		return false
+	}
+}
+
+async function merge_checked(input: CheckedMerge): Promise<void> {
+	let snapshot = input.checked ?? (await input.wait_for_green())
+
+	for (let move = 0; move < MAX_HEAD_MOVES; move += 1) {
+		// eslint-disable-next-line no-await-in-loop -- each merge names the head the wait before it passed
+		if (await try_merge(input.branch_name, snapshot)) return
+
+		console.info(HEAD_MOVED_NOTE)
+		// eslint-disable-next-line no-await-in-loop -- the new head has to pass before it is merged
+		snapshot = await input.wait_for_green()
+	}
+
+	throw new Error(HEAD_KEPT_MOVING_MESSAGE)
+}
+
+// The merge gate's default wait, then the bound merge.
+async function merge_when_green(branch_name: string): Promise<void> {
+	async function wait_for_green(): Promise<PrStateSnapshot> {
+		return await git_pr_checks.wait_for_pr_success(branch_name)
+	}
+
+	await merge_checked({ branch_name, wait_for_green })
+}
+
+const git_pr_merge_checked = {
+	merge_checked,
+	merge_when_green,
+}
+
+export type { CheckedMerge, WaitForGreen }
+export { git_pr_merge_checked, HEAD_KEPT_MOVING_MESSAGE, MAX_HEAD_MOVES, NO_CHECKED_HEAD_MESSAGE }

package/scripts/gh/git-pr.ts

@@ -5,6 +5,7 @@ import { issue_cite } from '#scripts/issue/issue-cite'
 import { session_cite } from '#scripts/issue/session-cite'
 import { animation_helpers, type AnimationOptions } from '#scripts/lib/animation-helpers'
 import { json_value } from '#scripts/lib/json-value'
+import { acceptance_map } from '#scripts/review/acceptance-map'
 import { git_gh_command } from './git-gh-command'
 import { git_pr_error } from './git-pr-error'
 import { git_pr_messages } from './git-pr-messages'
@@ -172,6 +173,17 @@ function build_body(issue_info: IssueInfo, extra_body?: string): string {
 	return `${closes}\n\n${extra_body}`
 }
 
+// A body without the acceptance-criteria table gets one pending row per criterion, so the author fills
+// in rows that already carry their identifiers — `josh followup` refuses the merge until they do.
+async function body_with_map(issue_info: IssueInfo, extra_body?: string): Promise<string> {
+	const body = build_body(issue_info, extra_body)
+
+	if (acceptance_map.has_map(body)) return body
+	const map = acceptance_map.skeleton(await git_gh_command.issue_get_body(issue_info.number))
+
+	return map === undefined ? body : `${body}\n\n${map}`
+}
+
 async function existing_pr_label(branch_name: string): Promise<ReleaseClassification | undefined> {
 	if (
 		!(await git_gh_command.pr_exists(branch_name)) ||
@@ -190,7 +202,7 @@ async function create_for_issue(
 ): Promise<void> {
 	await create(
 		build_title(issue_info),
-		build_body(issue_info, extra_body),
+		await body_with_map(issue_info, extra_body),
 		issue_info.branch_name,
 		{
 			label,

package/scripts/git/base-tree.ts

@@ -1,4 +1,4 @@
-import { mkdtemp, rm, symlink } from 'node:fs/promises'
+import { copyFile, mkdir, mkdtemp, rm, symlink } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import path from 'node:path'
 import { git_worktree } from './git-worktree'
@@ -60,7 +60,24 @@ async function with_tree<T>(
 	}
 }
 
-const base_tree = { NODE_MODULES, with_tree }
+async function copy_one(tree: string, file: string): Promise<void> {
+	const target = path.join(tree, file)
+
+	await mkdir(path.dirname(target), { recursive: true })
+	await copyFile(file, target)
+}
+
+// The caller's working-tree files into the tree at the same relative paths. Each file has its own
+// target, and a recursive `mkdir` tolerates a sibling creating the same parent.
+async function copy_in(tree: string, files: ReadonlyArray<string>): Promise<void> {
+	await Promise.all(
+		files.map(async (file) => {
+			await copy_one(tree, file)
+		}),
+	)
+}
+
+const base_tree = { NODE_MODULES, copy_in, with_tree }
 
 export type { BaseTree }
 export { base_tree }

package/scripts/git/changed-file-scope.ts

@@ -11,9 +11,10 @@ import { git_command } from './git-command'
 // nothing, and listing what was narrowed by — is identical, so it lives here once rather than in
 // each command.
 //
-// **A narrowed run is added in front of the whole check, never in place of it.** Both fallbacks
-// therefore end at the whole check, and each says which of the two it was: the one thing this must
-// never do is answer "nothing to run" quietly.
+// The narrowed unit run replaces the whole suite in the gate (joshuafolkken/kit#4065), and the
+// narrowed lint the whole-tree lint (joshuafolkken/kit#4085), each with CI's whole run behind it.
+// Either way both fallbacks end at the whole check, and each says which of the two it was: the
+// one thing this must never do is answer "nothing to run" quietly.
 
 type ScopeMode = 'all' | 'related'
 
@@ -176,7 +177,7 @@ async function resolve_command_scope(request: ScopeRequest): Promise<ChangedFile
 // describing a set the caller never handed over.
 function report_unusable_arguments(
 	command_arguments: ReadonlyArray<string>,
-	scope: ChangedFileScope,
+	scope: Pick<ChangedFileScope, 'files'>,
 	label: string,
 ): void {
 	const narrowed = new Set(scope.files)
@@ -195,6 +196,7 @@ const changed_file_scope = {
 	UNREADABLE_REASON,
 	describe_scope,
 	flags_of,
+	format_file_list,
 	is_flag,
 	read_changed_files,
 	report_unusable_arguments,

package/scripts/git/changed-paths.ts

@@ -24,6 +24,23 @@ async function read_changed_paths(is_staged: boolean): Promise<Array<string>> {
 	return [...tracked, ...untracked]
 }
 
-const changed_paths = { read_changed_paths, to_paths }
+// The same reading against any commit rather than the change base — the change since the tree a
+// test-read map was recorded on.
+async function read_changed_since(commit: string): Promise<Array<string>> {
+	const tracked = to_paths(await git_command.diff_names_since(commit))
+	const untracked = to_paths(await git_command.untracked_names())
+
+	return [...new Set([...tracked, ...untracked])]
+}
+
+// The paths among `paths` the tree of `commit` held. An empty list asks git nothing, since
+// `ls-tree` with no path lists the whole tree.
+async function read_held_at(commit: string, paths: ReadonlyArray<string>): Promise<Array<string>> {
+	if (paths.length === 0) return []
+
+	return to_paths(await git_command.tree_names_at(commit, paths))
+}
+
+const changed_paths = { read_changed_paths, read_changed_since, read_held_at, to_paths }
 
 export { changed_paths }

package/scripts/git/git-diff-reads.ts

@@ -151,18 +151,41 @@ async function change_base_commit(): Promise<string> {
 	return await git_spawn.read(['rev-parse', await change_base()])
 }
 
-async function diff_main_names(): Promise<string> {
+// The working tree against any commit, with the same flags as the branch diff. `josh test:related`
+// reads the change since the commit its test-read map was recorded on, which is not the merge base.
+async function diff_names_since(commit: string): Promise<string> {
 	return await git_spawn.read([
 		...NO_PATH_QUOTING,
 		'diff',
 		NAME_ONLY_FLAG,
 		NO_RELATIVE_PATHS,
 		NO_RENAME_DETECTION,
-		await change_base(),
+		commit,
+		'--',
+	])
+}
+
+// Which of `paths` a commit's tree holds. `josh test:related` asks it of the tree its test-read map
+// was recorded on: a file that tree held and no test read is one no test reads, while a file added
+// since is one the map knows nothing about. **Callers pass at least one path** — with none, `ls-tree`
+// lists the whole tree.
+async function tree_names_at(commit: string, paths: ReadonlyArray<string>): Promise<string> {
+	return await git_spawn.read([
+		...NO_PATH_QUOTING,
+		'ls-tree',
+		'-r',
+		NAME_ONLY_FLAG,
+		'--full-tree',
+		commit,
 		'--',
+		...paths,
 	])
 }
 
+async function diff_main_names(): Promise<string> {
+	return await diff_names_since(await change_base())
+}
+
 async function diff_cached_names(): Promise<string> {
 	return await git_spawn.read([
 		...NO_PATH_QUOTING,
@@ -224,7 +247,9 @@ const git_diff_reads = {
 	diff_main,
 	diff_main_names,
 	diff_main_numstat,
+	diff_names_since,
 	get_default_branch,
+	tree_names_at,
 	untracked_names,
 }
 

package/scripts/git/git-grep-hits.ts

@@ -0,0 +1,85 @@
+import { get_exit_code } from '#scripts/git/git-execa-error'
+import { git_spawn } from '#scripts/git/git-spawn'
+
+// One fixed-string `git grep -n` over a pathspec, read back as `file:line` hits with a short excerpt.
+// `run:prep`'s code locations and `plan:consumers` both search a name this way, so the parse and the
+// no-match-versus-failure reading live here rather than in each.
+
+const GREP_LINE = /^(?<path>[^:]+):(?<line>\d+):(?<text>.*)$/u
+const MAX_EXCERPT_LENGTH = 80
+const ELLIPSIS = '…'
+// `git grep` exits 1 for no match; any other exit is a search that never ran.
+const GREP_NO_MATCH_EXIT = 1
+
+interface Hit {
+	path: string
+	line: string
+	excerpt: string
+}
+
+interface GrepResult {
+	hits: ReadonlyArray<Hit>
+	has_failed: boolean
+}
+
+function shorten(text: string): string {
+	const trimmed = text.trim()
+
+	if (trimmed.length <= MAX_EXCERPT_LENGTH) return trimmed
+
+	return `${trimmed.slice(0, MAX_EXCERPT_LENGTH)}${ELLIPSIS}`
+}
+
+// `git grep -n` prints `path:line:text`; the text may itself hold colons, so only the first two split.
+function to_hit(output_line: string): Hit | undefined {
+	const groups = GREP_LINE.exec(output_line)?.groups
+
+	if (groups === undefined) return undefined
+
+	// All three groups are non-optional in `GREP_LINE`, so a match always carries each of them.
+	const { path, line, text } = groups as Record<'line' | 'path' | 'text', string>
+
+	return { path, line, excerpt: shorten(text) }
+}
+
+function parse(stdout: string): Array<Hit> {
+	const hits = stdout.split('\n').map((line) => to_hit(line))
+
+	return hits.filter((hit): hit is Hit => hit !== undefined)
+}
+
+// `git grep` exits 1 when nothing matches, which `git_spawn.read` raises. Only that is "no match": a
+// git without `grep -m` (older than 2.38) exits 129, and naming every target absent then would send
+// the reader away from code that is there. `root` searches that checkout rather than the working
+// directory's.
+async function search(
+	target: string,
+	flags: ReadonlyArray<string>,
+	pathspecs: ReadonlyArray<string>,
+	root?: string,
+): Promise<GrepResult> {
+	const location = root === undefined ? [] : ['-C', root]
+	const grep_arguments = [
+		...location,
+		'grep',
+		'-n',
+		'-I',
+		'-F',
+		...flags,
+		'-e',
+		target,
+		'--',
+		...pathspecs,
+	]
+
+	try {
+		return { hits: parse(await git_spawn.read(grep_arguments)), has_failed: false }
+	} catch (error) {
+		return { hits: [], has_failed: get_exit_code(error) !== GREP_NO_MATCH_EXIT }
+	}
+}
+
+const git_grep_hits = { parse, search }
+
+export type { GrepResult, Hit }
+export { git_grep_hits }

package/scripts/git/git-location-environment.ts

@@ -9,7 +9,7 @@
 //
 // The list is single-sourced here because it has three consumers that must not drift apart: the
 // probes that clear it, the fixture that clears it, and the unit-suite guard that refuses a write
-// while any of it is set (`scripts/test/test-repository-guard.ts`).
+// while any of it is set (`tools/test/test-repository-guard.ts`).
 //
 // **Only the variables that redirect where git writes are listed.** `GIT_PREFIX`, `GIT_EDITOR` and
 // the `GIT_CONFIG_*` family are exported to hooks too and are deliberately absent: clearing them