rvlib-shipkit 0.14.0 → 0.16.0

package/src/release/run-bump.ts

@@ -0,0 +1,419 @@
+// the whole release from one word. each step is trivial, the sequence is
+// what costs time and produces half-released states, so the sequence is the
+// command.
+//
+// order is load-bearing. The MERGE happens first, because every fact a bump
+// writes (the next version, the tag, the per-unit gate) must describe the
+// merged tree, never the branch it was computed on. Nothing is pushed until
+// the very end, so any refusal rolls the merge back and returns you to your
+// branch. The gate then runs before anything is written, so a red repo never
+// gets a version bump commit, and the prepublish scripts run before the
+// commit, so a failing build cannot be tagged. publishing is delegated to
+// run-release.
+//
+// --dry-run is the ONE exception, and deliberately so: it is the command you
+// run BECAUSE you do not want to touch anything, so a rehearsal that merges
+// and rolls back is wrong even when the rollback works. It probes the merge
+// in the object database instead (git-facts mergeProbe) and gates the
+// UNMERGED tree, saying so. That is strictly less proof than a real bump,
+// which is why the report states what it did NOT cover.
+//
+// every window where the release branch carries an unagreed merge is closed
+// on the way out: the rollback reads both git exit codes, and an interrupt
+// during the gate or the prepublish scripts runs it too.
+//
+// with several units the ATOMIC part is the version commit: one commit holds
+// every selected unit's package.json and changelog. The publish part is
+// RESUMABLE instead, because an npm publish cannot be undone and a rollback
+// that cannot roll back is a lie.
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { relative } from 'path'
+import { hasUnreleasedNotes, promoteUnreleased } from './changelog.ts'
+import { deriveRemote, dirtyPaths, git as gitAt, mergeProbe, remoteTags, tagExistsLocally } from './git-facts.ts'
+import { unitBlockers } from './unit-gate.ts'
+import { formatUnitError, releaseOrder, renderTag, resolveUnits, unitById, unitPrepublishScripts, type ReleaseUnit } from './units.ts'
+import { environmentBlockers, runReleaseGate, releaseUnit } from './run-release.ts'
+import type { RepoConfig } from '../repo-config.ts'
+
+export type BumpKind = 'major' | 'minor' | 'patch'
+
+/** next version, X.Y.Z only. A prerelease or build suffix is refused rather
+ *  than silently mangled: guessing what `1.2.3-beta.1` plus "minor" means is
+ *  exactly the kind of doubt this tool exists to remove. */
+export function nextVersion(current: string, kind: BumpKind): string {
+    const m = current.match(/^(\d+)\.(\d+)\.(\d+)$/)
+    if (m == null) throw new Error(`version '${current}' is not plain X.Y.Z — bump it by hand, then release`)
+    const [maj, min, pat] = [Number(m[1]), Number(m[2]), Number(m[3])]
+    if (kind === 'major') return `${maj + 1}.0.0`
+    if (kind === 'minor') return `${maj}.${min + 1}.0`
+    return `${maj}.${min}.${pat + 1}`
+}
+
+export type BumpOpts = {
+    /** rehearse: gate and prepublish scripts run, nothing is written, and no
+     *  merge is made — the merge is probed in the object database instead */
+    dryRun?: boolean
+    /** stop after committing the bump, do not tag or publish */
+    noRelease?: boolean
+    /** refuse on a feature branch instead of merging it into the release branch */
+    noMerge?: boolean
+    /** which unit to bump (default 'root') */
+    unit?: string
+    /** bump every unit whose changelog carries non-empty Unreleased notes */
+    all?: boolean
+    print?: (line: string) => void
+}
+
+type Git = (args: string[]) => { code: number; out: string }
+
+/** bring a feature branch onto the release branch with a merge commit, and
+ *  hand back a rollback. nothing here is pushed, so a later failure can undo
+ *  the merge completely and put the caller back where it started. */
+function mergeIntoReleaseBranch(
+    git: Git,
+    p: { from: string; to: string; remote: string; print: (l: string) => void },
+): { ok: true; rollback: () => void } | { ok: false } {
+    const { from, to, remote, print } = p
+    git(['fetch', remote, '--quiet'])
+    // every return-to-the-branch is checked: a silent checkout failure leaves
+    // HEAD on the release branch while the line above says otherwise, and the
+    // operator's next commit lands there
+    const restore = (): boolean => {
+        const r = git(['checkout', '--quiet', from])
+        if (r.code === 0) return true
+        print(`FAIL: could not return to '${from}' (git checkout exited ${r.code}) — HEAD is STILL on '${to}', your next commit would land there`)
+        for (const l of r.out.split('\n').slice(0, 4)) print(`      ${l}`)
+        print(`      fix: git checkout ${from}`)
+        return false
+    }
+
+    const co = git(['checkout', '--quiet', to])
+    if (co.code !== 0) { print(`FAIL: cannot switch to '${to}' — ${co.out}`); return { ok: false } }
+
+    // fast-forward only: a release branch that diverged from its remote is a
+    // human decision, never something a release command resolves
+    const remoteHead = git(['rev-parse', '--quiet', '--verify', `${remote}/${to}`])
+    if (remoteHead.code === 0) {
+        const ff = git(['merge', '--ff-only', `${remote}/${to}`])
+        if (ff.code !== 0) {
+            print(`FAIL: '${to}' has diverged from ${remote}/${to} — reconcile it by hand`)
+            restore()
+            return { ok: false }
+        }
+    }
+    const before = git(['rev-parse', 'HEAD']).out
+    const merge = git(['merge', '--no-ff', from, '-m', `merge ${from}`])
+    if (merge.code !== 0) {
+        print(`FAIL: merging '${from}' into '${to}' hit conflicts, nothing was changed`)
+        for (const l of merge.out.split('\n').slice(0, 8)) print(`      ${l}`)
+        git(['merge', '--abort'])
+        restore()
+        return { ok: false }
+    }
+    print(`ok: merged '${from}' into '${to}' (merge commit, not pushed yet)`)
+    return {
+        ok: true,
+        rollback: () => {
+            // the merge was never pushed, so this drops only local work. Both
+            // calls are READ: an index.lock from a concurrent run makes the
+            // reset fail, and announcing a rollback that did not happen is how
+            // a merge nobody agreed to gets pushed by the next command.
+            const reset = git(['reset', '--hard', before])
+            if (reset.code !== 0) {
+                print(`FAIL: rollback FAILED — '${to}' STILL carries the merge (git reset --hard exited ${reset.code})`)
+                for (const l of reset.out.split('\n').slice(0, 4)) print(`      ${l}`)
+                print(`      fix: git reset --hard ${before} && git checkout ${from}`)
+                return
+            }
+            if (restore()) print(`ok: rolled '${to}' back and returned to '${from}' — nothing was pushed`)
+        },
+    }
+}
+
+/** the rehearsal's answer to the same two questions, from the object database:
+ *  has the release branch diverged from its remote, and would the merge
+ *  conflict. Nothing is checked out and no ref moves, which is the whole point
+ *  of a dry run. It must answer for the tree the REAL path would build, so a
+ *  release branch that exists only on the remote resolves to the remote ref:
+ *  that is exactly what `git checkout <to>` creates. `refuse` stops the run,
+ *  and `inconclusive` forbids the closing "dry run clean" claim. */
+type MergeRehearsal = { refuse: true } | { refuse: false; inconclusive: boolean }
+
+function probeMergeIntoReleaseBranch(
+    root: string,
+    git: Git,
+    p: { from: string; to: string; remote: string; print: (l: string) => void },
+): MergeRehearsal {
+    const { from, to, remote, print } = p
+    git(['fetch', remote, '--quiet'])
+    const remoteRef = `${remote}/${to}`
+    const localExists = git(['rev-parse', '--quiet', '--verify', to]).code === 0
+    const remoteExists = git(['rev-parse', '--quiet', '--verify', remoteRef]).code === 0
+    if (!localExists && !remoteExists) {
+        print(`FAIL: no branch '${to}' here or on '${remote}' — a release needs a branch to ship from`)
+        return { refuse: true }
+    }
+    let tip = localExists ? to : remoteRef
+    if (localExists && remoteExists) {
+        // the real path fast-forwards, which succeeds when either side is an
+        // ancestor of the other and refuses only on a genuine divergence
+        const behind = git(['merge-base', '--is-ancestor', to, remoteRef]).code === 0
+        const ahead = git(['merge-base', '--is-ancestor', remoteRef, to]).code === 0
+        if (!behind && !ahead) { print(`FAIL: '${to}' has diverged from ${remoteRef} — reconcile it by hand`); return { refuse: true } }
+        if (behind) tip = remoteRef
+    }
+    const probe = mergeProbe(root, tip, from)
+    if (probe.state === 'conflicts') {
+        print(`FAIL: '${from}' would conflict with '${to}' — nothing was merged, nothing was changed`)
+        for (const path of probe.paths.slice(0, 8)) print(`      ${path}`)
+        return { refuse: true }
+    }
+    if (probe.state === 'unknown') {
+        print(`WARN cannot check the merge without touching the worktree (${probe.reason}) — the rehearsal does not know whether '${from}' merges into '${to}'`)
+        return { refuse: false, inconclusive: true }
+    }
+    print(`note: '${from}' merges cleanly into '${to}' (checked in the object database, no ref moved)`)
+    return { refuse: false, inconclusive: false }
+}
+
+type Selected = { unit: ReleaseUnit; version: string; changelogRel: string }
+
+export async function runBump(root: string, config: RepoConfig, kind: BumpKind, o: BumpOpts = {}): Promise<number> {
+    const print = o.print ?? ((l: string) => console.log(l))
+    if (o.all === true && o.unit != null) { print('FAIL: pass a unit or --all, never both'); return 1 }
+
+    const git: Git = (args) => gitAt(root, args)
+    const cur = git(['rev-parse', '--abbrev-ref', 'HEAD']).out
+    const branch = config.release?.branch ?? 'main'
+
+    // pre-merge, ONLY what a merge cannot change: a typo'd unit id, a dirty
+    // tree, the branch decision, the remote. Everything the bump WRITES is
+    // computed after the merge, off the tree that actually ships.
+    const onDisk = resolveUnits(root, config)
+    if (onDisk.errors.length > 0) { for (const e of onDisk.errors) print(`FAIL: ${formatUnitError(e)}`); return 1 }
+    if (o.all !== true) {
+        const id = o.unit ?? 'root'
+        if (unitById(onDisk.units, id) == null) {
+            print(`FAIL: no release unit '${id}' — known units: ${onDisk.units.map((x) => x.id).join(', ')}`)
+            print('      fix: shipkit releases')
+            return 1
+        }
+    }
+    // the tree must be clean BEFORE any branch move, or a checkout carries
+    // uncommitted work across branches
+    const dirty = dirtyPaths(root, config)
+    if (dirty !== '') { print(`FAIL: working tree not clean, commit your work first:\n${dirty.split('\n').slice(0, 10).join('\n')}`); return 1 }
+
+    const wantMerge = cur !== branch && o.noMerge !== true && (config.release?.mergeFromBranch ?? true)
+    if (cur !== branch && !wantMerge) { print(`FAIL: releases ship from '${branch}', HEAD is on '${cur}'`); return 1 }
+    const remote = deriveRemote(root)
+    if ('error' in remote) { print(`FAIL: ${remote.error}`); return 1 }
+    if (wantMerge) print(`note: on '${cur}', so '${cur}' merges into '${branch}' first`)
+
+    // the merge happens FIRST among the writes, so every fact below describes
+    // the tree that ships. Nothing here is pushed, so every refusal rolls it
+    // back whole. A rehearsal merges NOTHING and says what it therefore did
+    // not prove (the file header owns the reasoning).
+    const rehearsal = o.dryRun === true
+    let rollback: (() => void) | null = null
+    let onInterrupt: (() => void) | null = null
+    let mergeUnknown = false
+    if (wantMerge && rehearsal) {
+        const probe = probeMergeIntoReleaseBranch(root, git, { from: cur, to: branch, remote: remote.remote, print })
+        if (probe.refuse) return 1
+        mergeUnknown = probe.inconclusive
+    } else if (wantMerge) {
+        const m = mergeIntoReleaseBranch(git, { from: cur, to: branch, remote: remote.remote, print })
+        if (!m.ok) return 1
+        rollback = m.rollback
+        // the merge window spans the gate and the prepublish scripts, and
+        // nothing there handles an interrupt: Ctrl-C used to leave the merge
+        // on the release branch with not a line printed about it
+        onInterrupt = () => { print(`FAIL: interrupted — rolling '${branch}' back`); rollback?.(); process.exit(130) }
+        process.on('SIGINT', onInterrupt)
+        process.on('SIGTERM', onInterrupt)
+    }
+    // shut the window: after this the merge is either undone or permanent, and
+    // an interrupt must never reset --hard over files the operator has to keep
+    const closeMergeWindow = (): void => {
+        if (onInterrupt != null) { process.off('SIGINT', onInterrupt); process.off('SIGTERM', onInterrupt); onInterrupt = null }
+        rollback = null
+    }
+    const rollBack = (): void => { rollback?.(); closeMergeWindow() }
+    const fail = (msg: string, fixLine?: string): number => {
+        print(`FAIL: ${msg}`)
+        if (fixLine != null) print(`      fix: ${fixLine}`)
+        rollBack()
+        return 1
+    }
+
+    // phase 1, on the MERGED tree (on the FEATURE tree in a rehearsal): the
+    // resolution, the selection, the next versions, the tag refusals and the
+    // per-unit gate all describe what ships
+    const resolved = resolveUnits(root, config)
+    // bump can touch several units at once, so ANY unresolved unit is fatal:
+    // a selection built from a partial model is a selection nobody can trust
+    if (resolved.errors.length > 0) { for (const e of resolved.errors) print(`FAIL: ${formatUnitError(e)}`); rollBack(); return 1 }
+    const all = releaseOrder(resolved.units)
+
+    // selection. `--all` reads the changelogs: a unit with nothing to say is
+    // skipped, not failed, so `--all` means "ship everything that has news".
+    let picked: ReleaseUnit[]
+    if (o.all === true) {
+        picked = []
+        for (const u of all) {
+            if (!existsSync(u.changelog)) { print(`skip: ${u.id} — no changelog at ${relative(root, u.changelog)}`); continue }
+            if (hasUnreleasedNotes(readFileSync(u.changelog, 'utf8'))) picked.push(u)
+            else print(`skip: ${u.id} — no Unreleased notes`)
+        }
+        if (picked.length === 0) return fail('no unit has non-empty Unreleased notes — write what changed, then bump')
+    } else {
+        const id = o.unit ?? 'root'
+        const u = unitById(all, id)
+        if (u == null) return fail(`no release unit '${id}' after the merge — known units: ${all.map((x) => x.id).join(', ')}`, 'shipkit releases')
+        picked = [u]
+    }
+
+    // one ls-remote for the whole run: a tag name the remote already carries
+    // is a burnt version, and finding that out AFTER the version commit leaves
+    // a number nobody can ship
+    const onRemote = remoteTags(root, remote.remote)
+    if ('error' in onRemote) return fail(`cannot read tags on '${remote.remote}' (${onRemote.error}) — a bump that cannot see the remote's tags can burn a version`)
+
+    const blockers: string[] = []
+    const selected: Selected[] = []
+    for (const unit of picked) {
+        let version: string
+        try { version = nextVersion(unit.version, kind) }
+        catch (e) { blockers.push(`unit '${unit.id}': ${e instanceof Error ? e.message : String(e)}`); continue }
+        const changelogRel = relative(root, unit.changelog)
+        if (!existsSync(unit.changelog)) { blockers.push(`unit '${unit.id}': ${changelogRel} not found — a release states what changed`); continue }
+        const promoted = promoteUnreleased(readFileSync(unit.changelog, 'utf8'), version)
+        if ('error' in promoted) { blockers.push(`unit '${unit.id}': ${promoted.error}`); continue }
+        const tag = renderTag(unit, version)
+        if (tagExistsLocally(root, tag)) {
+            blockers.push(`unit '${unit.id}': tag ${tag} already exists here — finish that release with \`shipkit release ${unit.id}\`, or pick another bump`)
+            continue
+        }
+        if (onRemote.tags.has(tag)) {
+            blockers.push(`unit '${unit.id}': tag ${tag} already exists on '${remote.remote}' — that version number is taken, pick another bump`)
+            continue
+        }
+        blockers.push(...unitBlockers(root, config, unit))
+        selected.push({ unit, version, changelogRel })
+    }
+    // everything the release needs that does not depend on the new version.
+    // HEAD is the release branch by now, so the branch check applies — except
+    // in a rehearsal that deliberately stayed on the feature branch, where the
+    // branch decision was already made and refused above
+    blockers.push(...environmentBlockers(root, config, {
+        wantGh: picked.some((u) => u.targets.githubRelease),
+        skipBranch: rehearsal && wantMerge,
+    }))
+    if (blockers.length > 0) { for (const b of blockers) print(`FAIL: ${b}`); rollBack(); return 1 }
+
+    for (const s of selected) print(`note: ${s.unit.id} ${s.unit.version} → ${s.version} (${kind})`)
+
+    // phase 2: ONE gate for the whole repo. The repo is one worktree, so N
+    // gates cost N times as much and prove the same thing. Frozen, and fatal
+    // on non-blocking failures when the repo declared requireHealthy.
+    // releaseUnit then skips it, because bump already proved this exact tree.
+    if ((await runReleaseGate(root, config, print, { fix: true })) !== 0) return fail('ci gate is red on the merged result — fix it, then bump')
+    // the gate's fix pass can rewrite files. writing a version on top of that
+    // produces a version commit that excludes the rewrite and a release that
+    // then refuses on a dirty tree, which is a half-released repo.
+    const afterGate = dirtyPaths(root, config)
+    if (afterGate !== '')
+        return fail(
+            `the gate rewrote files, so the tree is no longer clean:\n${afterGate.split('\n').slice(0, 10).join('\n')}`,
+            rollback != null
+                ? 'the rollback below discards them. run `shipkit ci` on your branch, commit what it rewrites, then bump again'
+                : 'run `shipkit ci`, commit what it rewrites, then bump again',
+        )
+    print('ok: ci gate green')
+
+    for (const s of selected) {
+        for (const script of unitPrepublishScripts(s.unit)) {
+            const r = Bun.spawnSync(['bun', 'run', script], { cwd: s.unit.dir, stdout: 'inherit', stderr: 'inherit' })
+            if (r.exitCode !== 0) return fail(`${s.unit.id}: ${script} failed (exit ${r.exitCode}) — nothing was written`)
+            print(`ok: ${s.unit.id} ${script}`)
+        }
+    }
+    if (selected.every((s) => unitPrepublishScripts(s.unit).length === 0)) print('note: no prepublish scripts')
+
+    if (rehearsal) {
+        const what = selected.map((s) => `${s.unit.id} ${s.version}`).join(', ')
+        // a rehearsal that could not answer the merge question must not close
+        // with the word "clean": that green is what sends an operator into a
+        // real bump that aborts mid-merge
+        if (mergeUnknown) print(`WARN dry run inconclusive — would write ${what}, but the merge into '${branch}' could not be checked (git 2.38+ answers it)`)
+        else print(`ok: dry run clean — would write ${what}, commit, then ${o.noRelease === true ? 'stop' : 'release'}`)
+        // what the rehearsal did NOT cover, said out loud: a merge that never
+        // happened cannot have been gated, and a number computed on the
+        // feature branch can differ from the one the real bump writes
+        if (wantMerge)
+            print(`      it did NOT merge: '${branch}' never moved, and everything above (versions, tags, gate) describes '${cur}' UNMERGED`)
+        rollBack()
+        return 0
+    }
+
+    // phase 3: ONE version commit holding every selected unit's two files.
+    // Partial writes are the half-released state this whole command exists to
+    // prevent, so the write and the commit are one step for the whole selection.
+    //
+    // from the first write on, a failure NEVER rolls back: `git reset --hard`
+    // would delete the very files the fix line tells the operator to commit.
+    // What is on disk is reported as it is, interrupts included.
+    closeMergeWindow()
+    const failKeep = (msg: string, fixLine: string): number => { print(`FAIL: ${msg}`); print(`      fix: ${fixLine}`); return 1 }
+    const files: string[] = []
+    for (const s of selected) {
+        const pkgRel = s.unit.rel === '' ? 'package.json' : `${s.unit.rel}/package.json`
+        // re-read: a merge can have changed both files under us
+        const pkgNow = readFileSync(`${root}/${pkgRel}`, 'utf8')
+        const promoted = promoteUnreleased(readFileSync(s.unit.changelog, 'utf8'), s.version)
+        if ('error' in promoted) return failKeep(`${s.unit.id}: ${promoted.error}`, `check ${s.changelogRel}, then run bump again`)
+        // indentation is preserved by rewriting only the version VALUE, so a bump
+        // never reformats a file the repo cares about
+        const bumped = pkgNow.replace(/("version"\s*:\s*")[^"]*(")/, `$1${s.version}$2`)
+        if (bumped === pkgNow) return failKeep(`${s.unit.id}: could not rewrite the version field in ${pkgRel}`, `git status, then set the version by hand`)
+        writeFileSync(`${root}/${pkgRel}`, bumped)
+        writeFileSync(s.unit.changelog, promoted.text)
+        files.push(pkgRel, s.changelogRel)
+        print(`ok: ${pkgRel} ${s.version}, ${s.changelogRel} section promoted`)
+    }
+
+    const add = git(['add', ...files])
+    if (add.code !== 0) return failKeep('git add failed', 'the version files are written but unstaged. git status, then commit them')
+    const label = selected.map((s) => (s.unit.id === 'root' ? s.version : `${s.unit.id}@${s.version}`)).join(', ')
+    // the hooks already ran through the gate above; --no-verify is NOT used,
+    // so the repo's own commit gates still apply to this commit
+    const commit = git(['commit', '-m', `release ${label}`])
+    if (commit.code !== 0)
+        return failKeep(`commit failed — ${commit.out}`, 'the version files are written but uncommitted. fix the gate, commit, then `shipkit release`')
+    print(`ok: committed release ${label}`)
+
+    if (o.noRelease === true) { print(`ok: bumped ${label}, not released (--no-release)`); return 0 }
+
+    // phase 4: publish per unit, sequentially. A failure STOPS and never rolls
+    // back: the version commit already landed for every unit, so each one
+    // resumes with `shipkit release <id>` and no re-bump.
+    const fresh = resolveUnits(root, config)
+    if (fresh.errors.length > 0) { for (const e of fresh.errors) print(`FAIL: ${formatUnitError(e)}`); return 1 }
+    const order = selected.map((s) => unitById(fresh.units, s.unit.id)).filter((u): u is ReleaseUnit => u != null)
+    for (let i = 0; i < order.length; i++) {
+        const u = order[i]!
+        const code = await releaseUnit(root, config, u, {
+            skipGate: true,
+            skipGateReason: 'already green on this tree (bump ran it)',
+            skipUnitGate: true,
+            print,
+        })
+        if (code !== 0) {
+            print(`FAIL: ${u.id} did not finish — the version commit is already in, so nothing needs re-bumping`)
+            for (const rest of order.slice(i)) print(`      fix: shipkit release ${rest.id}`)
+            return 1
+        }
+    }
+    return 0
+}