infra-kit 0.1.102 → 0.1.107

package/src/lib/release-id/__tests__/release-id.test.ts

@@ -0,0 +1,351 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  InvalidReleaseNameError,
+  InvalidReleaseRefError,
+  compareReleaseIds,
+  displayLabel,
+  formatBranchName,
+  formatJiraName,
+  formatPrTitle,
+  formatRcTitle,
+  isReleaseBranch,
+  parseBranchName,
+  parseReleaseRef,
+  validateName,
+} from '../release-id'
+import type { ReleaseId } from '../release-id'
+
+const version = (major: number, minor: number, patch: number): ReleaseId => {
+  return { kind: 'version', semver: { major, minor, patch }, raw: `${major}.${minor}.${patch}` }
+}
+
+const name = (n: string): ReleaseId => {
+  return { kind: 'name', name: n, raw: n }
+}
+
+describe('parseBranchName', () => {
+  it('parses release/v<semver> as a version', () => {
+    expect(parseBranchName('release/v1.2.3')).toEqual(version(1, 2, 3))
+  })
+
+  it('parses release/n/<name> as a name', () => {
+    expect(parseBranchName('release/n/checkout-redesign')).toEqual(name('checkout-redesign'))
+  })
+
+  it('strips a leading refs/heads/ prefix for versions and names', () => {
+    expect(parseBranchName('refs/heads/release/v2.0.1')).toEqual(version(2, 0, 1))
+    expect(parseBranchName('refs/heads/release/n/my-feature')).toEqual(name('my-feature'))
+  })
+
+  it('trims surrounding whitespace', () => {
+    expect(parseBranchName('  release/v1.0.0  ')).toEqual(version(1, 0, 0))
+  })
+
+  it('returns null for non-release branches', () => {
+    expect(parseBranchName('feature/x')).toBeNull()
+    expect(parseBranchName('main')).toBeNull()
+    expect(parseBranchName('dev')).toBeNull()
+  })
+
+  it('returns null for junk under the release/ prefix', () => {
+    expect(parseBranchName('release/foo')).toBeNull()
+    expect(parseBranchName('release/garbage')).toBeNull()
+  })
+
+  it('returns null for incomplete version branches', () => {
+    expect(parseBranchName('release/v1.2')).toBeNull()
+    expect(parseBranchName('release/v1')).toBeNull()
+    expect(parseBranchName('release/v1.2.3.4')).toBeNull()
+    expect(parseBranchName('release/vfoo')).toBeNull()
+  })
+
+  it('returns null for invalid names', () => {
+    expect(parseBranchName('release/n/Bad_Name')).toBeNull()
+    expect(parseBranchName('release/n/UPPER')).toBeNull()
+    expect(parseBranchName('release/n/main')).toBeNull()
+    expect(parseBranchName('release/n/')).toBeNull()
+  })
+
+  it('never throws on arbitrary input', () => {
+    expect(() => {
+      return parseBranchName('')
+    }).not.toThrow()
+    expect(() => {
+      return parseBranchName('!!!')
+    }).not.toThrow()
+    expect(parseBranchName('')).toBeNull()
+  })
+})
+
+describe('parseReleaseRef', () => {
+  it('delegates a release branch ref to parseBranchName', () => {
+    expect(parseReleaseRef('release/v1.2.3')).toEqual(version(1, 2, 3))
+    expect(parseReleaseRef('release/n/checkout-redesign')).toEqual(name('checkout-redesign'))
+    expect(parseReleaseRef('refs/heads/release/v3.4.5')).toEqual(version(3, 4, 5))
+  })
+
+  it('throws when a release branch ref is invalid', () => {
+    expect(() => {
+      return parseReleaseRef('release/garbage')
+    }).toThrow(InvalidReleaseRefError)
+    expect(() => {
+      return parseReleaseRef('release/v1.2')
+    }).toThrow(InvalidReleaseRefError)
+    expect(() => {
+      return parseReleaseRef('release/n/Bad_Name')
+    }).toThrow(InvalidReleaseRefError)
+  })
+
+  it('parses a bare semver token as a version', () => {
+    expect(parseReleaseRef('1.2.3')).toEqual(version(1, 2, 3))
+  })
+
+  it('parses a v-prefixed semver token as a version (normalized raw)', () => {
+    expect(parseReleaseRef('v1.2.3')).toEqual(version(1, 2, 3))
+    expect(parseReleaseRef('v1.2.3').raw).toBe('1.2.3')
+  })
+
+  it('parses a kebab name as a name', () => {
+    expect(parseReleaseRef('checkout-redesign')).toEqual(name('checkout-redesign'))
+  })
+
+  it('throws on the next token (must be resolved before ref parsing)', () => {
+    expect(() => {
+      return parseReleaseRef('next')
+    }).toThrow(InvalidReleaseRefError)
+    expect(() => {
+      return parseReleaseRef('next')
+    }).toThrow(/computeNextVersion/)
+  })
+
+  it('throws on an invalid token with the validation reason', () => {
+    expect(() => {
+      return parseReleaseRef('Bad_Name')
+    }).toThrow(InvalidReleaseRefError)
+    expect(() => {
+      return parseReleaseRef('main')
+    }).toThrow(InvalidReleaseRefError)
+  })
+
+  it('trims input before classifying', () => {
+    expect(parseReleaseRef('  1.2.3  ')).toEqual(version(1, 2, 3))
+    expect(parseReleaseRef('  checkout-redesign ')).toEqual(name('checkout-redesign'))
+  })
+})
+
+describe('validateName', () => {
+  it('accepts simple kebab-case names', () => {
+    expect(() => {
+      return validateName('a')
+    }).not.toThrow()
+    expect(() => {
+      return validateName('a-b-c')
+    }).not.toThrow()
+    expect(() => {
+      return validateName('1-2-3')
+    }).not.toThrow()
+    expect(() => {
+      return validateName('checkout-redesign')
+    }).not.toThrow()
+  })
+
+  it('rejects non-kebab tokens', () => {
+    expect(() => {
+      return validateName('-a')
+    }).toThrow(InvalidReleaseNameError)
+    expect(() => {
+      return validateName('a-')
+    }).toThrow(InvalidReleaseNameError)
+    expect(() => {
+      return validateName('a--b')
+    }).toThrow(InvalidReleaseNameError)
+    expect(() => {
+      return validateName('A-b')
+    }).toThrow(InvalidReleaseNameError)
+    expect(() => {
+      return validateName('a_b')
+    }).toThrow(InvalidReleaseNameError)
+  })
+
+  it('rejects an empty name', () => {
+    expect(() => {
+      return validateName('')
+    }).toThrow(InvalidReleaseNameError)
+  })
+
+  it('rejects each reserved word', () => {
+    for (const reserved of ['dev', 'main', 'next', 'hotfix', 'regular', 'release']) {
+      expect(() => {
+        return validateName(reserved)
+      }).toThrow(InvalidReleaseNameError)
+    }
+  })
+
+  it('rejects a name of length 51 but accepts length 50', () => {
+    expect(() => {
+      return validateName('a'.repeat(50))
+    }).not.toThrow()
+    expect(() => {
+      return validateName('a'.repeat(51))
+    }).toThrow(InvalidReleaseNameError)
+  })
+
+  it('rejects semver-looking tokens via the kebab rule', () => {
+    expect(() => {
+      return validateName('1.2.3')
+    }).toThrow(InvalidReleaseNameError)
+    expect(() => {
+      return validateName('v1.2.3')
+    }).toThrow(InvalidReleaseNameError)
+  })
+})
+
+describe('formatBranchName', () => {
+  it('formats versions and names', () => {
+    expect(formatBranchName(version(1, 2, 3))).toBe('release/v1.2.3')
+    expect(formatBranchName(name('checkout-redesign'))).toBe('release/n/checkout-redesign')
+  })
+})
+
+describe('formatPrTitle', () => {
+  it('formats versioned regular and hotfix titles', () => {
+    expect(formatPrTitle(version(1, 2, 3), 'regular')).toBe('Release v1.2.3')
+    expect(formatPrTitle(version(1, 2, 3), 'hotfix')).toBe('Hotfix v1.2.3')
+  })
+
+  it('formats named regular and hotfix titles', () => {
+    expect(formatPrTitle(name('checkout-redesign'), 'regular')).toBe('Release checkout-redesign')
+    expect(formatPrTitle(name('checkout-redesign'), 'hotfix')).toBe('Hotfix checkout-redesign')
+  })
+})
+
+describe('formatRcTitle', () => {
+  it('formats versioned and named RC titles', () => {
+    expect(formatRcTitle(version(1, 2, 3))).toBe('Release v1.2.3 (RC)')
+    expect(formatRcTitle(name('checkout-redesign'))).toBe('Release checkout-redesign (RC)')
+  })
+})
+
+describe('formatJiraName', () => {
+  it('formats versioned and named Jira names', () => {
+    expect(formatJiraName(version(1, 2, 3))).toBe('v1.2.3')
+    expect(formatJiraName(name('checkout-redesign'))).toBe('checkout-redesign')
+  })
+})
+
+describe('displayLabel', () => {
+  it('formats versioned and named labels', () => {
+    expect(displayLabel(version(1, 2, 3))).toBe('1.2.3')
+    expect(displayLabel(name('checkout-redesign'))).toBe('checkout-redesign')
+  })
+})
+
+describe('isReleaseBranch', () => {
+  it('returns true for both branch schemes', () => {
+    expect(isReleaseBranch('release/v1.2.3')).toBe(true)
+    expect(isReleaseBranch('release/n/checkout-redesign')).toBe(true)
+    expect(isReleaseBranch('refs/heads/release/v1.2.3')).toBe(true)
+  })
+
+  it('returns false for junk', () => {
+    expect(isReleaseBranch('feature/x')).toBe(false)
+    expect(isReleaseBranch('release/foo')).toBe(false)
+    expect(isReleaseBranch('main')).toBe(false)
+  })
+
+  it('returns false for null and undefined', () => {
+    expect(isReleaseBranch(null)).toBe(false)
+    expect(isReleaseBranch(undefined)).toBe(false)
+  })
+})
+
+describe('compareReleaseIds', () => {
+  it('sorts pure-version arrays in numeric semver order (not lexicographic)', () => {
+    const ids = [version(1, 10, 0), version(1, 9, 0), version(2, 0, 0), version(1, 9, 5)]
+    const sorted = [...ids].sort((a, b) => {
+      return compareReleaseIds(a, b)
+    })
+
+    expect(sorted).toEqual([version(1, 9, 0), version(1, 9, 5), version(1, 10, 0), version(2, 0, 0)])
+  })
+
+  it('matches existing semver order byte-for-byte for the all-versioned case', () => {
+    const raws = [version(1, 62, 0), version(1, 64, 5), version(1, 63, 0)]
+      .sort((a, b) => {
+        return compareReleaseIds(a, b)
+      })
+      .map((id) => {
+        return displayLabel(id)
+      })
+
+    expect(raws).toEqual(['1.62.0', '1.63.0', '1.64.5'])
+  })
+
+  it('places all names after all versions regardless of comparison order', () => {
+    expect(compareReleaseIds(version(9, 9, 9), name('aaa'))).toBeLessThan(0)
+    expect(compareReleaseIds(name('aaa'), version(0, 0, 0))).toBeGreaterThan(0)
+  })
+
+  it('produces a versions-block-then-names-block when sorted', () => {
+    const ids = [name('zeta'), version(2, 0, 0), name('alpha'), version(1, 0, 0)]
+    const sorted = [...ids].sort((a, b) => {
+      return compareReleaseIds(a, b)
+    })
+
+    expect(sorted).toEqual([version(1, 0, 0), version(2, 0, 0), name('alpha'), name('zeta')])
+  })
+
+  it('orders names by date ascending when both dates are provided', () => {
+    const result = compareReleaseIds(name('zzz'), name('aaa'), {
+      a: '2026-01-01T00:00:00Z',
+      b: '2026-02-01T00:00:00Z',
+    })
+
+    // zzz is earlier by date, so it sorts first despite later lexicographically.
+    expect(result).toBeLessThan(0)
+  })
+
+  it('accepts Date objects for name dates', () => {
+    const result = compareReleaseIds(name('aaa'), name('zzz'), {
+      a: new Date('2026-03-01T00:00:00Z'),
+      b: new Date('2026-01-01T00:00:00Z'),
+    })
+
+    // aaa is later by date, so it sorts after zzz.
+    expect(result).toBeGreaterThan(0)
+  })
+
+  it('falls back to lexicographic name order when dates are absent', () => {
+    expect(compareReleaseIds(name('alpha'), name('beta'))).toBeLessThan(0)
+    expect(compareReleaseIds(name('beta'), name('alpha'))).toBeGreaterThan(0)
+    expect(compareReleaseIds(name('same'), name('same'))).toBe(0)
+  })
+
+  it('falls back to lexicographic order when only one date is present', () => {
+    expect(compareReleaseIds(name('alpha'), name('beta'), { a: '2026-05-01T00:00:00Z' })).toBeLessThan(0)
+  })
+
+  it('falls back to lexicographic order when dates are equal', () => {
+    const date = '2026-01-01T00:00:00Z'
+
+    expect(compareReleaseIds(name('alpha'), name('beta'), { a: date, b: date })).toBeLessThan(0)
+  })
+
+  it('ignores invalid date strings and falls back to lexicographic order', () => {
+    expect(compareReleaseIds(name('alpha'), name('beta'), { a: 'not-a-date', b: 'also-bad' })).toBeLessThan(0)
+  })
+
+  it('is stable and deterministic across repeated sorts', () => {
+    const ids = [name('b'), version(1, 0, 0), name('a'), version(0, 5, 0), name('c')]
+    const first = [...ids].sort((a, b) => {
+      return compareReleaseIds(a, b)
+    })
+    const second = [...ids].sort((a, b) => {
+      return compareReleaseIds(a, b)
+    })
+
+    expect(first).toEqual(second)
+    expect(first).toEqual([version(0, 5, 0), version(1, 0, 0), name('a'), name('b'), name('c')])
+  })
+})

