Changelog Module

const newChangelog = addEntry(changelog, {
  version: '1.2.0',
  date: '2024-01-15',
  unreleased: false,
  sections: [...]
})

const item = { description: 'Add dark mode support', scope: 'ui' }
const updated = addItemToEntry(changelog, '1.2.0', 'features', item)
// Item added to the features section of version 1.2.0

const sections = [createChangelogSection('features', 'Added', [item])]
const updated = addUnreleasedEntry(changelog, sections)
// => Changelog with unreleased entry at the top

const combined = appendChangelog(mainChangelog, newChangelog, 'start')
// newChangelog entries appear before mainChangelog entries

const result = checkSchemaCompatibility(mainChangelog, branchChangelog)
if (!result.compatible) {
  console.log('Schema differences:', result.differences)
}

const copy = cloneChangelog(changelog)
// Independent deep copy, safe to mutate

const unified = combineChangelogs([pkg1Changelog, pkg2Changelog], {
  strategy: 'merge-sections',
})
// All entries from both changelogs merged with conflict resolution

const compacted = compact(changelog)
// Empty sections and entries removed (unreleased kept)

const strict = compact(changelog, false)
// Even empty unreleased entry is removed

const changelog = createChangelog({ source: 'CHANGELOG.md' })
// => { source: 'CHANGELOG.md', header: { title: '# Changelog', ... }, entries: [] }

const entry = createChangelogEntry('1.0.0', {
  date: '2024-01-15',
  sections: [createChangelogSection('features', 'Added', items)],
})

const item = createChangelogItem('Add user authentication', {
  scope: 'auth',
  breaking: false,
  references: [{ number: 42, type: 'issue' }],
})

const link = createChangelogLink('1.0.0', 'https://github.com/org/repo/compare/v0.9.0...v1.0.0')
// => { label: '1.0.0', url: 'https://github.com/...' }

const section = createChangelogSection('features', 'Added', [
  createChangelogItem('New dashboard widget'),
])

const ref = createCommitRef('abc1234def5678', 'https://github.com/org/repo/commit/abc1234def5678')
// => { hash: 'abc1234def5678', shortHash: 'abc1234', url: 'https://...' }

const changelog = createEmptyChangelog()
// => Changelog with standard Keep a Changelog header and no entries

const issueRef = createIssueRef(42, 'issue', 'https://github.com/org/repo/issues/42')
// => { number: 42, type: 'issue', url: 'https://...' }

const prRef = createIssueRef(123, 'pull-request')
// => { number: 123, type: 'pull-request', url: undefined }

createSpacing(2, '\n')
// => '\n\n'

const unreleased = createUnreleasedEntry([
  createChangelogSection('features', 'Added', [item]),
])
// => { version: 'Unreleased', date: null, unreleased: true, sections: [...] }

const deduped = deduplicateItems(changelog)
// Duplicate items (same scope:description) are removed

const diff = diffChangelogs(mainChangelog, branchChangelog)
console.log(`Added: ${diff.added.length}, Removed: ${diff.removed.length}`)

const diff = diffEntries(entryV1, entryV2)
// => { version: '1.0.0', changes: [{ path: ['date'], type: 'changed', ... }], sectionsChanged: true }

const publicChanges = excludeByScope(changelog, ['internal', 'test'])
// Items scoped to 'internal' or 'test' are removed

const breaking = filterBreakingChanges(changelog)
// Only entries containing breaking changes or items marked as breaking

const q1 = filterByDateRange(changelog, '2024-01-01', '2024-03-31')
// Entries released in Q1 2024

const apiChanges = filterByScope(changelog, ['api', 'core'])
// Only items scoped to 'api' or 'core'

const majors = filterByVersionRange(changelog, '>=1.0.0 <2.0.0')

const filtered = filterEntries(changelog, (entry) => !entry.unreleased)

const recent = filterFromVersion(changelog, '2.0.0')
// Only entries for version 2.0.0 and later

