rvlib-shipkit 1.4.0 → 1.6.0

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/read-set.ts

@@ -9,8 +9,8 @@
 // a millisecond later: the next run hashes the disk again, the two differ, and
 // the check runs. Nothing here can turn a mid-run edit into a replay.
 import { createHash } from 'crypto'
-import { lstatSync, readdirSync, readFileSync, statSync } from 'fs'
-import { join } from 'path'
+import { lstatSync, readdirSync, readFileSync, readlinkSync, statSync } from 'fs'
+import { isAbsolute, join } from 'path'
 
 /** `file` or `dir` when the path was there, null when it was not */
 export type PathKind = 'file' | 'dir' | null
@@ -29,6 +29,60 @@ export type ReadSet = {
     /** repo-relative path → whether a symlink stood there. Absent from a set
      *  stored before it existed */
     links?: Record<string, boolean>
+    /** path → its stat signature (`statSig`). For a path in `files` it is a
+     *  fast path: an unchanged signature skips the content hash. For an
+     *  absolute path outside the repo it is the whole record: a traced task
+     *  reads its runtime and its tools there, which are too big to hash on
+     *  every replay and never shared between checkouts anyway */
+    sigs?: Record<string, string>
+    /** local port → `closed`: a traced task met a refusal there, and its
+     *  answer holds only while nothing listens on it */
+    ports?: Record<string, 'closed'>
+    /** symlink → its target, null when no link stands there: what a traced
+     *  task learned from readlink or lstat */
+    targets?: Record<string, string | null>
+}
+
+/** the target a symlink at `abs` points to, null when none stands there */
+export function linkTarget(abs: string): string | null {
+    try {
+        return readlinkSync(abs)
+    } catch {
+        return null
+    }
+}
+
+let listenMemo: { at: number; ports: Set<string> } | null = null
+
+/** the TCP ports something listens on right now, on any local address. One
+ *  netstat per second at most: a replay asks for several at once */
+export function listeningPorts(now = Date.now()): Set<string> {
+    if (listenMemo != null && now - listenMemo.at < 1_000) return listenMemo.ports
+    const ports = new Set<string>()
+    const r = Bun.spawnSync(['/usr/sbin/netstat', '-an', '-p', 'tcp'], { stdout: 'pipe', stderr: 'pipe' })
+    for (const line of r.stdout.toString().split('\n')) {
+        if (!/\bLISTEN\b/.test(line)) continue
+        const local = line.trim().split(/\s+/)[3] ?? ''
+        const port = local.slice(local.lastIndexOf('.') + 1)
+        if (/^\d+$/.test(port)) ports.add(port)
+    }
+    listenMemo = { at: now, ports }
+    return ports
+}
+
+/** a path as recorded: repo-relative, or absolute for one outside the repo */
+const at = (root: string, p: string): string => (isAbsolute(p) ? p : join(root, p))
+
+/** what stat says about a file: size, modification time to the nanosecond
+ *  and inode, `-` when nothing is there. Content can change under an equal
+ *  signature only when a tool restores the mtime on purpose */
+export function statSig(abs: string): string {
+    try {
+        const s = statSync(abs, { bigint: true })
+        return `${s.size}:${s.mtimeNs}:${s.ino}`
+    } catch {
+        return '-'
+    }
 }
 
 /** one entry of a directory, as `c.entries` returns it */
@@ -103,6 +157,9 @@ export class Reads {
     readonly lists = new Map<string, string>()
     readonly dirs = new Map<string, string | null>()
     readonly links = new Map<string, boolean>()
+    readonly sigs = new Map<string, string>()
+    readonly ports = new Map<string, 'closed'>()
+    readonly targets = new Map<string, string | null>()
 
     file(path: string, oid: string | null): void { this.files.set(path, oid) }
     exist(path: string, kind: PathKind): void { this.exists.set(path, kind) }
@@ -116,11 +173,26 @@ export class Reads {
         for (const [k, v] of o.lists) this.lists.set(k, v)
         for (const [k, v] of o.dirs) this.dirs.set(k, v)
         for (const [k, v] of o.links) this.links.set(k, v)
+        for (const [k, v] of o.sigs) this.sigs.set(k, v)
+        for (const [k, v] of o.ports) this.ports.set(k, v)
+        for (const [k, v] of o.targets) this.targets.set(k, v)
+    }
+
+    /** a whole set, as a traced process read it (trace/read-trace.ts) */
+    mergeSet(s: ReadSet): void {
+        for (const [k, v] of Object.entries(s.files)) this.files.set(k, v)
+        for (const [k, v] of Object.entries(s.exists)) this.exists.set(k, v)
+        for (const [k, v] of Object.entries(s.lists)) this.lists.set(k, v)
+        for (const [k, v] of Object.entries(s.dirs ?? {})) this.dirs.set(k, v)
+        for (const [k, v] of Object.entries(s.links ?? {})) this.links.set(k, v)
+        for (const [k, v] of Object.entries(s.sigs ?? {})) this.sigs.set(k, v)
+        for (const [k, v] of Object.entries(s.ports ?? {})) this.ports.set(k, v)
+        for (const [k, v] of Object.entries(s.targets ?? {})) this.targets.set(k, v)
     }
 
     snapshot(): ReadSet {
         const sorted = <V>(m: Map<string, V>): Record<string, V> => Object.fromEntries([...m].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)))
