brittle-jobs 0.2.0 → 0.2.2

package/README.md

@@ -4,7 +4,8 @@ Run [brittle](https://github.com/holepunchto/brittle) test files concurrently, o
 
 - A hung file costs one file, not the run: idle and hard timeouts kill the whole process group, grandchildren included.
 - Every file gets its own `TMPDIR`, wiped by the runner on exit or kill, so leaked tmp data cannot starve the disk.
-- Pool size is not tied to core count. Test files are mostly wait-bound, so the default oversubscribes.
+- Pool size defaults to the core count. Oversubscribing made a CPU-bound suite slower, so raise `-j` only for
+  wait-bound suites.
 
 ## Installation
 
@@ -25,18 +26,20 @@ brittle-jobs test/*.js --runtime node
 ```
 brittle-jobs [globs|files...] [flags]
 
-  -j, --jobs N          concurrent processes (default BRITTLE_JOBS or 2 x cores)
+  -j, --jobs N          concurrent processes (default BRITTLE_JOBS or cores)
   -t, --timeout MS      hard cap per file (default 300000)
       --idle-timeout MS kill file after this long without output (default 120000)
       --retries N       rerun failed files, pass on retry = FLAKY (default 0)
       --min-free-mb N   wait for free disk on tmp root before spawning (default 1024)
       --shard i/n       run the i-th of n slices
+      --solo GLOB       run matching files alone, after the rest (repeatable)
+      --timings FILE    json of file durations: orders and balances shards by it, updated after the run
       --runtime CMD     child command (default bare)
   -b, --bail            stop on first failure
 ```
 
-Each file runs as `<runtime> <file>`; a brittle test file runs itself. `bare` resolves from the project's own
-`bare-runtime` install, then from `PATH`.
+Each file runs as `<runtime> <file>`; a brittle test file runs itself. `bare` is spawned through the project's own
+`bare-runtime/spawn`, then from `PATH`. Pin `bare-runtime` exactly: that API is not covered by semver.
 
 Output is one line per file as it finishes, the full output of any file that fails, the ten slowest files, and a
 summary. Exit code is 1 when any file fails or hangs.
@@ -56,12 +59,17 @@ A `HUNG` report includes the process tree of the file at the moment it was kille
 - `TMPDIR`, `TMP`, `TEMP` point at a per-file directory under `os.tmpdir()/brittle-jobs-<cwd hash>`. It is removed
   when the file ends, however it ends. A stale root from a killed runner is removed at startup.
 - `BRITTLE_JOBS_WORKER_ID` and `JEST_WORKER_ID` hold the pool slot (`1..jobs`), for namespacing ports or databases.
-- Files start largest first. `--shard i/n` takes every n-th file of that order, so heavy files spread across shards.
+- Files start heaviest first. `--shard i/n` assigns each file, in that order, to the lightest shard so far.
+- Weight is the file size, or its duration with `--timings`. A file missing from the timings gets the median.
+- Every shard must read the same timings file, or shards drop and repeat files. Commit it; do not restore it from
+  a per-job cache. Each run merges the durations of passing files back into it.
+- `--solo` files run one at a time once the pool is empty, for files that starve each other under concurrency.
 
 ### Limits
 
 - POSIX only: process groups are not available on Windows.
-- A grandchild that calls `setsid` escapes the group kill.
+- A grandchild that calls `setsid` escapes the group kill. If it holds the file's stdout, the runner stops waiting
+  2s after the file exits.
 - Two concurrent runs from the same working directory share a tmp root and wipe each other.
 
 ## Migrating from 0.1
@@ -70,7 +78,7 @@ A `HUNG` report includes the process tree of the file at the moment it was kille
 - Default runtime is `bare`. `--bare` is accepted and ignored; use `--runtime node` for Node.
 - Generated `all.*` runner files are skipped, not expanded. Pass the test files or a glob.
 - `--timeout` is now a per-file cap enforced by the runner, not brittle's per-test timeout.
-- No timing cache; files are ordered by size.
+- No implicit timing cache; files are ordered by size unless `--timings` is passed.
 
 ## License
 

package/bin.js

@@ -16,6 +16,8 @@ const { values: opts, positionals } = parseArgs({
     retries: { type: 'string', default: '0' },
     'min-free-mb': { type: 'string', default: '1024' },
     shard: { type: 'string' },
+    solo: { type: 'string', multiple: true },
+    timings: { type: 'string' },
     runtime: { type: 'string' },
     bail: { type: 'boolean', short: 'b', default: false },
     bare: { type: 'boolean', default: false },
@@ -26,37 +28,44 @@ const { values: opts, positionals } = parseArgs({
 if (opts.help) {
   console.log(`brittle-jobs [globs|files...] [flags]
 
-  -j, --jobs N          concurrent processes (default BRITTLE_JOBS or 2 x cores)
+  -j, --jobs N          concurrent processes (default BRITTLE_JOBS or cores)
   -t, --timeout MS      hard cap per file (default 300000)
       --idle-timeout MS kill file after this long without output (default 120000)
       --retries N       rerun failed files, pass on retry = FLAKY (default 0)
       --min-free-mb N   wait for free disk on tmp root before spawning (default 1024)
       --shard i/n       run the i-th of n slices
+      --solo GLOB       run matching files alone, after the rest (repeatable)
+      --timings FILE    json of file durations: orders and balances shards by it, updated after the run
       --runtime CMD     child command (default bare)
   -b, --bail            stop on first failure`)
   process.exit(0)
 }
 
 const GRACE_MS = 2000
-const jobs = Math.max(
-  1,
-  Number(opts.jobs || process.env.BRITTLE_JOBS) || 2 * os.availableParallelism()
-)
+const jobs = Math.max(1, Number(opts.jobs || process.env.BRITTLE_JOBS) || os.availableParallelism())
 const timeoutMs = Number(opts.timeout)
 const idleMs = Number(opts['idle-timeout'])
 const retries = Number(opts.retries)
 const minFree = Number(opts['min-free-mb']) * 1024 * 1024
 const gha = !!process.env.GITHUB_ACTIONS
-const [runtime, ...runtimeArgs] = (opts.runtime || defaultRuntime()).split(' ')
+const [runtime, ...runtimeArgs] = (opts.runtime || 'bare').split(' ')
 
-function defaultRuntime() {
+let spawnBare = null
+if (!opts.runtime) {
   try {
-    return createRequire(path.join(process.cwd(), 'package.json'))('bare-runtime')()
-  } catch {
-    return 'bare'
-  }
+    spawnBare = createRequire(path.join(process.cwd(), 'package.json'))('bare-runtime/spawn')
+  } catch {}
 }
 
+let timings = {}
+if (opts.timings) {
+  try {
+    timings = JSON.parse(fs.readFileSync(opts.timings, 'utf8'))
+  } catch {}
+}
+const known = Object.values(timings).sort((a, b) => a - b)
+const median = known[known.length >> 1]
+
 let files = [
   ...new Set(
     fs
@@ -64,17 +73,26 @@ let files = [
       .filter((f) => !/^all\./.test(path.basename(f)) && fs.statSync(f).isFile())
   )
 ]
-  .map((f) => ({ f, size: fs.statSync(f).size }))
-  .sort((a, b) => b.size - a.size || a.f.localeCompare(b.f))
-  .map((x) => x.f)
+  .map((f) => ({ f, w: timings[f] ?? median ?? fs.statSync(f).size }))
+  .sort((a, b) => b.w - a.w || a.f.localeCompare(b.f))
 
 if (opts.shard) {
   const [i, n] = opts.shard.split('/').map(Number)
   if (!(i >= 1 && i <= n)) die(`bad --shard ${opts.shard}`)
-  files = files.filter((_, k) => k % n === i - 1)
+  const load = Array(n).fill(0)
+  files = files.filter((x) => {
+    const k = load.indexOf(Math.min(...load))
+    load[k] += x.w || 1
+    return k === i - 1
+  })
 }
+files = files.map((x) => x.f)
 if (files.length === 0) die('no test files matched')
 
+const soloSet = new Set(opts.solo ? fs.globSync(opts.solo) : [])
+const pool = files.filter((f) => !soloSet.has(f))
+const solo = files.filter((f) => soloSet.has(f))
+
 // ponytail: tmp root keyed by cwd, two concurrent runs in one cwd wipe each other. Key by pid if that happens.
 const cwdHash = crypto.createHash('sha1').update(process.cwd()).digest('hex').slice(0, 8)
 const tmpRoot = path.join(fs.realpathSync(os.tmpdir()), `brittle-jobs-${cwdHash}`)
@@ -133,7 +151,7 @@ function runOnce(file, slot) {
   return new Promise((resolve) => {
     const tmp = fs.mkdtempSync(path.join(tmpRoot, 'bb-'))
     const started = Date.now()
-    const child = spawn(runtime, [...runtimeArgs, file], {
+    const spawnOpts = {
       detached: true,
       stdio: ['ignore', 'pipe', 'pipe'],
       env: {
@@ -144,7 +162,10 @@ function runOnce(file, slot) {
         BRITTLE_JOBS_WORKER_ID: String(slot),
         JEST_WORKER_ID: String(slot)
       }
-    })
+    }
+    const child = spawnBare
+      ? spawnBare('bare', { ...spawnOpts, args: [file] })
+      : spawn(runtime, [...runtimeArgs, file], spawnOpts)
     const pid = child.pid
     if (pid) active.add(pid)
 
@@ -179,9 +200,14 @@ function runOnce(file, slot) {
     touch()
 
     let exit = null
+    let done = false
+    let closeTimer
     const finish = () => {
+      if (done) return
+      done = true
       clearTimeout(hardTimer)
       clearTimeout(idleTimer)
+      clearTimeout(closeTimer)
       active.delete(pid)
       fs.rmSync(tmp, { recursive: true, force: true })
       for (const w of waiters.splice(0)) w()
@@ -203,6 +229,11 @@ function runOnce(file, slot) {
     child.on('exit', (code, signal) => {
       exit = { code, signal }
       killGroup(pid, 'SIGKILL')
+      closeTimer = setTimeout(() => {
+        child.stdout.destroy()
+        child.stderr.destroy()
+        finish()
+      }, GRACE_MS)
     })
     child.on('close', () => exit && !exit.err && finish())
   })
@@ -233,25 +264,40 @@ function report(file, res) {
   if (gha) console.log(`::error file=${file}::${res.status}${reason}\n::group::${file} output`)
   console.log(res.output.trim())
   if (gha) console.log('::endgroup::')
-  if (opts.bail) stop = true
+  if (opts.bail) {
+    stop = true
+    for (const pid of active) killGroup(pid, 'SIGKILL')
+  }
 }
 
 const started = Date.now()
-console.log(`brittle-jobs: ${files.length} files, ${jobs} jobs, runtime ${runtime}`)
+console.log(
+  `brittle-jobs: ${files.length} files, ${jobs} jobs, runtime ${spawnBare ? 'bare-runtime' : runtime}`
+)
 
 let next = 0
 await Promise.all(
-  Array.from({ length: Math.min(jobs, files.length) }, async (_, i) => {
-    while (!stop && next < files.length) {
-      const file = files[next++]
+  Array.from({ length: Math.min(jobs, pool.length) }, async (_, i) => {
+    while (!stop && next < pool.length) {
+      const file = pool[next++]
       const res = await runFile(file, i + 1)
-      if (res) report(file, res)
+      if (res && !stop) report(file, res)
     }
   })
 )
+for (const file of solo) {
+  if (stop) break
+  const res = await runFile(file, 1)
+  if (res) report(file, res)
+}
 
 fs.rmSync(tmpRoot, { recursive: true, force: true })
 
+if (opts.timings) {
+  for (const r of results) if (r.status === 'PASS') timings[r.file] = Math.round(r.secs * 1000)
+  fs.writeFileSync(opts.timings, JSON.stringify(timings, Object.keys(timings).sort(), 2) + '\n')
+}
+
 const count = (s) => results.filter((r) => r.status === s).length
 const bad = results.filter((r) => r.status === 'FAIL' || r.status === 'HUNG')
 console.log(`\nslowest:`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "brittle-jobs",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Run brittle test files concurrently, one isolated process per file, with hang detection and tmp cleanup.",
   "type": "module",
   "bin": {
@@ -27,4 +27,4 @@
     "url": "git+https://github.com/matheus1lva/brittle-jobs.git"
   },
   "license": "MIT"
-}
+}