@hyperfrontend/versioning§

import { discoverProject, addDependent } from '@hyperfrontend/versioning'

const project = discoverProject('./libs/utils')
if (project) {
  const updated = addDependent(project, '@myorg/new-app')
  console.log('Dependents now:', updated.internalDependents)
}

const newChangelog = addEntry(changelog, {
  version: '1.2.0',
  date: '2024-01-15',
  unreleased: false,
  sections: [...]
})

const item = { description: 'Add dark mode support', scope: 'ui' }
const updated = addItemToEntry(changelog, '1.2.0', 'features', item)
// Item added to the features section of version 1.2.0

import { addStep, createConventionalFlow, createNoopStep } from '@hyperfrontend/versioning'

const flow = createConventionalFlow()
const extended = addStep(flow, createNoopStep('custom', 'Custom Step'))

console.log(extended.steps.length)
// => original steps + 1

const sections = [createChangelogSection('features', 'Added', [item])]
const updated = addUnreleasedEntry(changelog, sections)
// => Changelog with unreleased entry at the top

Amend the last commit with a new message
const commit = amendCommit('feat: improved feature')

const combined = appendChangelog(mainChangelog, newChangelog, 'start')
// newChangelog entries appear before mainChangelog entries

import { createTree, commitChanges } from '@hyperfrontend/project-scope'
import { applyBumps, calculateCascadeBumps } from '@hyperfrontend/versioning'

const tree = createTree(workspaceRoot)
const cascadeResult = calculateCascadeBumps(workspace, directBumps)
const updateResult = applyBumps(tree, workspace, cascadeResult.bumps)

if (updateResult.success) {
  commitChanges(tree) // Atomic commit of all changes
  console.log(`Updated ${updateResult.updated.length} packages`)
} else {
  console.error('Some updates failed:', updateResult.failed)
  // No commitChanges() call - changes are discarded
}

import { buildDependencyGraph, discoverPackages } from '@hyperfrontend/versioning'

const { projects } = discoverPackages()
const analysis = buildDependencyGraph(projects)

// Get packages that depend on 'lib-utils'
const dependents = analysis.dependencyGraph.get('lib-utils') ?? []

// Get packages in topological order for building
const buildOrder = getTopologicalOrder(analysis)

Build full reference names from type and name
buildRefName('branch', 'main') // 'refs/heads/main'
buildRefName('tag', 'v1.0.0') // 'refs/tags/v1.0.0'
buildRefName('remote', 'main', 'origin') // 'refs/remotes/origin/main'

Build tag names with different formats
buildTagName('@scope/pkg', '1.2.3') // '@scope/pkg@1.2.3'
buildTagName('utils', '1.0.0', 'v${version}') // 'v1.0.0'
buildTagName('pkg', '2.0.0', '${package}-v${version}') // 'pkg-v2.0.0'

import { calculateCascadeBumps } from '@hyperfrontend/versioning'

// If lib-utils is getting a minor bump
const result = calculateCascadeBumps(workspace, [
  { name: 'lib-utils', bumpType: 'minor' }
])

// result.bumps includes lib-utils and all packages that depend on it
for (const bump of result.bumps) {
  console.log(`${bump.name}: ${bump.currentVersion} -> ${bump.nextVersion}`)
}

import { discoverWorkspace, calculateCascadeBumpsFromPackage } from '@hyperfrontend/versioning'

const workspace = discoverWorkspace()
const result = calculateCascadeBumpsFromPackage(workspace, '@myorg/utils', 'minor')

console.log(`${result.totalAffected} packages will be bumped`)
for (const bump of result.bumps) {
  console.log(`${bump.name}: ${bump.currentVersion} -> ${bump.nextVersion}`)
}

try { await executor() } catch (err) { return cancelled(err as Error) }

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

try {
  execFileSync('npm', ['view', name, 'version'])
} catch (error) {
  const failure = classifyNpmError(error)
  if (failure.kind === 'absent') return null
  throw createRegistryUnavailableError({ ...failure, packageName: name })
}

const copy = cloneChangelog(changelog)
// Independent deep copy, safe to mutate

