rvlib-shipkit 1.7.0 → 1.8.0

package/src/suite/suite-cli.ts

@@ -9,27 +9,39 @@
 import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'fs'
 import { availableParallelism, tmpdir } from 'os'
 import { machineLoad } from '../core/budget.ts'
-import { join } from 'path'
+import { join, posix } from 'path'
 import { FULL_TESTS_ENV } from '../ledger/gate-checks.ts'
 import { CHECK_ID_ENV, recordSuites, type SuitePhase } from '../ledger/suite-log.ts'
 import { killTree } from '../core/spawn-timeout.ts'
 import { parallelCap } from '../core/parallel.ts'
 import { poolDir, poolOccupancy } from '../core/slots.ts'
 import { keepTimings, seedTimings, timingsHome } from './kept-timings.ts'
-import { aloneRunsNeeded, bunfigTest, readPhaseCpu, SUITE_CPU_ENV, type AloneRun, type Confirmed, confirmOver, crashedWorkers, overWords, DEFAULT_BUDGET_MS, FULL_CEILING_MS, failedSuites, failLines, judgeSuites, normSuitePath, parseSuiteFlags, planPhases, QUICK_CEILING_MS, poolWorkers } from './judge-suites.ts'
+import { SUITE_READS_ENV, SUITE_ROOT_ENV, SUITE_SELECT_ENV } from './reads-env.ts'
+import { changedKeys, dropStaticEdges, extras, isBunSuite, envFilesOf, foldReads, loadErrorModules, loadState, preloadsOf, saveState, selectStatePath, selectSuites, snapshot, suiteFiles, taintedSuites, walkGraph, type GraphEntry, type Selection, type SelectState } from './select.ts'
+import { gitRoot } from '../core/git-root.ts'
+import { loadConfig } from '../ts/config.ts'
+import { aloneRunsNeeded, bunfigTest, type BunfigTest, readPhaseCpu, SUITE_CPU_ENV, type AloneRun, type Confirmed, confirmOver, crashedWorkers, overWords, DEFAULT_BUDGET_MS, FULL_CEILING_MS, failedSuites, failLines, judgeSuites, normSuitePath, parseSuiteFlags, planPhases, QUICK_CEILING_MS, poolWorkers } from './judge-suites.ts'
 
 type Phase = { code: number; signal: string | null; stalled: boolean; out: string; timings: Record<string, number>; cpuMs: number | null }
 
