rvlib-shipkit 1.7.0 → 1.9.0

package/src/serve/run-lanes.ts

@@ -0,0 +1,138 @@
+// THE RUNS OF ONE HUB: who attaches, who runs beside whom, who waits.
+//
+//   - a run with a key identical to one in flight attaches to it: the lines it
+//     printed so far, then the rest, then its exit code. To a queued one always
+//     (it reads the tree after both asks), to a running one only while the tree
+//     stamp equals the one taken at its start
+//   - a run that writes the tree (a repair pass) waits for every run ahead of
+//     it, and every later run waits for it
+//   - every other run starts at once: the machine slot pool each check body
+//     takes bounds the CPU, never this queue. It admits fewer slots on a
+//     loaded machine (core/slots.ts), so a run past it waits and says why
+//
+// the one constraint a reader breaks first: the stamp is taken when a run
+// STARTS, before its body reads anything, so a tree that moves during the run
+// can only make a later asker run on its own, never adopt a stale verdict.
+import { createHash } from 'crypto'
+import { statSync } from 'fs'
+import { join } from 'path'
+import { fixPassRuns } from '../core/fix-scope.ts'
+import { gitBin } from '../core/git-bin.ts'
+
+export type LaneAsk = {
+    /** what makes two runs the same run, null: never shared */
+    key: string | null
+    /** the run rewrites tracked files (a repair pass) */
+    writes: boolean
+    print: (line: string) => void
+    /** no note lines: a --json run prints the json and nothing else */
+    quiet?: boolean
+}
+
+type Entry = {
+    key: string | null
+    writes: boolean
+    running: boolean
+    stamp: string | null
+    lines: string[]
+    listeners: Set<(line: string) => void>
+    done: Promise<number>
+}
+
+export const ATTACHED_NOTE = 'note: an identical run is in flight on this tree, so this one takes its lines and its verdict'
+export const WAIT_NOTE = 'note: a run that rewrites files is in flight, so this one starts when it ends'
+
+export class RunLanes {
+    private entries: Entry[] = []
+    constructor(private readonly stampOf: () => Promise<string | null> | string | null) {}
+
+    /** runs in flight, queued ones included */
+    get size(): number {
+        return this.entries.length
+    }
+
+    async submit(ask: LaneAsk, body: (print: (line: string) => void) => Promise<number>): Promise<number> {
+        if (ask.key != null) {
+            const same = this.entries.find((e) => e.key === ask.key)
+            if (same != null && (!same.running || (same.stamp != null && same.stamp === (await this.stampOf())))) return this.attach(same, ask.print)
+        }
+        const ahead = this.entries.filter((e) => ask.writes || e.writes).map((e) => e.done.catch(() => 1))
+        let finish!: (code: number) => void
+        let fail!: (e: unknown) => void
+        const entry: Entry = {
+            key: ask.key,
+            writes: ask.writes,
+            running: false,
+            stamp: null,
+            lines: [],
+            listeners: new Set([ask.print]),
+            done: new Promise<number>((res, rej) => { finish = res; fail = rej }),
+        }
+        // the asker gets the throw; an attacher, if any, its own rejection
+        entry.done.catch(() => {})
+        this.entries.push(entry)
+        const tee = (line: string): void => {
+            entry.lines.push(line)
+            for (const l of entry.listeners) l(line)
+        }
+        try {
+            if (ahead.length > 0) {
+                if (ask.quiet !== true) tee(WAIT_NOTE)
+                await Promise.all(ahead)
+            }
+            entry.stamp = ask.key == null ? null : await this.stampOf()
+            entry.running = true
+            const code = await body(tee)
+            finish(code)
+            return code
+        } catch (e) {
+            fail(e)
+            throw e
+        } finally {
+            this.entries = this.entries.filter((x) => x !== entry)
+        }
+    }
+
+    private attach(e: Entry, print: (line: string) => void): Promise<number> {
+        print(ATTACHED_NOTE)
+        for (const l of e.lines) print(l)
+        e.listeners.add(print)
+        return e.done.finally(() => e.listeners.delete(print))
+    }
+}
+
+/** the key of a run: its kind and its options, whoever asked */
+export function runKey(kind: string, opts: Record<string, unknown>): string {
+    const { invokedBy: _by, ...rest } = opts
+    const sorted = Object.fromEntries(Object.entries(rest).filter(([, v]) => v !== undefined).sort(([a], [b]) => (a < b ? -1 : 1)))
+    return `${kind} ${JSON.stringify(sorted)}`
+}
+
+/** a run whose repair pass runs (core/fix-scope.ts): the structural fixers
+ *  and the hooks only ever run inside it */
+export const writesTree = (opts: Record<string, unknown>): boolean =>
+    fixPassRuns({ fix: typeof opts.fix === 'boolean' ? opts.fix : undefined, onlyIds: Array.isArray(opts.onlyIds) ? (opts.onlyIds as string[]) : undefined })
+
+/** HEAD, what git status lists, and the stat of each listed path, hashed:
+ *  equal stamps mean no tracked or untracked file moved in between. Null
+ *  outside git, where nothing attaches */
+export function treeStamp(root: string): string | null {
+    const git = (args: string[]): string | null => {
+        const p = Bun.spawnSync([gitBin(), '--no-optional-locks', ...args], { cwd: root, stdout: 'pipe', stderr: 'pipe' })
+        return p.exitCode === 0 ? p.stdout.toString() : null
+    }
+    const head = git(['rev-parse', '-q', '--verify', 'HEAD']) ?? 'none'
+    const status = git(['status', '--porcelain=v1', '-z', '-uall', '--no-renames', '--ignore-submodules'])
+    if (status == null) return null
+    const h = createHash('sha256').update(head).update('\0').update(status)
+    for (const entry of status.split('\0')) {
+        if (entry.length < 4) continue
+        try {
+            const st = statSync(join(root, entry.slice(3)))
+            h.update(`\0${st.size}:${st.mtimeMs}:${st.ctimeMs}`)
+        } catch {
+            h.update('\0gone')
+        }
+    }
+    return h.digest('hex')
+}

