@joshuafolkken/kit 1.872.0

package/scripts/hooks/format-edited-file.ts

@@ -0,0 +1,510 @@
+#!/usr/bin/env tsx
+import { existsSync } from 'node:fs'
+import path from 'node:path'
+import { text } from 'node:stream/consumers'
+import { fileURLToPath } from 'node:url'
+import { resolve_local_bin, resolve_package_bin } from '#scripts/build/local-bin'
+import { ESLINT_EDIT_CACHE_FLAGS } from '#scripts/josh/josh-command-types'
+import { time_density_hook } from '#scripts/time-runtime/time-density-hook'
+import { execa } from 'execa'
+import { z } from 'zod'
+import { edited_cspell } from './edited-cspell'
+import { rewrite_notice } from './format-rewrite-notice'
+
+// Claude Code hands a `PostToolUse` hook the tool call as JSON on stdin; for `Edit` and `Write` the
+// edited path is `tool_input.file_path`. Everything else in the payload is ignored, and a payload
+// that does not carry a path is a no-op rather than an error — this hook runs after the edit has
+// already been applied and must never turn a successful edit into a failure.
+const hook_payload_schema = z.object({
+	tool_input: z.object({ file_path: z.string().min(1) }).optional(),
+})
+
+// What prettier is asked to write. Kept explicit rather than deferring to `--ignore-unknown` alone
+// so the hook's cost is bounded by a list that can be read, and so a path this project has no
+// opinion about never spawns a process at all.
+const PRETTIER_EXTENSIONS = new Set([
+	'.ts',
+	'.tsx',
+	'.js',
+	'.jsx',
+	'.mjs',
+	'.cjs',
+	'.svelte',
+	'.json',
+	'.jsonc',
+	'.md',
+	'.yml',
+	'.yaml',
+	'.css',
+	'.html',
+])
+
+// eslint only runs where the config has rules to apply. A `--fix` pass on a `.md` or `.yml` file
+// costs a process start to do nothing.
+const ESLINT_EXTENSIONS = new Set(['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.svelte'])
+
+// Never this project's to format, however the edit reached them. Split in two because depth means
+// different things: an installed package or a git internal is off-limits wherever it sits, while
+// `dist` and `build` name build output only at the top level — `src/routes/build/+page.ts` is
+// ordinary source, and excluding it by name would switch the hook off for a real part of the tree.
+const EXCLUDED_ANYWHERE = new Set(['node_modules', '.git'])
+const EXCLUDED_AT_ROOT = new Set(['dist', 'build'])
+const PARENT_SEGMENT = '..'
+
+// The shims under `node_modules/.bin` are spawned directly rather than through `pnpm exec`. This
+// runs on every edit, and each `pnpm exec` is another process start on a chain that already holds
+// `pnpm josh` and tsx — the two saved are the ones this file controls.
+const PNPM = 'pnpm'
+const PRETTIER_BIN = 'prettier'
+const PRETTIER_ARGUMENTS: ReadonlyArray<string> = ['--write', '--ignore-unknown']
+// `--no-error-on-unmatched-pattern` covers a file the eslint config does not cover: the hook has
+// nothing to say about it, and a non-zero exit here would be reported as a failed hook.
+//
+// The cache flags are not here to make the hook faster — they are here to stop it destroying the
+// gate's cache (joshuafolkken/kit#1332). ESLint started *without* `--cache` deletes the file at
+// `--cache-location`, so this hook wiped `.eslintcache` on every edit and the gate's lint ran cold
+// every time. Passing them points that deletion, and the hook's own reads and writes, at a location
+// of its own — its own rather than the gate's because the two run concurrently, and each eslint run
+// rewrites its cache file whole from the copy it loaded at start-up. `ESLINT_EDIT_CACHE_FLAGS` is
+// single-sourced beside the gate's so the two locations cannot drift into being the same file.
+const ESLINT_BIN = 'eslint'
+const ESLINT_ARGUMENTS: ReadonlyArray<string> = [
+	'--fix',
+	'--no-error-on-unmatched-pattern',
+	...ESLINT_EDIT_CACHE_FLAGS,
+]
+// eslint is what this hook spends its time on, and almost none of it is the file: measured on this
+// repository, one `eslint --fix` on a single TypeScript file takes 1.70s of a 2.50s hook, and a
+// second lint inside the same process takes 0.13s. The 1.6s difference is the flat config, its
+// plugins and the type-aware program, rebuilt from nothing on every edit. `eslint_d` keeps one warm
+// eslint — the *project's* own eslint, held to that by `ESLINT_D_MISS=fail` below rather than by
+// hope — behind a socket and forwards the same arguments to it, which is why the fixed output is
+// identical rather than merely similar. The config entry file is re-read per request; the modules it
+// imports are not, which `plan_daemon_restart` below is the answer to. The daemon exits after 15
+// minutes of inactivity (joshuafolkken/kit#1259).
+const ESLINT_DAEMON = 'eslint_d'
+const DAEMON_RESTART = 'restart'
+// The two shapes a flat config is built from here and in every consumer of this kit: the root
+// `eslint.config.*` entry, and the rule modules under `eslint/` that it imports.
+const ESLINT_CONFIG_DIR = 'eslint'
+const ESLINT_CONFIG_ENTRY = /^eslint\.config\.[cm]?[jt]s$/u
+// A formatter that hangs would hold the edit's turn open, so each spawn is bounded. The bound has
+// to be read against the *worst-case run* rather than one spawn: an edit to a config input plans
+// eslint, prettier and `eslint_d restart`, and the first and last each have a second route behind
+// the daemon — five spawns. The hook entry in `.claude/settings.json` declares 90 seconds, so the
+// per-spawn bound must leave five of them under it, or the harness kill lands first and lands at a
+// moment this file did not choose — possibly inside `prettier --write`, which rewrites in place and
+// can leave the file truncated. 15s × 5 = 75s. It is still two orders of magnitude beyond the 0.84s
+// a warm run takes, so reaching it means something is already wrong.
+const PROCESS_TIMEOUT_MS = 15_000
+
+// The problems eslint could not auto-fix are handed to the model verbatim from eslint's own stdout —
+// its default formatter already prints the file, the `line:col`, and the rule name the issue asks
+// for (joshuafolkken/kit#2275). A header names what the block is, since additionalContext arrives
+// with no framing of its own.
+const DIAGNOSTIC_HEADER =
+	'The edit hook could not auto-fix these lint problems; address them now rather than at the gate:'
+// additionalContext rides back on an edit, so an unbounded lint dump would balloon the run's
+// context. Past this many characters the block is cut and marked. One place, so the bound is read
+// rather than guessed.
+const MAX_DIAGNOSTIC_CHARS = 4000
+const DIAGNOSTIC_TRUNCATION_NOTICE = '\n…(diagnostics truncated)'
+// The density line first, then the lint problems, with a blank line between them when both are
+// present.
+const SECTION_SEPARATOR = '\n\n'
+
+// Where this file sits inside the kit package. `eslint_d` is kit's dependency rather than the
+// consumer's, and pnpm writes a `node_modules/.bin` shim only for a project's *direct* dependencies,
+// so a consumer's project root cannot see it and this directory can.
+const MODULE_DIRECTORY = path.dirname(fileURLToPath(import.meta.url))
+
+interface FormatCommand {
+	bin: string
+	command_arguments: ReadonlyArray<string>
+}
+
+// The three ways this hook can reach a formatter, fastest first — a warm daemon, the project's own
+// shim, then `pnpm exec`. Each later route exists because the one before it can be absent, so a
+// project without the daemon behaves exactly as it did before it was introduced. Both fields are
+// declared rather than optional: `exactOptionalPropertyTypes` makes an absent key and an explicit
+// `undefined` different types, and every caller here computes the value rather than omitting it.
+interface BinRoutes {
+	daemon_cli: string | undefined
+	shim: string | undefined
+}
+
+// What one spawn answered. The exit code alone cannot say whether a formatter ran, because
+// `eslint --fix` exits non-zero whenever something it could not fix remains — its ordinary outcome
+// on a half-written file. The stdout the spawn captured is what separates the two: eslint prints the
+// problems it is exiting non-zero about, while a daemon that could not start prints its reason to
+// stderr and leaves stdout empty. It is kept whole rather than reduced to a boolean because the
+// problems eslint could not fix are reported to the model from it (joshuafolkken/kit#2275).
+interface CommandOutcome {
+	exit_code: number
+	stdout: string
+}
+
+type CommandRunner = (command: FormatCommand, project_root: string) => Promise<CommandOutcome>
+
+function parse_edited_path(raw_payload: string): string | undefined {
+	try {
+		const result = hook_payload_schema.safeParse(JSON.parse(raw_payload))
+
+		return result.success ? result.data.tool_input?.file_path : undefined
+	} catch {
+		return undefined
+	}
+}
+
+// Read against the path relative to the project root, never the absolute one: a checkout that lives
+// under a directory called `build` or `dist` would otherwise have the hook silently switched off for
+// every file in it.
+function is_excluded(relative_path: string): boolean {
+	const segments = relative_path.split(path.sep)
+
+	return (
+		segments.some((segment) => EXCLUDED_ANYWHERE.has(segment)) ||
+		EXCLUDED_AT_ROOT.has(segments[0] ?? '')
+	)
+}
+
+// Claude Code runs a hook from the project directory, and this project's prettier and eslint config
+// is the only config the hook has. An edit can still land outside that tree — a session may carry
+// additional working directories, and paths in another checkout or a home-directory config file are
+// governed by their own rules — so a path that is not under the root is left alone rather than
+// rewritten to kit's taste.
+// Returns the path relative to the root, or nothing when the file is not under it. The first
+// segment is compared to `..` rather than tested as a prefix: `..config.ts` is a file in the root,
+// not a step above it.
+function relative_to_root(project_root: string, file_path: string): string | undefined {
+	const relative = path.relative(path.resolve(project_root), path.resolve(file_path))
+	const is_inside_root =
+		relative !== '' && relative.split(path.sep)[0] !== PARENT_SEGMENT && !path.isAbsolute(relative)
+
+	return is_inside_root ? relative : undefined
+}
+
+// One question, asked before any list is built: is this a file this project formats at all?
+function is_formattable(file_path: string, project_root: string): boolean {
+	const relative = relative_to_root(project_root, file_path)
+
+	return relative !== undefined && !is_excluded(relative) && existsSync(file_path)
+}
+
+// Returns the commands to run, in order. eslint goes first and prettier last so prettier has the
+// final word: an `--fix` that removes a now-unused disable directive leaves the whitespace behind
+// it, and running in the other order shipped exactly that — a file the hook had just "formatted"
+// that `prettier --check` then rejected. An empty list means the hook has nothing to do: the file is
+// outside the project, gone by the time the hook ran, or of a kind nothing formats.
+function plan_commands(file_path: string, project_root: string): ReadonlyArray<FormatCommand> {
+	if (!is_formattable(file_path, project_root)) return []
+
+	const extension = path.extname(file_path).toLowerCase()
+	const commands: Array<FormatCommand> = []
+
+	if (ESLINT_EXTENSIONS.has(extension)) {
+		commands.push({ bin: ESLINT_BIN, command_arguments: [...ESLINT_ARGUMENTS, file_path] })
+	}
+
+	if (PRETTIER_EXTENSIONS.has(extension)) {
+		commands.push({ bin: PRETTIER_BIN, command_arguments: [...PRETTIER_ARGUMENTS, file_path] })
+	}
+
+	return commands
+}
+
+// The daemon when it is installed, the local shim when it is there, `pnpm exec` when neither is. A
+// workspace sub-package keeps its binaries somewhere other than the root's `node_modules/.bin`, and
+// with output ignored a missing shim would otherwise make the hook a permanent silent no-op rather
+// than a slower one. Kept pure and separate from the disk lookups so the choice itself is what the
+// unit tests read.
+function select_invocation(command: FormatCommand, routes: BinRoutes): FormatCommand {
+	if (routes.daemon_cli !== undefined) {
+		return {
+			bin: process.execPath,
+			command_arguments: [routes.daemon_cli, ...command.command_arguments],
+		}
+	}
+
+	if (routes.shim !== undefined) {
+		return { bin: routes.shim, command_arguments: command.command_arguments }
+	}
+
+	return { bin: PNPM, command_arguments: ['exec', command.bin, ...command.command_arguments] }
+}
+
+// Only eslint has a daemon here. prettier costs 0.21s against eslint's 1.70s, so a second warm
+// process would buy little and double what can go stale. `eslint_d` itself is in the set because the
+// restart below is addressed to the daemon rather than to a formatter.
+const DAEMON_BINS: ReadonlySet<string> = new Set([ESLINT_BIN, ESLINT_DAEMON])
+
+function resolve_daemon_cli(bin: string, project_root: string): string | undefined {
+	if (!DAEMON_BINS.has(bin)) return undefined
+
+	return (
+		resolve_package_bin(MODULE_DIRECTORY, ESLINT_DAEMON, ESLINT_DAEMON) ??
+		resolve_package_bin(project_root, ESLINT_DAEMON, ESLINT_DAEMON)
+	)
+}
+
+// Only the config *entry file* is re-read per request: ESLint cache-busts `eslint.config.js` by
+// appending its mtime to the import URL, and the modules that file imports carry no such query, so a
+// long-lived daemon keeps the rule modules it loaded first. Edit `eslint/rules/naming-convention.js`
+// and then any source file, and it would be auto-fixed against the pre-edit rules for as long as the
+// daemon lives — an author testing a rule change would read that as the rule being broken. Restarting
+// after an edit to a config input is what makes the whole config current, not just its first file.
+function is_eslint_config_input(relative_path: string): boolean {
+	return (
+		relative_path.split(path.sep)[0] === ESLINT_CONFIG_DIR ||
+		ESLINT_CONFIG_ENTRY.test(relative_path)
+	)
+}
+
+function plan_daemon_restart(
+	file_path: string,
+	project_root: string,
+): ReadonlyArray<FormatCommand> {
+	const relative = relative_to_root(project_root, file_path)
+
+	if (relative === undefined || !is_eslint_config_input(relative)) return []
+	if (resolve_daemon_cli(ESLINT_DAEMON, project_root) === undefined) return []
+
+	return [{ bin: ESLINT_DAEMON, command_arguments: [DAEMON_RESTART] }]
+}
+
+// The routes to try, fastest first. The second entry is the one that has always been here, and it
+// is what a project with no daemon runs directly — resolving the daemon is not the same as it
+// starting, so the slower route stays reachable rather than being replaced.
+function resolve_invocations(
+	command: FormatCommand,
+	project_root: string,
+): ReadonlyArray<FormatCommand> {
+	const shim = resolve_local_bin(project_root, command.bin)
+	const routes: BinRoutes = {
+		daemon_cli: resolve_daemon_cli(command.bin, project_root),
+		shim: existsSync(shim) ? shim : undefined,
+	}
+	const without_daemon = select_invocation(command, { ...routes, daemon_cli: undefined })
+
+	if (routes.daemon_cli === undefined) return [without_daemon]
+
+	return [select_invocation(command, routes), without_daemon]
+}
+
+// A daemon that resolved on disk can still fail to start — a blocked loopback bind, a watch-limit
+// refusal, a read-only store it cannot write its own config into — and it says so on stderr while
+// exiting non-zero with nothing on stdout. `ESLINT_D_MISS=fail` below lands in the same shape.
+// Without this the hook would silently stop fixing anything with eslint wherever the daemon cannot
+// run, which is the "permanent silent no-op rather than a slower one" the shim fallback exists to
+// prevent, reintroduced one level up.
+function is_start_failure(outcome: CommandOutcome): boolean {
+	return outcome.exit_code !== 0 && outcome.stdout.length === 0
+}
+
+// `cwd` is not decoration: the daemon runs each request under the cwd of the process that forwarded
+// it, so it is what decides which eslint installation and which flat config answer.
+// `ESLINT_D_MISS=fail` refuses the bundled eslint the daemon would otherwise fall back to when the
+// project's own is not resolvable — the hook must format with the project's eslint or not at all,
+// and a refusal here is a start failure, which the caller retries on the slower route.
+async function spawn_invocation(
+	invocation: FormatCommand,
+	project_root: string,
+): Promise<CommandOutcome> {
+	const result = await execa(invocation.bin, [...invocation.command_arguments], {
+		reject: false,
+		cwd: project_root,
+		env: { ESLINT_D_MISS: 'fail' },
+		stdout: 'pipe',
+		stderr: 'ignore',
+		timeout: PROCESS_TIMEOUT_MS,
+	})
+
+	return { exit_code: result.exitCode ?? 1, stdout: result.stdout }
+}
+
+// One planned command, tried down its routes. A route is retried only when the one before it failed
+// to start — never when the formatter itself reported problems, which is its normal way of exiting.
+async function run_command(command: FormatCommand, project_root: string): Promise<CommandOutcome> {
+	let outcome: CommandOutcome = { exit_code: 0, stdout: '' }
+
+	for (const invocation of resolve_invocations(command, project_root)) {
+		outcome = await spawn_invocation(invocation, project_root)
+		if (!is_start_failure(outcome)) return outcome
+	}
+
+	return outcome
+}
+
+// eslint's stdout is diagnostics only when eslint is the command and it exited non-zero with
+// something to say. A start failure (non-zero, empty) has already been retried and carries no
+// problems, and prettier's stdout is the list of files it wrote rather than anything to act on.
+function eslint_unfixed(command: FormatCommand, outcome: CommandOutcome): string | undefined {
+	if (command.bin !== ESLINT_BIN) return undefined
+	if (outcome.exit_code === 0 || outcome.stdout.length === 0) return undefined
+
+	return outcome.stdout
+}
+
+// The block the model reads: the header, then eslint's own output, cut to the bound so a large lint
+// dump cannot balloon the run's context. `undefined` when eslint had nothing left unfixed, so the
+// ordinary edit adds nothing to additionalContext.
+function format_diagnostics(unfixed: string | undefined): string | undefined {
+	if (unfixed === undefined) return undefined
+
+	const is_over = unfixed.length > MAX_DIAGNOSTIC_CHARS
+	const body = is_over
+		? `${unfixed.slice(0, MAX_DIAGNOSTIC_CHARS)}${DIAGNOSTIC_TRUNCATION_NOTICE}`
+		: unfixed
+
+	return `${DIAGNOSTIC_HEADER}\n${body}`
+}
+
+// The fixes eslint could apply are applied silently, as before; what it could not fix is returned so
+// the model sees it on this edit rather than at the gate (joshuafolkken/kit#2275). A `PostToolUse`
+// hook still reports no failure — the edit already landed, and returning the problems is not the same
+// as failing the write.
+// Runs the planned commands in order, returning the last unfixed eslint output. Empty until eslint
+// reports something it could not fix; `eslint_unfixed` never returns an empty string, so '' stays the
+// "nothing to report" sentinel.
+async function collect_unfixed(
+	plan: ReadonlyArray<FormatCommand>,
+	runner: CommandRunner,
+	project_root: string,
+): Promise<string> {
+	let unfixed = ''
+
+	for (const command of plan) {
+		try {
+			unfixed = eslint_unfixed(command, await runner(command, project_root)) ?? unfixed
+		} catch {
+			// One formatter failing to start is not a reason to skip the next: prettier runs last, and
+			// it is the one whose output the project's own lint step checks.
+			continue
+		}
+	}
+
+	return unfixed
+}
+
+async function format_edited_file(
+	raw_payload: string,
+	runner: CommandRunner,
+	project_root: string,
+): Promise<string | undefined> {
+	const file_path = parse_edited_path(raw_payload)
+
+	if (file_path === undefined) return undefined
+
+	const plan = [
+		...plan_commands(file_path, project_root),
+		...plan_daemon_restart(file_path, project_root),
+	]
+	const unfixed = await collect_unfixed(plan, runner, project_root)
+
+	return format_diagnostics(unfixed === '' ? undefined : unfixed)
+}
+
+// Provider adapters use the same live runner as the direct Claude hook without exporting that
+// implementation detail or recreating its fallback sequence.
+async function format_edited_payload(
+	raw_payload: string,
+	project_root: string,
+): Promise<string | undefined> {
+	return await format_edited_file(raw_payload, run_command, project_root)
+}
+
+// The one hook event this file is wired to, and the value the envelope below has to name.
+const HOOK_EVENT_NAME = 'PostToolUse'
+
+// The live round-trip density line, riding this hook rather than one of its own
+// (joshuafolkken/kit#1329) — a `PostToolUse` matcher covering every tool would add a process start to
+// all ~250 calls of a run.
+//
+// **A `PostToolUse` hook's plain stdout never reaches the model**; only `additionalContext` inside
+// the documented envelope does, which is why the line cannot simply be printed. `undefined` when
+// there is nothing to say, so the ordinary edit writes nothing at all to stdout and the payload the
+// harness parses stays empty.
+// Both the density line and eslint's unfixed problems reach the model the same way — as
+// additionalContext on this one hook — and a `PostToolUse` hook's stdout carries a single envelope,
+// so the two are joined into one rather than written twice: a second JSON object on stdout would
+// leave the harness unable to parse either. No `permissionDecision` is ever set, so returning the
+// problems does not turn the edit into a failure.
+function build_envelope(additional_context: string): string {
+	return JSON.stringify({
+		hookSpecificOutput: { hookEventName: HOOK_EVENT_NAME, additionalContext: additional_context },
+	})
+}
+
+function density_envelope(raw_payload: string): string | undefined {
+	const notice = time_density_hook.density_notice(raw_payload)
+
+	return notice === undefined ? undefined : build_envelope(notice)
+}
+
+// The density line and the lint problems, joined when both are present. `undefined` when there is
+// nothing to say, so the ordinary edit writes nothing at all to stdout.
+function compose_context(
+	notice: string | undefined,
+	diagnostics: string | undefined,
+): string | undefined {
+	const sections = [notice, diagnostics].filter(
+		(section): section is string => section !== undefined,
+	)
+
+	return sections.length === 0 ? undefined : sections.join(SECTION_SEPARATOR)
+}
+
+// Run from a terminal there is no payload coming, and waiting for one looks like a hang.
+function report_no_payload(): void {
+	process.stderr.write(
+		'format:edited reads a Claude Code PostToolUse payload on stdin; it is not run by hand.\n',
+	)
+}
+
+// The lint problems come from eslint and the unknown words from cspell, so both are known only once
+// their processes have run; the density line is joined to them into the single envelope the harness
+// can parse, rather than written first on its own. The rewrite notice is read from the file itself —
+// its content before the formatters ran against its content after — so it too is known only once they
+// have (joshuafolkken/kit#2314). The rewrite, lint and spell blocks are composed together first, then
+// joined to the density line — one envelope, since a `PostToolUse` hook's stdout carries only one
+// (joshuafolkken/kit#2296). A hook killed at its 15s timeout is the one case this loses the density
+// line to — a run already gone pathologically wrong, per PROCESS_TIMEOUT_MS.
+async function run_hook(payload: string): Promise<void> {
+	const notice = time_density_hook.density_notice(payload)
+	const file_path = parse_edited_path(payload)
+	const before = rewrite_notice.read_text(file_path)
+	const lint = await format_edited_payload(payload, process.cwd())
+	const rewrite = rewrite_notice.build(before, rewrite_notice.read_text(file_path))
+	const spelling = await edited_cspell.spelling_diagnostics(file_path, process.cwd())
+	const parts = compose_context(rewrite, compose_context(lint, spelling))
+	const context = compose_context(notice, parts)
+
+	if (context !== undefined) process.stdout.write(`${build_envelope(context)}\n`)
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+	if (process.stdin.isTTY) {
+		report_no_payload()
+	} else {
+		await run_hook(await text(process.stdin))
+	}
+}
+
+export {
+	build_envelope,
+	compose_context,
+	density_envelope,
+	format_edited_file,
+	format_edited_payload,
+	is_start_failure,
+	parse_edited_path,
+	plan_commands,
+	plan_daemon_restart,
+	relative_to_root,
+	resolve_invocations,
+	select_invocation,
+	ESLINT_DAEMON,
+	MAX_DIAGNOSTIC_CHARS,
+	PROCESS_TIMEOUT_MS,
+}
+export type { CommandRunner, FormatCommand }

