rvlib-shipkit 1.4.0 → 1.5.0

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')
+}

package/src/core/runs.ts

@@ -0,0 +1,242 @@
+// WHERE A CHECK RUNS AND HOW ITS ANSWER IS KEPT, declared in full by every
+// check, with no default anywhere.
+//
+// Every context that can run a check body or its repair is one key of `runs`,
+// plus `fix` (which command applies the repair), `cache` (how the answer is
+// kept) and `applies` (whether this repo gives it anything to do). A check
+// file writes every key. A row with no file to say it in (a floor slot, a
+// config task, a legacy form) gets every key from the code that derives it,
+// with the reason, so no row ever resolves to a value nobody wrote.
+//
+// the one constraint a reader breaks first: a missing key is a load error,
+// never a default. `runsProblem` and `cacheProblem` are the only judges, and
+// `check()` calls both at import time.
+import type { CheckEnv } from '../check.ts'
+import { cadenceOf, ONCE, type Every, type WhenInactiveDecl } from '../plan/cadence.ts'
+import { parseDuration } from './wire.ts'
+
+// ── the declaration ──────────────────────────────────────────────────────
+
+/** the pre-commit hook: never, or in process on the working tree under a
+ *  budget of at most PRE_COMMIT_MAX_MS */
+export type OnPreCommit = false | { budgetMs: number }
+/** the daemon after a quiet save burst: never, only when the check's key
+ *  moved, or after every burst */
+export type OnSave = false | 'moved' | 'burst'
+/** the daemon on its own time: never, once while no answer exists for the
+ *  fact's key, or on a period with what to do while the repo is inactive */
+export type OnClock = false | 'once' | { every: Every; inactive: WhenInactiveDecl }
+
+export type Runs = {
+    /** `git commit`, in the pre-commit hook, before the message */
+    onPreCommit: OnPreCommit
+    /** `shipkit ci`: the gate an agent runs once before it pushes its work,
+     *  and a whole run from the hub's run button */
+    onCi: boolean
+    /** `shipkit ci --full`: the full tests tier. Every `onCi` row is here too */
+    onFull: boolean
+    /** the preflight of `shipkit bump` and `shipkit release`: full tier,
+     *  frozen, no cache read, no repair */
+    onRelease: boolean
+    /** `shipkit check`, the TUI checks panel, the hub health run */
+    onHealth: boolean
+    /** the daemon, after a quiet save burst in the repo */
+    onSave: OnSave
+    /** the daemon, on its own time */
+    onClock: OnClock
+}
+
+/** which command applies the check's `repair`: none exists, the gate's fix
+ *  pass (and `shipkit check --fix`), or only `shipkit check --fix <id>` */
+export type FixWhen = 'none' | 'ci' | 'manual'
+
+/** how an answer is kept. Every variant names its one parameter */
+export type CacheDecl =
+    /** keyed on the content of these repo paths (and the check's own code) */
+    | { by: 'files'; inputs: string[]; key: ((env: CheckEnv) => string) | null }
+    /** keyed on what the body read through its context, re-checked before a replay */
+    | { by: 'reads' }
+    /** a clean answer about the world keeps for `span` */
+    | { by: 'ttl'; span: string; key: ((env: CheckEnv) => string) | null }
+    /** a decided fact, keyed on the declared value alone, never expires */
+    | { by: 'fact'; key: (env: CheckEnv) => string }
+    /** no key can describe it, with the reason: measured every time */
+    | { by: 'never'; why: string }
+
+export type CacheBy = CacheDecl['by']
+
+/** whether this repo gives the check anything to do. A reason back makes the
+ *  row n/a in every context: never run, never planned, shown with the reason */
+export type Applies = 'always' | ((env: CheckEnv) => string | null)
+
+export const RUNS_KEYS = ['onPreCommit', 'onCi', 'onFull', 'onRelease', 'onHealth', 'onSave', 'onClock'] as const
+export type RunsAxis = (typeof RUNS_KEYS)[number]
+export const CACHE_BY: readonly CacheBy[] = ['files', 'reads', 'ttl', 'fact', 'never']
+export const FIX_WHEN: readonly FixWhen[] = ['none', 'ci', 'manual']
+
+/** the ceiling a pre-commit check may declare. The hook boots in about
+ *  500ms, and the text gates it already runs cost 50 to 100ms together, so a
+ *  check that needs more than this belongs in `onCi` */
+export const PRE_COMMIT_MAX_MS = 100
+
+// ── the judges ───────────────────────────────────────────────────────────
+
+const isBool = (v: unknown): v is boolean => typeof v === 'boolean'
+
+function everyProblem(v: unknown): string | null {
+    if (typeof v === 'function') return null
+    if (v == null || v === ONCE) return `onClock.every takes a span, a range, a cron or a function, never ${JSON.stringify(v)} (use onClock: false or 'once')`
+    const c = cadenceOf(v as Every & (string | [string, string]), '')
+    return typeof c === 'string' ? `onClock.every: ${c}` : null
+}
+
+/** what is wrong with a `runs` object, or null. Every key is required */
+export function runsProblem(r: unknown): string | null {
+    if (r == null || typeof r !== 'object') return `runs is required: { ${RUNS_KEYS.join(', ')} }, every key explicit`
+    const o = r as Record<string, unknown>
+    const missing = RUNS_KEYS.filter((k) => !(k in o))
+    if (missing.length > 0) return `runs is missing ${missing.join(', ')}: every key is explicit, no default`
+    const unknown = Object.keys(o).filter((k) => !(RUNS_KEYS as readonly string[]).includes(k))
+    if (unknown.length > 0) return `runs has unknown key ${unknown.join(', ')} (the keys: ${RUNS_KEYS.join(', ')})`
+    const p = o.onPreCommit
+    if (p !== false) {
+        const b = (p as { budgetMs?: unknown } | null)?.budgetMs
+        if (p == null || typeof p !== 'object' || typeof b !== 'number' || !Number.isInteger(b) || b < 1 || b > PRE_COMMIT_MAX_MS)
+            return `runs.onPreCommit takes false or { budgetMs: 1..${PRE_COMMIT_MAX_MS} }`
+    }
+    for (const k of ['onCi', 'onFull', 'onRelease', 'onHealth'] as const) if (!isBool(o[k])) return `runs.${k} takes true or false`
+    if (o.onSave !== false && o.onSave !== 'moved' && o.onSave !== 'burst') return `runs.onSave takes false, 'moved' or 'burst'`
+    const c = o.onClock
+    if (c !== false && c !== ONCE) {
+        if (c == null || typeof c !== 'object') return `runs.onClock takes false, 'once' or { every, inactive }`
+        const cc = c as { every?: unknown; inactive?: unknown }
+        if (!('every' in cc) || !('inactive' in cc)) return `runs.onClock takes { every, inactive }, both keys explicit`
+        const e = everyProblem(cc.every)
+        if (e != null) return `runs.${e}`
+        if (typeof cc.inactive !== 'function' && cc.inactive !== 'run' && cc.inactive !== 'wait') return `runs.onClock.inactive takes 'run', 'wait' or a function returning one`
+    }
+    if (o.onCi === true && o.onFull !== true) return `runs.onCi true needs onFull true: the full gate is the quick gate plus more`
+    return null
+}
+
+/** what is wrong with a `cache` object, or null */
+export function cacheProblem(c: unknown): string | null {
+    if (c == null || typeof c !== 'object') return `cache is required: { by: ${CACHE_BY.map((b) => `'${b}'`).join(' | ')}, ... }`
+    const o = c as Record<string, unknown>
+    const want: Record<CacheBy, string[]> = { files: ['inputs', 'key'], reads: [], ttl: ['span', 'key'], fact: ['key'], never: ['why'] }
+    const by = o.by as CacheBy
+    if (!CACHE_BY.includes(by)) return `cache.by takes ${CACHE_BY.map((b) => `'${b}'`).join(', ')}`
+    const keys = want[by]
+    const missing = keys.filter((k) => !(k in o))
+    if (missing.length > 0) return `cache { by: '${by}' } is missing ${missing.join(', ')}: every key is explicit`
+    const unknown = Object.keys(o).filter((k) => k !== 'by' && !keys.includes(k))
+    if (unknown.length > 0) return `cache { by: '${by}' } has unknown key ${unknown.join(', ')} (it takes ${keys.length === 0 ? 'nothing else' : keys.join(', ')})`
+    if (by === 'files' && (!Array.isArray(o.inputs) || o.inputs.length === 0 || o.inputs.some((p) => typeof p !== 'string' || p === ''))) return `cache.inputs is a non empty list of repo relative paths`
+    if ((by === 'files' || by === 'ttl') && o.key !== null && typeof o.key !== 'function') return `cache.key is null or a function of { root, config }`
+    if (by === 'fact' && typeof o.key !== 'function') return `cache { by: 'fact' } needs key: a function of { root, config } returning the declared value`
+    if (by === 'ttl') {
+        if (typeof o.span !== 'string') return `cache.span is a duration, as in '24h'`
+        try { if (parseDuration(o.span) <= 0) return `cache.span must be above zero` } catch (e) { return `cache.span: ${(e as Error).message}` }
+    }
+    if (by === 'never' && (typeof o.why !== 'string' || o.why.trim() === '')) return `cache { by: 'never' } needs why: the reason no key can describe it`
+    return null
+}
+
+/** what a whole declaration must satisfy together, or null */
+export type WholeDecl = { runs: Runs; cache: CacheDecl; fix: FixWhen; repair: unknown; build: boolean; body: 'run' | 'cmd'; blocking: boolean }
+
+export function combinationProblem(d: WholeDecl): string | null {
+    const { runs: r, cache: c } = d
+    if (!FIX_WHEN.includes(d.fix)) return `fix takes 'none', 'ci' or 'manual'`
+    if (d.fix !== 'none' && typeof d.repair !== 'function') return `fix '${d.fix}' needs a repair function`
+    if (d.fix === 'none' && d.repair != null) return `a repair function needs fix 'ci' or 'manual', never 'none'`
+    if (d.fix === 'ci' && !r.onCi) return `fix 'ci' needs onCi true: the gate's fix pass runs the body first, so a check the gate does not run would run there anyway. Say 'manual'`
+    if (d.build && (r.onHealth || r.onPreCommit !== false || d.fix !== 'none'))
+        return `a build step runs only in gates: onHealth false, onPreCommit false, fix 'none' (a tool repairs its own findings)`
+    if (r.onPreCommit !== false) {
+        if (d.body === 'cmd') return `onPreCommit needs an in process run body, never a cmd`
+        if (!d.blocking) return `onPreCommit needs blocking true: the hook only refuses, it never warns about the world`
+        if (c.by === 'ttl' || c.by === 'fact' || c.by === 'never') return `onPreCommit needs cache files or reads: the hook reads the tree, never the world`
+    }
+    if (r.onSave === 'moved' && (c.by === 'ttl' || c.by === 'never')) return `onSave 'moved' needs cache files, reads or fact: nothing can move under ${c.by}`
+    if (r.onClock === ONCE && c.by !== 'fact') return `onClock 'once' needs cache fact: once means while no answer exists for the fact's key`
+    if (c.by === 'fact' && r.onClock !== ONCE) return `cache fact needs onClock 'once': a fact nobody runs once is a fact never answered`
+    if (c.by === 'reads' && d.body === 'cmd') return `cache reads needs a run body: a subprocess records no reads, say files or never`
+    const triggered = r.onPreCommit !== false || r.onCi || r.onFull || r.onRelease || r.onHealth || r.onSave !== false || r.onClock !== false
+    // an opt in build step (a deploy) is the one row nothing but a name runs:
+    // `shipkit ci --with <id>` asks it on purpose
+    if (!triggered && d.fix === 'none' && !d.build) return `nothing runs it: every trigger is false and fix is 'none'. Delete the file, turn it off in the repo with a reason, or make it an opt in build step (build: true)`
+    return null
+}
+
+// ── the resolved row ─────────────────────────────────────────────────────
+
+/** where one resolved value came from */
+export type RunsSource = 'check file' | 'repo.config.ts' | 'derived'
+
+export type ResolvedRuns = Runs & {
+    fix: FixWhen
+    /** a reason the row runs in no context: the repo turned it off, or it
+     *  does not apply here. Null for a live row */
+    off: string | null
+    /** where each value came from */
+    source: Record<RunsAxis | 'fix', RunsSource>
+    /** why a derived row has the values it has, null for a declared one */
+    derivedWhy: string | null
+}
+
+/** every value from one source */
+export function sourced(r: Runs, fix: FixWhen, from: RunsSource, derivedWhy: string | null = null, off: string | null = null): ResolvedRuns {
+    const source = Object.fromEntries([...RUNS_KEYS, 'fix'].map((k) => [k, from])) as ResolvedRuns['source']
+    return { ...r, fix, off, source, derivedWhy }
+}
+
+/** runs in no context at all */
+export const NOWHERE: Runs = { onPreCommit: false, onCi: false, onFull: false, onRelease: false, onHealth: false, onSave: false, onClock: false }
+
+/** the context a runner asks about */
+export type RunContext = 'preCommit' | 'ci' | 'full' | 'release' | 'health'
+
+/** does this context run the row? Off is never */
+export function runsIn(r: ResolvedRuns, ctx: RunContext): boolean {
+    if (r.off != null) return false
+    switch (ctx) {
+        case 'preCommit': return r.onPreCommit !== false
+        case 'ci': return r.onCi
+        case 'full': return r.onFull
+        case 'release': return r.onRelease
+        case 'health': return r.onHealth
+    }
+}
+
+/** the daemon plans it at all */
+export const planned = (r: ResolvedRuns): boolean => r.off == null && (r.onSave !== false || r.onClock !== false)
+
+/** the one line a surface prints for a row that is off */
+export const offLine = (id: string, r: ResolvedRuns): string => `${id} off: ${r.off ?? '(no reason)'}`
+
+/** the cell a matrix prints for one axis */
+export function cellText(r: ResolvedRuns, k: RunsAxis | 'fix'): string {
+    const v = k === 'fix' ? r.fix : r[k]
+    if (v === true) return 'yes'
+    if (v === false) return '·'
+    if (typeof v === 'string') return v
+    if (k === 'onPreCommit') return `${(v as { budgetMs: number }).budgetMs}ms`
+    const c = v as { every: Every; inactive: WhenInactiveDecl }
+    const every = typeof c.every === 'function' ? 'fn' : Array.isArray(c.every) ? `${c.every[0]}..${c.every[1]}` : String(c.every)
+    return `${every}${c.inactive === 'run' ? ' (runs inactive)' : ''}`
+}
+
+/** a files cache as one short cell: three paths, then a count */
+export const filesText = (inputs: string[]): string => `files ${inputs.length <= 3 ? inputs.join(' ') : `${inputs.slice(0, 3).join(' ')} +${inputs.length - 3}`}`
+
+/** the cache variant as one short cell */
+export function cacheText(c: CacheDecl): string {
+    switch (c.by) {
+        case 'files': return filesText(c.inputs)
+        case 'reads': return 'reads'
+        case 'ttl': return `ttl ${c.span}`
+        case 'fact': return 'fact'
+        case 'never': return `never: ${c.why}`
+    }
+}