const withRefs = filterItems(changelog, (item) => item.references.length > 0)
// Only items with issue/PR references

const latest = filterRecentEntries(changelog, 5)
// Last 5 released versions (plus unreleased if present)

const userFacing = filterSections(changelog, (section) =>
  ['features', 'fixes', 'breaking'].includes(section.type)
)

const userChanges = filterSectionTypes(changelog, ['features', 'fixes'])
// Only features and fixes sections remain

const legacy = filterToVersion(changelog, '1.9.9')
// Only entries for versions up to 1.9.9

const range = filterVersionRange(changelog, '1.5.0', '2.0.0')
// Entries from 1.5.0 through 2.0.0

formatLink('1.0.0', 'https://github.com/org/repo/releases/tag/v1.0.0')
// => '[1.0.0](https://github.com/org/repo/releases/tag/v1.0.0)'

const entry = getEntryByVersion(changelog, '1.0.0')
// => ChangelogEntry for 1.0.0 or undefined

getListMarker(false) // => '- '
getListMarker(true)  // => '* '

getSectionHeading('features')
// => 'Added'

getSectionHeading('features', { features: 'New Features' })
// => 'New Features'

getSectionType('Added')
// => 'features'

getSectionType('Bug Fixes')
// => 'fixes'

getSectionType('Custom Section')
// => 'other'

getShortHash('abc1234def5678901234567890')
// => 'abc1234'

hasVersion(changelog, '2.0.0')
// => true if an entry for version 2.0.0 exists

haveSameVersions(changelog1, changelog2)
// => true if both have entries for the same version strings

if (isChangelogEqual(mainChangelog, branchChangelog)) {
  console.log('Changelogs are identical')
}

isCommitRefEqual(commitA, commitB)
// => true if hash, shortHash, and url match

isEntryContentEqual(committedEntry, regeneratedEntry)
// => true even though the dates and compare URLs differ

isEntryEqual(entryA, entryB)
// => true if version, date, sections, and all nested data match

isHeaderEqual(changelog1.header, changelog2.header)
// => true if titles, descriptions, and links match

isIssueRefEqual({ number: 42, type: 'issue' }, { number: 42, type: 'issue' })
// => true

isItemEqual(itemA, itemB)
// => true if description, scope, breaking, commits, and references match

isLinkEqual({ label: '1.0.0', url: '...' }, { label: '1.0.0', url: '...' })
// => true

isMetadataEqual(changelog1.metadata, changelog2.metadata)
// => true if format, isConventional, repositoryUrl, and warnings match

isSectionEqual(featuresA, featuresB)
// => true if type, heading, and all items match

const result = mergeChangelogs(mainChangelog, branchChangelog)
console.log(`Merged ${result.stats.merged} entries`)

const normalized = normalizeSectionHeadings(changelog)
// 'New Features' becomes 'Added', 'Bug Fixes' becomes 'Fixed', etc.

const markdown = `# Changelog

## [1.0.0] - 2024-01-15

### Added
- Initial release`

const changelog = parseChangelog(markdown, 'CHANGELOG.md')
// => { header: { title: '# Changelog', ... }, entries: [{ version: '1.0.0', ... }] }

parseCommitRefs('Fixed bug (abc1234)', 'https://github.com/org/repo')
// => [{ hash: 'abc1234', shortHash: 'abc1234', url: 'https://github.com/org/repo/commit/abc1234' }]

parseIssueRefs('Closes #42 and PR #123', 'https://github.com/org/repo')
// => [{ number: 42, type: 'issue', url: '...' }, { number: 123, type: 'pull-request', url: '...' }]

parseScopeFromItem('**api:** Add new endpoint')
// => { scope: 'api', description: 'Add new endpoint' }

parseScopeFromItem('Simple change without scope')
// => { scope: undefined, description: 'Simple change without scope' }

