@joshuafolkken/kit 1.1514.0 → 1.2114.0

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

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({
@@ -29,6 +36,7 @@ const ai_review_pull_comment_schema = z.object({
 	body: z.string().optional(),
 	url: z.string().optional(),
 	author: z.object({ login: z.string().optional() }).optional(),
+	updatedAt: z.string().optional(),
 })
 
 const pr_info_schema = z.object({
@@ -40,6 +48,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
@@ -99,6 +109,7 @@ const rest_comment_schema = z.looseObject({
 	body: z.string().nullish(),
 	html_url: z.string().optional(),
 	user: z.looseObject({ login: z.string().optional() }).nullish(),
+	updated_at: z.string().optional(),
 })
 
 // The `number,state,labels,body` read, for the epic check and the `--add` closed-epic refusal.
@@ -128,6 +139,12 @@ const epic_subject_schema = z.object({
 // So `blockedBy` is optional for the reason it is absent in practice — the display and the busy
 // check never ask for it, and a field that was not asked for is left out of the mapped row rather
 // than filled in.
+// Who wrote an issue, as REST names it — read through `gh_author_association.author_of`.
+const author_fields_schema = {
+	author_association: z.string().nullish(),
+	user: z.looseObject({ login: z.string() }).nullish(),
+}
+
 const open_issue_schema = z.object({
 	number: z.number(),
 	title: z.string(),
@@ -136,14 +153,20 @@ const open_issue_schema = z.object({
 	blockedBy: blocked_by_schema,
 	// Present only on the pickup listing, which reads it for the paths each issue declares.
 	body: z.string().optional(),
+	...author_fields_schema,
+	// Assembled by the pickup from the author above, never read off the listing: whether the author
+	// has write access. Absent on every other listing.
+	author_trusted: z.boolean().optional(),
 })
 
 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>
 
 export {
+	author_fields_schema,
 	package_name_schema,
 	rollup_item_schema,
 	pr_raw_schema,
@@ -159,4 +182,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/git-worktree.ts

@@ -19,6 +19,7 @@ import { repository_lock } from './repository-lock'
 // `lane-start-point.ts` and `release-publish.ts` both act on — so this module stops at "what git
 // printed" and the meaning of it is decided there.
 const WORKTREE = 'worktree'
+const ORIGIN = 'origin'
 
 // **Every call that writes `.git/worktrees/` runs under one repository-wide lock**.
 // `git worktree add` is not safe against itself: while one add is still
@@ -87,6 +88,17 @@ async function worktree_add(
 	return await locked([WORKTREE, ...flags, directory, start_point ?? branch_name], SUITE_TIMEOUT_MS)
 }
 
+// **A lane's upstream is written when it is opened, not by its first push**
+// (joshuafolkken/kit#4653). A Codex lane's sandbox cannot write the common directory's `config`, so the
+// `--set-upstream` its push falls back to records nothing, and every later reader of `@{upstream}`
+// would take the pushed lane for an unpushed one. Pointing it at the lane's own name on `origin` keeps
+// a bare `git push` working before the remote branch exists. Under the work-tree lock, since two lanes
+// opened at once would otherwise race on `config.lock`.
+async function set_upstream(branch_name: string): Promise<void> {
+	await locked(['config', `branch.${branch_name}.remote`, ORIGIN])
+	await locked(['config', `branch.${branch_name}.merge`, `refs/heads/${branch_name}`])
+}
+
 // A throwaway tree at one commit, on no branch — `josh test:red` checks the merge-base out here, so
 // the pre-fix tree is built without creating a branch or touching the caller's tree and index.
 async function worktree_add_detached(directory: string, commit: string): Promise<string> {
@@ -139,6 +151,7 @@ async function branch_delete(branch_name: string): Promise<string> {
 const git_worktree = {
 	branch_delete,
 	ls_remote_branch,
+	set_upstream,
 	worktree_add,
 	worktree_add_detached,
 	worktree_list,

package/scripts/git/gone-branch.ts

@@ -7,7 +7,10 @@ import { git_spawn } from './git-spawn'
 // **A branch is removed only when all three hold** — its upstream is gone, it is merged into the
 // default branch, and no work tree has it checked out. Gone alone is not enough: a branch whose remote
 // was deleted by hand before its work merged still holds the only copy of it. A branch with no
-// upstream at all is never gone, so a local-only branch stays.
+// upstream at all is never gone, so a local-only branch stays. A lane branch has its upstream from the
+// moment it opens (`lane-open.ts`), so an unpushed lane reads `[gone]`: the merge test keeps one with
+// commits of its own, and one with none — merged already — is kept by its work tree, then deleted with
+// nothing lost once the tree is gone.
 //
 // **One `for-each-ref` read carries the work-tree answer too** — `%(worktreepath)` is git's own
 // record of which tree holds the branch, so no `git worktree list` parse is repeated here.

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

@@ -0,0 +1,89 @@
+// The resolution of a merge that stopped on `document-byte-budget.ts`'s ceiling rows
+// (joshuafolkken/kit#4976). Two lanes that grow the same page each raise that page's ceiling and add a
+// comment naming their Issue, so the later merge stops on the same row from both sides.
+//
+// **Only a hunk made of ceiling rows and their comments is resolved**: each side is comment lines
+// followed by at most one ceiling row, both rows name the same page, and the result keeps every
+// comment from both sides and the larger ceiling. A hunk holding only comments is resolved only when
+// the row it annotates follows it. Any other hunk — the table's structure, another function — throws,
+// so the merge stays the `conflict` it was. The merged page's size is still checked against the kept
+// ceiling by `document-byte-budget.test.ts`.
+
+const BUDGET_TABLE_PATH = 'scripts/document/document-byte-budget.ts'
+const CEILING_ROW = /^\t\{ path: '(?<path>[^']+)', bytes: (?<bytes>[\d_]+) \},$/u
+const COMMENT_PREFIX = '\t// '
+const CONFLICT_MARKER = /^(?:<{7}|={7}|>{7}|\|{7})/mu
+// A diff3 base section, dropped before the hunks are read: the resolution needs only the two sides.
+const BASE_SECTION = /^\|{7} .*\n(?:.*\n)*?(?=={7}\n)/gmu
+// One conflict hunk; the line after it is captured without being consumed.
+const HUNK = /^<{7} .*\n(?<ours>(?:.*\n)*?)={7}\n(?<theirs>(?:.*\n)*?)>{7} .*\n(?=(?<after>.*))/gmu
+
+interface Side {
+	comments: ReadonlyArray<string>
+	row: string | undefined
+}
+
+function side_of(text: string): Side {
+	const lines = text.split('\n').slice(0, -1)
+	const last = lines.at(-1) ?? ''
+	const row = CEILING_ROW.test(last) ? last : undefined
+	const comments = row === undefined ? lines : lines.slice(0, -1)
+
+	if (comments.some((line) => !line.startsWith(COMMENT_PREFIX))) {
+		throw new Error(`${BUDGET_TABLE_PATH}: a conflict outside the ceiling rows`)
+	}
+
+	return { comments, row }
+}
+
+function ceiling_of(row: string): { path: string; bytes: number } {
+	const groups: Partial<Record<'path' | 'bytes', string>> = CEILING_ROW.exec(row)?.groups ?? {}
+
+	return { path: groups.path ?? '', bytes: Number(groups.bytes?.replaceAll('_', '')) }
+}
+
+function larger_row(ours: string, theirs: string): string {
+	const [mine, other] = [ceiling_of(ours), ceiling_of(theirs)]
+
+	if (mine.path !== other.path) {
+		throw new Error(
+			`${BUDGET_TABLE_PATH}: rows of two pages conflict (${mine.path}, ${other.path})`,
+		)
+	}
+
+	return mine.bytes >= other.bytes ? ours : theirs
+}
+
+function rows_of(ours: Side, theirs: Side, after: string): ReadonlyArray<string> {
+	if (ours.row !== undefined && theirs.row !== undefined) return [larger_row(ours.row, theirs.row)]
+	// Equal here only when both are undefined: a hunk of comments alone, kept only above a row.
+	if (ours.row === theirs.row && CEILING_ROW.test(after)) return []
+
+	throw new Error(`${BUDGET_TABLE_PATH}: a ceiling row changed on one side only`)
+}
+
+function merge_hunk(ours: string, theirs: string, after: string): string {
+	const [mine, other] = [side_of(ours), side_of(theirs)]
+	const comments = [...new Set([...mine.comments, ...other.comments])]
+
+	return [...comments, ...rows_of(mine, other, after)].map((line) => `${line}\n`).join('')
+}
+
+// The file with every hunk resolved; throws when any hunk is not a ceiling-row conflict.
+function resolve(content: string): string {
+	const resolved = content
+		.replaceAll(BASE_SECTION, '')
+		.replaceAll(HUNK, (_hunk: string, ours: string, theirs: string, after: string) =>
+			merge_hunk(ours, theirs, after),
+		)
+
+	if (resolved === content || CONFLICT_MARKER.test(resolved)) {
+		throw new Error(`${BUDGET_TABLE_PATH}: a conflict left unresolved`)
+	}
+
+	return resolved
+}
+
+const main_merge_budget_conflict = { BUDGET_TABLE_PATH, resolve }
+
+export { main_merge_budget_conflict }