infra-kit 0.1.102 → 0.1.105

package/src/lib/package-validator/loader/config-loader.ts

@@ -0,0 +1,77 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { z } from 'zod'
+
+import { DEFAULT_RULES, packageConfigSchema, resolvePackageConfig } from 'src/lib/package-config'
+import type { ResolvedPackageRules } from 'src/lib/package-config'
+
+import { pathExists } from '../fs-utils'
+
+/** Per-package config filename every validated package must provide. */
+export const PACKAGE_CONFIG_FILE = 'infra-kit.config.ts'
+
+interface PackageJsonShape {
+  name?: string
+  scripts?: Record<string, string>
+}
+
+/**
+ * Read and JSON-parse a package.json, returning an empty object when it is
+ * missing or unreadable so callers can degrade into a clear "missing" check.
+ */
+export const readPackageJson = async (packageDir: string): Promise<PackageJsonShape> => {
+  try {
+    const raw = await fs.readFile(path.join(packageDir, 'package.json'), 'utf-8')
+
+    return JSON.parse(raw) as PackageJsonShape
+  } catch {
+    return {}
+  }
+}
+
+/**
+ * Load, resolve, and validate a package's `infra-kit.config.ts`.
+ *
+ * Dynamic-imports the file (ESM), resolves the Vite-style factory or object
+ * default export, validates the result against {@link packageConfigSchema}, and
+ * merges it over the defaults. Throws a descriptive error when the file is
+ * absent or the resolved config violates the schema.
+ *
+ * @example
+ * await loadPackageConfig('/repo/packages/serverless-config')
+ * // => { requiredScripts: [], requiredFiles: ['serverless.common.yml'], turboTasks: [] }
+ */
+export const loadPackageConfig = async (
+  packageDir: string,
+  baseline: Readonly<ResolvedPackageRules> = DEFAULT_RULES,
+): Promise<ResolvedPackageRules> => {
+  const configPath = path.join(packageDir, PACKAGE_CONFIG_FILE)
+
+  if (!(await pathExists(configPath))) {
+    throw new Error(`${PACKAGE_CONFIG_FILE} not found at ${configPath}`)
+  }
+
+  // Cache-bust with the file mtime so repeated loads (long-running MCP server)
+  // pick up edits without a process restart. `.ts` configs load via Node's
+  // native type stripping (the repo requires Node >= 24).
+  const stat = await fs.stat(configPath)
+  const moduleUrl = `${pathToFileURL(configPath).href}?mtime=${Number(stat.mtimeMs)}`
+
+  const imported = (await import(moduleUrl)) as { default?: unknown }
+  const rawExport = imported.default
+
+  if (rawExport === undefined) {
+    throw new Error(`${PACKAGE_CONFIG_FILE} at ${configPath} has no default export`)
+  }
+
+  const resolvedExport = typeof rawExport === 'function' ? await (rawExport as () => unknown)() : rawExport
+
+  const parsed = packageConfigSchema.safeParse(resolvedExport)
+
+  if (!parsed.success) {
+    throw new Error(`Invalid ${PACKAGE_CONFIG_FILE} at ${configPath}: ${z.prettifyError(parsed.error)}`)
+  }
+
+  return resolvePackageConfig(parsed.data, baseline)
+}

package/src/lib/package-validator/loader/index.ts

@@ -0,0 +1,2 @@
+export { loadPackageConfig, PACKAGE_CONFIG_FILE, readPackageJson } from './config-loader'
+export { discoverPackages } from './package-discovery'

package/src/lib/package-validator/loader/package-discovery.ts

