docs/lib/release-notes-utils.js

import semver from 'semver'
import renderContent from './render-content/index.js'

/**
 * Turn { [key]: { notes, intro, date } }
 * into [{ version, notes, intro, date }]
 */
export function sortPatchKeys(release, version, options = {}) {
  const keys = Object.keys(release)
    .map((key) => {
      const keyWithDots = key.replace(/-/g, '.')
      return {
        version: `${version}.${keyWithDots}`,
        patchVersion: keyWithDots,
        downloadVersion: `${version}.${keyWithDots.replace(/\.rc\d*$/, '')}`,
        release: version, // TODO this naming :/ we are not currently using this value, but we may want to.
        ...release[key],
      }
    })
    // Filter out any deprecated patches
    .filter((key) => !key.deprecated)

  // Versions with numbered releases like GHES 2.22, 3.0, etc. need additional semver sorting;
  // Versions with date releases need to be sorted by date.
  return options.semverSort
    ? semverSort(keys)
    : keys.sort((a, b) => new Date(b.date) - new Date(a.date))
}

export function semverSort(keys) {
  return keys.sort((a, b) => {
    let aTemp = a.version
    let bTemp = b.version

    // There's an RC version here, so doing regular semver
    // comparisons won't work. So, we'll convert the incompatible version
    // strings to real semver strings, then compare.
    const [aBase, aRc] = a.version.split('.rc')
    if (aRc) aTemp = `${aBase}-rc.${aRc}`

    const [bBase, bRc] = b.version.split('.rc')
    if (bRc) bTemp = `${bBase}-rc.${bRc}`

    if (semver.gt(aTemp, bTemp)) return -1
    if (semver.lt(aTemp, bTemp)) return 1
    return 0
  })
}

/**
 * Render each note in the given patch, by looping through the
 * sections and rendering either `note` or `note.notes` in the
 * case of a sub-section
 */
export async function renderPatchNotes(patch, ctx) {
  // Run the notes through the markdown rendering pipeline
  for (const key in patch.sections) {
    await Promise.all(
      patch.sections[key].map(async (noteOrHeading, index) => {
        patch.sections[key][index] =
          typeof noteOrHeading === 'string'
            ? await renderContent(noteOrHeading, ctx)
            : {
                ...noteOrHeading,
                notes: await Promise.all(
                  noteOrHeading.notes.map((note) => renderContent(note, ctx))
                ),
              }
      })
    )
  }

  // Also render the patch's intro
  if (patch.intro) {
    patch.intro = await renderContent(patch.intro, ctx)
  }

  return patch
}

export function sortReleasesByDate(releaseNotes) {
  return Object.keys(releaseNotes)
    .map((release) => {
      const [year, month] = release.split('-')
      return {
        name: release,
        date: new Date(`20${year}`, month - 1, '1'),
      }
    })
    .sort((releaseEntry1, releaseEntry2) => releaseEntry2.date - releaseEntry1.date)
    .map((releaseEntry) => releaseEntry.name)
}

export function getAllReleases(releases, releaseNotesPerPlan, hasNumberedReleases) {
  return releases.map((version) => {
    const release = releaseNotesPerPlan[version.replace(/\./g, '-')]
    if (!release) return { version }
    const patches = sortPatchKeys(release, version, { semverSort: hasNumberedReleases })
    return { version, patches }
  })
}

export default {
  sortReleasesByDate,
  sortPatchKeys,
  renderPatchNotes,
  getAllReleases,
}