HyperFrontend
← Back to @hyperfrontend/versioning
@hyperfrontend/versioning/flow/steps

steps

Reusable flow-step factories — the building blocks that the flow/presets family composes into release pipelines.

createFetchRegistryStep, createAnalyzeCommitsStep, createCalculateBumpStep, createCheckIdempotencyStep, createGenerateChangelogStep, createWriteChangelogStep, createGitCommitStep, createTagStep, and createPushTagStep each return a FlowStep with a stable, exported step ID (FETCH_REGISTRY_STEP_ID, ANALYZE_COMMITS_STEP_ID, etc.) so consumers can reference, replace, or position individual steps inside custom flows. DEFAULT_COMMIT_TYPE_TO_SECTION is the conventional mapping from commit types to changelog sections used by the changelog-generation step.

API Reference

ƒ Functions

§function

createAnalyzeCommitsStep(): FlowStep

Creates the analyze-commits step.
This step:
  1. Uses publishedCommit from npm registry (set by fetch-registry step)
  2. Verifies the commit is reachable from current HEAD
  3. Gets all commits since that commit (or recent commits if first release/fallback)
  4. Parses each commit using conventional commit format
  5. Classifies commits based on scope filtering strategy
  6. Filters to only release-worthy commits that belong to this project
State updates:
  • effectiveBaseCommit: The verified base commit (null if fallback was used)
  • commits: Array of parsed conventional commits (for backward compatibility)
  • classificationResult: Full classification result with source attribution

Returns

FlowStep
A FlowStep that analyzes commits

Example

Analyzing commits since last release

import { createAnalyzeCommitsStep, executeStep } from '@hyperfrontend/versioning'

const step = createAnalyzeCommitsStep()
const result = await executeStep(step, context)

// Access analyzed commits
console.log(result.stateUpdates?.commits)
// => [{ type: 'feat', subject: 'add feature' }, ...]
§function

createCalculateBumpStep(): FlowStep

Creates the calculate-bump step.
This step:
  1. Analyzes commit types and breaking changes
  2. Determines the appropriate bump level
  3. Calculates the next version
State updates:
  • bumpType: 'major' | 'minor' | 'patch' | 'none'
  • nextVersion: Calculated next version string

Returns

FlowStep
A FlowStep that calculates version bump

Example

Running the calculate-bump step

import { createCalculateBumpStep, executeStep } from '@hyperfrontend/versioning'

const step = createCalculateBumpStep()
const result = await executeStep(step, context)

// Get the calculated bump
console.log(result.stateUpdates?.bumpType)
// => 'minor'
console.log(result.stateUpdates?.nextVersion)
// => '1.2.0'
§function

createCascadeDependenciesStep(): FlowStep

Creates a step that updates dependent packages in a monorepo.
This step cascades version updates to packages that depend on the updated package.

Returns

FlowStep
A FlowStep that cascades dependency updates

Example

Updating dependent packages in a monorepo

import { createCascadeDependenciesStep, executeStep } from '@hyperfrontend/versioning'

const step = createCascadeDependenciesStep()
const result = await executeStep(step, contextWithTrackDeps)

// Dependent packages are updated
console.log(result.message)
§function

createCheckIdempotencyStep(): FlowStep

Creates a step that checks for idempotency.
This step prevents redundant releases by checking if the calculated version is already published.

Returns

FlowStep
A FlowStep that checks idempotency

Example

Preventing duplicate releases

import { createCheckIdempotencyStep, executeStep } from '@hyperfrontend/versioning'

const step = createCheckIdempotencyStep()
const result = await executeStep(step, context)

// If version already published, step skips with bumpType: 'none'
if (result.status === 'skipped') {
  console.log('Version already published')
}
§function

createFetchRegistryStep(): FlowStep

Creates the fetch-registry step.
This step:
  1. Queries the registry for the latest published version
  2. Reads the current version from package.json
  3. Determines if this is a first release
State updates:
  • publishedVersion: Latest version on registry (null if not published)
  • currentVersion: Version from local package.json
  • isFirstRelease: True if never published

Returns

FlowStep
A FlowStep that fetches registry information

Example

Fetching published version from registry

import { createFetchRegistryStep, executeStep } from '@hyperfrontend/versioning'

const step = createFetchRegistryStep()
const result = await executeStep(step, context)

// Check if first release
if (result.stateUpdates?.isFirstRelease) {
  console.log('First release detected')
}
§function

createGenerateChangelogStep(): FlowStep

Creates the generate-changelog step.
This step:
  1. Groups commits by type/section
  2. Creates changelog items from commits
  3. Assembles a complete changelog entry
