← Back to @hyperfrontend/versioning
@hyperfrontend/versioning/changelog/compare

compare

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

API Reference§

ƒ Functions

§function

diffChangelogs(source: Changelog, target: Changelog): ChangelogDiff

Computes the diff between two changelogs.
Parameters
NameTypeDescription
§source
ChangelogThe source/original changelog
§target
ChangelogThe target/modified changelog
Returns
ChangelogDiff
Detailed diff of changes
Example

Comparing two changelogs

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

diffEntries(source: ChangelogEntry, target: ChangelogEntry): EntryDiff

Computes the diff between two changelog entries.
Parameters
NameTypeDescription
§source
ChangelogEntryThe source entry
§target
ChangelogEntryThe target entry
Returns
EntryDiff
Detailed entry diff
Example

Computing diff between two entries

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

getEntryByVersion(changelog: Changelog, version: string): ChangelogEntry

Gets an entry by version from a changelog.
Parameters
NameTypeDescription
§changelog
ChangelogThe changelog to search
§version
stringThe version to find
Returns
ChangelogEntry
The entry if found, undefined otherwise
Example

Getting an entry by version

const entry = getEntryByVersion(changelog, '1.0.0')
// => ChangelogEntry for 1.0.0 or undefined
View source →
§function

hasVersion(changelog: Changelog, version: string): boolean

Checks if a changelog contains a specific version.
Parameters
NameTypeDescription
§changelog
ChangelogThe changelog to search
§version
stringThe version to look for
Returns
boolean
True if the version exists in the changelog
Example

Checking if a changelog contains a version

hasVersion(changelog, '2.0.0')
// => true if an entry for version 2.0.0 exists
View source →
§function

haveSameVersions(a: Changelog, b: Changelog): boolean

Checks if two changelogs have the same entries (by version). Does not compare entry contents, only versions present.
Parameters
NameTypeDescription
§a
ChangelogFirst changelog
§b
ChangelogSecond changelog
Returns
boolean
True if both changelogs have the same versions
Example

Checking if changelogs have the same versions

haveSameVersions(changelog1, changelog2)
// => true if both have entries for the same version strings
View source →
§function

isChangelogEqual(a: Changelog, b: Changelog): boolean

Checks if two changelogs are structurally identical.
Parameters
NameTypeDescription
§a
ChangelogFirst changelog
§b
ChangelogSecond changelog
Returns
boolean
True if changelogs are identical
Example

Checking changelog equality

if (isChangelogEqual(mainChangelog, branchChangelog)) {
  console.log('Changelogs are identical')
}
View source →
§function

isCommitRefEqual(a: CommitRef, b: CommitRef): boolean

Checks if two commit references are equal.
Parameters
NameTypeDescription
§a
CommitRefFirst commit ref
§b
CommitRefSecond commit ref
Returns
boolean
True if commit refs are equal
Example

Comparing commit references

isCommitRefEqual(commitA, commitB)
// => true if hash, shortHash, and url match
View source →
§function

isEntryContentEqual(a: ChangelogEntry, b: ChangelogEntry): boolean

Checks if two changelog entries describe the same release.
The 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
NameTypeDescription
§a
ChangelogEntryFirst entry
§b
ChangelogEntrySecond entry
Returns
boolean
True if both entries carry the same version and sections
Example

Validating a committed entry against one regenerated today

isEntryContentEqual(committedEntry, regeneratedEntry)
// => true even though the dates and compare URLs differ
View source →
§function

isEntryEqual(a: ChangelogEntry, b: ChangelogEntry): boolean

Checks if two changelog entries are equal.
Parameters
NameTypeDescription
§a
ChangelogEntryFirst entry
§b
ChangelogEntrySecond entry
Returns
boolean
True if entries are equal
Example

Comparing changelog entries

isEntryEqual(entryA, entryB)
// => true if version, date, sections, and all nested data match
View source →
§function

isHeaderEqual(a: ChangelogHeader, b: ChangelogHeader): boolean

Checks if two changelog headers are equal.
Parameters
NameTypeDescription
§a
ChangelogHeaderFirst header
§b
ChangelogHeaderSecond header
Returns
boolean
True if headers are equal
Example

Comparing changelog headers

isHeaderEqual(changelog1.header, changelog2.header)
// => true if titles, descriptions, and links match
View source →
§function

isIssueRefEqual(a: IssueRef, b: IssueRef): boolean

