rvlib-shipkit 1.3.0 → 1.5.0

package/src/core/motherhome.ts

@@ -1,15 +1,20 @@
-// Report to the motherhome — upsert this repo's row into the docsBase
-// wiki's `build/shipkit/local-projects.md`, when that page ALREADY EXISTS
-// on this disk. The lib NEVER creates the page and never writes into a
-// relative or URL docsBase: the page is a tracked wiki file, so a real
-// docs checkout has it, and a consumer that merely set docsBase as a
-// fix-pointer prefix must never find surprise files in its docs tree.
-// The whole read-modify-write runs under the shared file lock
-// (core/locked-write) — concurrent reporters never lose rows or tear the
-// file; the loser skips and self-heals on its next run. Rows whose repo
-// path no longer exists are pruned on every write. Churn control: a row
-// rewrites only when its DATA changes or its last-seen day is older than
-// 7 days. Never fails the calling command.
+// Report to the motherhome: a repo's row in the docsBase wiki's
+// `build/shipkit/local-projects.md`, in two halves.
+//
+// - `reportToMotherhome` (every ci/check/init) files the row in the MACHINE
+//   DB and nothing else. A gate answers about its own repo, so it never
+//   writes, let alone commits, in the docs repo.
+// - `landMotherhome` (the daemon's hourly sweep) renders every filed row into
+//   its page and lands the page as ONE commit, at most once per LAND_GAP_MS
+//   per page, only when a row's data changed or its last-seen day is older
+//   than STALE_DAYS.
+//
+// The lib NEVER creates the page and never reads a relative or URL docsBase:
+// the page is a tracked wiki file, so a real docs checkout has it, and a
+// consumer that merely set docsBase as a fix-pointer prefix must never find
+// surprise files in its docs tree. The page's read-modify-write runs under
+// the shared file lock (core/locked-write). Rows whose repo path no longer
+// exists are pruned from the page and from the machine db.
 import { existsSync, readFileSync } from 'fs'
 import { homedir } from 'os'
 import { join, resolve } from 'path'
@@ -17,46 +22,31 @@ import type { RepoConfig } from '../repo-config.ts'
 import { atomicWrite, withFileLock } from './locked-write.ts'
 import { isLinkedWorktree } from './git-root.ts'
 import { machineCommit } from './machine-commit.ts'
+import { machineDelete, machineGet, machineList, machineSet } from './machine-db.ts'
 import { LIB_VERSION } from './lib-version.ts'
 
 const BEGIN = '<!-- >>> shipkit local-projects — machine-written, edit outside the markers -->'
 const END = '<!-- <<< shipkit local-projects -->'
 const STALE_DAYS = 7
+/** the longest the page waits for a changed row: one commit a day at most */
+export const LAND_GAP_MS = 24 * 60 * 60 * 1000
+/** a row filed in the machine db, by its repo's path */
+const ROW = 'motherhome:'
+/** when a page last landed, by its path */
+const LANDED = 'motherhome-landed:'
 
 type Row = { name: string; root: string; version: string; mode: string; seen: string }
+type Filed = Row & { page: string }
 
 const rowLine = (r: Row): string => `- ${r.name} — \`${r.root}\` — shipkit ${r.version} (${r.mode}) — last seen ${r.seen}`
 
-/**
- * Commit the row we just wrote, and ONLY that file.
- *
- * This page is machine written and rewrites whenever a repo's shipkit version
- * or consumption mode changes, so left alone it dirties the docs repo from a
- * gate run nobody associates with it, and the dirt then rides into an unrelated
- * commit or blocks a release. The row is not worth a human's attention in
- * either direction, so the machine that writes it also lands it.
- *
- * The scoping, the refusals and the escape hatch live in `core/machine-commit`,
- * which every machine written path commits through. This one fires only when
- * the row's DATA changed, not on every gate, so the hooks it runs are affordable.
- */
-function autoCommitRow(page: string, name: string): string {
-    const landed = machineCommit({
-        anchor: resolve(page, '..'),
-        message: `chore(machine): refresh local-projects row (${name})`,
-        paths: [page],
-    })
-    return landed ? ' + committed' : ''
-}
-
 const parseRow = (line: string): Row | null => {
     const m = line.match(/^- (.+?) — `(.+?)` — shipkit (\S+) \((.+?)\) — last seen (\d{4}-\d{2}-\d{2})$/)
     return m == null ? null : { name: m[1]!, root: m[2]!, version: m[3]!, mode: m[4]!, seen: m[5]! }
 }
 
