lazycodex-ai 5.1.48 → 5.1.54

package/packages/lsp-core/src/lsp/workspace-edit-commit.test.ts

@@ -0,0 +1,140 @@
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { afterEach, describe, expect, it } from "bun:test";
+
+import { applyWorkspaceEditDetailed, commitWorkspaceEditPlan, planWorkspaceEdit } from "./workspace-edit.js";
+
+const tempDirectories: string[] = [];
+
+afterEach(() => {
+	for (const directory of tempDirectories.splice(0)) rmSync(directory, { recursive: true, force: true });
+});
+
+describe("workspace edit commit barrier", () => {
+	it("#given cancellation before commit #when a valid plan is applied #then no mutation begins", () => {
+		const fixture = makeFixture();
+		const controller = new AbortController();
+		controller.abort();
+
+		const commit = applyWorkspaceEditDetailed(textEdit(fixture.source, "before", "after"), {
+			workspaceRoot: fixture.workspace,
+			signal: controller.signal,
+		});
+
+		expect(commit.result.success).toBe(false);
+		expect(commit.result.errors.join("\n")).toContain("cancelled before commit");
+		expect(commit.delta.operations).toEqual([]);
+		expect(readFileSync(fixture.source, "utf-8")).toBe("const before = 1;\n");
+	});
+
+	it("#given repeated pre-gate interruptions #when retried #then every attempt leaves the snapshot untouched", () => {
+		const fixture = makeFixture();
+		for (let attempt = 0; attempt < 3; attempt += 1) {
+			const controller = new AbortController();
+			controller.abort();
+			const commit = applyWorkspaceEditDetailed(textEdit(fixture.source, "before", "after"), {
+				workspaceRoot: fixture.workspace,
+				signal: controller.signal,
+			});
+			expect(commit.result.success).toBe(false);
+			expect(commit.delta.operations).toEqual([]);
+		}
+		expect(readFileSync(fixture.source, "utf-8")).toBe("const before = 1;\n");
+	});
+
+	it("#given cancellation after the first write #when commit has crossed the barrier #then all operations finish once", () => {
+		const fixture = makeFixture();
+		const second = join(fixture.workspace, "second.ts");
+		writeFileSync(second, "const second = 2;\n", "utf-8");
+		const controller = new AbortController();
+		let writes = 0;
+
+		const commit = applyWorkspaceEditDetailed(
+			{
+				changes: {
+					[pathToFileURL(fixture.source).href]: [replacement("before", "after")],
+					[pathToFileURL(second).href]: [replacement("second", "later_")],
+				},
+			},
+			{
+				workspaceRoot: fixture.workspace,
+				signal: controller.signal,
+				io: {
+					writeFile(path, content) {
+						writes += 1;
+						writeFileSync(path, content, "utf-8");
+						if (writes === 1) controller.abort();
+					},
+				},
+			},
+		);
+
+		expect(commit.result).toMatchObject({ success: true, lateAbort: true, totalEdits: 2 });
+		expect(writes).toBe(2);
+		expect(readFileSync(fixture.source, "utf-8")).toBe("const after = 1;\n");
+		expect(readFileSync(second, "utf-8")).toBe("const later_ = 2;\n");
+	});
+
+	it("#given an injected write failure #when commit begins #then the result reports real I/O failure", () => {
+		const fixture = makeFixture();
+
+		const commit = applyWorkspaceEditDetailed(textEdit(fixture.source, "before", "after"), {
+			workspaceRoot: fixture.workspace,
+			io: {
+				writeFile() {
+					throw new InjectedWriteError();
+				},
+			},
+		});
+
+		expect(commit.result).toMatchObject({ success: false, failedChange: 0 });
+		expect(commit.result.errors.join("\n")).toContain("I/O failure during text: injected write failure");
+		expect(commit.delta.operations).toEqual([]);
+		expect(readFileSync(fixture.source, "utf-8")).toBe("const before = 1;\n");
+	});
+
+	it("#given a stale file snapshot #when a prepared plan commits #then the newer bytes are preserved", () => {
+		const fixture = makeFixture();
+		const planned = planWorkspaceEdit(textEdit(fixture.source, "before", "after"), fixture.workspace);
+		expect(planned.success).toBe(true);
+		if (!planned.success) return;
+		writeFileSync(fixture.source, "const external = 2;\n", "utf-8");
+
+		const commit = commitWorkspaceEditPlan(planned.plan);
+
+		expect(commit.result.success).toBe(false);
+		expect(commit.result.errors.join("\n")).toContain("workspace state changed before commit");
+		expect(commit.delta.operations).toEqual([]);
+		expect(readFileSync(fixture.source, "utf-8")).toBe("const external = 2;\n");
+	});
+});
+
+class InjectedWriteError extends Error {
+	override readonly name = "InjectedWriteError";
+
+	constructor() {
+		super("injected write failure");
+	}
+}
+
+function makeFixture(): { readonly workspace: string; readonly source: string } {
+	const workspace = mkdtempSync(join(tmpdir(), "lsp-workspace-commit-"));
+	tempDirectories.push(workspace);
+	const source = join(workspace, "source.ts");
+	writeFileSync(source, "const before = 1;\n", "utf-8");
+	return { workspace, source };
+}
+
+function textEdit(path: string, before: string, after: string) {
+	return { changes: { [pathToFileURL(path).href]: [replacement(before, after)] } };
+}
+
+function replacement(before: string, after: string) {
+	return {
+		range: { start: { line: 0, character: 6 }, end: { line: 0, character: 6 + before.length } },
+		newText: after,
+	};
+}

