@hyperfrontend/versioning/changelog/comparecompare
Equality checks and structural diffs for changelogs, entries, sections, items, and references.
Overview
compare/ answers two questions: are two changelogs equivalent, and where do they differ? Equality functions (isChangelogEqual, isEntryEqual, isSectionEqual, ...) perform deep value comparison ignoring incidental ordering where appropriate. isEntryContentEqual compares what an entry says about its release (version and sections) and ignores the date and compare URL, which are stamped at generation time and drift when the same entry is regenerated later. Diff functions (diffChangelogs, diffEntries, summarizeDiff) produce structured ChangelogDiff reports describing added, removed, and modified pieces. Useful for round-trip tests, merge conflict resolution, and changelog drift detection in CI.
See Also
- models/: Shapes being compared
- operations/merge: Consumes diffs to drive merges
API Reference§
ƒ Functions
Parameters
Returns
ChangelogDiffExample
Comparing two changelogs
const diff = diffChangelogs(mainChangelog, branchChangelog)
console.log(`Added: ${diff.added.length}, Removed: ${diff.removed.length}`)Parameters
| Name | Type | Description |
|---|---|---|
§source | ChangelogEntry | The source entry |
§target | ChangelogEntry | The target entry |
Returns
EntryDiffExample
Computing diff between two entries
const diff = diffEntries(entryV1, entryV2)
// => { version: '1.0.0', changes: [{ path: ['date'], type: 'changed', ... }], sectionsChanged: true }Parameters
Returns
ChangelogEntryExample
Getting an entry by version
const entry = getEntryByVersion(changelog, '1.0.0')
// => ChangelogEntry for 1.0.0 or undefinedParameters
Returns
booleanExample
Checking if a changelog contains a version
hasVersion(changelog, '2.0.0')
// => true if an entry for version 2.0.0 existsReturns
booleanExample
Checking if changelogs have the same versions
haveSameVersions(changelog1, changelog2)
// => true if both have entries for the same version stringsReturns
booleanExample
Checking changelog equality
if (isChangelogEqual(mainChangelog, branchChangelog)) {
console.log('Changelogs are identical')
}Returns
booleanExample
Comparing commit references
isCommitRefEqual(commitA, commitB)
// => true if hash, shortHash, and url matchThe date and the compare URL are stamped when an entry is generated: the date is the day of generation and the compare URL ends at whatever commit was HEAD. Neither is derived from the commits the entry describes, so an entry regenerated later for the same release differs in both while saying exactly the same thing. This comparison reads the version, the unreleased flag, the raw content, and the sections, which is what a release's changelog entry asserts about the commits behind it.
Parameters
| Name | Type | Description |
|---|---|---|
§a | ChangelogEntry | First entry |
§b | ChangelogEntry | Second entry |
Returns
booleanExample
Validating a committed entry against one regenerated today
isEntryContentEqual(committedEntry, regeneratedEntry)
// => true even though the dates and compare URLs differParameters
| Name | Type | Description |
|---|---|---|
§a | ChangelogEntry | First entry |
§b | ChangelogEntry | Second entry |
Returns
booleanExample
Comparing changelog entries
isEntryEqual(entryA, entryB)
// => true if version, date, sections, and all nested data matchParameters
| Name | Type | Description |
|---|---|---|
§a | ChangelogHeader | First header |
§b | ChangelogHeader | Second header |
Returns
booleanExample
Comparing changelog headers
isHeaderEqual(changelog1.header, changelog2.header)
// => true if titles, descriptions, and links matchReturns
booleanExample
Comparing issue references
isIssueRefEqual({ number: 42, type: 'issue' }, { number: 42, type: 'issue' })
// => trueParameters
| Name | Type | Description |
|---|---|---|
§a | ChangelogItem | First item |
§b | ChangelogItem | Second item |
Returns
booleanExample
Comparing changelog items
isItemEqual(itemA, itemB)
// => true if description, scope, breaking, commits, and references matchParameters
| Name | Type | Description |
|---|---|---|
§a | ChangelogLink | First link |
§b | ChangelogLink | Second link |
Returns
booleanExample
Comparing changelog links
isLinkEqual({ label: '1.0.0', url: '...' }, { label: '1.0.0', url: '...' })
// => trueParameters
| Name | Type | Description |
|---|---|---|
§a | ChangelogMetadata | First metadata |
§b | ChangelogMetadata | Second metadata |
Returns
booleanExample
Comparing changelog metadata
isMetadataEqual(changelog1.metadata, changelog2.metadata)
// => true if format, isConventional, repositoryUrl, and warnings matchParameters
| Name | Type | Description |
|---|---|---|
§a | ChangelogSection | First section |
§b | ChangelogSection | Second section |
Returns
booleanExample
Comparing changelog sections
isSectionEqual(featuresA, featuresB)
// => true if type, heading, and all items matchParameters
| Name | Type | Description |
|---|---|---|
§diff | ChangelogDiff | The diff to summarize |
Returns
stringExample
Creating human-readable diff summary
const diff = diffChangelogs(oldChangelog, newChangelog)
summarizeDiff(diff)
// => 'Added 2 version(s): 1.2.0, 1.1.0; Modified 1 version(s): 1.0.0'