Coerce partial versions to valid semver
coerceVersion('1') // { major: 1, minor: 0, patch: 0, ... }
coerceVersion('1.2') // { major: 1, minor: 2, patch: 0, ... }
coerceVersion('v2.0') // { major: 2, minor: 0, patch: 0, ... }

const unified = combineChangelogs([pkg1Changelog, pkg2Changelog], {
  strategy: 'merge-sections',
})
// All entries from both changelogs merged with conflict resolution

Create a new commit
const commit = createCommit('feat: add new feature')
const commit = createCommit('fix: resolve bug', { body: 'Detailed description' })

if (commitExists('abc123def')) {
  console.log('Commit found in repository')
}

const compacted = compact(changelog)
// Empty sections and entries removed (unreleased kept)

const strict = compact(changelog, false)
// Even empty unreleased entry is removed

Compare two semantic versions
compare(parseVersion('1.0.0'), parseVersion('2.0.0')) // -1
compare(parseVersion('1.0.0'), parseVersion('1.0.0')) // 0
compare(parseVersion('2.0.0'), parseVersion('1.0.0')) // 1

const refs = [refB, refA, refC]
refs.sort(compareRefsByName) // => [refA, refB, refC]

const tags = [tagV1, tagV2, tagV3]
tags.sort(compareTagsByVersion) // => [tagV3, tagV2, tagV1]

countHeaderLength({ type: 'feat', scope: ['core'] }, 'add login')
// => 'feat(core): add login'.length === 21

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' }, ...]

Create an annotated git tag with metadata
const tag = createAnnotatedTag({
  name: 'v1.0.0',
  commitHash: 'abc123...',
  message: 'Release v1.0.0',
  taggerName: 'John Doe',
  taggerEmail: 'john@example.com',
  tagDate: '2026-03-12T10:00:00Z',
})

const anyRange = createAnyRange()
satisfies(parseVersionStrict('999.999.999'), anyRange) // => true

const session = createAuthorSession()
await runAuthorSession(session)

createAuthorSession({ config: { validateRuleset: customRuleset } })

import { createBatchReleaseFlow, executeFlow } from '@hyperfrontend/versioning'

// Release multiple packages without individual commits
for (const pkg of ['lib-a', 'lib-b', 'lib-c']) {
  await executeFlow(createBatchReleaseFlow(), pkg, '/workspace')
}
// Then create a single combined commit

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

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

const cache = createCache(30000) // 30 second TTL
cache.set('key', { data: 'value' })
const value = cache.get<{ data: string }>('key')

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'

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

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

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

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

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

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

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

import { createChangelogOnlyFlow, executeFlow } from '@hyperfrontend/versioning'

const flow = createChangelogOnlyFlow()
const result = await executeFlow(flow, 'my-lib', '/workspace')

// Only changelog is updated, no version bump
console.log(result.state.changelogEntry)

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

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

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

// Result indicates if any dependents need bumps
console.log(result.message)

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')
}

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

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

// Single changelog for all packages
console.log(result.message)

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

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

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

createComparator('>=', parseVersionStrict('1.0.0'))
// => { operator: '>=', version: { major: 1, minor: 0, patch: 0, ... } }

createComparatorSet([gte100, lt200]) // AND: >=1.0.0 AND <2.0.0

// GitHub
createCompareUrl({
  repository: { platform: 'github', baseUrl: 'https://github.com/owner/repo' },
  fromCommit: 'abc1234',
  toCommit: 'def5678'
})
// → 'https://github.com/owner/repo/compare/abc1234...def5678'

// GitLab
createCompareUrl({
  repository: { platform: 'gitlab', baseUrl: 'https://gitlab.com/group/project' },
  fromCommit: 'abc1234',
  toCommit: 'def5678'
})
// → 'https://gitlab.com/group/project/-/compare/abc1234...def5678'

// Bitbucket (reversed order)
createCompareUrl({
  repository: { platform: 'bitbucket', baseUrl: 'https://bitbucket.org/owner/repo' },
  fromCommit: 'abc1234',
  toCommit: 'def5678'
})
// → 'https://bitbucket.org/owner/repo/compare/def5678..abc1234'

