rvlib-shipkit 1.4.0 → 1.5.0

package/src/core/port-check-cli.ts

@@ -0,0 +1,52 @@
+// THE WRITE HALF of the check file port (core/port-check-file.ts), in its own
+// process: whether an undeclared `run` body can be keyed on its reads is a walk
+// of its import closure on disk (core/raw-access.ts), which no check context
+// read can stand for, so SK029's repair reaches it through `c.exec`.
+//
+//   bun port-check-cli.ts <root> <rel> [<rel> …]   → one json line on stdout
+import { readFileSync } from 'fs'
+import { join } from 'path'
+import { atomicWrite } from './locked-write.ts'
+import { LIB_ROOT } from './lib-root.ts'
+import { rawAccessInClosure } from './raw-access.ts'
+import { findCheckObject, portCheckSource, retiredKeysIn } from './port-check-file.ts'
+import { plainDefaultFor } from './port-check-files.ts'
+
+export type PortRun = { did: string[]; hand: string[] }
+
+/** why an undeclared `run` body cannot be keyed on its reads, or null */
+function rawAccessOf(root: string, rel: string, src: string): string | null {
+    const obj = findCheckObject(src, { plainDefault: plainDefaultFor(rel) })
+    const keys = new Set(obj?.props.map((p) => p.key) ?? [])
+    if (!keys.has('run') || keys.has('inputs') || keys.has('ttl') || keys.has('never')) return null
+    const r = rawAccessInClosure(root, join(root, rel), { skip: LIB_ROOT })
+    return r == null ? null : `its imports reach the disk around c (${r.file}:${r.line}, ${r.what})`
+}
+
+export function portFiles(root: string, rels: string[]): PortRun {
+    const did: string[] = []
+    const hand: string[] = []
+    for (const rel of rels) {
+        const abs = join(root, rel)
+        let src: string
+        try { src = readFileSync(abs, 'utf8') } catch (e) { hand.push(`${rel}: unreadable (${(e as Error).message})`); continue }
+        const plainDefault = plainDefaultFor(rel)
+        const keys = retiredKeysIn(src, { plainDefault })
+        if (keys.length === 0) continue
+        const r = portCheckSource(src, { plainDefault, rawAccess: rawAccessOf(root, rel, src) })
+        if ('error' in r) { hand.push(`${rel}: ${r.error}`); continue }
+        if (!r.changed) continue
+        atomicWrite(abs, r.source)
+        did.push(`${rel} declares runs, cache, fix and applies (was: ${keys.join(', ')})${r.notes.length > 0 ? `. Note: ${r.notes.join('; ')}` : ''}`)
+    }
+    return { did, hand }
+}
+
+if (import.meta.main) {
+    const [root, ...rels] = process.argv.slice(2)
+    if (root == null) {
+        console.error('usage: bun port-check-cli.ts <root> <rel> [<rel> …]')
+        process.exit(2)
+    }
+    console.log(JSON.stringify(portFiles(root, rels)))
+}

package/src/core/port-check-file.ts

