Skip to content

A self-organizing Obsidian vault that gives AI coding agents persistent memory.

fix: changelog generator no longer accumulates blank lines each release (#193)

jcaruso20201475cc38b4ac
diff --git a/.claude/scripts/tests/generate-changelog.test.ts b/.claude/scripts/tests/generate-changelog.test.ts
index 92c16aa..2b7dbc8 100644
--- a/.claude/scripts/tests/generate-changelog.test.ts
+++ b/.claude/scripts/tests/generate-changelog.test.ts
@@ -15,6 +15,7 @@ import {
pickMarkers,
findLatestOpenFingerprint,
bumpShardYamlVersion,
+ insertChangelogSection,
} from "../../../.github/scripts/generate-changelog.ts";
describe("classifyCommit", () => {
@@ -302,6 +303,62 @@ describe("bumpShardYamlVersion", () => {
});
});
+describe("insertChangelogSection", () => {
+ test("inserts exactly one blank line after the header on first use", () => {
+ const content = "# Changelog\n";
+ const section = "## v1.0.0 — 2026-01-01\n\n### Added\n- first release\n";
+ const out = insertChangelogSection(content, section, "v1.0.0");
+ assert.equal(
+ out,
+ "# Changelog\n\n## v1.0.0 — 2026-01-01\n\n### Added\n- first release\n\n",
+ );
+ });
+
+ test("does not accumulate blank lines across repeated releases", () => {
+ // Regression test: prependToChangelog used to compute the post-header
+ // insertion point correctly but then slice from index 0 up to that
+ // point — which *keeps* every blank line already separating the
+ // header from the first entry — before adding one more of its own.
+ // Each simulated release used to grow the gap by one blank line.
+ let content = "# Changelog\n";
+ for (let i = 1; i <= 5; i++) {
+ const version = `v1.${i}.0`;
+ const section = `## ${version} — 2026-01-0${i}\n\n### Added\n- release ${i}\n`;
+ content = insertChangelogSection(content, section, version);
+ }
+ assert.match(content, /^# Changelog\n\n## v1\.5\.0/);
+ assert.doesNotMatch(content, /\n{3,}## v1\.5\.0/);
+ });
+
+ test("replaces an existing version's section in place instead of duplicating it", () => {
+ const content = [
+ "# Changelog",
+ "",
+ "## v2.0.0 — 2026-02-01",
+ "",
+ "### Added",
+ "- old entry",
+ "",
+ "## v1.0.0 — 2026-01-01",
+ "",
+ "### Added",
+ "- first release",
+ "",
+ ].join("\n");
+ const section = "## v2.0.0 — 2026-02-02\n\n### Added\n- corrected entry\n";
+ const out = insertChangelogSection(content, section, "v2.0.0");
+ assert.match(out, /- corrected entry/);
+ assert.doesNotMatch(out, /- old entry/);
+ assert.match(out, /- first release/);
+ assert.equal((out.match(/## v2\.0\.0/g) ?? []).length, 1);
+ });
+
+ test("falls back to prepending a fresh header when none exists", () => {
+ const out = insertChangelogSection("", "## v1.0.0 — 2026-01-01\n", "v1.0.0");
+ assert.equal(out, "# Changelog\n\n## v1.0.0 — 2026-01-01\n\n");
+ });
+});
+
describe("findLatestOpenFingerprint", () => {
test("returns the highest version without a missing field", () => {
const fp = {
diff --git a/.github/scripts/generate-changelog.ts b/.github/scripts/generate-changelog.ts
index 8fffd48..ad4bf1d 100644
--- a/.github/scripts/generate-changelog.ts
+++ b/.github/scripts/generate-changelog.ts
@@ -125,39 +125,62 @@ export function generateSection(version: string, commits: readonly string[]): st
return lines.join("\n");
}
-function prependToChangelog(section: string, version: string): void {
- const content = readFileSync("CHANGELOG.md", { encoding: "utf-8" });
+/**
+ * Insert a version section into changelog `content`, or replace it in place
+ * if that version's heading already exists. Pure string transform so the
+ * blank-line handling can be regression-tested without touching disk.
+ */
+export function insertChangelogSection(
+ content: string,
+ section: string,
+ version: string,
+): string {
const versionPattern = new RegExp(`^## ${escapeRegex(version)} — .*$`, "m");
+ // The trailing alternative must mean true end-of-string. A bare `$` would
+ // do that too under a non-multiline regex, but this pattern needs the `m`
+ // flag for `^`, and `m` makes `$` match end-of-*line* as well — which let
+ // the lazy `[\s\S]*?` stop right after the heading, leaving the rest of
+ // the section's old body behind on replace.
const existingPattern = new RegExp(
- `^## ${escapeRegex(version)} — [\\s\\S]*?(?=\\n## [^\\n]|$)`,
+ `^## ${escapeRegex(version)} — [\\s\\S]*?(?=\\n## [^\\n]|(?![\\s\\S]))`,
"m",
);
- let newContent: string;
if (versionPattern.test(content)) {
- newContent = content.replace(existingPattern, section.trimEnd());
- } else {
- const header = "# Changelog";
- const idx = content.indexOf(header);
- if (idx === -1) {
- newContent = `${header}\n\n${section}\n${content}`;
- } else {
- let insertAt = idx + header.length;
- while (
- insertAt < content.length &&
- (content[insertAt] === "\n" || content[insertAt] === "\r")
- ) {
- insertAt += 1;
- }
- newContent =
- content.slice(0, insertAt) +
- "\n" +
- section +
- "\n" +
- content.slice(insertAt);
- }
+ return content.replace(existingPattern, section.trimEnd());
}
+ const header = "# Changelog";
+ const idx = content.indexOf(header);
+ if (idx === -1) {
+ return `${header}\n\n${section}\n${content}`;
+ }
+
+ // Find where the existing entries start, skipping past any blank lines
+ // already separating them from the header...
+ let entriesStart = idx + header.length;
+ while (
+ entriesStart < content.length &&
+ (content[entriesStart] === "\n" || content[entriesStart] === "\r")
+ ) {
+ entriesStart += 1;
+ }
+ // ...but slice from right after the header itself, not from entriesStart,
+ // so those skipped blank lines are dropped rather than kept. Re-running
+ // this on an already-generated file must always land on exactly one
+ // blank line, never grow it by one per release.
+ return (
+ content.slice(0, idx + header.length) +
+ "\n\n" +
+ section +
+ "\n" +
+ content.slice(entriesStart)
+ );
+}
+
+function prependToChangelog(section: string, version: string): void {
+ const content = readFileSync("CHANGELOG.md", { encoding: "utf-8" });
+ const newContent = insertChangelogSection(content, section, version);
writeFileSync("CHANGELOG.md", newContent, { encoding: "utf-8" });
}