@joshuafolkken/kit 1.1435.0 → 1.1453.0

package/scripts/auto-ok/auto-ok-judge.ts

@@ -0,0 +1,67 @@
+import { createHash } from 'node:crypto'
+import { issue_auto_ok, type AutoOkDecision } from '#scripts/issue/issue-auto-ok'
+import { AUTO_OK_LABEL, has_label_name } from '#scripts/issue/issue-labels'
+import type { WatchComment } from '#scripts/issue/issue-watch-diff'
+
+// The pure half of `josh auto-ok:judge`: which open issues `backlogrun` judges for `auto-ok` when a lane
+// is free and nothing is opted in, and whether one was already judged (joshuafolkken/kit#3854).
+//
+// **The mechanical exclusions are `issue_auto_ok.exclusion_of`**, the list a filing is judged by
+// (joshuafolkken/kit#3853), never a second one. What a label cannot answer — whether a policy decision,
+// an external account or a human visual check is needed — is the agent's reading of the body and the
+// comments, so this module only says which issues still owe that reading.
+//
+// **The record is the judgement comment itself.** It carries a digest of the body it judged, so an
+// issue is judged again only when its body changed or a person commented after it — the same line
+// `issue_watch_diff` draws between a person's update and an automated one.
+
+interface JudgeIssue {
+	number: number
+	labels: ReadonlyArray<string>
+	body: string
+}
+
+const MARKER_PREFIX = '<!-- josh:auto-ok-judged body='
+const MARKER_SUFFIX = ' -->'
+const MARKER_PATTERN = /<!-- josh:auto-ok-judged body=(?<digest>[\da-f]+) -->/u
+const DIGEST_LENGTH = 16
+const CRLF = '\r\n'
+const LF = '\n'
+
+function is_candidate(issue: JudgeIssue): boolean {
+	if (has_label_name(issue.labels, AUTO_OK_LABEL)) return false
+
+	return issue_auto_ok.exclusion_of(issue.labels) === undefined
+}
+
+// GitHub stores a body saved in its web editor with CRLF, so the digest is taken over LF alone.
+function body_digest(body: string): string {
+	const normalized = body.split(CRLF).join(LF)
+
+	return createHash('sha256').update(normalized).digest('hex').slice(0, DIGEST_LENGTH)
+}
+
+function digest_of(comment: WatchComment): string | undefined {
+	return MARKER_PATTERN.exec(comment.body)?.groups?.['digest']
+}
+
+// Judged when the newest judgement comment covers the body as it stands and no person has commented
+// since. A failed comment read never reaches here — the caller treats it as nothing learned.
+function is_judged(body: string, comments: ReadonlyArray<WatchComment>): boolean {
+	const judgement = comments.findLast((comment) => digest_of(comment) !== undefined)
+
+	if (judgement === undefined || digest_of(judgement) !== body_digest(body)) return false
+
+	return comments.every((comment) => comment.id <= judgement.id || comment.is_automated)
+}
+
+function comment_of(decision: AutoOkDecision, body: string): string {
+	const marker = `${MARKER_PREFIX}${body_digest(body)}${MARKER_SUFFIX}`
+
+	return `${issue_auto_ok.line_of(decision)}${LF}${LF}${marker}`
+}
+
+const auto_ok_judge = { comment_of, is_candidate, is_judged }
+
+export type { JudgeIssue }
+export { auto_ok_judge }

package/scripts/backlog/backlog-drive-cli.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env tsx
 import { setTimeout as sleep } from 'node:timers/promises'
 import { fileURLToPath } from 'node:url'
+import { auto_ok_judge_read, type JudgedCache } from '#scripts/auto-ok/auto-ok-judge-read'
 import { issue_cite } from '#scripts/issue/issue-cite'
 import { hook_decision } from '#scripts/josh/hook-decision'
 import { josh_command } from '#scripts/josh/josh-run'
@@ -166,6 +167,18 @@ function end_line(end: DriveEnd): string {
 	return end.detail === undefined ? base : `${base} ${end.detail}`
 }
 