package/packages/lsp-core/src/lsp/workspace-edit-commit.ts

@@ -0,0 +1,220 @@
+import { existsSync, lstatSync, renameSync, rmSync, writeFileSync } from "node:fs";
+
+import { snapshotPath } from "./workspace-edit-path.js";
+import type {
+	ApplyResult,
+	ApplyWorkspaceEditOptions,
+	PlannedWorkspaceOperation,
+	WorkspaceEditCommit,
+	WorkspaceEditCommitIo,
+	WorkspaceEditPlan,
+	WorkspaceMutation,
+	WorkspaceMutationDelta,
+	WorkspaceSnapshotEntry,
+} from "./workspace-edit-types.js";
+
+const DEFAULT_IO: WorkspaceEditCommitIo = {
+	writeFile(path, content) {
+		writeFileSync(path, content, "utf-8");
+	},
+	rename(oldPath, newPath) {
+		renameSync(oldPath, newPath);
+	},
+	remove(path, recursive) {
+		rmSync(path, { recursive, force: false });
+	},
+};
+
+function snapshotsEqual(expected: WorkspaceSnapshotEntry, actual: WorkspaceSnapshotEntry): boolean {
+	if (expected.kind !== actual.kind) return false;
+	if (expected.kind === "file" && actual.kind === "file") return expected.content === actual.content;
+	if (expected.kind === "directory" && actual.kind === "directory" && expected.children !== undefined) {
+		return JSON.stringify(expected.children) === JSON.stringify(actual.children);
+	}
+	return true;
+}
+
+function liveSnapshot(path: string, expected: WorkspaceSnapshotEntry): WorkspaceSnapshotEntry {
+	return snapshotPath(path, expected.kind === "directory" && expected.children !== undefined);
+}
+
+function firstOperationIndex(plan: WorkspaceEditPlan): number {
+	return plan.operations[0]?.changeIndex ?? 0;
+}
+
+interface CommitFailure {
+	readonly message: string;
+	readonly changeIndex: number;
+	readonly mutations?: readonly WorkspaceMutation[];
+	readonly filesModified?: readonly string[];
+	readonly totalEdits?: number;
+	readonly lateAbort?: boolean;
+}
+
+function failedCommit(plan: WorkspaceEditPlan, failure: CommitFailure): WorkspaceEditCommit {
+	const { message, changeIndex, mutations = [], filesModified = [], totalEdits = 0, lateAbort = false } = failure;
+	return {
+		result: {
+			success: false,
+			filesModified,
+			totalEdits,
+			errors: [`change ${changeIndex}: ${message}`],
+			failedChange: changeIndex,
+			...(lateAbort ? { lateAbort: true } : {}),
+		},
+		delta: mutationDelta(mutations),
+		fingerprint: plan.fingerprint,
+	};
+}
+
+function verifySnapshots(plan: WorkspaceEditPlan): WorkspaceEditCommit | null {
+	for (const [path, expected] of plan.snapshots) {
+		let actual: WorkspaceSnapshotEntry;
+		try {
+			actual = liveSnapshot(path, expected);
+		} catch (error) {
+			const changeIndex = plan.firstChangeByPath.get(path) ?? firstOperationIndex(plan);
+			const detail = error instanceof Error ? error.message : String(error);
+			return failedCommit(plan, { message: `cannot verify snapshot for ${path}: ${detail}`, changeIndex });
+		}
+		if (!snapshotsEqual(expected, actual)) {
+			const changeIndex = plan.firstChangeByPath.get(path) ?? firstOperationIndex(plan);
+			return failedCommit(plan, { message: `workspace state changed before commit: ${path}`, changeIndex });
+		}
+	}
+	return null;
+}
+
+function addModifiedPath(paths: string[], path: string): void {
+	if (!paths.includes(path)) paths.push(path);
+}
+
+function reportedPath(plan: WorkspaceEditPlan, path: string): string {
+	return plan.reportedPathByCanonical.get(path) ?? path;
+}
+
+function changedPathsForMutation(mutation: WorkspaceMutation): readonly string[] {
+	return mutation.kind === "rename" ? [mutation.oldPath, mutation.newPath] : [mutation.path];
+}
+
+function mutationDelta(operations: readonly WorkspaceMutation[]): WorkspaceMutationDelta {
+	const changedPaths = new Set<string>();
+	for (const operation of operations) {
+		for (const path of changedPathsForMutation(operation)) changedPaths.add(path);
+	}
+	return { operations, changedPaths: [...changedPaths].sort() };
+}
+
+function resolveIo(overrides: Partial<WorkspaceEditCommitIo> | undefined): WorkspaceEditCommitIo {
+	return {
+		writeFile: overrides?.writeFile ?? DEFAULT_IO.writeFile,
+		rename: overrides?.rename ?? DEFAULT_IO.rename,
+		remove: overrides?.remove ?? DEFAULT_IO.remove,
+	};
+}
+
+interface CommitAccumulator {
+	readonly mutations: WorkspaceMutation[];
+	readonly filesModified: string[];
+	totalEdits: number;
+}
+
+interface CommitContext {
+	readonly plan: WorkspaceEditPlan;
+	readonly io: WorkspaceEditCommitIo;
+	readonly accumulator: CommitAccumulator;
+}
+
+function commitOperation(
+	context: CommitContext,
+	operation: PlannedWorkspaceOperation,
+): void {
+	const { plan, io, accumulator } = context;
+	if (operation.kind === "noop") return;
+	if (operation.kind === "text") {
+		io.writeFile(operation.path, operation.afterText);
+		accumulator.mutations.push({
+			kind: "text",
+			path: operation.path,
+			beforeText: operation.beforeText,
+			afterText: operation.afterText,
+		});
+		addModifiedPath(accumulator.filesModified, reportedPath(plan, operation.path));
+		accumulator.totalEdits += operation.editCount;
+		return;
+	}
+	if (operation.kind === "create") {
+		io.writeFile(operation.path, "");
+		accumulator.mutations.push({ kind: "create", path: operation.path, replaced: operation.replaced });
+		addModifiedPath(accumulator.filesModified, reportedPath(plan, operation.path));
+		return;
+	}
+	if (operation.kind === "rename") {
+		if (operation.replaceDestination) {
+			const targetKind = existsSync(operation.newPath) && lstatSync(operation.newPath).isDirectory() ? "directory" : "file";
+			io.remove(operation.newPath, targetKind === "directory");
+			accumulator.mutations.push({ kind: "delete", path: operation.newPath, targetKind });
+			addModifiedPath(accumulator.filesModified, reportedPath(plan, operation.newPath));
+		}
+		io.rename(operation.oldPath, operation.newPath);
+		accumulator.mutations.push({
+			kind: "rename",
+			oldPath: operation.oldPath,
+			newPath: operation.newPath,
+			sourceKind: operation.sourceKind,
+		});
+		addModifiedPath(accumulator.filesModified, reportedPath(plan, operation.newPath));
+		return;
+	}
+	io.remove(operation.path, operation.recursive);
+	accumulator.mutations.push({
+		kind: "delete",
+		path: operation.path,
+		targetKind: operation.targetKind,
+	});
+	addModifiedPath(accumulator.filesModified, reportedPath(plan, operation.path));
+}
+
+export function commitWorkspaceEditPlan(
+	plan: WorkspaceEditPlan,
+	options: Pick<ApplyWorkspaceEditOptions, "signal" | "io"> = {},
+): WorkspaceEditCommit {
+	if (options.signal?.aborted) {
+		return failedCommit(plan, { message: "cancelled before commit", changeIndex: firstOperationIndex(plan) });
+	}
+	const stale = verifySnapshots(plan);
+	if (stale) return stale;
+	if (options.signal?.aborted) {
+		return failedCommit(plan, { message: "cancelled before commit", changeIndex: firstOperationIndex(plan) });
+	}
+
+	const io = resolveIo(options.io);
+	const accumulator: CommitAccumulator = { mutations: [], filesModified: [], totalEdits: 0 };
+	const context: CommitContext = { plan, io, accumulator };
+	let lateAbort = false;
+	for (const operation of plan.operations) {
+		try {
+			commitOperation(context, operation);
+		} catch (error) {
+			const detail = error instanceof Error ? error.message : String(error);
+			return failedCommit(plan, {
+				message: `I/O failure during ${operation.kind}: ${detail}`,
+				changeIndex: operation.changeIndex,
+				mutations: accumulator.mutations,
+				filesModified: accumulator.filesModified,
+				totalEdits: accumulator.totalEdits,
+				lateAbort: lateAbort || options.signal?.aborted === true,
+			});
+		}
+		if (options.signal?.aborted) lateAbort = true;
+	}
+
+	const result: ApplyResult = {
+		success: true,
+		filesModified: accumulator.filesModified,
+		totalEdits: accumulator.totalEdits,
+		errors: [],
+		...(lateAbort ? { lateAbort: true } : {}),
+	};
+	return { result, delta: mutationDelta(accumulator.mutations), fingerprint: plan.fingerprint };
+}