package/src/smoke/run-smoke.ts

@@ -27,6 +27,10 @@ export type SmokeRoute = {
      *  match's href after this route and judges the landed page as its own
      *  row. How a detail page with a real id gets visited without knowing one. */
     open?: string
+    /** the visible text a settled route needs before it counts as rendered,
+     *  default 40. A canvas app (a game) draws everything into one canvas and
+     *  shows no text: `{ path: '/', waitFor: 'canvas', minChars: 0 }`. */
+    minChars?: number
 }
 
 export type SmokeLogin = {
@@ -63,8 +67,9 @@ export type SmokeConfig = {
 const SMOKE_KEYS = new Set(['base', 'routes', 'login', 'paceMs', 'shots'])
 const LOGIN_KEYS = new Set(['path', 'email', 'emailSecret', 'passwordSecret', 'form'])
 const FORM_KEYS = new Set(['email', 'password', 'submit'])
-const ROUTE_KEYS = new Set(['path', 'waitFor', 'open'])
+const ROUTE_KEYS = new Set(['path', 'waitFor', 'open', 'minChars'])
 export const DEFAULT_LOGIN_PATH = '/login'
+export const DEFAULT_MIN_CHARS = 40
 
 export const DEFAULT_PACE_MS = 3000
 export const DEFAULT_SHOTS = `${LAYOUT.tmp}/smoke`
@@ -86,6 +91,8 @@ export function validateSmokeConfig(c: unknown): SmokeConfig {
                 const v = (r as Record<string, unknown>)[k]
                 if (v != null && (typeof v !== 'string' || v === '')) throw new Error(`defineRepo: smoke.routes['${path}'].${k} must be a non-empty selector`)
             }
+            const min = (r as Record<string, unknown>)['minChars']
+            if (min != null && (typeof min !== 'number' || !Number.isInteger(min) || min < 0)) throw new Error(`defineRepo: smoke.routes['${path}'].minChars must be a whole number of characters, 0 or more`)
         }
     }
     if (s['login'] != null) {
@@ -152,8 +159,8 @@ export type SmokeReport = {
  *  nothing threw, an empty `waitFor` on a listing is exactly how a broken
  *  migration looks, and a page that scrolls sideways is a layout defect only
  *  a real browser can see (happy-dom does no layout). */
-export function judgeRoute(r: { route: string; chars: number; matches: number; problems: number; waitFor?: string; overflowPx: number }): RouteReport {
-    const empty = r.chars < 40
+export function judgeRoute(r: { route: string; chars: number; matches: number; problems: number; waitFor?: string; minChars?: number; overflowPx: number }): RouteReport {
+    const empty = r.chars < (r.minChars ?? DEFAULT_MIN_CHARS)
     const noMatch = r.waitFor != null && r.matches === 0
     const sideways = r.overflowPx > 1
     const note = empty ? 'EMPTY PAGE' : noMatch ? `NO MATCH FOR ${r.waitFor}` : sideways ? `PAGE SCROLLS SIDEWAYS +${r.overflowPx}px` : r.problems > 0 ? `${r.problems} problem(s)` : ''
@@ -368,7 +375,7 @@ export async function runSmoke(root: string, config: SmokeConfig, opts: SmokeRun
         }
 
         /** visit one url, settle it, judge it, screenshot it */
-        const visit = async (label: string, url: string, waitFor?: string): Promise<RouteReport> => {
+        const visit = async (label: string, url: string, waitFor?: string, minChars?: number): Promise<RouteReport> => {
             // let the previous page's requests drain out of the concurrency
             // window BEFORE the label moves, or its late failures land on this row
             if (paceMs > 0) await page.waitForTimeout(paceMs)
@@ -387,11 +394,11 @@ export async function runSmoke(root: string, config: SmokeConfig, opts: SmokeRun
                 return Math.max(de.scrollWidth - de.clientWidth, doc.body.scrollWidth - doc.body.clientWidth)
             }).catch(() => 0)
             await page.screenshot({ path: join(shots, `${routeSlug(label)}.png`), fullPage: true })
-            return judgeRoute({ route: label, chars, matches, problems: problems.length - before, waitFor, overflowPx })
+            return judgeRoute({ route: label, chars, matches, problems: problems.length - before, waitFor, minChars, overflowPx })
         }
 
         for (const route of routes) {
-            reports.push(await visit(route.path, route.path, route.waitFor))
+            reports.push(await visit(route.path, route.path, route.waitFor, route.minChars))
             if (route.open == null) continue
             // a detail page with a real id: the first link the selector matches
             const href = await page.locator(route.open).first().getAttribute('href').catch(() => null)

package/src/suite/judge-suites.ts

@@ -24,6 +24,8 @@ export type TestsConfig = {
     slow?: SlowSuite[]
     /** suites that cannot share a run: they run one at a time after the parallel phase */
     serial?: SerialSuite[]
+    /** true: the quick tier runs only the suites a change since the last run can reach (their import closure and what its modules read at runtime) and the ones that did not pass then. Off by default: every suite runs every time. The full tier always runs every suite */
+    select?: boolean
 }
 
 export const DEFAULT_BUDGET_MS = 2000
@@ -39,17 +41,18 @@ export const DEFAULT_BUDGET_MS = 2000
  *  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
+ *  fires on a worker stuck in a SYNCHRONOUS call, or in `expect(p).resolves`
+ *  or `.rejects` on a promise that never settles, 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 TESTS_KEYS = ['budgetMs', 'slow', 'serial', 'select']
 const SLOW_KEYS = ['file', 'catches', 'whyNotFast']
 const SERIAL_KEYS = ['file', 'why']
-const OWN_FLAGS = ['--budget-ms', '--slow', '--serial', '--declared-in', '--ceiling-ms', '--unit']
+const OWN_FLAGS = ['--budget-ms', '--slow', '--serial', '--declared-in', '--ceiling-ms', '--unit', '--select']
 
 export const normSuitePath = (file: string): string => posix.normalize(file.replace(/\\/g, '/')).replace(/^\.\//, '')
 
@@ -84,13 +87,14 @@ export function suiteFlags(t: TestsConfig | undefined): string[] {
         ...(t.budgetMs != null ? ['--budget-ms', String(t.budgetMs)] : []),
         ...(t.slow ?? []).flatMap((s) => ['--slow', s.file]),
         ...(t.serial ?? []).flatMap((s) => ['--serial', s.file]),
+        ...(t.select === true ? ['--select', 'on'] : []),
     ]
 }
 
 /** 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; ceilingMs: number | null; unit: string } | string {
-    const tests: Required<TestsConfig> = { budgetMs: DEFAULT_BUDGET_MS, slow: [], serial: [] }
+    const tests: Required<TestsConfig> = { budgetMs: DEFAULT_BUDGET_MS, slow: [], serial: [], select: false }
     let declaredIn = 'repo.config.ts tests'
     let ceilingMs: number | null = null
     let unit = ''
@@ -109,6 +113,7 @@ export function parseSuiteFlags(argv: string[]): { tests: TestsConfig; rawArgs:
         else if (flag === '--serial') tests.serial.push({ file: value, why: '(declared)' })
         else if (flag === '--ceiling-ms') ceilingMs = Number(value)
         else if (flag === '--unit') unit = value
+        else if (flag === '--select') { if (value !== 'off' && value !== 'on') return '--select takes on or off'; tests.select = value === 'on' }
         else declaredIn = value
     }
     if (!(tests.budgetMs > 0)) return '--budget-ms must be a positive number'
@@ -116,6 +121,8 @@ export function parseSuiteFlags(argv: string[]): { tests: TestsConfig; rawArgs:
     return { tests, rawArgs: argv.slice(i), declaredIn, ceilingMs, unit }
 }
 
+const PARALLEL_COUNT = /^--parallel=([1-9]\d*)$/
+
 /** 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.
  *
@@ -124,8 +131,15 @@ export function parseSuiteFlags(argv: string[]): { tests: TestsConfig; rawArgs:
  *  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 } {
+ *  itself keeps it.
+ *
+ *  `workers` (the pool share) is a ceiling under the repo's own
+ *  `--parallel=<n>`: the phase takes the smaller, as the one flag on its line,
+ *  since bun reads the last `--parallel` it is given. No other line names a
+ *  worker count: the serial phase, a phase one that is not parallel (the full
+ *  tier) and `alone` (what a suspect's rerun puts before its file) each run
+ *  one suite at a time, so the repo's `--parallel` stays off them. */
+export function planPhases(p: { tests: TestsConfig; tier: 'quick' | 'full'; rawArgs: string[]; parallel: boolean; noIsolate?: boolean; configIgnores?: string[]; workers?: number }): { parallel: string[]; serial: string[] | null; alone: string[]; workers: number | null } {
     const slow = (p.tests.slow ?? []).map((s) => normSuitePath(s.file))
     const serial = (p.tests.serial ?? []).map((s) => normSuitePath(s.file))
     const own = [...new Set([...(p.tier === 'quick' ? slow : []), ...serial])]
@@ -139,9 +153,15 @@ export function planPhases(p: { tests: TestsConfig; tier: 'quick' | 'full'; rawA
     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')
+    const repoCount = p.rawArgs.map((a) => PARALLEL_COUNT.exec(a)?.[1]).filter((n) => n != null).map(Number).at(-1)
+    const bounds = [p.workers, repoCount].filter((n) => n != null)
+    const workers = p.parallel && bounds.length > 0 ? Math.min(...bounds) : null
+    const solo = args.filter((a) => a !== '--parallel' && !PARALLEL_COUNT.test(a))
     return {
-        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,
+        parallel: [...solo, ...(p.parallel ? [workers != null ? `--parallel=${workers}` : '--parallel'] : []), ...(p.parallel && p.noIsolate === true && !isolated ? ['--no-isolate'] : []), ...ignored.map((f) => `--path-ignore-patterns=${f}`)],
+        serial: serialRun.length > 0 ? [...solo, ...serialRun] : null,
+        alone: solo,
+        workers,
     }
 }
 
@@ -163,14 +183,16 @@ export function poolWorkers(p: { cores: number; size: number; held: number }): n
 
 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[] } {
+export function judgeSuites(p: { timings: Record<string, number>; tests: TestsConfig; tier: 'quick' | 'full'; red?: string[] }): { over: Timed[]; noLongerSlow: Timed[]; slowest: Timed[] } {
     const budget = p.tests.budgetMs ?? DEFAULT_BUDGET_MS
     const slow = new Set((p.tests.slow ?? []).map((s) => normSuitePath(s.file)))
+    const red = new Set((p.red ?? []).map(normSuitePath))
     const timed = Object.entries(p.timings).map(([file, ms]) => ({ file: normSuitePath(file), ms })).sort((a, b) => b.ms - a.ms)
     return {
         // the budget guards the tier every edit waits on. The full tier is
-        // where slow suites belong, and it only reports
-        over: p.tier === 'quick' ? timed.filter((t) => t.ms > budget && !slow.has(t.file)) : [],
+        // where slow suites belong, and it only reports. A red suite took
+        // the time of its failure (a timeout, a crash), which its red explains
+        over: p.tier === 'quick' ? timed.filter((t) => t.ms > budget && !slow.has(t.file) && !red.has(t.file)) : [],
         // half the budget, so a declaration does not flap on timing noise
         noLongerSlow: timed.filter((t) => slow.has(t.file) && t.ms < budget / 2),
         slowest: timed.slice(0, 3),
@@ -234,6 +256,20 @@ export function confirmOver(suspects: Timed[], alone: Record<string, AloneRun>,
     return { over: judged.filter((c) => c.over != null), cleared: judged.filter((c) => c.over == null) }
 }
 
+/** a lone run over the budget on CPU runs once more. Under load the
+ *  scheduler can spill a lone run onto the efficiency cores, where the same
+ *  retired instructions cost up to 4x the CPU time (measured on Apple
+ *  silicon), and a spill only ever raises the figure. A wait or a wall
+ *  verdict is not CPU, so it keeps its one run */
+export const retryAlone = (t: Timed, run: AloneRun, budgetMs: number, load: MachineLoad): boolean =>
+    confirmOver([t], { [t.file]: run }, budgetMs, load).over[0]?.over === 'cpu'
+
+/** the run charged less, as confirmOver charges it: the smaller of CPU and wall */
+export const smallerRun = (a: AloneRun, b: AloneRun): AloneRun => {
+    const charge = (r: AloneRun): number => Math.min(r.cpuMs ?? r.wallMs, r.wallMs)
+    return charge(b) < charge(a) ? b : a
+}
+
 const secs = (ms: number): string => `${(ms / 1000).toFixed(1)}s`
 
 /** the line a confirmed suite fails with */
@@ -339,6 +375,37 @@ export function failLines(output: string): Map<string, string> {
 
 const clip = (s: string): string => (s.length > 300 ? `${s.slice(0, 299)}…` : s)
 
+/** the clause the headline carries for the gate line: the command phase one
+ *  ran, and the flags the runner added to the script's own. Per file ignores
+ *  stay out, the slow and serial counts already say what they leave out */
+export function ranAs(phase: string[], rawArgs: string[]): string {
+    const shown = phase.filter((a) => !a.startsWith('--path-ignore-patterns'))
+    const added = shown.filter((a) => !rawArgs.includes(a))
+    return `as \`${['bun', 'test', ...shown].join(' ')}\`${added.length > 0 ? ` (added ${added.join(' ')})` : ''}`
+}
+
+/** the suites bun lists under `Interrupted while still running:` when a
+ *  phase is killed, one indented `<file> (<n>s)` line each */
+export function interruptedSuites(output: string): string[] {
+    const out: string[] = []
+    let inBlock = false
+    for (const line of output.split('\n')) {
+        if (/^Interrupted while still running:\s*$/.test(line)) { inBlock = true; continue }
+        if (!inBlock) continue
+        const m = /^\s+(\S+)\s+\(\d+(?:\.\d+)?m?s\)\s*$/.exec(line)
+        if (m == null) { inBlock = false; continue }
+        out.push(normSuitePath(m[1]!))
+    }
+    return out
+}
+
+/** the line a phase killed at its ceiling fails with. Measured on bun 1.4.3:
+ *  a plain await of a promise that never settles fails at the per test
+ *  timeout, while `expect(p).resolves` or `.rejects` on one blocks the worker
+ *  past it, as a synchronous loop does */
+export const stallWords = (name: string, ceilingMs: number, files: string[]): string =>
+    `${name} ran past its ${secs(ceilingMs)} ceiling and was killed${files.length > 0 ? ` with ${files.join(', ')} still running` : ''}: a test blocked its worker past the per test timeout, either a synchronous loop or expect(...).resolves or .rejects on a promise that never settles`
+
 /** 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]! }))
@@ -348,6 +415,7 @@ export function testsConfigProblems(t: TestsConfig): string[] {
     const problems: string[] = []
     for (const k of Object.keys(t)) if (!TESTS_KEYS.includes(k)) problems.push(`tests.${k} is not a tests field (fields: ${TESTS_KEYS.join(', ')})`)
     if (t.budgetMs != null && !(typeof t.budgetMs === 'number' && t.budgetMs > 0)) problems.push('tests.budgetMs must be a positive number of milliseconds')
+    if (t.select != null && typeof t.select !== 'boolean') problems.push('tests.select must be true or false')
     const lists: [string, { file: string }[], string[], [string, string][]][] = [
         ['slow', t.slow ?? [], SLOW_KEYS, [['catches', 'what it catches that no fast test can'], ['whyNotFast', 'why it cannot be made fast']]],
         ['serial', t.serial ?? [], SERIAL_KEYS, [['why', 'what breaks when it shares a run']]],

package/src/suite/reads-env.ts

@@ -0,0 +1,8 @@
+// the variables that hand the read recorder (suite-reads-preload.ts) its job:
+// where to write, the root it charges reads under, and, in a spawned bun
+// child, the module that spawned it
+export const SUITE_READS_ENV = 'SHIPKIT_SUITE_READS'
+export const SUITE_ROOT_ENV = 'SHIPKIT_SUITE_ROOT'
+export const SUITE_OWNER_ENV = 'SHIPKIT_SUITE_READS_OWNER'
+/** `0` runs every suite in the quick tier and records nothing, `1` selects even where tests.select is not true */
+export const SUITE_SELECT_ENV = 'SHIPKIT_TEST_SELECT'