State updates:
  • changelogEntry: The generated ChangelogEntry

Returns

FlowStep
A FlowStep that generates changelog

Example

Generating a changelog entry from commits

import { createGenerateChangelogStep, executeStep } from '@hyperfrontend/versioning'

const step = createGenerateChangelogStep()
const result = await executeStep(step, context)

// Access the generated changelog entry
const entry = result.stateUpdates?.changelogEntry
console.log(entry?.version, entry?.sections.length)
// => '1.2.0', 3
§function

createGitCommitStep(): FlowStep

Creates the create-commit step.
This step:
  1. Stages modified files
  2. Creates a commit with the configured message
State updates:
  • commitHash: Hash of the created commit

Returns

FlowStep
A FlowStep that creates a git commit

Example

Creating and staging a release commit

import { createGitCommitStep, executeStep } from '@hyperfrontend/versioning'

const step = createGitCommitStep()
const result = await executeStep(step, context)

// Get the created commit hash
console.log(result.stateUpdates?.commitHash)
// => 'a1b2c3d4e5f6...'
§function

createPushTagStep(): FlowStep

Creates a step that pushes the created tag to remote.

Returns

FlowStep
A FlowStep that pushes the git tag

Example

Pushing the tag to remote

import { createPushTagStep, executeStep } from '@hyperfrontend/versioning'

const step = createPushTagStep()
const result = await executeStep(step, context)

// Tag is pushed to remote
console.log(result.message)
// => 'Pushed tag: my-lib@1.2.0'
§function

createResolveRepositoryStep(): FlowStep

Creates the resolve-repository step.
This step resolves repository configuration for compare URL generation. It supports multiple resolution modes:
  • undefined or 'disabled': No-op, backward compatible default
  • 'inferred': Auto-detect from package.json or git remote
  • RepositoryConfig: Direct repository configuration provided
  • RepositoryResolution: Fine-grained control with mode and options
State updates:
  • repositoryConfig: Resolved repository configuration (if successful)

Returns

FlowStep
A FlowStep that resolves repository configuration

Example

Configuring repository resolution modes

// Auto-detect repository
const flow = createFlow({
  repository: 'inferred'
})

// Explicit repository
const flow = createFlow({
  repository: {
    platform: 'github',
    baseUrl: 'https://github.com/owner/repo'
  }
})
§function

createTagStep(): FlowStep

Creates the create-tag step.
This step:
  1. Creates an annotated git tag
  2. Uses the configured tag format
State updates:
  • tagName: Name of the created tag

Returns

FlowStep
A FlowStep that creates a git tag

Example

Creating an annotated version tag

import { createTagStep, executeStep } from '@hyperfrontend/versioning'

const step = createTagStep()
const result = await executeStep(step, context)

// Get the created tag name
console.log(result.stateUpdates?.tagName)
// => 'my-lib@1.2.0'
§function

createUpdatePackageStep(): FlowStep

Creates the update-packages step.
This step:
  1. Updates the version field in package.json
  2. Tracks the modified files
State updates:
  • modifiedFiles: Adds package.json to list

Returns

FlowStep
A FlowStep that updates package.json

Example

Updating the package.json version field

import { createUpdatePackageStep, executeStep } from '@hyperfrontend/versioning'

const step = createUpdatePackageStep()
const result = await executeStep(step, context)

// package.json version field is updated
console.log(result.stateUpdates?.modifiedFiles)
// => ['/workspace/libs/my-lib/package.json']
§function

createWriteChangelogStep(): FlowStep

Creates the write-changelog step.
This step writes the generated changelog entry to CHANGELOG.md.

Returns

FlowStep
A FlowStep that writes changelog to file

Example

Writing the changelog entry to CHANGELOG.md

import { createWriteChangelogStep, executeStep } from '@hyperfrontend/versioning'

const step = createWriteChangelogStep()
const result = await executeStep(step, context)

// CHANGELOG.md is updated with the new entry
console.log(result.message)
// => 'Updated CHANGELOG.md with version 1.2.0'

● Variables

§type

ANALYZE_COMMITS_STEP_ID

§type

CALCULATE_BUMP_STEP_ID

§type

CREATE_COMMIT_STEP_ID

§type

CREATE_TAG_STEP_ID

§type

DEFAULT_COMMIT_TYPE_TO_SECTION

Maps conventional commit types to changelog section types.
§type

FETCH_REGISTRY_STEP_ID

§type

GENERATE_CHANGELOG_STEP_ID

§type

RESOLVE_REPOSITORY_STEP_ID

§type

UPDATE_PACKAGES_STEP_ID