fix(release): absorb mislabeled unreleased version sections when stamping MIGRATION.md (#1667)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: FelixTJDietrich

scripts/sync-release-version.test.ts

@@ -1,6 +1,6 @@
 import assert from "node:assert/strict";
 import { execFile } from "node:child_process";
-import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { mkdir, mkdtemp, readFile, readdir, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import test from "node:test";
@@ -21,9 +21,11 @@ void test("synchronizes every release-owned version reference", async () => {
 		join(cwd, "README.md"),
 		"```bash\n  VERSION=0.74.0 # the release you are installing\n```\n",
 	);
+	// v0.76.0 and v0.75.0 are mislabeled hand-written sections for unreleased work (the released
+	// history starts at v0.74.0) — the exact shape that broke the Version PR on main.
 	await writeFile(
 		join(cwd, "MIGRATION.md"),
-		"### Next release\n\n#### 🔴 Existing action\n\nDo it.\n\n### v0.74.0\n\nOld.\n",
+		"### Next release\n\n#### 🔴 Existing action\n\nDo it.\n\n### v0.76.0\n\n#### 🔴 Mislabeled newer action\n\nFold me.\n\n### v0.75.0\n\n#### 🔴 Mislabeled same-version action\n\nFold me too.\n\n### v0.74.0\n\nOld.\n",
 	);
 	await writeFile(
 		join(cwd, ".migration/z-last.md"),
@@ -42,29 +44,35 @@ void test("synchronizes every release-owned version reference", async () => {
 		await readFile(join(cwd, "README.md"), "utf8"),
 		"```bash\n  VERSION=0.75.0 # the release you are installing\n```\n",
 	);
-	assert.equal(
-		await readFile(join(cwd, "MIGRATION.md"), "utf8"),
-		"### Next release\n\n### v0.75.0\n\n#### 🔴 Existing action\n\nDo it.\n\n#### 🔴 A action\n\nDo A.\n\n#### 🔴 Z action\n\nDo Z: keep `$$VAR`, `$&`, and `$'` literal.\n\n### v0.74.0\n\nOld.\n",
-	);
+	const stamped =
+		"### Next release\n\n### v0.75.0\n\n#### 🔴 Existing action\n\nDo it.\n\n#### 🔴 Mislabeled newer action\n\nFold me.\n\n#### 🔴 Mislabeled same-version action\n\nFold me too.\n\n#### 🔴 A action\n\nDo A.\n\n#### 🔴 Z action\n\nDo Z: keep `$$VAR`, `$&`, and `$'` literal.\n\n### v0.74.0\n\nOld.\n";
+	assert.equal(await readFile(join(cwd, "MIGRATION.md"), "utf8"), stamped);
 	assert.deepEqual(await readdir(join(cwd, ".migration")), ["README.md"]);
 
+	// Regeneration re-reads the script's own prior output and must be byte-idempotent.
+	await run(process.execPath, [join(import.meta.dirname, "sync-release-version.ts")], { cwd });
+	assert.equal(await readFile(join(cwd, "MIGRATION.md"), "utf8"), stamped);
+	assert.deepEqual(await readdir(join(cwd, ".migration")), ["README.md"]);
+
+	// A fragment landing between regenerations merges into the same unreleased section.
+	await writeFile(join(cwd, ".migration/late.md"), "#### 🔴 Late action\n");
 	await run(process.execPath, [join(import.meta.dirname, "sync-release-version.ts")], { cwd });
 	assert.equal(
 		await readFile(join(cwd, "MIGRATION.md"), "utf8"),
-		"### Next release\n\n### v0.75.0\n\n#### 🔴 Existing action\n\nDo it.\n\n#### 🔴 A action\n\nDo A.\n\n#### 🔴 Z action\n\nDo Z: keep `$$VAR`, `$&`, and `$'` literal.\n\n### v0.74.0\n\nOld.\n",
+		stamped.replace("\n### v0.74.0", "\n#### 🔴 Late action\n\n### v0.74.0"),
 	);
 	assert.deepEqual(await readdir(join(cwd, ".migration")), ["README.md"]);
 
-	await writeFile(join(cwd, ".migration/late.md"), "#### 🔴 Late action\n");
+	// A same-version heading below released history is a real conflict, not prior output.
+	await writeFile(
+		join(cwd, "MIGRATION.md"),
+		`${await readFile(join(cwd, "MIGRATION.md"), "utf8")}\n### v0.75.0\n\nGhost.\n`,
+	);
 	await assert.rejects(
 		run(process.execPath, [join(import.meta.dirname, "sync-release-version.ts")], { cwd }),
 		/already contains ### v0\.75\.0/,
 	);
-	await rm(join(cwd, ".migration/late.md"));
-	await writeFile(
-		join(cwd, "MIGRATION.md"),
-		`### Next release\n\n${await readFile(join(cwd, "MIGRATION.md"), "utf8")}`,
-	);
+	await writeFile(join(cwd, "MIGRATION.md"), `### Next release\n\n${stamped}`);
 	await assert.rejects(
 		run(process.execPath, [join(import.meta.dirname, "sync-release-version.ts")], { cwd }),
 		/exactly one ### Next release/,

scripts/sync-release-version.ts

@@ -44,18 +44,46 @@ const fragmentFiles = existsSync(fragmentDirectory)
 			.filter((file) => file.endsWith(".md") && file !== "README.md")
 			.toSorted()
 	: [];
-if (pending !== "" || fragmentFiles.length > 0) {
-	if (migration.split("\n").includes(`### v${version}`)) {
+
+// A version can only gain a history section by being released, and `changeset version` computes
+// the lowest unreleased version — so any section for this version or a later one is unreleased
+// content that ships now. Sections directly below the pending anchor whose headings say otherwise
+// (hand-written before fragments existed, or this script's own output when a regeneration re-reads
+// it) are absorbed into the section being stamped instead of failing the release.
+const semverAtLeast = (candidate: string, reference: string): boolean => {
+	const left = candidate.split(".").map(Number);
+	const right = reference.split(".").map(Number);
+	for (let index = 0; index < 3; index += 1) {
+		if ((left[index] ?? 0) !== (right[index] ?? 0)) return (left[index] ?? 0) > (right[index] ?? 0);
+	}
+	return true;
+};
+const regionStart = pendingSections[0]?.index ?? 0;
+let regionLength = pendingSections[0]?.[0]?.length ?? 0;
+const unreleased: string[] = [];
+for (;;) {
+	const tail = migration.slice(regionStart + regionLength);
+	const next = /^### v(\d+\.\d+\.\d+)\n([\s\S]*?)(?=^### |(?![\s\S]))/m.exec(tail);
+	if (!next || next.index !== 0 || !semverAtLeast(next[1] ?? "", version)) break;
+	unreleased.push(next[2]?.trim() ?? "");
+	regionLength += next[0].length;
+}
+
+if (pending !== "" || unreleased.length > 0 || fragmentFiles.length > 0) {
+	const remainder = migration.slice(0, regionStart) + migration.slice(regionStart + regionLength);
+	if (remainder.split("\n").includes(`### v${version}`)) {
 		throw new Error(`sync-release-version: MIGRATION.md already contains ### v${version}`);
 	}
 	const fragments = fragmentFiles.map((file) =>
 		readFileSync(join(fragmentDirectory, file), "utf8").trim(),
 	);
-	const section = ["### Next release", `### v${version}`, pending, ...fragments].filter(Boolean);
+	const section = ["### Next release", `### v${version}`, pending, ...unreleased, ...fragments]
+		.filter(Boolean)
+		.join("\n\n");
+	// Splicing by offset keeps `$&`/`$$` in migration notes literal.
 	writeFileSync(
 		migrationFile,
-		// The replacer is a function so `$&`/`$$` in migration notes stay literal.
-		migration.replace(pendingSections[0]?.[0] ?? "", () => `${section.join("\n\n")}\n\n`),
+		`${migration.slice(0, regionStart)}${section}\n\n${migration.slice(regionStart + regionLength)}`,
 	);
 	for (const file of fragmentFiles) rmSync(join(fragmentDirectory, file));
 }