// Azure DevOps
createCompareUrl({
  repository: { platform: 'azure-devops', baseUrl: 'https://dev.azure.com/org/proj/_git/repo' },
  fromCommit: 'abc1234',
  toCommit: 'def5678'
})
// → 'https://dev.azure.com/org/proj/_git/repo/compare?version=GTdef5678&compareVersion=GTabc1234'

// Custom formatter
createCompareUrl({
  repository: {
    platform: 'custom',
    baseUrl: 'https://my-git.internal/repo',
    formatCompareUrl: (from, to) => `https://my-git.internal/diff/${from}/${to}`
  },
  fromCommit: 'abc1234',
  toCommit: 'def5678'
})
// → 'https://my-git.internal/diff/abc1234/def5678'

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

import { createConventionalFlow, executeFlow } from '@hyperfrontend/versioning'

// Use defaults
const flow = createConventionalFlow()

// With overrides
const customFlow = createConventionalFlow({
  skipTag: false,
  releaseTypes: ['feat', 'fix'],
})

const result = await executeFlow(flow, 'lib-utils', '/workspace')

const config = createDisabledResolution()
// { mode: 'disabled' }

import { createDryRunFlow, executeFlow } from '@hyperfrontend/versioning'

const flow = createDryRunFlow('conventional')
const result = await executeFlow(flow, 'my-lib', '/workspace')

// Preview changes without modifying files
console.log('Would release:', result.state.nextVersion)

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

Create an empty commit for CI triggers
const commit = createEmptyCommit('chore: trigger CI')

const exact = createExactRange(parseVersionStrict('1.2.3'))
satisfies(parseVersionStrict('1.2.3'), exact) // => true
satisfies(parseVersionStrict('1.2.4'), exact) // => false

const config = createExplicitResolution({
  platform: 'github',
  baseUrl: 'https://github.com/owner/repo'
})

import { createFailedResult } from '@hyperfrontend/versioning'

// In a step handler:
try {
  await doOperation()
} catch (err) {
  return createFailedResult(err as Error, 'Operation failed')
}

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')
}

const first = createFirstRelease()
format(first) // => '1.0.0'

import { createFixedVersionFlow, executeFlow } from '@hyperfrontend/versioning'

// Release with explicit version, ignoring commit analysis
const flow = createFixedVersionFlow('2.0.0')
const result = await executeFlow(flow, 'workspace', '/workspace')

console.log(result.state.nextVersion)
// => '2.0.0'

const myFlow = createFlow(
  'custom',
  'Custom Release Flow',
  [fetchStep, analyzeStep, bumpStep],
  { description: 'My custom versioning workflow' }
)

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

Create a git client for a repository
const git = createGitClient({ cwd: '/path/to/repo' })
const status = git.getStatus()
const commits = git.getCommitsSince('v1.0.0')

Create a git commit model
const commit = createGitCommit({
  hash: 'abc123...',
  authorName: 'John Doe',
  authorEmail: 'john@example.com',
  authorDate: '2026-03-12T10:00:00Z',
  subject: 'feat: add new feature',
})

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

Create a git reference from full name
const ref = createGitRef({
  fullName: 'refs/heads/main',
  commitHash: 'abc123...',
})

import { createIndependentFlow, executeFlow } from '@hyperfrontend/versioning'

const flow = createIndependentFlow()
const result = await executeFlow(flow, 'lib-utils', '/workspace')

// Inspect the version that was released
console.log(result.state.nextVersion)

// Default order: package.json → git remote
const config = createInferredResolution()

// Custom order: git remote → package.json
const customOrder = createInferredResolution(['git-remote', 'package-json'])

const initial = createInitialVersion()
format(initial) // => '0.0.0'

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 }

Create a lightweight git tag
const tag = createLightweightTag({
  name: 'v1.0.0',
  commitHash: 'abc123...',
})

import { createMinimalFlow, executeFlow } from '@hyperfrontend/versioning'

const flow = createMinimalFlow()
const result = await executeFlow(flow, 'my-lib', '/workspace')

