rvlib-shipkit 1.1.1 → 1.3.0

package/src/core/machine-db.ts

@@ -0,0 +1,83 @@
+// THE MACHINE DB: what shipkit remembers about this machine, whatever repo
+// asks, in one sqlite file: pm's children and resources (their pid records),
+// the repos flagged active, the rail order, the self update answer, the
+// instance registry. One `state` table of named json values.
+//
+// The one constraint a reader breaks first: a failure reads as "nothing
+// remembered", and every caller treats that as the safe side (no adoption,
+// no replay, the pid rule). Slot LOCKS are not here: they are leases a dead
+// pid must release at once, which a file does and a row does not.
+import { Database } from 'bun:sqlite'
+import { existsSync, mkdirSync, readFileSync, rmSync } from 'fs'
+import { homedir } from 'os'
+import { dirname, join } from 'path'
+import { ensureWal } from '../ledger/db.ts'
+
+export const MACHINE_DB_ENV = 'SHIPKIT_MACHINE_DB'
+
+/** `~/.config/shipkit/shipkit.sqlite`; beside a moved home dir when one is
+ *  set, so a smoke or a suite with its own home never touches the real one */
+export function machineDbPath(): string {
+    const env = process.env[MACHINE_DB_ENV]
+    if (env != null && env !== '') return env
+    const home = process.env.SHIPKIT_HOME_DIR
+    if (home != null && home !== '') return join(home, 'machine.sqlite')
+    return join(homedir(), '.config', 'shipkit', 'shipkit.sqlite')
+}
+
+/** a machine write waits this long on another process's */
+const BUSY_MS = 2_000
+
+const SCHEMA = 'create table if not exists state (name text primary key, value text not null, at integer not null)'
+
+function withMachine<R>(body: (db: Database) => R, path = machineDbPath()): R | null {
+    let db: Database | null = null
+    try {
+        mkdirSync(dirname(path), { recursive: true })
+        db = new Database(path, { create: true, readwrite: true })
+        db.exec(`pragma busy_timeout = ${BUSY_MS}`)
+        ensureWal(db, BUSY_MS)
+        db.exec(SCHEMA)
+        return body(db)
+    } catch {
+        return null
+    } finally {
+        try { db?.close() } catch { /* never opened */ }
+    }
+}
+
+export function machineGet<T>(name: string): T | null {
+    const row = withMachine((db) => db.query('select value from state where name = ?').get(name) as { value: string } | null)
+    if (row == null) return null
+    try { return JSON.parse(row.value) as T } catch { return null }
+}
+
+export function machineSet(name: string, value: unknown): boolean {
+    return withMachine((db) => {
+        db.query('insert or replace into state (name, value, at) values (?, ?, ?)').run(name, JSON.stringify(value), Date.now())
+        return true
+    }) ?? false
+}
+
+export function machineDelete(name: string): void {
+    withMachine((db) => db.query('delete from state where name = ?').run(name))
+}
+
+/** every value whose name starts with `prefix` */
+export function machineList<T>(prefix: string): { name: string; value: T; at: number }[] {
+    const rows = withMachine((db) => db.query('select name, value, at from state where substr(name, 1, ?) = ?').all(prefix.length, prefix) as { name: string; value: string; at: number }[]) ?? []
+    return rows.flatMap((r) => {
+        try { return [{ name: r.name, value: JSON.parse(r.value) as T, at: r.at }] } catch { return [] }
+    })
+}
+
+/** the migration of one json file: its value becomes the row, then the file
+ *  goes. Only when the row does not exist yet, so a file an older copy wrote
+ *  after the move never overwrites a newer row */
+export function importMachineFile<T>(name: string, file: string, parse: (text: string) => T = (t) => JSON.parse(t) as T): void {
+    if (!existsSync(file)) return
+    try {
+        if (machineGet(name) == null) machineSet(name, parse(readFileSync(file, 'utf8')))
+        rmSync(file, { force: true })
+    } catch { /* an unreadable file is left for a person to look at */ }
+}

package/src/core/one-lib.ts