-
-// how this repo consumes the lib — `?` on an unreadable package.json (a
-// read failure must never be rendered as the fact 'path')
+// how this repo consumes the lib: `?` on an unreadable package.json (a read
+// failure must never be rendered as the fact 'path')
 function consumptionMode(root: string): string {
     try {
         const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { dependencies?: Record<string, string>; devDependencies?: Record<string, string> }
@@ -70,47 +60,79 @@ function consumptionMode(root: string): string {
 
 export type MotherhomeOutcome = { wrote: boolean; note?: string }
 
+/** file this repo's row in the machine db. `wrote` says the filed row changed */
 export function reportToMotherhome(root: string, config: RepoConfig, today: string = new Date().toISOString().slice(0, 10)): MotherhomeOutcome {
     try {
         if (config.docsBase == null) return { wrote: false }
         const base = config.docsBase.startsWith('~/') ? join(homedir(), config.docsBase.slice(2)) : config.docsBase
-        // absolute local paths only — a relative docsBase would resolve
+        // absolute local paths only: a relative docsBase would resolve
         // against CWD, a URL is a display prefix
         if (!base.startsWith('/')) return { wrote: false }
         const page = join(base, 'build/shipkit/local-projects.md')
         if (!existsSync(page)) return { wrote: false }
-        // a gate run inside a linked worktree must not write the MAIN
-        // checkout's tracked page: the row it would add describes a temporary
-        // side checkout, and the write lands as unexplained dirt in a tree
-        // somebody else is working in. The worktree's own runs are covered
-        // when its branch merges.
+        // a linked worktree is a temporary side checkout: its runs are
+        // covered when its branch merges
         if (isLinkedWorktree(root)) return { wrote: false, note: `motherhome: skipped (${config.name} is a linked worktree — its row belongs to the main checkout)` }
-
         const mode = consumptionMode(root)
         // source-consumed code is not the published release its version
-        // string names — disclose it
+        // string names: disclose it
         const version = mode === 'npm' ? LIB_VERSION : `${LIB_VERSION}+src`
-        const me: Row = { name: config.name, root: resolve(root), version, mode, seen: today }
-
-        const r = withFileLock(page, (): MotherhomeOutcome => {
-            const lines = readFileSync(page, 'utf8').split('\n')
-            const b = lines.indexOf(BEGIN)
-            const e = lines.indexOf(END)
-            if (b === -1 || e === -1 || e < b) return { wrote: false, note: `WARN motherhome upsert skipped — markers missing/corrupted in ${page}` }
-            const rows = lines.slice(b + 1, e).map(parseRow).filter((row): row is Row => row != null)
-            const cur = rows.find((row) => row.root === me.root)
-            const dataSame = cur != null && cur.name === me.name && cur.version === me.version && cur.mode === me.mode
-            const fresh = cur != null && (Date.parse(today) - Date.parse(cur.seen)) / 86_400_000 < STALE_DAYS
-            if (dataSame && fresh) return { wrote: false }
-            // prune rows for repos that no longer exist at their recorded path
-            const next = [...rows.filter((row) => row.root !== me.root && existsSync(row.root)), me].sort((a, z) => a.name.localeCompare(z.name))
-            atomicWrite(page, [...lines.slice(0, b + 1), ...next.map(rowLine), ...lines.slice(e)].join('\n'))
-            const committed = autoCommitRow(page, me.name)
-            return { wrote: true, note: `motherhome: local-projects.md ${cur == null ? 'row added' : 'row refreshed'} (${me.name})${committed}` }
-        })
-        // lock lost to a racing reporter — self-heals on the next run
-        return r.ok ? r.value : { wrote: false }
+        const me: Filed = { page, name: config.name, root: resolve(root), version, mode, seen: today }
+        const key = `${ROW}${me.root}`
+        if (JSON.stringify(machineGet<Filed>(key)) === JSON.stringify(me)) return { wrote: false }
+        return machineSet(key, me) ? { wrote: true } : { wrote: false, note: 'WARN motherhome row not filed: the machine db could not be written' }
     } catch (err) {
-        return { wrote: false, note: `WARN motherhome upsert failed (${String(err).slice(0, 120)}) — registry may be stale` }
+        return { wrote: false, note: `WARN motherhome row not filed (${String(err).slice(0, 120)})` }
+    }
+}
+
+/** a page's rows once the filed ones are merged in: a filed row replaces the
+ *  page's only when its data changed or the page's day is STALE_DAYS old,
+ *  and a row whose repo path is gone is pruned */
+function mergeRows(onPage: Row[], filed: Row[]): Row[] {
+    const by = new Map(onPage.map((r) => [r.root, r]))
+    for (const f of filed) {
+        const cur = by.get(f.root)
+        const same = cur != null && cur.name === f.name && cur.version === f.version && cur.mode === f.mode
+        const fresh = cur != null && (Date.parse(f.seen) - Date.parse(cur.seen)) / 86_400_000 < STALE_DAYS
+        if (!(same && fresh)) by.set(f.root, { name: f.name, root: f.root, version: f.version, mode: f.mode, seen: f.seen })
+    }
+    return [...by.values()].filter((r) => existsSync(r.root)).sort((a, z) => a.name.localeCompare(z.name) || a.root.localeCompare(z.root))
+}
+
+/** render every filed row into its page and land each changed page as one
+ *  commit, at most once per LAND_GAP_MS. Returns what to print */
+export function landMotherhome(o: { now?: number; gapMs?: number } = {}): string[] {
+    const now = o.now ?? Date.now()
+    const notes: string[] = []
+    const filed = machineList<Filed>(ROW)
+    for (const f of filed) if (!existsSync(f.value.root)) machineDelete(f.name)
+    const pages = new Map<string, Row[]>()
+    for (const f of filed) if (existsSync(f.value.root)) pages.set(f.value.page, [...(pages.get(f.value.page) ?? []), f.value])
+    for (const [page, rows] of pages) {
+        try {
+            if (!existsSync(page)) continue
+            const last = machineGet<number>(`${LANDED}${page}`)
+            if (last != null && now - last < (o.gapMs ?? LAND_GAP_MS)) continue
+            const r = withFileLock(page, (): boolean => {
+                const text = readFileSync(page, 'utf8')
+                const lines = text.split('\n')
+                const b = lines.indexOf(BEGIN)
+                const e = lines.indexOf(END)
+                if (b === -1 || e === -1 || e < b) { notes.push(`WARN motherhome: markers missing or out of order in ${page}, rows not written`); return false }
+                const onPage = lines.slice(b + 1, e).map(parseRow).filter((row): row is Row => row != null)
+                const next = [...lines.slice(0, b + 1), ...mergeRows(onPage, rows).map(rowLine), ...lines.slice(e)].join('\n')
+                if (next === text) return false
+                atomicWrite(page, next)
+                return true
+            })
+            if (!r.ok || !r.value) continue
+            machineSet(`${LANDED}${page}`, now)
+            const landed = machineCommit({ anchor: resolve(page, '..'), message: 'chore(machine): refresh local-projects rows', paths: [page] })
+            notes.push(`motherhome: ${page} rows refreshed${landed ? ' + committed' : ', not committed'}`)
+        } catch (err) {
+            notes.push(`WARN motherhome: ${page} not refreshed (${String(err).slice(0, 120)})`)
+        }
     }
+    return notes
 }

package/src/core/one-way-in-policy.ts

@@ -1,4 +1,4 @@
-// ONE WAY IN, the harness half (build/shipkit.md). The package.json half
+// ONE WAY IN, the harness half (build/shipkit/one-way-in.md). The package.json half
 // (rule SK001) routes `bun run test` into shipkit, but `bun test` is a bun
 // BUILTIN: no script can intercept it, so a package.json alone leaves the
 // reflex wide open. Claude Code permission rules can close it.
@@ -76,7 +76,7 @@ export const denyRules = (exemptSlots: Iterable<string> = []): string[] => {
 export function refusal(r: RawRunner, segment?: string): string {
     const alt = r.iterate == null ? '' : `, or \`${r.iterate}\` to iterate on ONE suite while you fix a bug`
     const which = segment == null || segment.trim() === '' || segment.trim() === r.head ? '' : ` (refused on \`${segment.trim().slice(0, 80)}\`)`
-    return `\`${r.head}\`${which} bypasses shipkit, so nothing is cached and no other agent's run can be attached to. Use \`${r.use}\`${alt}. Lifting this for good: delete the "Bash(${r.head}*)" line from .claude/settings.json permissions.deny (build/shipkit.md, ONE WAY IN).`
+    return `\`${r.head}\`${which} bypasses shipkit, so nothing is cached and no other agent's run can be attached to. Use \`${r.use}\`${alt}. Lifting this for good: delete the "Bash(${r.head}*)" line from .claude/settings.json permissions.deny (build/shipkit/one-way-in.md).`
 }
 
 /** shell wrappers that do not change what is being run */

package/src/core/outcome-words.ts

@@ -38,8 +38,24 @@ export const checkVerdictWords = (status: 'pass' | 'warn' | 'fail' | 'skip' | nu
             : status === 'skip' ? 'skipped'
                 : status === 'pass' ? (o.replayed ? `passed, ${CACHED}` : 'passed') : 'never ran here'
 
-/** the stamp on the first line of a cached check: `(cached, 5.6s saved)` */
-export const cachedStamp = (savedMs: number): string => `(${CACHED}, ${(savedMs / 1000).toFixed(1)}s saved)`
+/** a span in its one biggest unit: `45s`, `12m`, `3h`, `2d` */
+export function spanShort(ms: number): string {
+    const s = Math.max(0, Math.round(ms / 1000))
+    if (s < 60) return `${s}s`
+    if (s < 3600) return `${Math.floor(s / 60)}m`
+    if (s < 86400) return `${Math.floor(s / 3600)}h`
+    return `${Math.floor(s / 86400)}d`
+}
+
+/** what a run cost: `12ms` under a second, `6.4s` past it */
+export const costShort = (ms: number): string => (ms < 1000 ? `${Math.max(0, Math.round(ms))}ms` : `${(ms / 1000).toFixed(1)}s`)
+
+/** the stamp on the first line of a cached check: how old the answer is and
+ *  what measuring it cost, `(cached, 3h old, 5.6s saved)` */
+export const cachedStamp = (savedMs: number, ageMs: number): string => `(${CACHED}, ${spanShort(ageMs)} old, ${costShort(savedMs)} saved)`
+
+/** the stamp on the first line of a check that ran in this run: `(ran 6.4s)` */
+export const ranStamp = (ms: number): string => `(${RAN} ${costShort(ms)})`
 
 /** the stamp on the first line of an attached check */
 export const attachedStamp = (pid: number, ranMs: number): string => `(${ATTACHED} to pid ${pid}, ${RAN} there in ${(ranMs / 1000).toFixed(1)}s)`

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

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

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

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

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

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