// Quick release without changelog or tags
console.log('Released:', result.state.nextVersion)

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

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

const step = createNoopStep('placeholder', 'Placeholder Step')
const result = await executeStep(step, context)

console.log(result.status)
// => 'success'

Creating an npm registry client
const registry = createNpmRegistry()
const version = await registry.getLatestVersion('@hyperfrontend/utils')

const info = createPackageInfo({
  name: '@scope/my-package',
  latestVersion: '2.0.0',
  versions: ['1.0.0', '1.1.0', '2.0.0'],
  license: 'MIT'
})

import { createProject, readPackageJson } from '@hyperfrontend/versioning'

const packageJson = readPackageJson('./libs/my-lib/package.json')
const project = createProject({
  name: '@myorg/my-lib',
  version: '1.0.0',
  path: './libs/my-lib',
  packageJsonPath: './libs/my-lib/package.json',
  packageJson,
  changelogPath: './libs/my-lib/CHANGELOG.md',
})

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'

createRange([set1, set2], '>=1.0.0 || >=2.0.0 <3.0.0')

Creating an npm registry client
const registry = createRegistry('npm')
const version = await registry.getLatestVersion('lodash')

throw createRegistryUnavailableError({
  registry: 'npm',
  packageName: '@scope/pkg',
  operation: 'getLatestVersion',
  reason: 'network',
  detail: 'ECONNREFUSED',
})

// GitHub repository
const config = createRepositoryConfig({
  platform: 'github',
  baseUrl: 'https://github.com/owner/repo'
})

// Custom platform
const customConfig = createRepositoryConfig({
  platform: 'custom',
  baseUrl: 'https://my-git.internal/repo',
  formatCompareUrl: (from, to) => `https://my-git.internal/diff/${from}/${to}`
})

const config = createRepositoryConfigFromUrl('https://github.com/owner/repo'))
// → { platform: 'github', baseUrl: 'https://github.com/owner/repo' }

const config = createRepositoryConfigFromUrl('git@gitlab.com:group/project.git')
// → { platform: 'gitlab', baseUrl: 'https://gitlab.com/group/project' }

createSemVer({ major: 1, minor: 2, patch: 3 })
// => { major: 1, minor: 2, patch: 3, prerelease: [], build: [] }
createSemVer({ major: 1, minor: 0, patch: 0, prerelease: ['beta', '1'] })
// => 1.0.0-beta.1

createSessionContext(config)
// => { draft: {}, candidateScopes: [], defaultScope: undefined, config }

import { createSkippedResult } from '@hyperfrontend/versioning'

// In a step handler:
if (!config.enabled) {
  return createSkippedResult('Feature disabled in config')
}

createSpacing(2, '\n')
// => '\n\n'

const fetchStep = createStep(
  'fetch-registry',
  'Fetch Registry Version',
  async (ctx) => {
    const version = await ctx.registry.getLatestVersion(ctx.packageName)
    return {
      status: 'success',
      stateUpdates: { publishedVersion: version },
      message: `Found published version: ${version}`
    }
  }
)

import { createSuccessResult } from '@hyperfrontend/versioning'

// In a step handler:
return createSuccessResult('Updated 3 files', {
  modifiedFiles: ['/path/a.ts', '/path/b.ts', '/path/c.ts']
})

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

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

// All packages updated to same version
console.log(result.stateUpdates?.modifiedFiles)

import { createSyncedFlow, executeFlow } from '@hyperfrontend/versioning'

const flow = createSyncedFlow()
const result = await executeFlow(flow, 'workspace', '/workspace')

// All packages now share the same version
console.log(`Released v${result.state.nextVersion}`)

Create lightweight and annotated tags
// Create lightweight tag
const tag = createTag('v1.0.0')

// Create annotated tag
const tag = createTag('v1.0.0', { message: 'Release v1.0.0' })

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'

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

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']

import { createVersionFlow, executeFlow } from '@hyperfrontend/versioning'

// Create a conventional flow
const flow = createVersionFlow('conventional')

// Create an independent flow with custom config
const customFlow = createVersionFlow('independent', {
  skipTag: true,
  trackDeps: true,
})

