lazycodex-ai 5.1.48 → 5.1.54

package/packages/lsp-core/src/post-edit/not-installed-guidance.ts

@@ -0,0 +1,36 @@
+import type { PostEditFileLocation } from "./file-location.js";
+
+export interface PostEditNotInstalledOutcome {
+	readonly kind: "not_installed";
+	readonly serverId: string;
+	readonly installDecisionTool: boolean;
+	/** A recorded install decision; absent while the user has not decided. */
+	readonly decision?: "declined" | "allowed";
+	readonly text: string;
+}
+
+export interface NotInstalledGuidanceState {
+	readonly notInstalledServers: Set<string>;
+}
+
+/**
+ * Decides whether a missing-server nudge reaches the model.
+ *
+ * Recorded decisions keep their own text. Undecided nudges are skipped for files outside a project
+ * (no marked root, the agent's config dir, or a temp dir) because a repo-local install there would
+ * create a manifest in HOME or a temp dir. Without a decision tool nothing can be recorded, so a
+ * server is nudged at most once per session state.
+ */
+export function notInstalledGuidance(
+	filePath: string,
+	outcome: PostEditNotInstalledOutcome,
+	state: NotInstalledGuidanceState,
+	locateFile: ((filePath: string) => PostEditFileLocation) | undefined,
+): string | undefined {
+	if (outcome.decision !== undefined) return outcome.text;
+	if (locateFile !== undefined && locateFile(filePath) !== "project") return undefined;
+	if (outcome.installDecisionTool) return outcome.text;
+	if (state.notInstalledServers.has(outcome.serverId)) return undefined;
+	state.notInstalledServers.add(outcome.serverId);
+	return outcome.text;
+}

package/packages/lsp-core/src/post-edit/not-installed.test.ts