package/src/lib/release-id/__tests__/versioned-regression.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from 'vitest'
+
+import {
+  compareReleaseIds,
+  displayLabel,
+  formatBranchName,
+  formatJiraName,
+  formatPrTitle,
+  formatRcTitle,
+  parseBranchName,
+  parseReleaseRef,
+} from 'src/lib/release-id'
+import { sortVersions } from 'src/lib/version-utils'
+
+/**
+ * Regression lock for the named-releases feature (plan Principle 2):
+ * a VERSIONED release must produce byte-identical branch names, PR titles,
+ * RC titles, Jira version names, display labels, and sort order to the
+ * pre-named-releases behavior. If any assertion here fails, versioned
+ * releases have regressed.
+ */
+describe('versioned-release output regression', () => {
+  const id = parseReleaseRef('1.62.0')
+
+  it('derives byte-identical strings for a versioned release', () => {
+    expect(formatBranchName(id)).toBe('release/v1.62.0')
+    expect(formatPrTitle(id, 'regular')).toBe('Release v1.62.0')
+    expect(formatPrTitle(id, 'hotfix')).toBe('Hotfix v1.62.0')
+    expect(formatRcTitle(id)).toBe('Release v1.62.0 (RC)')
+    expect(formatJiraName(id)).toBe('v1.62.0')
+    expect(displayLabel(id)).toBe('1.62.0')
+  })
+
+  it('accepts the historical input forms for the same version', () => {
+    for (const input of ['1.62.0', 'v1.62.0', 'release/v1.62.0']) {
+      expect(formatBranchName(parseReleaseRef(input))).toBe('release/v1.62.0')
+    }
+
+    expect(parseBranchName('release/v1.62.0')).toEqual(id)
+  })
+
+  it('sorts pure-version branch lists in the same order as legacy sortVersions', () => {
+    const branches = ['release/v1.10.0', 'release/v1.9.3', 'release/v2.0.0', 'release/v1.9.10', 'release/v1.62.0']
+
+    const expectedOrder = ['release/v1.9.3', 'release/v1.9.10', 'release/v1.10.0', 'release/v1.62.0', 'release/v2.0.0']
+
+    const newOrder = [...branches].sort((a, b) => {
+      const idA = parseBranchName(a)
+      const idB = parseBranchName(b)
+
+      if (idA === null || idB === null) throw new Error('unexpected unparseable version branch')
+
+      return compareReleaseIds(idA, idB)
+    })
+
+    expect(newOrder).toEqual(expectedOrder)
+
+    // Cross-check against legacy sortVersions on its v-token contract.
+    const asToken = (branch: string): string => {
+      const id = parseBranchName(branch)
+
+      if (id === null) throw new Error('unexpected unparseable version branch')
+
+      return `v${displayLabel(id)}`
+    }
+
+    expect(newOrder.map(asToken)).toEqual(sortVersions(branches.map(asToken)))
+  })
+})

