rvlib-shipkit 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.17.0
+
+**Correction to 0.16.0.** Its notes and its `--frozen` flag description claimed some combination of flags made `shipkit ci` write nothing. None does: STATUS.md is refreshed on every run unless a caller passes `status: false`. If you wired `ci --no-fix --frozen` into CI expecting a read-only run, it leaves STATUS.md behind, and `--json` is the only output that writes nothing. 0.16.0 also flipped rule SK005 from warning to BLOCKING without saying so: a `link:` dependency that no longer resolves, or a declared dependency that is not installed, now fails the gate.
+
+- **`bump --all` takes a kind per unit.** Write `## Unreleased (minor)` on a unit's changelog heading and a batch release gives each unit the kind it actually needs, in ONE gate. A unit whose heading declares nothing refuses rather than being guessed into a version number. Passing a kind on the command line still applies it to the whole selection, and promoting strips the marker. `shipkit bump <unit>` with no kind works the same way.
+- **`notReleasable` can no longer cover a declared release unit.** An entry naming a container that holds one excused every future package under it while the rule reported green. The two lists state opposite intents, so overlap fails.
+- **A release gates fresh.** SK005 caches a clean pass for a day to rate-limit its registry call, but its blocking branches are local facts about whether the tree can import its own dependencies. Those are measured at release time now, not replayed.
+- **The bump rehearsal reads `git fetch`.** Offline or with an expired credential it could compare against stale remote refs and still report a clean merge. It warns and closes inconclusive instead.
+- New pre-commit gate **root-identity**: the name in the root `package.json` and `repo.config.ts`, index against HEAD, plus staged `.bak`/`.orig`/`.rej`. A fixture builder that escapes its temp dir overwrites those files and every other gate still passes, because a gutted repo lints fine. A deliberate rename passes with `SHIPKIT_ALLOW_IDENTITY_CHANGE=1`.
+- `.rv-private/` joins the SK004 gitignore policy. It holds the leak guard's own keyword file, which was committable in every repo until now.
+- `ci --frozen` exists as a flag, and no TUI panel writes STATUS.md any more, so opening the dashboard cannot overwrite a full gate's verdict with a tasks-only one.
+
 ## 0.16.0
 
 Upgrading from 0.14.0 lands straight here: 0.15.0 was stamped and never

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "rvlib-shipkit",
-    "version": "0.16.0",
+    "version": "0.17.0",
     "description": "All-in-one repo companion: ci gate (task DAG), auto-discovered health checks, release-contract fulfillness, asks queue, md-wiki tools, asset atelier, live tui",
     "license": "MIT",
     "type": "module",

package/src/cli/cmd_Bump.ts

@@ -15,32 +15,41 @@ export class BumpCommand extends Command {
             ['a feature release', 'shipkit bump minor'],
             ['a breaking release', 'shipkit bump major'],
             ['one sub-unit (ids: shipkit releases)', 'shipkit bump minor rvlib-shipkit'],
-            ['every unit that has Unreleased notes, root last', 'shipkit bump patch --all'],
+            ['a whole mixed batch in ONE gate, each unit at the kind its heading declares', 'shipkit bump --all'],
+            ['every unit that has Unreleased notes, all at the same kind', 'shipkit bump patch --all'],
+            ['one unit, kind from its own heading', 'shipkit bump rvlib-shipkit'],
             ['rehearse the whole thing', 'shipkit bump minor --dry-run'],
             ['bump and commit, release later', 'shipkit bump patch --no-release'],
             ['from a feature branch, refuse rather than merge', 'shipkit bump patch --no-merge'],
         ],
     })
 
-    kind = Option.String({ required: true })
+    // both positionals are optional so `bump --all` can read each unit's own
+    // kind. The kinds are a closed set of three words, so a first positional
+    // that is not one of them is a unit id, never an ambiguity
+    kind = Option.String({ required: false })
     unit = Option.String({ required: false })
     dryRun = Option.Boolean('--dry-run', false, { description: 'rehearse: run every preflight, the gate and the prepublish scripts, then stop before any version is written. the gate can rewrite files, and the merge is probed rather than performed, so the release branch never moves' })
     noRelease = Option.Boolean('--no-release', false, { description: 'stop after the version commit, do not tag or publish' })
     noMerge = Option.Boolean('--no-merge', false, { description: 'refuse on a feature branch instead of merging it into the release branch' })
