infra-kit 0.1.102 → 0.1.107

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

@@ -0,0 +1,122 @@
+import { describe, expect, it } from 'vitest'
+
+import { OperationError } from 'src/lib/errors/operation-error'
+
+import {
+  DEV_REF,
+  formatBranchChoices,
+  parseBranchChoices,
+  releaseLabelFromBranch,
+  resolveReleaseBranch,
+} from '../release-utils'
+
+describe('parseBranchChoices', () => {
+  it('parses version and name branches and drops junk', () => {
+    const result = parseBranchChoices([
+      'release/v1.2.3',
+      'release/n/checkout-redesign',
+      'feature/not-a-release',
+      'release/v9.9', // malformed semver
+    ])
+
+    const labels = result.map((r) => {
+      return r.label
+    })
+    const kinds = result.map((r) => {
+      return r.id.kind
+    })
+    const branches = result.map((r) => {
+      return r.branch
+    })
+
+    expect(labels).toEqual(['1.2.3', 'checkout-redesign'])
+    expect(kinds).toEqual(['version', 'name'])
+    expect(branches).toEqual(['release/v1.2.3', 'release/n/checkout-redesign'])
+  })
+
+  it('returns an empty array when nothing parses', () => {
+    expect(parseBranchChoices(['main', 'dev', 'feature/x'])).toEqual([])
+  })
+})
+
+describe('formatBranchChoices', () => {
+  it('labels versions and names, keying Jira descriptions by the Jira version name', () => {
+    const choices = formatBranchChoices({
+      branches: ['release/v1.2.3', 'release/n/checkout-redesign'],
+      // Jira descriptions are keyed by the Jira version NAME: `v1.2.3` | `<name>`.
+      descriptions: new Map([
+        ['v1.2.3', 'version desc'],
+        ['checkout-redesign', 'name desc'],
+      ]),
+    })
+
+    expect(choices).toHaveLength(2)
+    expect(choices[0]?.value).toBe('release/v1.2.3')
+    expect(choices[0]?.name).toContain('1.2.3')
+    expect(choices[0]?.name).toContain('version desc')
+    expect(choices[1]?.value).toBe('release/n/checkout-redesign')
+    expect(choices[1]?.name).toContain('checkout-redesign')
+    expect(choices[1]?.name).toContain('name desc')
+  })
+
+  it('includes the type tag when types are provided', () => {
+    const choices = formatBranchChoices({
+      branches: ['release/n/checkout-redesign'],
+      descriptions: new Map(),
+      types: new Map([['release/n/checkout-redesign', 'hotfix']]),
+    })
+
+    expect(choices[0]?.name).toContain('[hotfix]')
+  })
+
+  it('drops branches that do not parse as release ids', () => {
+    const choices = formatBranchChoices({
+      branches: ['release/v1.2.3', 'feature/not-a-release'],
+      descriptions: new Map(),
+    })
+
+    expect(
+      choices.map((c) => {
+        return c.value
+      }),
+    ).toEqual(['release/v1.2.3'])
+  })
+})
+
+describe('resolveReleaseBranch', () => {
+  it('builds a version branch from a bare or v-prefixed version', () => {
+    expect(resolveReleaseBranch('1.2.3')).toBe('release/v1.2.3')
+    expect(resolveReleaseBranch('v1.2.3')).toBe('release/v1.2.3')
+  })
+
+  it('builds a name branch from a release name', () => {
+    expect(resolveReleaseBranch('checkout-redesign')).toBe('release/n/checkout-redesign')
+  })
+
+  it('throws an OperationError for junk input', () => {
+    expect(() => {
+      return resolveReleaseBranch('Not A Valid Name')
+    }).toThrow(OperationError)
+  })
+
+  it('throws an OperationError for the unresolved "next" token', () => {
+    expect(() => {
+      return resolveReleaseBranch('next')
+    }).toThrow(OperationError)
+  })
+})
+
+describe('releaseLabelFromBranch', () => {
+  it('passes through the dev sentinel unchanged', () => {
+    expect(releaseLabelFromBranch(DEV_REF)).toBe('dev')
+  })
+
+  it('labels version and name branches', () => {
+    expect(releaseLabelFromBranch('release/v1.2.3')).toBe('1.2.3')
+    expect(releaseLabelFromBranch('release/n/checkout-redesign')).toBe('checkout-redesign')
+  })
+
+  it('falls back to the raw branch when it does not parse', () => {
+    expect(releaseLabelFromBranch('feature/not-a-release')).toBe('feature/not-a-release')
+  })
+})

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