@@ -0,0 +1,224 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "bun:test";
+
+import {
+	classifyPostEditFileLocation,
+	collectPostEditDiagnostics,
+	createPostEditNotConfiguredCache,
+	type PostEditDiagnosticsOutcome,
+	type PostEditFileLocation,
+	resetPostEditNotConfiguredCache,
+} from "./index.js";
+
+const tempDirectories: string[] = [];
+
+afterEach(() => {
+	for (const directory of tempDirectories.splice(0)) {
+		rmSync(directory, { recursive: true, force: true });
+	}
+});
+
+function tempRoot(prefix: string): string {
+	const root = mkdtempSync(join(tmpdir(), prefix));
+	tempDirectories.push(root);
+	return root;
+}
+
+function touch(path: string, text = ""): string {
+	mkdirSync(join(path, ".."), { recursive: true });
+	writeFileSync(path, text);
+	return path;
+}
+
+const FULL_NUDGE = [
+	"LSP server 'typescript' for .ts is NOT INSTALLED.",
+	"To install in THIS repository (preferred, no global install needed):",
+	"ACTION REQUIRED: ASK THE USER whether to install this LSP server.",
+].join("\n");
+
+function notInstalled(
+	serverId: string,
+	overrides: Partial<Extract<PostEditDiagnosticsOutcome, { kind: "not_installed" }>> = {},
+): PostEditDiagnosticsOutcome {
+	return {
+		kind: "not_installed",
+		serverId,
+		installDecisionTool: false,
+		text: `${FULL_NUDGE} (${serverId})`,
+		...overrides,
+	};
+}
+
+function at(location: PostEditFileLocation): () => PostEditFileLocation {
+	return () => location;
+}
+
+describe("classifyPostEditFileLocation", () => {
+	it("#given a file with no workspace marker above it #when classified #then it is outside any project", () => {
+		const root = tempRoot("lsp-postedit-noproject-");
+		const file = touch(join(root, "scratch", "note.mjs"));
+
+		expect(classifyPostEditFileLocation(file, { cwd: root, agentDirs: [], tempDirs: [] })).toBe("outside_project");
+	});
+
+	it("#given a file under the agent config dir inside a git repository #when classified #then the agent config dir wins", () => {
+		const root = tempRoot("lsp-postedit-agentdir-");
+		mkdirSync(join(root, ".git"));
+		const agentDir = join(root, ".omo", "agent");
+		const file = touch(join(agentDir, "models.json"), "{}\n");
+
+		expect(classifyPostEditFileLocation(file, { cwd: root, agentDirs: [agentDir], tempDirs: [] })).toBe(
+			"agent_config",
+		);
+	});
+
+	it("#given a temp dir holding a stray package.json #when a scratch file there is classified #then it is a temp file", () => {
+		const temp = tempRoot("lsp-postedit-temp-");
+		touch(join(temp, "package.json"), "{}\n");
+		const file = touch(join(temp, "rules_test.mjs"));
+
+		expect(classifyPostEditFileLocation(file, { cwd: temp, agentDirs: [], tempDirs: [temp] })).toBe("temp");
+	});
+
+	it("#given the default temp dirs #when an OS temp file is classified #then the canonical temp dir matches", () => {
+		const root = tempRoot("lsp-postedit-ostemp-");
+		const file = touch(join(root, "scratch.mjs"));
+
+		expect(classifyPostEditFileLocation(file, { cwd: root, agentDirs: [] })).toBe("temp");
+		if (process.platform !== "win32") {
+			const slashTmp = join("/tmp", `lsp-postedit-missing-${process.pid}`, "rules_test.mjs");
+			expect(classifyPostEditFileLocation(slashTmp, { cwd: root, agentDirs: [] })).toBe("temp");
+		}
+	});
+
+	for (const marker of ["package.json", ".git"] as const) {
+		it(`#given a ${marker} directly in HOME #when a home-level file is classified #then HOME is not its project`, () => {
+			const home = tempRoot("lsp-postedit-home-");
+			if (marker === ".git") mkdirSync(join(home, ".git"));
+			else touch(join(home, marker), "{}\n");
+			const topLevel = touch(join(home, "notes.ts"));
+			const nested = touch(join(home, "scratch", "draft.ts"));
+
+			const options = { cwd: home, agentDirs: [], tempDirs: [], homeDirs: [home] };
+			expect(classifyPostEditFileLocation(topLevel, options)).toBe("outside_project");
+			expect(classifyPostEditFileLocation(nested, options)).toBe("outside_project");
+		});
+	}
+
+	it("#given a marked HOME and a project under it #when a project file is classified #then it is still a project", () => {
+		const home = tempRoot("lsp-postedit-homeproject-");
+		mkdirSync(join(home, ".git"));
+		touch(join(home, "work", "app", "package.json"), "{}\n");
+		const file = touch(join(home, "work", "app", "src", "a.ts"));
+
+		expect(classifyPostEditFileLocation(file, { cwd: home, agentDirs: [], tempDirs: [], homeDirs: [home] })).toBe(
+			"project",
+		);
+	});
+
+	it("#given a project with its own marker inside a temp dir #when classified #then it is a project", () => {
+		const temp = tempRoot("lsp-postedit-tempproject-");
+		const project = join(temp, "checkout");
+		touch(join(project, "package.json"), "{}\n");
+		const file = touch(join(project, "src", "a.ts"));
+
+		expect(classifyPostEditFileLocation(file, { cwd: project, agentDirs: [], tempDirs: [temp] })).toBe("project");
+		expect(classifyPostEditFileLocation("src/a.ts", { cwd: project, agentDirs: [], tempDirs: [temp] })).toBe(
+			"project",
+		);
+	});
+});
+
+describe("collectPostEditDiagnostics not-installed guidance", () => {
+	for (const location of ["outside_project", "agent_config", "temp"] as const) {
+		it(`#given a missing server for a ${location} file #when diagnostics run #then the install nudge is skipped`, async () => {
+			const result = await collectPostEditDiagnostics({
+				filePaths: ["file.ts"],
+				runDiagnostics: async () => notInstalled("typescript"),
+				locateFile: at(location),
+			});
+
+			expect(result.blocks).toEqual([]);
+			expect(result.observations).toEqual([{ filePath: "file.ts", kind: "not_installed" }]);
+		});
+	}
+
+	it("#given a missing server for a project file #when diagnostics run #then today's full guidance is kept", async () => {
+		const result = await collectPostEditDiagnostics({
+			filePaths: ["src/a.ts"],
+			runDiagnostics: async () => notInstalled("typescript"),
+			locateFile: at("project"),
+		});
+
+		expect(result.blocks).toEqual([{ filePath: "src/a.ts", diagnostics: `${FULL_NUDGE} (typescript)`, blocking: false }]);
+	});
+
+	it("#given no decision tool #when repeated edits hit missing servers #then each server is nudged once per session", async () => {
+		const cache = createPostEditNotConfiguredCache();
+		const serverFor = (filePath: string): string => (filePath.endsWith(".json") ? "biome" : "typescript");
+		const run = (filePaths: readonly string[]) =>
+			collectPostEditDiagnostics({
+				filePaths,
+				cache,
+				runDiagnostics: async (filePath) => notInstalled(serverFor(filePath)),
+				locateFile: at("project"),
+			});
+
+		const first = await run(["a.ts", "b.ts"]);
+		const second = await run(["c.ts", "d.json"]);
+		const third = await run(["e.json", "f.ts"]);
+
+		expect(first.blocks.map((block) => block.filePath)).toEqual(["a.ts"]);
+		expect(second.blocks.map((block) => block.filePath)).toEqual(["d.json"]);
+		expect(third.blocks).toEqual([]);
+
+		resetPostEditNotConfiguredCache(cache);
+		const afterReset = await run(["g.ts"]);
+		expect(afterReset.blocks.map((block) => block.filePath)).toEqual(["g.ts"]);
+	});
+
+	it("#given a decision tool #when repeated edits hit a missing server #then every edit keeps the guidance", async () => {
+		const cache = createPostEditNotConfiguredCache();
+		const run = (filePath: string) =>
+			collectPostEditDiagnostics({
+				filePaths: [filePath],
+				cache,
+				runDiagnostics: async () => notInstalled("typescript", { installDecisionTool: true }),
+				locateFile: at("project"),
+			});
+
+		expect((await run("a.ts")).blocks).toHaveLength(1);
+		expect((await run("b.ts")).blocks).toHaveLength(1);
+	});
+
+	for (const decision of ["declined", "allowed"] as const) {
+		it(`#given a recorded ${decision} decision #when edits repeat anywhere #then that branch's text is unchanged every time`, async () => {
+			const cache = createPostEditNotConfiguredCache();
+			const text = `LSP server 'typescript' ${decision} branch text`;
+			const outcomes: PostEditFileLocation[] = ["project", "outside_project", "project"];
+			const blocks: string[] = [];
+			for (const location of outcomes) {
+				const result = await collectPostEditDiagnostics({
+					filePaths: ["a.ts"],
+					cache,
+					runDiagnostics: async () => notInstalled("typescript", { decision, text }),
+					locateFile: at(location),
+				});
+				blocks.push(...result.blocks.map((block) => block.diagnostics));
+			}
+
+			expect(blocks).toEqual([text, text, text]);
+		});
+	}
+
+	it("#given no file locator #when a missing server is reported #then the full guidance is kept", async () => {
+		const result = await collectPostEditDiagnostics({
+			filePaths: ["a.ts"],
+			runDiagnostics: async () => notInstalled("typescript"),
+		});
+
+		expect(result.blocks).toEqual([{ filePath: "a.ts", diagnostics: `${FULL_NUDGE} (typescript)`, blocking: false }]);
+	});
+});