package/packages/lsp-core/src/lsp/workspace-edit-contract-evidence.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+	CANONICAL_CONCURRENT_WORKSPACE_APPLY_EDIT_FAILURE_REASON,
+	workspaceApplyEditConcurrentFailureReason,
+} from "./workspace-apply-edit-failure.js";
+import {
+	normalizeWorkspaceEditContractEvidence,
+	workspaceEditContractFailureEvidence,
+} from "./workspace-edit-contract-evidence.js";
+
+describe("workspace edit contract evidence", () => {
+	it("#given both legitimate concurrent applyEdit lease outcomes #when failure evidence is hashed #then one canonical shape and hash is produced", () => {
+		const workspace = "/tmp/workspace-edit-contract";
+		const applying = workspaceEditContractFailureEvidence(
+			{
+				applied: false,
+				failureReason: workspaceApplyEditConcurrentFailureReason("applying"),
+			},
+			workspace,
+		);
+		const settled = workspaceEditContractFailureEvidence(
+			{
+				applied: false,
+				failureReason: workspaceApplyEditConcurrentFailureReason("settled"),
+			},
+			workspace,
+		);
+
+		expect(applying.normalized).toEqual({
+			applied: false,
+			failureReason: CANONICAL_CONCURRENT_WORKSPACE_APPLY_EDIT_FAILURE_REASON,
+		});
+		expect(settled.normalized).toEqual(applying.normalized);
+		expect(settled.sha256).toBe(applying.sha256);
+	});
+
+	it("#given workspace-scoped evidence and a non-concurrent failure #when normalized #then paths are sanitized and the reason is preserved", () => {
+		const workspace = "/tmp/workspace-edit-contract";
+
+		expect(
+			normalizeWorkspaceEditContractEvidence(
+				{
+					applied: false,
+					failureReason: "document version 9 does not match open document version 1 for /tmp/workspace-edit-contract/source.ts",
+					nested: ["/tmp/workspace-edit-contract/source.ts"],
+				},
+				workspace,
+			),
+		).toEqual({
+			applied: false,
+			failureReason: "document version 9 does not match open document version 1 for <workspace>/source.ts",
+			nested: ["<workspace>/source.ts"],
+		});
+	});
+});

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

