lazycodex-ai 5.1.48 → 5.1.54

package/packages/lsp-core/src/lsp/fixtures/workspace-edit-contract-probe.ts

@@ -0,0 +1,196 @@
+import { readFileSync, realpathSync, writeFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+
+import {
+	createWorkspaceEditTestHarness,
+	diagnostic,
+	readEvents,
+	renameTextEdit,
+	waitForEventCount,
+} from "../workspace-apply-edit-test-support.js";
+import { workspaceEditContractFailureEvidence } from "../workspace-edit-contract-evidence.js";
+
+class WorkspaceEditContractProbeError extends Error {
+	override readonly name = "WorkspaceEditContractProbeError";
+}
+
+function requireProbe(condition: boolean, message: string): asserts condition {
+	if (!condition) throw new WorkspaceEditContractProbeError(message);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function applyResponses(eventsPath: string): readonly unknown[] {
+	return readEvents(eventsPath)
+		.filter((event) => event.type === "clientResponse" && event.method === "workspace/applyEdit")
+		.map((event) => event.result);
+}
+
+function isRejectedApply(value: unknown): boolean {
+	return isRecord(value) && value["applied"] === false && typeof value["failureReason"] === "string";
+}
+
+function didChangeVersions(eventsPath: string): readonly number[] {
+	const versions: number[] = [];
+	for (const event of readEvents(eventsPath)) {
+		if (event.type !== "clientNotification" || event.method !== "textDocument/didChange") continue;
+		if (!isRecord(event.params)) continue;
+		const textDocument = event.params["textDocument"];
+		if (!isRecord(textDocument) || typeof textDocument["version"] !== "number") continue;
+		versions.push(textDocument["version"]);
+	}
+	return versions;
+}
+
+const outputPath = process.argv[2];
+if (!outputPath) throw new WorkspaceEditContractProbeError("output path is required");
+
+const harness = createWorkspaceEditTestHarness();
+try {
+	const success = await harness.makeClient({
+		renameSteps: [{ applyEdit: renameTextEdit("before", "after", { version: 1 }), renameResult: "same" }],
+		diagnostics: [diagnostic("todo3-fresh")],
+	});
+	let successWrites = 0;
+	success.client.setWorkspaceEditIo({
+		writeFile(path, content) {
+			successWrites += 1;
+			writeFileSync(path, content, "utf-8");
+		},
+	});
+	await success.client.openFile(success.source);
+	const successResult = await success.client.rename(success.source, 1, 6, "after");
+	const successResponses = applyResponses(success.events);
+	const successVersions = didChangeVersions(success.events);
+	const successUri = pathToFileURL(realpathSync(success.source)).href;
+	const successEvidence = {
+		serverAppliedRename:
+			successResponses.length === 1 && isRecord(successResponses[0]) && successResponses[0]["applied"] === true,
+		recordedResultReused: successResult.edit !== null && successResult.apply.success && successWrites === 1,
+		writeCount: successWrites,
+		secondWritePrevented: successWrites === 1 && successVersions.length === 1,
+		synchronizedDocumentVersion: success.client.getOpenDocumentVersion(success.source) ?? null,
+		didChangeVersions: successVersions,
+		immediateDiagnostics: success.client
+			.getStoredDiagnostics(successUri)
+			.some((entry) => entry.message === "todo3-fresh"),
+		finalContent: readFileSync(success.source, "utf-8"),
+	};
+	requireProbe(successEvidence.serverAppliedRename, "successful server apply was not reported truthfully");
+	requireProbe(successEvidence.recordedResultReused, "rename did not reuse the recorded server result");
+	requireProbe(successEvidence.secondWritePrevented, "server edit was written or synchronized more than once");
+	requireProbe(successEvidence.synchronizedDocumentVersion === 2, "open document version did not advance to 2");
+	requireProbe(successEvidence.immediateDiagnostics, "fresh diagnostics were not visible immediately after applyEdit");
+	requireProbe(successEvidence.finalContent === "const after = 1;\n", "successful rename produced unexpected bytes");
+
+	const unscoped = await harness.makeClient({
+		unscopedApplyEdit: renameTextEdit("before", "after", { version: 1 }),
+	});
+	const unscopedResponses = await waitForEventCount(
+		unscoped.events,
+		(event) => event.type === "clientResponse" && event.method === "workspace/applyEdit",
+		1,
+	);
+	const unscopedFailure = unscopedResponses[0]?.result;
+	requireProbe(isRejectedApply(unscopedFailure), "unscoped applyEdit was not rejected");
+	requireProbe(readFileSync(unscoped.source, "utf-8") === "const before = 1;\n", "unscoped failure mutated bytes");
+
+	const concurrent = await harness.makeClient({
+		renameSteps: [
+			{
+				applyEdit: renameTextEdit("before", "after", { version: 1 }),
+				applyConcurrently: true,
+				renameResult: "same",
+			},
+		],
+	});
+	let concurrentWrites = 0;
+	concurrent.client.setWorkspaceEditIo({
+		writeFile(path, content) {
+			concurrentWrites += 1;
+			writeFileSync(path, content, "utf-8");
+		},
+	});
+	await concurrent.client.openFile(concurrent.source);
+	const concurrentResult = await concurrent.client.rename(concurrent.source, 1, 6, "after");
+	const concurrentFailure = applyResponses(concurrent.events).find(isRejectedApply);
+	requireProbe(concurrentResult.apply.success, "the winning concurrent applyEdit did not complete");
+	requireProbe(concurrentWrites === 1, "concurrent applyEdit wrote more than once");
+	requireProbe(isRejectedApply(concurrentFailure), "concurrent applyEdit loser was not rejected");
+
+	const mismatched = await harness.makeClient({
+		renameSteps: [{ applyEdit: renameTextEdit("before", "after", { version: 9 }), renameResult: "same" }],
+	});
+	await mismatched.client.openFile(mismatched.source);
+	const mismatchedResult = await mismatched.client.rename(mismatched.source, 1, 6, "after");
+	const mismatchedFailure = applyResponses(mismatched.events).find(isRejectedApply);
+	requireProbe(!mismatchedResult.apply.success, "mismatched document version unexpectedly succeeded");
+	requireProbe(isRejectedApply(mismatchedFailure), "mismatched version was not rejected over applyEdit");
+	requireProbe(readFileSync(mismatched.source, "utf-8") === "const before = 1;\n", "version failure mutated bytes");
+
+	const preGate = await harness.makeClient({
+		renameSteps: [
+			{
+				applyEdit: renameTextEdit("before", "after", { version: 1 }),
+				applyDelayMs: 100,
+				renameResult: "same",
+			},
+		],
+	});
+	const controller = new AbortController();
+	await preGate.client.openFile(preGate.source);
+	const pendingRename = preGate.client.rename(preGate.source, 1, 6, "after", controller.signal);
+	await waitForEventCount(
+		preGate.events,
+		(event) => event.type === "clientRequest" && event.method === "textDocument/rename",
+		1,
+		);
+		controller.abort();
+		const preGateError = await pendingRename.then(
+			() => null,
+			(error: unknown) => error,
+		);
+		const preGateMessage = preGateError instanceof Error ? preGateError.message : String(preGateError);
+		const preGateFailure = {
+			success: false,
+			filesModified: [],
+			totalEdits: 0,
+			errors: [preGateMessage],
+		};
+		requireProbe(preGateError !== null, "pre-gate cancellation unexpectedly succeeded");
+		requireProbe(
+			preGateFailure.errors.some((message) => /cancel|abort/i.test(message)),
+			"pre-gate cancellation returned the wrong failure",
+		);
+		requireProbe(readFileSync(preGate.source, "utf-8") === "const before = 1;\n", "pre-gate cancellation mutated bytes");
+
+	const failureCases = {
+			unscoped: workspaceEditContractFailureEvidence(unscopedFailure, unscoped.workspace),
+			concurrent: workspaceEditContractFailureEvidence(concurrentFailure, concurrent.workspace),
+			mismatched: workspaceEditContractFailureEvidence(mismatchedFailure, mismatched.workspace),
+			preGate: workspaceEditContractFailureEvidence(preGateFailure, preGate.workspace),
+		};
+	writeFileSync(
+		outputPath,
+		`${JSON.stringify(
+			{
+				schemaVersion: 1,
+				success: successEvidence,
+				failureCases,
+				failureHashes: {
+					unscoped: failureCases.unscoped.sha256,
+					concurrent: failureCases.concurrent.sha256,
+					mismatched: failureCases.mismatched.sha256,
+					preGate: failureCases.preGate.sha256,
+				},
+			},
+			null,
+			2,
+		)}\n`,
+		"utf-8",
+	);
+} finally {
+	await harness.cleanup();
+}

package/packages/lsp-core/src/lsp/fixtures/workspace-edit-server.mjs

@@ -0,0 +1,234 @@
+import { appendFileSync, readFileSync } from "node:fs";
+
+const [, , scenarioPath, eventsPath] = process.argv;
+const scenario = JSON.parse(readFileSync(scenarioPath, "utf-8"));
+
+let buffer = Buffer.alloc(0);
+let nextServerRequestId = 10_000;
+let renameIndex = 0;
+let diagnosticIndex = 0;
+const pendingServerRequests = new Map();
+const releasedDiagnosticResponses = [];
+
+function record(event) {
+	appendFileSync(eventsPath, `${JSON.stringify(event)}\n`, "utf-8");
+}
+
+function send(message) {
+	const body = Buffer.from(JSON.stringify(message), "utf-8");
+	process.stdout.write(`Content-Length: ${body.length}\r\n\r\n`);
+	process.stdout.write(body);
+}
+
+function sendResponse(id, result) {
+	send({ jsonrpc: "2.0", id, result });
+}
+
+function sendError(id, code, message) {
+	send({ jsonrpc: "2.0", id, error: { code, message } });
+}
+
+function sendApplyEdit(edit, context) {
+	const id = nextServerRequestId;
+	nextServerRequestId += 1;
+	pendingServerRequests.set(String(id), context);
+	record({ type: "serverRequest", method: "workspace/applyEdit", id, edit });
+	send({ jsonrpc: "2.0", id, method: "workspace/applyEdit", params: { edit } });
+}
+
+function renameResult(step) {
+	if (step.renameResult === "same") return step.applyEdit ?? null;
+	if (step.renameResult === "different") return step.differentEdit ?? null;
+	if (step.renameResult === "edit") return step.renameEdit ?? null;
+	return null;
+}
+
+function finishRename(context) {
+	const result = renameResult(context.step);
+	const delay = Number(context.step.responseDelayMs ?? 0);
+	setTimeout(() => {
+		record({ type: "serverResponse", method: "textDocument/rename", result });
+		sendResponse(context.renameRequestId, result);
+	}, delay);
+}
+
+function sendPublishDeliveryBarrier() {
+	const id = nextServerRequestId;
+	nextServerRequestId += 1;
+	pendingServerRequests.set(String(id), { kind: "publishDeliveryBarrier", method: "workspace/configuration" });
+	record({ type: "serverRequest", method: "workspace/configuration", id });
+	send({ jsonrpc: "2.0", id, method: "workspace/configuration", params: { items: [] } });
+}
+
+function schedulePublish(step, fallbackUri, fallbackVersion) {
+	const delay = Number(step.delayMs ?? 0);
+	setTimeout(() => {
+		const params = {
+			uri: step.uri ?? fallbackUri,
+			...(step.version === undefined ? {} : { version: step.version }),
+			diagnostics: Array.isArray(step.diagnostics) ? step.diagnostics : [],
+		};
+		record({ type: "serverNotification", method: "textDocument/publishDiagnostics", params });
+		send({ jsonrpc: "2.0", method: "textDocument/publishDiagnostics", params });
+		if (step.awaitClientDelivery === true) sendPublishDeliveryBarrier();
+	}, delay);
+}
+
+function publishSteps(trigger) {
+	if (!Array.isArray(scenario.publishDiagnostics)) return [];
+	return scenario.publishDiagnostics.filter((step) => step?.trigger === trigger);
+}
+
+function applyPublishSteps(trigger, fallbackUri, fallbackVersion) {
+	for (const step of publishSteps(trigger)) schedulePublish(step, fallbackUri, fallbackVersion);
+}
+
+function handleClientResponse(message) {
+	const context = pendingServerRequests.get(String(message.id));
+	if (!context) return;
+	pendingServerRequests.delete(String(message.id));
+	record({
+		type: "clientResponse",
+		method: context.method ?? "workspace/applyEdit",
+		result: message.result ?? null,
+		error: message.error ?? null,
+	});
+	if (context.kind === "publishDeliveryBarrier" || context.kind === "unscoped") return;
+	if (typeof context.pendingApplyResponses === "number") {
+		context.pendingApplyResponses -= 1;
+		if (context.pendingApplyResponses > 0) return;
+		finishRename(context);
+		return;
+	}
+	if (context.step.applyTwice === true && context.applyCount === 1) {
+		sendApplyEdit(context.step.applyEdit, { ...context, applyCount: 2 });
+		return;
+	}
+	finishRename(context);
+}
+
+function handleRequest(message) {
+	if (message.method === "initialize") {
+		record({ type: "clientRequest", method: message.method, id: message.id, params: message.params });
+		sendResponse(message.id, { capabilities: scenario.capabilities ?? {} });
+		return;
+	}
+	if (message.method === "textDocument/rename") {
+		const step = scenario.renameSteps?.[renameIndex] ?? {};
+		renameIndex += 1;
+		record({ type: "clientRequest", method: message.method, id: message.id, params: message.params, renameIndex });
+		if (step.applyEdit) {
+			const context = { kind: "rename", renameRequestId: message.id, step, applyCount: 1 };
+			if (step.applyConcurrently === true) {
+				context.pendingApplyResponses = 2;
+				sendApplyEdit(step.applyEdit, context);
+				sendApplyEdit(step.applyEdit, context);
+				return;
+			}
+			const delay = Number(step.applyDelayMs ?? 0);
+			if (delay > 0) {
+				setTimeout(() => sendApplyEdit(step.applyEdit, context), delay);
+				return;
+			}
+			sendApplyEdit(step.applyEdit, context);
+			return;
+		}
+		finishRename({ renameRequestId: message.id, step });
+		return;
+	}
+	if (message.method === "textDocument/diagnostic") {
+		record({ type: "clientRequest", method: message.method, id: message.id, params: message.params, diagnosticIndex: diagnosticIndex + 1 });
+		applyPublishSteps("diagnosticRequest", message.params?.textDocument?.uri, undefined);
+		const step = Array.isArray(scenario.diagnosticResponses) ? scenario.diagnosticResponses[diagnosticIndex] : undefined;
+		diagnosticIndex += 1;
+		if (step?.action === "hang") return;
+		if (step?.action === "close") {
+			const delay = Number(step.delayMs ?? 0);
+			setTimeout(() => process.exit(0), delay);
+			return;
+		}
+		const sendDiagnosticResponse = () => {
+			if (step?.error) {
+				record({ type: "serverError", method: "textDocument/diagnostic", error: step.error });
+				sendError(message.id, step.error.code, step.error.message);
+				return;
+			}
+			const result = step?.report ?? { items: scenario.diagnostics ?? [] };
+			record({ type: "serverResponse", method: "textDocument/diagnostic", result });
+			sendResponse(message.id, result);
+		};
+		if (step?.releaseOnDidChange === true) {
+			releasedDiagnosticResponses.push(sendDiagnosticResponse);
+		} else {
+			const delay = Number(step?.delayMs ?? 0);
+			setTimeout(sendDiagnosticResponse, delay);
+		}
+		return;
+	}
+	if (message.method === "shutdown") {
+		sendResponse(message.id, null);
+		return;
+	}
+	sendResponse(message.id, null);
+}
+
+function handleNotification(message) {
+	record({ type: "clientNotification", method: message.method, params: message.params ?? null });
+	if (message.method === "initialized" && scenario.unscopedApplyEdit) {
+		sendApplyEdit(scenario.unscopedApplyEdit, { kind: "unscoped" });
+	}
+	if (message.method === "initialized") {
+		applyPublishSteps("initialized", undefined, undefined);
+	}
+	if (message.method === "textDocument/didOpen") {
+		applyPublishSteps("didOpen", message.params.textDocument.uri, message.params.textDocument.version);
+		if (scenario.unscopedApplyEditOnDidOpen) {
+			sendApplyEdit(scenario.unscopedApplyEditOnDidOpen, { kind: "unscoped" });
+		}
+	}
+	if (message.method === "textDocument/didChange" && Array.isArray(scenario.diagnostics)) {
+		send({
+			jsonrpc: "2.0",
+			method: "textDocument/publishDiagnostics",
+			params: {
+				uri: message.params.textDocument.uri,
+				version: message.params.textDocument.version,
+				diagnostics: scenario.diagnostics,
+			},
+		});
+	}
+	if (message.method === "textDocument/didChange") {
+		applyPublishSteps("didChange", message.params.textDocument.uri, message.params.textDocument.version);
+		for (const release of releasedDiagnosticResponses.splice(0)) release();
+	}
+	if (message.method === "exit") process.exit(0);
+}
+
+function handleMessage(message) {
+	if (Object.hasOwn(message, "id") && (Object.hasOwn(message, "result") || Object.hasOwn(message, "error"))) {
+		handleClientResponse(message);
+		return;
+	}
+	if (Object.hasOwn(message, "id")) {
+		handleRequest(message);
+		return;
+	}
+	handleNotification(message);
+}
+
+process.stdin.on("data", (chunk) => {
+	buffer = Buffer.concat([buffer, chunk]);
+	for (;;) {
+		const headerEnd = buffer.indexOf("\r\n\r\n");
+		if (headerEnd === -1) return;
+		const header = buffer.subarray(0, headerEnd).toString("ascii");
+		const match = /content-length:\s*(\d+)/i.exec(header);
+		if (!match) process.exit(2);
+		const length = Number(match[1]);
+		const bodyStart = headerEnd + 4;
+		if (buffer.length < bodyStart + length) return;
+		const body = buffer.subarray(bodyStart, bodyStart + length).toString("utf-8");
+		buffer = buffer.subarray(bodyStart + length);
+		handleMessage(JSON.parse(body));
+	}
+});

package/packages/lsp-core/src/lsp/format-document.test.ts

@@ -0,0 +1,143 @@
+import { mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { afterEach, describe, expect, it } from "bun:test";
+
+import type { LspClient } from "./client.js";
+import { formatDocumentWithClient } from "./format-document.js";
+import type { TextEdit } from "./types.js";
+
+const workspaces: string[] = [];
+
+afterEach(() => {
+	for (const workspace of workspaces.splice(0)) rmSync(workspace, { recursive: true, force: true });
+});
+
+function workspaceWith(fileName: string, content: string): { readonly root: string; readonly filePath: string } {
+	const root = mkdtempSync(join(tmpdir(), "lsp-format-"));
+	workspaces.push(root);
+	const filePath = join(root, fileName);
+	writeFileSync(filePath, content, "utf-8");
+	return { root, filePath };
+}
+
+function stubClient(edits: TextEdit[] | null): LspClient {
+	return {
+		async formatDocument() {
+			return edits;
+		},
+		async openFile() {},
+	} as Pick<LspClient, "formatDocument" | "openFile"> as LspClient;
+}
+
+describe("formatDocumentWithClient", () => {
+	it("#given a server returning text edits #when the document is formatted #then the file is rewritten and line deltas are reported", async () => {
+		// given
+		const { filePath } = workspaceWith("sample.ts", "const a=1\nconst b   =2\nconst c=3\n");
+		const edits: TextEdit[] = [
+			{ range: { start: { line: 0, character: 0 }, end: { line: 1, character: 12 } }, newText: "const a = 1;\nconst b = 2;" },
+		];
+
+		// when
+		const result = await formatDocumentWithClient(stubClient(edits), filePath);
+
+		// then
+		expect(result.status).toBe("formatted");
+		expect(readFileSync(filePath, "utf-8")).toBe("const a = 1;\nconst b = 2;\nconst c=3\n");
+		expect(result).toMatchObject({ status: "formatted", linesAdded: 2, linesRemoved: 2 });
+	});
+
+	it("#given a server returning an edit that adds lines #when the document is formatted #then the added and removed line counts differ", async () => {
+		// given
+		const { filePath } = workspaceWith("sample.ts", "const a=1;const b=2\n");
+		const edits: TextEdit[] = [
+			{ range: { start: { line: 0, character: 0 }, end: { line: 0, character: 19 } }, newText: "const a = 1;\nconst b = 2;" },
+		];
+
+		// when
+		const result = await formatDocumentWithClient(stubClient(edits), filePath);
+
+		// then
+		expect(result).toMatchObject({ status: "formatted", linesAdded: 2, linesRemoved: 1 });
+		expect(readFileSync(filePath, "utf-8")).toBe("const a = 1;\nconst b = 2;\n");
+	});
+
+	it("#given a server that does not advertise document formatting #when the document is formatted #then the result is unavailable and the file bytes are untouched", async () => {
+		// given
+		const original = "const a=1\n";
+		const { filePath } = workspaceWith("sample.ts", original);
+		const before = statSync(filePath);
+
+		// when
+		const result = await formatDocumentWithClient(stubClient(null), filePath);
+
+		// then
+		expect(result).toEqual({ status: "unavailable", reason: "capability_not_advertised" });
+		expect(readFileSync(filePath)).toEqual(Buffer.from(original));
+		expect(statSync(filePath).mtimeMs).toBe(before.mtimeMs);
+	});
+
+	it("#given a server returning no edits #when the document is formatted #then the result is unchanged and the file bytes are untouched", async () => {
+		// given
+		const original = "const a = 1;\n";
+		const { filePath } = workspaceWith("sample.ts", original);
+
+		// when
+		const result = await formatDocumentWithClient(stubClient([]), filePath);
+
+		// then
+		expect(result).toEqual({ status: "unchanged", linesAdded: 0, linesRemoved: 0 });
+		expect(readFileSync(filePath)).toEqual(Buffer.from(original));
+	});
+
+	it("#given edits that reproduce the current bytes #when the document is formatted #then the result is unchanged", async () => {
+		// given
+		const original = "const a = 1;\n";
+		const { filePath } = workspaceWith("sample.ts", original);
+		const edits: TextEdit[] = [
+			{ range: { start: { line: 0, character: 0 }, end: { line: 0, character: 12 } }, newText: "const a = 1;" },
+		];
+
+		// when
+		const result = await formatDocumentWithClient(stubClient(edits), filePath);
+
+		// then
+		expect(result.status).toBe("unchanged");
+		expect(readFileSync(filePath, "utf-8")).toBe(original);
+	});
+
+	it("#given the file shrinks after the server computed its edits #when the edits are applied #then the stale edit is rejected instead of corrupting the file", async () => {
+		// given
+		const { filePath } = workspaceWith("sample.ts", "const a=1\nconst b=2\n");
+		const staleEdits: TextEdit[] = [
+			{ range: { start: { line: 1, character: 0 }, end: { line: 1, character: 9 } }, newText: "const b = 2;" },
+		];
+		const racingClient = {
+			async formatDocument() {
+				writeFileSync(filePath, "short\n", "utf-8");
+				return staleEdits;
+			},
+			async openFile() {},
+		} as Pick<LspClient, "formatDocument" | "openFile"> as LspClient;
+
+		// when / then
+		await expect(formatDocumentWithClient(racingClient, filePath)).rejects.toThrow(/outside line/);
+		expect(readFileSync(filePath, "utf-8")).toBe("short\n");
+	});
+
+	it("#given a formatted document #when the write completes #then no temporary file is left behind", async () => {
+		// given
+		const { root, filePath } = workspaceWith("sample.ts", "const a=1\n");
+		const edits: TextEdit[] = [
+			{ range: { start: { line: 0, character: 0 }, end: { line: 0, character: 9 } }, newText: "const a = 1;" },
+		];
+
+		// when
+		await formatDocumentWithClient(stubClient(edits), filePath);
+
+		// then
+		expect(readFileSync(filePath, "utf-8")).toBe("const a = 1;\n");
+		expect(() => statSync(join(root, "sample.ts.tmp"))).toThrow();
+	});
+});

package/packages/lsp-core/src/lsp/format-document.ts

@@ -0,0 +1,90 @@
+import { readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
+
+import type { LspClient } from "./client.js";
+import type { FormattingOptions, TextEdit } from "./types.js";
+import { normalizeTextEdits } from "./workspace-edit-text.js";
+
+export const DEFAULT_FORMATTING_OPTIONS: FormattingOptions = {
+	tabSize: 4,
+	insertSpaces: false,
+	trimTrailingWhitespace: true,
+	insertFinalNewline: true,
+	trimFinalNewlines: true,
+};
+
+export type FormatDocumentResult =
+	| { readonly status: "formatted"; readonly linesAdded: number; readonly linesRemoved: number }
+	| { readonly status: "unchanged"; readonly linesAdded: 0; readonly linesRemoved: 0 }
+	| { readonly status: "unavailable"; readonly reason: "capability_not_advertised" };
+
+export interface FormatDocumentOptions {
+	readonly formattingOptions?: FormattingOptions;
+	readonly signal?: AbortSignal;
+}
+
+const UNCHANGED: FormatDocumentResult = { status: "unchanged", linesAdded: 0, linesRemoved: 0 };
+
+/**
+ * Formats one document through the resident language server and commits the result to disk.
+ *
+ * The server is asked for whole-document edits rather than formatted text, so the edits are
+ * validated and applied with the same normalization the workspace-edit path uses. Nothing is
+ * written when the server declines the capability or when the edits reproduce the current bytes,
+ * which keeps a no-op format from touching file mtimes that downstream tooling watches.
+ */
+export async function formatDocumentWithClient(
+	client: LspClient,
+	filePath: string,
+	options: FormatDocumentOptions = {},
+): Promise<FormatDocumentResult> {
+	const edits = await client.formatDocument(
+		filePath,
+		options.formattingOptions ?? DEFAULT_FORMATTING_OPTIONS,
+		options.signal,
+	);
+	if (edits === null) return { status: "unavailable", reason: "capability_not_advertised" };
+	if (edits.length === 0) return UNCHANGED;
+
+	const before = readFileSync(filePath, "utf-8");
+	const normalized = normalizeTextEdits(before, edits, 0);
+	if (normalized.text === before) return UNCHANGED;
+
+	writeAtomically(filePath, normalized.text);
+	await client.openFile(filePath);
+
+	return {
+		status: "formatted",
+		...lineDelta(normalized.edits),
+	};
+}
+
+/**
+ * Counts the lines each edit removes from the document and adds back in its place.
+ *
+ * Counting from the edits instead of diffing the whole file keeps the report proportional to what
+ * the server actually rewrote, so an unrelated line never shows up as churn.
+ */
+function lineDelta(edits: readonly TextEdit[]): { readonly linesAdded: number; readonly linesRemoved: number } {
+	let linesAdded = 0;
+	let linesRemoved = 0;
+	for (const edit of edits) {
+		linesRemoved += edit.range.end.line - edit.range.start.line + 1;
+		linesAdded += edit.newText.split("\n").length;
+	}
+	return { linesAdded, linesRemoved };
+}
+
+function writeAtomically(filePath: string, content: string): void {
+	const tempPath = `${filePath}.omo-format.tmp`;
+	writeFileSync(tempPath, content, "utf-8");
+	try {
+		renameSync(tempPath, filePath);
+	} catch (error) {
+		try {
+			unlinkSync(tempPath);
+		} catch {
+			// The rename failure is the actionable error; a leftover temp file must not mask it.
+		}
+		throw error;
+	}
+}