-    all = Option.Boolean('--all', false, { description: 'bump every unit whose changelog carries Unreleased notes, in declared order, root last. The kind applies to ALL of them, so a batch mixing a typo fix and a break wants one bump per unit instead' })
+    all = Option.Boolean('--all', false, { description: 'bump every unit whose changelog carries Unreleased notes, in declared order, root last. Given a kind it applies to ALL of them. Given none, each unit takes the kind from its own "## Unreleased (minor)" heading, and a unit whose heading is silent refuses' })
 
     async execute(): Promise<number> {
-        if (this.kind !== 'major' && this.kind !== 'minor' && this.kind !== 'patch') {
+        const KINDS = ['major', 'minor', 'patch']
+        // `bump rvlib-shipkit` names a unit and leaves the kind to its heading
+        const kind = this.kind != null && KINDS.includes(this.kind) ? (this.kind as BumpKind) : null
+        const unit = kind == null && this.kind != null ? this.kind : this.unit
+        if (kind == null && this.kind != null && this.unit != null) {
             this.context.stderr.write(`FAIL: bump takes major, minor or patch (got '${this.kind}')\n`)
             return 1
         }
         try {
             const config = await loadRepoConfig(process.cwd())
-            return await runBump(process.cwd(), config, this.kind as BumpKind, {
+            return await runBump(process.cwd(), config, kind, {
                 dryRun: this.dryRun,
                 noRelease: this.noRelease,
                 noMerge: this.noMerge,
-                unit: this.unit,
+                unit,
                 all: this.all,
                 print: (l) => this.context.stdout.write(`${l}\n`),
             })

package/src/cli/cmd_Ci.ts

@@ -21,9 +21,9 @@ export class CiCommand extends Command {
 
     bail = Option.Boolean('--bail', false, { description: 'stop at the first failure' })
     json = Option.Boolean('--json', false, { description: 'machine-readable result instead of wire lines' })
-    fix = Option.Boolean('--fix', true, { description: 'repair the mechanical slots before gating. Default on. --no-fix skips the repair pass, checks can still write, add --frozen for a run that writes nothing. Under CI the fixers still run but the gate FAILS on any file they rewrite' })
+    fix = Option.Boolean('--fix', true, { description: 'repair the mechanical slots before gating. Default on. --no-fix skips the repair pass, checks can still write. Under CI the fixers still run but the gate FAILS on any file they rewrite' })
     fixRules = Option.Boolean('--fix-rules', true, { description: 'apply the structural rule autofixes too. Default on. --no-fix-rules leaves repo config alone' })
-    frozen = Option.Boolean('--frozen', false, { description: 'report-only mode for self-maintaining rules (SK005 never touches package.json). With --no-fix, the run writes nothing' })
+    frozen = Option.Boolean('--frozen', false, { description: 'report-only mode for self-maintaining rules (SK005 never touches package.json). STATUS.md is still refreshed, so no combination of flags makes the run write nothing' })
     skip = Option.Array('--skip', [], { description: 'skip a task group (repeatable)' })
     withIds = Option.Array('--with', [], { description: 'include an opt-in task (repeatable)' })
     only = Option.Array('--only', [], { description: 'run only this task + its dep closure (repeatable)' })

package/src/core/run-ci.ts

@@ -27,6 +27,9 @@ export type CiOpts = {
     fix?: boolean
     /** also apply the structural SK rule fixers during the fix pass */
     fixRules?: boolean
+    /** bust every check's TTL cache. A release gates with this on: a blocking
+     *  rule replaying a clean pass from hours ago is not a gate. */
+    fresh?: boolean
     /** report-only for self-maintaining rules and checks (SHIPKIT_FROZEN
      *  travels to child checks). The release path passes it: a rule that
      *  rewrites package.json between the gate and `npm publish` packs a tree
@@ -93,7 +96,7 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
     // declares whether it blocks, and that is the only question about it.
     const checks = o.skipChecks === true
         ? { lines: [], blocked: false, advisoryFailures: [], undeclared: [] }
-        : await collectChecks(root, { status: false, config: c, frozen: o.frozen })
+        : await collectChecks(root, { status: false, config: c, frozen: o.frozen, fresh: o.fresh })
     const color = process.stdout.isTTY && process.env.NO_COLOR == null
     for (const l of checks.lines) { collected.push(formatLine(l, false)); print(formatLine(l, color)) }
     for (const u of checks.undeclared) {

package/src/hooks/root-identity.ts

@@ -0,0 +1,64 @@
+// a commit must not silently change WHICH REPO this is.
+//
+// the failure this exists for: a fixture builder ran with its cwd on the real
+// repo instead of a temp dir, overwrote the root package.json and
+// repo.config.ts with a throwaway shape, and committed. Every other gate
+// passed, because a gutted repo still lints, still typechecks and still has a
+// valid package.json. Only the NAME betrayed it.
+import { existsSync } from 'fs'
+import { join } from 'path'
+
+export type IdentityOutcome =
+    | { status: 'skipped'; reason: string }
+    | { status: 'clean' }
+    | { status: 'changed'; changes: string[]; scratch: string[] }
+
+/** scratch files a refactor leaves behind. They are never a deliberate commit,
+ *  and one of them rode in with the fixture accident. */
+const SCRATCH = /\.(bak|orig|rej)$/
+
+const git = (root: string, args: string[]): { code: number; out: string } => {
+    const p = Bun.spawnSync(['git', ...args], { cwd: root, env: process.env })
+    return { code: p.exitCode, out: p.stdout.toString() }
+}
+
+/** the `name:` a repo.config.ts declares, read textually: importing it would
+ *  run the file, and the staged version is exactly the one not to trust. */
+export function configName(source: string): string | null {
+    return source.match(/\bname\s*:\s*['"`]([^'"`]+)['"`]/)?.[1] ?? null
+}
+
+export function packageName(source: string): string | null {
+    try { return (JSON.parse(source) as { name?: string }).name ?? null }
+    catch { return null }
+}
+
+/** compare the INDEX against HEAD: what is about to be committed, versus what
+ *  the repo already agreed it is. Absent on either side is not a change, so
+ *  adding or removing a file is left to the rules that own that. */
+function identityDrift(root: string, path: string, read: (s: string) => string | null): string | null {
+    const staged = git(root, ['show', `:${path}`])
+    const head = git(root, ['show', `HEAD:${path}`])
+    if (staged.code !== 0 || head.code !== 0) return null
+    const before = read(head.out)
+    const after = read(staged.out)
+    if (before == null || after == null || before === after) return null
+    return `${path}: name '${before}' → '${after}'`
+}
+
+export function runRootIdentity(root: string): IdentityOutcome {
+    if (git(root, ['rev-parse', '--verify', 'HEAD']).code !== 0)
+        return { status: 'skipped', reason: 'no HEAD yet — nothing to compare the first commit against' }
+    if (process.env['SHIPKIT_ALLOW_IDENTITY_CHANGE'] === '1')
+        return { status: 'skipped', reason: 'SHIPKIT_ALLOW_IDENTITY_CHANGE=1' }
+
+    const changes = [
+        identityDrift(root, 'package.json', packageName),
+        ...(existsSync(join(root, 'repo.config.ts')) ? [identityDrift(root, 'repo.config.ts', configName)] : []),
+    ].filter((c): c is string => c != null)
+
+    const added = git(root, ['diff', '--cached', '--name-only', '--diff-filter=A'])
+    const scratch = added.out.split('\n').map((l) => l.trim()).filter((l) => l !== '' && SCRATCH.test(l))
+
+    return changes.length === 0 && scratch.length === 0 ? { status: 'clean' } : { status: 'changed', changes, scratch }
+}

package/src/hooks/run-hooks.ts

@@ -7,6 +7,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
 import { join } from 'path'
 import { commitMessageOffenses } from './commit-message.ts'
 import { runLeakGuard } from './leak-guard.ts'
+import { runRootIdentity } from './root-identity.ts'
 import { spawnWithTimeout } from '../core/spawn-timeout.ts'
 import type { RepoConfig } from '../repo-config.ts'
 
@@ -20,7 +21,7 @@ export type HooksConfig = {
     /** keyword file for the leak guard (default '.rv-private/banned-keywords.txt') */
     keywordFile?: string
     /** disable a built-in gate, visible in `hooks list`, never silent */
-    disable?: ('leak-guard' | 'commit-message')[]
+    disable?: ('leak-guard' | 'commit-message' | 'root-identity')[]
 }
 
 const HOOK_DIR = 'hooks'
@@ -66,6 +67,22 @@ export async function runPreCommit(root: string, config: RepoConfig): Promise<Ga
             ],
         })
     }
+    if (!(h.disable ?? []).includes('root-identity')) {
+        const r = runRootIdentity(root)
+        if (r.status === 'skipped') out.push({ id: 'root-identity', ok: true, lines: [`skip: root-identity (${r.reason})`] })
+        else if (r.status === 'clean') out.push({ id: 'root-identity', ok: true, lines: ['ok: root-identity unchanged'] })
+        else out.push({
+            id: 'root-identity',
+            ok: false,
+            lines: [
+                `FAIL: this commit changes WHICH REPO this is, which is almost always a fixture that escaped its temp dir`,
+                ...r.changes.map((c) => `      ${c}`),
+                ...r.scratch.map((s) => `      adds a scratch file: ${s}`),
+                `      fix: restore the real files (git checkout HEAD -- package.json repo.config.ts) and drop the scratch files`,
+                `      a deliberate rename: SHIPKIT_ALLOW_IDENTITY_CHANGE=1 git commit ...`,
+            ],
+        })
+    }
     for (const c of h.preCommit ?? []) {
         const r = await spawnWithTimeout(c.cmd, { cwd: root, timeoutMs: 120_000 })
         out.push({
@@ -123,6 +140,7 @@ export function listGates(config: RepoConfig, root = process.cwd()): string[] {
     const leakState = off.has('leak-guard') ? ' (DISABLED by config)' : existsSync(join(root, kw)) ? '' : ` (INACTIVE, ${kw} absent)`
     return [
         `pre-commit  leak-guard${leakState} — staged content + paths vs ${kw}`,
+        `pre-commit  root-identity${off.has('root-identity') ? ' (DISABLED by config)' : ''} — the repo's own name in package.json + repo.config.ts, and scratch files`,
         ...(h.preCommit ?? []).map((c) => `pre-commit  ${c.id} — ${c.cmd.join(' ')}`),
         `commit-msg  commit-message${off.has('commit-message') ? ' (DISABLED by config)' : ''} — dash punctuation + AI attribution`,
         `commit-msg  leak-guard${leakState} — the message text`,

package/src/release/changelog.ts

@@ -28,11 +28,28 @@ export function extractChangelogSection(p: { changelog: string; version: string
 export const hasVersionSection = (changelog: string, version: string): boolean =>
     changelog.split('\n').some((l) => changelogHeading(version).test(l.trim()))
 
-const UNRELEASED = /^##\s*\[?unreleased\]?\s*$/i
+// the heading may carry the kind this release IS: `## Unreleased (minor)`.
+// Whoever writes the notes knows whether they broke something, and that is
+// the only moment the answer is cheap. A batch release then needs no single
+// kind imposed across units that changed by different amounts.
+const UNRELEASED = /^##\s*\[?unreleased\]?\s*(?:\((major|minor|patch)\))?\s*$/i
+
+export type ReleaseKind = 'major' | 'minor' | 'patch'
 
 export const hasUnreleasedHeading = (changelog: string): boolean =>
     changelog.split('\n').some((l) => UNRELEASED.test(l.trim()))
 
+/** the kind declared on the Unreleased heading, or null when it says nothing.
+ *  Null is never guessed into a kind: `--all` refuses and names the unit,
+ *  because a wrong version number reaches a registry and cannot be recalled. */
+export function declaredKind(changelog: string): ReleaseKind | null {
+    for (const l of changelog.split('\n')) {
+        const m = l.trim().match(UNRELEASED)
+        if (m != null) return (m[1]?.toLowerCase() as ReleaseKind | undefined) ?? null
+    }
+    return null
+}
+
 /** rename the Unreleased heading to the new version. Returns the new text, or
  *  an error when there is no such section or it carries no notes: a version
  *  with empty notes is a version nobody can read later. */

package/src/release/run-bump.ts

@@ -28,7 +28,7 @@
 // that cannot roll back is a lie.
 import { existsSync, readFileSync, writeFileSync } from 'fs'
 import { relative } from 'path'
-import { hasUnreleasedNotes, promoteUnreleased } from './changelog.ts'
+import { declaredKind, 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'
@@ -145,7 +145,12 @@ function probeMergeIntoReleaseBranch(
     p: { from: string; to: string; remote: string; print: (l: string) => void },
 ): MergeRehearsal {
     const { from, to, remote, print } = p
-    git(['fetch', remote, '--quiet'])
+    // a rehearsal's ONLY product is this answer, so it must not be computed
+    // from a remote ref that never refreshed. Offline, an expired credential
+    // or a declined prompt all land here.
+    const fetched = git(['fetch', remote, '--quiet'])
+    const stale = fetched.code !== 0
+    if (stale) print(`WARN could not fetch '${remote}' (git fetch exited ${fetched.code}) — the remote refs below may be stale`)
     const remoteRef = `${remote}/${to}`
     const localExists = git(['rev-parse', '--quiet', '--verify', to]).code === 0
     const remoteExists = git(['rev-parse', '--quiet', '--verify', remoteRef]).code === 0
@@ -173,12 +178,14 @@ function probeMergeIntoReleaseBranch(
         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 }
+    // a clean answer computed from refs that never refreshed proves less than
+    // it says, so the rehearsal declines to close clean
+    return { refuse: false, inconclusive: stale }
 }
 
-type Selected = { unit: ReleaseUnit; version: string; changelogRel: string }
+type Selected = { unit: ReleaseUnit; version: string; changelogRel: string; kind: BumpKind }
 
-export async function runBump(root: string, config: RepoConfig, kind: BumpKind, o: BumpOpts = {}): Promise<number> {
+export async function runBump(root: string, config: RepoConfig, kind: BumpKind | null, 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 }
 
@@ -283,12 +290,22 @@ export async function runBump(root: string, config: RepoConfig, kind: BumpKind,
     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)
+        const source = readFileSync(unit.changelog, 'utf8')
+        // an explicit kind on the command line wins for the whole selection.
+        // Without one, each unit answers for itself from its own heading, and
+        // a unit that never said is a refusal: guessing a version number
+        // publishes it, and a published number cannot be recalled.
+        const unitKind = kind ?? declaredKind(source)
+        if (unitKind == null) {
+            blockers.push(`unit '${unit.id}': ${changelogRel} does not say what kind of release this is — write "## Unreleased (minor)", or pass a kind that applies to every selected unit`)
+            continue
+        }
+        let version: string
+        try { version = nextVersion(unit.version, unitKind) }
+        catch (e) { blockers.push(`unit '${unit.id}': ${e instanceof Error ? e.message : String(e)}`); continue }
+        const promoted = promoteUnreleased(source, version)
         if ('error' in promoted) { blockers.push(`unit '${unit.id}': ${promoted.error}`); continue }
         const tag = renderTag(unit, version)
         if (tagExistsLocally(root, tag)) {
@@ -300,7 +317,7 @@ export async function runBump(root: string, config: RepoConfig, kind: BumpKind,
             continue
         }
         blockers.push(...unitBlockers(root, config, unit))
-        selected.push({ unit, version, changelogRel })
+        selected.push({ unit, version, changelogRel, kind: unitKind })
     }
     // 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
@@ -312,7 +329,7 @@ export async function runBump(root: string, config: RepoConfig, kind: BumpKind,
     }))
     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})`)
+    for (const s of selected) print(`note: ${s.unit.id} ${s.unit.version} → ${s.version} (${s.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

package/src/release/run-release.ts

@@ -92,6 +92,10 @@ export async function runReleaseGate(root: string, config: RepoConfig, print: (l
         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}`),

package/src/rules/SK004-gitignore-policy.ts

@@ -18,6 +18,9 @@ const END = '# <<< shipkit gitignore policy'
 const CONTRIB = '# repo-contributed lines (repo.config.ts gitignore:)'
 
 const POLICY_LINES = [
+    // the leak guard reads .rv-private/banned-keywords.txt: the file listing
+    // what must never be committed cannot itself be committable
+    '.rv-private/',
     '.rv-reflections/',
     '.rv-social/',
     '.rv-journal/',

package/src/rules/SK010-undeclared-release-unit.ts

@@ -98,7 +98,18 @@ export const undeclaredReleaseUnit: Rule = {
             return
         }
         const excused = decls.map((d) => join(env.root, d))
-        const claimed = [...units.filter((u) => u.rel !== '').map((u) => u.dir), ...excused]
+        const declaredDirs = units.filter((u) => u.rel !== '').map((u) => u.dir)
+        // an excuse that also covers a RELEASE UNIT is the kill switch one
+        // level down: `notReleasable: ['libs']` beside `units: [libs/a]` reads
+        // as green while every new package under libs/ hides. The two lists
+        // describe opposite intents, so they must not overlap.
+        const overlapping = decls.filter((d) => declaredDirs.some((u) => u === join(env.root, d) || u.startsWith(`${join(env.root, d)}/`)))
+        if (overlapping.length > 0) {
+            for (const d of overlapping)
+                t.fail(`notReleasable '${d}' also covers a declared release unit, so it excuses every package under it while reading as green`, `repo.config notReleasable: name the dirs that are NOT release units, never a container holding one`)
+            return
+        }
+        const claimed = [...declaredDirs, ...excused]
         const orphans = pkgs.filter((d) => !covered(claimed, d))
         if (orphans.length === 0) {
             // PACKAGES, not entries: one entry over a nested tree excuses more