rvlib-shipkit 1.3.0 → 1.5.0

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,
@@ -87,11 +89,8 @@ export type CheckOpts = {
     /** the gate binary that own ledger is keyed on (default: the one running
      *  it). Ignored when `ledger` is passed, which carries its own. */
     cliEntry?: string
-    /** refresh the motherhome registry row. runCi passes false and does it
-     *  ITSELF, after the ledger has committed: that row is a TRACKED file under
-     *  `wiki/`, so writing it before the post-run re-hash makes the gate look
-     *  like an agent editing the tree and throws away every result the run just
-     *  measured. */
+    /** file the motherhome row in the machine db (core/motherhome.ts). runCi
+     *  passes false and does it ITSELF, once, after its verdict. */
     reportHome?: boolean
 }
 
@@ -110,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 */
@@ -128,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,
@@ -214,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 {} }
@@ -228,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,
@@ -250,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,15 +287,15 @@ 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
     const verdict = code === 0 && !run.interrupted ? verdictLine(run.results, scope.fullGate ? { tier, cache: ledger?.counts ?? null } : null) : null
     if (verdict != null) sink(verdict)
-    // 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
+    // the motherhome row, filed in the machine db and landed in the docsBase
+    // page by the daemon (core/motherhome.ts): never affects the gate, never
+    // writes in another repo, and a frozen run files nothing
     if (o.frozen !== true) {
         const mh = reportToMotherhome(root, c)
         if (mh.note != null) print(mh.note)

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
 }

package/src/core/run-fixers.ts

@@ -8,8 +8,8 @@
 // rewrites the tree it checks can turn red green with no commit. one
 // mechanism, two modes, rather than a formatter plus a format:check that
 // drift apart.
-import { existsSync, readFileSync } from 'fs'
-import { join } from 'path'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs'
+import { dirname, join } from 'path'
 import { fileURLToPath } from 'url'
 import { armHooks } from '../hooks/run-hooks.ts'
 import { loadRepoConfig, type RepoConfig } from '../repo-config.ts'
@@ -22,6 +22,8 @@ import { layoutSummary, migrateLayout } from './migrate-layout.ts'
 import { renderPolicy } from '../checks/SK004-gitignore-policy.check.ts'
 import { spawnWithTimeout } from './spawn-timeout.ts'
 import { gitBin } from './git-bin.ts'
+import { LAYOUT } from './layout.ts'
+import { gateBinary, toolchainIdentity } from '../ledger/toolchain-identity.ts'
 
 const FIXER_TIMEOUT_MS = 120_000
 
@@ -123,6 +125,31 @@ function treeState(root: string): Map<string, string> | null {
     return m
 }
 