@@ -5,7 +5,11 @@ export {
   formatVersionLabel,
   getBaseBranch,
   getJiraDescriptions,
+  parseBranchChoices,
   prepareGitForRelease,
+  releaseBranchLabels,
   type ReleaseCreationResult,
+  releaseLabelFromBranch,
   type ReleaseType,
+  resolveReleaseBranch,
 } from './release-utils'

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

@@ -3,6 +3,12 @@ import { $ } from 'zx'
 import { createReleaseBranch } from 'src/integrations/gh'
 import { createJiraVersion, getProjectVersions, loadJiraConfigOptional } from 'src/integrations/jira'
 import type { JiraConfig } from 'src/integrations/jira'
+import { OperationError } from 'src/lib/errors/operation-error'
+import { displayLabel, formatBranchName, formatJiraName, parseBranchName, parseReleaseRef } from 'src/lib/release-id'
+import type { ReleaseId } from 'src/lib/release-id'
+
+/** Sentinel ref for deploying from the `dev` branch instead of a release branch. */
+export const DEV_REF = 'dev'
 
 export type ReleaseType = 'regular' | 'hotfix'
 
@@ -39,7 +45,7 @@ export const prepareGitForRelease = async (type: ReleaseType = 'regular'): Promi
 }
 
 interface CreateSingleReleaseArgs {
-  version: string
+  id: ReleaseId
   jiraConfig: JiraConfig
   description?: string
   type?: ReleaseType
@@ -49,9 +55,10 @@ interface CreateSingleReleaseArgs {
  * Create a single release by creating both Jira version and GitHub release branch
  */
 export const createSingleRelease = async (args: CreateSingleReleaseArgs): Promise<ReleaseCreationResult> => {
-  const { version, jiraConfig, description, type = 'regular' } = args
-  // 1. Create Jira version (mandatory)
-  const versionName = `v${version}`
+  const { id, jiraConfig, description, type = 'regular' } = args
+  // 1. Create Jira version (mandatory). For versioned releases this is
+  // "v1.2.3" (byte-identical to before); for named releases it is "<name>".
+  const versionName = formatJiraName(id)
 
   const result = await createJiraVersion(
     {
@@ -68,10 +75,10 @@ export const createSingleRelease = async (args: CreateSingleReleaseArgs): Promis
   const jiraVersionUrl = `${jiraConfig.baseUrl}/projects/${result.version!.projectId}/versions/${result.version!.id}/tab/release-report-all-issues`
 
   // 2. Create GitHub release branch
-  const releaseInfo = await createReleaseBranch({ version, jiraVersionUrl, type, description })
+  const releaseInfo = await createReleaseBranch({ id, jiraVersionUrl, type, description })
 
   return {
-    version,
+    version: displayLabel(id),
     type,
     branchName: releaseInfo.branchName,
     prUrl: releaseInfo.prUrl,
@@ -130,32 +137,93 @@ interface FormatBranchChoicesArgs {
   types?: Map<string, ReleaseType>
 }
 
+interface ParsedBranchChoice {
+  branch: string
+  id: ReleaseId
+  /** Human display label: `1.2.3` | `<name>`. */
+  label: string
+}
+
+/**
+ * Parse branches into release ids, dropping any that do not parse (lenient
+ * discovery source). Exported for unit testing the version/name/junk split.
+ */
+export const parseBranchChoices = (branches: string[]): ParsedBranchChoice[] => {
+  return branches.flatMap((branch) => {
+    const id = parseBranchName(branch)
+
+    if (!id) return []
+
+    return [{ branch, id, label: displayLabel(id) }]
+  })
+}
+
+/**
+ * Resolve an operator-supplied release ref (version `1.2.3` / `v1.2.3` or name
+ * `checkout-redesign`) to its branch name (`release/v1.2.3` | `release/n/<name>`).
+ * Strict: surfaces a parse failure as an OperationError with remediation text.
+ */
+export const resolveReleaseBranch = (versionArg: string): string => {
+  try {
+    return formatBranchName(parseReleaseRef(versionArg))
+  } catch (error) {
+    throw new OperationError(error, {
+      operation: `resolve release ref "${versionArg}"`,
+      remediation: 'pass a version (e.g. "1.2.5") or a release name (e.g. "checkout-redesign")',
+    })
+  }
+}
+
+/**
+ * Render the human display label for a release branch. Returns the `dev`
+ * sentinel unchanged; otherwise derives `1.2.3` | `<name>` from the branch.
+ * Falls back to the raw branch when it does not parse as a release id.
+ */
+export const releaseLabelFromBranch = (branch: string): string => {
+  if (branch === DEV_REF) return DEV_REF
+
+  const id = parseBranchName(branch)
+
+  return id ? displayLabel(id) : branch
+}
+
+/**
+ * Render human display labels for a list of release branches, dropping any
+ * branch that does not parse as a release id (lenient discovery contract).
+ */
+export const releaseBranchLabels = (branches: string[]): string[] => {
+  return branches.flatMap((branch) => {
+    const id = parseBranchName(branch)
+
+    return id ? [displayLabel(id)] : []
+  })
+}
+
 /**
  * Format release branch names as checkbox choices with aligned type tags and Jira descriptions
  */
 export const formatBranchChoices = (args: FormatBranchChoicesArgs): { name: string; value: string }[] => {
   const { branches, descriptions, types } = args
 
-  const versionNames = branches.map((b) => {
-    return b.replace('release/v', '')
-  })
+  const parsed = parseBranchChoices(branches)
 
   const maxLen = Math.max(
-    ...versionNames.map((v) => {
-      return v.length
+    0,
+    ...parsed.map((p) => {
+      return p.label.length
     }),
   )
 
-  return branches.map((branch, i) => {
-    const version = versionNames[i] as string
+  return parsed.map(({ branch, id, label }) => {
     const type = types ? types.get(branch) || 'regular' : undefined
-    const desc = descriptions.get(`v${version}`)
-    const padding = ' '.repeat(maxLen - version.length + 3)
+    // Jira-descriptions map is keyed by the Jira version NAME (`v1.2.3` | `<name>`).
+    const desc = descriptions.get(formatJiraName(id))
+    const padding = ' '.repeat(maxLen - label.length + 3)
 
-    let name = type ? formatVersionLabel(version, type, maxLen) : version
+    let name = type ? formatVersionLabel(label, type, maxLen) : label
 
     if (desc) {
-      name = type ? `${name}  ${desc}` : `${version}${padding}${desc}`
+      name = type ? `${name}  ${desc}` : `${label}${padding}${desc}`
     }
 
     return { name, value: branch }

package/src/lib/version-utils/__tests__/load-existing-versions.test.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest'
+
+import { extractVersionBranches } from '../load-existing-versions'
+
+const lsRemoteLine = (ref: string): string => {
+  return `0000000000000000000000000000000000000000\trefs/heads/${ref}`
+}
+
+describe('extractVersionBranches', () => {
+  it('keeps only semver version branches and returns no-v tokens', () => {
+    const stdout = [lsRemoteLine('release/v1.62.0'), lsRemoteLine('release/v1.64.5'), ''].join('\n')
+
+    expect(extractVersionBranches(stdout)).toEqual(['1.62.0', '1.64.5'])
+  })
+
+  it('ignores named release/n/* branches (irrelevant to next-bump math)', () => {
+    const stdout = [
+      lsRemoteLine('release/v1.0.0'),
+      lsRemoteLine('release/n/checkout-redesign'),
+      lsRemoteLine('release/n/zeta-feature'),
+    ].join('\n')
+
+    expect(extractVersionBranches(stdout)).toEqual(['1.0.0'])
+  })
+
+  it('ignores junk and non-release lines without throwing', () => {
+    const stdout = [
+      lsRemoteLine('release/garbage'),
+      lsRemoteLine('release/v2.3.4'),
+      'malformed-line-without-tab',
+      lsRemoteLine('feature/login'),
+      '',
+    ].join('\n')
+
+    expect(extractVersionBranches(stdout)).toEqual(['2.3.4'])
+  })
+})

package/src/lib/version-utils/__tests__/next-version.test.ts

@@ -1,12 +1,26 @@
 import { describe, expect, it } from 'vitest'
 
+import { InvalidReleaseNameError, formatBranchName, formatJiraName, formatPrTitle } from '../../release-id'
+import type { ReleaseId } from '../../release-id'
 import {
   NoPriorVersionsError,
   collectKnownVersions,
   computeNextVersion,
+  hasNextToken,
   parseReleaseSpec,
   resolveReleaseEntries,
 } from '../next-version'
+import type { ReleaseEntry } from '../next-version'
+
+const versionId = (raw: string): ReleaseId => {
+  const [major, minor, patch] = raw.split('.').map(Number)
+
+  return { kind: 'version', semver: { major: major!, minor: minor!, patch: patch! }, raw }
+}
+
+const nameId = (name: string): ReleaseId => {
+  return { kind: 'name', name, raw: name }
+}
 
 describe('collectKnownVersions', () => {
   it('parses remote branch refs and Jira version names and dedupes', () => {
@@ -123,7 +137,7 @@ describe('parseReleaseSpec', () => {
 describe('resolveReleaseEntries', () => {
   const known = collectKnownVersions({ remoteBranches: ['release/v1.63.0'] })
 
-  it('passes through explicit semver entries unchanged', () => {
+  it('passes through explicit semver entries, wrapping them in a version ReleaseId', () => {
     expect(
       resolveReleaseEntries(
         [
@@ -133,14 +147,14 @@ describe('resolveReleaseEntries', () => {
         known,
       ),
     ).toEqual([
-      { version: '1.70.0', type: 'regular' },
-      { version: '1.70.1', type: 'hotfix' },
+      { id: versionId('1.70.0'), type: 'regular' },
+      { id: versionId('1.70.1'), type: 'hotfix' },
     ])
   })
 
   it('resolves a single "next" using the entry type', () => {
     expect(resolveReleaseEntries([{ version: 'next', type: 'regular' }], known)).toEqual([
-      { version: '1.64.0', type: 'regular' },
+      { id: versionId('1.64.0'), type: 'regular' },
     ])
   })
 
@@ -154,8 +168,8 @@ describe('resolveReleaseEntries', () => {
         known,
       ),
     ).toEqual([
-      { version: '1.64.0', type: 'regular' },
-      { version: '1.65.0', type: 'regular' },
+      { id: versionId('1.64.0'), type: 'regular' },
+      { id: versionId('1.65.0'), type: 'regular' },
     ])
   })
 
@@ -169,8 +183,8 @@ describe('resolveReleaseEntries', () => {
         known,
       ),
     ).toEqual([
-      { version: '1.64.0', type: 'regular' },
-      { version: '1.64.1', type: 'hotfix' },
+      { id: versionId('1.64.0'), type: 'regular' },
+      { id: versionId('1.64.1'), type: 'hotfix' },
     ])
   })
 
@@ -185,21 +199,21 @@ describe('resolveReleaseEntries', () => {
         known,
       ),
     ).toEqual([
-      { version: '1.64.0', type: 'regular' },
-      { version: '1.70.0', type: 'regular' },
-      { version: '1.71.0', type: 'regular' },
+      { id: versionId('1.64.0'), type: 'regular' },
+      { id: versionId('1.70.0'), type: 'regular' },
+      { id: versionId('1.71.0'), type: 'regular' },
     ])
   })
 
   it('preserves description through resolution', () => {
     expect(resolveReleaseEntries([{ version: 'next', type: 'regular', description: 'Holiday' }], known)).toEqual([
-      { version: '1.64.0', type: 'regular', description: 'Holiday' },
+      { id: versionId('1.64.0'), type: 'regular', description: 'Holiday' },
     ])
   })
 
   it('accepts case-insensitive "next"', () => {
     expect(resolveReleaseEntries([{ version: 'NEXT', type: 'regular' }], known)).toEqual([
-      { version: '1.64.0', type: 'regular' },
+      { id: versionId('1.64.0'), type: 'regular' },
     ])
   })
 
@@ -214,4 +228,96 @@ describe('resolveReleaseEntries', () => {
       return resolveReleaseEntries([{ version: 'next', type: 'regular' }], [])
     }).toThrow(NoPriorVersionsError)
   })
+
+  describe('named entries', () => {
+    it('resolves a valid name into a name ReleaseId', () => {
+      expect(resolveReleaseEntries([{ name: 'checkout-redesign', type: 'regular' }], known)).toEqual([
+        { id: nameId('checkout-redesign'), type: 'regular' },
+      ])
+    })
+
+    it('preserves type and description on named entries (named hotfix allowed)', () => {
+      expect(
+        resolveReleaseEntries([{ name: 'checkout-redesign', type: 'hotfix', description: 'Q3 work' }], known),
+      ).toEqual([{ id: nameId('checkout-redesign'), type: 'hotfix', description: 'Q3 work' }])
+    })
+
+    it('never auto-bumps a named entry (no version interaction)', () => {
+      expect(
+        resolveReleaseEntries(
+          [
+            { name: 'first-thing', type: 'regular' },
+            { version: 'next', type: 'regular' },
+          ],
+          known,
+        ),
+      ).toEqual([
+        { id: nameId('first-thing'), type: 'regular' },
+        { id: versionId('1.64.0'), type: 'regular' },
+      ])
+    })
+
+    it('throws InvalidReleaseNameError on an invalid (non-kebab) name', () => {
+      expect(() => {
+        return resolveReleaseEntries([{ name: 'Checkout_Redesign', type: 'regular' }], known)
+      }).toThrow(InvalidReleaseNameError)
+    })
+
+    it('throws InvalidReleaseNameError when the name is the reserved word "next"', () => {
+      expect(() => {
+        return resolveReleaseEntries([{ name: 'next', type: 'regular' }], known)
+      }).toThrow(InvalidReleaseNameError)
+    })
+  })
+
+  describe('formatting round-trip (zero-regression for versioned, correct for named)', () => {
+    const resolve = (entry: Parameters<typeof resolveReleaseEntries>[0][number]): ReleaseEntry => {
+      return resolveReleaseEntries([entry], known)[0] as ReleaseEntry
+    }
+
+    it('versioned literal "1.62.0" produces byte-identical branch/PR/Jira output', () => {
+      const { id } = resolve({ version: '1.62.0', type: 'regular' })
+
+      expect(formatBranchName(id)).toBe('release/v1.62.0')
+      expect(formatPrTitle(id, 'regular')).toBe('Release v1.62.0')
+      expect(formatJiraName(id)).toBe('v1.62.0')
+    })
+
+    it('versioned "next" resolves then formats identically to the equivalent literal', () => {
+      const { id } = resolve({ version: 'next', type: 'regular' })
+
+      // known max is 1.63.0 → regular next is 1.64.0
+      expect(formatBranchName(id)).toBe('release/v1.64.0')
+      expect(formatPrTitle(id, 'hotfix')).toBe('Hotfix v1.64.0')
+      expect(formatJiraName(id)).toBe('v1.64.0')
+    })
+
+    it('named entry produces the named branch/PR/Jira output', () => {
+      const { id } = resolve({ name: 'checkout-redesign', type: 'regular' })
+
+      expect(formatBranchName(id)).toBe('release/n/checkout-redesign')
+      expect(formatPrTitle(id, 'regular')).toBe('Release checkout-redesign')
+      expect(formatJiraName(id)).toBe('checkout-redesign')
+    })
+  })
+})
+
+describe('hasNextToken', () => {
+  it('is true when any versioned entry is "next"', () => {
+    expect(
+      hasNextToken([
+        { name: 'checkout-redesign', type: 'regular' },
+        { version: 'next', type: 'regular' },
+      ]),
+    ).toBe(true)
+  })
+
+  it('is false for explicit versions and named entries only', () => {
+    expect(
+      hasNextToken([
+        { version: '1.2.3', type: 'regular' },
+        { name: 'next-thing', type: 'regular' },
+      ]),
+    ).toBe(false)
+  })
 })

package/src/lib/version-utils/index.ts

@@ -4,10 +4,13 @@ export {
   computeNextVersion,
   type ExistingVersionsSources,
   hasNextToken,
+  type NamedReleaseInput,
   NEXT_TOKEN,
   NoPriorVersionsError,
   parseReleaseSpec,
   type ReleaseEntry,
+  type ReleaseInput,
+  type ReleaseSpec,
   resolveReleaseEntries,
   type SemVer,
 } from './next-version'

package/src/lib/version-utils/load-existing-versions.ts

@@ -2,27 +2,46 @@ import { $ } from 'zx'
 
 import { getProjectVersions, loadJiraConfigOptional } from 'src/integrations/jira'
 import { logger } from 'src/lib/logger'
+import { parseBranchName } from 'src/lib/release-id'
 
 import { collectKnownVersions } from './next-version'
 import type { SemVer } from './next-version'
 
+/**
+ * Extract version-branch tokens from raw `git ls-remote` stdout. Each line is
+ * `<sha>\t<ref>`; refs are routed through release-id's lenient
+ * {@link parseBranchName} and only `kind: 'version'` ids are kept (named
+ * `release/n/*` branches are irrelevant to `next`-bump math and are dropped).
+ * Returns the no-`v` semver tokens (e.g. `1.2.3`) that
+ * {@link collectKnownVersions} parses as versions. Pure — no I/O — so it is
+ * unit-testable without the network.
+ */
+export const extractVersionBranches = (lsRemoteStdout: string): string[] => {
+  return lsRemoteStdout
+    .split('\n')
+    .map((line) => {
+      const tab = line.indexOf('\t')
+
+      if (tab === -1) return null
+
+      return parseBranchName(line.slice(tab + 1))
+    })
+    .filter((id): id is NonNullable<typeof id> => {
+      return id !== null && id.kind === 'version'
+    })
+    .map((id) => {
+      return id.raw
+    })
+}
+
 const parseRemoteRefs = async (): Promise<string[]> => {
   const previousQuiet = $.quiet
 
   try {
     $.quiet = true
     const result = await $`git ls-remote --heads origin 'release/v*'`
-    const lines = result.stdout.split('\n')
-
-    return lines
-      .map((line) => {
-        const tab = line.indexOf('\t')
-
-        if (tab === -1) return ''
 
-        return line.slice(tab + 1).replace(/^refs\/heads\//, '')
-      })
-      .filter(Boolean)
+    return extractVersionBranches(result.stdout)
   } finally {
     $.quiet = previousQuiet
   }