-async function runPhase(args: string[], timingsFile: string | null, ceilingMs: number, tmp: string, echo = true, cpuFile: string | null = null): Promise<Phase> {
+/** where the read recorder writes, and the repo root it charges reads under */
+type Recording = { file: string; top: string }
+
+async function runPhase(args: string[], timingsFile: string | null, ceilingMs: number, tmp: string, echo = true, cpuFile: string | null = null, rec: Recording | null = null): Promise<Phase> {
     const timing = timingsFile != null ? [`--timings=${timingsFile}`, '--update-timings'] : []
     // the per suite CPU figure rides in a preload of the runner's own, beside
     // the repo's (a command line preload adds to bunfig's, never replaces it)
     const cpu = cpuFile != null ? ['--preload', CPU_PRELOAD] : []
+    const reads = rec != null ? ['--preload', READS_PRELOAD] : []
     // TMPDIR is the run's own dir, deleted with it: whatever a suite forgets to
     // clean dies here, never in the machine temp dir, whose listing bun reads on
     // the first import from a fixture there (90k leaked dirs cost ~100ms each time)
-    const env = { ...process.env, TMPDIR: tmp, ...(cpuFile != null ? { [SUITE_CPU_ENV]: cpuFile } : {}) }
-    const proc = Bun.spawn(['bun', 'test', ...cpu, ...timing, ...args], { stdout: 'pipe', stderr: 'pipe', stdin: 'ignore', env })
+    const env = {
+        ...process.env, TMPDIR: tmp,
+        ...(cpuFile != null ? { [SUITE_CPU_ENV]: cpuFile } : {}),
+        ...(rec != null ? { [SUITE_READS_ENV]: rec.file, [SUITE_ROOT_ENV]: rec.top } : {}),
+    }
+    const proc = Bun.spawn(['bun', 'test', ...cpu, ...reads, ...timing, ...args], { stdout: 'pipe', stderr: 'pipe', stdin: 'ignore', env })
     // the workers are children of `bun test`, and a stuck one is the process
     // to reach, so the whole tree goes
     let stalled = false
@@ -60,6 +72,8 @@ async function runPhase(args: string[], timingsFile: string | null, ceilingMs: n
 }
 
 const CPU_PRELOAD = join(import.meta.dir, 'suite-cpu-preload.ts')
+const READS_PRELOAD = join(import.meta.dir, 'suite-reads-preload.ts')
+const NO_PHASE: Phase = { code: 0, signal: null, stalled: false, out: '', timings: {}, cpuMs: 0 }
 
 const secs = (ms: number): string => `${(ms / 1000).toFixed(1)}s`
 
@@ -68,12 +82,30 @@ const secs = (ms: number): string => `${(ms / 1000).toFixed(1)}s`
 const phaseFiles = (phase: string[], rawArgs: string[]): string[] => phase.filter((a) => !a.startsWith('-') && !rawArgs.includes(a))
 const lastCount = (out: string, re: RegExp): number => Number([...out.matchAll(re)].at(-1)?.[1] ?? 0)
 
+/** what the selection carries from before the run to after it */
+type SelectCtx = { sel: Selecting | null; /** the suites that ran and passed, time included */ ran: string[]; tier: 'quick' | 'full'; /** every suite ran to its end, red or green: no phase stalled or was killed */ complete: boolean; /** what every phase printed */ out: string }
+
 export async function suiteCli(argv: string[]): Promise<number> {
+    const ctx: SelectCtx = { sel: null, ran: [], tier: 'quick', complete: false, out: '' }
+    try {
+        const code = await runSuites(argv, ctx)
+        if (ctx.sel != null) {
+            const problem = finishSelection(ctx.sel, ctx.ran, ctx.tier === 'full' && ctx.complete, ctx.out)
+            if (problem != null) console.log(problem)
+        }
+        return code
+    } finally {
+        if (ctx.sel != null) rmSync(ctx.sel.rec.file, { force: true })
+    }
+}
+
+async function runSuites(argv: string[], ctx: SelectCtx): Promise<number> {
     const t0 = Date.now()
     const parsed = parseSuiteFlags(argv)
     if (typeof parsed === 'string') { console.log(`FAIL: suite runner: ${parsed}`); return 2 }
     const { tests, rawArgs, declaredIn, unit } = parsed
     const tier = process.env[FULL_TESTS_ENV] === '1' ? 'full' : 'quick'
+    ctx.tier = tier
     const ceilingMs = parsed.ceilingMs ?? (tier === 'full' ? FULL_CEILING_MS : QUICK_CEILING_MS)
     const budget = tests.budgetMs ?? DEFAULT_BUDGET_MS
 
@@ -97,8 +129,9 @@ export async function suiteCli(argv: string[]): Promise<number> {
     // the pool is read, never taken: this process runs on its check's slot
     const cores = availableParallelism()
     const held = parallel ? poolOccupancy({ dir: poolDir(), size: parallelCap() }).held.length : 0
-    const workers = parallel ? poolWorkers({ cores, size: parallelCap(), held }) : undefined
-    const plan = planPhases({ tests, tier, rawArgs, parallel, noIsolate: helpText.includes('--no-isolate'), configIgnores: bunfig.ignores, workers })
+    const pool = parallel ? poolWorkers({ cores, size: parallelCap(), held }) : undefined
+    const plan = planPhases({ tests, tier, rawArgs, parallel, noIsolate: helpText.includes('--no-isolate'), configIgnores: bunfig.ignores, workers: pool })
+    const { workers } = plan
     const dir = mkdtempSync(join(tmpdir(), 'shipkit-suite-'))
     const tmp = join(dir, 'temp')
     mkdirSync(tmp)
@@ -115,8 +148,28 @@ export async function suiteCli(argv: string[]): Promise<number> {
         // the load BEFORE this run: read after it, the one minute average
         // carries this run's own parallel phase, which is no other process
         const load = machineLoad()
+        const picked = prepareSelection({ tests, tier, rawArgs, bunfig, unit, plan })
+        if (typeof picked === 'string') notes.push(picked)
+        else {
+            ctx.sel = picked
+            for (const n of picked.notes) console.log(n)
+            if (picked.picked != null && picked.picked.length === 0) {
+                for (const n of notes) console.log(n)
+                console.log(`ok: no suite reaches what changed since the last run (${picked.changed} path(s)), and every one passed then, so none ran`)
+                return 0
+            }
+        }
+        const rec = ctx.sel?.rec ?? null
+        const pickedSet = ctx.sel?.picked == null ? null : new Set(ctx.sel.picked)
+        const serialSet = new Set((tests.serial ?? []).map((x) => normSuitePath(x.file)))
+        const parallelArgs = pickedSet == null ? plan.parallel : [...plan.parallel, ...[...pickedSet].filter((f) => !serialSet.has(f)).map((f) => `./${f}`)]
+        const serialArgs = plan.serial == null || pickedSet == null ? plan.serial : (() => {
+            const files = [...serialSet].filter((f) => pickedSet.has(f))
+            return files.length === 0 ? null : [...plan.alone, ...files]
+        })()
+        const parallelEmpty = pickedSet != null && parallelArgs.length === plan.parallel.length
         const p1At = Date.now()
-        const p1 = await runPhase(plan.parallel, timed ? join(dir, 'parallel.json') : null, ceilingMs, tmp, true, cpuFile)
+        const p1 = parallelEmpty ? { ...NO_PHASE } : await runPhase(parallelArgs, timed ? join(dir, 'parallel.json') : null, ceilingMs, tmp, true, cpuFile, rec)
         const p1Ms = Date.now() - p1At
         // bun merges what it read into what it writes, so a suite deleted since
         // the last run is judged and kept only if the workers say it ran here
@@ -131,8 +184,11 @@ export async function suiteCli(argv: string[]): Promise<number> {
                 keepTimings(join(dir, 'parallel.json'), kept)
             }
         }
+        // the kept durations keep every suite for the next run's schedule,
+        // and only the picked ones ran here, so only they are judged
+        if (pickedSet != null) p1.timings = Object.fromEntries(Object.entries(p1.timings).filter(([f]) => pickedSet.has(normSuitePath(f))))
         const p2At = Date.now()
-        const p2 = plan.serial != null ? await runPhase(plan.serial, timed ? join(dir, 'serial.json') : null, ceilingMs, tmp) : null
+        const p2 = serialArgs != null ? await runPhase(serialArgs, timed ? join(dir, 'serial.json') : null, ceilingMs, tmp, true, null, rec) : null
         const p2Ms = p2 == null ? null : Date.now() - p2At
         const phases = [p1, ...(p2 != null ? [p2] : [])]
         const ran = phases.reduce((n, p) => n + lastCount(p.out, /Ran (\d+) tests?/g), 0)
@@ -150,7 +206,7 @@ export async function suiteCli(argv: string[]): Promise<number> {
         const { rerun, cleared: clearedInPhase } = aloneRunsNeeded(judged.over, parallelCpu, budget, load)
         const aloneAt = Date.now()
         for (const [i, t] of rerun.entries()) {
-            const run = await runPhase([...rawArgs, t.file], join(dir, `alone-${i}.json`), ceilingMs, tmp, false)
+            const run = await runPhase([...plan.alone, t.file], join(dir, `alone-${i}.json`), ceilingMs, tmp, false, null, rec)
             const wallMs = Object.entries(run.timings).find(([f]) => normSuitePath(f) === t.file)?.[1]
             if (wallMs != null) aloneRuns[t.file] = { wallMs, cpuMs: run.cpuMs }
         }
@@ -167,17 +223,21 @@ export async function suiteCli(argv: string[]): Promise<number> {
                 : null
         const crashed = crashedWorkers(p1.out)
         const killed = p1.stalled ? [] : crashed.map((c) => `killed by ${c.signal} while running ${c.file} (out of memory, or killed from outside)`)
-        const stalls = [stalledIn('the parallel phase', p1, crashed.map((c) => c.file)), stalledIn('the serial phase', p2, phaseFiles(plan.serial ?? [], rawArgs).filter((a) => p2?.timings[normSuitePath(a)] == null))]
+        const stalls = [stalledIn('the parallel phase', p1, crashed.map((c) => c.file)), stalledIn('the serial phase', p2, phaseFiles(serialArgs ?? [], rawArgs).filter((a) => p2?.timings[normSuitePath(a)] == null))]
         for (const line of stalls) if (line != null) killed.unshift(line)
         if (p1.signal != null) killed.push(`killed by ${p1.signal} during the parallel run (out of memory, or killed from outside)`)
         if (p2?.signal != null) {
-            const unfinished = phaseFiles(plan.serial ?? [], rawArgs).filter((a) => p2.timings[normSuitePath(a)] == null)
+            const unfinished = phaseFiles(serialArgs ?? [], rawArgs).filter((a) => p2.timings[normSuitePath(a)] == null)
             killed.push(`killed by ${p2.signal} while running ${unfinished.join(' or ')} (out of memory, or killed from outside)`)
         }
         // the record behind the hub's test files to fix: every suite this run
         // timed, with the alone timing where one was taken, and red when a
         // test in it failed or its worker died
         const red = new Set([...phases.flatMap((p) => failedSuites(p.out)), ...crashedWorkers(p1.out).map((c) => c.file)])
+        const overSet = new Set(over.map((o) => o.file))
+        ctx.complete = killed.length === 0
+        ctx.out = phases.map((p) => p.out).join('\n')
+        ctx.ran = Object.keys(timings).map(normSuitePath).filter((f) => !red.has(f) && !overSet.has(f))
         const at = Date.now()
         const alone = new Map([...over, ...cleared, ...clearedInPhase].map((t) => [t.file, t.ms]))
         const why = failLines(phases.map((p) => p.out).join('\n'))
@@ -227,12 +287,134 @@ export async function suiteCli(argv: string[]): Promise<number> {
         // the most actionable failure prints LAST, where the gate reads its headline
         for (const f of fails.slice(1).reverse()) console.log(f)
         if (fails.length > 0) { console.log(fails[0]); return 1 }
-        const serialCount = plan.serial != null ? phaseFiles(plan.serial, rawArgs).length : 0
-        console.log(`ok: Ran ${ran} tests across ${Object.keys(timings).length || '?'} suites, ${parallel ? `parallel on ${workers} workers` : 'one at a time'}${serialCount > 0 ? ` then ${serialCount} serial` : ''}, ${tier} tier${slowest}`)
+        const serialCount = serialArgs != null ? phaseFiles(serialArgs, rawArgs).length : 0
+        const chosen = ctx.sel?.picked != null ? `, the ${ctx.sel.picked.length} of ${ctx.sel.total} a change reaches` : ''
+        console.log(`ok: Ran ${ran} tests across ${Object.keys(timings).length || '?'} suites${chosen}, ${parallel ? `parallel on ${workers} workers` : 'one at a time'}${serialCount > 0 ? ` then ${serialCount} serial` : ''}, ${tier} tier${slowest}`)
         return 0
     } finally {
         rmSync(dir, { recursive: true, force: true })
     }
 }
 
+/** a selection in flight: the recorder's file, the state it started from,
+ *  the snapshot taken before the run, and the suites it picked (cwd
+ *  relative, null = every suite) */
+type Selecting = {
+    rec: Recording
+    statePath: string
+    state: SelectState
+    now: Record<string, string>
+    graph: Record<string, GraphEntry>
+    preloads: string[]
+    cwdRel: string
+    picked: string[] | null
+    /** when the snapshot was taken */
+    started: number
+    /** every suite of the run, repo-relative */
+    allSuites: string[]
+    total: number
+    changed: number
+    notes: string[]
+}
+
+/** a bun test argument that is neither a flag nor a flag's value: a path or
+ *  a filter the repo's own script names, which a selection would override */
+function positional(rawArgs: string[]): string | null {
+    for (let i = 0; i < rawArgs.length; i++) {
+        const a = rawArgs[i]!
+        if (a.startsWith('-')) {
+            if (!a.includes('=') && VALUE_FLAGS.includes(a)) i++
+            continue
+        }
+        return a
+    }
+    return null
+}
+const VALUE_FLAGS = ['--preload', '-r', '--env-file', '--timeout', '-t', '--test-name-pattern', '--path-ignore-patterns', '--reporter', '--reporter-outfile', '--coverage-dir', '--rerun-each', '--seed', '--max-concurrency', '--cwd', '--config', '-c', '--tsconfig-override', '--define', '-d', '--loader', '-l', '--jsx-factory', '--jsx-fragment', '--jsx-import-source', '--conditions', '--timings']
+
+/** the recorder's file and, in the quick tier, the suites a change since the
+ *  last green run reaches. A string says why nothing is recorded */
+function prepareSelection(o: { tests: TestsConfigLike; tier: 'quick' | 'full'; rawArgs: string[]; bunfig: BunfigTest; unit: string; plan: { parallel: string[] } }): Selecting | string {
+    const env = process.env[SUITE_SELECT_ENV]
+    if (env === '0') return `skip: suite selection (${SUITE_SELECT_ENV}=0): every suite runs`
+    if (o.tests.select !== true && env !== '1') return `skip: suite selection (tests.select is not true, ${SUITE_SELECT_ENV}=1 turns it on for one run): every suite runs`
+    // a run that filters tests by name passes suites it ran only in part: it can neither pick nor clear one
+    const filter = o.rawArgs.find((a) => /^(-t|--test-name-pattern|--only|--todo)(=|$)/.test(a))
+    if (filter != null) return `skip: suite selection (the run filters tests with ${filter}): every suite runs, and this run records nothing`
+    const g = gitRoot(process.cwd())
+    if (g == null) return 'skip: suite selection (not in a git work tree): every suite runs'
+    const top = g.top
+    const cwdRel = g.prefix.replace(/\/$/, '')
+    const notes: string[] = []
+    const t0 = performance.now()
+    try {
+        const statePath = selectStatePath(top, o.unit)
+        const state = loadState(statePath)
+        const cfg = loadConfig(top)
+        const ignores = [
+            ...o.bunfig.ignores,
+            ...o.plan.parallel.filter((a) => a.startsWith('--path-ignore-patterns=')).map((a) => a.slice('--path-ignore-patterns='.length)),
+        ]
+        const suites = suiteFiles(top, cwdRel, o.bunfig.root, ignores, isBunSuite)
+        const toTop = (f: string): string => (cwdRel === '' ? f : `${cwdRel}/${f}`)
+        const bunfigText = existsSync('bunfig.toml') ? readFileSync('bunfig.toml', 'utf8') : null
+        const preloads = preloadsOf(bunfigText, o.rawArgs, cwdRel)
+        const loads = Object.values(state.modules).flatMap((m) => m.l ?? [])
+        const graph = walkGraph(cfg, [...suites.map(toTop), ...preloads, ...loads], state.graph)
+        const started = Date.now()
+        const now = snapshot(top, state.modules)
+        const rec: Recording = { file: join(tmpdir(), `shipkit-reads-${process.pid}-${Date.now()}.tsv`), top }
+        const base = { rec, statePath, state, now, started, graph, preloads, cwdRel, allSuites: suites.map(toTop), total: suites.length, notes, changed: 0 }
+        if (o.tier !== 'quick') return { ...base, picked: null }
+        const pos = positional(o.rawArgs)
+        if (pos != null) { notes.push(`note: every suite runs: the test script names ${pos}, which a selection would override`); return { ...base, picked: null } }
+        if (state.base == null) { notes.push('note: every suite runs: no run recorded yet, the next run selects'); return { ...base, picked: null } }
+        const changed = changedKeys(state.base, now)
+        if (state.bun !== Bun.version) { notes.push(`note: every suite runs: bun ${Bun.version} ran no recorded run yet`); return { ...base, picked: null } }
+        const roots = [...new Set([...cfg.roots, posix.normalize(posix.join(cwdRel, o.bunfig.root ?? '.')), ...preloads.map((p) => posix.dirname(p))])]
+        const sel: Selection = selectSuites({ suites: suites.map(toTop), preloads, envFiles: envFilesOf(o.rawArgs, cwdRel), graph, modules: state.modules, recorded: new Set(state.recorded), dirty: new Set(state.dirty), changed, roots })
+        if (sel.all) { notes.push(`note: every suite runs: ${sel.why}`); return { ...base, picked: null, changed: changed.size } }
+        const fromTop = (f: string): string => (cwdRel === '' ? f : f.slice(cwdRel.length + 1))
+        const picked = sel.run.map(fromTop)
+        const reasons = [...new Set(sel.why.values())]
+        if (picked.length > 0) notes.push(`note: ${picked.length} of ${suites.length} suites reach what changed since the last run (${changed.size} path(s)), or did not pass then, picked in ${Math.round(performance.now() - t0)}ms: ${reasons.slice(0, 3).join('; ')}${reasons.length > 3 ? `; ${reasons.length - 3} more` : ''}`)
+        return { ...base, picked, changed: changed.size }
+    } catch (e) {
+        return `WARN: suite selection failed, so every suite runs: ${e instanceof Error ? e.message : String(e)}`
+    }
+}
+
+type TestsConfigLike = { select?: boolean }
+
+/** what a run leaves for the next: the reads it recorded, the snapshot it
+ *  started from, and the suites it picked that did not pass. A full run where
+ *  every suite ran to its end saw every read, so it replaces the reads
+ *  instead of adding to them: a quick run sees only the paths its suites took */
+function finishSelection(sel: Selecting, passed: string[], replace: boolean, out: string): string | null {
+    try {
+        const text = existsSync(sel.rec.file) ? readFileSync(sel.rec.file, 'utf8') : ''
+        const modules = dropStaticEdges(foldReads(replace ? {} : sel.state.modules, text), sel.graph)
+        const toTop = (f: string): string => (sel.cwdRel === '' ? f : `${sel.cwdRel}/${f}`)
+        const ok = new Set(passed.map(toTop))
+        const recorded = [...new Set([...(replace ? [] : sel.state.recorded), ...ok])].sort()
+        // a suite this run picked and did not see pass stays dirty; with no
+        // pick, every suite was picked. One the run did not pick keeps its state
+        const picked = sel.picked == null ? sel.allSuites : sel.picked.map(toTop)
+        const before = sel.picked == null ? [] : sel.state.dirty.filter((d) => !picked.includes(d))
+        // a module that threw while loading loads silently in the next file of
+        // a worker that shares its modules, so a suite reaching it is not
+        // trusted green, whatever bun said of it
+        const thrown = loadErrorModules(out, sel.rec.top)
+        const tainted = taintedSuites(picked, thrown, sel.graph, modules, sel.preloads)
+        const dirty = [...new Set([...before, ...picked.filter((s) => !ok.has(s) || tainted.has(s))])].sort()
+        // a read first recorded by this run joins the snapshot it started from,
+        // unless its path moved since the start
+        const base = { ...sel.now, ...extras(sel.rec.top, modules, sel.now, sel.started) }
+        saveState(sel.statePath, { ...sel.state, base, dirty, modules, recorded, graph: sel.graph, bun: Bun.version })
+        return null
+    } catch (e) {
+        return `WARN: suite selection could not keep this run (${e instanceof Error ? e.message : String(e)}), so the next run selects from the last one`
+    }
+}
+
 if (import.meta.main) process.exit(await suiteCli(process.argv.slice(2)))

package/src/suite/suite-reads-preload.ts

@@ -0,0 +1,335 @@
+// WHAT EACH MODULE READ, preloaded into every test worker and every bun
+// process a suite spawns. The quick tier runs only the suites whose reads
+// changed since the last green run (select.ts), and a module's static imports
+// are only part of what it reads: a suite also reads files by path, lists
+// dirs, globs and spawns. This preload records each of those, attributed to
+// every module of the repo on the call stack. A memo filled by one suite and
+// used by the next is still charged to the module that holds it, and every
+// suite whose import closure holds that module depends on the read.
+//
+// Lines, appended to the file SHIPKIT_SUITE_READS names: `<kind>\t<module>\t<path>`.
+//   r  a file read, probed or stat'ed (its content, or its absence, matters)
+//   d  a dir listed (its names matter)
+//   g  a tree walked by a glob (every name under it matters)
+//   o  a process spawned that reads what nobody records (git or a shell run
+//      in the repo): the module is opaque, and every suite that reaches it
+//      runs every time
+//   l  a repo module loaded at runtime from a call this module was on the
+//      stack of (a require or an import() in a function body)
+//   L  a repo module loaded while this module itself was being loaded
+// A read with no repo frame on its stack is charged to `-`, which every suite
+// depends on. A bun child records under the module that spawned it.
+//
+// node:fs is replaced through bun:test's mock.module, the one hook that also
+// reaches a named ESM import, and it updates modules imported before it.
+import { mock, afterAll } from 'bun:test'
+import * as fsLive from 'node:fs'
+import * as fspLive from 'node:fs/promises'
+import * as cpLive from 'node:child_process'
+import { appendFileSync, realpathSync } from 'node:fs'
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { SUITE_OWNER_ENV, SUITE_READS_ENV, SUITE_ROOT_ENV } from './reads-env.ts'
+
+const out = process.env[SUITE_READS_ENV]
+const root = process.env[SUITE_ROOT_ENV]
+const owner = process.env[SUITE_OWNER_ENV]
+const SELF = import.meta.path
+
+if (out != null && out !== '' && root != null && root !== '') install(out, resolve(root))
+
+function install(outFile: string, rootDir: string): void {
+    const realFs = { ...fsLive } as Record<string, unknown>
+    const realFsp = { ...fspLive } as Record<string, unknown>
+    const realCp = { ...cpLive } as Record<string, unknown>
+    // the root as git prints it is a realpath, and a path a module names can
+    // go through a symlink to it (macOS: /var is /private/var), so each
+    // spelling of the root counts
+    const real = ((): string => { try { return realpathSync(rootDir) } catch { return rootDir } })()
+    const roots = [...new Set([rootDir, real, ...[rootDir, real].filter((r) => r.startsWith('/private/')).map((r) => r.slice('/private'.length))])]
+    const seen = new Set<string>()
+    let buf: string[] = []
+
+    /** repo-relative posix path, null outside the repo, in an install, or in git's own dir */
+    const rel = (p: unknown): string | null => {
+        let s: string
+        if (typeof p === 'string') s = p
+        else if (p instanceof URL) { if (p.protocol !== 'file:') return null; s = fileURLToPath(p) }
+        else if (p instanceof Uint8Array) s = Buffer.from(p).toString()
+        else return null
+        if (s.startsWith('file:')) { try { s = fileURLToPath(s) } catch { return null } }
+        const abs = isAbsolute(s) ? resolve(s) : resolve(process.cwd(), s)
+        const base = roots.find((r) => abs === r || abs.startsWith(r.endsWith(sep) ? r : `${r}${sep}`))
+        if (base == null) return null
+        const r = relative(base, abs).split(sep).join('/')
+        if (r === '' ) return '.'
+        if (r === 'node_modules' || r.startsWith('node_modules/') || r.includes('/node_modules/')) return null
+        return r
+    }
+    /** the innermost repo module on the stack, outside this file */
+    // a read is charged to EVERY repo module on the stack: the one that read
+    // it, the ones that hold a memo of what it read, and the one that asked. A
+    // cache a preload installs is asked through the module that holds its
+    // hook, and every suite reusing the memo calls that module again
+    const callers = (): string[] => {
+        if (owner != null && owner !== '') return [owner]
+        const limit = Error.stackTraceLimit
+        Error.stackTraceLimit = 80
+        const stack = new Error().stack ?? ''
+        Error.stackTraceLimit = limit
+        const out: string[] = []
+        for (const line of stack.split('\n')) {
+            const m = /\(?((?:\/|[A-Za-z]:\\)[^():]+):\d+:\d+\)?\s*$/.exec(line)
+            const file = m?.[1]
+            if (file == null || file === SELF) continue
+            const r = rel(file)
+            if (r != null && r !== '.' && !out.includes(r)) out.push(r)
+        }
+        return out.length > 0 ? out : ['-']
+    }
+    /** the module a child records under: the innermost one that spawned it */
+    const caller = (): string => callers()[0]!
+    /** a read through a symlink reads its target too */
+    const target = (path: string): string | null => {
+        try {
+            const real = rel((realFs['realpathSync'] as (p: string) => string)(join(rootDir, path)))
+            return real != null && real !== path ? real : null
+        } catch {
+            return null
+        }
+    }
+    const note = (kind: string, path: string | null, mods: string | string[] = callers()): void => {
+        if (path == null) return
+        if (kind !== 'o') {
+            const t = target(path)
+            if (t != null) note(kind, t, mods)
+        }
+        for (const mod of typeof mods === 'string' ? [mods] : mods) {
+            const line = `${kind}\t${mod}\t${path}`
+            if (seen.has(line)) continue
+            seen.add(line)
+            buf.push(line)
+        }
+    }
+    const flush = (): void => {
+        if (buf.length === 0) return
+        try { appendFileSync(outFile, `${buf.join('\n')}\n`) } catch { /* no record: the next full run fills it */ }
+        buf = []
+    }
+
+    const READS = ['readFileSync', 'readFile', 'existsSync', 'exists', 'statSync', 'stat', 'lstatSync', 'lstat', 'accessSync', 'access', 'openSync', 'open', 'createReadStream', 'readlinkSync', 'readlink', 'realpathSync', 'realpath', 'opendirSync', 'opendir', 'copyFileSync', 'copyFile', 'watchFile', 'statfsSync', 'statfs']
+    // a copy or a watch of a dir takes the whole tree under it
+    const TREES = ['cpSync', 'cp', 'watch']
+    const LISTS = ['readdirSync', 'readdir']
+    const GLOBS = ['globSync', 'glob']
+    const wrap = (real: Record<string, unknown>, kind: string, names: string[]): Record<string, unknown> => {
+        const shim: Record<string, unknown> = {}
+        for (const n of names) {
+            const f = real[n]
+            if (typeof f !== 'function') continue
+            const g = function (this: unknown, ...a: unknown[]): unknown {
+                if (kind === 'g') note('g', globRoot(a[0], a[1]))
+                else if (kind === 't') {
+                    const r = rel(a[0])
+                    note(r != null && exists(join(rootDir, r), false) ? 'r' : 'g', r)
+                }
+                else {
+                    const r = rel(a[0])
+                    // a recursive listing is a walk of the whole tree
+                    const recursive = kind === 'd' && typeof a[1] === 'object' && a[1] != null && (a[1] as { recursive?: unknown }).recursive === true
+                    note(recursive ? 'g' : n.startsWith('opendir') ? 'd' : kind, r)
+                }
+                return (f as (...x: unknown[]) => unknown).apply(this, a)
+            }
+            Object.assign(g, f)
+            shim[n] = g
+        }
+        return shim
+    }
+    const globRoot = (pattern: unknown, opts: unknown): string | null => {
+        const pats = Array.isArray(pattern) ? pattern : [pattern]
+        const cwd = typeof opts === 'object' && opts != null && typeof (opts as { cwd?: unknown }).cwd === 'string' ? (opts as { cwd: string }).cwd : process.cwd()
+        const roots = pats.filter((p): p is string => typeof p === 'string').map((p) => {
+            const lit = p.split('/').filter((_, i, a) => !/[*?[{]/.test(a.slice(0, i + 1).join('/'))).join('/')
+            return rel(join(cwd, lit))
+        })
+        return roots.length === 1 ? roots[0]! : rel(cwd)
+    }
+    const fsShim: Record<string, unknown> = { ...realFs, ...wrap(realFs, 'r', READS), ...wrap(realFs, 'd', LISTS), ...wrap(realFs, 'g', GLOBS), ...wrap(realFs, 't', TREES) }
+    const fspShim: Record<string, unknown> = { ...realFsp, ...wrap(realFsp, 'r', READS), ...wrap(realFsp, 'd', LISTS), ...wrap(realFsp, 'g', GLOBS), ...wrap(realFsp, 't', TREES) }
+    fsShim['promises'] = fspShim
+    mock.module('node:fs', () => ({ ...fsShim, default: fsShim }))
+    mock.module('fs', () => ({ ...fsShim, default: fsShim }))
+    mock.module('node:fs/promises', () => ({ ...fspShim, default: fspShim }))
+    mock.module('fs/promises', () => ({ ...fspShim, default: fspShim }))
+
+    // a bun child runs this same preload and records under the spawning module.
+    // Any other child reads what nobody records
+    /** a path that stands there (a file, or a dir when `dir`) */
+    const exists = (abs: string, dir: boolean): boolean => {
+        try {
+            const st = (realFs['statSync'] as (p: string) => { isFile(): boolean; isDirectory(): boolean })(abs)
+            return st.isFile() || (dir && st.isDirectory())
+        } catch { return false }
+    }
+    const SHELLS = new Set(['sh', 'bash', 'zsh', 'dash', 'fish', 'env', 'xargs', 'nice', 'time', 'timeout'])
+    // tools that read only the files their arguments name, nothing they find through them
+    const FILE_TOOLS = new Set(['true', 'false', 'echo', 'sleep', 'kill', 'rm', 'mkdir', 'touch', 'cwebp', 'dwebp'])
+    const isBun = (bin: unknown): boolean => typeof bin === 'string' && (bin === 'bun' || bin === process.execPath || /(^|\/)bun$/.test(bin))
+    const childEnv = (env: unknown): Record<string, string | undefined> => {
+        const base = (typeof env === 'object' && env != null ? env : process.env) as Record<string, string | undefined>
+        const opts = base['BUN_OPTIONS'] ?? ''
+        return {
+            ...base,
+            [SUITE_READS_ENV]: outFile,
+            [SUITE_ROOT_ENV]: rootDir,
+            [SUITE_OWNER_ENV]: caller(),
+            BUN_OPTIONS: opts.includes(SELF) ? opts : `${opts} --preload=${SELF}`.trim(),
+        }
+    }
+    // a child that is not bun reads what nobody records. It is trusted only
+    // when it runs outside the repo and names nothing in it (git in a temp
+    // repo); a tool known to read only the files it names (cwebp) records
+    // them; any other child in or about the repo makes its module opaque
+    const spawned = (cmd: unknown, cwdOpt: unknown): void => {
+        const argv = (Array.isArray(cmd) ? cmd : typeof cmd === 'string' ? [cmd] : []).map(String)
+        if (isBun(argv[0])) return
+        const tool = (argv[0] ?? '?').split('/').pop() ?? '?'
+        const cwd = typeof cwdOpt === 'string' ? resolve(cwdOpt) : cwdOpt instanceof URL ? fileURLToPath(cwdOpt) : process.cwd()
+        const shell = SHELLS.has(tool)
+        const words = argv.slice(1).flatMap((a) => (shell ? a.split(/[\s;&|<>()'"`=]+/) : [a.replace(/^--?[\w-]+=/, '')])).filter((w) => w !== '' && !w.startsWith('-'))
+        const inRepo: string[] = []
+        for (const w of words) {
+            const abs = isAbsolute(w) ? w : join(cwd, w)
+            if (!isAbsolute(w) && !w.includes('/') && !exists(abs, true)) continue
+            const r = rel(abs)
+            if (r != null) inRepo.push(r)
+        }
+        // a tool known to read only the files it names records them; any other
+        // tool is trusted only far from the repo: run outside it, naming nothing in it
+        if (!shell && FILE_TOOLS.has(tool)) {
+            for (const r of inRepo) note(exists(join(rootDir, r), false) ? 'r' : 'g', r)
+            return
+        }
+        if (rel(cwd) != null || inRepo.length > 0) note('o', tool)
+    }
+    const realSpawn = Bun.spawn
+    const realSpawnSync = Bun.spawnSync
+    const viaBun = (real: typeof Bun.spawn | typeof Bun.spawnSync) => function (this: unknown, ...a: unknown[]): unknown {
+        const first = a[0]
+        const cmd = Array.isArray(first) ? first : (first as { cmd?: unknown } | undefined)?.cmd
+        spawned(cmd, ((Array.isArray(first) ? a[1] : first) as { cwd?: unknown } | undefined)?.cwd)
+        if (Array.isArray(first)) {
+            const opts = (a[1] ?? {}) as { env?: unknown }
+            return (real as (...x: unknown[]) => unknown).call(this, first, { ...opts, env: childEnv(opts.env) })
+        }
+        const opts = (first ?? {}) as { env?: unknown }
+        return (real as (...x: unknown[]) => unknown).call(this, { ...opts, env: childEnv(opts.env) })
+    }
+    Bun.spawn = viaBun(realSpawn) as typeof Bun.spawn
+    Bun.spawnSync = viaBun(realSpawnSync) as typeof Bun.spawnSync
+    const cpWrap = (n: string, cmdAt: (a: unknown[]) => unknown, optsAt: number | ((a: unknown[]) => number)): unknown => {
+        const f = realCp[n]
+        if (typeof f !== 'function') return f
+        return function (this: unknown, ...a: unknown[]): unknown {
+            const cmd = cmdAt(a)
+            const i = typeof optsAt === 'number' ? optsAt : optsAt(a)
+            const opts = (typeof a[i] === 'object' && a[i] != null && !Array.isArray(a[i]) ? a[i] : {}) as { env?: unknown; cwd?: unknown }
+            if (n === 'exec' || n === 'execSync') spawned(['sh', '-c', cmd], opts.cwd)
+            else spawned([cmd, ...(Array.isArray(a[1]) ? a[1] : [])], opts.cwd)
+            const args = [...a]
+            while (args.length < i) args.push(undefined)
+            args[i] = { ...opts, env: childEnv(opts.env) }
+            return (f as (...x: unknown[]) => unknown).apply(this, args)
+        }
+    }
+    const withArgs = (a: unknown[]): number => (Array.isArray(a[1]) ? 2 : 1)
+    const cpShim: Record<string, unknown> = {
+        ...realCp,
+        spawn: cpWrap('spawn', (a) => a[0], withArgs),
+        spawnSync: cpWrap('spawnSync', (a) => a[0], withArgs),
+        execFile: cpWrap('execFile', (a) => a[0], withArgs),
+        execFileSync: cpWrap('execFileSync', (a) => a[0], withArgs),
+        exec: cpWrap('exec', (a) => a[0], 1),
+        execSync: cpWrap('execSync', (a) => a[0], 1),
+        fork: cpWrap('fork', () => 'bun', withArgs),
+    }
+    mock.module('node:child_process', () => ({ ...cpShim, default: cpShim }))
+    mock.module('child_process', () => ({ ...cpShim, default: cpShim }))
+    const realShell = Bun.$
+    Bun.$ = new Proxy(realShell, { apply: (t, self, a) => { note('o', 'sh'); return Reflect.apply(t, self, a) } })
+
+    // a file:// fetch is a read; a Worker runs code no preload of ours sees
+    const realFetch = globalThis.fetch
+    globalThis.fetch = Object.assign(function (this: unknown, input: unknown, init?: unknown): unknown {
+        const url = typeof input === 'string' ? input : input instanceof URL ? input.href : (input as { url?: unknown } | null)?.url
+        if (typeof url === 'string' && url.startsWith('file:')) note('r', rel(url))
+        return (realFetch as (...x: unknown[]) => unknown).call(this, input, init)
+    }, realFetch) as typeof fetch
+    for (const name of ['Worker', 'SharedWorker']) {
+        const Real = (globalThis as Record<string, unknown>)[name] as (new (...a: unknown[]) => object) | undefined
+        if (typeof Real !== 'function') continue
+        const Wrapped = function (this: unknown, ...a: unknown[]): object {
+            note('o', name.toLowerCase())
+            return new Real(...a)
+        } as unknown as typeof Real
+        Wrapped.prototype = Real.prototype
+        ;(globalThis as Record<string, unknown>)[name] = Wrapped
+    }
+
+    const realFile = Bun.file
+    Bun.file = function (this: unknown, p: unknown, o?: unknown): unknown {
+        note('r', rel(p))
+        return (realFile as (...x: unknown[]) => unknown).call(this, p, o)
+    } as typeof Bun.file
+    // a Glob keeps no pattern a caller can read, so each one remembers its own:
+    // the walked tree is the cwd joined with the pattern's literal head
+    const RealGlob = Bun.Glob
+    const patterns = new WeakMap<object, string>()
+    const Glob = function (this: unknown, pattern: string): unknown {
+        const g = new RealGlob(pattern)
+        patterns.set(g, pattern)
+        return g
+    } as unknown as typeof Bun.Glob
+    Glob.prototype = RealGlob.prototype
+    Bun.Glob = Glob
+    const G = RealGlob.prototype as unknown as Record<string, (...a: unknown[]) => unknown>
+    for (const n of ['scan', 'scanSync']) {
+        const f = G[n]
+        if (typeof f !== 'function') continue
+        G[n] = function (this: object, opts?: unknown): unknown {
+            const cwd = typeof opts === 'string' ? opts : typeof opts === 'object' && opts != null && typeof (opts as { cwd?: unknown }).cwd === 'string' ? (opts as { cwd: string }).cwd : process.cwd()
+            note('g', globRoot(patterns.get(this) ?? '**', { cwd }))
+            return f.call(this, opts)
+        }
+    }
+
+    // every import resolved at runtime, as an edge from its importer and from
+    // every module on the stack: a module a computed import loads is in no
+    // static closure, and the edge charges it wherever the load was asked
+    // from, whichever suite ran first. A key already seen asks nothing again
+    const edges = new Set<string>()
+    const imported = (spec: string, importer: string | undefined): void => {
+        if (importer == null || importer === '' || spec.startsWith('node:') || spec.startsWith('bun:')) return
+        const from = rel(importer)
+        if (from == null || from === '.') return
+        const key = `${from}\0${spec}\0${new Error().stack ?? ''}`
+        if (edges.has(key)) return
+        edges.add(key)
+        const bare = spec.replace(/\?.*$/, '')
+        const base = isAbsolute(bare) ? bare : bare.startsWith('.') ? join(importer, '..', bare) : join(rootDir, bare)
+        const abs = [base, `${base}.ts`, `${base}.tsx`, join(base, 'index.ts')].find((x) => exists(x, false))
+        if (abs == null) return
+        const to = rel(abs)
+        // charged like a read: a lazy load inside a hook a preload installed
+        // is reached through the modules that called the hook
+        if (to == null || to === from) return
+        const asked = callers().filter((c) => c !== from && c !== '-')
+        if (asked.length === 0) note('L', to, from)
+        else note('l', to, [from, ...asked])
+    }
+    Bun.plugin({ name: 'shipkit-suite-reads', setup(b) { b.onResolve({ filter: /.*/ }, (a) => { imported(a.path, a.importer); return undefined }) } })
+
+    try { afterAll(flush) } catch { /* not under bun test: the exit hook below records it */ }
+    process.on('exit', flush)
+}