feat: add ReleaseNotesTransformer for article API (#61436)

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Kevin Heis <heiskr@users.noreply.github.com>

Author: 3 people

src/article-api/tests/release-notes-transformer.ts

@@ -0,0 +1,187 @@
+import { describe, expect, test, vi } from 'vitest'
+
+import type { Context, GHESReleasePatch, Page } from '@/types'
+import {
+  ReleaseNotesTransformer,
+  renderReleaseNotesMarkdown,
+} from '@/article-api/transformers/release-notes-transformer'
+
+// Mock renderContent so the unit tests don't need fixtures and so we can
+// assert that markdownRequested: true is always threaded through. The mock
+// returns the input unchanged so we can verify the output shape.
+vi.mock('@/content-render/index', () => ({
+  renderContent: vi.fn(async (template: string, ctx: { markdownRequested?: boolean }) => {
+    if (!ctx?.markdownRequested) {
+      throw new Error('renderContent was called without markdownRequested: true')
+    }
+    return template
+  }),
+}))
+
+// Mock the release notes loader so the unit tests don't depend on fixtures
+// existing on disk. Returns empty data, which makes the "release not found"
+// branch in transform() the deterministic outcome.
+vi.mock('@/release-notes/middleware/get-release-notes', () => ({
+  getReleaseNotes: vi.fn(() => ({})),
+}))
+
+const makeContext = (overrides: Partial<Context> = {}): Context =>
+  ({
+    currentVersion: 'enterprise-server@3.21',
+    currentLanguage: 'en',
+    ...overrides,
+  }) as Context
+
+const makePage = (overrides: Partial<Page> = {}): Page =>
+  ({
+    layout: 'release-notes',
+    title: 'GitHub Enterprise Server 3.21 release notes',
+    intro: '',
+    renderProp: async () => '',
+    ...overrides,
+  }) as unknown as Page
+
+const samplePatch = (): GHESReleasePatch => ({
+  version: '3.21.0',
+  patchVersion: '0',
+  downloadVersion: '3.21.0',
+  release: '3.21',
+  date: '2026-05-26',
+  intro: 'Intro paragraph for this patch.',
+  sections: {
+    features: ['A new feature note.'],
+    bugs: ['A bug was fixed.', 'Another bug was fixed.'],
+    known_issues: [
+      { heading: 'Instance administration', notes: ['Sub note one.', 'Sub note two.'] },
+    ],
+    security_fixes: ['**CRITICAL**: Something serious.'],
+  },
+})
+
+describe('ReleaseNotesTransformer', () => {
+  describe('canTransform', () => {
+    test('matches pages with layout: release-notes', () => {
+      const transformer = new ReleaseNotesTransformer()
+      expect(transformer.canTransform(makePage({ layout: 'release-notes' }))).toBe(true)
+    })
+
+    test('does not match pages with other layouts', () => {
+      const transformer = new ReleaseNotesTransformer()
+      expect(transformer.canTransform(makePage({ layout: 'default' } as unknown as Page))).toBe(
+        false,
+      )
+      expect(transformer.canTransform(makePage({ layout: undefined } as unknown as Page))).toBe(
+        false,
+      )
+    })
+  })
+
+  describe('transform error paths', () => {
+    test('throws when currentVersion is missing', async () => {
+      const transformer = new ReleaseNotesTransformer()
+      await expect(
+        transformer.transform(
+          makePage(),
+          '/x',
+          makeContext({ currentVersion: undefined as unknown as string }),
+        ),
+      ).rejects.toThrow(/No currentVersion/)
+    })
+
+    test('throws when plan is not enterprise-server', async () => {
+      const transformer = new ReleaseNotesTransformer()
+      await expect(
+        transformer.transform(
+          makePage(),
+          '/x',
+          makeContext({ currentVersion: 'free-pro-team@latest' }),
+        ),
+      ).rejects.toThrow(/only supports enterprise-server/)
+    })
+
+    test('throws when release is not found', async () => {
+      const transformer = new ReleaseNotesTransformer()
+      await expect(
+        transformer.transform(
+          makePage(),
+          '/x',
+          makeContext({ currentVersion: 'enterprise-server@0.0' }),
+        ),
+      ).rejects.toThrow(/No release notes found/)
+    })
+  })
+})
+
+describe('renderReleaseNotesMarkdown', () => {
+  test('builds H1 title and intro', async () => {
+    const out = await renderReleaseNotesMarkdown('My Title', 'Intro line.', [], makeContext())
+    expect(out).toMatch(/^# My Title\n\nIntro line\.$/)
+  })
+
+  test('renders H2 per patch and H3 per section with bulleted notes', async () => {
+    const out = await renderReleaseNotesMarkdown('Title', '', [samplePatch()], makeContext())
+
+    expect(out).toContain('## 3.21.0')
+    expect(out).toContain('**Release date:** 2026-05-26')
+    expect(out).toContain('Intro paragraph for this patch.')
+
+    expect(out).toContain('### Features')
+    expect(out).toContain('- A new feature note.')
+
+    expect(out).toContain('### Bug fixes')
+    expect(out).toContain('- A bug was fixed.')
+    expect(out).toContain('- Another bug was fixed.')
+
+    expect(out).toContain('### Security fixes')
+    expect(out).toContain('- **CRITICAL**: Something serious.')
+  })
+
+  test('renders { heading, notes } as a nested bulleted list', async () => {
+    const out = await renderReleaseNotesMarkdown('Title', '', [samplePatch()], makeContext())
+
+    expect(out).toContain('### Known issues')
+    // Heading is a top-level bullet, sub-notes are nested under it.
+    expect(out).toContain('- **Instance administration**')
+    expect(out).toMatch(
+      /- \*\*Instance administration\*\*\n {2}- Sub note one\.\n {2}- Sub note two\./,
+    )
+  })
+
+  test('preserves multi-line notes with continuation indent', async () => {
+    const patch: GHESReleasePatch = {
+      ...samplePatch(),
+      sections: { features: ['Line one.\n\nLine two.'] },
+    }
+    const out = await renderReleaseNotesMarkdown('Title', '', [patch], makeContext())
+    expect(out).toMatch(/- Line one\.\n\n {2}Line two\./)
+  })
+
+  test('throws on unrecognized note shape', async () => {
+    const patch: GHESReleasePatch = {
+      ...samplePatch(),
+      sections: { features: [{ unknown: 'shape' } as unknown as string] },
+    }
+    await expect(renderReleaseNotesMarkdown('Title', '', [patch], makeContext())).rejects.toThrow(
+      /Unrecognized release note shape/,
+    )
+  })
+
+  test('uses raw section key when label is unknown', async () => {
+    const patch: GHESReleasePatch = {
+      ...samplePatch(),
+      sections: { custom_section: ['A note.'] } as unknown as GHESReleasePatch['sections'],
+    }
+    const out = await renderReleaseNotesMarkdown('Title', '', [patch], makeContext())
+    expect(out).toContain('### custom_section')
+  })
+
+  test('skips empty sections', async () => {
+    const patch: GHESReleasePatch = {
+      ...samplePatch(),
+      sections: { features: [], bugs: ['A bug.'] },
+    }
+    const out = await renderReleaseNotesMarkdown('Title', '', [patch], makeContext())
+    expect(out).not.toContain('### Features')
+    expect(out).toContain('### Bug fixes')
+  })
+})

src/article-api/transformers/index.ts

@@ -15,6 +15,7 @@ import { JourneyLandingTransformer } from './journey-landing-transformer'
 import { CategoryLandingTransformer } from './category-landing-transformer'
 import { DiscoveryLandingTransformer } from './discovery-landing-transformer'
 import { SearchPageTransformer } from './search-page-transformer'
+import { ReleaseNotesTransformer } from './release-notes-transformer'
 import { ArticleTransformer } from './article-transformer'
 
 /**
@@ -39,6 +40,7 @@ transformerRegistry.register(new JourneyLandingTransformer())
 transformerRegistry.register(new CategoryLandingTransformer())
 transformerRegistry.register(new DiscoveryLandingTransformer())
 transformerRegistry.register(new SearchPageTransformer())
+transformerRegistry.register(new ReleaseNotesTransformer())
 // ArticleTransformer is the catch-all — must be registered last.
 transformerRegistry.register(new ArticleTransformer())
 

src/article-api/transformers/release-notes-transformer.ts

@@ -0,0 +1,126 @@
+import type { Context, Page, GHESReleasePatch } from '@/types'
+import type { PageTransformer } from './types'
+import { getReleaseNotes } from '@/release-notes/middleware/get-release-notes'
+import { formatReleases } from '@/release-notes/lib/release-notes-utils'
+import { renderContent } from '@/content-render/index'
+
+/**
+ * Transformer for GHES enterprise-server release notes pages.
+ *
+ * The release notes content comes from YAML data files (not the markdown body),
+ * so the generic ArticleTransformer would return an empty body. This transformer
+ * fetches the release notes data directly and renders it as markdown.
+ */
+export class ReleaseNotesTransformer implements PageTransformer {
+  canTransform(page: Page): boolean {
+    return page.layout === 'release-notes'
+  }
+
+  async transform(page: Page, _pathname: string, context: Context): Promise<string> {
+    const currentVersion = context.currentVersion
+    if (!currentVersion) {
+      throw new Error('No currentVersion in context for release notes transformer')
+    }
+
+    const [plan, release] = currentVersion.split('@')
+    if (plan !== 'enterprise-server') {
+      throw new Error(`Release notes transformer only supports enterprise-server, got: ${plan}`)
+    }
+
+    const releaseNotes = getReleaseNotes('enterprise-server', 'en')
+    const allReleases = formatReleases(releaseNotes)
+
+    const matchedRelease = allReleases.find((r) => r.version === release)
+    if (!matchedRelease) {
+      throw new Error(`No release notes found for enterprise-server@${release}`)
+    }
+
+    const title = page.title
+    const intro = page.intro ? await page.renderProp('intro', context, { textOnly: true }) : ''
+
+    return await renderReleaseNotesMarkdown(title, intro, matchedRelease.patches, context)
+  }
+}
+
+// Matches the labels used by the web renderer; keep in sync with
+// src/release-notes/components/PatchNotes.tsx.
+const SECTION_LABELS: Record<string, string> = {
+  features: 'Features',
+  bugs: 'Bug fixes',
+  known_issues: 'Known issues',
+  security_fixes: 'Security fixes',
+  changes: 'Changes',
+  deprecations: 'Deprecations',
+  backups: 'Backups',
+  errata: 'Errata',
+  closing_down: 'Closing down',
+  retired: 'Retired',
+}
+
+async function renderNoteMarkdown(raw: string, context: Context): Promise<string> {
+  return await renderContent(raw, { ...context, markdownRequested: true })
+}
+
+// Format `text` as a list item at the given indent depth. The first line
+// gets the `- ` bullet; continuation lines are indented to align under it,
+// so multi-paragraph notes and fenced code blocks stay inside the list item
+// per CommonMark/GFM rules.
+function bulletize(text: string, depth = 0): string {
+  const trimmed = text.replace(/\s+$/, '')
+  if (!trimmed) return ''
+  const indent = '  '.repeat(depth)
+  const continuationIndent = `${indent}  `
+  const [first, ...rest] = trimmed.split('\n')
+  if (rest.length === 0) return `${indent}- ${first}`
+  const continuation = rest.map((line) => (line.length ? `${continuationIndent}${line}` : line))
+  return `${indent}- ${first}\n${continuation.join('\n')}`
+}
+
+export async function renderReleaseNotesMarkdown(
+  title: string,
+  intro: string,
+  patches: GHESReleasePatch[],
+  context: Context,
+): Promise<string> {
+  const lines: string[] = [`# ${title}`]
+  if (intro) lines.push('', intro)
+
+  for (const patch of patches) {
+    lines.push('', `## ${patch.version}`)
+    if (patch.date) lines.push('', `**Release date:** ${patch.date}`)
+    if (patch.intro) {
+      lines.push('', await renderNoteMarkdown(patch.intro, context))
+    }
+
+    for (const [sectionKey, sectionArray] of Object.entries(patch.sections)) {
+      if (!Array.isArray(sectionArray) || sectionArray.length === 0) continue
+      const sectionLabel = SECTION_LABELS[sectionKey] || sectionKey
+      lines.push('', `### ${sectionLabel}`)
+
+      for (const note of sectionArray) {
+        if (typeof note === 'string') {
+          const rendered = await renderNoteMarkdown(note, context)
+          lines.push('', bulletize(rendered))
+        } else if (
+          note &&
+          typeof note === 'object' &&
+          'heading' in note &&
+          'notes' in note &&
+          Array.isArray((note as { notes: unknown }).notes)
+        ) {
+          const heading = (note as { heading: string }).heading
+          const subNotes = (note as { notes: string[] }).notes
+          lines.push('', `- **${heading}**`)
+          for (const subNote of subNotes) {
+            const rendered = await renderNoteMarkdown(subNote, context)
+            lines.push(bulletize(rendered, 1))
+          }
+        } else {
+          throw new Error(`Unrecognized release note shape in section ${sectionKey}`)
+        }
+      }
+    }
+  }
+
+  return lines.join('\n')
+}