@@ -0,0 +1,30 @@
+import { createHash } from "node:crypto";
+
+import { canonicalizeWorkspaceApplyEditFailureReason } from "./workspace-apply-edit-failure.js";
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+export function normalizeWorkspaceEditContractEvidence(value: unknown, workspace: string): unknown {
+	if (typeof value === "string") return value.replaceAll(workspace, "<workspace>");
+	if (Array.isArray(value)) return value.map((entry) => normalizeWorkspaceEditContractEvidence(entry, workspace));
+	if (!isRecord(value)) return value;
+	const normalized: Record<string, unknown> = {};
+	for (const key of Object.keys(value).sort()) {
+		const entry = normalizeWorkspaceEditContractEvidence(value[key], workspace);
+		normalized[key] =
+			key === "failureReason" && typeof entry === "string"
+				? canonicalizeWorkspaceApplyEditFailureReason(entry)
+				: entry;
+	}
+	return normalized;
+}
+
+export function workspaceEditContractFailureEvidence(value: unknown, workspace: string) {
+	const normalized = normalizeWorkspaceEditContractEvidence(value, workspace);
+	return {
+		normalized,
+		sha256: createHash("sha256").update(JSON.stringify(normalized)).digest("hex"),
+	};
+}

package/packages/lsp-core/src/lsp/workspace-edit-fingerprint.ts