@@ -0,0 +1,85 @@
+// one copy of the toolkit per process: a process that loads several repos
+// (the home) makes every `rvlib-shipkit` import, from any repo config or check
+// file, land on its OWN copy. A repo's install is never loaded, so there is one
+// module instance per lib file: one mobx, one class identity, one version.
+//
+// the one constraint a reader breaks first: register it BEFORE the first repo
+// config is imported. A module already loaded keeps the copy it resolved.
+import { readFileSync, realpathSync } from 'fs'
+import { extname, join } from 'path'
+import { LIB_ROOT } from './lib-root.ts'
+
+const NAME = 'rvlib-shipkit'
+
+type Exports = Record<string, string>
+
+const readExports = (root: string): Exports => {
+    try {
+        const pkg = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')) as { exports?: Exports }
+        return pkg.exports ?? { '.': './src/shipkit.ts' }
+    } catch {
+        return { '.': './src/shipkit.ts' }
+    }
+}
+
+/** the file a specifier names inside `root`, through its package exports
+ *  (`.`, `./contracts`, `./src/*`), or null when it is not this package */
+export function libTarget(spec: string, root: string = LIB_ROOT, exports: Exports = readExports(root)): string | null {
+    if (spec !== NAME && !spec.startsWith(`${NAME}/`)) return null
+    const sub = `.${spec.slice(NAME.length)}`
+    const exact = exports[sub]
+    if (exact != null) return join(root, exact)
+    for (const [k, v] of Object.entries(exports)) {
+        if (!k.endsWith('/*') || !sub.startsWith(k.slice(0, -1))) continue
+        return join(root, v.slice(0, -1) + sub.slice(k.length - 1))
+    }
+    return join(root, sub)
+}
+
+/** a file of ANOTHER copy of the package (a repo's node_modules, bun's
+ *  install cache), as the path inside that copy, else null */
+export function foreignLibPath(path: string, root: string = LIB_ROOT): string | null {
+    const m = /\/(?:node_modules\/rvlib-shipkit|install\/cache\/rvlib-shipkit@[^/]*)\/(.+)$/.exec(path)
+    if (m == null) return null
+    const own = real(root)
+    if (path.startsWith(`${root}/`) || real(path).startsWith(`${own}/`)) return null
+    return m[1]!
+}
+
+const real = (p: string): string => {
+    try {
+        return realpathSync(p)
+    } catch {
+        return p
+    }
+}
+
+const LOADERS: Record<string, 'ts' | 'tsx' | 'js' | 'jsx'> = { '.ts': 'ts', '.tsx': 'tsx', '.js': 'js', '.mjs': 'js', '.jsx': 'jsx' }
+
+let installed = false
+
+/** route every import of the package to this process's copy. Idempotent */
+export function useOneLib(root: string = LIB_ROOT): void {
+    if (installed) return
+    installed = true
+    const exports = readExports(root)
+    Bun.plugin({
+        name: 'shipkit-one-lib',
+        setup(build) {
+            // a subpath is resolved here, before any other copy is looked at
+            build.onResolve({ filter: /^rvlib-shipkit\// }, (a) => {
+                const path = libTarget(a.path, root, exports)
+                return path == null ? undefined : { path }
+            })
+            // the bare name never reaches onResolve at runtime, so the file
+            // another copy resolved to is loaded as a re-export of ours
+            build.onLoad({ filter: /\/(node_modules\/rvlib-shipkit|install\/cache\/rvlib-shipkit@[^/]*)\// }, (a) => {
+                const loader = LOADERS[extname(a.path)] ?? 'ts'
+                const sub = foreignLibPath(a.path, root)
+                if (sub == null) return { contents: readFileSync(a.path, 'utf8'), loader }
+                const target = JSON.stringify(join(root, sub))
+                return { contents: `export * from ${target}\nimport * as own from ${target}\nexport default (own as { default?: unknown }).default\n`, loader: 'ts' }
+            })
+        },
+    })
+}

package/src/core/port-holders.ts

