Merge pull request #87 from nyaomaru/fix/preserve-custom-release-note

fix(changelog): preserve custom release-note sections like "What's New"

Author: nyaomaru

src/utils/llm-output.ts

@@ -206,7 +206,8 @@ async function buildOutputFromReleaseNotes(
   } = params;
 
   const parsedRelease = parseReleaseNotes(releaseBody, { owner, repo });
-  if (!parsedRelease.items.length) return null;
+  const hasAdditionalSections = Boolean(parsedRelease.sections?.length);
+  if (!parsedRelease.items.length && !hasAdditionalSections) return null;
 
   fallbackReasons.push(
     'Used GitHub Release Notes as the source (no model call)',
@@ -222,11 +223,14 @@ async function buildOutputFromReleaseNotes(
   });
 
   const titlesForLLM = buildTitlesForClassification(parsedRelease.items);
-  let categories = await classifyTitles(titlesForLLM, provider.name);
-  // Mark that an LLM was used when classification ran with a valid provider key.
-  aiUsed = aiUsed || hasProviderKey;
-  // Heuristic tuning: ensure typing/contract corrections are grouped under Fixed.
-  categories = tuneCategoriesByTitle(parsedRelease.items, categories);
+  let categories: Record<string, string[]> = {};
+  if (titlesForLLM.length) {
+    categories = await classifyTitles(titlesForLLM, provider.name);
+    // Mark AI usage only when classification had input and a provider key is available.
+    aiUsed = aiUsed || hasProviderKey;
+    // Heuristic tuning: ensure typing/contract corrections are grouped under Fixed.
+    categories = tuneCategoriesByTitle(parsedRelease.items, categories);
+  }
 
   const section = buildSectionFromRelease({
     version,

src/utils/release.ts

@@ -17,6 +17,8 @@ const PR_URL_RE = /https?:\/\/\S+\/pull\/(\d+)/; // captures PR number
 const PR_REF_RE = /\(#?(\d+)\)|#(\d+)/; // (#123) or #123
 const AUTHOR_RE = /@([A-Za-z0-9_-]+)/;
 const TRAILING_BY_IN_RE = /\s*(by|in)\s*$/i; // strip noisy trailing tokens
+const TYPOGRAPHIC_APOSTROPHE_RE = /[’`´]/g;
+const COLLAPSE_WHITESPACE_RE = /\s+/g;
 
 /** GitHub repository owner/name pair used for compare link construction. */
 type RepoInfo = {
@@ -130,6 +132,42 @@ function collectH2Sections(body: string): RawSection[] {
   return sections;
 }
 
+/**
+ * Normalize heading text to compare release-note section names robustly.
+ * WHY: Users often edit release notes with typographic apostrophes or inconsistent spacing.
+ * @param heading Raw heading content.
+ * @returns Normalized heading for case-insensitive matching.
+ */
+function normalizeHeading(heading: string): string {
+  return heading
+    .trim()
+    .toLowerCase()
+    .replace(TYPOGRAPHIC_APOSTROPHE_RE, "'")
+    .replace(COLLAPSE_WHITESPACE_RE, ' ');
+}
+
+/**
+ * Check whether an H2 heading refers to the canonical "What's Changed" section.
+ * @param heading Heading text without markdown markers.
+ * @returns True when the heading is a "What's Changed" variant.
+ */
+function isWhatsChangedHeading(heading: string): boolean {
+  const normalizedHeading = normalizeHeading(heading);
+  return (
+    normalizedHeading.startsWith("what's changed") ||
+    normalizedHeading.startsWith('whats changed')
+  );
+}
+
+/**
+ * Check whether an H2 heading is the "Full Changelog" block.
+ * @param heading Heading text without markdown markers.
+ * @returns True when the heading denotes the full changelog section.
+ */
+function isFullChangelogHeading(heading: string): boolean {
+  return normalizeHeading(heading).startsWith('full changelog');
+}
+
 /**
  * Collect the bullet lines under the provided "What's Changed" section lines.
  * @param lines Section content lines following the heading.
@@ -139,7 +177,7 @@ function parseWhatsChangedLines(lines: string[]): string[] {
   const collected: string[] = [];
   for (const rawLine of lines) {
     const line = rawLine.trim();
-    if (!line || /Full Changelog/i.test(line)) continue;
+    if (!line || FULL_CHANGELOG_RE.test(line)) continue;
     collected.push(line);
   }
   return collected;
@@ -216,23 +254,26 @@ export function parseReleaseNotes(
   if (!body) return { items };
 
   const h2Sections = collectH2Sections(body);
-  const whatsChangedSection = h2Sections.find((section) =>
-    /^What's Changed/i.test(section.heading),
-  );
-  const whatsChangedLines = whatsChangedSection
-    ? parseWhatsChangedLines(whatsChangedSection.lines)
-    : [];
+  const whatsChangedLines = h2Sections
+    .filter((section) => isWhatsChangedHeading(section.heading))
+    .flatMap((section) => parseWhatsChangedLines(section.lines));
 
   for (const line of whatsChangedLines) {
     const item = parseReleaseLine(line, repo);
     if (item) items.push(item);
   }
 
+  const seenSections = new Set<string>();
   for (const section of h2Sections) {
-    if (/^What's Changed/i.test(section.heading)) continue;
-    if (/^Full Changelog/i.test(section.heading)) continue;
+    if (isWhatsChangedHeading(section.heading)) continue;
+    if (isFullChangelogHeading(section.heading)) continue;
     const structured = toReleaseSection(section);
-    if (structured) additionalSections.push(structured);
+    if (!structured) continue;
+
+    const sectionKey = `${normalizeHeading(structured.heading)}\n${structured.body.trim()}`;
+    if (seenSections.has(sectionKey)) continue;
+    seenSections.add(sectionKey);
+    additionalSections.push(structured);
   }
 
   const fullChangelog = extractFullChangelog(body, repo);

tests/utils/llm-output.test.ts

@@ -83,4 +83,73 @@ describe('llm-output', () => {
     expect(result.llm.new_section_markdown).toContain('### Added');
     expect(result.llm.new_section_markdown).toContain('- Add feature');
   });
+
+  test('preserves custom release-note sections when no items are parsed', async () => {
+    const whatsNewHeading = 'What\u2019s New \u{1F680}';
+    const result = await buildChangelogLlmOutput({
+      owner: 'octo',
+      repo: 'repo',
+      version: '1.0.0',
+      date: '2024-01-01',
+      releaseRef: 'v1.0.0',
+      prevRef: 'v0.9.0',
+      releaseBody: [
+        `## ${whatsNewHeading}`,
+        'Introduces the `assert` helper and usage examples.',
+        '',
+        '**Full Changelog**: v0.9.0...v1.0.0',
+      ].join('\n'),
+      existingChangelog: '',
+      commitList: [],
+      prs: '',
+      prMapBySha: {},
+      titleToPr: {},
+      provider: mockProvider,
+      hasProviderKey: false,
+      token: undefined,
+    });
+
+    expect(result.fallbackReasons).toContain(
+      'Used GitHub Release Notes as the source (no model call)',
+    );
+    expect(result.llm.new_section_markdown).toContain(
+      '## [v1.0.0] - 2024-01-01',
+    );
+    expect(result.llm.new_section_markdown).toContain(`### ${whatsNewHeading}`);
+    expect(result.llm.new_section_markdown).toContain(
+      'Introduces the `assert` helper and usage examples.',
+    );
+    expect(result.llm.new_section_markdown).toContain(
+      '**Full Changelog**: https://github.com/octo/repo/compare/v0.9.0...v1.0.0',
+    );
+  });
+
+  test('keeps fallback note when provider key exists but release notes have no items', async () => {
+    const result = await buildChangelogLlmOutput({
+      owner: 'octo',
+      repo: 'repo',
+      version: '1.0.0',
+      date: '2024-01-01',
+      releaseRef: 'v1.0.0',
+      prevRef: 'v0.9.0',
+      releaseBody: [
+        '## What\u2019s New',
+        'User-facing highlights only.',
+        '',
+        '**Full Changelog**: v0.9.0...v1.0.0',
+      ].join('\n'),
+      existingChangelog: '',
+      commitList: [],
+      prs: '',
+      prMapBySha: {},
+      titleToPr: {},
+      provider: mockProvider,
+      hasProviderKey: true,
+      token: undefined,
+    });
+
+    expect(result.aiUsed).toBe(false);
+    expect(result.llm.pr_body).toContain('Generated without LLM');
+    expect(result.llm.new_section_markdown).toContain('### What\u2019s New');
+  });
 });