+// The count of open issues owing an `auto-ok` judgement, over a cache kept for the process so a watch
+// minute reads the comments only of the issues that moved (`auto-ok-judge-read.ts`).
+function judgement_reader(): () => Promise<number> {
+	const cache: JudgedCache = new Map()
+
+	return async () => {
+		const owed = await auto_ok_judge_read.owed(cache)
+
+		return owed?.length ?? 0
+	}
+}
+
 function ports_of(
 	context: DriveContext,
 	seeded: ReadonlyArray<string>,
@@ -177,6 +190,7 @@ function ports_of(
 		offer: async (state) => await read_offer(state, context),
 		launch: async (issue) => await backlog_drive_launch.launch(issue, context.owner),
 		free_lanes: backlog_ready.drive_free_lane_count,
+		judgement_owed: judgement_reader(),
 		now: () => new Date(),
 		sleep: async (milliseconds) => {
 			await sleep(milliseconds)

package/scripts/backlog/backlog-drive.ts

@@ -65,6 +65,8 @@ const KNOWN_VERDICTS: ReadonlySet<string> = new Set([
 ])
 const NO_RETRIES = 0
 const NO_FREE_LANES = 0
+const EXHAUSTED_ANSWER = 'exhausted'
+const JUDGE_REASON = 'judge'
 const LAUNCHED = 'launched'
 const UNOPENED = 'unopened'
 
@@ -98,7 +100,8 @@ interface DriveState {
 }
 
 interface DriveEnd {
-	// Why the loop handed control back: `merge`, `launch`, `offer`, `watch`, `stop`, `window` or a verdict.
+	// Why the loop handed control back: `merge`, `launch`, `offer`, `judge`, `watch`, `stop`, `window`
+	// or a verdict.
 	reason: string
 	// The token the parent reads, where one command printed it.
 	token: string | undefined
@@ -121,6 +124,9 @@ interface DrivePorts {
 	// The lanes free right now — `backlog_ready.drive_free_lane_count` in production, the limit less the
 	// open lanes.
 	free_lanes: () => Promise<number>
+	// How many open issues lacking `auto-ok` still owe a judgement — `auto_ok_judge_read.owed` in
+	// production, `0` when the read failed.
+	judgement_owed: () => Promise<number>
 	now: () => Date
 }
 
@@ -149,7 +155,7 @@ function ended(reason: string, state: DriveState, token?: string, issue?: string
 function is_drain(read: OfferRead, state: DriveState): boolean {
 	return (
 		read.verdict === WATCH_VERDICT &&
-		read.answer === 'exhausted' &&
+		read.answer === EXHAUSTED_ANSWER &&
 		state.in_flight.length === 0 &&
 		read.is_retrospective_owed === true
 	)
@@ -158,7 +164,7 @@ function is_drain(read: OfferRead, state: DriveState): boolean {
 function needs_retrospective(read: OfferRead, state: DriveState): boolean {
 	return (
 		read.verdict === STOP_VERDICT &&
-		read.answer === 'exhausted' &&
+		read.answer === EXHAUSTED_ANSWER &&
 		state.in_flight.length === 0 &&
 		read.is_retrospective_owed === true
 	)
@@ -318,6 +324,18 @@ function on_verdict(read: OfferRead, state: DriveState): PassResult {
 	return { kind: 'continue', state }
 }
 
+// **A free lane with nothing opted in is the open backlog's turn to be judged**
+// (joshuafolkken/kit#3854): a watch over an exhausted pool hands back `judge` while an open issue
+// lacking `auto-ok` still owes a judgement, ahead of the drain it would otherwise be. Once every one
+// carries its judgement comment the count is zero and the watch is the driver's again.
+async function is_judgement_owed(read: OfferRead, ports: DrivePorts): Promise<boolean> {
+	const is_exhausted = read.verdict === WATCH_VERDICT && read.answer === EXHAUSTED_ANSWER
+
+	if (!is_exhausted || (await ports.free_lanes()) <= NO_FREE_LANES) return false
+
+	return (await ports.judgement_owed()) > 0
+}
+
 async function ask_offer(state: DriveState, ports: DrivePorts): Promise<PassResult> {
 	const read = await ports.offer(state)
 
@@ -326,6 +344,7 @@ async function ask_offer(state: DriveState, ports: DrivePorts): Promise<PassResu
 	const next = { ...state, retries: read.retries }
 
 	if (read.verdict === RUN_VERDICT) return await launch_all(read.issues, next, ports)
+	if (await is_judgement_owed(read, ports)) return ended(JUDGE_REASON, next, JUDGE_REASON)
 
 	return on_verdict(read, next)
 }

package/scripts/document/document-byte-budget.ts

@@ -76,7 +76,7 @@ const DOCUMENT_BYTE_BUDGET: ReadonlyArray<DocumentBudget> = [
 	{ path: 'docs/josh-commands-automation.md', bytes: 53_248 },
 	{ path: 'docs/josh-commands-run.md', bytes: 77_824 },
 	{ path: 'docs/josh-commands-backlog.md', bytes: 61_440 },
-	{ path: 'docs/josh-commands.md', bytes: 53_248 },
+	{ path: 'docs/josh-commands.md', bytes: 57_344 },
 	{ path: 'docs/labels-and-run-states.md', bytes: 8192 },
 	{ path: 'prompts/coding-standards.md', bytes: 8192 },
 	{ path: 'prompts/collaboration-workflow.md', bytes: 8192 },

package/scripts/fresh-machine/fresh-machine-patterns.ts

@@ -27,13 +27,18 @@ const INIT_COMMANDS = [INSTALL_TARBALL, 'pnpm exec josh init', GATE]
 // `josh start` leaves the project on its setup branch, where the gate asks for the scoped checks
 // first; this is the line its refusal hands back.
 const SCOPED_CHECKS = 'pnpm josh lint:related && pnpm josh test:related'
-const START_COMMANDS = [
-	EXCLUDE_RELEASE_AGE,
-	INSTALL_PUBLISHED,
-	'pnpm exec josh start --yes --github',
-	SCOPED_CHECKS,
-	GATE,
-]
+const START = 'pnpm exec josh start --yes --github'
+
+// An agent names the profile rather than leaving it to detection, so every pattern passes its own.
+function start_commands(profile: string): Array<string> {
+	return [
+		EXCLUDE_RELEASE_AGE,
+		INSTALL_PUBLISHED,
+		`${START} --profile ${profile}`,
+		SCOPED_CHECKS,
+		GATE,
+	]
+}
 
 // `gh auth login` cannot run without a person, and it is what points git at gh for credentials; with
 // the token in the environment this is the same step.
@@ -49,6 +54,11 @@ const FIRST_COMMIT = [
 	'git add --all && git commit --message "Initial commit"',
 ]
 const CREATE_REPOSITORY = 'gh repo create "$RUN_NAME" --private --source . --push'
+// The labels a repository already had, recorded before `josh start` so the probe after it shows none
+// was removed or changed.
+const LABELS = 'gh label list --limit 100'
+// The setup pull request's CI, waited for and recorded; the pull request itself is never merged.
+const SETUP_CI = 'gh pr checks --watch --interval 60'
 
 // The two states #3712 was found in: a shell that reads no rc file, and a PATH with `node` on it and
 // no `pnpm`.
@@ -60,13 +70,29 @@ const PATH_PROBES = [
 	`mkdir -p ${NODE_ONLY} && ln -sf "$(command -v node)" ${NODE_ONLY}/node && ${BARE_SHELL} 'PATH="$HOME/node-only:$PATH" ./node_modules/.bin/josh gate'`,
 ]
 
+// What a `josh start` run is checked against before the PATH states: the profile it recorded, the
+// repository's visibility and branch, its labels, and the files the first commit on `main` holds. Where
+// `main` already had a commit, `josh start` opens a setup Issue and pull request instead of pushing to
+// it; the last four record those, the files the pull request carries and the `main` GitHub holds.
+const PROFILE = 'pnpm josh profile'
+const START_PROBES = [
+	PROFILE,
+	'gh repo view --json visibility,defaultBranchRef',
+	LABELS,
+	'git show --name-only --format= "$(git rev-list --max-parents=0 main)"',
+	'gh issue list --state all --json number,title,state,labels',
+	'gh pr list --state all --json number,title,state,headRefName,labels,closingIssuesReferences',
+	'gh pr diff --name-only',
+	'git log --oneline origin/main',
+]
+
 // What a `josh init` run is checked against after the gate: the profile it chose, the files it left
 // (a `./.git` line is a repository it should not have made), and a second run that changes nothing.
 const PROJECT_FILES =
 	'find . -name node_modules -prune -o -name .git -prune -o -type f -print | sort'
 const CHECKSUMS = `${PROJECT_FILES} | xargs sha256sum`
 const INIT_PROBES = [
-	'pnpm josh profile',
+	PROFILE,
 	'find . -name node_modules -prune -o -print | sort',
 	`${CHECKSUMS} > "$HOME/before-second-init.sha" && pnpm exec josh init && ${CHECKSUMS} | diff "$HOME/before-second-init.sha" -`,
 ]
@@ -90,31 +116,50 @@ function init_pattern(
 	})
 }
 
+// What a `josh start` pattern adds to the shared steps: the state before the install, the profile it
+// names, the commands that must pass after the gate, and the probes recorded before the PATH states.
+interface StartProject {
+	setup: ReadonlyArray<string>
+	profile: string
+	checks?: ReadonlyArray<string>
+	probes?: ReadonlyArray<string>
+}
+
 function start_pattern(
 	project: string,
 	files: Record<string, string>,
-	setup: ReadonlyArray<string>,
+	{ setup, profile, checks = [], probes = [] }: StartProject,
 ): Scenario {
 	return fresh_machine_spec.define({
 		name: `kit-test-${project}-start`,
 		requires_github: true,
 		package_source: 'published',
 		files,
-		commands: [SIGN_IN, ...setup, ...START_COMMANDS],
-		probes: PATH_PROBES,
+		commands: [SIGN_IN, ...setup, ...start_commands(profile), ...checks],
+		probes: [...START_PROBES, ...probes, ...PATH_PROBES],
 	})
 }
 
 const PATTERNS: ReadonlyArray<Scenario> = [
 	init_pattern('lua', LUA_FILES, [BARE_MANIFEST]),
 	// No Git: `josh start` creates the repository, the first commit and the GitHub repository.
-	start_pattern('lua', LUA_FILES, [MACHINE_IDENTITY, BARE_MANIFEST]),
+	start_pattern('lua', LUA_FILES, { setup: [MACHINE_IDENTITY, BARE_MANIFEST], profile: 'basic' }),
 	init_pattern('html', HTML_FILES, [BARE_MANIFEST]),
 	// Git with a first commit on `main`, no GitHub repository.
-	start_pattern('html', HTML_FILES, [...FIRST_COMMIT, BARE_MANIFEST]),
+	start_pattern('html', HTML_FILES, { setup: [...FIRST_COMMIT, BARE_MANIFEST], profile: 'basic' }),
 	init_pattern('svelte', {}, [CREATE_SVELTEKIT, SV_VERSION, SVELTEKIT_CHECKS], [SVELTEKIT_CHECKS]),
-	// A GitHub repository with `main` already pushed.
-	start_pattern('svelte', {}, [CREATE_SVELTEKIT, ...FIRST_COMMIT, CREATE_REPOSITORY]),
+	// A GitHub repository with `main` already pushed, its labels recorded before the install; the app
+	// still builds and type-checks on the setup branch, and the setup pull request's CI is waited for.
+	start_pattern(
+		'svelte',
+		{},
+		{
+			setup: [CREATE_SVELTEKIT, SV_VERSION, ...FIRST_COMMIT, CREATE_REPOSITORY, LABELS],
+			profile: 'full',
+			checks: [SVELTEKIT_CHECKS],
+			probes: [SETUP_CI],
+		},
+	),
 ]
 
 function names(): Array<string> {

package/scripts/gate/project-checks.ts

@@ -2,6 +2,7 @@ import { existsSync, globSync, readFileSync } from 'node:fs'
 import path from 'node:path'
 import { find_local_bin_upwards } from '#scripts/build/local-bin'
 import { doctor_consumer } from '#scripts/doctor/doctor-consumer'
+import { own_formatter } from '#scripts/init/own-formatter'
 import { project_profile } from '#scripts/init/project-profile'
 import { ancestor_directories } from '#scripts/lib/ancestor-directories'
 import { json_value } from '#scripts/lib/json-value'
@@ -150,10 +151,12 @@ function type_check_skip_reason(directory: string): string | undefined {
 }
 
 // Shared by `josh lint`, `josh lint:related` and `josh format`, so a basic project without Web
-// files — a Python or Rust project, which `josh init` gives no Prettier — is skipped for the same
-// reason by all three.
+// files — a Python or Rust project, which `josh init` gives no Prettier — or with a formatter of its
+// own is skipped for the same reason by all three.
 function prettier_skip_reason(directory: string): string | undefined {
 	if (!is_basic(directory)) return undefined
+	const formatter = own_formatter.find_config(project_root(directory))
+	if (formatter !== undefined) return `${formatter} configures the project's own formatter`
 	if (!has_files(directory, WEB_FILES)) return 'no HTML, CSS or JavaScript files were found'
 
 	return missing_tool_reason(directory, 'prettier', 'prettier')

package/scripts/gh/git-gh-issue-rest.ts

@@ -71,6 +71,7 @@ const REST_FIELD_NAMES = new Map<string, string>([
 	['url', 'html_url'],
 	['createdAt', 'created_at'],
 	['closedAt', 'closed_at'],
+	['updatedAt', 'updated_at'],
 ])
 
 const NOT_AN_ISSUE_MESSAGE = 'gh api answered something other than an issue object'

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

@@ -150,6 +150,14 @@ async function issue_list_by_label_in_repo(
 	return await issue_list({ json_fields: SUMMARY_FIELDS, limit, label, repo })
 }
 
+// Every open issue with what `josh auto-ok:judge` judges it by — its labels and body — and `updatedAt`,
+// so the backlog driver's resident check reads an issue's comments again only once it has moved.
+const JUDGEMENT_FIELDS = 'number,title,body,labels,updatedAt'
+
+async function issue_list_open_for_judgement(limit: number): Promise<IssueListOutcome> {
+	return await issue_list({ json_fields: JUDGEMENT_FIELDS, limit })
+}
+
 const git_gh_issue = {
 	...git_gh_issue_read,
 	...git_gh_issue_write,
@@ -159,6 +167,7 @@ const git_gh_issue = {
 	issue_list_by_label_summary,
 	issue_search_body,
 	issue_list_open_bodies,
+	issue_list_open_for_judgement,
 	issue_list_recently_closed,
 }
 

package/scripts/init/init-actions.ts

@@ -106,7 +106,7 @@ function build_basic_settings_action(): FileAction {
 }
 
 function build_basic_vscode_actions(shape: ProjectShape): ReadonlyArray<FileAction> {
-	const recommendations = shape.has_web
+	const recommendations = shape.should_use_prettier
 		? [...BASIC_EXTENSIONS, PRETTIER_EXTENSION]
 		: BASIC_EXTENSIONS
 	const actions: Array<FileAction> = [
@@ -117,7 +117,7 @@ function build_basic_vscode_actions(shape: ProjectShape): ReadonlyArray<FileActi
 		),
 	]
 
-	if (shape.has_web) actions.push(build_basic_settings_action())
+	if (shape.should_use_prettier) actions.push(build_basic_settings_action())
 
 	return actions
 }
@@ -210,7 +210,7 @@ function build_basic_actions(shape: ProjectShape): ReadonlyArray<FileAction> {
 	if (shape.has_git) actions.push(build_gitignore_action())
 	if (shape.has_typescript) actions.push(build_basic_tsconfig_action())
 
-	if (shape.has_web) {
+	if (shape.should_use_prettier) {
 		actions.push({
 			dest: BASIC_PRETTIER_CONFIG,
 			create: () =>

package/scripts/init/init-ai-copy.ts

@@ -348,7 +348,7 @@ function should_copy_github_file(filename: string, shape?: ProjectShape): boolea
 function should_copy_basic_file(filename: string, shape?: ProjectShape): boolean {
 	if (filename !== PRETTIER_IGNORE || shape?.profile !== 'basic') return true
 
-	return shape.has_web
+	return shape.should_use_prettier
 }
 
 function should_copy_ai_file(filename: string, shape?: ProjectShape): boolean {

package/scripts/init/init-basic.ts

@@ -45,7 +45,7 @@ function merge_basic_manifest(
 	const with_kit = init_logic.merge_development_dependencies(with_script, {
 		[KIT_PACKAGE_NAME]: versions.kit,
 	})
-	const with_prettier = shape.has_web
+	const with_prettier = shape.should_use_prettier
 		? init_logic.merge_development_dependencies(with_kit, { prettier: versions.prettier })
 		: with_kit
 

package/scripts/init/init-bootstrap.ts

@@ -82,13 +82,17 @@ function ensure_project_manifest(project_root: string): void {
 	if (!existsSync(manifest_path)) writeFileSync(manifest_path, init_basic.initial_manifest())
 }
 
+function is_handed_off(): boolean {
+	return process.env[HANDOFF_ENV] !== undefined
+}
+
 // Returns the failure to report, or undefined once the project-installed kit finished the setup.
 function hand_off(
 	package_directory: string,
 	project_root: string,
 	args: ReadonlyArray<string>,
 ): string | undefined {
-	if (process.env[HANDOFF_ENV] !== undefined) return REPEATED_HANDOFF
+	if (is_handed_off()) return REPEATED_HANDOFF
 	console.info('\n🚀 Installing @joshuafolkken/kit into the project, then running its josh init')
 	const template = readFileSync(path.join(package_directory, KIT_BUILDS_TEMPLATE), 'utf8')
 	const install = kit_install_step(has_kit_dependency(project_root), template)
@@ -100,5 +104,5 @@ function hand_off(
 	return undefined
 }
 
-const init_bootstrap = { is_project_kit, kit_build_flags, hand_off }
+const init_bootstrap = { HANDOFF_ENV, is_project_kit, kit_build_flags, hand_off, is_handed_off }
 export { init_bootstrap }

package/scripts/init/init-dry-run-report.ts

@@ -0,0 +1,150 @@
+import { json_value } from '#scripts/lib/json-value'
+
+type ChangeKind = 'create' | 'merge' | 'overwrite' | 'delete'
+
+interface FileChange {
+	path: string
+	before: string | undefined
+	after: string | undefined
+}
+
+type JsonRecord = Record<string, unknown>
+
+const PACKAGE_JSON = 'package.json'
+const JSON_EXTENSION = '.json'
+const KIND_WIDTH = 'overwrite'.length
+const NO_CHANGES = '  (no file changes)'
+
+// Every path whose content differs between the two snapshots, sorted, so a run reads the same twice.
+function changed_files(
+	before: ReadonlyMap<string, string>,
+	after: ReadonlyMap<string, string>,
+): Array<FileChange> {
+	const paths = [...new Set([...before.keys(), ...after.keys()])].toSorted((left, right) =>
+		left.localeCompare(right),
+	)
+
+	return paths
+		.filter((file) => before.get(file) !== after.get(file))
+		.map((file) => ({ path: file, before: before.get(file), after: after.get(file) }))
+}
+
+// A changed file is a merge when every line it had survives — the project's own content is kept —
+// and an overwrite when any of its lines is replaced or removed.
+function keeps_every_line(before: string, after: string): boolean {
+	const remaining = new Set(after.split('\n'))
+
+	return before.split('\n').every((line) => remaining.has(line))
+}
+
+function is_kept_array(before: ReadonlyArray<unknown>, after: unknown): boolean {
+	if (!Array.isArray(after)) return false
+	const remaining = new Set(after.map((value) => JSON.stringify(value)))
+
+	return before.every((value) => remaining.has(JSON.stringify(value)))
+}
+
+// A JSON file is rewritten whole when kit adds to it — `package.json` written out again, a list grown — so
+// it is compared by value: a merge when every value it had is still there, wherever the lines moved.
+function is_kept(before: unknown, after: unknown): boolean {
+	if (Array.isArray(before)) return is_kept_array(before, after)
+	if (!json_value.is_record(before) || !json_value.is_record(after)) return before === after
+
+	return Object.keys(before).every((key) => is_kept(before[key], after[key]))
+}
+
+// Undefined when either side is not plain JSON (a `tsconfig.json` with comments), which falls back
+// to the line test.
+function keeps_every_value(before: string, after: string): boolean | undefined {
+	const old_value = json_value.parse_or_undefined(before)
+	const new_value = json_value.parse_or_undefined(after)
+	if (old_value === undefined || new_value === undefined) return undefined
+
+	return is_kept(old_value, new_value)
+}
+
+function keeps_content(file: string, before: string, after: string): boolean {
+	const is_kept_by_value = file.endsWith(JSON_EXTENSION)
+		? keeps_every_value(before, after)
+		: undefined
+
+	return is_kept_by_value ?? keeps_every_line(before, after)
+}
+
+function change_kind(change: FileChange): ChangeKind {
+	if (change.before === undefined) return 'create'
+	if (change.after === undefined) return 'delete'
+
+	return keeps_content(change.path, change.before, change.after) ? 'merge' : 'overwrite'
+}
+
+function parse_record(content: string | undefined): JsonRecord {
+	const parsed = content === undefined ? undefined : json_value.parse_or_undefined(content)
+
+	return json_value.is_record(parsed) ? parsed : {}
+}
+
+function changed_keys(before: JsonRecord, after: JsonRecord): Array<string> {
+	const keys = [...new Set([...Object.keys(before), ...Object.keys(after)])]
+
+	return keys.filter((key) => JSON.stringify(before[key]) !== JSON.stringify(after[key]))
+}
+
+function entry_line(name: string, before: unknown, after: unknown): string {
+	if (before === undefined) return `+ ${name} ${JSON.stringify(after)}`
+	if (after === undefined) return `- ${name}`
+
+	return `~ ${name} ${JSON.stringify(before)} → ${JSON.stringify(after)}`
+}
+
+// A missing field reads as an empty object, so a block added or removed whole is listed too.
+function as_entries(value: unknown): JsonRecord | undefined {
+	if (value === undefined) return {}
+
+	return json_value.is_record(value) ? value : undefined
+}
+
+// A field that is an object (`scripts`, `devDependencies`) is listed entry by entry, so the plan
+// names each script and dependency rather than the whole block.
+function field_lines(key: string, before: unknown, after: unknown): Array<string> {
+	const old_entries = as_entries(before)
+	const new_entries = as_entries(after)
+
+	if (old_entries === undefined || new_entries === undefined) {
+		return [entry_line(key, before, after)]
+	}
+
+	return changed_keys(old_entries, new_entries).map((name) =>
+		entry_line(`${key}.${name}`, old_entries[name], new_entries[name]),
+	)
+}
+
+function package_json_lines(change: FileChange): Array<string> {
+	const before = parse_record(change.before)
+	const after = parse_record(change.after)
+
+	return changed_keys(before, after).flatMap((key) => field_lines(key, before[key], after[key]))
+}
+
+function change_lines(change: FileChange): Array<string> {
+	const head = `  ${change_kind(change).padEnd(KIND_WIDTH)} ${change.path}`
+	if (change.path !== PACKAGE_JSON || change.after === undefined) return [head]
+
+	return [head, ...package_json_lines(change).map((line) => `      ${line}`)]
+}
+
+function format_report(
+	title: string,
+	changes: ReadonlyArray<FileChange>,
+	dependency_lines: ReadonlyArray<string>,
+): string {
+	const files =
+		changes.length === 0 ? [NO_CHANGES] : changes.flatMap((change) => change_lines(change))
+	const dependencies = dependency_lines.map((line) => `  ${line}`)
+
+	return [title, '', 'Files:', ...files, '', 'Dependencies:', ...dependencies].join('\n')
+}
+
+const init_dry_run_report = { changed_files, change_kind, package_json_lines, format_report }
+export { init_dry_run_report }
+export type { ChangeKind, FileChange }