rvlib-shipkit 1.7.0 → 1.9.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, interruptedSuites, overWords, ranAs, retryAlone, smallerRun, stallWords, 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,14 +184,19 @@ 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)
         const failedTests = phases.reduce((n, p) => n + lastCount(p.out, /^\s*(\d+) fail$/gm), 0)
         const timings = Object.assign({}, ...phases.map((p) => p.timings)) as Record<string, number>
-        const judged = judgeSuites({ timings, tests, tier })
+        const crashed = crashedWorkers(p1.out)
+        const red = new Set([...phases.flatMap((p) => failedSuites(p.out)), ...crashed.map((c) => c.file)])
+        const judged = judgeSuites({ timings, tests, tier, red: [...red] })
         const slowest = judged.slowest.length > 0 ? ` (slowest: ${judged.slowest.map((t) => `${t.file} ${secs(t.ms)}`).join(', ')})` : ''
 
         // a parallel timing carries every other suite's load, so a suspect
@@ -149,10 +207,20 @@ export async function suiteCli(argv: string[]): Promise<number> {
         const parallelCpu = phaseCpu.cpu
         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 runAlone = async (t: { file: string }, name: string): Promise<AloneRun | null> => {
+            const run = await runPhase([...plan.alone, t.file], join(dir, `${name}.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 }
+            return wallMs == null ? null : { wallMs, cpuMs: run.cpuMs }
+        }
+        for (const [i, t] of rerun.entries()) {
+            const first = await runAlone(t, `alone-${i}`)
+            if (first == null) continue
+            aloneRuns[t.file] = first
+            if (!retryAlone(t, first, budget, load)) continue
+            const second = await runAlone(t, `alone-${i}-again`)
+            if (second == null) continue
+            aloneRuns[t.file] = smallerRun(first, second)
+            notes.push(`note: ${t.file} ran alone twice, ${secs(first.cpuMs ?? first.wallMs)} then ${secs(second.cpuMs ?? second.wallMs)} of CPU, and the smaller stands: a lone run the scheduler spills onto slower cores burns more CPU for the same work`)
         }
         const aloneMs = Date.now() - aloneAt
         const { over, cleared } = rerun.length > 0 ? confirmOver(rerun, aloneRuns, budget, load) : { over: [], cleared: [] }
@@ -162,26 +230,26 @@ export async function suiteCli(argv: string[]): Promise<number> {
         // a ceiling kill makes bun report every worker it held as crashed, and
         // those are the suites that never finished, not an outside kill
         const stalledIn = (name: string, p: Phase | null, files: string[]): string | null =>
-            p?.stalled === true
-                ? `${name} ran past its ${secs(ceilingMs)} ceiling and was killed${files.length > 0 ? ` with ${files.join(', ')} still running` : ''}: a test worker stopped answering, most likely stuck in a synchronous call, which no per test timeout can interrupt`
-                : null
-        const crashed = crashedWorkers(p1.out)
+            p?.stalled === true ? stallWords(name, ceilingMs, [...new Set([...files, ...interruptedSuites(p.out)])]) : null
         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).map(normSuitePath))]
         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'))
-        for (const c of crashedWorkers(p1.out)) if (!why.has(c.file)) why.set(c.file, `its worker crashed: ${c.signal}`)
+        for (const c of crashed) if (!why.has(c.file)) why.set(c.file, `its worker crashed: ${c.signal}`)
         // which phase timed each file, and the CPU spent on it: an alone
         // rerun, the parallel phase's own figure, or a phase that ran that one file
         const phaseOf = (f: string): SuitePhase => (p2 != null && Object.keys(p2.timings).some((k) => normSuitePath(k) === f) ? 'serial' : parallel ? 'parallel' : 'sequential')
@@ -227,12 +295,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, ${ranAs(plan.parallel, rawArgs)}${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)))