rvlib-shipkit 1.0.0 → 1.1.0

package/src/core/floor-resolve.ts

@@ -99,7 +99,7 @@ const SUITE_CLI = fileURLToPath(import.meta.resolve('rvlib-shipkit/src/suite/sui
  *  bunfig, its preload and its `units[].tests` budget apply, after the checks
  *  its `deps` name. Its inputs are its dir and the dirs of the
  *  sibling units its package.json names, derived rather than declared */
-function unitTestTasks(c: RepoConfig, root: string, io: FloorReader, subs: TestUnitDecl[], siblings: Map<string, string[]>, notes: string[], unfilled: { id: string; reason: string }[]): TaskDef[] {
+function unitTestTasks(root: string, io: FloorReader, subs: TestUnitDecl[], siblings: Map<string, string[]>, notes: string[], unfilled: { id: string; reason: string }[]): TaskDef[] {
     const read = io.text
     const out: TaskDef[] = []
     for (const u of subs) {
@@ -258,7 +258,7 @@ export function resolveFloor(c: RepoConfig, root: string, io: FloorReader): Floo
         else { tasks.push(decorate(b.task)); sources[id] = b.source }
     }
     const siblings = siblingUnits(subs, io.text)
-    for (const t of unitTestTasks(c, root, io, subs, siblings, notes, unfilled)) { tasks.push(t); sources[t.id] = 'unit' }
+    for (const t of unitTestTasks(root, io, subs, siblings, notes, unfilled)) { tasks.push(t); sources[t.id] = 'unit' }
     for (const t of unitTypecheckTasks(root, io, subs, siblings, unfilled)) { tasks.push(t); sources[t.id] = 'unit' }
     return { tasks, disabled, unfilled, sources, notes }
 }

package/src/core/git-root.ts

@@ -2,9 +2,10 @@
 // root and its prefix inside it. One rev-parse answers all four, and the answer
 // is remembered per directory, because one gate asks it from a dozen places
 // (store, run record, scan, nesting, three rules) and each ask is a process
-// spawn. A directory with no `.git` in reach is answered without asking. Every remembered answer is re-validated with a few stats on each hit,
+// spawn. A directory with no `.git` in reach is answered without asking, and
+// so is a plain repository root (plainRoot). Every remembered answer is re-validated with a few stats on each hit,
 // so a `git init` or a deleted repo is seen at once in a long-lived process.
-import { existsSync, realpathSync, statSync } from 'fs'
+import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from 'fs'
 import { dirname, join, resolve } from 'path'
 import { gitBin } from './git-bin.ts'
 
@@ -78,8 +79,31 @@ function nothingInReach(dir: string): boolean {
     }
 }
 
+/** the common case answered from the disk: `.git` is a plain directory right
+ *  at `dir`, which git describes as exactly that. Anything unusual (a locating
+ *  variable, a gitfile or a symlinked `.git`, a shared common dir, a config
+ *  that relocates the work tree, marks it bare or includes another file, a
+ *  `.git` owned by someone else) is left to git */
+function plainRoot(dir: string): GitRoot | null {
+    if (LOCATING_ENV.some((k) => (process.env[k] ?? '') !== '')) return null
+    try {
+        const top = realpathSync(dir)
+        const gitDir = join(top, '.git')
+        const st = lstatSync(gitDir)
+        if (!st.isDirectory() || (process.getuid != null && st.uid !== process.getuid())) return null
+        if (!existsSync(join(gitDir, 'HEAD')) || existsSync(join(gitDir, 'commondir'))) return null
+        const cfg = readFileSync(join(gitDir, 'config'), 'utf8')
+        if (/^\s*(worktree\s*=|bare\s*=\s*true|\[include)/im.test(cfg)) return null
+        return { gitDir, commonDir: gitDir, top, prefix: '' }
+    } catch {
+        return null
+    }
+}
+
 function ask(dir: string): Probe {
     if (nothingInReach(dir)) return { root: null, error: 'fatal: not a git repository (or any of the parent directories): .git' }
+    const plain = plainRoot(dir)
+    if (plain != null) return { root: plain, error: '' }
     let p: ReturnType<typeof Bun.spawnSync>
     try {
         p = Bun.spawnSync([gitBin(), 'rev-parse', '--path-format=absolute', '--absolute-git-dir', '--git-common-dir', '--show-toplevel', '--show-prefix'], {

package/src/core/lib-version.ts

@@ -0,0 +1,16 @@
+// the version of this lib: what the running process booted with, and what
+// the package.json on disk says now. The boot version is a MODULE import on
+// purpose: `bun --watch` follows the module graph only, so a version bump
+// (which touches nothing but package.json) restarts a watched hub. Read with
+// fs, the file sits outside the graph and a watched hub never learns of it.
+import { readFileSync } from 'fs'
+import pkg from '../../package.json' with { type: 'json' }
+
+/** the version this process booted with */
+export const LIB_VERSION: string = pkg.version
+
+/** what package.json says at this moment, `?` when it is unreadable. Only a
+ *  process NOT under a watch can see it differ from LIB_VERSION */
+export const diskLibVersion = (): string => {
+    try { return (JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')) as { version?: string }).version ?? '?' } catch { return '?' }
+}

package/src/core/migrate-layout.ts

@@ -34,7 +34,20 @@ import { nestedIn } from './nesting.ts'
 /** the prefix every contract folder carried before `.shipkit/` */
 export const LEGACY_CONTRACT_PREFIX = '.rv-'
 
-export const MIGRATION_MESSAGE = 'chore(machine): move the shipkit folders under .shipkit/'
+const CONFIG_FILE = 'repo.config.ts'
+
+/** what one pass did, in words: the folders it moved and the root files it
+ *  dropped. Empty when it did neither, so no caller prints a sentence with a
+ *  hole where the list should be */
+export function layoutSummary(r: { moved: LayoutMove[]; removed: string[] }): string {
+    const list = (xs: string[]): string => (xs.length <= 1 ? xs.join('') : `${xs.slice(0, -1).join(', ')} and ${xs.at(-1)}`)
+    const folders = r.moved.filter((m) => m.kind !== 'cache').map((m) => `${m.from}/`)
+    const parts = [
+        ...(folders.length > 0 ? [`move ${list(folders)} under ${SHIPKIT_DIR}/`] : []),
+        ...(r.removed.length > 0 ? [`drop the root ${list(r.removed)}, which shipkit writes under ${SHIPKIT_DIR}/`] : []),
+    ]
+    return parts.join(', and ')
+}
 
 /** the contract names a typo is matched against */
 const KNOWN = ['identity', 'assets', 'comfy', 'private', 'reflections', 'social', 'journal', 'domain', 'itch', 'steam', 'discord'] as const
@@ -200,6 +213,39 @@ export function rebaseRelative(text: string, at: { from: string; to: string }, m
         .replace(/(\]\()(\.\.?\/[^)\s#]+)/g, (_m, lead: string, spec: string) => `${lead}${rebase(spec)}`)
 }
 
+/** one repo.config.ts value that names a moved folder, as a path: the folder
+ *  then a slash, behind an optional `!`, `/` or `./`. A word, a bare folder
+ *  name and a longer name that merely starts the same stay as they are */
+function rebasePathValue(v: string, moves: LayoutMove[]): string {
+    const m = /^(!?(?:\/|\.\/)?)(.*)$/s.exec(v)!
+    const rest = m[2]!
+    const hit = moves.find((x) => rest.startsWith(`${x.from}/`))
+    return hit == null ? v : `${m[1]}${hit.to}${rest.slice(hit.from.length)}`
+}
+
+/** PURE: repo.config.ts source with every quoted path that names a moved
+ *  folder rewritten (`leakAllow` paths, `blockedPaths`, `gitignore` lines, a
+ *  prose include, any other value): each of them is a repo path by contract */
+export function sweepConfigSource(text: string, moves: LayoutMove[]): string {
+    if (moves.length === 0) return text
+    return text.replace(/(['"`])((?:\\.|(?!\1)[^\\\n])*)\1/g, (lit, q: string, body: string) => {
+        if (q === '`' && body.includes('${')) return lit
+        const next = rebasePathValue(body, moves)
+        return next === body ? lit : `${q}${next}${q}`
+    })
+}
+
+/** PURE: the loaded config with the same rewrite, so what this pass renders
+ *  from it (the ignore block) reads the values the file now holds. Only plain
+ *  objects and arrays are copied; functions and class instances are kept */
+export function rebaseConfigPaths<T>(v: T, moves: LayoutMove[]): T {
+    if (typeof v === 'string') return rebasePathValue(v, moves) as T
+    if (Array.isArray(v)) return v.map((x) => rebaseConfigPaths(x, moves)) as T
+    if (v != null && typeof v === 'object' && Object.getPrototypeOf(v) === Object.prototype)
+        return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, rebaseConfigPaths(x, moves)])) as T
+    return v
+}
+
 /** PURE: the .gitignore after the move. Old names turn into new ones, except
  *  the folders still on disk (`keep`), whose lines keep guarding them. A
  *  negation of one FILE inside a folder (`!.shipkit/social/README.md`) is dead
@@ -327,9 +373,10 @@ export function legacyHooksOurs(root: string): boolean {
  *  still has core.hooksPath on the vanished `hooks/`, and git runs no hook
  *  from a folder that is not there: the commit gates go dark in silence */
 function repointStaleHooks(root: string): void {
+    // the disk decides first: git is asked only when the move has happened
+    if (existsSync(join(root, 'hooks')) || !existsSync(join(root, LAYOUT.hooks, 'pre-commit'))) return
     const v = git(root, ['config', 'core.hooksPath']).out.trim().replace(/\/+$/, '')
     if (v !== 'hooks' && v !== join(root, 'hooks')) return
-    if (existsSync(join(root, 'hooks')) || !existsSync(join(root, LAYOUT.hooks, 'pre-commit'))) return
     git(root, ['config', 'core.hooksPath', LAYOUT.hooks])
 }
 
@@ -400,8 +447,10 @@ function inProgress(root: string): string | null {
 export type MigrateOpts = {
     config?: RepoConfig
     /** re-render the SK004 block into this .gitignore text (SK004 owns the
-     *  block). `legacy`: an old folder is still on disk, so its name stays ignored */
-    renderGitignore?: (text: string, legacy: boolean) => string
+     *  block). `legacy`: an old folder is still on disk, so its name stays
+     *  ignored. `config`: the repo config with its paths already moved, which
+     *  is what the block must be rendered from */
+    renderGitignore?: (text: string, legacy: boolean, config?: RepoConfig) => string
 }
 
 /** tracked symlinks, with where each points */
@@ -442,8 +491,13 @@ export function migrateLayout(root: string, o: MigrateOpts = {}): LayoutResult {
     const targets = Object.fromEntries(plan.moves.filter((m) => m.kind === 'contract').map((m) => [m.from, m.to]))
     const sources = plan.moves.filter((m) => m.kind !== 'cache').map((m) => m.from)
     const tracked = inGit ? lsFiles(root, [...sources, ...legacyStatus]) : []
-    // a moved file is rebased whether or not it names an old folder
-    const swept = inGit ? [...new Set([...sweepTargets(root, contractNames), ...tracked.filter((t) => /\.(m?[jt]sx?|json|md)$/.test(t))])] : []
+    // a moved file is rebased whether or not it names an old folder, and
+    // repo.config.ts whenever one of its values names one
+    const configNames = inGit && lsFiles(root, [CONFIG_FILE]).length > 0 && sweepConfigSource(readFileSync(join(root, CONFIG_FILE), 'utf8'), plan.moves) !== readFileSync(join(root, CONFIG_FILE), 'utf8') ? [CONFIG_FILE] : []
+    // a legacy generated file is dropped, never rewritten: a rewrite would
+    // write it back after the drop, and the commit would keep it
+    const dropped = new Set<string>(legacyStatus)
+    const swept = inGit ? [...new Set([...sweepTargets(root, contractNames), ...tracked.filter((t) => /\.(m?[jt]sx?|json|md)$/.test(t)), ...configNames])].filter((f) => !dropped.has(f)) : []
     const links = inGit ? trackedLinks(root) : []
     // commit the ignore file when git tracks it, or when this pass creates it:
     // it is what keeps the moved private folders out. An existing untracked
@@ -464,7 +518,8 @@ export function migrateLayout(root: string, o: MigrateOpts = {}): LayoutResult {
         const text = readFileSync(join(root, rel), 'utf8')
         if (text.includes(SWEEP_SKIP)) continue
         const now = movedTo(moves, rel)
-        const next = sweepText(rebaseRelative(text, { from: rel, to: now }, moves), targets, { from: rel, to: now })
+        const paths = rel === CONFIG_FILE ? sweepConfigSource(text, moves) : text
+        const next = sweepText(rebaseRelative(paths, { from: rel, to: now }, moves), targets, { from: rel, to: now })
         if (next !== text) writes.push({ now, text: next })
     }
     const relinks: { now: string; target: string }[] = []
@@ -486,7 +541,8 @@ export function migrateLayout(root: string, o: MigrateOpts = {}): LayoutResult {
 
     const gi = join(root, '.gitignore')
     const giOriginal = existsSync(gi) ? readFileSync(gi, 'utf8') : ''
-    const render = (text: string, legacy: boolean): string => (o.renderGitignore != null ? o.renderGitignore(text, legacy) : text)
+    const config = o.config == null ? undefined : rebaseConfigPaths(o.config, moves)
+    const render = (text: string, legacy: boolean): string => (o.renderGitignore != null ? o.renderGitignore(text, legacy, config) : text)
     const stillOld = (): string[] => dirsIn(root).filter((d) => d.startsWith(LEGACY_CONTRACT_PREFIX))
     try {
         // 1. both layouts ignored while any folder is in flight
@@ -550,7 +606,11 @@ export function migrateLayout(root: string, o: MigrateOpts = {}): LayoutResult {
     const giChanged = giNew || (giTracked && readFileSync(join(root, '.gitignore'), 'utf8') !== giOriginal)
     const touched = [...new Set([...tracked, ...added, ...sweptTracked, ...(giChanged ? ['.gitignore'] : [])])]
     if (touched.length === 0) return out
-    const landed = machineCommit({ anchor: root, message: MIGRATION_MESSAGE, paths: touched.map((p) => join(root, p)) })
+    // the title names what this commit carries; a pass that did neither has
+    // nothing tracked to land and returned above
+    const what = layoutSummary(out)
+    if (what === '') return out
+    const landed = machineCommit({ anchor: root, message: `chore(machine): ${what}`, paths: touched.map((p) => join(root, p)) })
     if (!landed) return { ...out, uncommitted: true, pending: touched }
     out.commit = git(root, ['rev-parse', '--short', 'HEAD']).out.trim()
     return out

package/src/core/motherhome.ts

@@ -17,6 +17,7 @@ import type { RepoConfig } from '../repo-config.ts'
 import { atomicWrite, withFileLock } from './locked-write.ts'
 import { isLinkedWorktree } from './git-root.ts'
 import { machineCommit } from './machine-commit.ts'
+import { LIB_VERSION } from './lib-version.ts'
 
 const BEGIN = '<!-- >>> shipkit local-projects — machine-written, edit outside the markers -->'
 const END = '<!-- <<< shipkit local-projects -->'
@@ -53,9 +54,6 @@ const parseRow = (line: string): Row | null => {
     return m == null ? null : { name: m[1]!, root: m[2]!, version: m[3]!, mode: m[4]!, seen: m[5]! }
 }
 
-function libVersion(): string {
-    try { return (JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')) as { version?: string }).version ?? '?' } catch { return '?' }
-}
 
 // how this repo consumes the lib — `?` on an unreadable package.json (a
 // read failure must never be rendered as the fact 'path')
@@ -91,7 +89,7 @@ export function reportToMotherhome(root: string, config: RepoConfig, today: stri
         const mode = consumptionMode(root)
         // source-consumed code is not the published release its version
         // string names — disclose it
-        const version = mode === 'npm' ? libVersion() : `${libVersion()}+src`
+        const version = mode === 'npm' ? LIB_VERSION : `${LIB_VERSION}+src`
         const me: Row = { name: config.name, root: resolve(root), version, mode, seen: today }
 
         const r = withFileLock(page, (): MotherhomeOutcome => {

package/src/core/package-manager.ts

@@ -7,9 +7,8 @@
 // TRACKED locks decide, because an untracked bun.lock is exactly what a wrong
 // update leaves behind, and reading it as the repo's choice would make that
 // first mistake permanent. Nothing tracked (a fresh tree, no git) falls back
-// to what sits on disk. Among several, the order below IS the preference, and
-// the loser is named so the drift is visible. No lock at all is bun, the
-// house default.
+// to what sits on disk. No lock at all, or locks of two managers, is a
+// REFUSAL that names what it saw: a guessed manager is the failure above.
 import { existsSync } from 'fs'
 import { join } from 'path'
 import { gitBin } from './git-bin.ts'
@@ -24,10 +23,11 @@ export type PackageManager = {
     install: string[]
     /** move these deps to their latest version, manifest AND lock in one call */
     update: (names: string[]) => string[]
-    /** set when several managers own a lock here, so the pick is a guess */
-    warn?: string
 }
 
+/** the manager, or why the lock files do not name exactly one */
+export type PackageManagerPick = PackageManager | { refused: string }
+
 const BUN_LOCKS = ['bun.lock', 'bun.lockb']
 export const LOCK_FILES = [...BUN_LOCKS, 'pnpm-lock.yaml', 'yarn.lock', 'package-lock.json']
 
@@ -70,17 +70,21 @@ export function trackedLocks(root: string): string[] {
 }
 
 /** the manager this repo installs with, read off its lock files */
-export function detectPackageManager(root: string, tracked: string[] = trackedLocks(root)): PackageManager {
+export function detectPackageManager(root: string, tracked?: string[]): PackageManagerPick {
     const present = LOCK_FILES.filter((f) => existsSync(join(root, f)))
-    const owned = present.filter((f) => tracked.includes(f))
+    // git is asked which locks it tracks only when there is a lock to ask about
+    const known = present.length === 0 ? [] : (tracked ?? trackedLocks(root))
+    const owned = present.filter((f) => known.includes(f))
     const locks = owned.length > 0 ? owned : present
-    const has = (f: string): boolean => locks.includes(f)
-    let pick = bun
-    if (BUN_LOCKS.some(has)) pick = bun
-    else if (has('pnpm-lock.yaml')) pick = pnpm
-    else if (has('yarn.lock')) pick = yarn(existsSync(join(root, '.yarnrc.yml')))
-    else if (has('package-lock.json')) pick = npm
-    const others = locks.filter((f) => !pick.locks.includes(f))
-    if (others.length === 0) return pick
-    return { ...pick, warn: `several lock files at the root (${locks.join(', ')}) — updating with ${pick.name}, so ${others.join(', ')} will drift; delete the one this repo does not install with` }
+    const managers = [
+        ...(locks.some((f) => BUN_LOCKS.includes(f)) ? [bun] : []),
+        ...(locks.includes('pnpm-lock.yaml') ? [pnpm] : []),
+        ...(locks.includes('yarn.lock') ? [yarn(existsSync(join(root, '.yarnrc.yml')))] : []),
+        ...(locks.includes('package-lock.json') ? [npm] : []),
+    ]
+    if (managers.length === 1) return managers[0]!
+    if (managers.length === 0) return { refused: `no lock file at the root (looked for ${LOCK_FILES.join(', ')}), so which package manager installs this repo is unknown: install once with the right one and commit its lock` }
+    return { refused: `lock files of ${managers.length} package managers ${owned.length > 0 ? 'are tracked' : 'sit at the root'} (${locks.join(', ')}), so which one installs this repo is unknown: delete the lock of the one it does not install with` }
 }
+
+export const isRefusal = (p: PackageManagerPick): p is { refused: string } => 'refused' in p

package/src/core/raw-access.ts

@@ -72,17 +72,25 @@ function scanSource(src: string, o: ClosureKind): { line: number; what: string }
  *  scanned, and neither is `skip`, the toolkit's own tree when it sits inside
  *  the repo: the toolchain id covers it exactly as it covers an install.
  *  Throws when the closure cannot be walked, which the caller counts as a hit */
-export function rawAccessInClosure(root: string, file: string, o: { skip?: string; configs?: Map<string, RvtConfig> } & ClosureKind = {}): RawAccess | null {
+export function rawAccessInClosure(root: string, file: string, o: { skip?: string; configs?: Map<string, RvtConfig>; texts?: Map<string, string> } & ClosureKind = {}): RawAccess | null {
     // one pass over many checks under one root hands in `configs`, so the
     // root's config (a walk of its source tree) is read once for all of them
     let loaded = o.configs?.get(root)
     if (loaded == null) { loaded = loadConfig(root); o.configs?.set(root, loaded) }
     const cfg = { ...loaded, root }
     const skipped = (f: string): boolean => f.split('/').includes('node_modules') || (o.skip != null && join(root, f).startsWith(`${o.skip}/`))
-    const files = importClosure(cfg, [relative(root, file).replace(/\\/g, '/')], o).filter((f) => !skipped(f))
+    // one pass over many checks hands in `texts` too: their closures share
+    // most of their files, and each is read once for the whole pass
+    const read = (rel: string): string => {
+        const p = join(root, rel)
+        let text = o.texts?.get(p)
+        if (text == null) { text = readFileSync(p, 'utf8'); o.texts?.set(p, text) }
+        return text
+    }
+    const files = importClosure(cfg, [relative(root, file).replace(/\\/g, '/')], { ...o, read }).filter((f) => !skipped(f))
     for (const f of files) {
         let src: string
-        try { src = readFileSync(join(root, f), 'utf8') } catch { continue }
+        try { src = read(f) } catch { continue }
         const hit = rawAccessInSource(src, o)
         if (hit != null) return { file: f, ...hit }
     }

package/src/core/reexec.ts

@@ -0,0 +1,26 @@
+// run this exact invocation again, on whatever code is on disk now. execve
+// replaces the image in place: same pid, same terminal, same argv (so the
+// same flags and the same port), and a `--watch` flag stays in execArgv. A
+// runtime without execve runs the invocation as a child and exits with its
+// code, which keeps the terminal but leaves this process waiting under it.
+import { existsSync } from 'fs'
+
+const argvOf = (): string[] => [process.execPath, ...process.execArgv, ...process.argv.slice(1)]
+
+/** why this invocation cannot run again, null when it can. Asked BEFORE a
+ *  caller tears anything down, so a refusal leaves the process serving */
+export function reexecBlocker(): string | null {
+    const entry = process.argv[1]
+    if (entry != null && entry !== '' && !entry.startsWith('-') && /\.[cm]?[jt]sx?$/.test(entry) && !existsSync(entry)) return `its entry file ${entry} is gone`
+    return null
+}
+
+/** never returns. `env` defaults to this process's own */
+export function reexecSelf(env: Record<string, string | undefined> = process.env): never {
+    const argv = argvOf()
+    const clean = Object.fromEntries(Object.entries(env).filter((e): e is [string, string] => e[1] != null))
+    const execve = (process as { execve?: (file: string, args: string[], env: Record<string, string>) => never }).execve
+    if (typeof execve === 'function') execve.call(process, process.execPath, argv, clean)
+    const child = Bun.spawnSync(argv, { cwd: process.cwd(), stdout: 'inherit', stderr: 'inherit', stdin: 'inherit', env: clean })
+    process.exit(child.exitCode ?? 1)
+}

package/src/core/run-check.ts

@@ -14,10 +14,11 @@ import { Ledger } from '../ledger/ledger.ts'
 import { RunLog, type InvokedBy } from '../ledger/run-log.ts'
 import { storeRoot } from '../ledger/store.ts'
 import { gateBinary } from '../ledger/toolchain-identity.ts'
-import { runChecks, type Audience, type CheckEvent, type CheckResult } from './check-runner.ts'
+import { runChecks, selectChecks, type Audience, type CheckEvent, type CheckResult, type RunnableCheck } from './check-runner.ts'
 import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
 import { reportToMotherhome } from './motherhome.ts'
 import { unknownWhenIds } from './when.ts'
+import { unknownBudgetIds } from './budget.ts'
 import { formatLine, type Line } from './wire.ts'
 import { writeStatus } from './write-status.ts'
 import { CHECK_TABLE_FILE, writeCheckTable } from '../ledger/check-table.ts'
@@ -106,12 +107,37 @@ export type CheckRun = {
     /** `when` entries naming no check of this repo — a toggle that does
      *  nothing is worse than none, so it is fatal too */
     unknownWhen: string[]
+    /** `budgets` entries naming no check of this repo, fatal for the same reason */
+    unknownBudgets: string[]
     /** what every asked-for check did, in declaration order */
     results: CheckResult[]
     /** the run was interrupted or bailed out */
     interrupted: boolean
 }
 
+/** what the runner selects from, built from the pass options in ONE place: the
+ *  ledger is scoped on the same selection the runner then makes */
+function selectionOf(checks: RunnableCheck[], o: CheckOpts, tier: TestTier) {
+    return {
+        checks,
+        audience: o.audience ?? 'health',
+        fullTier: tier === 'full',
+        skipGroups: o.skipGroups,
+        onlyIds: o.only,
+        withIds: o.withIds,
+        onlyBlocking: o.onlyBlocking,
+        buildOnly: o.buildOnly,
+        includeProactive: o.includeProactive,
+        exclude: o.exclude,
+    } satisfies Parameters<typeof selectChecks>[0]
+}
+
+/** the ids a pass with these options executes: the scope its ledger scans for */
+export function passScope(composed: GateCheck[], o: CheckOpts): Set<string> {
+    const tier: TestTier = o.tier ?? envTier()
+    return new Set(selectChecks(selectionOf(composed.map((g) => g.runnable), o, tier)).selected.map((u) => u.id))
+}
+
 /** THE run body: compose this repo's checks, run the set the audience asks
  *  for, and classify the outcome by what each check declared. `shipkit check`
  *  and `shipkit ci` both come through here, and nothing else decides
@@ -135,7 +161,7 @@ export async function runCheckPass(root: string, o: CheckOpts = {}): Promise<Che
     let ledger: Ledger | null = o.ledger ?? null
     if (ledger === null && o.ledger === undefined) {
         try {
-            ledger = Ledger.open(root, composed.map((g) => g.row.decl), { cliEntry: o.cliEntry ?? gateBinary(), fresh: o.fresh })
+            ledger = Ledger.open(root, composed.map((g) => g.row.decl), { cliEntry: o.cliEntry ?? gateBinary(), fresh: o.fresh, scope: passScope(composed, o) })
         } catch { ledger = null }
     }
     // the caller's log, or this run's own: `shipkit check` measures checks too,
@@ -157,24 +183,15 @@ export async function runCheckPass(root: string, o: CheckOpts = {}): Promise<Che
     const collected: Line[] = []
     const sink = (l: string): void => print(l)
     const summary = await runChecks({
-        checks,
+        ...selectionOf(checks, o, tier),
         root,
         config: c,
-        audience,
-        fullTier: tier === 'full',
         logDir: c.logDir ?? join(root, CI_LOG_DIR),
         cache: { storeDir: storeRoot(root), ns: c.name, now: Date.now },
         ledger,
         log,
         childEnv: { [SHARE_ENV]: sharePath, ...(o.fresh === true ? { SHIPKIT_FRESH: '1' } : {}) },
         bail: o.bail,
-        skipGroups: o.skipGroups,
-        onlyIds: o.only,
-        withIds: o.withIds,
-        onlyBlocking: o.onlyBlocking,
-        buildOnly: o.buildOnly,
-        includeProactive: o.includeProactive,
-        exclude: o.exclude,
         print: sink,
         onCheck: (e) => { collected.push(...e.lines); o.onCheck?.(e) },
     })
@@ -205,13 +222,16 @@ export async function runCheckPass(root: string, o: CheckOpts = {}): Promise<Che
     if (o.runLog === undefined && log != null) for (const l of log.flush()) say(l)
     // a `when` id naming nothing is a switch wired to no check: the id is read
     // against the WHOLE inventory this run composed, never its narrowed list
-    const unknownWhen = unknownWhenIds(composed.map((g) => g.row), c)
+    const rows = composed.map((g) => g.row)
+    const unknownWhen = unknownWhenIds(rows, c)
+    const unknownBudgets = unknownBudgetIds(rows.map((r) => r.decl.id), c.budgets)
     return {
         lines: [...collected, ...lines],
         blocked: !summary.ok,
         advisoryFailures: summary.advisoryFailures,
         undeclared: summary.undeclared,
         unknownWhen,
+        unknownBudgets,
         results: summary.results,
         interrupted: summary.interrupted,
     }
@@ -222,14 +242,14 @@ export async function runCheck(root: string, o: CheckOpts = {}): Promise<number>
     const print = o.print ?? ((l: string) => console.log(l))
     const c = o.config ?? (await loadRepoConfig(root))
     const run = await runCheckPass(root, { ...o, config: c })
-    const code = run.blocked || run.undeclared.length > 0 || run.unknownWhen.length > 0 ? 1 : 0
+    const code = run.blocked || run.undeclared.length > 0 || run.unknownWhen.length > 0 || run.unknownBudgets.length > 0 ? 1 : 0
     if (o.json === true) { print(JSON.stringify(run)); return code }
     for (const u of run.undeclared) {
         print(`FAIL: ${u} does not declare whether it blocks`)
         print(`      fix: add \`blocking: true\` (about this repo) or \`false\` (about the world) to that check`)
     }
-    for (const id of run.unknownWhen) {
-        print(`FAIL: when.${id} names no check of this repo`)
+    for (const key of [...run.unknownWhen.map((id) => `when.${id}`), ...run.unknownBudgets.map((id) => `budgets.${id}`)]) {
+        print(`FAIL: ${key} names no check of this repo`)
         print(`      fix: \`shipkit checks\` lists every id; drop the entry or correct it`)
     }
     if (o.status !== false) {

package/src/core/run-ci.ts

@@ -6,15 +6,14 @@
 // (write-status.ts — atomic + lock) unless status:false, and the fix pass plus
 // some checks WRITE, so a run is not read-only unless frozen is set and
 // --no-fix is passed.
-import { join } from 'path'
 import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
 import { reportToMotherhome } from './motherhome.ts'
-import { runCheckPass, type CheckOpts } from './run-check.ts'
+import { passScope, runCheckPass, type CheckOpts } from './run-check.ts'
 import { poolLines } from './slots.ts'
 import { runFixPass } from './run-fixers.ts'
-import { formatLine, type Line } from './wire.ts'
+import { formatLine } from './wire.ts'
 import { writeStatus } from './write-status.ts'
-import { allTasks, composeChecks, envTier, FULL_TESTS_ENV, gateInventory, type TestTier } from '../ledger/gate-checks.ts'
+import { allTasks, composeChecks, envTier, FULL_TESTS_ENV, type TestTier } from '../ledger/gate-checks.ts'
 import { CHECK_TABLE_FILE, writeCheckTable } from '../ledger/check-table.ts'
 import { Ledger } from '../ledger/ledger.ts'
 import { RunLog, type InvokedBy } from '../ledger/run-log.ts'
@@ -170,11 +169,34 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
     // ONE walk for the whole gate: the ledger is keyed on it and the run
     // measures it, and two walks can disagree about what exists
     const composed = await composeChecks(root, c, { tier })
+    // `gate = false` opts a check out of the everyday gate, and failOnAdvisory
+    // (release.requireHealthy) re-arms the world probes, because a repo asking
+    // for exactly those must not have them silently dropped by the opt-out
+    const passOpts: CheckOpts = {
+        status: false,
+        config: c,
+        composed,
+        audience: 'gate',
+        includeProactive: o.failOnAdvisory === true,
+        frozen: o.frozen,
+        onlyBlocking: o.onlyBlockingChecks,
+        only: o.onlyIds,
+        withIds: o.withIds,
+        skipGroups: o.skipGroups,
+        exclude: o.skipTaskIds,
+        buildOnly: o.buildOnly,
+        bail: o.bail,
+        fresh: o.fresh,
+        tier,
+    }
     try {
         ledger = Ledger.open(root, composed.map((g) => g.row.decl), {
             cliEntry: o.cliEntry ?? gateBinary(),
             read: o.ledgerRead,
             fresh: o.fresh,
+            // only what this run executes is scanned: an `--only` run pays for
+            // its own checks, never for the whole inventory
+            scope: passScope(composed, passOpts),
         })
         const reg = ledger.layer.registration
         for (const e of reg.errors) { registrationFailed = true; sink(`FAIL: ${e}`) }
@@ -192,27 +214,9 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
         ledger = null
         sink(`WARN cache unavailable (${String(e).slice(0, 160)}) — every check runs this time, so the gate is correct and slower`)
     }
-    // THE RUN. One engine, one DAG, one pass over everything this gate asks
-    // for: `gate = false` opts a check out of the everyday gate, and
-    // failOnAdvisory (release.requireHealthy) re-arms the world probes,
-    // because a repo asking for exactly those must not have them silently
-    // dropped by the opt-out.
+    // THE RUN. One engine, one DAG, one pass over everything this gate asks for
     const run = await runCheckPass(root, {
-        status: false,
-        config: c,
-        composed,
-        audience: 'gate',
-        includeProactive: o.failOnAdvisory === true,
-        frozen: o.frozen,
-        onlyBlocking: o.onlyBlockingChecks,
-        only: o.onlyIds,
-        withIds: o.withIds,
-        skipGroups: o.skipGroups,
-        exclude: o.skipTaskIds,
-        buildOnly: o.buildOnly,
-        bail: o.bail,
-        fresh: o.fresh,
-        tier,
+        ...passOpts,
         ledger,
         runLog,
         onCheck: o.onCheck,
@@ -231,8 +235,8 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
     }
     // a switch wired to no check does nothing, silently, which is the one thing
     // a toggle must never do
-    for (const id of run.unknownWhen) {
-        sink(`FAIL: when.${id} names no check of this repo`)
+    for (const key of [...run.unknownWhen.map((id) => `when.${id}`), ...run.unknownBudgets.map((id) => `budgets.${id}`)]) {
+        sink(`FAIL: ${key} names no check of this repo`)
         sink(`      fix: \`shipkit checks\` lists every id; drop the entry or correct it`)
     }
     let advisoryFatal = false
@@ -250,7 +254,7 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
     if (ledger != null) for (const l of ledger.header(ledger.commit())) sink(formatLine(l, false))
     // one write for the whole gate, after everything has finished
     for (const l of runLog.flush()) sink(formatLine(l, false))
-    const code = run.blocked || fixFailed || registrationFailed || advisoryFatal || run.undeclared.length > 0 || run.unknownWhen.length > 0 ? 1 : 0
+    const code = run.blocked || fixFailed || registrationFailed || advisoryFatal || run.undeclared.length > 0 || run.unknownWhen.length > 0 || run.unknownBudgets.length > 0 ? 1 : 0
     // motherhome row (docsBase wiki on this disk) — never affects the gate,
     // and never fires under frozen: a bump/release gate must not re-dirty the
     // tree it just proved clean

package/src/core/run-fix.ts

@@ -17,11 +17,14 @@ export type FixOpts = {
      *  not wire-shaped, which the frozen output contract forbids */
     quiet?: boolean
     print?: (line: string) => void
+    /** the config as it stands on disk now, when the caller holds one: a
+     *  second load of a rewritten repo.config.ts can hit the module cache */
+    config?: RepoConfig
 }
 
 export async function runFix(root: string, o: FixOpts = {}): Promise<number> {
     const print = o.print ?? ((l: string) => console.log(l))
-    const config = await loadRepoConfig(root)
+    const config = o.config ?? (await loadRepoConfig(root))
     const env: CheckEnv = { root, config }
     // a fresh context per body: a fixer may rewrite the config, and the body
     // after it must read the one on disk now