@@ -0,0 +1,44 @@
+import { createHash } from "node:crypto";
+
+import type { ParsedWorkspaceOperation } from "./workspace-edit-plan-types.js";
+
+export function canonicalFingerprint(operations: readonly ParsedWorkspaceOperation[]): string {
+	const canonical = operations.map((operation) => {
+		switch (operation.kind) {
+			case "text":
+				return {
+					kind: operation.kind,
+					changeIndex: operation.changeIndex,
+					path: operation.path,
+					edits: operation.edits,
+					version: operation.version,
+				};
+			case "rename":
+				return {
+					kind: operation.kind,
+					changeIndex: operation.changeIndex,
+					oldPath: operation.oldPath,
+					newPath: operation.newPath,
+					overwrite: operation.overwrite,
+					ignoreIfExists: operation.ignoreIfExists,
+				};
+			case "create":
+				return {
+					kind: operation.kind,
+					changeIndex: operation.changeIndex,
+					path: operation.path,
+					overwrite: operation.overwrite,
+					ignoreIfExists: operation.ignoreIfExists,
+				};
+			case "delete":
+				return {
+					kind: operation.kind,
+					changeIndex: operation.changeIndex,
+					path: operation.path,
+					recursive: operation.recursive,
+					ignoreIfNotExists: operation.ignoreIfNotExists,
+				};
+		}
+	});
+	return createHash("sha256").update(JSON.stringify(canonical)).digest("hex");
+}

package/packages/lsp-core/src/lsp/workspace-edit-options.test.ts

@@ -0,0 +1,147 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { afterEach, describe, expect, it } from "bun:test";
+
+import { applyWorkspaceEdit } from "./workspace-edit.js";
+
+const tempDirectories: string[] = [];
+
+afterEach(() => {
+	for (const directory of tempDirectories.splice(0)) {
+		rmSync(directory, { recursive: true, force: true });
+	}
+});
+
+describe("applyWorkspaceEdit resource options", () => {
+	it("#given create ignoreIfExists #when the target exists #then existing bytes are preserved", () => {
+		// given
+		const workspace = makeTempDirectory();
+		const target = join(workspace, "target.ts");
+		writeFileSync(target, "preserve\n", "utf-8");
+
+		// when
+		const result = applyWorkspaceEdit(
+			{
+				documentChanges: [
+					{ kind: "create", uri: pathToFileURL(target).href, options: { ignoreIfExists: true } },
+				],
+			},
+			{ workspaceRoot: workspace },
+		);
+
+		// then
+		expect(result.success).toBe(true);
+		expect(result.filesModified).toEqual([]);
+		expect(readFileSync(target, "utf-8")).toBe("preserve\n");
+	});
+
+	it("#given rename ignoreIfExists #when the destination exists #then both files are preserved", () => {
+		// given
+		const workspace = makeTempDirectory();
+		const source = join(workspace, "source.ts");
+		const destination = join(workspace, "destination.ts");
+		writeFileSync(source, "source\n", "utf-8");
+		writeFileSync(destination, "destination\n", "utf-8");
+
+		// when
+		const result = applyWorkspaceEdit(
+			{
+				documentChanges: [
+					{
+						kind: "rename",
+						oldUri: pathToFileURL(source).href,
+						newUri: pathToFileURL(destination).href,
+						options: { ignoreIfExists: true },
+					},
+				],
+			},
+			{ workspaceRoot: workspace },
+		);
+
+		// then
+		expect(result.success).toBe(true);
+		expect(result.filesModified).toEqual([]);
+		expect(readFileSync(source, "utf-8")).toBe("source\n");
+		expect(readFileSync(destination, "utf-8")).toBe("destination\n");
+	});
+
+	it("#given rename overwrite #when the destination exists #then source replaces destination", () => {
+		// given
+		const workspace = makeTempDirectory();
+		const source = join(workspace, "source.ts");
+		const destination = join(workspace, "destination.ts");
+		writeFileSync(source, "source\n", "utf-8");
+		writeFileSync(destination, "destination\n", "utf-8");
+
+		// when
+		const result = applyWorkspaceEdit(
+			{
+				documentChanges: [
+					{
+						kind: "rename",
+						oldUri: pathToFileURL(source).href,
+						newUri: pathToFileURL(destination).href,
+						options: { overwrite: true },
+					},
+				],
+			},
+			{ workspaceRoot: workspace },
+		);
+
+		// then
+		expect(result.success).toBe(true);
+		expect(existsSync(source)).toBe(false);
+		expect(readFileSync(destination, "utf-8")).toBe("source\n");
+	});
+
+	it("#given delete ignoreIfNotExists #when the target is missing #then it is a successful no-op", () => {
+		// given
+		const workspace = makeTempDirectory();
+		const target = join(workspace, "missing.ts");
+
+		// when
+		const result = applyWorkspaceEdit(
+			{
+				documentChanges: [
+					{ kind: "delete", uri: pathToFileURL(target).href, options: { ignoreIfNotExists: true } },
+				],
+			},
+			{ workspaceRoot: workspace },
+		);
+
+		// then
+		expect(result.success).toBe(true);
+		expect(result.filesModified).toEqual([]);
+	});
+
+	it("#given recursive delete #when the target is a non-empty directory #then the subtree is removed", () => {
+		// given
+		const workspace = makeTempDirectory();
+		const target = join(workspace, "nested");
+		mkdirSync(target);
+		writeFileSync(join(target, "child.ts"), "child\n", "utf-8");
+
+		// when
+		const result = applyWorkspaceEdit(
+			{
+				documentChanges: [
+					{ kind: "delete", uri: pathToFileURL(target).href, options: { recursive: true } },
+				],
+			},
+			{ workspaceRoot: workspace },
+		);
+
+		// then
+		expect(result.success).toBe(true);
+		expect(existsSync(target)).toBe(false);
+	});
+});
+
+function makeTempDirectory(): string {
+	const directory = mkdtempSync(join(tmpdir(), "lsp-workspace-options-"));
+	tempDirectories.push(directory);
+	return directory;
+}