tests/utils/release.test.ts

@@ -36,6 +36,44 @@ describe('release utils', () => {
     });
   });
 
+  test('parseReleaseNotes preserves custom sections and handles typographic headings', () => {
+    const whatsNewHeading = 'What\u2019s New \u{1F680}';
+    const body = [
+      '# v1.2.0',
+      '',
+      `## ${whatsNewHeading}`,
+      'Includes user-facing highlights and examples.',
+      '',
+      '## What\u2019s Changed',
+      '- feat: Add assert helper by @alice in #321',
+      '',
+      `## ${whatsNewHeading}`,
+      'Includes user-facing highlights and examples.',
+      '',
+      '## Migration Notes',
+      'No migration steps required.',
+      '',
+      '**Full Changelog**: v1.1.13...v1.2.0',
+    ].join('\n');
+
+    const parsed = parseReleaseNotes(body, { owner: 'acme', repo: 'repo' });
+    expect(parsed.items).toHaveLength(1);
+    expect(parsed.items[0].title).toBe('Add assert helper');
+    expect(parsed.sections).toEqual([
+      {
+        heading: whatsNewHeading,
+        body: 'Includes user-facing highlights and examples.',
+      },
+      {
+        heading: 'Migration Notes',
+        body: 'No migration steps required.',
+      },
+    ]);
+    expect(parsed.fullChangelog).toBe(
+      'https://github.com/acme/repo/compare/v1.1.13...v1.2.0',
+    );
+  });
+
   test('buildSectionFromRelease formats bullets with author and PR link', () => {
     const items = [
       {