@@ -0,0 +1,295 @@
+// THE PORT of a check file written before every context was explicit: its
+// source in, the same check out with `runs`, `cache`, `fix` and `applies`
+// spelled out, carrying the values the retired keys resolved to (the gate,
+// the health pass and the planner of 0.62), so a ported check runs exactly
+// where it ran before. Pure: text in, text out. SK016 reports what this finds
+// and its repair applies it (core/port-check-cli.ts reaches the disk).
+//
+// the one constraint a reader breaks first: it edits the check object by the
+// RANGE of each top level property, found on a masked copy of the source
+// (strings, comments and regex literals blanked), so a value, a comment or a
+// multi line lambda it does not touch comes out byte for byte.
+
+/** the keys the explicit declaration retired */
+export const RETIRED_KEYS = ['when', 'inputs', 'ttl', 'never', 'every', 'cron', 'whenInactive', 'planOff', 'cacheKey'] as const
+
+/** the range a repo row nothing keys ran on, before it declared one */
+const DAILY = "['20h', '28h']"
+
+/** the source with every string, comment, template text and regex literal
+ *  blanked to spaces, newlines kept, so offsets line up with the original */
+export function maskSource(src: string): string {
+    const out = src.split('')
+    const blank = (from: number, to: number): void => { for (let k = from; k < to; k++) if (out[k] !== '\n') out[k] = ' ' }
+    let i = 0
+    // one entry per open template: the brace depth of its current `${`
+    const tpl: number[] = []
+    let last = ''
+    const regexOk = (): boolean => last === '' || '(,=:[!&|?{};+-*%<>~^'.includes(last)
+    const readTemplateText = (): void => {
+        // at a character inside template text: blank until `${` or the closing backtick
+        const start = i
+        while (i < src.length && src[i] !== '`' && !(src[i] === '$' && src[i + 1] === '{')) i += src[i] === '\\' ? 2 : 1
+        blank(start, i)
+        if (src[i] === '`') { i++; tpl.pop(); last = 'x' } else { i += 2; tpl[tpl.length - 1] = 0; last = '{' }
+    }
+    while (i < src.length) {
+        const ch = src[i]!
+        const next = src[i + 1]
+        if (ch === '/' && next === '/') { const s = i; while (i < src.length && src[i] !== '\n') i++; blank(s, i); continue }
+        if (ch === '/' && next === '*') { const s = i; const e = src.indexOf('*/', i + 2); i = e < 0 ? src.length : e + 2; blank(s, i); continue }
+        if (ch === "'" || ch === '"') {
+            const s = i
+            i++
+            while (i < src.length && src[i] !== ch && src[i] !== '\n') i += src[i] === '\\' ? 2 : 1
+            i++
+            blank(s + 1, i - 1)
+            last = 'x'
+            continue
+        }
+        if (ch === '`') { tpl.push(-1); i++; readTemplateText(); continue }
+        if (tpl.length > 0 && tpl[tpl.length - 1]! >= 0) {
+            if (ch === '{') tpl[tpl.length - 1]!++
+            if (ch === '}') {
+                if (tpl[tpl.length - 1] === 0) { tpl[tpl.length - 1] = -1; i++; readTemplateText(); continue }
+                tpl[tpl.length - 1]!--
+            }
+        }
+        if (ch === '/' && regexOk()) {
+            const s = i
+            let j = i + 1
+            let inClass = false
+            while (j < src.length && src[j] !== '\n') {
+                if (src[j] === '\\') { j += 2; continue }
+                if (src[j] === '[') inClass = true
+                else if (src[j] === ']') inClass = false
+                else if (src[j] === '/' && !inClass) break
+                j++
+            }
+            if (src[j] === '/') { j++; while (/[a-z]/.test(src[j] ?? '')) j++; blank(s + 1, j - 1); i = j; last = 'x'; continue }
+        }
+        if (!/\s/.test(ch)) last = ch
+        i++
+    }
+    return out.join('')
+}
+
+/** one top level property of the check object: its whole segment (leading
+ *  whitespace and comments included), and where its key and value sit */
+export type Prop = { key: string | null; seg: [number, number]; keyAt: number; value: string }
+
+export type CheckObject = { open: number; close: number; props: Prop[]; indent: string }
+
+const KEY_RE = /^\s*(?:(?:async|get|set)\s+)?([A-Za-z_$][\w$]*)\s*\??\s*[:(]/
+
+/** the check object of a file: `check({...})`, else `export default {...}`
+ *  in a check file. Null when there is none */
+export function findCheckObject(src: string, o: { plainDefault: boolean }): CheckObject | null {
+    const m = maskSource(src)
+    const call = /\bcheck\s*\(\s*\{/.exec(m)
+    const plain = o.plainDefault ? /\bexport\s+default\s*\{/.exec(m) : null
+    const hit = call ?? plain
+    if (hit == null) return null
+    const open = hit.index + hit[0].length - 1
+    let depth = 0
+    let start = open + 1
+    const segs: [number, number][] = []
+    let close = -1
+    for (let k = open; k < m.length; k++) {
+        const ch = m[k]
+        if (ch === '{' || ch === '(' || ch === '[') depth++
+        else if (ch === '}' || ch === ')' || ch === ']') {
+            depth--
+            if (depth === 0) { segs.push([start, k]); close = k; break }
+        } else if (ch === ',' && depth === 1) { segs.push([start, k]); start = k + 1 }
+    }
+    if (close < 0) return null
+    const props: Prop[] = segs.map(([a, b]) => {
+        const km = KEY_RE.exec(m.slice(a, b))
+        if (km == null) return { key: null, seg: [a, b], keyAt: -1, value: '' }
+        const keyAt = a + km.index + km[0].indexOf(km[1]!)
+        const colon = m.indexOf(':', keyAt)
+        const isColon = colon >= 0 && colon < b && m.slice(keyAt + km[1]!.length, colon).trim().replace('?', '') === ''
+        return { key: km[1]!, seg: [a, b], keyAt, value: isColon ? src.slice(colon + 1, b).trim() : '' }
+    })
+    const first = props.find((p) => p.key != null)
+    const indent = first == null ? '    ' : (/[ \t]*$/.exec(src.slice(0, first.keyAt))?.[0] ?? '    ')
+    return { open, close, props, indent }
+}
+
+/** what a file's check object lacks or still says in the retired shape: each
+ *  retired key it declares, `fix` when it is a function, and `runs` when the
+ *  object declares none (a file that declared nothing ran on defaults) */
+export function retiredKeysIn(src: string, o: { plainDefault: boolean }): string[] {
+    const obj = findCheckObject(src, o)
+    if (obj == null) return []
+    const keys = new Set(obj.props.map((p) => p.key))
+    const out: string[] = RETIRED_KEYS.filter((k) => keys.has(k))
+    const fix = obj.props.find((p) => p.key === 'fix')
+    if (fix != null && !/^(['"])(none|ci|manual)\1$/.test(fix.value)) out.push('fix')
+    if (!keys.has('runs') && (keys.has('run') || keys.has('cmd'))) out.push('runs')
+    return out
+}
+
+/** a string literal's value, or null for any other expression */
+export const literal = (v: string | undefined): string | null => {
+    const m = v == null ? null : /^(['"`])([^'"`$\\]*)\1$/.exec(v.trim())
+    return m == null ? null : m[2]!
+}
+
+/** what a check declared before, as the port reads it */
+export type LegacyDecl = {
+    /** the `when` literal, null when absent, undefined when it is not a literal */
+    when: string | null | undefined
+    build: boolean
+    body: 'run' | 'cmd'
+    /** the expression text of each declaration, absent when not declared */
+    inputs?: string
+    ttl?: string
+    never?: string
+    cacheKey?: string
+    every?: string
+    cron?: string
+    whenInactive?: string
+    planOff?: string
+    /** a repair function is declared */
+    repair: boolean
+    /** why the body's imports reach the disk around `c`, for an undeclared
+     *  `run` body (core/raw-access.ts), else null */
+    rawAccess: string | null
+}
+
+export type Derived = { runs: string; cache: string; fix: string; applies: string; notes: string[] }
+
+/** the explicit declaration a legacy one resolved to, or why it cannot be
+ *  carried across without a person */
+export function deriveExplicit(d: LegacyDecl, q: (s: string) => string): Derived | { error: string } {
+    const notes: string[] = []
+    if (d.when === undefined) return { error: '`when` is not a string literal' }
+    const whenLit = d.when
+    const off = whenLit != null && (whenLit === 'off' || whenLit.startsWith('off:')) ? whenLit.slice(4).trim() || 'off' : null
+    const at = off != null ? 'always' : (whenLit ?? 'always')
+    if (!['always', 'release', 'health'].includes(at)) return { error: `when '${whenLit}' is not always, release, health or off:<why>` }
+    const ttlLit = d.ttl == null ? null : literal(d.ttl)
+    const forever = ttlLit === 'forever'
+    // the population the gate read it as
+    const keyed = d.inputs != null || (d.ttl == null && d.never == null && d.body === 'run' && d.rawAccess == null)
+    const world = d.ttl != null
+    // the gate axes: a build step never ran in the health pass
+    const gates = at === 'always' ? [true, true, true] : at === 'release' ? [false, true, true] : [false, false, false]
+    const onHealth = !d.build && true
+    // the planner: only an always or health row, and never a build step off the gate
+    const plannable = (at === 'always' || at === 'health') && !(d.build && at === 'health')
+    const gate = at !== 'health'
+    const declaredClock = d.cron != null || d.every !== undefined
+    const fallback = forever ? "'once'" : d.ttl != null ? d.ttl : d.build ? null : keyed ? null : DAILY
+    const clocked = fallback != null || declaredClock
+    const onChange = forever || (!world && (keyed || (gate && !clocked)))
+    let onSave = 'false'
+    let onClock = 'false'
+    if (plannable) {
+        onSave = onChange ? (keyed || forever ? "'moved'" : "'burst'") : 'false'
+        const every = d.cron ?? (d.every !== undefined ? d.every : fallback)
+        if (every != null && every.trim() !== 'null') {
+            if (literal(every) === 'once') onClock = "'once'"
+            else onClock = `{ every: ${every}, inactive: ${d.whenInactive ?? q('wait')} }`
+        }
+    }
+    if (onClock === "'once'" && !forever) return { error: "every 'once' without ttl 'forever': a fact asked once needs a declared value" }
+    if (forever && onClock !== "'once'" && plannable) return { error: "ttl 'forever' with a declared every: a fact is asked once, never on a period" }
+    let cache: string
+    if (d.inputs != null) cache = `{ by: ${q('files')}, inputs: ${d.inputs}, key: ${d.cacheKey ?? 'null'} }`
+    else if (forever) cache = `{ by: ${q('fact')}, key: ${d.cacheKey ?? `() => ${q('declared')}`} }`
+    else if (d.ttl != null) cache = `{ by: ${q('ttl')}, span: ${d.ttl}, key: ${d.cacheKey ?? 'null'} }`
+    else if (d.never != null) cache = `{ by: ${q('never')}, why: ${d.never} }`
+    else if (d.body === 'run' && d.rawAccess == null) cache = `{ by: ${q('reads')} }`
+    else if (d.body === 'run') cache = `{ by: ${q('never')}, why: ${q(d.rawAccess!)} }`
+    else cache = `{ by: ${q('never')}, why: ${q('a cmd declaring no inputs: nothing keys it')} }`
+    if (forever && !plannable) return { error: "ttl 'forever' on a check the planner never ran: a fact nobody asks once is never answered" }
+    // the ci fix pass applied every repair; a check off the quick gate now
+    // repairs only by name
+    const fix = !d.repair ? 'none' : gates[0] ? 'ci' : 'manual'
+    if (d.repair && !gates[0]) notes.push("its repair ran in the ci fix pass although the gate did not run it: now fix 'manual', shipkit check --fix <id> applies it")
+    if (d.build && d.repair) return { error: 'a build step with a repair: a tool repairs its own findings, drop one of them' }
+    const runs = `{ onPreCommit: false, onCi: ${gates[0]}, onFull: ${gates[1]}, onRelease: ${gates[2]}, onHealth: ${d.build ? false : onHealth}, onSave: ${onSave}, onClock: ${onClock} }`
+    let applies = d.planOff ?? q('always')
+    if (d.planOff != null) notes.push('its planOff only kept it off the planner; as applies it is n/a in every context while it gives a reason')
+    if (off != null) {
+        if (d.planOff != null) return { error: '`when` off and a planOff: say one reason' }
+        applies = `() => ${q(off)}`
+        notes.push('it was off in its own file: applies now gives the reason, so it runs nowhere')
+    }
+    return { runs, cache, fix, applies, notes }
+}
+
+export type PortResult =
+    | { changed: false; reason: string }
+    | { changed: true; source: string; notes: string[] }
+    | { changed: false; error: string }
+
+/** the file ported, or why not. `rawAccess` is what the caller measured on
+ *  the file's import closure, needed only for an undeclared `run` body */
+export function portCheckSource(src: string, o: { plainDefault: boolean; rawAccess: string | null }): PortResult {
+    const obj = findCheckObject(src, o)
+    if (obj == null) return { changed: false, reason: 'no check object' }
+    const retired = retiredKeysIn(src, o)
+    if (retired.length === 0) return { changed: false, reason: 'already explicit' }
+    const byKey = new Map(obj.props.filter((p) => p.key != null).map((p) => [p.key!, p]))
+    for (const k of ['runs', 'cache', 'applies']) if (byKey.has(k)) return { changed: false, error: `it declares ${k} beside a retired shape: finish it by hand` }
+    const dq = /^\s*import[^\n]*"/m.test(src) && !/^\s*import[^\n]*'/m.test(src)
+    const q = (s: string): string => (dq ? `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"` : `'${s.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`)
+    const val = (k: string): string | undefined => byKey.get(k)?.value
+    const build = val('build')?.trim() === 'true'
+    const body = byKey.has('cmd') ? 'cmd' : 'run'
+    const whenV = val('when')
+    const derived = deriveExplicit({
+        when: whenV == null ? null : (literal(whenV) ?? undefined),
+        build,
+        body,
+        inputs: val('inputs'),
+        ttl: val('ttl'),
+        never: val('never'),
+        cacheKey: val('cacheKey'),
+        every: val('every'),
+        cron: val('cron'),
+        whenInactive: val('whenInactive'),
+        planOff: val('planOff'),
+        repair: retired.includes('fix'),
+        rawAccess: o.rawAccess,
+    }, q)
+    if ('error' in derived) return { changed: false, error: derived.error }
+    // rebuild: drop the retired props, keep their comments above the new
+    // keys, rename a fix function to repair, insert before the body
+    const ind = obj.indent
+    const comments: string[] = []
+    const kept: string[] = []
+    let insertAt = -1
+    for (const p of obj.props) {
+        const text = src.slice(p.seg[0], p.seg[1])
+        if (p.key != null && (RETIRED_KEYS as readonly string[]).includes(p.key)) {
+            for (const l of src.slice(p.seg[0], p.keyAt).split('\n')) if (l.trim().startsWith('//')) comments.push(`${ind}${l.trim()}`)
+            continue
+        }
+        if (insertAt < 0 && (p.key === 'run' || p.key === 'cmd' || (p.key === 'fix' && retired.includes('fix')))) insertAt = kept.length
+        if (p.key === 'fix' && retired.includes('fix')) {
+            const rel = p.keyAt - p.seg[0]
+            kept.push(`${text.slice(0, rel)}repair${text.slice(rel + 3)}`)
+            continue
+        }
+        kept.push(text)
+    }
+    // a trailing comma leaves an empty last segment: keep it last
+    const tail = kept.length > 0 && kept[kept.length - 1]!.trim() === '' ? kept.pop()! : null
+    if (insertAt < 0 || insertAt > kept.length) insertAt = kept.length
+    // each new property is one segment shaped like the others: a newline,
+    // the indent, the key. The comments of the keys it replaced lead the first
+    const newProps = [
+        `\n${comments.map((c) => `${c}\n`).join('')}${ind}runs: ${derived.runs}`,
+        `\n${ind}cache: ${derived.cache}`,
+        `\n${ind}fix: ${q(derived.fix)}`,
+        `\n${ind}applies: ${derived.applies}`,
+    ]
+    const props = [...kept.slice(0, insertAt), ...newProps, ...kept.slice(insertAt), ...(tail == null ? [] : [tail])]
+    const source = `${src.slice(0, obj.open + 1)}${props.join(',')}${src.slice(obj.close)}`
+    return { changed: true, source, notes: derived.notes }
+}

package/src/core/port-check-files.ts

@@ -0,0 +1,31 @@
+// which check files of a repo still need the port (core/port-check-file.ts):
+// read through the context alone, so SK029 is cached on the listing and the
+// sources. A legacy check SCRIPT is left to its own static reader.
+import { CHECK_SUFFIX, isLegacyCheckSource, SKIPPED_DIRS, UNIT_SUFFIX } from './check-file-names.ts'
+import type { ScanCtx } from './check-ctx.ts'
+import { retiredKeysIn } from './port-check-file.ts'
+
+/** a `.check.ts` or `.check.shipkit.ts` file may export a plain object; a
+ *  plain unit file is a check only through a `check(...)` call */
+export const plainDefaultFor = (rel: string): boolean => rel.endsWith(CHECK_SUFFIX) || rel.endsWith(`.check${UNIT_SUFFIX}`)
+
+const walked = (rel: string): boolean => rel.split('/').slice(0, -1).every((d) => !SKIPPED_DIRS.has(d) && !d.startsWith('.'))
+
+/** the cheap text test before the scan: a file that declares `runs` and none
+ *  of the retired spellings is explicit already */
+const RETIRED_RE = /\b(when|inputs|ttl|never|every|cron|whenInactive|planOff|cacheKey)\s*\??\s*:|\bfix\s*\??\s*:\s*(async\b|\(|function\b|[A-Za-z_$][\w$]*\s*[,\n])/
+
+export type Unported = { rel: string; keys: string[] }
+
+export function unportedCheckFiles(c: Pick<ScanCtx, 'list' | 'read'>): Unported[] {
+    const rels = [...c.list(`**/*${CHECK_SUFFIX}`), ...c.list(`**/*${UNIT_SUFFIX}`)].filter(walked)
+    const out: Unported[] = []
+    for (const rel of [...new Set(rels)].sort()) {
+        const src = c.read(rel)
+        if (src == null || isLegacyCheckSource(src)) continue
+        if (/\bruns\s*:/.test(src) && !RETIRED_RE.test(src)) continue
+        const keys = retiredKeysIn(src, { plainDefault: plainDefaultFor(rel) })
+        if (keys.length > 0) out.push({ rel, keys })
+    }
+    return out
+}

package/src/core/retention.ts

@@ -16,8 +16,6 @@ import { JOBS, JOBS_KEEP_MS, JOBS_MAX, sweepJobs } from './jobs.ts'
 import { CI_LOG_DIR } from './layout.ts'
 import { compactDb, dbPath, shipkitRoot } from '../ledger/db.ts'
 import { SCAN_INDEX_KEEP_MS, sweepScanIndexes } from '../ledger/git-scan.ts'
-import { capLog, LOG_MAX_BYTES } from '../home/supervise.ts'
-import { processDir } from '../serve/repo-processes.ts'
 import { KEEP_MS as RECORD_KEEP_MS, MAX_ROWS, recordUse, sweepRuns } from '../ledger/run-log.ts'
 import { answersDb, answersUse, importLegacyStore, KEEP_MS as ANSWERS_KEEP_MS, legacyStoreDir, MAX_ANSWERS, sweepAnswers } from '../ledger/store.ts'
 
@@ -169,18 +167,6 @@ export function repoStores(root: string): Store[] {
             },
             sweep: (now) => sweepJobs(root, now),
         },
-        {
-            // the dev servers the hub runs for the repo (serve.processes)
-            id: 'process logs',
-            where: `${processDir(root)}/*.log`,
-            cap: { maxFileBytes: LOG_MAX_BYTES },
-            measure: () => walkUse(processDir(root), { match: (n) => n.endsWith('.log') }),
-            sweep: () => {
-                let names: string[] = []
-                try { names = readdirSync(processDir(root)) } catch { return }
-                for (const n of names) if (n.endsWith('.log')) capLog(join(processDir(root), n))
-            },
-        },
     ]
     if (gitDir != null) {
         const dir = join(gitDir, 'shipkit')

package/src/core/run-check.ts

@@ -17,7 +17,7 @@ import { gateBinary } from '../ledger/toolchain-identity.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 { unknownOffIds } from './when.ts'
 import { unknownBudgetIds } from './budget.ts'
 import { formatLine, type Line } from './wire.ts'
 import { writeStatus } from './write-status.ts'
@@ -75,6 +75,8 @@ export type CheckOpts = {
     buildOnly?: boolean
     /** the gate asks the proactive checks too (`release.requireHealthy`) */
     includeProactive?: boolean
+    /** the release preflight: the rows declaring `onRelease` run */
+    release?: boolean
     /** ids this caller does not need (a sub-unit release) */
     exclude?: string[]
     /** the already-composed check list, when the caller built one (runCi does,
@@ -107,9 +109,9 @@ export type CheckRun = {
     advisoryFailures: string[]
     /** checks that never declared `blocking` — always fatal */
     undeclared: string[]
-    /** `when` entries naming no check of this repo — a toggle that does
+    /** `off` entries naming no check of this repo — a toggle that does
      *  nothing is worse than none, so it is fatal too */
-    unknownWhen: string[]
+    unknownOff: 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 */
@@ -125,6 +127,7 @@ function selectionOf(checks: RunnableCheck[], o: CheckOpts, tier: TestTier) {
         checks,
         audience: o.audience ?? 'health',
         fullTier: tier === 'full',
+        release: o.release,
         skipGroups: o.skipGroups,
         onlyIds: o.only,
         withIds: o.withIds,
@@ -211,7 +214,7 @@ export async function runCheckPass(root: string, o: CheckOpts = {}): Promise<Che
     // page just replaced
     if (summary.parked.length > 0) {
         const head = summary.parked.slice(0, 8).join(', ')
-        say({ kind: 'skip', text: `${summary.parked.length} check(s) not in this run (health only, release only at the quick tier, or a skipped group): ${head}${summary.parked.length > 8 ? `, and ${summary.parked.length - 8} more` : ''}` }, o.detail ?? print)
+        say({ kind: 'skip', text: `${summary.parked.length} check(s) not in this run (their runs do not name this context, or a skipped group, shipkit when shows each): ${head}${summary.parked.length > 8 ? `, and ${summary.parked.length - 8} more` : ''}` }, o.detail ?? print)
     }
     // the survey dies with the run that made it, and only the run that made it
     if (inherited == null || inherited === '') for (const f of [sharePath, `${sharePath}.lock`]) { try { rmSync(f, { force: true }) } catch {} }
@@ -225,17 +228,17 @@ export async function runCheckPass(root: string, o: CheckOpts = {}): Promise<Che
     if (o.ledger === undefined && ledger != null) for (const l of ledger.header(ledger.commit())) say(l)
     // the caller that OPENED the record owns writing it, the same rule
     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
+    // an `off` 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 rows = composed.map((g) => g.row)
-    const unknownWhen = unknownWhenIds(rows, c)
+    const unknownOff = unknownOffIds(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,
+        unknownOff,
         unknownBudgets,
         results: summary.results,
         interrupted: summary.interrupted,
@@ -247,13 +250,13 @@ 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 || run.unknownBudgets.length > 0 ? 1 : 0
+    const code = run.blocked || run.undeclared.length > 0 || run.unknownOff.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 key of [...run.unknownWhen.map((id) => `when.${id}`), ...run.unknownBudgets.map((id) => `budgets.${id}`)]) {
+    for (const key of [...run.unknownOff.map((id) => `off.${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`)
     }

package/src/core/run-ci.ts

@@ -32,8 +32,11 @@ export type CiOpts = {
     /** repair the mechanical slots before gating. default on locally, verify
      *  mode under CI. core/run-fixers.ts owns the scope. */
     fix?: boolean
-    /** also apply the structural SK rule fixers during the fix pass */
+    /** also apply the repairs of the checks declaring `fix: 'ci'` during the
+     *  fix pass */
     fixRules?: boolean
+    /** the release preflight: the rows declaring `onRelease` run */
+    release?: boolean
     /** self-arm the git hooks in the fix pass (interactive ci entry only) */
     armHooks?: boolean
     /** run only the checks that can block (core/run-checks onlyBlocking) */
@@ -203,6 +206,7 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
         composed,
         audience: 'gate',
         includeProactive: o.failOnAdvisory === true,
+        release: o.release,
         frozen: o.frozen,
         onlyBlocking: o.onlyBlockingChecks,
         only: o.onlyIds,
@@ -226,7 +230,7 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
         })
         const reg = ledger.layer.registration
         for (const e of reg.errors) { registrationFailed = true; sink(`FAIL: ${e}`) }
-        if (registrationFailed) sink('      fix: a check declares `inputs` (content), or `ttl` (world), or `never: <reason>`, and never two of them')
+        if (registrationFailed) sink('      fix: each check declares one cache that its body can honour: files, reads, ttl, fact or never (build/shipkit/runs.md)')
         // both counts, always. Printing only the burn-down made `never:` the
         // cheap way to shrink the visible number, and that field carries no
         // verification at all: a growing decided population has to be as
@@ -262,7 +266,7 @@ 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 key of [...run.unknownWhen.map((id) => `when.${id}`), ...run.unknownBudgets.map((id) => `budgets.${id}`)]) {
+    for (const key of [...run.unknownOff.map((id) => `off.${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`)
     }
@@ -283,7 +287,7 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
     if (ledger != null) for (const [i, l] of ledger.header(ledger.commit()).entries()) (i === 0 ? detail : 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 || run.unknownBudgets.length > 0 ? 1 : 0
+    const code = run.blocked || fixFailed || registrationFailed || advisoryFatal || run.undeclared.length > 0 || run.unknownOff.length > 0 || run.unknownBudgets.length > 0 ? 1 : 0
     // THE VERDICT, one line and only on a pass: a red run already said so in
     // its FAIL lines. The whole gate adds the tier and the cache counts, which
     // a narrowed run asked no question about

package/src/core/run-fix.ts

@@ -1,11 +1,13 @@
-// `shipkit check --fix [<id> …]` — apply check autofixes, then re-run and
-// show the real end state. Never runs under ci (the gate stays pure), never
-// caches (a fixer must see reality). No ids = every fixable check; a
-// requested id that is unknown or unfixable fails loud instead of silently
-// narrowing.
+// `shipkit check --fix [<id> …]` — apply check repairs, then re-run and
+// show the real end state. Never caches (a repair must see reality). No ids =
+// every check declaring `fix: 'ci'`, which is also what the gate's fix pass
+// applies; a `fix: 'manual'` repair runs only when its id is named. A
+// requested id that is unknown or has no repair fails loud instead of
+// silently narrowing.
 import { CheckCtx } from './check-ctx.ts'
 import { formatLine } from './wire.ts'
-import { whenOfRule, whenOfCheck, type WhenDecl } from './when.ts'
+import type { FixWhen } from './runs.ts'
+import { gateInventory } from '../ledger/gate-checks.ts'
 import { loadRepoConfig } from '../repo-config.ts'
 import { discoverChecks } from './discover-checks.ts'
 import { runCheckBody, type CheckDef, type CheckEnv } from '../check.ts'
@@ -34,19 +36,25 @@ export async function runFix(root: string, o: FixOpts = {}): Promise<number> {
     const ctx = (c: RepoConfig): CheckCtx => CheckCtx.open({ root, config: c })
     const color = process.stdout.isTTY && process.env.NO_COLOR == null
     /** one fixable check, whatever declared it */
-    type Target = { id: string; title: string; owner: string; run: CheckDef['run']; fix?: CheckDef['fix']; when: WhenDecl }
+    type Target = { id: string; title: string; owner: string; run: CheckDef['run']; fix?: CheckDef['repair']; when: FixWhen; off: string | null }
+    // what each row resolved to: its declared `fix` and whether it is off
+    const resolved = new Map((await gateInventory(root, config)).map((r) => [r.decl.id, r.runs]))
     // a rule the repo still registers fixes exactly like a check file, one
-    // code path. Only a check that declared a `fix` is a target at all
+    // code path, with the fix word its derived row carries
     const all: Target[] = [
-        ...(await discoverChecks(root)).map((u): Target => ({ id: u.id, title: u.title, owner: u.owner, run: u.def.run, fix: u.def.fix, when: whenOfCheck(config, u) })),
-        ...(config.rules ?? []).map((r): Target => ({
-            id: r.id, title: r.title, owner: r.owner, when: whenOfRule(config, r.id),
-            run: (c) => r.lint(c, { root: c.root, config: c.config }),
-            fix: r.fix == null ? undefined : (c) => r.fix!({ root: c.root, config: c.config }),
-        })),
+        ...(await discoverChecks(root)).map((u): Target => ({ id: u.id, title: u.title, owner: u.owner, run: u.def.run, fix: u.def.repair, when: resolved.get(u.id)?.fix ?? u.def.fix, off: resolved.get(u.id)?.off ?? null })),
+        ...(config.rules ?? []).map((r): Target => {
+            const runs = resolved.get(r.id)
+            return {
+                id: r.id, title: r.title, owner: r.owner, when: runs?.fix ?? 'none', off: runs?.off ?? null,
+                run: (c) => r.lint(c, { root: c.root, config: c.config }),
+                fix: r.fix == null ? undefined : (c) => r.fix!({ root: c.root, config: c.config }),
+            }
+        }),
     ]
 
-    let targets = all.filter((r) => r.fix != null)
+    // no ids: the repairs declared for the gate. A manual one runs by name
+    let targets = all.filter((r) => r.fix != null && r.when === 'ci')
     if (o.ids != null && o.ids.length > 0) {
         for (const id of o.ids) {
             const r = all.find((x) => x.id === id)
@@ -54,17 +62,16 @@ export async function runFix(root: string, o: FixOpts = {}): Promise<number> {
             if (r.fix == null) { print(`FAIL: [${id}] has no autofix — fix by hand: ${config.docsBase ?? ''}${r.owner}`); return 1 }
         }
         const wanted = new Set(o.ids)
-        targets = targets.filter((r) => wanted.has(r.id))
+        targets = all.filter((r) => r.fix != null && wanted.has(r.id))
     }
 
     let exit = 0
     for (const rule of targets) {
         const before = ctx(env.config)
-        const off = rule.when
-        await runCheckBody(rule, before, off.at === 'off' ? { reason: off.reason } : undefined)
+        await runCheckBody(rule, before, rule.off != null ? { reason: rule.off } : undefined)
         // a check that is OFF never autofixes: the repo broke that invariant on purpose
-        if (off.at === 'off') {
-            if (o.quiet !== true) print(`skip: [${rule.id}] ${rule.id} exempt: ${off.reason ?? ''}`)
+        if (rule.off != null) {
+            if (o.quiet !== true) print(`skip: [${rule.id}] ${rule.id} exempt: ${rule.off}`)
             continue
         }
         if (!before.failed && !before.warned) {
@@ -97,8 +104,8 @@ export async function runFix(root: string, o: FixOpts = {}): Promise<number> {
         for (const l of after.lines) (o.quiet === true ? o.detail ?? print : say)(formatLine({ ...l, text: l.text.replace(/ · autofix: shipkit check --fix \S+$/, '') }, color))
         if (after.failed) exit = 1
     }
-    const unfixable = all.filter((r) => r.fix == null).length
-    if (unfixable > 0 && o.quiet !== true && (o.ids == null || o.ids.length === 0))
-        print(`${unfixable} check(s) have no autofix — they report in the run below`)
+    const manual = all.filter((r) => r.fix != null && r.when === 'manual').map((r) => r.id)
+    if (manual.length > 0 && o.quiet !== true && (o.ids == null || o.ids.length === 0))
+        print(`${manual.length} repair(s) run only by name: shipkit check --fix ${manual.join(' ')}`)
     return exit
 }