pi-edit-file 0.2.2 → 0.3.0

package/README.md

@@ -128,10 +128,12 @@ Not-found is the most expensive failure because it is the one models retry blind
 | Typo in one character (`1000` → `1001`) | `closest line 2 (95% similar): "const timeout = 1000;"` |
 | Hand-written `\n` inside a line | `Escaping note: a literal "\n" in a before-line is a backslash followed by "n", not a line break …` |
 | Block occurs more than once in the file | `not unique — the before-block matches at lines 12, 45 (exact match, 2 copies)` + *include more surrounding lines … a line number cannot choose between identical blocks* |
-| Every hunk is a no-op (`before == after`) | `nothing applied — every hunk of this patch is a no-op …, so the file was NOT written` |
+| Every hunk is a no-op (`before == after`) or empty (`@@@` with nothing on either side) | `nothing applied — every hunk of this patch is empty or a no-op …`; inside a batch each one is `SKIPPED — no-op …` / `SKIPPED — empty hunk …` and the rest still applies |
 | No hunk header at all (chain form), a header where the closing delimiter belongs, or an unterminated hunk | the blocks are located in the file and re-emitted as a ready-to-paste numbered skeleton (`NOT UNIQUE` / `NOT FOUND` placeholders when a block cannot be pinned), with the note that a single unique block may start with a bare delimiter line instead of a number |
+| **One hunk whose opening delimiter line was left out** (`old` / delim / `new` / delim) | not called a chain: `the opening delimiter line is missing … Only that first line is missing`, with both legal forms spelled out and no placeholders (24 of 27 rejections in one session were this shape) |
+| Closing delimiter missing inside the patch | the skeleton's preamble says so — `the hunk header is there, but a "@@@" line is missing inside the patch` — instead of claiming the patch opened with content |
 
