@hyperfrontend/versioning/commits/models

models

Conventional-commit type system: type taxonomies, breaking-change models, factories, and semver-bump derivation.

ConventionalCommit and CommitFooter are the structured shapes produced by the parser; createConventionalCommit and createCommitFooter are the canonical factories. The BreakingChange model captures whether a commit declared a breaking change via ! syntax or a BREAKING CHANGE: footer (createBreakingFromFooter, createBreakingFromSubject, createNonBreaking, isBreakingFooterKey). The CommitType taxonomy plus COMMIT_TYPES, MINOR_TYPES, PATCH_TYPES, RELEASE_TYPES, isStandardType, and isReleaseType answer the "what kind of commit is this?" questions, while getSemverBump maps a (type, breaking) pair to the corresponding BumpType.

API Reference

ƒ Functions

§function

createBreakingFromFooter(description: string): BreakingChange

Creates a breaking change from a footer.

Parameters

Name	Type	Description
§description	`string`	The description of the breaking change

Returns

BreakingChange

A BreakingChange object with source 'footer'

Example

Creating a breaking change from footer

createBreakingFromFooter('The config format has changed')
// => { isBreaking: true, description: 'The config format has changed', source: 'footer' }

§function

createBreakingFromSubject(description?: string): BreakingChange

Creates a breaking change from a subject indicator (!).

Parameters

Name	Type	Description
§description?	`string`	Optional description of the breaking change

Returns

BreakingChange

A BreakingChange object with source 'subject'

Example

Creating a breaking change from subject

createBreakingFromSubject('remove deprecated API')
// => { isBreaking: true, description: 'remove deprecated API', source: 'subject' }

§function

createCommitFooter(key: string, value: string, separator: ":" | " #"): CommitFooter

Creates a commit footer.

Parameters

Name	Type	Description
§key	`string`	Footer identifier such as 'Refs', 'Fixes', or 'BREAKING CHANGE'
§value	`string`	Associated content for the footer entry
§separator	`":" \| " #"`	Delimiter between key and value (':' or ' #') (default: `':'`)

Returns

CommitFooter

A new CommitFooter object

Example

Creating commit footers

createCommitFooter('Refs', '#123')
// => { key: 'Refs', value: '#123', separator: ':' }

createCommitFooter('Fixes', '456', ' #')
// => { key: 'Fixes', value: '456', separator: ' #' }

§function

createConventionalCommit(type: string, subject: string, options?: Partial<Omit<ConventionalCommit, "type" | "subject" | "raw">> & { raw: string }): ConventionalCommit

Creates a conventional commit.

Parameters

Name	Type	Description
§type	`string`	The commit type (e.g., 'feat', 'fix')
§subject	`string`	The commit subject line
§options?	`Partial<Omit<ConventionalCommit, "type" \| "subject" \| "raw">> & { raw: string }`	Optional configuration for scope, body, footers, etc.

Returns

ConventionalCommit

A new ConventionalCommit object

Example

Creating conventional commits

createConventionalCommit('feat', 'add user authentication')
// => { type: 'feat', subject: 'add user authentication', scope: [], footers: [], breaking: false, raw: 'feat: add user authentication' }

createConventionalCommit('fix', 'resolve memory leak', { scope: ['core'], breaking: true })
// => { type: 'fix', subject: 'resolve memory leak', scope: ['core'], breaking: true, ... }

createConventionalCommit('feat', 'add x', { scope: ['versioning', 'questions'] })
// => { ..., scope: ['versioning', 'questions'], raw: 'feat(versioning,questions): add x' }

§function

createNonBreaking(): BreakingChange

Creates a non-breaking change.

Returns

BreakingChange

A BreakingChange object indicating no breaking change

Example

Creating a non-breaking change

createNonBreaking()
// => { isBreaking: false, source: 'none' }

§function

getSemverBump(type: string, breaking: boolean): "minor" | "patch" | "none" | "major"

Gets the semver bump level for a commit type. Returns 'none' for types that don't trigger a bump.

Parameters

Name	Type	Description
§type	`string`	The commit type
§breaking	`boolean`	Whether this is a breaking change

Returns

"minor" | "patch" | "none" | "major"

The semver bump level ('major', 'minor', 'patch', or 'none')

Example

Determining semver bump level

getSemverBump('feat', false)
// => 'minor'

getSemverBump('fix', true)
// => 'major'

getSemverBump('docs', false)
// => 'none'

§function

isBreakingFooterKey(key: string): boolean

Checks if a footer key indicates a breaking change.

Parameters

Name	Type	Description
§key	`string`	The footer key to check

Returns

boolean

True if the key indicates a breaking change

Example

Checking if a footer key indicates breaking change

isBreakingFooterKey('BREAKING CHANGE')
// => true

isBreakingFooterKey('BREAKING-CHANGE')
// => true

isBreakingFooterKey('Refs')
// => false

§function

isReleaseType(type: string): boolean

Checks if a commit type triggers a release.

Parameters

Name	Type	Description
§type	`string`	The commit type to check

Returns

boolean

True if the type triggers a release

Example

Checking for release-triggering types

isReleaseType('feat')
// => true

isReleaseType('chore')
// => false

§function

isStandardType(type: string): unknown

Checks if a commit type is a standard type.

Parameters

Name	Type	Description
§type	`string`	The commit type to check

Returns

unknown

True if the type is a standard conventional commit type

Example

Checking for standard commit types

isStandardType('feat')
// => true

isStandardType('custom')
// => false

◈ Interfaces

§interface

BreakingChange

Breaking change information.

Properties

§readonly description?:string—

Description of the breaking change

§readonly isBreaking:boolean—

Whether this is a breaking change

§readonly source:"none" | "subject" | "footer"—

Source of the breaking change indicator

§interface

CommitFooter

Footer trailer in a conventional commit message

Properties

§readonly key:string—

Footer key (e.g., "BREAKING CHANGE", "Refs", "Fixes")

§readonly separator:":" | " #"—

Whether key used : or # separator

§readonly value:string—

Footer value

§interface

ConventionalCommit

Parsed conventional commit message per https://www.conventionalcommits.org/en/v1.0.0/

Properties

§readonly body?:string—

Full commit body

§readonly breaking:boolean—

Whether this is a breaking change

§readonly breakingDescription?:string—

Breaking change description (from footer or subject !)

§readonly footers:unknown—

Parsed footer trailers

§readonly raw:string—

Original raw message

§readonly scope:unknown—

Scopes in parentheses (empty array when header has no scope)

§readonly subject:string—

Subject line (after colon)

§readonly type:string—

Commit type (feat, fix, docs, etc.)

◆ Types

§type

CommitType

Conventional commit type identifier (e.g., 'feat', 'fix', 'docs').

type CommitType = "feat" | "fix" | "docs" | "style" | "refactor" | "perf" | "test" | "build" | "ci" | "chore" | "revert" | string

● Variables

§type

COMMIT_TYPES

§type

MINOR_TYPES

§type

PATCH_TYPES

§type