package/packages/lsp-core/src/lsp/workspace-edit-parse-helpers.ts

@@ -0,0 +1,59 @@
+import type { Position, Range, TextEdit } from "./types.js";
+import { WorkspaceEditValidationError } from "./workspace-edit-types.js";
+
+export function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function parsePosition(value: unknown): Position | null {
+	if (!isRecord(value) || typeof value["line"] !== "number" || typeof value["character"] !== "number") {
+		return null;
+	}
+	return { line: value["line"], character: value["character"] };
+}
+
+function parseRange(value: unknown): Range | null {
+	if (!isRecord(value)) return null;
+	const start = parsePosition(value["start"]);
+	const end = parsePosition(value["end"]);
+	return start && end ? { start, end } : null;
+}
+
+export function parseTextEdits(value: unknown, changeIndex: number): readonly TextEdit[] {
+	if (!Array.isArray(value)) {
+		throw new WorkspaceEditValidationError(changeIndex, "text edits must be an array");
+	}
+	const edits: TextEdit[] = [];
+	for (const candidate of value) {
+		if (!isRecord(candidate) || typeof candidate["newText"] !== "string") {
+			throw new WorkspaceEditValidationError(changeIndex, "text edit requires range and newText");
+		}
+		if ("annotationId" in candidate) {
+			throw new WorkspaceEditValidationError(changeIndex, "annotated text edits are unsupported");
+		}
+		const range = parseRange(candidate["range"]);
+		if (!range) throw new WorkspaceEditValidationError(changeIndex, "text edit range is malformed");
+		edits.push({ range, newText: candidate["newText"] });
+	}
+	return edits;
+}
+
+function parseBooleanOption(options: Record<string, unknown>, key: string, changeIndex: number): boolean {
+	const value = options[key];
+	if (value === undefined) return false;
+	if (typeof value !== "boolean") {
+		throw new WorkspaceEditValidationError(changeIndex, `${key} must be boolean`);
+	}
+	return value;
+}
+
+export function parseOptions(value: unknown, allowed: readonly string[], changeIndex: number): Record<string, boolean> {
+	if (value === undefined) return {};
+	if (!isRecord(value)) throw new WorkspaceEditValidationError(changeIndex, "resource options must be an object");
+	for (const key of Object.keys(value)) {
+		if (!allowed.includes(key)) throw new WorkspaceEditValidationError(changeIndex, `unsupported resource option ${key}`);
+	}
+	const parsed: Record<string, boolean> = {};
+	for (const key of allowed) parsed[key] = parseBooleanOption(value, key, changeIndex);
+	return parsed;
+}