rvlib-shipkit 0.38.0 → 1.0.0

package/src/suite/judge-suites.ts

@@ -4,6 +4,7 @@
 import { isAbsolute, posix } from 'path'
 
 export type SlowSuite = {
+    /** the suite path, relative to the repo root (or to the unit dir inside `units[]`) */
     file: string
     /** what this suite catches that no fast test can */
     catches: string
@@ -11,12 +12,13 @@ export type SlowSuite = {
     whyNotFast: string
 }
 export type SerialSuite = {
+    /** the suite path, relative to the repo root (or to the unit dir inside `units[]`) */
     file: string
     /** what breaks when it shares a run with other suites */
     why: string
 }
 export type TestsConfig = {
-    /** per suite wall time in the quick tier (default 2000). A suite over it under the parallel run is timed again alone, and only that timing fails it. The full tier fails nothing on time */
+    /** per suite time in the quick tier (default 2000). A suite whose wall time goes over it under the parallel run is run again alone, and fails when that run burns more CPU than this, or waits more than twice this while the machine is idle. A suite whose CPU inside the parallel run, children included, plus all its worker burned before it stays under it skips that run, unless it may wait on an idle machine or ended with a child not yet reaped. The full tier fails nothing on time */
     budgetMs?: number
     /** suites that break the budget on purpose: the full tier runs them, the quick tier does not */
     slow?: SlowSuite[]
@@ -25,14 +27,47 @@ export type TestsConfig = {
 }
 
 export const DEFAULT_BUDGET_MS = 2000
+
+/** what a FULL tier run gives each test. Its suites build real repositories
+ *  and spawn whole gates, and the same file has finished in 6.8s and in 21.3s
+ *  on identical code depending on what else was running, so bun's 5s default
+ *  turns machine load into a red release gate.
+ *
+ *  It rides on the COMMAND LINE because nothing else can carry it: a preload
+ *  calling setDefaultTimeout raises the ceiling for the FIRST file of a run
+ *  and for nothing after it, which left 106 of this repo's 107 suites at the
+ *  5s default while the preload said otherwise. */
+export const FULL_TIMEOUT_MS = 120_000
+/** the wall ceiling of one `bun test` phase. bun's per test timeout never
+ *  fires on a worker stuck in a SYNCHRONOUS call, and bun's spawnSync has been
+ *  seen spinning on a child that already exited (planPhases avoids the known
+ *  trigger), so without this a hang lasts until something outside kills it. The quick
+ *  tier answers in seconds, so two minutes is far from any real run. */
+export const QUICK_CEILING_MS = 120_000
+/** the full tier runs every suite one after the other, about three minutes */
+export const FULL_CEILING_MS = 1_800_000
 const TESTS_KEYS = ['budgetMs', 'slow', 'serial']
 const SLOW_KEYS = ['file', 'catches', 'whyNotFast']
 const SERIAL_KEYS = ['file', 'why']
+const OWN_FLAGS = ['--budget-ms', '--slow', '--serial', '--declared-in', '--ceiling-ms', '--unit']
 
 export const normSuitePath = (file: string): string => posix.normalize(file.replace(/\\/g, '/')).replace(/^\.\//, '')
 
 /** the arguments after `bun test`, or null when a shell would interpret the script
  *  (cd, env prefix, pipes, quotes, substitution): that body stays the repo's own */
+export type BunfigTest = { root: string | null; ignores: string[]; error: string | null }
+
+/** the `[test]` table of a bunfig.toml: where discovery starts, and what it skips */
+export function bunfigTest(text: string | null): BunfigTest {
+    if (text == null) return { root: null, ignores: [], error: null }
+    let parsed: { test?: { root?: unknown; pathIgnorePatterns?: unknown } }
+    try { parsed = Bun.TOML.parse(text) as typeof parsed } catch (e) { return { root: null, ignores: [], error: `bunfig.toml is unparseable (${String(e).slice(0, 120)})` } }
+    const t = parsed.test ?? {}
+    const raw = t.pathIgnorePatterns
+    const ignores = typeof raw === 'string' ? [raw] : Array.isArray(raw) ? raw.filter((x): x is string => typeof x === 'string') : []
+    return { root: typeof t.root === 'string' ? normSuitePath(t.root) : null, ignores, error: null }
+}
+
 export function parseBunTestScript(script: string): string[] | null {
     const s = script.trim()
     if (!/^bun test(\s|$)/.test(s)) return null
@@ -54,38 +89,78 @@ export function suiteFlags(t: TestsConfig | undefined): string[] {
 
 /** the inverse of suiteFlags, plus where the declarations live (printed in
  *  every fix line) and the `bun test` arguments after `--` */
-export function parseSuiteFlags(argv: string[]): { tests: TestsConfig; rawArgs: string[]; declaredIn: string } | string {
+export function parseSuiteFlags(argv: string[]): { tests: TestsConfig; rawArgs: string[]; declaredIn: string; ceilingMs: number | null; unit: string } | string {
     const tests: Required<TestsConfig> = { budgetMs: DEFAULT_BUDGET_MS, slow: [], serial: [] }
     let declaredIn = 'repo.config.ts tests'
+    let ceilingMs: number | null = null
+    let unit = ''
+    // the runner's own flags end at `--` OR at the first token that is not one
+    // of them: bun swallows a LEADING `--`, so a repo with no declaration hands
+    // over the `bun test` arguments with no separator at all
     let i = 0
-    for (; i < argv.length && argv[i] !== '--'; i++) {
+    for (; i < argv.length; i += 2) {
         const flag = argv[i]!
+        if (flag === '--') { i++; break }
+        if (!OWN_FLAGS.includes(flag)) break
         const value = argv[i + 1]
         if (value == null || value === '--') return `${flag} needs a value`
-        i++
         if (flag === '--budget-ms') tests.budgetMs = Number(value)
         else if (flag === '--slow') tests.slow.push({ file: value, catches: '(declared)', whyNotFast: '(declared)' })
         else if (flag === '--serial') tests.serial.push({ file: value, why: '(declared)' })
-        else if (flag === '--declared-in') declaredIn = value
-        else return `unknown flag ${flag}`
+        else if (flag === '--ceiling-ms') ceilingMs = Number(value)
+        else if (flag === '--unit') unit = value
+        else declaredIn = value
     }
     if (!(tests.budgetMs > 0)) return '--budget-ms must be a positive number'
-    return { tests, rawArgs: argv.slice(i + 1), declaredIn }
+    if (ceilingMs != null && !(ceilingMs > 0)) return '--ceiling-ms must be a positive number'
+    return { tests, rawArgs: argv.slice(i), declaredIn, ceilingMs, unit }
 }
 
 /** what `bun test` receives in each phase. The serial phase names its files
- *  explicitly, because bun reports no tests when a path is both named and ignored */
-export function planPhases(p: { tests: TestsConfig; tier: 'quick' | 'full'; rawArgs: string[]; parallel: boolean }): { parallel: string[]; serial: string[] | null } {
+ *  explicitly, because bun reports no tests when a path is both named and ignored.
+ *
+ *  `noIsolate` (the bun in use knows `--no-isolate`): the parallel phase keeps
+ *  one global per worker, as a plain `bun test` and the serial phase always
+ *  did. `--parallel` implies per file isolation, and under it a worker's
+ *  spawnSync can spin forever on a child that already exited (bun issue
+ *  34069), which hung one full run in eight. A repo that passes `--isolate`
+ *  itself keeps it. */
+export function planPhases(p: { tests: TestsConfig; tier: 'quick' | 'full'; rawArgs: string[]; parallel: boolean; noIsolate?: boolean; configIgnores?: string[]; workers?: number }): { parallel: string[]; serial: string[] | null } {
     const slow = (p.tests.slow ?? []).map((s) => normSuitePath(s.file))
     const serial = (p.tests.serial ?? []).map((s) => normSuitePath(s.file))
-    const ignored = [...new Set([...(p.tier === 'quick' ? slow : []), ...serial])]
+    const own = [...new Set([...(p.tier === 'quick' ? slow : []), ...serial])]
+    // bun REPLACES the bunfig pathIgnorePatterns with the command line ones, so
+    // the repo's own come along whenever this or the repo's arguments name any
+    const cliIgnores = p.rawArgs.some((a) => a.startsWith('--path-ignore-patterns'))
+    const ignored = own.length > 0 || cliIgnores ? [...own, ...(p.configIgnores ?? []).filter((g) => !own.includes(g))] : []
     const serialRun = serial.filter((f) => p.tier === 'full' || !slow.includes(f))
+    // the full tier ceiling, on every file. The quick tier keeps bun's
+    // default, where a suite is under a second and a hang must fail fast
+    const named = p.rawArgs.some((a) => a === '--timeout' || a.startsWith('--timeout='))
+    const args = p.tier === 'full' && !named ? [`--timeout=${FULL_TIMEOUT_MS}`, ...p.rawArgs] : p.rawArgs
+    const isolated = p.rawArgs.some((a) => a === '--isolate' || a === '--no-isolate')
     return {
-        parallel: [...p.rawArgs, ...(p.parallel ? ['--parallel'] : []), ...ignored.map((f) => `--path-ignore-patterns=${f}`)],
-        serial: serialRun.length > 0 ? [...p.rawArgs, ...serialRun] : null,
+        parallel: [...args, ...(p.parallel ? [p.workers != null ? `--parallel=${p.workers}` : '--parallel'] : []), ...(p.parallel && p.noIsolate === true && !isolated ? ['--no-isolate'] : []), ...ignored.map((f) => `--path-ignore-patterns=${f}`)],
+        serial: serialRun.length > 0 ? [...args, ...serialRun] : null,
     }
 }
 
+/** how many `--parallel` workers one suite run takes. Every test check runs
+ *  on one slot of the machine pool (core/slots.ts), so a run sized to every
+ *  core while four other checks do the same puts five times the cores to
+ *  work. A run takes its own slot's share of the cores plus the share of
+ *  every slot free when it starts, never more than the cores, and never
+ *  fewer than half of them: the count is fixed for the whole run, and a gate
+ *  starts it while its first burst of short checks holds the pool, so the
+ *  share alone left the longest suite on two workers long after that burst
+ *  ended. Measured on 8 cores: two workers 12.2s, four 7.6s, eight 7.0s */
+export function poolWorkers(p: { cores: number; size: number; held: number }): number {
+    const size = Math.max(1, p.size)
+    const mine = Math.max(1, size - Math.max(1, p.held) + 1)
+    const floor = Math.max(2, Math.floor(p.cores / 2))
+    return Math.max(floor, Math.min(p.cores, Math.round((p.cores * mine) / size)))
+}
+
 type Timed = { file: string; ms: number }
 
 export function judgeSuites(p: { timings: Record<string, number>; tests: TestsConfig; tier: 'quick' | 'full' }): { over: Timed[]; noLongerSlow: Timed[]; slowest: Timed[] } {
@@ -102,14 +177,137 @@ export function judgeSuites(p: { timings: Record<string, number>; tests: TestsCo
     }
 }
 
-/** what stays over budget once each suspect ran alone: a parallel timing
- *  carries the load of every other suite and every other gate on the machine,
- *  so only the alone timing can fail a suite */
-export function confirmOver(over: Timed[], alone: Record<string, number>, budgetMs: number): Timed[] {
-    const byFile = new Map(Object.entries(alone).map(([f, ms]) => [normSuitePath(f), ms]))
-    return over.map((t) => ({ file: t.file, ms: byFile.get(t.file) ?? t.ms })).filter((t) => t.ms > budgetMs)
+/** one suspect's run alone, in its own `bun test` process. cpuMs is user plus
+ *  system time of that process and every child it reaped, null when the
+ *  runtime reports none */
+export type AloneRun = { wallMs: number; cpuMs: number | null }
+/** the 1 minute load average against the core count, read before a suspect runs */
+export type MachineLoad = { load1: number; cores: number }
+/** how far past the budget a suite must WAIT on an idle machine before its
+ *  wall time fails it: a suite that sleeps or polls costs its owner the same
+ *  as one that computes, and the factor keeps scheduler noise out */
+export const WAIT_FACTOR = 2
+/** how much more CPU the same suite burns on a saturated machine. CPU time is
+ *  not load free: measured on 8 cores, one suite went from 1.0s of CPU idle to
+ *  1.35 to 1.5s with the cores saturated (load 7 to 19), and did not grow past
+ *  that. So a loaded machine fails a suite past the budget times this */
+export const LOADED_CPU_FACTOR = 1.5
+/** `ms` is the time the verdict used: cpu, or wall for a wait or when no cpu figure exists */
+export type Confirmed = { file: string; ms: number; wallMs: number; cpuMs: number | null; over: 'cpu' | 'wait' | 'wall' | null }
+
+/** the verdict on each suspect once it ran alone. A wall time carries the load
+ *  of every other process on the machine, and another gate can triple it, so
+ *  the budget judges CPU: what the suite itself burned, which load moves by
+ *  a bounded factor only (LOADED_CPU_FACTOR). Wall time still fails a suite
+ *  far over the budget while the machine was idle, because only then is the
+ *  wait the suite's own */
+export function confirmOver(suspects: Timed[], alone: Record<string, AloneRun>, budgetMs: number, load: MachineLoad): { over: Confirmed[]; cleared: Confirmed[] } {
+    const byFile = new Map(Object.entries(alone).map(([f, run]) => [normSuitePath(f), run]))
+    const idle = load.load1 < load.cores
+    const judged = suspects.map((t): Confirmed => {
+        const run = byFile.get(t.file)
+        const wallMs = run?.wallMs ?? t.ms
+        const cpuMs = run?.cpuMs ?? null
+        if (cpuMs == null) return { file: t.file, ms: wallMs, wallMs, cpuMs, over: wallMs > budgetMs ? 'wall' : null }
+        if (cpuMs > budgetMs * (idle ? 1 : LOADED_CPU_FACTOR)) return { file: t.file, ms: cpuMs, wallMs, cpuMs, over: 'cpu' }
+        if (idle && wallMs > budgetMs * WAIT_FACTOR) return { file: t.file, ms: wallMs, wallMs, cpuMs, over: 'wait' }
+        return { file: t.file, ms: cpuMs, wallMs, cpuMs, over: null }
+    })
+    return { over: judged.filter((c) => c.over != null), cleared: judged.filter((c) => c.over == null) }
+}
+
+/** how the parallel phase's workers hand the runner the CPU of each suite
+ *  (suite-cpu-preload.ts writes it, readPhaseCpu reads it) */
+export const SUITE_CPU_ENV = 'SHIPKIT_SUITE_CPU'
+
+/** one suite's figures from the parallel phase: its own CPU, children
+ *  included, and all its worker burned before it began (suite-cpu-preload.ts
+ *  says why the sum bounds a lone run) */
+export type PhaseCpu = { cpuMs: number; priorMs: number }
+
+/** what the workers wrote, keyed like the timings: relative to the run's cwd.
+ *  `ran` is every suite that finished in the phase, `cpu` the ones whose
+ *  figure can be trusted. A file bun ran twice keeps its larger bound, and
+ *  none at all once one of its runs could not be trusted */
+export function readPhaseCpu(text: string, cwd: string): { ran: string[]; cpu: Record<string, PhaseCpu> } {
+    const ran = new Set<string>()
+    const unsure = new Set<string>()
+    const cpu: Record<string, PhaseCpu> = {}
+    const base = cwd.replace(/\\/g, '/')
+    for (const line of text.split('\n')) {
+        const [file, ms, prior] = line.split('\t')
+        if (file == null || file === '' || ms == null || prior == null) continue
+        const rel = normSuitePath(posix.relative(base, file.replace(/\\/g, '/')))
+        if (ms === '-' && prior === '-') { ran.add(rel); unsure.add(rel); continue }
+        if (!/^\d+$/.test(ms) || !/^\d+$/.test(prior)) continue
+        ran.add(rel)
+        const next = { cpuMs: Number(ms), priorMs: Number(prior) }
+        const had = cpu[rel]
+        if (had == null || next.cpuMs + next.priorMs > had.cpuMs + had.priorMs) cpu[rel] = next
+    }
+    for (const f of unsure) delete cpu[f]
+    return { ran: [...ran].sort(), cpu }
+}
+
+/** which suspects still need their alone run. A lone run can only need
+ *  what the worker computed by the suite's end, its whole CPU before the
+ *  suite (priorMs) plus what the suite burned, and sharing the machine only
+ *  raises CPU, so a suspect whose sum is inside the budget is inside it alone
+ *  too. A suspect with no figure (a child not yet reaped) runs alone. Only the alone run can see a WAIT, so a
+ *  suite past WAIT_FACTOR times the budget in wall time still gets it while
+ *  the machine is idle */
+export function aloneRunsNeeded(suspects: Timed[], parallelCpu: Record<string, PhaseCpu>, budgetMs: number, load: MachineLoad): { rerun: Timed[]; cleared: Confirmed[] } {
+    const idle = load.load1 < load.cores
+    const rerun: Timed[] = []
+    const cleared: Confirmed[] = []
+    for (const t of suspects) {
+        const f = parallelCpu[t.file]
+        const mayWait = idle && t.ms > budgetMs * WAIT_FACTOR
+        if (f != null && f.cpuMs + f.priorMs <= budgetMs && !mayWait) cleared.push({ file: t.file, ms: f.cpuMs, wallMs: t.ms, cpuMs: f.cpuMs, over: null })
+        else rerun.push(t)
+    }
+    return { rerun, cleared }
 }
 
+/** the suites with a failing test, read off bun's report: a file that failed
+ *  prints its path as a header line, then its `(fail)` lines under it. A
+ *  passing file prints nothing at all in a piped run, which is why this reads
+ *  failures only */
+export function failedSuites(output: string): string[] {
+    const out = new Set<string>()
+    let cur: string | null = null
+    for (const line of output.split('\n')) {
+        const head = line.match(/^(\S+\.(?:test|spec)\.[cm]?[jt]sx?):$/)
+        if (head != null) { cur = normSuitePath(head[1]!); continue }
+        // a file that cannot load prints no `(fail)` line, only this banner
+        if (cur != null && (/^\(fail\) /.test(line) || line.startsWith('# Unhandled error between tests'))) out.add(cur)
+    }
+    return [...out]
+}
+
+/** the FIRST failure of each failing suite, read off the same report as
+ *  failedSuites: its `(fail)` line, timing dropped, with the first `error:`
+ *  line bun printed before it in that file. What the record keeps so a page
+ *  can say why a file is red without a rerun */
+export function failLines(output: string): Map<string, string> {
+    const out = new Map<string, string>()
+    let cur: string | null = null
+    let err: string | null = null
+    for (const raw of output.split('\n')) {
+        const line = raw.trimEnd()
+        const head = line.match(/^(\S+\.(?:test|spec)\.[cm]?[jt]sx?):$/)
+        if (head != null) { cur = normSuitePath(head[1]!); err = null; continue }
+        if (cur == null || out.has(cur)) continue
+        if (err == null && /^\s*error: /.test(line)) err = line.trim()
+        const fail = line.match(/^\(fail\) (.*?)(?: \[[\d.]+m?s\])?$/)
+        if (fail != null) out.set(cur, clip(err == null ? fail[1]! : `${fail[1]!}: ${err}`))
+        else if (line.startsWith('# Unhandled error between tests')) out.set(cur, clip(err == null ? 'an unhandled error between tests' : `an unhandled error between tests: ${err}`))
+    }
+    return out
+}
+
+const clip = (s: string): string => (s.length > 300 ? `${s.slice(0, 299)}…` : s)
+
 /** the suites bun names as a crashed parallel worker */
 export function crashedWorkers(output: string): { file: string; signal: string }[] {
     return [...output.matchAll(/^\s*✗\s+(\S+)\s+\(worker crashed: (SIG[A-Z0-9]+)\)\s*$/gm)].map((m) => ({ file: normSuitePath(m[1]!), signal: m[2]! }))

package/src/suite/kept-timings.ts

@@ -0,0 +1,58 @@
+// THE DURATIONS A SUITE RUN LEAVES FOR THE NEXT ONE. bun's --timings file does
+// two jobs: the runner reads the durations back for the budget, and bun itself
+// starts the slowest files first when the file already holds durations. A run
+// that only ever reads a file in its own temp dir schedules in discovery order,
+// so one long suite can start last and set the wall time alone.
+//
+// The kept file is shared by every run of the unit, several at once, so bun
+// never writes it directly: each run gets a copy to read and update, and the
+// kept file is replaced whole by a rename. A kept file that is not in bun's own
+// shape seeds nothing, because bun fails the whole phase on one.
+//
+// bun MERGES what it measured into what it read, so a suite deleted since the
+// last run comes back in the file as a timing this run never took. The runner
+// judges and keeps only the suites the phase ran (suite-cli.ts).
+import { copyFileSync, mkdirSync, readFileSync } from 'fs'
+import { dirname, join } from 'path'
+import { atomicWrite } from '../core/locked-write.ts'
+import { shipkitRoot } from '../ledger/store.ts'
+
+/** where a unit's durations live, beside everything else the repo remembers */
+export const timingsHome = (root: string, unit: string): string => join(shipkitRoot(root), 'suite-timings', `${unit === '' ? 'root' : unit}.json`)
+
+/** the text, when it is a timings document bun wrote */
+const timingsText = (path: string): string | null => {
+    try {
+        const text = readFileSync(path, 'utf8')
+        // bun refuses a timings file without `version: 1`, and a refusal fails
+        // the whole phase, so only a file in bun's own shape is handed on
+        const parsed = JSON.parse(text) as { version?: unknown; files?: unknown }
+        return parsed != null && parsed.version === 1 && typeof parsed.files === 'object' && parsed.files != null && !Array.isArray(parsed.files) ? text : null
+    } catch {
+        return null
+    }
+}
+
+/** copy the kept durations to where this run's bun reads them. false when
+ *  there are none worth reading */
+export function seedTimings(kept: string, runFile: string): boolean {
+    if (timingsText(kept) == null) return false
+    try {
+        copyFileSync(kept, runFile)
+        return true
+    } catch {
+        return false
+    }
+}
+
+/** keep what this run measured. A run that wrote nothing readable keeps the
+ *  last good file */
+export function keepTimings(runFile: string, kept: string): void {
+    const text = timingsText(runFile)
+    if (text == null) return
+    try {
+        mkdirSync(dirname(kept), { recursive: true })
+        atomicWrite(kept, text)
+    } catch { /* the next run schedules blind, which is slower and never wrong */ }
+}
+

package/src/suite/runner-shapes.ts

@@ -0,0 +1,88 @@
+// does this check body run bun's test runner ITSELF? Tests run through the
+// generated test checks only (the floor `test` slot, one `test:<unit>` per
+// declared unit, core/floor-resolve.ts): they run in the unit's dir with its
+// bunfig and preload, parallel and timed against the budget, and SK018 knows
+// which file each one reaches. A hand written check running `bun test` is a
+// second runner nobody plans, times or dedupes. Rule SK019 fails on one.
+//
+// Read from source text, never by importing it: a legacy check script runs its
+// body on import. The reader only looks at code, never at comments, and only at
+// three shapes that EXECUTE something: an argv literal (`['bun', 'test']`), a
+// command string handed to a shell (`sh -c`, `$\`…\``, `execSync(…)`), and a
+// reference to the suite runner module. A string that merely NAMES a command
+// (a message, a script body written into package.json) is data, and passes.
+import { basename } from 'path'
+import { lexSource } from '../ts/lex.ts'
+
+/** a `bun run <script>` that runs the test slot's own body */
+const TEST_SCRIPT = /^test(:raw)?$/
+
+/** a package.json script body by name, null when there is none */
+export type ScriptReader = (name: string) => string | null
+
+/** what an argv runs, when it is bun's test runner: `bun test`, `bun run
+ *  test:raw`, `bun run test`, `bun run <script>` whose body runs it (when
+ *  `scripts` can read the body), or a shell command string that does */
+export function argvRunsTests(argv: readonly string[], scripts?: ScriptReader): string | null {
+    const [head, a1, a2] = argv
+    if (head == null) return null
+    const bin = basename(head)
+    if (bin === 'bun' || head === 'process.execPath') {
+        if (a1 === 'test') return 'bun test'
+        if (a1 === 'run' && a2 != null) return runScript(a2, scripts)
+    }
+    if (argv.some((a) => a.includes('suite-cli'))) return 'the suite runner (suite-cli)'
+    if (['sh', 'bash', 'zsh'].includes(bin) && a1 === '-c' && a2 != null) return commandRunsTests(a2, scripts)
+    return null
+}
+
+/** `bun run <name>`: the test slot's own script, or one whose body runs the
+ *  test runner. One level deep, so a script naming itself cannot loop */
+function runScript(name: string, scripts?: ScriptReader): string | null {
+    if (TEST_SCRIPT.test(name)) return `bun run ${name}`
+    const body = scripts?.(name)
+    if (body == null) return null
+    const inner = commandRunsTests(body)
+    return inner == null ? null : `bun run ${name} (its script runs ${inner})`
+}
+
+/** a shell command string that runs bun's test runner, at its start or after
+ *  a `&&`, `;` or `||`, env assignments (`TZ=UTC bun test`) allowed before it */
+export function commandRunsTests(cmd: string, scripts?: ScriptReader): string | null {
+    for (const m of cmd.matchAll(/(?:^|&&|;|\|\|)\s*(?:\w+=\S*\s+)*bun\s+(test(?=\s|$)|run\s+([\w:.-]+))/g)) {
+        if (m[2] == null) return 'bun test'
+        const hit = runScript(m[2], scripts)
+        if (hit != null) return hit
+    }
+    return null
+}
+
+const LIT = '\\0(\\d+)\\0'
+/** an argv literal in a position that EXECUTES it: `cmd: [`, `exec([`,
+ *  `spawn([`, `Bun.spawn([`. A list of words held as data is not a run */
+const ARGV_RUN = new RegExp(`(?:\\bcmd\\s*:\\s*|\\b(?:exec|execFile|execFileSync|spawn|spawnSync|execa)\\s*\\(\\s*|\\bBun\\.spawn(?:Sync)?\\s*\\(\\s*)\\[\\s*((?:process\\.execPath|${LIT})(?:\\s*,\\s*${LIT})*)`, 'g')
+/** a string handed straight to a shell: `execSync('…')`, `$\`…\``. A
+ *  template's chunks come as a run, `${…}` between them */
+const SHELL_CALL = new RegExp(`(?:\\b(?:execSync|exec|execaCommand|spawnSync|spawn)\\s*\\(\\s*|\\$)\`?((?:${LIT})(?:\\$\\{[^\\0\`]*?\\}${LIT})*)`, 'g')
+/** the suite runner's module, resolved or imported */
+const SUITE_REF = new RegExp(`(?:\\bresolve\\s*\\(\\s*|\\bimport\\s*\\(\\s*|\\bfrom\\s*)\`?${LIT}`, 'g')
+
+const literals = (run: string, strings: string[]): string[] => [...run.matchAll(new RegExp(`process\\.execPath|${LIT}`, 'g'))].map((x) => (x[1] == null ? 'process.execPath' : strings[Number(x[1])]!))
+
+/** every way this source runs bun's test runner, one line each. Empty = it
+ *  never does. `scripts` reads the package.json a `bun run <name>` names */
+export function sourceRunsTests(src: string, scripts?: ScriptReader): string[] {
+    const { code, strings } = lexSource(src)
+    const found = new Set<string>()
+    for (const m of code.matchAll(ARGV_RUN)) {
+        const hit = argvRunsTests(literals(m[1]!, strings), scripts)
+        if (hit != null) found.add(hit)
+    }
+    for (const m of code.matchAll(SHELL_CALL)) {
+        // an interpolation reads as one word, so `cd ${dir} && bun test` stays a command
+        const hit = commandRunsTests(literals(m[1]!, strings).join('X'), scripts)
+        if (hit != null) found.add(hit)
+    }
+    for (const m of code.matchAll(SUITE_REF)) if (/(?:^|\/)suite-cli(?:\.ts)?$/.test(strings[Number(m[1])]!)) found.add('the suite runner (suite-cli)')
+    return [...found]
+}