Checks if two issue references are equal.
Parameters
NameTypeDescription
§a
IssueRefFirst issue ref
§b
IssueRefSecond issue ref
Returns
boolean
True if issue refs are equal
Example

Comparing issue references

isIssueRefEqual({ number: 42, type: 'issue' }, { number: 42, type: 'issue' })
// => true
View source →
§function

isItemEqual(a: ChangelogItem, b: ChangelogItem): boolean

Checks if two changelog items are equal.
Parameters
NameTypeDescription
§a
ChangelogItemFirst item
§b
ChangelogItemSecond item
Returns
boolean
True if items are equal
Example

Comparing changelog items

isItemEqual(itemA, itemB)
// => true if description, scope, breaking, commits, and references match
View source →
§function

isLinkEqual(a: ChangelogLink, b: ChangelogLink): boolean

Checks if two changelog links are equal.
Parameters
NameTypeDescription
§a
ChangelogLinkFirst link
§b
ChangelogLinkSecond link
Returns
boolean
True if links are equal
Example

Comparing changelog links

isLinkEqual({ label: '1.0.0', url: '...' }, { label: '1.0.0', url: '...' })
// => true
View source →
§function

isMetadataEqual(a: ChangelogMetadata, b: ChangelogMetadata): boolean

Checks if two changelog metadata objects are equal.
Parameters
NameTypeDescription
§a
ChangelogMetadataFirst metadata
§b
ChangelogMetadataSecond metadata
Returns
boolean
True if metadata are equal
Example

Comparing changelog metadata

isMetadataEqual(changelog1.metadata, changelog2.metadata)
// => true if format, isConventional, repositoryUrl, and warnings match
View source →
§function

isSectionEqual(a: ChangelogSection, b: ChangelogSection): boolean

Checks if two changelog sections are equal.
Parameters
NameTypeDescription
§a
ChangelogSectionFirst section
§b
ChangelogSectionSecond section
Returns
boolean
True if sections are equal
Example

Comparing changelog sections

isSectionEqual(featuresA, featuresB)
// => true if type, heading, and all items match
View source →
§function

summarizeDiff(diff: ChangelogDiff): string

Creates a human-readable summary of a changelog diff.
Parameters
NameTypeDescription
§diff
ChangelogDiffThe diff to summarize
Returns
string
A string summary of the changes
Example

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'
View source →

◈ Interfaces

§interface

ChangelogDiff

Represents the diff between two changelogs.
Properties
§readonly added:unknownEntries added in target but not in source
§readonly removed:unknownEntries removed from source but not in target
§readonly modified:unknownEntries present in both but with differences
§readonly identical:booleanWhether changelogs are structurally identical
§readonly stats:DiffStatsSummary statistics
View source →
§interface

DiffStats

Statistics about the diff.
Properties
§readonly addedCount:numberNumber of added entries
§readonly removedCount:numberNumber of removed entries
§readonly modifiedCount:numberNumber of modified entries
§readonly totalChanges:numberTotal number of property changes across all modified entries
View source →
§interface

EntryDiff

Represents differences in a single entry.
Properties
§readonly version:stringVersion of the entry
§readonly source:ChangelogEntryOriginal entry (from source)
§readonly target:ChangelogEntryModified entry (from target)
§readonly changes:unknownList of property differences
§readonly addedSections:unknownSections added in target
§readonly removedSections:unknownSections removed from source
§readonly modifiedSections:unknownSections that were modified
View source →
§interface

ItemDiff

Represents differences in a single item.
Properties
§readonly sourceDescription:stringDescription from source
§readonly source:ChangelogItemSource item
§readonly target:ChangelogItemTarget item
§readonly changes:unknownList of property changes
View source →
§interface

PropertyDiff

Represents a single property difference.
Properties
§readonly path:unknownPath to the property (e.g., ['date'], ['sections', '0', 'heading'])
§readonly type:"added" | "changed" | "removed"Type of change
§readonly oldValue?:unknownPrevious value (for 'removed' and 'changed')
§readonly newValue?:unknownNew value (for 'added' and 'changed')
View source →
§interface

SectionDiff

Represents differences in a single section.
Properties
§readonly type:stringSection type
§readonly source:ChangelogSectionOriginal section (from source)
§readonly target:ChangelogSectionModified section (from target)
§readonly addedItems:unknownItems added in target
§readonly removedItems:unknownItems removed from source
§readonly modifiedItems:unknownItems that were modified
View source →