package/src/core/update-policy.ts

@@ -2,6 +2,8 @@
 // startup self-update and `shipkit fleet --update`. An automatic update never
 // crosses a breaking boundary. It reports the jump and names the one command
 // that takes it on purpose.
+import { lstatSync } from 'fs'
+import { join } from 'path'
 
 /** set by `shipkit fleet --update --major` on the repo run it spawns */
 export const ALLOW_MAJOR_ENV = 'SHIPKIT_ALLOW_MAJOR'
@@ -23,3 +25,21 @@ export function isBreaking(installed: string, latest: string): boolean {
  *  name, which is what `fleet --only` matches */
 export const breakingAdvice = (name: string, latest: string, repo: string): string =>
     `${name} ${latest} available (breaking): run \`shipkit fleet --update --major --only ${repo}\``
+
+/** the lowest version a semver pin admits (`^1.3.0` → 1.3.0, `1.3.0` →
+ *  1.3.0), null for anything else (`link:`, a tag, a url, a range with two
+ *  ends). What a fresh clone of the repo installs is judged from this */
+export function pinFloor(spec: string): string | null {
+    const m = /^(?:[\^~]|>=|=)?\s*v?(\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?)$/.exec(spec.trim())
+    return m?.[1] ?? null
+}
+
+/** true when node_modules/<name> is a symlink (`bun link <name>`): it then
+ *  carries a source tree, whose version says nothing about what the repo pins */
+export function isLinkedInstall(root: string, name: string): boolean {
+    try {
+        return lstatSync(join(root, 'node_modules', name)).isSymbolicLink()
+    } catch {
+        return false
+    }
+}