+/** where the key of the last clean fix pass is kept, per checkout */
+const memoPath = (root: string): string => join(root, LAYOUT.tmp, 'fix-pass.key')
+
+/** what the fixers would see: HEAD, the dirty paths and their bytes, the
+ *  toolchain that runs them, and their commands. null when HEAD cannot be read */
+function fixMemo(root: string, tree: Map<string, string>, cmds: string[][]): string | null {
+    const head = Bun.spawnSync([gitBin(), 'rev-parse', 'HEAD'], { cwd: root })
+    if (head.exitCode !== 0) return null
+    const h = new Bun.CryptoHasher('sha256')
+    h.update(`head=${head.stdout.toString().trim()}\n`)
+    for (const [path, hash] of [...tree].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))) h.update(`${path}\0${hash}\n`)
+    try { h.update(`toolchain=${toolchainIdentity(root, gateBinary()).id}\n`) } catch { return null }
+    h.update(`cmds=${JSON.stringify(cmds)}\n`)
+    return h.digest('hex')
+}
+
+const readMemo = (root: string): string | null => { try { return readFileSync(memoPath(root), 'utf8').trim() } catch { return null } }
+
+const writeMemo = (root: string, key: string): void => {
+    try {
+        mkdirSync(dirname(memoPath(root)), { recursive: true })
+        writeFileSync(memoPath(root), `${key}\n`)
+    } catch { /* a memo that cannot be kept only means the next pass runs the fixers */ }
+}
+
 /** the bytes of repo.config.ts and the set of check and check files, as one
  *  hash. Read without git, so a repo with no history is covered too */
 function shapeStamp(root: string): string {
@@ -231,13 +258,22 @@ async function fixPassBody(root: string, loaded: RepoConfig, o: FixPassOpts, ver
     for (const u of unfilled) detail(`skip: ${u.id} (${u.reason})`)
     for (const d of disabled) detail(`skip: ${d.id} (${d.reason})`)
     const before = treeState(root)
-
-    for (const s of slots) {
+    // the fixers already ran clean over exactly this tree (HEAD, every dirty
+    // path's bytes, the toolchain, the commands): running them again rewrites
+    // nothing and costs a whole formatter pass. CI never skips: there the
+    // pass IS the check
+    const memo = verify || before == null ? null : fixMemo(root, before, slots.map((s) => s.cmd))
+    const skip = memo != null && readMemo(root) === memo
+    let fixersOk = true
+    if (skip) detail(`ok: fixers skipped, the tree is unchanged since they last ran clean (${slots.length} fixer(s))`)
+    else for (const s of slots) {
         const r = await spawnWithTimeout(s.cmd, { cwd: root, timeoutMs: FIXER_TIMEOUT_MS })
         // a broken fixer must never be mistaken for a clean one: the gate
         // still runs, but the failure is loud and names the command
-        if (r.code !== 0)
+        if (r.code !== 0) {
+            fixersOk = false
             o.print(`WARN fix ${s.id} failed (exit ${r.code}) — ${r.out.trim().split('\n').at(-1)?.slice(0, 160) ?? ''}; the gate below still ran`)
+        }
     }
     // structural repo-config repair is never implicit, and never in verify mode
     if (o.rules === true && !verify) await runFix(root, { quiet: true, print: o.print, detail: o.detail, config })
@@ -265,6 +301,7 @@ async function fixPassBody(root: string, loaded: RepoConfig, o: FixPassOpts, ver
         return { ran: true, touched, failed: false, reshaped }
     }
     if (touched.length === 0) {
+        if (memo != null && !skip && fixersOk) writeMemo(root, memo)
         detail(`ok: ${verify ? 'fixers verified' : 'fix pass'} clean (${slots.length} fixer(s), nothing to rewrite)`)
         return { ran: true, touched, failed: false, reshaped }
     }

package/src/core/runs-matrix.ts

@@ -0,0 +1,179 @@
+// WHAT RUNS WHEN, as data every surface prints the same way: the legend (each
+// axis, each value, what it means) and one row of cells per check. Pure: it
+// reads composed rows and returns strings, so `shipkit when`, the hub's when
+// page and the docs page can never disagree.
+import type { CheckRow } from '../ledger/gate-checks.ts'
+import { cellText, RUNS_KEYS, type RunsAxis, type RunsSource } from './runs.ts'
+
+export type MatrixAxis = RunsAxis | 'fix'
+
+export const MATRIX_AXES: readonly MatrixAxis[] = [...RUNS_KEYS, 'fix']
+
+/** one axis of the legend: the command or event it is, and every value */
+export type LegendAxis = { axis: MatrixAxis | 'cache'; short: string; context: string; values: { value: string; means: string }[] }
+
+/** THE legend. Every surface prints it verbatim, and build/shipkit/runs.md is
+ *  generated from it */
+export const RUNS_LEGEND: readonly LegendAxis[] = [
+    {
+        axis: 'onPreCommit', short: 'commit', context: '`git commit`, in the pre-commit hook, on the working tree',
+        values: [
+            { value: 'false', means: 'never at commit' },
+            { value: '{ budgetMs: n }', means: 'runs in process with no cache, before the message. A failure refuses the commit, a run past n ms (at most 100) warns' },
+        ],
+    },
+    {
+        axis: 'onCi', short: 'ci', context: '`shipkit ci`, the quick gate: an agent runs it once before it pushes its work, and the hub button runs a whole one. Named after the command, never a CI server',
+        values: [
+            { value: 'true', means: 'in every quick gate: the cached answer while its key has not moved, else the body runs' },
+            { value: 'false', means: 'not in the quick gate. `--with <id>` or `--only <id>` still runs it by name' },
+        ],
+    },
+    {
+        axis: 'onFull', short: 'full', context: '`shipkit ci --full`: the quick gate (every onCi row) plus every slow suite',
+        values: [
+            { value: 'true', means: 'in the full gate' },
+            { value: 'false', means: 'not in the full gate' },
+        ],
+    },
+    {
+        axis: 'onRelease', short: 'release', context: 'the preflight of `shipkit bump` and `shipkit release`: full tier, frozen, no cache read, no repair',
+        values: [
+            { value: 'true', means: 'its body runs before a version ships, never from the cache, and a failure stops the release. A non blocking check runs there only when the repo sets release.requireHealthy' },
+            { value: 'false', means: 'a release never asks it' },
+        ],
+    },
+    {
+        axis: 'onHealth', short: 'health', context: '`shipkit check`, the TUI checks panel and the hub health run: is this repo healthy',
+        values: [
+            { value: 'true', means: 'part of the health pass' },
+            { value: 'false', means: 'not part of it (every build step)' },
+        ],
+    },
+    {
+        axis: 'onSave', short: 'save', context: 'the daemon, 60s after the last save in the repo',
+        values: [
+            { value: 'false', means: 'a save never starts it' },
+            { value: "'moved'", means: 'runs only when a file it is keyed on moved' },
+            { value: "'burst'", means: 'runs after every save burst, whatever moved (nothing keys it)' },
+        ],
+    },
+    {
+        axis: 'onClock', short: 'clock', context: 'the daemon, on its own time',
+        values: [
+            { value: 'false', means: 'never on a clock' },
+            { value: "'once'", means: 'once while no answer exists for its fact (first run, a changed declaration)' },
+            { value: '{ every, inactive }', means: "on a period ('24h', a range ['20h','28h'], a cron, or a function of its last result). inactive 'wait' holds it while nobody works in the repo, 'run' runs it anyway" },
+        ],
+    },
+    {
+        axis: 'fix', short: 'fix', context: 'which command applies the check\'s repair',
+        values: [
+            { value: "'none'", means: 'no repair: a failure is fixed by hand' },
+            { value: "'ci'", means: 'the fix pass of `shipkit ci` applies it after the body fails or warns, and `shipkit check --fix`' },
+            { value: "'manual'", means: 'only `shipkit check --fix <id>` or the hub fix button' },
+        ],
+    },
+    {
+        axis: 'cache', short: 'cache', context: 'how an answer is kept, in every context but the release and the hook',
+        values: [
+            { value: 'files', means: 'keyed on these paths and the check\'s own code: the cached answer holds while they do not move' },
+            { value: 'reads', means: 'keyed on what the body read last time, which the cache checks again before it answers' },
+            { value: 'ttl', means: 'an answer about the world, kept this long' },
+            { value: 'fact', means: 'a decided value, kept until the declaration changes' },
+            { value: 'never', means: 'runs every time, with the reason' },
+        ],
+    },
+]
+
+/** one cell: what it prints, whether the context runs it, and who said so */
+export type RunsCell = { text: string; on: boolean; source: RunsSource }
+
+/** one check as the matrix prints it */
+export type RunsCells = {
+    cells: Record<MatrixAxis, RunsCell>
+    cache: string
+    /** the reason it runs nowhere, null for a live row */
+    off: string | null
+    /** why a derived row has its values, null for a declared one */
+    derivedWhy: string | null
+}
+
+export function runsCellsOf(row: CheckRow): RunsCells {
+    const r = row.runs
+    const cells = Object.fromEntries(MATRIX_AXES.map((k) => {
+        const v = k === 'fix' ? r.fix : r[k]
+        const on = r.off == null && v !== false && v !== 'none'
+        return [k, { text: cellText(r, k), on, source: r.source[k] }]
+    })) as Record<MatrixAxis, RunsCell>
+    return { cells, cache: row.cache, off: r.off, derivedWhy: r.derivedWhy }
+}
+
+/** where a row runs, as one line of words: every context that runs it, with
+ *  its value when that says more than yes, then the command that repairs it */
+export function runsWords(c: RunsCells): string {
+    if (c.off != null) return `runs nowhere: ${c.off}`
+    const word = (k: MatrixAxis): string => {
+        const cell = c.cells[k]
+        const short = RUNS_LEGEND.find((a) => a.axis === k)!.short
+        return `${short}${cell.text === 'yes' ? '' : ` ${cell.text}`}`
+    }
+    const on = RUNS_KEYS.filter((k) => c.cells[k].on).map(word)
+    const where = on.length === 0 ? 'runs only when named' : `runs on ${on.join(' · ')}`
+    return c.cells.fix.on ? `${where}, repaired by ${word('fix')}` : where
+}
+
+/** what a cell's value means, the legend's own sentence for it. A cell
+ *  prints short (yes, ·, moved, 24h); the legend names the declared value */
+export function cellMeaning(k: MatrixAxis | 'cache', text: string): string {
+    const values = RUNS_LEGEND.find((a) => a.axis === k)!.values
+    const declared = k === 'cache'
+        ? text.split(/[\s:]/)[0]!
+        : text === 'yes' ? 'true'
+            : text === '·' ? 'false'
+                : k === 'onPreCommit' ? '{ budgetMs: n }'
+                    : k === 'onClock' && text !== 'once' ? '{ every, inactive }'
+                        : `'${text}'`
+    return values.find((v) => v.value === declared)?.means ?? ''
+}
+
+/** which rows a context runs, for the matrix's column filter */
+export const inColumn = (c: RunsCells, k: MatrixAxis): boolean => c.cells[k].on
+
+/** the matrix as terminal lines: the legend, then one row per check, and a
+ *  row the repo turned off with its reason */
+/** what a failure does, as one word: a build step and a blocking check stop
+ *  you, a check about the world only warns */
+export const stopsWord = (r: { blocking: boolean | null; build: boolean }): string => (r.build ? 'build' : r.blocking === false ? 'warns' : 'blocks')
+
+export function matrixLines(rows: { id: string; blocking: boolean | null; build: boolean; runs: RunsCells }[], o: { legend: boolean; only?: MatrixAxis } = { legend: true }): string[] {
+    const out: string[] = []
+    if (o.legend) {
+        for (const a of RUNS_LEGEND) {
+            out.push(`${a.axis.padEnd(12)}${a.context}`)
+            for (const v of a.values) out.push(`${''.padEnd(14)}${v.value.padEnd(20)}${v.means}`)
+        }
+        out.push('')
+    }
+    const shown = o.only == null ? rows : rows.filter((r) => inColumn(r.runs, o.only!))
+    const width = Math.max(5, ...shown.map((r) => r.id.length)) + 2
+    const heads = MATRIX_AXES.map((k) => RUNS_LEGEND.find((a) => a.axis === k)!.short)
+    const colW = (i: number): number => Math.max(heads[i]!.length, ...shown.map((r) => cellOut(r.runs, MATRIX_AXES[i]!).length)) + 2
+    const widths = MATRIX_AXES.map((_, i) => colW(i))
+    out.push(`${'check'.padEnd(width)}${'fails'.padEnd(8)}${heads.map((h, i) => h.padEnd(widths[i]!)).join('')}cache`)
+    for (const r of shown) {
+        if (r.runs.off != null) { out.push(`${r.id.padEnd(width)}${stopsWord(r).padEnd(8)}off: ${r.runs.off}`); continue }
+        out.push(`${r.id.padEnd(width)}${stopsWord(r).padEnd(8)}${MATRIX_AXES.map((k, i) => cellOut(r.runs, k).padEnd(widths[i]!)).join('')}${r.runs.cache}`)
+    }
+    return out
+}
+
+const cellOut = (c: RunsCells, k: MatrixAxis): string => c.cells[k].text
+
+/** the legend as markdown, the block `shipkit when --out` writes into a docs
+ *  page between its markers */
+export function legendMarkdown(): string {
+    const out = ['| key | the context | value | what it means |', '|---|---|---|---|']
+    for (const a of RUNS_LEGEND) a.values.forEach((v, i) => out.push(`| ${i === 0 ? `\`${a.axis}\`` : ''} | ${i === 0 ? a.context.replace(/\|/g, '\\|') : ''} | \`${v.value}\` | ${v.means.replace(/\|/g, '\\|')} |`))
+    return out.join('\n')
+}