pi-mono-all 1.0.0

package/node_modules/pi-mono-multi-edit/README.md

@@ -0,0 +1,244 @@
+# Multi-Edit — Enhanced Edit Tool
+
+A pi extension that replaces the built-in `edit` tool with a more powerful version that supports **batch edits** across multiple files and **Codex-style patch payloads** — all validated against a virtual filesystem before any real changes are written.
+
+## Origins
+
+Initially derived from [mitsuhiko/agent-stuff](https://github.com/mitsuhiko/agent-stuff)'s `pi-extensions/multi-edit.ts`. The substrate has since been substantially rewritten — the patch engine is now a recursive-descent parser over a line cursor with `indexOf`-based hunk anchoring, the diff renderer is a two-pass design, and the classic edit path gained atomic multi-file rollback, eager write-permission preflight, curly-quote fallback matching, a read-cache backed workspace, and `context-guard:file-modified` event integration. Shape-level divergences (notably the `Hunk { oldBlock, newBlock }` shape vs upstream's `UpdateChunk { oldLines[], newLines[] }`) and dropped compatibility corners are documented below.
+
+## Overview
+
+The standard `edit` tool handles one `oldText → newText` replacement at a time. Multi-Edit extends it with three modes so an agent can make many targeted changes in a single tool call, dramatically reducing round-trips and the risk of partial edits leaving the codebase in an inconsistent state.
+
+All modes run a **preflight pass** on a virtual (in-memory) copy of the filesystem first. If any replacement fails, no real files are touched.
+
+## Modes
+
+### 1. Single (classic)
+
+Identical to the built-in `edit` tool. Provide `path`, `oldText`, and `newText`.
+
+```jsonc
+{
+  "path": "src/index.ts",
+  "oldText": "const foo = 1;",
+  "newText": "const foo = 2;",
+}
+```
+
+### 2. Multi (batch array)
+
+Pass a `multi` array of edit objects. Each item has `path`, `oldText`, and `newText`. A top-level `path` can be set as a default that individual items inherit when they omit their own `path`.
+
+```jsonc
+{
+  "path": "src/utils.ts", // inherited by items that omit path
+  "multi": [
+    {
+      "oldText": "import foo from 'foo';",
+      "newText": "import foo from '@scope/foo';",
+    },
+    {
+      "path": "src/other.ts", // overrides the top-level path
+      "oldText": "const bar = 0;",
+      "newText": "const bar = 42;",
+    },
+  ],
+}
+```
+
+You can also mix a top-level single edit with `multi` — the top-level edit is prepended as the first item in the batch:
+
+```jsonc
+{
+  "path": "src/index.ts",
+  "oldText": "version: 1",
+  "newText": "version: 2",
+  "multi": [{ "oldText": "// old comment", "newText": "// new comment" }],
+}
+```
+
+### 3. Patch (Codex-style)
+
+Pass a `patch` string delimited by `*** Begin Patch` / `*** End Patch`. This format supports adding, deleting, and updating files with hunk-based diffs — similar to the patch format used by OpenAI Codex.
+
+```
+*** Begin Patch
+*** Add File: src/new-file.ts
++export const greeting = "hello";
+*** Delete File: src/deprecated.ts
+*** Update File: src/existing.ts
+@@ function oldName() {
+-function oldName() {
++function newName() {
+*** End Patch
+```
+
+**Supported operations inside a patch:**
+
+| Header                    | Effect                                                              |
+| ------------------------- | ------------------------------------------------------------------- |
+| `*** Add File: <path>`    | Creates (or overwrites) the file with `+`-prefixed lines as content |
+| `*** Delete File: <path>` | Removes the file (errors if it doesn't exist)                       |
+| `*** Update File: <path>` | Applies one or more `@@`-delimited hunks to the file                |
+
+> **Note:** `*** Move to:` (rename) operations are not supported and will throw an error.
+
+#### Codex apply_patch compatibility
+
+The patch engine implements a pragmatic subset of the Codex `apply_patch` format. The following edge cases are intentionally **not** supported and raise a parse error instead of degrading silently:
+
+| Feature                           | Status    | Notes                                                                                     |
+| --------------------------------- | --------- | ----------------------------------------------------------------------------------------- |
+| `@@` hunk header                  | Required  | Every hunk inside an `*** Update File:` block must start with `@@`                        |
+| Trailing-whitespace tolerance     | Supported | Hunks fall back to per-line `trimEnd` matching when exact `indexOf` misses                |
+| Full trim / unicode-normalized    | Dropped   | Only `trimEnd` is supported — normalize curly quotes or dashes in the patch before sending |
+| `*** End of File` sentinel hunks  | Dropped   | Use a normal hunk anchored on the last real line                                          |
+| `*** Move to:` rename             | Rejected  | Emit an Add + Delete pair instead                                                         |
+
+These restrictions keep the parser simpler and more predictable than a full 4-pass fuzzy matcher while still catching the most common class of whitespace mismatch.
+
+## Key Features
+
+### Preflight Validation
+
+Before writing a single byte to disk, every edit is applied to a virtual (in-memory) snapshot of the affected files. If any replacement fails — wrong `oldText`, file not found, missing context — the entire operation is aborted and no real files are modified. The preflight also checks write permissions against the real filesystem, so read-only targets fail fast before any virtual apply is attempted.
+
+### Atomic Multi-File Rollback
+
+When a classic batch spans multiple files, the applier snapshots each file's pre-edit content before writing it. If a later file in the batch fails mid-write, every file already written is restored from its snapshot on a best-effort basis — the original failure is still surfaced, but the filesystem ends up in its pre-batch state.
+
+### Positional Ordering for Same-File Edits
+
+When multiple edits target the same file, they are automatically sorted by their position in the **original** file content (top-to-bottom). This ensures the forward-search cursor works correctly regardless of the order the model listed the edits.
+
+### Quote-Normalized Matching for Classic Edits
+
+Classic `oldText` lookups escalate through an ordered list of normalizer passes applied to both `oldText` and file content. The first pass that locates the transformed string wins:
+
+1. **Exact** — character-for-character match
+2. **Curly → straight quotes** — `'` / `'` / `"` / `"` in the model's `oldText` are rewritten to ASCII before the second search
+3. **Trailing whitespace tolerance** — per-line `trimEnd` on both sides catches the most frequent class of mismatch (model generates trailing spaces the file doesn't have, or vice versa)
+
+Extending the chain is a matter of appending another normalizer to the `MATCH_PASSES` array in `classic.ts`.
+
+Patch `@@` hunks also support a `trimEnd` fallback — when the exact `indexOf` misses, the applier retries with per-line trailing-whitespace stripping on both the hunk and the file content.
+
+### Redundant Edit Detection
+
+If the same `oldText → newText` pair appears more than once in a `multi` batch for the same file (e.g. the model over-counted occurrences), subsequent duplicates are skipped gracefully with a success status rather than raising an error.
+
+### Diff Generation
+
+Every successful edit returns a unified diff attached to the tool result so the agent and user can inspect exactly what changed. For multi-file operations, per-file diffs are concatenated. The first changed line number is also surfaced for UI scrolling.
+
+### Path Inheritance
+
+In `multi` mode, items that omit `path` automatically inherit the top-level `path`. This is convenient when most edits target a single file with one or two exceptions.
+
+## Parameters
+
+| Parameter | Type                    | Description                                                                                                  |
+| --------- | ----------------------- | ------------------------------------------------------------------------------------------------------------ |
+| `path`    | `string` (optional)     | Target file path (absolute or relative to cwd). Serves as default for `multi` items.                         |
+| `oldText` | `string` (optional)     | Exact text to find and replace. Must match including all whitespace.                                         |
+| `newText` | `string` (optional)     | Replacement text.                                                                                            |
+| `multi`   | `EditItem[]` (optional) | Array of `{ path?, oldText, newText }` objects for batch mode.                                               |
+| `patch`   | `string` (optional)     | Codex-style patch payload (`*** Begin Patch … *** End Patch`). Mutually exclusive with all other parameters. |
+
+**`EditItem` shape:**
+
+```ts
+{
+  path?: string;   // inherits top-level path if omitted
+  oldText: string;
+  newText: string;
+}
+```
+
+## Dependencies
+
+| Package                         | Role                                                |
+| ------------------------------- | --------------------------------------------------- |
+| `@mariozechner/pi-coding-agent` | `ExtensionAPI` type and tool registration           |
+| `@sinclair/typebox`             | Runtime JSON Schema / TypeBox parameter definitions |
+| `diff`                          | Line-level diff generation for result output        |
+
+## Error Handling
+
+| Situation                                                            | Behaviour                                              |
+| -------------------------------------------------------------------- | ------------------------------------------------------ |
+| `patch` used together with `path`/`oldText`/`newText`/`multi`        | Throws immediately — parameters are mutually exclusive |
+| Incomplete top-level edit (e.g. `path` + `oldText` but no `newText`) | Throws listing the missing fields                      |
+| `multi` item missing `path` and no top-level `path` set              | Throws identifying which item is affected              |
+| `oldText` not found in file                                          | Preflight throws; no files are modified                |
+| `patch` context line not found                                       | Preflight throws; no files are modified                |
+| File does not exist or is not writable                               | Throws before any mutations                            |
+| Patch `*** Move to:` operation                                       | Throws — not supported                                 |
+
+## Performance vs Base Edit
+
+Measured across 38 real pi sessions (81 JSONL files) using `npm run bench -- --from-session --all`. Sessions are auto-classified: **base** = only single `path/oldText/newText` calls; **multi-edit** = uses `multi` or `patch` at least once.
+
+### Headline Numbers
+
+| Metric              |  Base | Multi-Edit |       Delta |
+| ------------------- | ----: | ---------: | ----------: |
+| Sessions            |    22 |         16 |             |
+| Tool calls          |    92 |        137 |             |
+| Logical edits       |    92 |        247 |             |
+| Edits / tool call   |  1.00 |       1.80 |       +0.80 |
+| Failure rate        |  6.5% |       6.6% |     +0.0 pp |
+| P50 duration        |  7 ms |      11 ms |             |
+| P95 duration        | 31 ms |      25 ms |             |
+| Cost / logical edit | $0.29 |      $0.17 |      -41.8% |
+| Calls saved vs base |     — |        110 | 44.5% fewer |
+
+### What the data says
+
+**Wins:**
+
+- **Cost per edit drops 42%**. Batching N edits into one tool call avoids N-1 round-trips of assistant→tool→assistant, each of which carries the full conversation context as input tokens. At $0.17 vs $0.29 per logical edit, multi-edit pays for itself on any batch ≥ 2.
+- **44.5% fewer tool calls**. 110 hypothetical round-trips eliminated. This is time the model spends re-reading its own context, waiting for tool dispatch, and generating boilerplate tool-call framing — all wasted.
+- **P95 latency is lower** (25 ms vs 31 ms). The preflight + read cache avoids wasted disk I/O on doomed edits, and the cache deduplicates reads when multiple edits touch the same file.
+
+**Neutral / watch items:**
+
+- **P50 latency is slightly higher** (11 ms vs 7 ms). Expected: multi-edit does a full preflight pass before the real write. The delta is negligible per-edit (~2 ms extra for the safety guarantee).
+
+### Mode Breakdown (pre-v1.5.1)
+
+| Mode   | Calls |   % | Failure rate |
+| ------ | ----: | --: | -----------: |
+| single |    61 | 45% |         1.6% |
+| patch  |    41 | 30% |         9.8% |
+| multi  |    35 | 25% |        11.4% |
+
+Root-cause analysis of the 8 multi/patch failures showed: 5 were trailing-whitespace mismatches in `oldText`, 2 were batch-poisoned (1 bad edit killed 5 good siblings), and 1 was a legitimate ENOENT. Three fixes shipped in v1.5.1 to address this:
+
+1. **`trimEnd` matching for classic edits** — `findActualString` now tries a per-line `trimEnd` normalization pass on both `oldText` and file content when exact and curly-quote passes miss. Catches the dominant failure class (model generates trailing spaces the file doesn't have, or vice versa).
+2. **Partial success for multi batches** — when one edit in a batch can't be found, the remaining edits are still applied. Failures are reported individually instead of aborting the entire batch. A 6-edit call with 1 bad edit now produces 5 successes + 1 failure instead of 0 + 6.
+3. **`trimEnd` fallback for patch hunks** — the patch applier now falls back to per-line `trimEnd` matching when exact `indexOf` misses, using the same strategy for both `oldBlock` and `contextPrefix` anchors.
+
+**Projected impact:** multi mode failure rate ~11.4% → ~3%, patch mode ~9.8% → ~2.5%. The batch-poisoning fix alone eliminates the inflated failure count — previously a single bad edit in a 6-edit batch counted as 1 failed tool call; now it counts as 1 failed edit + 5 successes.
+
+Multi-edit sessions still use `single` mode 45% of the time — room to push batch adoption via prompt guidelines.
+
+### Running the Benchmark & Analysis
+
+The `benchmark-edits` tool provides two modes: a **synthetic benchmark** that measures engine latency on controlled scenarios, and a **session analysis** mode that parses historical pi session JSONL logs to compute cost, token, failure, and throughput metrics.
+
+```bash
+# Synthetic benchmark — built-in scenarios
+npm run bench
+
+# Custom scenario file (JSON array — see header comment in benchmark-edits.ts)
+npm run bench -- scenarios.json
+
+# Session analysis — all pi sessions
+npm run bench -- --from-session --all
+
+# Specific session files or directories
+npm run bench -- --from-session ~/.pi/agent/sessions/<project-dir>/
+npm run bench -- --from-session session1.jsonl session2.jsonl
+```

package/node_modules/pi-mono-multi-edit/__tests__/classic.test.ts

@@ -0,0 +1,277 @@
+/**
+ * applyClassicEdits — contract tests.
+ *
+ * Pins the classic-edit behavior before Phase C polish. Each test uses its own
+ * tmpdir so they can run in parallel.
+ */
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+import { chmod, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+
+import { applyClassicEdits, findActualString } from "../classic.ts";
+import type { EditItem, Workspace } from "../types.ts";
+import { createRealWorkspace } from "../workspace.ts";
+
+// Stub ExtensionAPI — only `events.emit` is touched by the real workspace.
+const stubPi: ExtensionAPI = {
+	events: { emit: () => {} },
+} as unknown as ExtensionAPI;
+
+async function withTmp<T>(fn: (dir: string) => Promise<T>): Promise<T> {
+	const dir = await mkdtemp(join(tmpdir(), "multi-edit-classic-"));
+	try {
+		return await fn(dir);
+	} finally {
+		await rm(dir, { recursive: true, force: true });
+	}
+}
+
+function makeWorkspace(): Workspace {
+	return createRealWorkspace(stubPi);
+}
+
+describe("applyClassicEdits — single edit", () => {
+	test("replaces oldText with newText", async () => {
+		await withTmp(async (dir) => {
+			const file = join(dir, "a.txt");
+			await writeFile(file, "hello world\n");
+
+			const edits: EditItem[] = [{ path: "a.txt", oldText: "hello", newText: "HI" }];
+			const results = await applyClassicEdits(edits, makeWorkspace(), dir);
+
+			assert.equal(results.length, 1);
+			assert.equal(results[0].success, true);
+			assert.equal(await readFile(file, "utf-8"), "HI world\n");
+		});
+	});
+
+	test("accepts absolute paths", async () => {
+		await withTmp(async (dir) => {
+			const file = join(dir, "abs.txt");
+			await writeFile(file, "foo\n");
+			const edits: EditItem[] = [{ path: file, oldText: "foo", newText: "bar" }];
+			const results = await applyClassicEdits(edits, makeWorkspace(), dir);
+			assert.equal(results[0].success, true);
+			assert.equal(await readFile(file, "utf-8"), "bar\n");
+		});
+	});
+
+	test("returns failure when oldText is not found", async () => {
+		await withTmp(async (dir) => {
+			const file = join(dir, "a.txt");
+			await writeFile(file, "hello world\n");
+			const edits: EditItem[] = [{ path: "a.txt", oldText: "absent", newText: "x" }];
+			await assert.rejects(() => applyClassicEdits(edits, makeWorkspace(), dir), /Could not find the exact text/);
+		});
+	});
+});
+
+describe("applyClassicEdits — multi edit, same file", () => {
+	test("applies two edits listed in bottom-up order (positional reordering)", async () => {
+		await withTmp(async (dir) => {
+			const file = join(dir, "a.txt");
+			await writeFile(file, "aaa\nbbb\nccc\n");
+
+			const edits: EditItem[] = [
+				{ path: "a.txt", oldText: "ccc", newText: "CCC" },
+				{ path: "a.txt", oldText: "aaa", newText: "AAA" },
+			];
+			const results = await applyClassicEdits(edits, makeWorkspace(), dir);
+
+			assert.equal(results.every((r) => r.success), true);
+			assert.equal(await readFile(file, "utf-8"), "AAA\nbbb\nCCC\n");
+		});
+	});
+
+	test("skips redundant duplicate edit when only one occurrence exists", async () => {
+		await withTmp(async (dir) => {
+			const file = join(dir, "a.txt");
+			await writeFile(file, "foo bar\n");
+
+			const edits: EditItem[] = [
+				{ path: "a.txt", oldText: "foo", newText: "FOO" },
+				{ path: "a.txt", oldText: "foo", newText: "FOO" },
+			];
+			const results = await applyClassicEdits(edits, makeWorkspace(), dir);
+
+			assert.equal(results[0].success, true);
+			assert.equal(results[1].success, true);
+			assert.match(results[1].message, /Skipped redundant edit/);
+			assert.equal(await readFile(file, "utf-8"), "FOO bar\n");
+		});
+	});
+});
+
+describe("applyClassicEdits — multi edit, multiple files", () => {
+	test("applies edits across two files successfully", async () => {
+		await withTmp(async (dir) => {
+			const a = join(dir, "a.txt");
+			const b = join(dir, "b.txt");
+			await writeFile(a, "alpha\n");
+			await writeFile(b, "beta\n");
+
+			const edits: EditItem[] = [
+				{ path: "a.txt", oldText: "alpha", newText: "ALPHA" },
+				{ path: "b.txt", oldText: "beta", newText: "BETA" },
+			];
+			const results = await applyClassicEdits(edits, makeWorkspace(), dir);
+
+			assert.equal(results.every((r) => r.success), true);
+			assert.equal(await readFile(a, "utf-8"), "ALPHA\n");
+			assert.equal(await readFile(b, "utf-8"), "BETA\n");
+		});
+	});
+
+	test("rolls back first file when second file's edit fails", async () => {
+		await withTmp(async (dir) => {
+			const a = join(dir, "a.txt");
+			const b = join(dir, "b.txt");
+			await writeFile(a, "alpha\n");
+			await writeFile(b, "beta\n");
+
+			const edits: EditItem[] = [
+				{ path: "a.txt", oldText: "alpha", newText: "ALPHA" },
+				{ path: "b.txt", oldText: "NOT_PRESENT", newText: "x" },
+			];
+
+			await assert.rejects(
+				() => applyClassicEdits(edits, makeWorkspace(), dir, undefined, { rollbackOnError: true }),
+				/Could not find the exact text/,
+			);
+
+			// a.txt should be restored; b.txt unchanged
+			assert.equal(await readFile(a, "utf-8"), "alpha\n");
+			assert.equal(await readFile(b, "utf-8"), "beta\n");
+		});
+	});
+});
+
+describe("applyClassicEdits — quote fallback (findActualString)", () => {
+	test("matches curly-quote oldText against straight-quote file content", async () => {
+		await withTmp(async (dir) => {
+			const file = join(dir, "q.txt");
+			// File has straight quotes; model's oldText has curly quotes (common when
+			// model was trained on formatted prose).
+			await writeFile(file, 'say "hello" to the world\n');
+
+			const edits: EditItem[] = [
+				{ path: "q.txt", oldText: "say \u201Chello\u201D", newText: 'SAY "HELLO"' },
+			];
+			const results = await applyClassicEdits(edits, makeWorkspace(), dir);
+			assert.equal(results[0].success, true);
+			assert.equal(await readFile(file, "utf-8"), 'SAY "HELLO" to the world\n');
+		});
+	});
+
+	test("findActualString returns exact match when no normalization is needed", () => {
+		const content = "hello world";
+		const match = findActualString(content, "hello", 0);
+		assert.ok(match);
+		assert.equal(match!.pos, 0);
+		assert.equal(match!.actualOldText, "hello");
+	});
+
+	test("findActualString falls back to curly→straight normalization of oldText", () => {
+		const content = "a 'b' c"; // straight quotes in the file
+		const match = findActualString(content, "a \u2018b\u2019 c", 0);
+		assert.ok(match);
+		assert.equal(match!.pos, 0);
+		// actualOldText is the normalized (straight) form that was actually matched
+		assert.equal(match!.actualOldText, "a 'b' c");
+	});
+
+	test("findActualString returns undefined when no match after normalization", () => {
+		const match = findActualString("nothing here", "missing", 0);
+		assert.equal(match, undefined);
+	});
+});
+
+describe("applyClassicEdits — read-only file", () => {
+	test("rejects before any mutation when target is read-only", async () => {
+		await withTmp(async (dir) => {
+			const file = join(dir, "ro.txt");
+			await writeFile(file, "readonly\n");
+			await chmod(file, 0o444);
+
+			const edits: EditItem[] = [{ path: "ro.txt", oldText: "readonly", newText: "X" }];
+			try {
+				await assert.rejects(() => applyClassicEdits(edits, makeWorkspace(), dir));
+				assert.equal(await readFile(file, "utf-8"), "readonly\n");
+			} finally {
+				await chmod(file, 0o644);
+			}
+		});
+	});
+});
+
+describe("applyClassicEdits — trailing whitespace tolerance", () => {
+	test("matches oldText with trailing spaces when file has none", async () => {
+		await withTmp(async (dir) => {
+			const file = join(dir, "ws.ts");
+			await writeFile(file, "const x = 1;\nconst y = 2;\n");
+
+			const edits: EditItem[] = [
+				{ path: "ws.ts", oldText: "const x = 1;  \nconst y = 2;  \n", newText: "const x = 10;\nconst y = 20;\n" },
+			];
+			const results = await applyClassicEdits(edits, makeWorkspace(), dir);
+			assert.equal(results[0].success, true);
+			assert.equal(await readFile(file, "utf-8"), "const x = 10;\nconst y = 20;\n");
+		});
+	});
+
+	test("findActualString falls back to trimEnd when exact and quote passes miss", () => {
+		const content = "line one\nline two\n";
+		const match = findActualString(content, "line one  \nline two  \n", 0);
+		assert.ok(match, "should find a match via trimEnd normalization");
+		assert.equal(match!.pos, 0);
+	});
+});
+
+describe("applyClassicEdits — continueOnError (partial success)", () => {
+	test("applies successful edits and records failures without aborting", async () => {
+		await withTmp(async (dir) => {
+			const file = join(dir, "partial.ts");
+			await writeFile(file, "aaa\nbbb\nccc\n");
+
+			const edits: EditItem[] = [
+				{ path: "partial.ts", oldText: "aaa", newText: "AAA" },
+				{ path: "partial.ts", oldText: "DOES_NOT_EXIST", newText: "X" },
+				{ path: "partial.ts", oldText: "ccc", newText: "CCC" },
+			];
+			const results = await applyClassicEdits(edits, makeWorkspace(), dir, undefined, {
+				continueOnError: true,
+			});
+
+			assert.equal(results[0].success, true, "first edit should succeed");
+			assert.equal(results[1].success, false, "second edit should fail");
+			assert.equal(results[2].success, true, "third edit should still succeed");
+			assert.equal(await readFile(file, "utf-8"), "AAA\nbbb\nCCC\n");
+		});
+	});
+
+	test("all-or-nothing when continueOnError is false", async () => {
+		await withTmp(async (dir) => {
+			const file = join(dir, "strict.ts");
+			await writeFile(file, "aaa\nbbb\nccc\n");
+
+			const edits: EditItem[] = [
+				{ path: "strict.ts", oldText: "aaa", newText: "AAA" },
+				{ path: "strict.ts", oldText: "DOES_NOT_EXIST", newText: "X" },
+				{ path: "strict.ts", oldText: "ccc", newText: "CCC" },
+			];
+			await assert.rejects(() =>
+				applyClassicEdits(edits, makeWorkspace(), dir, undefined, {
+					continueOnError: false,
+					rollbackOnError: true,
+				}),
+			);
+			// File should be untouched due to rollback.
+			assert.equal(await readFile(file, "utf-8"), "aaa\nbbb\nccc\n");
+		});
+	});
+});

package/node_modules/pi-mono-multi-edit/__tests__/diff.test.ts

@@ -0,0 +1,77 @@
+/**
+ * generateDiffString — contract tests.
+ *
+ * Locks the rendered diff format before Phase C rewrites the renderer.
+ */
+
+import { describe, test } from "node:test";
+import assert from "node:assert/strict";
+
+import { generateDiffString } from "../diff.ts";
+
+describe("generateDiffString", () => {
+	test("returns empty output and undefined firstChangedLine when content is identical", () => {
+		const { diff, firstChangedLine } = generateDiffString("a\nb\nc\n", "a\nb\nc\n");
+		assert.equal(diff, "");
+		assert.equal(firstChangedLine, undefined);
+	});
+
+	test("single-line replacement emits + and - markers with line numbers", () => {
+		const before = "line1\nline2\nline3\n";
+		const after = "line1\nCHANGED\nline3\n";
+		const { diff, firstChangedLine } = generateDiffString(before, after);
+		assert.match(diff, /-2 line2/);
+		assert.match(diff, /\+2 CHANGED/);
+		assert.equal(firstChangedLine, 2);
+	});
+
+	test("shows leading context before a change", () => {
+		const before = "a\nb\nc\nd\nTARGET\n";
+		const after = "a\nb\nc\nd\nREPLACED\n";
+		const { diff } = generateDiffString(before, after, 4);
+		for (const ctx of ["a", "b", "c", "d"]) {
+			assert.ok(diff.includes(` ${ctx}`) || diff.match(new RegExp(`\\s\\d+ ${ctx}`)), `missing context '${ctx}' in:\n${diff}`);
+		}
+	});
+
+	test("firstChangedLine is 1-indexed against the new content", () => {
+		const before = "one\ntwo\nthree\nfour\n";
+		const after = "one\ntwo\nthree\nFOUR\n";
+		const { firstChangedLine } = generateDiffString(before, after);
+		assert.equal(firstChangedLine, 4);
+	});
+
+	test("pads line numbers to the width of the largest line number", () => {
+		const before = Array.from({ length: 12 }, (_, i) => `line${i + 1}`).join("\n") + "\n";
+		const after = before.replace("line6", "CHANGED");
+		const { diff } = generateDiffString(before, after);
+		// 12 lines → 2-char wide line numbers
+		assert.match(diff, /- 6 line6/);
+		assert.match(diff, /\+ 6 CHANGED/);
+	});
+
+	test("collapses large unchanged runs between two changes with '...' marker", () => {
+		const lines: string[] = [];
+		for (let i = 1; i <= 40; i++) lines.push(`line${i}`);
+		const before = lines.join("\n") + "\n";
+		const after = before.replace("line1\n", "FIRST\n").replace("line40", "LAST");
+		const { diff } = generateDiffString(before, after, 4);
+		assert.ok(diff.includes("..."), `expected collapsed marker in:\n${diff}`);
+		assert.match(diff, /-\s?1 line1/);
+		assert.match(diff, /\+\s?1 FIRST/);
+		assert.match(diff, /-40 line40/);
+		assert.match(diff, /\+40 LAST/);
+	});
+
+	test("handles addition-only (empty → content)", () => {
+		const { diff, firstChangedLine } = generateDiffString("", "new line\n");
+		assert.match(diff, /\+1 new line/);
+		assert.equal(firstChangedLine, 1);
+	});
+
+	test("handles deletion-only (content → empty)", () => {
+		const { diff, firstChangedLine } = generateDiffString("gone\n", "");
+		assert.match(diff, /-1 gone/);
+		assert.equal(firstChangedLine, 1);
+	});
+});