package/packages/lsp-core/src/post-edit/orchestration.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, it } from "bun:test";
+
+import {
+	collectPostEditDiagnostics,
+	createPostEditNotConfiguredCache,
+	resetPostEditNotConfiguredCache,
+} from "./orchestration.js";
+
+describe("collectPostEditDiagnostics", () => {
+	it("#given rendered not_configured text #when the same extension is checked again #then the text is not cached", async () => {
+		const cache = createPostEditNotConfiguredCache();
+		let calls = 0;
+
+		const first = await collectPostEditDiagnostics({
+			filePaths: ["a.foo"],
+			cache,
+			runDiagnostics: async () => {
+				calls += 1;
+				return "No LSP server configured for extension: .foo\n\nordinary text from a renderer";
+			},
+		});
+		const second = await collectPostEditDiagnostics({
+			filePaths: ["b.foo"],
+			cache,
+			runDiagnostics: async () => {
+				calls += 1;
+				return "diagnostic for b.foo";
+			},
+		});
+
+		expect(calls).toBe(2);
+		expect(first.blocks).toEqual([
+			{ filePath: "a.foo", diagnostics: "No LSP server configured for extension: .foo\n\nordinary text from a renderer", blocking: true },
+		]);
+		expect(second.blocks).toEqual([{ filePath: "b.foo", diagnostics: "diagnostic for b.foo", blocking: true }]);
+		expect([...cache.notConfiguredExtensions]).toEqual([]);
+	});
+
+	it("#given duplicate edited paths #when diagnostics run #then first seen paths are processed once and blocks stay ordered", async () => {
+		const calls: string[] = [];
+
+		const result = await collectPostEditDiagnostics({
+			filePaths: ["a.ts", "b.ts", "a.ts", "c.ts"],
+			runDiagnostics: async (filePath: string) => {
+				calls.push(filePath);
+				return filePath === "b.ts" ? "No diagnostics found" : `diagnostic for ${filePath}`;
+			},
+		});
+
+		expect(calls).toEqual(["a.ts", "b.ts", "c.ts"]);
+		expect(result.blocks).toEqual([
+			{ filePath: "a.ts", diagnostics: "diagnostic for a.ts", blocking: true },
+			{ filePath: "c.ts", diagnostics: "diagnostic for c.ts", blocking: true },
+		]);
+	});
+
+	it("#given many edited paths #when diagnostics run #then concurrency is bounded to four and failures isolate", async () => {
+		let active = 0;
+		let maxActive = 0;
+
+		const result = await collectPostEditDiagnostics({
+			filePaths: ["a.ts", "b.ts", "c.ts", "d.ts", "e.ts", "f.ts"],
+			runDiagnostics: async (filePath: string) => {
+				active += 1;
+				maxActive = Math.max(maxActive, active);
+				await Promise.resolve();
+				active -= 1;
+				if (filePath === "c.ts") throw new Error("server exploded");
+				return filePath === "e.ts" ? "No diagnostics found" : `diagnostic for ${filePath}`;
+			},
+		});
+
+		expect(maxActive).toBe(4);
+		expect(result.blocks).toEqual([
+			{ filePath: "a.ts", diagnostics: "diagnostic for a.ts", blocking: true },
+			{ filePath: "b.ts", diagnostics: "diagnostic for b.ts", blocking: true },
+			{ filePath: "c.ts", diagnostics: "server exploded", blocking: true },
+			{ filePath: "d.ts", diagnostics: "diagnostic for d.ts", blocking: true },
+			{ filePath: "f.ts", diagnostics: "diagnostic for f.ts", blocking: true },
+		]);
+	});
+
+	it("#given structured not_configured diagnostics #when cache is reused and reset #then only not_configured is cached", async () => {
+		const cache = createPostEditNotConfiguredCache();
+		const calls: string[] = [];
+		const responses = new Map<string, string | { readonly kind: "not_configured"; readonly extension: string }>([
+			["a.foo", { kind: "not_configured", extension: ".foo" }],
+			["b.foo", "diagnostic should be skipped"],
+			["c.bar", "LSP server 'bar' for .bar is NOT INSTALLED."],
+		]);
+
+		const first = await collectPostEditDiagnostics({
+			filePaths: ["a.foo", "c.bar"],
+			cache,
+			runDiagnostics: async (filePath: string) => {
+				calls.push(filePath);
+				return responses.get(filePath) ?? "No diagnostics found";
+			},
+		});
+
+		expect(calls).toEqual(["a.foo", "c.bar"]);
+		expect(first.blocks).toEqual([{ filePath: "c.bar", diagnostics: "LSP server 'bar' for .bar is NOT INSTALLED.", blocking: true }]);
+
+		const cached = await collectPostEditDiagnostics({
+			filePaths: ["b.foo"],
+			cache,
+			runDiagnostics: async (filePath: string) => {
+				calls.push(filePath);
+				return responses.get(filePath) ?? "No diagnostics found";
+			},
+		});
+
+		expect(cached.blocks).toEqual([]);
+		expect(calls).toEqual(["a.foo", "c.bar"]);
+
+		responses.set("a.foo", "No diagnostics found");
+		resetPostEditNotConfiguredCache(cache);
+		const second = await collectPostEditDiagnostics({
+			filePaths: ["a.foo", "b.foo"],
+			cache,
+			runDiagnostics: async (filePath: string) => {
+				calls.push(filePath);
+				return responses.get(filePath) ?? "No diagnostics found";
+			},
+		});
+
+		expect(second.blocks).toEqual([{ filePath: "b.foo", diagnostics: "diagnostic should be skipped", blocking: true }]);
+		expect(calls).toEqual(["a.foo", "c.bar", "a.foo", "b.foo"]);
+	});
+
+	it("#given non-not_configured failures #when cache is reused #then every failure retries", async () => {
+		const cache = createPostEditNotConfiguredCache();
+		let calls = 0;
+
+		const first = await collectPostEditDiagnostics({
+			filePaths: ["a.foo"],
+			cache,
+			runDiagnostics: async () => {
+				calls += 1;
+				return "LSP server 'foo' for .foo is NOT INSTALLED.";
+			},
+		});
+		const second = await collectPostEditDiagnostics({
+			filePaths: ["b.foo"],
+			cache,
+			runDiagnostics: async () => {
+				calls += 1;
+				throw new Error("daemon unavailable");
+			},
+		});
+
+		expect(calls).toBe(2);
+		expect(first.blocks).toEqual([{ filePath: "a.foo", diagnostics: "LSP server 'foo' for .foo is NOT INSTALLED.", blocking: true }]);
+		expect(second.blocks).toEqual([{ filePath: "b.foo", diagnostics: "daemon unavailable", blocking: true }]);
+		expect([...cache.notConfiguredExtensions]).toEqual([]);
+	});
+});