@@ -0,0 +1,43 @@
+// who holds a local tcp port, and the process group a pid runs in: what a
+// takeover of a server started elsewhere needs to stop it. Unreadable (no
+// lsof, no ps) means an empty answer, never a throw.
+import { existsSync } from 'fs'
+
+/** the pids LISTENING on a tcp port, on darwin and linux. `-sTCP:LISTEN`
+ *  carries the whole answer: `-i tcp:<port>` alone also matches every client
+ *  connected to it, this process included, and those must never be killed.
+ *  lsof sits in /usr/sbin on darwin, which a gui-launched shell can miss */
+export function portHolders(port: number): number[] {
+    const lsof = Bun.which('lsof') ?? ['/usr/sbin/lsof', '/usr/bin/lsof'].find((p) => existsSync(p))
+    if (lsof == null) return []
+    const r = Bun.spawnSync([lsof, '-ti', `tcp:${port}`, '-sTCP:LISTEN'], { stdout: 'pipe', stderr: 'ignore' })
+    const pids = r.stdout
+        .toString()
+        .split('\n')
+        .map((l) => Number(l.trim()))
+        .filter((n) => Number.isInteger(n) && n > 0)
+    return [...new Set(pids)]
+}
+
+/** the process group of a pid, null when ps cannot say */
+export function groupOf(pid: number): number | null {
+    const ps = Bun.which('ps') ?? (existsSync('/bin/ps') ? '/bin/ps' : null)
+    if (ps == null) return null
+    const r = Bun.spawnSync([ps, '-o', 'pgid=', '-p', String(pid)], { stdout: 'pipe', stderr: 'ignore' })
+    const g = Number(r.stdout.toString().trim())
+    return Number.isInteger(g) && g > 0 ? g : null
+}
+
+/** the port a local url serves on, null for a remote host or no url */
+export function localPort(url: string | null): number | null {
+    if (url == null) return null
+    let u: URL
+    try {
+        u = new URL(url)
+    } catch {
+        return null
+    }
+    if (!['127.0.0.1', 'localhost', '[::1]', '0.0.0.0'].includes(u.hostname)) return null
+    const p = u.port !== '' ? Number(u.port) : u.protocol === 'https:' ? 443 : u.protocol === 'http:' ? 80 : NaN
+    return Number.isInteger(p) && p > 0 ? p : null
+}

package/src/core/repo-facts.ts

@@ -0,0 +1,14 @@
+// what a repo declares about itself and its root unit, read from its config.
+// Its own module, free of any fs import, so a check that asks it stays keyed
+// on what it read.
+import type { RepoConfig } from '../repo-config.ts'
+
+/** the github visibility this repo declares (absent = 'private') */
+export const declaredVisibility = (c: RepoConfig): 'private' | 'public' => c.visibility ?? 'private'
+
+/** declared public: strangers read the tracked tree */
+export const declaredPublic = (c: RepoConfig): boolean => c.visibility === 'public'
+
+/** the root unit declares an npm target. Declared, never inferred from a
+ *  missing `private` flag, so an app that forgot the flag is still an app */
+export const rootPublishesNpm = (c: RepoConfig): boolean => c.release?.npm === true

package/src/core/retention.ts