const result = await executeFlow(flow, 'lib-utils', '/workspace')

const release = createVersionInfo({
  version: '1.2.3',
  publishedAt: '2024-01-15T10:30:00Z',
  tarball: 'https://registry.npmjs.org/pkg/-/pkg-1.2.3.tgz'
})

import { createWorkspace, createWorkspaceConfig, createProject } from '@hyperfrontend/versioning'

const projects = new Map([['@myorg/utils', createProject({ ... })]])
const workspace = createWorkspace({
  root: '/path/to/workspace',
  type: 'nx',
  projects,
  config: createWorkspaceConfig(),
  dependencyGraph: new Map(),
  reverseDependencyGraph: new Map(),
})

import { createWorkspaceConfig } from '@hyperfrontend/versioning'

const config = createWorkspaceConfig({
  patterns: ['packages/*', 'libs/*'],
  exclude: ['node_modules', 'dist'],
})

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'

const deduped = deduplicateItems(changelog)
// Duplicate items (same scope:description) are removed

defaultScope([{ name: 'alpha', path: '/repo/libs/alpha' }])
// => 'alpha'

defaultScope([
  { name: 'root', path: '/repo' },
  { name: 'alpha', path: '/repo/libs/alpha' },
])
// => 'root'

defaultScope([
  { name: 'alpha', path: '/repo/libs/alpha' },
  { name: 'beta', path: '/repo/libs/beta' },
])
// => undefined

Delete a tag by name
const deleted = deleteTag('v1.0.0')

import { discoverWorkspace, dependsOn } from '@hyperfrontend/versioning'

const workspace = discoverWorkspace()
if (dependsOn(workspace, '@myorg/app', '@myorg/utils')) {
  console.log('@myorg/app directly depends on @myorg/utils')
}

detectPlatformFromHostname('github.com')           // 'github'
detectPlatformFromHostname('gitlab.mycompany.com') // 'gitlab'
detectPlatformFromHostname('custom-git.internal')  // 'unknown'

Calculate the difference type between two versions
diff(parseVersion('1.0.0'), parseVersion('2.0.0')) // 'major'
diff(parseVersion('1.0.0'), parseVersion('1.1.0')) // 'minor'
diff(parseVersion('1.0.0'), parseVersion('1.0.1')) // 'patch'

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

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

import { discoverAllChangelogs } from '@hyperfrontend/versioning'

const changelogs = discoverAllChangelogs('/path/to/workspace')
for (const changelog of changelogs) {
  console.log(`${changelog.projectPath} -> ${changelog.path}`)
}

import { discoverPackages } from '@hyperfrontend/versioning'

// Discover all packages in current workspace
const result = discoverPackages()

// Discover with custom patterns
const result = discoverPackages({
  patterns: ['packages/*/package.json'],
  includeChangelogs: true
})

// Access discovered projects
for (const project of result.projects) {
  console.log(`${project.name}@${project.version}`)
}

import { discoverProject } from '@hyperfrontend/versioning'

const project = discoverProject('./libs/utils')
if (project) {
  console.log(`Found ${project.name}@${project.version}`)
}

// Also accepts direct package.json path
const project2 = discoverProject('./libs/utils/package.json')

import { discoverProjectByName } from '@hyperfrontend/versioning'

const project = discoverProjectByName('@myorg/utils')
if (project) {
  console.log(`Found at ${project.path}`)
}

// With custom workspace root
const project2 = discoverProjectByName('@myorg/core', { workspaceRoot: '/custom/path' })

discoverScopes(['libs/versioning/src/a.ts', 'libs/questions/src/b.ts'], { cwd: '/repo' })
// => [
//   { name: '@hyperfrontend/versioning', path: '/repo/libs/versioning' },
//   { name: '@hyperfrontend/questions', path: '/repo/libs/questions' },
// ]

async run(): Promise<StepResult> { return done() }

import { dryRun, createConventionalFlow } from '@hyperfrontend/versioning'

const flow = createConventionalFlow()
const result = await dryRun(flow, 'my-lib', '/workspace')