package/packages/lsp-core/src/post-edit/orchestration.ts

@@ -0,0 +1,205 @@
+import { extname } from "node:path";
+
+import type { PostEditFileLocation } from "./file-location.js";
+import { notInstalledGuidance, type PostEditNotInstalledOutcome } from "./not-installed-guidance.js";
+
+const DEFAULT_MAX_CONCURRENCY = 4;
+const CLEAN_DIAGNOSTICS_TEXT = "No diagnostics found";
+
+export type PostEditDiagnosticsOutcome =
+	| string
+	| {
+			readonly kind: "not_configured";
+			readonly extension: string;
+	  }
+	| PostEditNotInstalledOutcome;
+
+export type DiagnosticsRunner = (filePath: string) => Promise<PostEditDiagnosticsOutcome>;
+
+export interface PostEditDiagnosticsBlock {
+	readonly filePath: string;
+	readonly diagnostics: string;
+	/** False for missing-server guidance: it is feedback for the model, not a defect in the edit. */
+	readonly blocking: boolean;
+}
+
+export interface PostEditDiagnosticsObservation {
+	readonly filePath: string;
+	readonly kind: "block" | "clean" | "not_configured" | "not_installed";
+}
+
+export interface PostEditDiagnosticsResult {
+	readonly blocks: readonly PostEditDiagnosticsBlock[];
+	readonly observations: readonly PostEditDiagnosticsObservation[];
+}
+
+export interface PostEditNotConfiguredCache {
+	readonly notConfiguredExtensions: Set<string>;
+	readonly notInstalledServers: Set<string>;
+}
+
+export interface CollectPostEditDiagnosticsInput {
+	readonly filePaths: readonly string[];
+	readonly runDiagnostics: DiagnosticsRunner;
+	readonly cache?: PostEditNotConfiguredCache;
+	readonly maxConcurrency?: number;
+	readonly locateFile?: (filePath: string) => PostEditFileLocation;
+}
+
+interface IndexedFilePath {
+	readonly index: number;
+	readonly filePath: string;
+}
+
+interface IndexedDiagnostics {
+	readonly index: number;
+	readonly filePath: string;
+	readonly outcome: PostEditDiagnosticsOutcome;
+}
+
+export function createPostEditNotConfiguredCache(): PostEditNotConfiguredCache {
+	return { notConfiguredExtensions: new Set(), notInstalledServers: new Set() };
+}
+
+export function resetPostEditNotConfiguredCache(cache: PostEditNotConfiguredCache): void {
+	cache.notConfiguredExtensions.clear();
+	cache.notInstalledServers.clear();
+}
+
+export async function collectPostEditDiagnostics(
+	input: CollectPostEditDiagnosticsInput,
+): Promise<PostEditDiagnosticsResult> {
+	const cache = input.cache === undefined ? createPostEditNotConfiguredCache() : input.cache;
+	const filePaths = firstSeenDiagnosticTargets(input.filePaths, cache);
+	const results = await runBoundedDiagnostics(filePaths, input.runDiagnostics, input.maxConcurrency);
+	const blocks: PostEditDiagnosticsBlock[] = [];
+	const observations: PostEditDiagnosticsObservation[] = [];
+
+	for (const result of results) {
+		const outcome = result.outcome;
+		const classification =
+			typeof outcome !== "string" && outcome.kind === "not_installed"
+				? classifyNotInstalled(notInstalledGuidance(result.filePath, outcome, cache, input.locateFile))
+				: classifyDiagnostics(outcome);
+		switch (classification.kind) {
+			case "not_installed":
+				observations.push({ filePath: result.filePath, kind: "not_installed" });
+				break;
+			case "clean":
+				observations.push({ filePath: result.filePath, kind: "clean" });
+				break;
+			case "not_configured":
+				cache.notConfiguredExtensions.add(classification.extension);
+				observations.push({ filePath: result.filePath, kind: "not_configured" });
+				break;
+			case "block":
+				blocks.push({ filePath: result.filePath, diagnostics: classification.diagnostics, blocking: true });
+				observations.push({ filePath: result.filePath, kind: "block" });
+				break;
+			case "guidance":
+				blocks.push({ filePath: result.filePath, diagnostics: classification.text, blocking: false });
+				observations.push({ filePath: result.filePath, kind: "block" });
+				break;
+			default: {
+				const exhaustive: never = classification;
+				return exhaustive;
+			}
+		}
+	}
+
+	return { blocks, observations };
+}
+
+function firstSeenDiagnosticTargets(
+	filePaths: readonly string[],
+	cache: PostEditNotConfiguredCache,
+): readonly IndexedFilePath[] {
+	const seen = new Set<string>();
+	const targets: IndexedFilePath[] = [];
+	for (const filePath of filePaths) {
+		if (filePath.length === 0 || seen.has(filePath)) continue;
+		seen.add(filePath);
+		const extension = extensionKey(filePath);
+		if (extension !== undefined && cache.notConfiguredExtensions.has(extension)) continue;
+		targets.push({ index: targets.length, filePath });
+	}
+	return targets;
+}
+
+async function runBoundedDiagnostics(
+	filePaths: readonly IndexedFilePath[],
+	runDiagnostics: DiagnosticsRunner,
+	maxConcurrency: number | undefined,
+): Promise<readonly IndexedDiagnostics[]> {
+	const results: IndexedDiagnostics[] = [];
+	const workerCount = Math.min(Math.max(1, maxConcurrency ?? DEFAULT_MAX_CONCURRENCY), filePaths.length);
+	let nextIndex = 0;
+
+	async function worker(): Promise<void> {
+		for (;;) {
+			const target = filePaths[nextIndex];
+			nextIndex += 1;
+			if (target === undefined) return;
+			results[target.index] = {
+				index: target.index,
+				filePath: target.filePath,
+				outcome: await collectFileDiagnostics(target.filePath, runDiagnostics),
+			};
+		}
+	}
+
+	await Promise.all(Array.from({ length: workerCount }, () => worker()));
+	return results.filter((result) => result !== undefined);
+}
+
+async function collectFileDiagnostics(
+	filePath: string,
+	runDiagnostics: DiagnosticsRunner,
+): Promise<PostEditDiagnosticsOutcome> {
+	try {
+		return normalizeDiagnosticsOutcome(await runDiagnostics(filePath));
+	} catch (error) {
+		if (error instanceof Error) return formatDiagnosticsError(error);
+		return normalizeDiagnosticsText(String(error));
+	}
+}
+
+function normalizeDiagnosticsOutcome(outcome: PostEditDiagnosticsOutcome): PostEditDiagnosticsOutcome {
+	if (typeof outcome === "string") return normalizeDiagnosticsText(outcome);
+	if (outcome.kind === "not_installed") return { ...outcome, text: normalizeDiagnosticsText(outcome.text) };
+	return outcome;
+}
+
+function classifyNotInstalled(
+	guidance: string | undefined,
+): { readonly kind: "not_installed" } | { readonly kind: "guidance"; readonly text: string } {
+	return guidance === undefined ? { kind: "not_installed" } : { kind: "guidance", text: guidance };
+}
+
+function normalizeDiagnosticsText(text: string): string {
+	return text.trim();
+}
+
+function formatDiagnosticsError(error: Error): string {
+	const message = normalizeDiagnosticsText(error.message);
+	return message.length > 0 ? message : normalizeDiagnosticsText(String(error));
+}
+
+function classifyDiagnostics(
+	outcome: Exclude<PostEditDiagnosticsOutcome, PostEditNotInstalledOutcome>,
+):
+	| { readonly kind: "clean" }
+	| { readonly kind: "not_configured"; readonly extension: string }
+	| { readonly kind: "block"; readonly diagnostics: string } {
+	if (typeof outcome !== "string") {
+		return { kind: "not_configured", extension: outcome.extension };
+	}
+	const diagnostics = outcome;
+	if (diagnostics.length === 0 || diagnostics === CLEAN_DIAGNOSTICS_TEXT) return { kind: "clean" };
+	return { kind: "block", diagnostics };
+}
+
+function extensionKey(filePath: string): string | undefined {
+	const extension = extname(filePath).toLowerCase();
+	return extension.length === 0 ? undefined : extension;
+}