@@ -0,0 +1,222 @@
+// NOTHING GROWS UNBOUND: every store shipkit writes declares a cap here (an
+// age, a count, a size), and one sweep enforces all of them. The daemon runs
+// it on boot and hourly for every repo it loads and for the machine; the
+// house repo's one `stores-under-cap` check fails when a store is past its
+// cap, so a sweep that stopped running is loud. Each store's sweep lives beside the code that writes it, so a gate
+// on a machine with no daemon still keeps its own stores in bounds.
+//
+// The one constraint a reader breaks first: a sweep never removes what a live
+// process may still use. Every sweep below checks a pid or an age first.
+import { existsSync, readdirSync, statSync } from 'fs'
+import { join } from 'path'
+import { INFLIGHT_KEEP_MS, sweepSlots } from './attach.ts'
+import { RUN_DIR_KEEP_MS, RUN_DIR_MAX, runEntries, sweepRunDirs } from './check-runner.ts'
+import { gitRoot } from './git-root.ts'
+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'
+
+export type Cap = {
+    /** the oldest entry may be this old */
+    maxAgeMs?: number
+    /** at most this many entries */
+    maxCount?: number
+    /** every file at most this big */
+    maxFileBytes?: number
+    /** all of it at most this big */
+    maxBytes?: number
+}
+
+export type Use = { count: number; oldestAt: number | null; bytes: number; largestFile: number }
+
+export type Store = {
+    id: string
+    /** where it lives, as a person would look for it */
+    where: string
+    cap: Cap
+    /** what it holds now, null when it cannot be read */
+    measure(): Use | null
+    /** bring it back under its cap */
+    sweep(now: number): void | Promise<void>
+}
+
+/** how far past its cap a store may drift between two sweeps before the
+ *  house check calls it over: the daemon sweeps hourly, and gates write in between */
+export const SLACK = { factor: 2, ageMs: 2 * 60 * 60 * 1000 }
+
+/** why a store is past its cap (with the drift a sweep interval allows), or
+ *  null while it is inside */
+export function overCap(use: Use, cap: Cap, now: number, slack = SLACK): string | null {
+    if (cap.maxCount != null && use.count > Math.max(cap.maxCount * slack.factor, cap.maxCount)) return `${use.count} entries, cap ${cap.maxCount}`
+    if (cap.maxAgeMs != null && use.oldestAt != null && now - use.oldestAt > cap.maxAgeMs + slack.ageMs) return `oldest ${fmtAge(now - use.oldestAt)} old, cap ${fmtAge(cap.maxAgeMs)}`
+    if (cap.maxFileBytes != null && use.largestFile > cap.maxFileBytes * slack.factor) return `a file of ${fmtBytes(use.largestFile)}, cap ${fmtBytes(cap.maxFileBytes)}`
+    if (cap.maxBytes != null && use.bytes > cap.maxBytes * slack.factor) return `${fmtBytes(use.bytes)}, cap ${fmtBytes(cap.maxBytes)}`
+    return null
+}
+
+/** a cap in words: `200 entries, 30d, 5.0 MB a file` */
+export const capWords = (s: Store): string =>
+    [
+        s.cap.maxCount != null ? `${s.cap.maxCount} entries` : null,
+        s.cap.maxAgeMs != null ? fmtAge(s.cap.maxAgeMs) : null,
+        s.cap.maxFileBytes != null ? `${fmtBytes(s.cap.maxFileBytes)} a file` : null,
+        s.cap.maxBytes != null ? fmtBytes(s.cap.maxBytes) : null,
+    ].filter((x) => x != null).join(', ')
+
+export const fmtBytes = (n: number): string => (n >= 1 << 20 ? `${(n / (1 << 20)).toFixed(1)} MB` : n >= 1024 ? `${Math.round(n / 1024)} KB` : `${n} B`)
+export const fmtAge = (ms: number): string => (ms >= 86_400_000 ? `${Math.round(ms / 86_400_000)}d` : ms >= 3_600_000 ? `${Math.round(ms / 3_600_000)}h` : `${Math.round(ms / 60_000)}m`)
+
+/** every file under a dir (not following links), skipping dirs `skip` names */
+export function walkUse(dir: string, o: { match?: (name: string) => boolean; skip?: (name: string) => boolean } = {}): Use | null {
+    if (!existsSync(dir)) return { count: 0, oldestAt: null, bytes: 0, largestFile: 0 }
+    const use: Use = { count: 0, oldestAt: null, bytes: 0, largestFile: 0 }
+    const walk = (d: string): void => {
+        let list
+        try { list = readdirSync(d, { withFileTypes: true }) } catch { return }
+        for (const e of list) {
+            const p = join(d, e.name)
+            if (e.isDirectory()) { if (o.skip?.(e.name) !== true) walk(p); continue }
+            if (!e.isFile() || (o.match != null && !o.match(e.name))) continue
+            try {
+                const s = statSync(p)
+                use.count++
+                use.bytes += s.size
+                use.largestFile = Math.max(use.largestFile, s.size)
+                use.oldestAt = use.oldestAt == null ? s.mtimeMs : Math.min(use.oldestAt, s.mtimeMs)
+            } catch { /* raced: gone */ }
+        }
+    }
+    walk(dir)
+    return use
+}
+
+const counted = (count: number, oldestAt: number | null): Use => ({ count, oldestAt, bytes: 0, largestFile: 0 })
+
+/** the stores one repo holds */
+export function repoStores(root: string): Store[] {
+    const sk = shipkitRoot(root)
+    const logs = join(root, CI_LOG_DIR)
+    const jobs = join(root, JOBS)
+    const gitDir = gitRoot(root)?.gitDir
+    const stores: Store[] = [
+        {
+            id: 'answers',
+            where: `${answersDb(root)} (answers)`,
+            cap: { maxAgeMs: ANSWERS_KEEP_MS, maxCount: MAX_ANSWERS },
+            measure: () => {
+                if (!existsSync(answersDb(root))) return counted(0, null)
+                const u = answersUse(answersDb(root))
+                return u == null ? null : counted(u.count, u.oldestUsed)
+            },
+            sweep: (now) => { sweepAnswers(answersDb(root), now) },
+        },
+        {
+            // the json store this table replaced: read once, then gone
+            id: 'json answers',
+            where: legacyStoreDir(root),
+            cap: { maxCount: 0 },
+            measure: () => walkUse(legacyStoreDir(root)),
+            sweep: async (now) => { await importLegacyStore(root, now) },
+        },
+        {
+            id: 'run record',
+            where: `${dbPath(root)} (runs, invocations, suites)`,
+            cap: { maxAgeMs: RECORD_KEEP_MS, maxCount: MAX_ROWS },
+            measure: () => {
+                if (!existsSync(dbPath(root))) return counted(0, null)
+                const u = recordUse(dbPath(root))
+                return u == null ? null : counted(u.count, u.oldest)
+            },
+            // the last db store: the answers above and these rows are one
+            // file, which the deletes leave full of free pages
+            sweep: (now) => {
+                sweepRuns(dbPath(root), now)
+                compactDb(dbPath(root))
+            },
+        },
+        {
+            id: 'inflight',
+            where: join(sk, 'inflight'),
+            cap: { maxAgeMs: INFLIGHT_KEEP_MS },
+            measure: () => walkUse(join(sk, 'inflight')),
+            sweep: (now) => sweepSlots(join(sk, 'inflight'), now),
+        },
+        {
+            id: 'run logs',
+            where: logs,
+            cap: { maxAgeMs: RUN_DIR_KEEP_MS, maxCount: RUN_DIR_MAX },
+            measure: () => {
+                const all = runEntries(logs)
+                return counted(all.length, all.length === 0 ? null : Math.min(...all.map((e) => e.started)))
+            },
+            sweep: (now) => sweepRunDirs(logs, now),
+        },
+        {
+            id: 'jobs',
+            where: jobs,
+            cap: { maxAgeMs: JOBS_KEEP_MS, maxCount: JOBS_MAX },
+            measure: () => {
+                let names: string[] = []
+                try { names = readdirSync(jobs) } catch { return counted(0, null) }
+                let oldest: number | null = null
+                for (const n of names) try { const m = statSync(join(jobs, n)).mtimeMs; oldest = oldest == null ? m : Math.min(oldest, m) } catch { /* raced */ }
+                return counted(names.length, oldest)
+            },
+            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')
+        stores.push({
+            id: 'scan indexes',
+            where: `${dir}/scan-<pid>.idx`,
+            // one per process scanning at once, and a machine runs a handful
+            cap: { maxAgeMs: SCAN_INDEX_KEEP_MS, maxCount: 16 },
+            measure: () => walkUse(dir, { match: (n) => /^scan-\d+\.idx(\.tmp)?$/.test(n), skip: () => true }),
+            sweep: (now) => sweepScanIndexes(dir, now),
+        })
+    }
+    return stores
+}
+
+export type Measured = { store: Store; use: Use | null; over: string | null }
+
+export function measureStores(stores: Store[], now = Date.now()): Measured[] {
+    return stores.map((store) => {
+        const use = store.measure()
+        return { store, use, over: use == null ? null : overCap(use, store.cap, now) }
+    })
+}
+
+/** sweep every store, one after the other, yielding between them so a
+ *  daemon keeps serving. A sweep that throws is reported, never fatal */
+export async function sweepStores(stores: Store[], now = Date.now()): Promise<{ id: string; error: string | null }[]> {
+    const out: { id: string; error: string | null }[] = []
+    for (const s of stores) {
+        try {
+            await s.sweep(now)
+            out.push({ id: s.id, error: null })
+        } catch (e) {
+            out.push({ id: s.id, error: (e as Error).message })
+        }
+        await Bun.sleep(0)
+    }
+    return out
+}

package/src/core/retired-checks.ts

@@ -0,0 +1,7 @@
+// built-in check ids that no longer exist, and where their question went. An
+// id is never reused, so a doc or a changelog may still name one, and
+// discovery refuses a built-in that takes one again.
+export const RETIRED_CHECK_IDS: Readonly<Record<string, string>> = {
+    SK021: "the gh login is a machine fact: the house repo's github-login check runs src/core/gh-login.ts",
+    SK023: "the store caps are the machine daemon's health: the house repo's stores-under-cap check",
+}

package/src/core/run-check.ts

@@ -12,7 +12,7 @@ import { join } from 'path'
 import { composeChecks, envTier, gateInventory, type GateCheck, type TestTier } from '../ledger/gate-checks.ts'
 import { Ledger } from '../ledger/ledger.ts'
 import { RunLog, type InvokedBy } from '../ledger/run-log.ts'
-import { storeRoot } from '../ledger/store.ts'
+import { answersDb } from '../ledger/store.ts'
 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'
@@ -37,6 +37,9 @@ export type CheckOpts = {
     status?: boolean
     /** line sink — commands pass their context stream; defaults to console */
     print?: (line: string) => void
+    /** where the lines nobody acts on go: the parked list and the green
+     *  summary. `shipkit ci` shows them only under --verbose. Default: print */
+    detail?: (line: string) => void
     /** per-CHECK completion tap: the real status, whether it replayed, what it
      *  cost. The demotion of a non-blocking failure happens in the LINES (a
      *  FAIL is rewritten to a warn before anything sees it), so `status` here
@@ -55,6 +58,9 @@ export type CheckOpts = {
     onlyBlocking?: boolean
     /** which test tier the caller is asking for */
     tier?: TestTier
+    /** colour the wire lines. Default: this process's stdout is a terminal. A
+     *  hub running a terminal's gate passes the terminal's answer */
+    color?: boolean
     /** which question: the gate's set (`shipkit ci`) or the health pass's */
     audience?: Audience
     /** the caller narrowed the run to these ids (`--only`) */
@@ -187,16 +193,18 @@ export async function runCheckPass(root: string, o: CheckOpts = {}): Promise<Che
         root,
         config: c,
         logDir: c.logDir ?? join(root, CI_LOG_DIR),
-        cache: { storeDir: storeRoot(root), ns: c.name, now: Date.now },
+        cache: { db: answersDb(root), ns: c.name, now: Date.now },
         ledger,
         log,
         childEnv: { [SHARE_ENV]: sharePath, ...(o.fresh === true ? { SHIPKIT_FRESH: '1' } : {}) },
         bail: o.bail,
+        color: o.color,
         print: sink,
+        detail: o.detail,
         onCheck: (e) => { collected.push(...e.lines); o.onCheck?.(e) },
     })
     const lines: Line[] = []
-    const say = (l: Line): void => { lines.push(l); print(formatLine(l, false)) }
+    const say = (l: Line, to: (line: string) => void = print): void => { lines.push(l); to(formatLine(l, false)) }
     // a declaration in a shape the check file replaced is reported by check
     // SK016, which also carries the fixer that rewrites it: one owner, one
     // line, one command, rather than a warning per surface.
@@ -206,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` : ''}` })
+        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)
     }
     // 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 {} }