package/scripts/hooks/format-rewrite-notice.ts

@@ -0,0 +1,99 @@
+import { readFileSync } from 'node:fs'
+
+// The rewrite half of the edit hook (joshuafolkken/kit#2314). The format hook runs prettier and
+// `eslint --fix` in place after every edit, so a file the model just wrote can be rewritten out from
+// under the image the model holds — and the next `Edit` against that stale image misses, then pays for
+// a full re-read that rides every later request. joshuafolkken/kit#2275 built the `additionalContext`
+// path this rides and joshuafolkken/kit#2296 put cspell on it; this returns the fact that the file
+// changed and the region that changed, so the model reissues against current text without re-reading
+// the whole file. Nothing is added when formatting left the file untouched.
+
+// additionalContext rides back on the edit, so the changed region is cut to this bound rather than
+// let a large reformat balloon the run's context — the notice is a cheaper hint than the full re-read
+// it replaces, and stays cheaper only while it is bounded.
+const MAX_REWRITE_CHARS = 1200
+const REWRITE_TRUNCATION_NOTICE = '\n…(rewrite preview truncated)'
+// The header names what the block is, since additionalContext arrives with no framing of its own, and
+// says the one thing the model has to act on: its copy is stale, so re-read before the next edit.
+const REWRITE_HEADER =
+	'The format hook rewrote this file after your edit, so your in-memory copy is now stale — re-read it before the next Edit or the match will miss.'
+const REWRITE_RANGE_PREFIX = 'Changed around lines '
+const LINE_SEPARATOR = '\n'
+const FIRST_LINE = 1
+
+// The span of the post-format file that differs from the pre-format one — the common head and tail
+// are trimmed so the range points at what actually moved rather than the whole file.
+interface ChangedRange {
+	start_line: number
+	end_line: number
+	body: string
+}
+
+function common_prefix_length(before: ReadonlyArray<string>, after: ReadonlyArray<string>): number {
+	const limit = Math.min(before.length, after.length)
+	let index = 0
+
+	while (index < limit && before[index] === after[index]) index += 1
+
+	return index
+}
+
+function common_suffix_length(
+	before: ReadonlyArray<string>,
+	after: ReadonlyArray<string>,
+	prefix: number,
+): number {
+	const limit = Math.min(before.length, after.length) - prefix
+	let index = 0
+
+	while (index < limit && before.at(-1 - index) === after.at(-1 - index)) index += 1
+
+	return index
+}
+
+function changed_range(before: string, after: string): ChangedRange {
+	const before_lines = before.split(LINE_SEPARATOR)
+	const after_lines = after.split(LINE_SEPARATOR)
+	const prefix = common_prefix_length(before_lines, after_lines)
+	const last = after_lines.length - common_suffix_length(before_lines, after_lines, prefix)
+
+	return {
+		start_line: prefix + FIRST_LINE,
+		end_line: Math.max(prefix + FIRST_LINE, last),
+		body: after_lines.slice(prefix, last).join(LINE_SEPARATOR),
+	}
+}
+
+function cap_body(body: string): string {
+	if (body.length <= MAX_REWRITE_CHARS) return body
+
+	return `${body.slice(0, MAX_REWRITE_CHARS)}${REWRITE_TRUNCATION_NOTICE}`
+}
+
+// The block the model reads: the header, the line range, then the region's new text cut to the bound.
+// `undefined` when formatting changed nothing, so the ordinary edit adds nothing to additionalContext.
+function build(before: string, after: string): string | undefined {
+	if (before === after) return undefined
+
+	const range = changed_range(before, after)
+	const location = `${REWRITE_RANGE_PREFIX}${String(range.start_line)}-${String(range.end_line)}:`
+
+	return `${REWRITE_HEADER}\n${location}\n${cap_body(range.body)}`
+}
+
+// The file content around a format run, read for the before/after comparison. A path the hook was
+// handed nothing for, or one gone by the time it reads, compares as an empty string rather than
+// throwing — the hook runs after the write already succeeded and must never turn it into a failure.
+function read_text(file_path: string | undefined): string {
+	if (file_path === undefined) return ''
+
+	try {
+		return readFileSync(file_path, 'utf8')
+	} catch {
+		return ''
+	}
+}
+
+const rewrite_notice = { build, read_text }
+
+export { rewrite_notice, MAX_REWRITE_CHARS }