parseVersionFromHeading('[1.2.3] - 2024-01-15')
// => { version: '1.2.3', date: '2024-01-15', compareUrl: undefined }

parseVersionFromHeading('v2.0.0')
// => { version: '2.0.0', date: null, compareUrl: undefined }

const released = releaseUnreleased(changelog, '2.0.0', '2024-03-01')
// Unreleased entry becomes version 2.0.0 with the specified date

const cleaned = removeEmptyEntries(changelog)
// Entries with no content are removed (unreleased kept by default)

const strict = removeEmptyEntries(changelog, false)
// Even empty unreleased entry is removed

const cleaned = removeEmptySections(changelog)
// Sections with no items are removed from all entries

const cleaned = removeEntries(changelog, ['0.1.0', '0.2.0'])
// Pre-release versions removed from changelog

const newChangelog = removeEntry(changelog, '1.0.0')

const updated = removeItem(changelog, '1.0.0', 'features', 'Add dark mode')
// The 'Add dark mode' item is removed from features in 1.0.0

const updated = removeSection(changelog, '1.0.0', 'deprecated')
// Version 1.0.0 no longer has a deprecated section

const released = removeUnreleased(changelog)
// Changelog without the unreleased entry

// Silently ignore if not found
const safe = removeUnreleased(changelog, { throwIfNotFound: false })

const opts = resolveOptions({ includeCommits: true })
// => { includeCommits: true, includeScope: true, lineEnding: '\n', ... }

const reversed = reverseEntries(changelog)
// Oldest entries now appear first

const markdown = serializeChangelog(changelog)

const markdown = serializeChangelog(changelog, {
  includeCommits: false,
  useAsterisks: true,
})

const json = serializeChangelogToJson(changelog)

const json = serializeChangelogToJson(changelog, {
  pretty: true,
  indent: 4,
})

const sorted = sortEntries(changelog)
// Entries ordered: Unreleased, 2.0.0, 1.1.0, 1.0.0, ...

const sorted = sortEntriesByDate(changelog)
// Entries ordered by release date, most recent first

const sorted = sortSections(changelog)
// Sections in each entry follow: breaking, features, fixes, ...

const custom = sortSections(changelog, ['fixes', 'features', 'breaking'])
// Custom ordering: fixes first, then features, then breaking

const stripped = stripMetadata(changelog)
// Source and warnings removed, only format and isConventional retained

const diff = diffChangelogs(oldChangelog, newChangelog)
summarizeDiff(diff)
// => 'Added 2 version(s): 1.2.0, 1.1.0; Modified 1 version(s): 1.0.0'

const obj = toJsonObject(changelog, { includeSource: true })
// => { source: 'CHANGELOG.md', header: { title: '...', ... }, entries: [...] }

// Send as API response
res.json(obj)

const tokens = tokenize('# Changelog\n\n## [1.0.0]\n- Added feature')
// => [{ type: 'heading-1', value: 'Changelog', ... }, { type: 'heading-2', ... }, ...]

const transformed = transformEntries(changelog, (entry) => ({
  ...entry,
  date: entry.date?.toUpperCase()
}))

const prefixed = transformItems(changelog, (item) => ({
  ...item,
  description: `[${item.scope || 'misc'}] ${item.description}`,
}))

const renamed = transformSections(changelog, (section) => ({
  ...section,
  heading: section.heading.toUpperCase(),
}))

const updated = updateEntry(changelog, '1.0.0', { date: '2024-01-15' })

// Or with transformer function
const modified = updateEntry(changelog, '1.0.0', (entry) => ({
  ...entry,
  compareUrl: `https://github.com/org/repo/compare/v0.9.0...v${entry.version}`,
}))

const updated = updateHeader(changelog, { title: '# Release Notes' })

const updated = updateMetadata(changelog, { repositoryUrl: 'https://github.com/org/repo' })

const result = validateChangelog(myChangelog)
if (!result.valid) {
  console.log('Validation errors:', result.errors)
}