// Preview what would happen
console.log('Would bump to:', result.state.nextVersion)
// No files modified, no git operations performed

eq(parseVersionStrict('1.0.0'), parseVersionStrict('1.0.0')) // => true
eq(parseVersionStrict('1.0.0'), parseVersionStrict('1.0.1')) // => false

const safeAuthor = escapeAuthor('John Doe <john@example.com>')
// => 'John Doe <john@example.com>'

const safePath = escapeFilePath('src/utils/helper.ts')
// => 'src/utils/helper.ts'
escapeFilePath('file$name.ts') // throws - '$' is invalid

escapeGitArg('John Doe <john@example.com>') // => 'John Doe <john@example.com>'

const safeMessage = escapeGitMessage('Release v1.0.0 "stable"')
// => 'Release v1.0.0 \"stable\"'

escapeGitPath('src/utils/helper.ts') // => 'src/utils/helper.ts'
escapeGitPath('path with spaces/file.ts') // => 'path with spaces/file.ts'

escapeGitRef('refs/heads/main') // => 'refs/heads/main'
escapeGitRef('feature/test') // => 'feature/test'
escapeGitRef('ref$invalid') // throws - '$' is invalid

const safePattern = escapeGitTagPattern('@scope/package@')
// => '@scope/package@'
escapeGitTagPattern('v1.0.*') // throws - '*' is invalid

escapePackageName('@scope/package') // => '@scope/package'
escapePackageName('simple-pkg') // => 'simple-pkg'
escapePackageName('pkg$invalid') // throws - '$' is invalid

escapeVersion('1.2.3') // => '1.2.3'
escapeVersion('1.0.0-beta.1') // => '1.0.0-beta.1'
escapeVersion('1.0.0+build') // => '1.0.0+build'

const publicChanges = excludeByScope(changelog, ['internal', 'test'])
// Items scoped to 'internal' or 'test' are removed

import { createConventionalFlow, executeFlow } from '@hyperfrontend/versioning'

const flow = createConventionalFlow({ dryRun: true })
const result = await executeFlow(flow, 'lib-utils', '/path/to/workspace')

console.log(result.summary)
// "Flow success in 234ms: 8 completed, 0 skipped, 0 failed. Version: 1.2.3 → 1.3.0"

Extract package name from tag
extractPackageFromTag('@scope/pkg@1.2.3') // '@scope/pkg'
extractPackageFromTag('lib-utils@1.2.3') // 'lib-utils'
extractPackageFromTag('v1.2.3') // undefined

extractRepositoryUrl('{"repository": {"url": "https://github.com/owner/repo"}}')
// → 'https://github.com/owner/repo'

extractRepositoryUrl('{"repository": "github:owner/repo"}')
// → null (shorthand is not a URL)

Extract scope from conventional commit
extractScope('feat(lib-versioning): add git support') // 'lib-versioning'
extractScope('fix: resolve issue') // undefined

Extract type from conventional commit
extractType('feat(lib-versioning): add git support') // 'feat'
extractType('fix: resolve issue') // 'fix'
extractType('random message') // undefined

Extract version from various tag formats
extractVersionFromTag('v1.2.3') // '1.2.3'
extractVersionFromTag('@scope/pkg@1.2.3') // '1.2.3'
extractVersionFromTag('release-1.2.3') // '1.2.3'

const breaking = filterBreakingChanges(changelog)
// Only entries containing breaking changes or items marked as breaking

const q1 = filterByDateRange(changelog, '2024-01-01', '2024-03-31')
// Entries released in Q1 2024

const apiChanges = filterByScope(changelog, ['api', 'core'])
// Only items scoped to 'api' or 'core'

const majors = filterByVersionRange(changelog, '>=1.0.0 <2.0.0')

const filtered = filterEntries(changelog, (entry) => !entry.unreleased)

const recent = filterFromVersion(changelog, '2.0.0')
// Only entries for version 2.0.0 and later

const withRefs = filterItems(changelog, (item) => item.references.length > 0)
// Only items with issue/PR references

const latest = filterRecentEntries(changelog, 5)
// Last 5 released versions (plus unreleased if present)