-Grammar failures get the same treatment as not-found ones: the patch is never applied, and the reply rebuilds the model's own blocks into legal form instead of stopping at a parse error. Not-found failures also include the nearest candidate region with per-line `=` / `≠` markers, and a **ready-to-paste corrected hunk** built from the real file content:
+Grammar failures get the same treatment as not-found ones: the patch is never applied, and the reply rebuilds the model's own blocks into legal form instead of stopping at a parse error. A block that is nowhere in the file is reported with its closest line by similarity (`closest line N (87% similar)`), in both the not-found diagnosis and the rebuilt skeleton. Not-found failures also include the nearest candidate region with per-line `=` / `≠` markers, and a **ready-to-paste corrected hunk** built from the real file content:
 
 ```
 Closest candidate: lines 2-4 — 2 of 3 line(s) match.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-edit-file",
-  "version": "0.2.2",
+  "version": "0.3.0",
   "description": "Block-based atomic file editing for Pi agents: one flat patch string, precise match diagnostics, word-level diff rendering",
   "keywords": [
     "pi-package",

package/src/core.ts

@@ -274,9 +274,10 @@ export function parsePatch(patch: string): Hunk[] {
 			if (hint < 1) throw new EditError("insert-after needs NNN >= 1");
 		}
 
-		if (before.length === 0 && after.length === 0) {
-			throw new EditError(`hunk ${hunks.length + 1} (${hintLabel(hint)}) is empty: both before and after blocks are blank`);
-		}
+		// An empty hunk (both blocks blank — usually a stray delimiter pair after a
+		// terminator) is kept rather than rejected here: inside a batch the tool
+		// skips it with a note, like a no-op, and only a patch that is nothing but
+		// empty/no-op hunks is an error (Nik, 2026-10-08).
 		hunks.push({ hint, before, after, ...(header.insertAfter ? { insertAfter: true } : {}) });
 
 		if (terminated && i < lines.length && lines[i].trim() === "" && i === lines.length - 1) {
@@ -320,7 +321,7 @@ function locateBlock(fileLines: string[], before: string[]): { status: "ok"; lin
 /** Skeleton for a chain patch; fileLines are needed to number the headers.
  * Always returns model-facing text — the file is never written from a chain
  * patch; the model re-emits the skeleton with its own blocks. */
-export function chainSkeleton(patch: string, fileLines: string[]): string {
+export function chainSkeleton(patch: string, fileLines: string[], situation?: string): string {
 	const lines = patch.split("\n");
 	if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
 
@@ -373,7 +374,8 @@ export function chainSkeleton(patch: string, fileLines: string[]): string {
 	}
 
 	const out: string[] = [
-		`the patch opens with content instead of a hunk header, and the chain form ("old ${delimRun} new ${delimRun} old ${delimRun} new") is not legal input — every block needs its own header.`,
+		situation ??
+			`the patch opens with content instead of a hunk header, and the chain form ("old ${delimRun} new ${delimRun} old ${delimRun} new") is not legal input — every block needs its own header.`,
 		`A block that occurs exactly once in the file needs no number: start the patch with a bare "${delimRun}" line.`,
 		"Here is the same edit with the headers filled in — paste your blocks between the header and delimiter lines:",
 		"",
@@ -405,7 +407,15 @@ export function chainSkeleton(patch: string, fileLines: string[]): string {
 				const more = loc.lines.length > 5 ? ` … and ${loc.lines.length - 5} more` : "";
 				headerLine = `<NOT UNIQUE: this before-block matches at lines ${capped.join(", ")}${more} — extend the before-block with surrounding lines to make it unique, then re-emit with the chosen NNN>`;
 			} else {
-				headerLine = `<NOT FOUND: this before-block does not appear in the file (exact, trimmed and whitespace-collapsed matching all failed) — re-read the file and copy the lines exactly>`;
+				// Symmetry with the not-found diagnosis: when the block is nowhere in the
+				// file, name the closest line by similarity too instead of only saying
+				// "re-read the file" (2026-10-08 feedback).
+				const distinctive = before.lines.reduce((best, l) => (l.trim().length > best.trim().length ? l : best), before.lines[0] ?? "");
+				const near = distinctive ? closestLine(fileLines, distinctive, before.hint ?? 1) : undefined;
+				const nearText = near
+					? ` — closest line ${near.index + 1} (${Math.round(near.similarity * 100)}% similar): ${JSON.stringify(near.text)}`
+					: "";
+				headerLine = `<NOT FOUND: this before-block does not appear in the file (exact, trimmed and whitespace-collapsed matching all failed)${nearText} — re-read the file and copy the lines exactly>`;
 			}
 		}
 		out.push(headerLine);
@@ -420,11 +430,42 @@ export function chainSkeleton(patch: string, fileLines: string[]): string {
 	out.push(
 		`Rules: the header is "NNN ${delimRun}" — the line where the old block starts; "+" after the number inserts AFTER that line (inserts only); ` +
 			`inserts have an empty before-block (header line, then the delimiter line, then the new lines); a delete is an empty after-block. ` +
-			`Remove the "<- note" annotations — they are explanations, not patch lines.`,
+			`Replace every "<...>" placeholder (including "<NOT UNIQUE …>" / "<NOT FOUND …>", after fixing that block) with your own lines — the angle brackets are explanations, not patch text.`,
 	);
 	return out.join("\n");
 }
 
+/** A patch that opens with content and holds exactly the delimiter lines of ONE
+ * hunk (its body plus the optional terminator) is not a chain: it is a single
+ * hunk whose opening delimiter line was left out. That shape gets called out
+ * precisely, with both legal forms spelled out and no placeholder skeleton —
+ * the chain-form diagnosis sent the model fixing a problem it did not have, and
+ * 24 of 27 rejections in one session were exactly this (2026-10-08). The
+ * one-delimiter variant of the same shape is accepted by headerlessSingleHunk(). */
+export function openingDelimiterDiagnosis(patch: string): string | null {
+	const lines = patch.split("\n");
+	if (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+	// A numbered header anywhere means the author knows about headers — that is a
+	// mixed/chain patch, and the rebuilt skeleton with real numbers serves it.
+	if (lines.some((line) => HEADER_RE.test(line))) return null;
+
+	const runs = lines.map((line) => delimiterRun(line));
+	const at: number[] = [];
+	for (let i = 0; i < runs.length; i++) if (runs[i] !== null) at.push(i);
+	if (at.length !== 2) return null; // 1 delimiter: accepted; 0 or ≥3: no single-hunk reading
+	const run = runs[at[0]];
+	if (runs[at[1]] !== run) return null; // mixed runs: let the parser complain about that
+	if (!lines.slice(at[1] + 1).every((l) => l.trim() === "")) return null; // content after the 2nd: a chain
+
+	return (
+		`the patch opens with content instead of a hunk header — the opening delimiter line is missing (the blocks themselves are fine).\n` +
+		`A hunk carries that line in front:\n\n` +
+		`${run}\nold lines\n${run}\nnew lines\n${run}\n\n` +
+		`or, with a line-number hint instead of the bare first line:\n\n` +
+		`NNN ${run}\nold lines\n${run}\nnew lines\n${run}\n\n` +
+		`Only that first line is missing — the rest of the patch is already in the right shape.`
+	);
+}
 const exactEq: LineEq = (a, b) => a === b;
 const trimEq: LineEq = (a, b) => a.trim() === b.trim();
 const collapseEq: LineEq = (a, b) => a.replace(/\s+/g, " ").trim() === b.replace(/\s+/g, " ").trim();
@@ -706,6 +747,20 @@ function resolveOne(hunk: Hunk, fileLines: string[], index: number): { ok: Resol
 	const hint = hunk.hint;
 	const kind: HunkKind = hunk.before.length === 0 ? "insert" : hunk.after.length === 0 ? "delete" : "replace";
 
+	// Both blocks blank: nothing to change. The extension skips these inside a
+	// batch, so reaching here means the patch was nothing but skipped hunks.
+	if (isEmptyHunk(hunk)) {
+		return {
+			fail: {
+				index,
+				hint,
+				kind,
+				reason: "empty hunk — no before-block and no after-block, so there is nothing to change (stray delimiter lines?)",
+				detail: "",
+			},
+		};
+	}
+
 	if (hunk.before.length === 0) {
 		if (hint === null) {
 			return {
@@ -1272,6 +1327,12 @@ export function insertTip(resolved: ResolvedHunk[], numbers?: number[], delim =
  * (exact): applying it changes nothing, so it is skipped with a note instead
  * of killing the batch or silently doing busywork. Trim-equal blocks still
  * apply — whitespace normalization is a real change. */
+/** A hunk with nothing on either side — usually stray delimiter lines after a
+ * terminator. Skipped inside a batch; a patch made only of these is an error. */
+export function isEmptyHunk(h: Hunk): boolean {
+	return h.before.length === 0 && h.after.length === 0;
+}
+
 export function isNoOpHunk(h: Hunk): boolean {
 	return h.before.length > 0 && h.before.length === h.after.length && h.before.every((l, i) => l === h.after[i]);
 }

package/src/extension.ts

@@ -43,6 +43,8 @@ import {
 	reportCaveats,
 	insertTip,
 	appliedLine,
+	openingDelimiterDiagnosis,
+	isEmptyHunk,
 } from "./core.ts";
 
 const TOOL_NAME = "edit_file";
@@ -165,30 +167,45 @@ export default function editFileExtension(pi: { registerTool: (t: unknown) => vo
 					// blocks on. Without one (only "NNN @@@" headers, no standalone
 					// delimiter line) its fallback text is the generic "no delimiter
 					// found" — then the precise diagnosis alone is more useful.
-					const grammarError = err.code === "content-start" || err.code === "missing-separator" || err.code === "unterminated";
-					if (grammarError && (err.code === "content-start" || patchDelimiter(params.patch) !== null)) {
-						const skeleton = chainSkeleton(params.patch, readLines(absPath).lines);
-						const diagnosis = err.code === "content-start" ? "" : `${err.message}\n\n`;
-						throw new EditError(`patch rejected — nothing was written to the file.\n${diagnosis}${skeleton}`);
+					// A patch that opens with content gets a reply built from its own
+					// blocks. When it is ONE hunk missing only its opening delimiter line
+					// (the shape models reach for again and again), the diagnosis is
+					// precise and placeholder-free; a real chain gets the rebuilt skeleton.
+					if (err.code === "content-start") {
+						const precise = openingDelimiterDiagnosis(params.patch);
+						const body = precise ?? chainSkeleton(params.patch, readLines(absPath).lines);
+						throw new EditError(`patch rejected — nothing was written to the file.\n${body}`);
+					}
+					// A delimiter line inside the patch is missing: the skeleton is right,
+					// but its preamble must describe THIS failure — it used to claim the
+					// patch opened with content even when the header was there.
+					const delim = patchDelimiter(params.patch);
+					if ((err.code === "missing-separator" || err.code === "unterminated") && delim !== null) {
+						const situation = `the hunk header is there, but a "${delim}" line is missing inside the patch — every block needs its closing "${delim}" line.`;
+						const skeleton = chainSkeleton(params.patch, readLines(absPath).lines, situation);
+						throw new EditError(`patch rejected — nothing was written to the file.\n${err.message}\n\n${skeleton}`);
 					}
 					throw new EditError(`patch rejected — nothing was written to the file.\n${err.message}`);
 				}
 				throw err;
 			}
 
-			// No-op hunks (before == after, exact) carry no change at all. Inside a
-			// batch each is skipped with a loud note; a patch made ONLY of them is
-			// rejected — such a patch means the author copied the wrong lines, and
-			// that signal must never come back as a success (Nik, 2026-10-02).
+			// Hunks that change nothing are skipped inside a batch, each with a loud
+			// note: no-ops (before == after) and empty ones (both blocks blank, usually
+			// stray delimiter lines after a terminator — one such hunk used to reject
+			// the whole batch). A patch made ONLY of them is rejected: that patch means
+			// the author copied the wrong lines, and such a signal must never come back
+			// as a success (Nik, 2026-10-02).
 			const active: Array<{ hunk: Hunk; origIndex: number }> = [];
 			const noOpNotes: string[] = [];
 			parsed.forEach((h, i) => {
-				if (isNoOpHunk(h)) noOpNotes.push(`hunk ${i + 1}: SKIPPED — no-op (the old block equals the new block); this hunk changes nothing`);
+				if (isEmptyHunk(h)) noOpNotes.push(`hunk ${i + 1}: SKIPPED — empty hunk (no old block, no new block); this hunk changes nothing`);
+				else if (isNoOpHunk(h)) noOpNotes.push(`hunk ${i + 1}: SKIPPED — no-op (the old block equals the new block); this hunk changes nothing`);
 				else active.push({ hunk: h, origIndex: i });
 			});
 			if (active.length === 0) {
 				throw new EditError(
-					`nothing applied — every hunk of this patch is a no-op (the old block equals the new block), so the file was NOT written.\n` +
+					`nothing applied — every hunk of this patch is empty or a no-op (it changes nothing), so the file was NOT written.\n` +
 						`${noOpNotes.join("\n")}\n` +
 						`Check that the old block is the text you mean to replace, and that the new block differs from it.`,
 				);