@@ -0,0 +1,98 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import yaml from 'yaml'
+
+import { pathExists } from '../fs-utils'
+
+const WORKSPACE_FILE = 'pnpm-workspace.yaml'
+
+/**
+ * List the immediate child directories of `dir`, returning `[]` when the path
+ * can't be read (e.g. the parent glob segment matched a non-existent dir).
+ */
+const listChildDirs = async (dir: string): Promise<string[]> => {
+  const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => {
+    return []
+  })
+
+  return entries
+    .filter((entry) => {
+      return entry.isDirectory()
+    })
+    .map((entry) => {
+      return path.join(dir, entry.name)
+    })
+}
+
+/**
+ * Apply one glob segment to a set of directories: `*` fans out to every child
+ * directory, a literal segment keeps the dirs where that child path exists.
+ */
+const expandSegment = async (dirs: string[], segment: string): Promise<string[]> => {
+  const next: string[] = []
+
+  for (const dir of dirs) {
+    if (segment === '*') {
+      next.push(...(await listChildDirs(dir)))
+
+      continue
+    }
+
+    const candidate = path.join(dir, segment)
+
+    if (await pathExists(candidate)) {
+      next.push(candidate)
+    }
+  }
+
+  return next
+}
+
+/**
+ * Expand a single pnpm-workspace glob (only the `*` segment wildcard is
+ * supported, which covers every pattern this monorepo uses) into directories.
+ */
+const expandGlob = async (projectRoot: string, pattern: string): Promise<string[]> => {
+  let dirs = [projectRoot]
+
+  for (const segment of pattern.split('/')) {
+    dirs = await expandSegment(dirs, segment)
+  }
+
+  return dirs
+}
+
+/**
+ * Discover validatable workspace packages from `pnpm-workspace.yaml`.
+ *
+ * Negation patterns (`!…`) and everything under `vendor/` are excluded —
+ * vendor is mirrored from `starter-workspace` and is checksum-enforced by
+ * `pnpm vendor:check`, so its configs are owned upstream, not here. Only
+ * directories that actually contain a package.json are returned.
+ *
+ * @example
+ * await discoverPackages('/repo')
+ * // => ['/repo/apps/infra-kit/cli', '/repo/packages/serverless-config']
+ */
+export const discoverPackages = async (projectRoot: string): Promise<string[]> => {
+  const raw = await fs.readFile(path.join(projectRoot, WORKSPACE_FILE), 'utf-8')
+  const parsed = (yaml.parse(raw) ?? {}) as { packages?: string[] }
+
+  const patterns = (parsed.packages ?? []).filter((pattern) => {
+    return !pattern.startsWith('!') && !pattern.startsWith('vendor')
+  })
+
+  const found = new Set<string>()
+
+  for (const pattern of patterns) {
+    const dirs = await expandGlob(projectRoot, pattern)
+
+    for (const dir of dirs) {
+      if (await pathExists(path.join(dir, 'package.json'))) {
+        found.add(dir)
+      }
+    }
+  }
+
+  return [...found].sort()
+}

package/src/lib/package-validator/package-validator.ts

@@ -0,0 +1,48 @@
+import path from 'node:path'
+
+import { DEFAULT_RULES } from 'src/lib/package-config'
+import type { ResolvedPackageRules } from 'src/lib/package-config'
+
+import { checkConfig, checkFiles, checkScripts, checkTurbo } from './checks'
+import { readPackageJson } from './loader'
+import type { PackageCheck, PackageValidationResult } from './types'
+
+// Re-exported on the historical import path so consumers and tests that reach
+// for the loader through `package-validator` keep resolving after the split.
+export { discoverPackages, loadPackageConfig } from './loader'
+export type { PackageCheck, PackageValidationResult } from './types'
+
+/**
+ * Validate a single directory against its `infra-kit.config.ts` rules: the config
+ * must be present and valid, every required script must be declared, every
+ * required file must exist, and (root only) every required turbo task must be
+ * defined. When the config fails to load, only that check is reported (the rules
+ * are unknown, so the rule-based checks are skipped). `baseline` selects which
+ * under-the-hood defaults apply — package defaults or {@link ROOT_DEFAULT_RULES}.
+ *
+ * @example
+ * const result = await validatePackage('/repo/packages/serverless-config')
+ * // result.passed reflects the package's conformance; result.checks lists each check
+ */
+export const validatePackage = async (
+  packageDir: string,
+  baseline: Readonly<ResolvedPackageRules> = DEFAULT_RULES,
+): Promise<PackageValidationResult> => {
+  const pkgJson = await readPackageJson(packageDir)
+  const packageName = pkgJson.name ?? path.basename(packageDir)
+
+  const { check: configCheck, rules } = await checkConfig(packageDir, baseline)
+  const checks: PackageCheck[] = [configCheck]
+
+  if (rules) {
+    checks.push(...checkScripts(pkgJson.scripts ?? {}, rules.requiredScripts))
+    checks.push(...(await checkFiles(packageDir, rules.requiredFiles)))
+    checks.push(...(await checkTurbo(packageDir, rules.turboTasks)))
+  }
+
+  const passed = checks.every((check) => {
+    return check.status === 'pass'
+  })
+
+  return { packageDir, packageName, checks, passed }
+}

package/src/lib/package-validator/types.ts

@@ -0,0 +1,15 @@
+/** Result of a single validation check against one package. */
+export interface PackageCheck {
+  /** Stable identifier for the check, e.g. `infra-kit.config.ts`, `script:build`. */
+  name: string
+  status: 'pass' | 'fail'
+  message: string
+}
+
+/** Aggregate validation outcome for one package directory. */
+export interface PackageValidationResult {
+  packageDir: string
+  packageName: string
+  checks: PackageCheck[]
+  passed: boolean
+}

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'