-        return { files: sorted(this.files), exists: sorted(this.exists), lists: sorted(this.lists), dirs: sorted(this.dirs), links: sorted(this.links) }
+        return { files: sorted(this.files), exists: sorted(this.exists), lists: sorted(this.lists), dirs: sorted(this.dirs), links: sorted(this.links), ...(this.sigs.size > 0 ? { sigs: sorted(this.sigs) } : {}), ...(this.ports.size > 0 ? { ports: sorted(this.ports) } : {}), ...(this.targets.size > 0 ? { targets: sorted(this.targets) } : {}) }
     }
 }
 
@@ -128,25 +200,41 @@ export class Reads {
  *  does. `list` answers a glob the way `c.list` would right now, and returns
  *  null when it cannot answer honestly (no git scan), which counts as drift. */
 export function readSetDrift(root: string, set: ReadSet, list: (glob: string) => readonly string[] | null): string | null {
-    for (const [p, oid] of Object.entries(set.files)) {
-        const now = oidOnDisk(join(root, p))
-        if (now !== oid) return `${p} ${oid == null ? 'appeared' : now == null ? 'is gone' : 'changed'}`
+    const sigs = set.sigs ?? {}
+    for (const [p, sig] of Object.entries(sigs)) {
+        if (p in set.files) continue
+        const now = statSig(at(root, p))
+        if (now !== sig) return `${p} ${sig === '-' ? 'appeared' : now === '-' ? 'is gone' : 'changed'}`
     }
     for (const [p, kind] of Object.entries(set.exists)) {
-        const now = kindOf(join(root, p))
+        const now = kindOf(at(root, p))
         if (now !== kind) return `${p} ${kind == null ? 'appeared' : now == null ? 'is gone' : `is a ${now} now`}`
     }
+    for (const [p, oid] of Object.entries(set.files)) {
+        const abs = at(root, p)
+        if (sigs[p] != null && statSig(abs) === sigs[p]) continue
+        const now = oidOnDisk(abs)
+        if (now !== oid) return `${p} ${oid == null ? 'appeared' : now == null ? 'is gone' : 'changed'}`
+    }
     for (const [g, hash] of Object.entries(set.lists)) {
         const now = list(g)
         if (now == null) return `${g} cannot be listed without a git scan`
         if (listingHash(now) !== hash) return `the files matching ${g} changed`
     }
     for (const [d, hash] of Object.entries(set.dirs ?? {})) {
-        const now = entriesHash(dirEntries(join(root, d)))
+        const now = entriesHash(dirEntries(at(root, d)))
         if (now !== hash) return `${d}/ ${hash == null ? 'appeared' : now == null ? 'is gone' : 'changed its entries'}`
     }
+    for (const [p, t] of Object.entries(set.targets ?? {})) {
+        if (linkTarget(at(root, p)) !== t) return `${p} points elsewhere now`
+    }
+    const closed = Object.keys(set.ports ?? {})
+    if (closed.length > 0) {
+        const open = listeningPorts()
+        for (const port of closed) if (open.has(port)) return `a service listens on local port ${port} now`
+    }
     for (const [p, was] of Object.entries(set.links ?? {})) {
-        if (isLinkAt(join(root, p)) !== was) return `${p} ${was ? 'is no longer a link' : 'became a link'}`
+        if (isLinkAt(at(root, p)) !== was) return `${p} ${was ? 'is no longer a link' : 'became a link'}`
     }
     return null
 }

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`)
     }
@@ -280,10 +284,15 @@ export async function runCi(root: string, o: CiOpts = {}): Promise<number> {
     // stored under a key that describes the file as it was before the edit.
     // the counts line folds into the verdict; what else it says (a store
     // that failed, answers thrown away) is printed as it is
-    if (ledger != null) for (const [i, l] of ledger.header(ledger.commit()).entries()) (i === 0 ? detail : sink)(formatLine(l, false))
+    if (ledger != null) {
+        for (const [i, l] of ledger.header(ledger.commit()).entries()) (i === 0 ? detail : sink)(formatLine(l, false))
+        // why every check that did not replay ran, grouped: a re-run nobody
+        // can explain costs a reader more than the line does
+        for (const { line, quiet } of ledger.explain()) (quiet ? detail : sink)(formatLine(line, 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