@hyperfrontend/versioning/changelog/models

models

Type definitions and factory functions for the changelog data model.

Exposes Changelog, ChangelogHeader, ChangelogEntry, ChangelogSection, ChangelogItem, CommitRef, and IssueRef, along with create* factories, the section-type registry (SECTION_HEADINGS, getSectionType), and the JSON schema (changelogSchema, validateChangelog). All other changelog/* submodules consume these shapes.

API Reference

ƒ Functions

§function

checkSchemaCompatibility(source: Changelog, target: Changelog): CompatibilityResult

Checks if two changelogs have compatible schemas. Used to detect format incompatibilities before merge/compare.

Parameters

Name	Type	Description
§source	`Changelog`	The source changelog
§target	`Changelog`	The target changelog

Returns

CompatibilityResult

Compatibility result with any differences found

Example

Checking schema compatibility before merge

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

§function

createChangelog(options?: Partial<Changelog>): Changelog

Creates a new changelog with default values.

Parameters

Name	Type	Description
§options?	`Partial<Changelog>`	Optional configuration to customize the changelog

Returns

Changelog

A new Changelog object with the specified options or defaults

Example

Creating a changelog with custom source

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

§function

createChangelogEntry(version: string, options?: Partial<Omit<ChangelogEntry, "version">>): ChangelogEntry

Creates a new changelog entry.

Parameters

Name	Type	Description
§version	`string`	The version string (e.g., '1.0.0')
§options?	`Partial<Omit<ChangelogEntry, "version">>`	Optional configuration for date, sections, and other properties

Returns

ChangelogEntry

A new ChangelogEntry object

Example

Creating a changelog entry with date and sections

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

§function

createChangelogItem(description: string, options?: Partial<Omit<ChangelogItem, "description">>): ChangelogItem

Creates a new changelog item.

Parameters

Name	Type	Description
§description	`string`	The description text of the change
§options?	`Partial<Omit<ChangelogItem, "description">>`	Optional configuration for scope, commits, references, and breaking flag

Returns

ChangelogItem

A new ChangelogItem object

Example

Creating a changelog item with options

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

§function

createChangelogLink(label: string, url: string): ChangelogLink

Creates a changelog link.

Parameters

Name	Type	Description
§label	`string`	The display text for the link
§url	`string`	The URL the link points to

Returns

ChangelogLink

A new ChangelogLink object

Example

Creating a version comparison link

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/...' }

§function

createChangelogSection(type: ChangelogSectionType, heading: string, items: unknown): ChangelogSection

Creates a new changelog section.

Parameters

Name	Type	Description
§type	`ChangelogSectionType`	The type of section (features, fixes, breaking, etc.)
§heading	`string`	The display heading for the section
§items	`unknown`	Optional array of changelog items in this section (default: `[]`)

Returns

ChangelogSection

A new ChangelogSection object

Example

Creating a features section with items

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

§function

createCommitRef(hash: string, url?: string): CommitRef

Creates a commit reference from a full hash.

Parameters

Name	Type	Description
§hash	`string`	The full commit hash
§url?	`string`	Optional URL to the commit

Returns

CommitRef

A new CommitRef object with both full and short hash

Example

Creating a commit reference

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

§function

createEmptyChangelog(): Changelog

Creates a new empty changelog with standard header.

Returns

Changelog

A new empty Changelog with Keep a Changelog format

Example

Creating an empty changelog with standard header

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

§function

createIssueRef(number: number, type: "issue" | "pull-request", url?: string): IssueRef

Creates an issue reference.

Parameters

Name	Type	Description
§number	`number`	The issue or PR number
§type	`"issue" \| "pull-request"`	The type of reference ('issue' or 'pull-request') (default: `'issue'`)
§url?	`string`	Optional URL to the issue or PR

Returns

IssueRef

A new IssueRef object

Example

Creating issue and PR references

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 }

§function

createUnreleasedEntry(sections: unknown): ChangelogEntry

Creates an unreleased changelog entry.

Parameters

Name	Type	Description
§sections	`unknown`	Optional array of changelog sections (default: `[]`)

Returns

ChangelogEntry

A new ChangelogEntry object marked as unreleased

Example

Creating an unreleased entry

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

§function

getSectionType(heading: string): ChangelogSectionType

Determines the section type from a heading string. Returns 'other' if the heading is not recognized.

Parameters

Name	Type	Description
§heading	`string`	The heading string to parse

Returns

ChangelogSectionType

The corresponding ChangelogSectionType

Example

Mapping heading strings to section types

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

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

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

§function

getShortHash(hash: string): string

Extracts the short hash from a full commit hash.

Parameters

Name	Type	Description
§hash	`string`	The full commit hash

Returns

string

The first 7 characters of the hash

Example

Extracting short hash from full hash

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

§function

validateChangelog(changelog: unknown): ValidationResult

Validates a changelog object against the schema.

Parameters

Name	Type	Description
§changelog	`unknown`	The changelog object to validate

Returns

ValidationResult

Validation result with any errors

Example

Validating a changelog object

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

◈ Interfaces

§interface

Changelog

Changelog
Complete representation of a CHANGELOG.md file. Designed for lossless round-tripping: parse -> modify -> serialize.

Properties

§readonly entries:unknown—

Version entries, ordered newest first

§readonly header:ChangelogHeader—

File header/preamble content

§readonly metadata:ChangelogMetadata—

Additional metadata extracted during parsing

§readonly source?:string—

Original file path (if parsed from file)

§interface

ChangelogEntry

Changelog Entry
Represents a single version entry in a changelog.

Properties

§readonly compareUrl?:string—

Compare URL (e.g., GitHub compare link)

§readonly date:string—

Release date (ISO format or null for unreleased)

§readonly rawContent?:string—

Raw text for entries that couldn't be parsed structurally

§readonly sections:unknown—

Grouped changes by category

§readonly unreleased:boolean—

Whether this is an unreleased/upcoming section

§readonly version:string—

Version string (e.g., "1.2.3")

§interface

ChangelogHeader

Changelog Header
The header section of a changelog file.

Properties

§readonly description:unknown—

Description paragraphs between title and first entry

§readonly links:unknown—

Any links defined in header

§readonly title:string—

Title (e.g., "# Changelog")

§interface

ChangelogItem

Changelog Item
Represents an individual change within a changelog section.

Properties

§readonly breaking:boolean—

Whether this is a breaking change

§readonly commits:unknown—

Commit references

§readonly description:string—

Description of the change

§readonly indirect?:boolean—

Whether this is an indirect change (dependency or infrastructure)

§readonly references:unknown—

Issue/PR references

§readonly scope?:string—

Scope (e.g., "api", "cli")

§readonly source?:CommitSource—

Classification source (for auditing/debugging)

§interface

ChangelogLink

Changelog Link
Represents a link defined in the changelog header or elsewhere.

Properties

§readonly label:string—

Link label

§readonly url:string—

Link URL

§interface

ChangelogMetadata

Changelog Metadata
Additional information extracted during parsing.

Properties

§readonly format:ChangelogFormat—

Detected changelog format/style

§readonly isConventional:boolean—

Whether the file follows conventional changelog spec

§readonly packageName?:string—

Package name if detected

§readonly repositoryUrl?:string—

Repository URL if detected

§readonly warnings:unknown—

Parser warnings/notes

§interface

ChangelogSection

Changelog Section
Represents a category of changes (Features, Bug Fixes, etc.)

Properties

§readonly heading:string—

Section heading as it appears in file

§readonly items:unknown—

Individual change items

§readonly type:ChangelogSectionType—

Section type (features, fixes, etc.)

§interface

CommitRef

Commit Reference
Represents a reference to a git commit in a changelog item.

Properties

§readonly hash:string—

Full commit hash

§readonly shortHash:string—

Short commit hash (typically 7 characters)

§readonly url?:string—

URL to the commit (e.g., GitHub commit link)

§interface

CompatibilityResult

Schema compatibility check result.

Properties

§readonly compatible:boolean—

Whether schemas are compatible

§readonly differences:unknown—

List of schema differences found

§interface

IssueRef

Issue/PR Reference
Represents a reference to an issue or pull request.

Properties

§readonly number:number—

Issue or PR number

§readonly type:"issue" | "pull-request"—

Type of reference

§readonly url?:string—

URL to the issue/PR

§interface

SchemaDifference

A single schema difference.

Properties

§readonly path:string—

JSON path where difference was found

§readonly sourceType?:string—

Type in source schema

§readonly targetType?:string—

Type in target schema

§readonly type:"type-mismatch" | "missing-property" | "extra-property"—

Type of difference

◆ Types

§type

ChangelogFormat

Changelog Format
Detected format/style of the changelog file.

type ChangelogFormat = "keep-a-changelog" | "conventional" | "custom" | "unknown"

§type

ChangelogSectionType

Changelog Section Types
Categories for grouping changes in a changelog entry.

type ChangelogSectionType = "breaking" | "features" | "fixes" | "performance" | "documentation" | "deprecations" | "refactoring" | "tests" | "build" | "ci" | "chores" | "other"

● Variables

§type

changelogSchema

JSON Schema for a complete Changelog document. Used for validation and format compatibility checking.

§type

SECTION_HEADINGS

Standard section headings for serialization. Maps section types to their preferred heading text.

§type

SECTION_TYPE_MAP

Maps section headings to their canonical types. Used during parsing to normalize different heading styles.