rvlib-shipkit 0.14.0 → 0.17.0

package/src/release/run-release.ts

@@ -0,0 +1,271 @@
+// one release path per unit, public or private. The unit decides which steps
+// apply, never a different script: a unit with no npm target skips the
+// publish and still gets tag, push, and a GitHub release when it wants one,
+// with notes from its own versioned CHANGELOG.
+//
+// every step is idempotent and the pipeline resumes: a run that died after
+// publishing completes only what is missing. preflight touches nothing.
+import { existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { runCi } from '../core/run-ci.ts'
+import { extractChangelogSection } from './changelog.ts'
+import { deriveRemote, dirtyPaths, git, remoteTagState, tagExistsLocally, type RemoteTagState } from './git-facts.ts'
+import { npmPublishArgv, unitBlockers } from './unit-gate.ts'
+import { formatUnitError, resolveUnits, unitById, type ReleaseUnit } from './units.ts'
+import type { RepoConfig } from '../repo-config.ts'
+
+export type ReleaseConfig = {
+    /** releases ship from this branch only (default 'main') */
+    branch?: string
+    /** the ROOT unit's tag template, `{version}` substituted (default 'v{version}') */
+    tag?: string
+    /** the ROOT unit's versioned changelog (default 'CHANGELOG.md') */
+    changelog?: string
+    /** publish the ROOT unit to npm. Default: its package.json is not private.
+     *  A private package NEVER publishes, whatever this says. */
+    npm?: boolean
+    /** argv printing an npm auth token on stdout (e.g. a secret-manager read).
+     *  Absent = rely on ambient npm auth. Never put a token in config.
+     *  Repo-wide: one account publishes every unit. */
+    npmTokenCommand?: string[]
+    /** cut a GitHub release for the ROOT unit with `gh` (default true) */
+    githubRelease?: boolean
+    /** make a NON-blocking check failure block the release too. Blocking
+     *  checks always block, here as everywhere. Default false: a non-blocking
+     *  check reports the world (a missing cred, a box that is off), and that
+     *  is rarely a reason to refuse a finished version. */
+    requireHealthy?: boolean
+    /** repo-relative tsconfig for the ROOT unit's own typecheck (default
+     *  '<root>/tsconfig.json' when it exists) */
+    tsconfig?: string
+    /** `shipkit bump` run from a feature branch merges it into the release
+     *  branch first, with a merge commit. Default true. A branch is a GATE, so
+     *  this is deliberately reachable ONLY by running bump by hand. */
+    mergeFromBranch?: boolean
+}
+
+/** the parts of the release preflight that do not depend on the new version
+ *  existing yet: branch, remote, gh. bump runs this BEFORE it writes anything,
+ *  or a refusal here lands after the version commit. */
+export function environmentBlockers(root: string, config: RepoConfig, o: { skipBranch?: boolean; wantGh?: boolean } = {}): string[] {
+    const branch = config.release?.branch ?? 'main'
+    const out: string[] = []
+    const cur = git(root, ['rev-parse', '--abbrev-ref', 'HEAD'])
+    if (cur.code !== 0) out.push('not a git repository')
+    else if (cur.out !== branch && o.skipBranch !== true) out.push(`releases ship from '${branch}', HEAD is on '${cur.out}'`)
+    const remote = deriveRemote(root)
+    if ('error' in remote) out.push(remote.error)
+    if (o.wantGh ?? config.release?.githubRelease ?? true) {
+        if (Bun.which('gh') == null) out.push('gh not installed and a unit wants a GitHub release — install gh or set githubRelease: false')
+        else if (Bun.spawnSync(['gh', 'auth', 'status']).exitCode !== 0) out.push('gh is not authenticated (gh auth login)')
+    }
+    return out
+}
+
+export type ReleaseOpts = {
+    dryRun?: boolean
+    allowDirty?: boolean
+    /** skip the ci gate preflight, deliberately awkward to reach */
+    skipGate?: boolean
+    /** why the gate was skipped. `shipkit bump` already ran it on this exact
+     *  tree, which is not the same thing as publishing unverified, and the
+     *  output must not claim it is. */
+    skipGateReason?: string
+    /** bump already ran the per-unit gate on this exact tree */
+    skipUnitGate?: boolean
+    /** which unit to release (default 'root') */
+    unit?: string
+    print?: (line: string) => void
+}
+
+/** the ci gate as the release path runs it: FROZEN (a self-updating rule that
+ *  rewrites package.json between the gate and `npm publish` packs a tree that
+ *  exists in no commit) and, when the repo asked for it, fatal on non-blocking
+ *  check failures too. There is no second health suite: `runCi` runs every
+ *  check, and a check's own `blocking` declaration is the only severity axis.
+ *
+ *  the config travels INTO the gate: classifying severity from one config
+ *  while the rules ran from another downgrades a blocking failure to a warning. */
+export async function runReleaseGate(root: string, config: RepoConfig, print: (l: string) => void, o: { fix?: boolean } = {}): Promise<number> {
+    return await runCi(root, {
+        fix: o.fix ?? false,
+        frozen: true,
+        status: false,
+        // a release must not gate on a clean pass cached hours ago: SK005's
+        // blocking branches are local facts (a link: that stopped resolving, a
+        // dep nobody installed) and a TTL replays them as green
+        fresh: true,
+        config,
+        failOnAdvisory: config.release?.requireHealthy === true,
+        print: (l) => print(`      ${l}`),
+    })
+}
+
+/** `shipkit release [unit]` — resolve the unit, then ship it. */
+export async function runRelease(root: string, config: RepoConfig, o: ReleaseOpts = {}): Promise<number> {
+    const print = o.print ?? ((l: string) => console.log(l))
+    const { units, errors } = resolveUnits(root, config)
+    const id = o.unit ?? 'root'
+    // only THIS unit's own resolution has to hold: a broken sibling is not a
+    // reason to refuse a release of something that resolves fine
+    const mine = errors.filter((e) => e.id === id)
+    if (mine.length > 0) { for (const e of mine) print(`FAIL: ${formatUnitError(e)}`); return 1 }
+    const unit = unitById(units, id)
+    if (unit == null) {
+        print(`FAIL: no release unit '${id}' — known units: ${units.map((u) => u.id).join(', ')}`)
+        print('      fix: shipkit releases')
+        return 1
+    }
+    return await releaseUnit(root, config, unit, o)
+}
+
+/** ship ONE resolved unit. Every gate above it has already run when bump
+ *  calls this; a bare `shipkit release` runs them here. */
+export async function releaseUnit(root: string, config: RepoConfig, unit: ReleaseUnit, o: ReleaseOpts = {}): Promise<number> {
+    const print = o.print ?? ((l: string) => console.log(l))
+    const rc = config.release ?? {}
+    const branch = rc.branch ?? 'main'
+    const { name, version, tag } = unit
+    const wantNpm = unit.targets.npm
+    const wantGh = unit.targets.githubRelease
+
+    const blockers: string[] = []
+    const notesResult = ((): { notes: string } | { error: string } => {
+        if (!existsSync(unit.changelog)) return { error: `unit '${unit.id}': CHANGELOG not found at ${unit.changelog} — a release states what changed` }
+        try { return { notes: extractChangelogSection({ changelog: readFileSync(unit.changelog, 'utf8'), version }) } }
+        catch (e) { return { error: `unit '${unit.id}': ${e instanceof Error ? e.message : String(e)}` } }
+    })()
+    if ('error' in notesResult) blockers.push(notesResult.error)
+    const notes = 'notes' in notesResult ? notesResult.notes : ''
+
+    const cur = git(root, ['rev-parse', '--abbrev-ref', 'HEAD'])
+    if (cur.code !== 0) blockers.push('not a git repository')
+    else if (cur.out !== branch) blockers.push(`releases ship from '${branch}', HEAD is on '${cur.out}'`)
+
+    const dirty = dirtyPaths(root, config)
+    if (dirty !== '' && o.allowDirty !== true)
+        blockers.push(`working tree not clean (--allow-dirty overrides):\n${dirty.split('\n').slice(0, 10).join('\n')}`)
+    if (o.skipUnitGate !== true) blockers.push(...unitBlockers(root, config, unit))
+
+    let alreadyPublished = false
+    if (wantNpm) {
+        const res = await fetch(`https://registry.npmjs.org/${name}`, { signal: AbortSignal.timeout(15000) }).catch(() => null)
+        if (res == null) blockers.push('npm registry unreachable — offline?')
+        else if (res.ok) {
+            const versions = ((await res.json()) as { versions?: Record<string, unknown> }).versions ?? {}
+            alreadyPublished = versions[version] != null
+        } else if (res.status !== 404) blockers.push(`npm registry lookup for ${name} → ${res.status}`)
+    }
+    // a tag that exists but was never pushed, or whose github release is
+    // missing, means a previous run died mid-pipeline. re-running must finish
+    // it, never demand a burnt version number. only a FULLY shipped version is
+    // a dead end.
+    const remote = deriveRemote(root)
+    if ('error' in remote) blockers.push(remote.error)
+    const remoteName0 = 'remote' in remote ? remote.remote : null
+    const tagExists = (): boolean => tagExistsLocally(root, tag)
+    const remoteState: RemoteTagState = remoteName0 == null ? { state: 'unreadable', error: 'no remote' } : remoteTagState(root, remoteName0, tag)
+    if (remoteName0 != null && remoteState.state === 'unreadable')
+        blockers.push(`cannot read tags on '${remoteName0}' (${remoteState.error}) — the push would be a guess`)
+    // a tag NAME the remote already carries at another commit is not a
+    // resumable release: this version would describe a tree that shipped as
+    // something else, and git refuses the push anyway
+    if (remoteState.state === 'different')
+        blockers.push(`tag ${tag} already on '${remoteName0 ?? ''}' at ${remoteState.remoteOid.slice(0, 8)}, ${remoteState.localOid == null ? 'and not here at all' : `not ${remoteState.localOid.slice(0, 8)} as here`} — that version number is burnt, bump a new one`)
+    const ghReleaseExists = (): boolean =>
+        wantGh && Bun.which('gh') != null && Bun.spawnSync(['gh', 'release', 'view', tag], { cwd: root }).exitCode === 0
+    const fullyShipped = tagExists() && remoteState.state === 'same' && (!wantGh || ghReleaseExists()) && (!wantNpm || alreadyPublished)
+    if (fullyShipped) blockers.push(`${name}@${version} is fully released (tag ${tag}${wantNpm ? ' + npm' : ''}) — bump the version first`)
+    else if (tagExists()) print(`WARN ${tag} exists but the release is incomplete — resuming the remaining steps`)
+    else if (alreadyPublished) print(`WARN ${version} is on npm but ${tag} is missing — resuming after publish`)
+
+    if (wantNpm && rc.npmTokenCommand == null) print('note: no release.npmTokenCommand — publishing with ambient npm auth')
+    if (wantGh && Bun.which('gh') == null) blockers.push('gh not installed and this unit wants a GitHub release — install gh or set githubRelease: false')
+    else if (wantGh && Bun.spawnSync(['gh', 'auth', 'status']).exitCode !== 0) blockers.push('gh is not authenticated (gh auth login)')
+
+    const steps = [
+        ...(wantNpm && !alreadyPublished ? [`npm publish ${name}@${version}`] : []),
+        ...(tagExists() ? [] : [`git tag ${tag}`]),
+        `git push + push tag ${tag}`,
+        ...(wantGh ? [`gh release create ${tag}`] : []),
+    ]
+
+    print(`note: ${unit.id} · ${name}@${version} → tag ${tag} · ${wantNpm ? 'npm' : unit.isPrivate ? 'PRIVATE (no npm)' : 'no npm target'} · ${notes === '' ? 'no notes' : `${notes.split('\n').length} line(s) of notes`}`)
+    for (const s of steps) print(`note:   ${s}`)
+
+    if (blockers.length > 0) {
+        for (const b of blockers) print(`FAIL: ${b}`)
+        return 1
+    }
+
+    // the gate runs BEFORE anything leaves the machine. A release that skips
+    // its own gate is exactly how a broken build, or a secret, ships. It runs
+    // in verify + frozen mode: a release publishes the reviewed commit, never
+    // a tree a fixer or a self-updating rule rewrote on the way out.
+    if (o.skipGate === true)
+        print(o.skipGateReason != null ? `ok: ci gate ${o.skipGateReason}` : 'WARN ci gate SKIPPED by --skip-gate — publishing unverified')
+    else {
+        if ((await runReleaseGate(root, config, print)) !== 0) { print('FAIL: ci gate is red — fix it, commit, then release'); return 1 }
+        // frozen is a declaration, not a guarantee: any check may still write.
+        // npm packs the DIRECTORY, so a rewrite here would publish a tarball
+        // that exists in no commit while the tag describes another tree.
+        const afterGate = dirtyPaths(root, config)
+        if (afterGate !== '' && o.allowDirty !== true) {
+            print(`FAIL: the gate rewrote files, so the tree no longer matches what the tag would describe:\n${afterGate.split('\n').slice(0, 10).join('\n')}`)
+            print('      fix: commit those changes, then run release again')
+            return 1
+        }
+        print('ok: ci gate green')
+    }
+
+    if (o.dryRun === true) { print(`ok: dry run clean — nothing was touched`); return 0 }
+
+    const remoteName = (remote as { remote: string }).remote
+    const work = mkdtempSync(join(tmpdir(), 'shipkit-release-'))
+    try {
+        if (wantNpm && !alreadyPublished) {
+            const env: Record<string, string> = { ...process.env as Record<string, string> }
+            const argv = rc.npmTokenCommand
+            let npmrc: string | null = null
+            if (argv != null && argv[0] != null) {
+                const t = Bun.spawnSync(argv)
+                const token = t.exitCode === 0 ? t.stdout.toString().trim() : ''
+                if (token === '') { print(`FAIL: release.npmTokenCommand produced no token (exit ${t.exitCode})`); return 1 }
+                // token via a throwaway userconfig, never argv, never a
+                // committed .npmrc, never a line in a log
+                npmrc = join(work, 'npmrc')
+                writeFileSync(npmrc, `//registry.npmjs.org/:_authToken=${token}\n`, { mode: 0o600 })
+            }
+            const p = Bun.spawnSync(npmPublishArgv({ npmrc }), { cwd: unit.dir, env, stdout: 'inherit', stderr: 'inherit' })
+            if (p.exitCode !== 0) { print(`FAIL: npm publish failed for ${unit.id} (exit ${p.exitCode})`); return 1 }
+            print(`ok: published ${name}@${version}`)
+        }
+
+        // every step below is recoverable by re-running: the failure message
+        // says so, because a half-released package is the scariest state
+        const resume = `      fix: shipkit release ${unit.id}`
+        if (!tagExists()) {
+            const t = git(root, ['tag', '-a', tag, '-m', `${name} ${version}`])
+            if (t.code !== 0) { print(`FAIL: git tag ${tag} failed — ${t.out}`); print(resume); return 1 }
+        }
+        const push = git(root, ['push', remoteName])
+        if (push.code !== 0) { print(`FAIL: git push failed — ${push.out}`); print(resume); return 1 }
+        const pushTag = git(root, ['push', remoteName, tag])
+        if (pushTag.code !== 0) { print(`FAIL: pushing ${tag} failed — ${pushTag.out}`); print(resume); return 1 }
+        print(`ok: tagged ${tag} and pushed to ${remoteName}`)
+
+        if (wantGh) {
+            const notesFile = join(work, 'notes.md')
+            writeFileSync(notesFile, notes)
+            const args = ['gh', 'release', 'create', tag, '--verify-tag', '--title', `${name} ${version}`, '--notes-file', notesFile]
+            const g = Bun.spawnSync(args, { cwd: root, stdout: 'inherit', stderr: 'inherit' })
+            if (g.exitCode !== 0) { print(`FAIL: gh release create failed (exit ${g.exitCode})`); print(`${resume} — the tag is already pushed`); return 1 }
+            print(`ok: GitHub release ${tag} live`)
+        }
+        print(`ok: ${name}@${version} released${wantNpm ? ' (npm + tag' : ' (tag'}${wantGh ? ' + github release)' : ')'}`)
+        return 0
+    } finally {
+        rmSync(work, { recursive: true, force: true })
+    }
+}

package/src/release/run-releases.ts

@@ -0,0 +1,230 @@
+// `shipkit releases` — where every release unit actually stands. Report only:
+// it never gates, never writes, and exits 0 even when everything is drifted,
+// because it exists to end the "what is published and what is not" question,
+// not to add another red light.
+//
+// the table stays one line per unit and carries only facts that fit in a
+// column. Anything that needs a sentence (drift, stale notes, an unreachable
+// remote) prints BELOW the table, so the noise is proportional to the problem.
+import { existsSync, readFileSync } from 'fs'
+import { relative } from 'path'
+import { hasUnreleasedHeading, hasVersionSection } from './changelog.ts'
+import { deriveRemote, git, remoteTags } from './git-facts.ts'
+import { formatUnitError, resolveUnits, type ReleaseUnit } from './units.ts'
+import type { RepoConfig } from '../repo-config.ts'
+
+export type UnitReport = {
+    id: string
+    rel: string
+    name: string
+    version: string
+    tag: string
+    /** local tag present */
+    tagLocal: boolean
+    /** on the remote; null when the remote could not be read */
+    tagRemote: boolean | null
+    /** npm dist-tags.latest, 'unpublished' when 404, null when not an npm target or unreadable */
+    npmLatest: string | null
+    /** why the registry could not be read — an unmeasured registry must never
+     *  render as "in sync" */
+    npmError: string | null
+    npmTarget: boolean
+    isPrivate: boolean
+    ghWanted: boolean
+    /** null when gh could not answer */
+    ghRelease: boolean | null
+    /** commits touching this unit since its tag; null when the tag is absent */
+    commitsSinceTag: number | null
+    /** the unit's tree differs from the tree at its tag; null when unassessable */
+    contentDiffers: boolean | null
+    /** the changelog carries a `## <version>` section */
+    hasSection: boolean
+    /** commits touching the unit AFTER the commit that wrote that section —
+     *  the version was stamped and work kept landing under notes that
+     *  describe none of it */
+    commitsAfterNotes: number | null
+    hasUnreleased: boolean
+}
+
+const pathspec = (u: ReleaseUnit): string[] => (u.rel === '' ? [] : ['--', u.rel])
+
+/** the commit that introduced this version's HEADING. Line-anchored on
+ *  purpose: a substring pickaxe also matches prose that MENTIONS `## 1.2.3`,
+ *  so a sentence in the Unreleased section moves the anchor to itself and
+ *  silences the stale-notes warning it was talking about. */
+export function notesAnchor(root: string, changelogRel: string, version: string): string | null {
+    const h = git(root, ['log', '-1', '--format=%H', '-G', `^## ${version.replace(/\./g, '\\.')}`, '--', changelogRel])
+    return h.code === 0 && h.out !== '' ? h.out : null
+}
+
+/** the git tree hash of the unit dir at a ref. Tree hashes, never commit
+ *  counts: a folder rename must not read as a content change. A tag can
+ *  predate the move, so a miss falls back to finding the directory by name
+ *  inside that ref's tree, or drift goes silently unassessed. */
+function treeAt(root: string, u: ReleaseUnit, ref: string): string | null {
+    const rev = (path: string): string | null => {
+        const r = git(root, ['rev-parse', path === '' ? ref : `${ref}:${path}`])
+        return r.code === 0 ? r.out : null
+    }
+    const direct = rev(u.rel)
+    if (direct != null || u.rel === '') return direct
+    const base = u.rel.split('/').at(-1)!
+    const ls = git(root, ['ls-tree', '-r', '-d', '--name-only', ref])
+    if (ls.code !== 0) return null
+    const hit = ls.out.split('\n').find((p) => p === base || p.endsWith(`/${base}`))
+    return hit != null ? rev(hit) : null
+}
+
+export async function collectReports(root: string, config: RepoConfig, o: { offline?: boolean } = {}): Promise<{ reports: UnitReport[]; errors: string[]; remote: string | null; remoteError: string | null }> {
+    // a unit that does not resolve is still news: it is named, and everything
+    // that DID resolve is still reported beside it
+    const { units, errors } = resolveUnits(root, config)
+    const derived = deriveRemote(root)
+    const remote = 'remote' in derived ? derived.remote : null
+    let remoteError = 'error' in derived ? derived.error : null
+    let pushed: Set<string> | null = null
+    if (remote != null && o.offline !== true) {
+        const r = remoteTags(root, remote)
+        if ('tags' in r) pushed = r.tags
+        else remoteError = `git ls-remote ${remote} unreachable (${r.error})`
+    }
+
+    const reports: UnitReport[] = []
+    for (const u of units) {
+        const tagLocal = git(root, ['rev-parse', '--quiet', '--verify', `refs/tags/${u.tag}`]).code === 0
+        const changelog = existsSync(u.changelog) ? readFileSync(u.changelog, 'utf8') : ''
+        const hasSection = hasVersionSection(changelog, u.version)
+        const changelogRel = relative(root, u.changelog)
+        // the commit that introduced this version's heading, then everything
+        // that touched the unit afterwards but is not the changelog itself
+        let commitsAfterNotes: number | null = null
+        const anchor = hasSection ? notesAnchor(root, changelogRel, u.version) : null
+        if (anchor != null) {
+            const c = git(root, ['rev-list', '--count', `${anchor}..HEAD`, ...(u.rel === '' ? ['--'] : ['--', u.rel]), `:(exclude)${changelogRel}`])
+            if (c.code === 0) commitsAfterNotes = Number(c.out)
+        }
+        const since = tagLocal ? git(root, ['rev-list', '--count', `${u.tag}..HEAD`, ...pathspec(u)]) : null
+        const tagTree = tagLocal ? treeAt(root, u, u.tag) : null
+        const headTree = tagLocal ? treeAt(root, u, 'HEAD') : null
+
+        let npmLatest: string | null = null
+        let npmError: string | null = null
+        if (u.targets.npm && o.offline !== true) {
+            const res = await fetch(`https://registry.npmjs.org/${u.name}`, { signal: AbortSignal.timeout(10000) }).catch(() => null)
+            if (res == null) npmError = 'registry unreachable'
+            else if (res.ok) {
+                npmLatest = ((await res.json()) as { 'dist-tags'?: { latest?: string } })['dist-tags']?.latest ?? null
+                if (npmLatest == null) npmError = 'registry answered without a dist-tags.latest'
+            } else if (res.status === 404) npmLatest = 'unpublished'
+            else npmError = `registry answered ${res.status}`
+        }
+        const ghRelease = u.targets.githubRelease && o.offline !== true && Bun.which('gh') != null
+            ? Bun.spawnSync(['gh', 'release', 'view', u.tag], { cwd: root }).exitCode === 0
+            : null
+
+        reports.push({
+            id: u.id,
+            rel: u.rel === '' ? '.' : u.rel,
+            name: u.name,
+            version: u.version,
+            tag: u.tag,
+            tagLocal,
+            tagRemote: pushed == null ? null : pushed.has(u.tag),
+            npmLatest,
+            npmError,
+            npmTarget: u.targets.npm,
+            isPrivate: u.isPrivate,
+            ghWanted: u.targets.githubRelease,
+            ghRelease,
+            commitsSinceTag: since != null && since.code === 0 ? Number(since.out) : null,
+            contentDiffers: tagTree != null && headTree != null ? tagTree !== headTree : null,
+            hasSection,
+            commitsAfterNotes,
+            hasUnreleased: hasUnreleasedHeading(changelog),
+        })
+    }
+    return { reports, errors: errors.map(formatUnitError), remote, remoteError }
+}
+
+const npmCell = (r: UnitReport): string => {
+    if (!r.npmTarget) return r.isPrivate ? 'private' : 'off'
+    if (r.npmLatest == null) return '?'
+    return r.npmLatest
+}
+const tagCell = (r: UnitReport): string => {
+    if (!r.tagLocal) return 'missing'
+    if (r.tagRemote == null) return 'local, remote ?'
+    return r.tagRemote ? 'pushed' : 'LOCAL ONLY'
+}
+const ghCell = (r: UnitReport): string => (!r.ghWanted ? 'off' : r.ghRelease == null ? '?' : r.ghRelease ? 'live' : 'missing')
+/** work that landed since the tag. A COLUMN, because it is the normal state of
+ *  a repo between releases, and a warning that is always on says nothing. */
+const sinceCell = (r: UnitReport): string => {
+    if (!r.tagLocal) return 'never tagged'
+    if (r.commitsSinceTag == null) return '?'
+    if (r.commitsSinceTag > 0) return `${r.commitsSinceTag} commit(s)`
+    return r.contentDiffers === true ? 'edited' : 'clean'
+}
+
+/** the sentences the table cannot hold. At most ONE next action per unit:
+ *  two lines telling you to publish and not to publish the same version is
+ *  the tool being useless out loud. Independent facts (a stranded tag, a
+ *  changelog with nothing in it) print beside it.
+ *
+ *  work landing after a release is NORMAL, so it is a table column and never
+ *  a warning: a line that fires on every commit after every release trains
+ *  the reader to skip the ones that mean something. ZERO commits since the tag
+ *  with a differing tree is a different state, and the column word for it
+ *  ("edited") cannot say what it means. */
+export function attentionLines(r: UnitReport): string[] {
+    const out: string[] = []
+    const behindNpm = r.npmTarget && r.npmLatest != null && r.npmLatest !== 'unpublished' && r.npmLatest !== r.version
+    const npmClause = behindNpm ? `, and npm still has ${r.npmLatest ?? ''}` : ''
+    const notesClause = r.hasUnreleased ? '' : 'write the notes under "## Unreleased", then '
+    // the tool knows the unit and its state, never whether the change is a fix,
+    // a feature or a break — stating a kind it cannot know is a guess in the
+    // shape of a command
+    const KIND = '<patch|minor|major>'
+
+    if (r.commitsAfterNotes != null && r.commitsAfterNotes > 0 && !r.tagLocal) {
+        // the trap: a version stamped into package.json while work kept
+        // landing. Publishing it ships that work under notes describing none
+        // of it, so the answer is a NEW version, never this one.
+        out.push(`WARN ${r.id}: ${r.version} was stamped but ${r.commitsAfterNotes} commit(s) landed after its notes${npmClause} — ${notesClause}shipkit bump ${KIND} ${r.id}`)
+    } else if (behindNpm && r.hasSection) {
+        // without the section `shipkit release` refuses (extractChangelogSection
+        // throws), so naming it here is an order the tool knows will fail
+        out.push(`WARN ${r.id}: local ${r.version} vs npm ${r.npmLatest} — shipkit release ${r.id}`)
+    } else if (r.hasUnreleased) {
+        // written notes with no release behind them are a DECISION waiting on
+        // a human, not a defect: a note, so the row still reads as healthy
+        out.push(`note: ${r.id}: "## Unreleased" notes are waiting — shipkit bump ${KIND} ${r.id}`)
+    }
+
+    if (r.commitsSinceTag === 0 && r.contentDiffers === true)
+        out.push(`WARN ${r.id}: nothing landed since ${r.tag}, yet its tree differs from it — ${r.tag} names contents this branch does not carry`)
+    if (r.npmTarget && r.npmError != null)
+        out.push(`WARN ${r.id}: npm ${r.npmError} — drift against the registry is UNASSESSED, not clean`)
+    if (r.tagLocal && r.tagRemote === false)
+        out.push(`WARN ${r.id}: ${r.tag} exists here and nowhere else — invisible on GitHub until it is pushed`)
+    if (!r.hasSection && !r.hasUnreleased)
+        out.push(`WARN ${r.id}: no "## ${r.version}" section and no "## Unreleased" in ${r.id === 'root' ? 'the root changelog' : 'its changelog'} — nothing to release from`)
+    return out
+}
+
+export function renderReports(reports: UnitReport[], o: { remoteError?: string | null; offline?: boolean } = {}): string[] {
+    const rows = [
+        ['UNIT', 'PATH', 'VERSION', 'NPM', 'TAG', 'SINCE TAG', 'GITHUB'],
+        ...reports.map((r) => [r.id, r.rel, r.version, npmCell(r), tagCell(r), sinceCell(r), ghCell(r)]),
+    ]
+    const w = rows[0]!.map((_, i) => Math.max(...rows.map((row) => (row[i] ?? '').length)))
+    const lines = rows.map((row) => row.map((cell, i) => (i === row.length - 1 ? cell : cell.padEnd(w[i]!))).join('  ').trimEnd())
+    for (const r of reports) lines.push(...attentionLines(r))
+    if (o.remoteError != null) lines.push(`WARN ${o.remoteError} — tag push state UNKNOWN, not a tag problem`)
+    // every `?` in the table comes from the same decision, so it is explained
+    // once rather than once per cell
+    if (o.offline === true) lines.push('note: --offline, so npm, the remote and gh were not read (the ? cells)')
+    const subs = reports.length - 1
+    lines.push(`note: ${reports.length} release unit(s) — the repo root${subs > 0 ? ` + ${subs} declared` : ' only, nothing else declared'}`)
+    return lines
+}

package/src/release/unit-gate.ts

@@ -0,0 +1,67 @@
+// what a single unit must prove before its version is written or published.
+// The ROOT unit is the repo, so `shipkit ci` already gates its tests and its
+// typecheck; this adds the per-unit proof only a SUB-unit lacks, because a
+// lib compiles and tests standalone under its own tsconfig and the root
+// tsconfig deliberately excludes it.
+import { existsSync } from 'fs'
+import { join } from 'path'
+import { dirtyPaths } from './git-facts.ts'
+import type { ReleaseUnit } from './units.ts'
+import type { RepoConfig } from '../repo-config.ts'
+
+/** the unit's own tsc: its node_modules, then the repo's, then PATH */
+export function resolveTsc(root: string, unit: ReleaseUnit): string | null {
+    for (const c of [join(unit.dir, 'node_modules/.bin/tsc'), join(root, 'node_modules/.bin/tsc')]) if (existsSync(c)) return c
+    return Bun.which('tsc')
+}
+
+/** the publish argv. `--access public` is not a default: npm restricts a
+ *  scoped package unless it is asked, and a restricted publish looks
+ *  successful right up until a consumer cannot install it. */
+export function npmPublishArgv(o: { npmrc?: string | null } = {}): string[] {
+    return ['npm', 'publish', '--access', 'public', ...(o.npmrc != null ? ['--userconfig', o.npmrc] : [])]
+}
+
+/** count of passing tests in a `bun test` run, or null when the output does
+ *  not say — a suite whose result cannot be read is not a proven suite */
+export const passCount = (out: string): number | null => {
+    const m = out.match(/(\d+) pass/)
+    return m?.[1] != null ? Number(m[1]) : null
+}
+
+/** everything that must hold for this unit, checked before anything is
+ *  written. Empty means the unit is releasable as far as the machine can tell. */
+export function unitBlockers(root: string, config: RepoConfig, unit: ReleaseUnit): string[] {
+    const out: string[] = []
+    // the tag must describe exactly what was packed, or every drift probe
+    // downstream compares a tree that never existed. --allow-dirty deliberately
+    // does NOT reach this: it exists for noise elsewhere in the worktree.
+    if (unit.rel !== '') {
+        const dirty = dirtyPaths(root, config, unit.rel)
+        if (dirty !== '') out.push(`unit '${unit.id}': uncommitted changes under ${unit.rel} — commit them, the tag must describe what ships:\n${dirty.split('\n').slice(0, 6).join('\n')}`)
+    }
+    if (unit.targets.npm && unit.tsconfig == null)
+        out.push(`unit '${unit.id}': publishes to npm but has no tsconfig.json — a package nobody typechecks standalone is a package that breaks on install`)
+    if (unit.id === 'root') return out
+
+    if (Bun.which('bun') == null) return [...out, 'bun is not on PATH']
+    const t = Bun.spawnSync(['bun', 'test'], { cwd: unit.dir })
+    const tOut = `${t.stdout.toString()}${t.stderr.toString()}`
+    if (t.exitCode !== 0) out.push(`unit '${unit.id}': its own test suite is red (exit ${t.exitCode}) — bun test in ${unit.rel}`)
+    else {
+        const pass = passCount(tOut)
+        if (pass == null || pass < 1) out.push(`unit '${unit.id}': its test suite ran 0 tests — a vacuous suite proves nothing, write a real one`)
+    }
+    if (unit.tsconfig != null) {
+        const tsc = resolveTsc(root, unit)
+        if (tsc == null) out.push(`unit '${unit.id}': tsc not resolvable — bun add -d typescript at the repo root`)
+        else {
+            const r = Bun.spawnSync([tsc, '--noEmit', '-p', unit.tsconfig], { cwd: root })
+            if (r.exitCode !== 0) {
+                const lines = `${r.stdout.toString()}${r.stderr.toString()}`.trim().split('\n').slice(0, 8).join('\n')
+                out.push(`unit '${unit.id}': does not typecheck under its own tsconfig — it cannot be published\n${lines}`)
+            }
+        }
+    }
+    return out
+}