package/src/lib/release-id/index.ts

@@ -0,0 +1,15 @@
+export {
+  compareReleaseIds,
+  displayLabel,
+  formatBranchName,
+  formatJiraName,
+  formatPrTitle,
+  formatRcTitle,
+  InvalidReleaseNameError,
+  InvalidReleaseRefError,
+  isReleaseBranch,
+  parseBranchName,
+  parseReleaseRef,
+  type ReleaseId,
+  validateName,
+} from './release-id'

package/src/lib/release-id/release-id.ts

@@ -0,0 +1,257 @@
+/**
+ * A release identity is either a semantic version or a free-form kebab-case
+ * name. `raw` is the canonical token for the id: the no-`v` semver string for
+ * versions (e.g. `1.2.3`) and the name itself for named releases.
+ */
+export type ReleaseId =
+  | { kind: 'version'; semver: { major: number; minor: number; patch: number }; raw: string }
+  | { kind: 'name'; name: string; raw: string }
+
+/** Matches a bare or `v`-prefixed semver token, e.g. `1.2.3` or `v1.2.3`. */
+const VERSION_RE = /^v?(\d+)\.(\d+)\.(\d+)$/
+
+/** Matches the semver core after the `v` in a `release/v…` branch. */
+const BRANCH_SEMVER_RE = /^(\d+)\.(\d+)\.(\d+)$/
+
+/** Kebab-case: lowercase alphanumeric segments joined by single hyphens. */
+const KEBAB_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/
+
+const RELEASE_BRANCH_PREFIX = 'release/'
+const VERSION_BRANCH_PREFIX = 'release/v'
+const NAME_BRANCH_PREFIX = 'release/n/'
+const REFS_HEADS_PREFIX = 'refs/heads/'
+
+const NEXT_TOKEN = 'next'
+const MAX_NAME_LENGTH = 50
+
+/**
+ * Names that would collide with branch/release semantics or read as a special
+ * token. Banned regardless of kebab-case validity.
+ */
+const RESERVED_NAMES: ReadonlySet<string> = new Set(['dev', 'main', 'next', 'hotfix', 'regular', 'release'])
+
+/** Thrown by {@link validateName} when a release name is not acceptable. */
+export class InvalidReleaseNameError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'InvalidReleaseNameError'
+  }
+}
+
+/** Thrown by {@link parseReleaseRef} when a release ref cannot be parsed. */
+export class InvalidReleaseRefError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'InvalidReleaseRefError'
+  }
+}
+
+const stripRefsHeads = (input: string): string => {
+  return input.startsWith(REFS_HEADS_PREFIX) ? input.slice(REFS_HEADS_PREFIX.length) : input
+}
+
+const makeVersion = (major: number, minor: number, patch: number): ReleaseId => {
+  return {
+    kind: 'version',
+    semver: { major, minor, patch },
+    raw: `${major}.${minor}.${patch}`,
+  }
+}
+
+/**
+ * Validate a release name. Throws {@link InvalidReleaseNameError} with a
+ * specific message unless the name is kebab-case, at most 50 characters, and
+ * not a reserved word. Semver-looking tokens (e.g. `1.2.3`) are already
+ * excluded by the kebab-case rule since they contain dots.
+ */
+export const validateName = (name: string): void => {
+  if (name.length === 0) {
+    throw new InvalidReleaseNameError('Release name is empty. Provide a kebab-case name like "checkout-redesign".')
+  }
+
+  if (name.length > MAX_NAME_LENGTH) {
+    throw new InvalidReleaseNameError(
+      `Release name "${name}" is ${name.length} characters; the maximum is ${MAX_NAME_LENGTH}.`,
+    )
+  }
+
+  if (!KEBAB_RE.test(name)) {
+    throw new InvalidReleaseNameError(
+      `Release name "${name}" is not kebab-case. Use lowercase letters, digits, and single hyphens, e.g. "checkout-redesign".`,
+    )
+  }
+
+  if (RESERVED_NAMES.has(name)) {
+    throw new InvalidReleaseNameError(
+      `Release name "${name}" is reserved. Reserved names: ${[...RESERVED_NAMES].join(', ')}.`,
+    )
+  }
+}
+
+/**
+ * Lenient parse of a git branch name into a {@link ReleaseId}. Tolerates a
+ * leading `refs/heads/`. Returns `null` for anything that is not a valid
+ * `release/v<semver>` or `release/n/<name>` branch. Never throws.
+ */
+export const parseBranchName = (branch: string): ReleaseId | null => {
+  const stripped = stripRefsHeads(branch.trim())
+
+  if (stripped.startsWith(VERSION_BRANCH_PREFIX)) {
+    const semverPart = stripped.slice(VERSION_BRANCH_PREFIX.length)
+    const match = BRANCH_SEMVER_RE.exec(semverPart)
+
+    if (!match) return null
+
+    return makeVersion(Number(match[1]), Number(match[2]), Number(match[3]))
+  }
+
+  if (stripped.startsWith(NAME_BRANCH_PREFIX)) {
+    const namePart = stripped.slice(NAME_BRANCH_PREFIX.length)
+
+    try {
+      validateName(namePart)
+    } catch {
+      return null
+    }
+
+    return { kind: 'name', name: namePart, raw: namePart }
+  }
+
+  return null
+}
+
+/**
+ * Strict parse of a release ref into a {@link ReleaseId}. Throws
+ * {@link InvalidReleaseRefError} on invalid input. Precedence (order matters):
+ *   1. `release/…` (or `refs/heads/release/…`) → delegate to parseBranchName.
+ *   2. semver token (`1.2.3` / `v1.2.3`) → version.
+ *   3. `next` → throws; callers must resolve `next` to a concrete version
+ *      via computeNextVersion before calling this.
+ *   4. otherwise → validateName, returning a named release.
+ */
+export const parseReleaseRef = (input: string): ReleaseId => {
+  const trimmed = input.trim()
+  const branchCandidate = stripRefsHeads(trimmed)
+
+  if (branchCandidate.startsWith(RELEASE_BRANCH_PREFIX)) {
+    const parsed = parseBranchName(trimmed)
+
+    if (!parsed) {
+      throw new InvalidReleaseRefError(
+        `"${input}" looks like a release branch but is not a valid release/v<semver> or release/n/<name> ref.`,
+      )
+    }
+
+    return parsed
+  }
+
+  const versionMatch = VERSION_RE.exec(trimmed)
+
+  if (versionMatch) {
+    return makeVersion(Number(versionMatch[1]), Number(versionMatch[2]), Number(versionMatch[3]))
+  }
+
+  if (trimmed.toLowerCase() === NEXT_TOKEN) {
+    throw new InvalidReleaseRefError(
+      'The "next" token must be resolved to a concrete version (via computeNextVersion) before parsing a release ref.',
+    )
+  }
+
+  try {
+    validateName(trimmed)
+  } catch (err) {
+    const reason = err instanceof Error ? err.message : String(err)
+
+    throw new InvalidReleaseRefError(`Cannot parse "${input}" as a release ref: ${reason}`)
+  }
+
+  return { kind: 'name', name: trimmed, raw: trimmed }
+}
+
+/** Render the branch name for a release id: `release/v1.2.3` | `release/n/<name>`. */
+export const formatBranchName = (id: ReleaseId): string => {
+  if (id.kind === 'version') return `${VERSION_BRANCH_PREFIX}${id.raw}`
+
+  return `${NAME_BRANCH_PREFIX}${id.name}`
+}
+
+/**
+ * Render a PR title: `Release v1.2.3` / `Hotfix v1.2.3` for versions,
+ * `Release <name>` / `Hotfix <name>` for names.
+ */
+export const formatPrTitle = (id: ReleaseId, type: 'regular' | 'hotfix'): string => {
+  const prefix = type === 'hotfix' ? 'Hotfix' : 'Release'
+
+  if (id.kind === 'version') return `${prefix} v${id.raw}`
+
+  return `${prefix} ${id.name}`
+}
+
+/** Render a release-candidate PR title: `Release v1.2.3 (RC)` | `Release <name> (RC)`. */
+export const formatRcTitle = (id: ReleaseId): string => {
+  if (id.kind === 'version') return `Release v${id.raw} (RC)`
+
+  return `Release ${id.name} (RC)`
+}
+
+/** Render the Jira fix-version name: `v1.2.3` | `<name>`. */
+export const formatJiraName = (id: ReleaseId): string => {
+  if (id.kind === 'version') return `v${id.raw}`
+
+  return id.name
+}
+
+/** Render a short human display label: `1.2.3` | `<name>`. */
+export const displayLabel = (id: ReleaseId): string => {
+  return id.raw
+}
+
+/** True iff `branch` is a valid release branch under either scheme. */
+export const isReleaseBranch = (branch: string | null | undefined): boolean => {
+  if (branch === null || branch === undefined) return false
+
+  return parseBranchName(branch) !== null
+}
+
+const toTime = (value: string | Date | undefined): number | null => {
+  if (value === undefined) return null
+
+  const time = value instanceof Date ? value.getTime() : new Date(value).getTime()
+
+  return Number.isNaN(time) ? null : time
+}
+
+/**
+ * Comparator for {@link ReleaseId} values (locked ordering):
+ *   - All versions sort before all names.
+ *   - Versions: semver ascending (major, then minor, then patch; numeric).
+ *   - Names: by date ascending when both dates are provided, otherwise
+ *     lexicographic by name. The result is stable and deterministic.
+ */
+export const compareReleaseIds = (
+  a: ReleaseId,
+  b: ReleaseId,
+  dates?: { a?: string | Date; b?: string | Date },
+): number => {
+  if (a.kind === 'version' && b.kind === 'version') {
+    if (a.semver.major !== b.semver.major) return a.semver.major - b.semver.major
+    if (a.semver.minor !== b.semver.minor) return a.semver.minor - b.semver.minor
+
+    return a.semver.patch - b.semver.patch
+  }
+
+  if (a.kind === 'version') return -1
+  if (b.kind === 'version') return 1
+
+  const timeA = toTime(dates?.a)
+  const timeB = toTime(dates?.b)
+
+  if (timeA !== null && timeB !== null && timeA !== timeB) {
+    return timeA - timeB
+  }
+
+  if (a.name < b.name) return -1
+  if (a.name > b.name) return 1
+
+  return 0
+}