brittle-jobs 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 matheus1lva
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,87 @@
+# brittle-jobs
+
+Run [brittle](https://github.com/holepunchto/brittle) test files concurrently, one process per file, on Node or Bare.
+
+## Installation
+
+```bash
+npm install --save-dev brittle-jobs
+```
+
+`brittle` is a peer dependency: the consumer's install is what runs each file.
+
+## Usage
+
+```bash
+brittle-jobs test/*.js
+brittle-jobs --bare -j 4 test/all.ts
+```
+
+```
+brittle-jobs [flags] <files...>
+
+  --bare              run test files with bare instead of node
+  --jobs|-j <n>       test files to run concurrently (positive integer; default: all cores)
+  --bail|-b           bail on first assert failure and stop scheduling files
+  --timeout|-t <ms>   per-test timeout passed to brittle
+```
+
+Each file runs as `<node|bare> brittle/cmd.js [--bail] [--timeout ms] <file>`, exactly what
+`brittle-node`/`brittle-bare` do, so per-file semantics are unchanged. `bare` is resolved on `PATH`
+(npm and bun scripts put `node_modules/.bin` there).
+
+Output is one line per file as it finishes, the full spec-formatted TAP for any file that fails, and a
+summary. Exit code is 1 when any file fails its TAP or exits non-zero.
+
+```
+200 files · bare · jobs=10
+
+✓ test/basic/chat.ts · 12 tests · 3.2s
+✗ test/basic/boot.ts · 4.1s
+    ...
+198/200 files passed · 1840 tests · 61.3s
+failed: test/basic/boot.ts, test/api/mesh.ts
+```
+
+### Runner files
+
+A generated runner containing only the declarative wrapper emitted by `brittle-make-test` is expanded
+into the files it loads instead of being run as one process. A line prefixed with `if (isBare)` is
+skipped when running on node:
+
+```js
+const isBare = typeof Bare !== 'undefined'
+
+await test.load(import.meta.resolve('./basic/chat.ts'))
+if (isBare) await test.load(import.meta.resolve('./tui/keys.ts'))
+```
+
+The runner file stays a valid brittle entrypoint, so `bare test/all.ts` still works serially. A file
+with setup, inline tests, comments, unsupported guards, or other unrecognized source runs as one
+process so its behavior stays intact. A runner with no applicable loads also runs as one process; a
+file that emits incomplete or no TAP counts as failed.
+
+`--jobs` limits the number of test file processes running at once. The default is the available CPU
+parallelism, and each process uses the selected runtime (`node` or `bare`).
+
+## API
+
+```js
+const run = require('brittle-jobs')
+
+const { passed, failed, results } = await run(['test/all.ts'], {
+  bare: false,
+  jobs: 4,
+  bail: false,
+  timeout: 30000,
+  cwd: process.cwd(),
+  out: process.stdout
+})
+```
+
+`results` holds one entry per file: `{ file, results, code, signal, stderr, failed, ms }`, where
+`results` is a [prettytap](https://www.npmjs.com/package/prettytap) `Results`.
+
+## License
+
+MIT

package/bin.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+const process = require('process')
+const paparam = require('paparam')
+const run = require('./index')
+
+const cmd = paparam
+  .command(
+    'brittle-jobs',
+    paparam.flag('--bare', 'Run test files with bare instead of node'),
+    paparam.flag('--jobs|-j <n>', 'Test files to run concurrently (default: all cores)'),
+    paparam.flag('--bail|-b', 'Bail on first assert failure and stop scheduling files'),
+    paparam.flag('--timeout|-t <ms>', 'Per-test timeout passed to brittle'),
+    paparam.rest('<files>'),
+    paparam.bail((bail) => {
+      console.error(bail.reason)
+      console.error(bail.command.usage())
+      process.exit(1)
+    })
+  )
+  .parse()
+
+if (!cmd) process.exit(0)
+if (cmd.rest.length === 0) {
+  console.error('Error: No test files were specified')
+  process.exit(1)
+}
+
+const { bare, jobs, bail, timeout } = cmd.flags
+let parsedJobs
+if (jobs !== undefined) {
+  parsedJobs = Number(jobs)
+  try {
+    run.validateJobs(parsedJobs)
+  } catch {
+    console.error(`Error: --jobs must be a positive safe integer`)
+    process.exit(1)
+  }
+}
+
+run(cmd.rest, {
+  bare,
+  bail,
+  jobs: parsedJobs,
+  timeout: timeout ? Number(timeout) : undefined
+})
+  .then(({ failed }) => {
+    if (failed && !process.exitCode) process.exitCode = 1
+  })
+  .catch((err) => {
+    console.error(`Error: ${err.message}`)
+    process.exitCode = 1
+  })

package/index.js

@@ -0,0 +1,116 @@
+const os = require('os')
+const path = require('path')
+const expand = require('./lib/manifest')
+const runFile = require('./lib/child')
+const report = require('./lib/report')
+
+module.exports = async function run(files, opts = {}) {
+  const cwd = opts.cwd ?? process.cwd()
+  const out = opts.out ?? process.stdout
+  const bare = !!opts.bare
+  const jobs = opts.jobs ?? os.availableParallelism()
+  validateJobs(jobs)
+  const runtime = bare ? 'bare' : process.execPath
+
+  const args = [require.resolve('brittle/cmd.js', { paths: [cwd] })]
+  if (opts.bail) args.push('--bail')
+  if (opts.timeout) args.push('--timeout', String(opts.timeout))
+
+  const queue = files.flatMap((file) => expand(path.resolve(cwd, file), { bare }))
+  const total = queue.length
+  const results = []
+  const running = new Set()
+  const start = Date.now()
+  let stop = false
+
+  const abort = () => {
+    stop = true
+    for (const r of running) {
+      try {
+        r.kill()
+      } catch {}
+    }
+    process.exitCode = 130
+  }
+  let listenerInstalled = false
+
+  try {
+    process.once('SIGINT', abort)
+    listenerInstalled = true
+
+    out.write(report.header({ total, runtime, jobs }))
+
+    await new Promise((resolve, reject) => {
+      let settled = false
+
+      const stopWithError = (err) => {
+        if (settled) return
+        stop = true
+        const pending = []
+        for (const r of running) {
+          try {
+            r.kill()
+          } catch {}
+          pending.push(Promise.resolve(r.promise).catch(() => {}))
+        }
+        settled = true
+        Promise.all(pending).then(() => {
+          running.clear()
+          reject(err)
+        })
+      }
+
+      const next = () => {
+        if (settled) return
+        if (running.size === 0 && (stop || queue.length === 0)) {
+          settled = true
+          resolve()
+          return
+        }
+        while (!stop && running.size < jobs && queue.length > 0) {
+          let r
+          try {
+            r = runFile(queue.shift(), { runtime, args, cwd })
+          } catch (err) {
+            stopWithError(err)
+            return
+          }
+          running.add(r)
+          Promise.resolve(r.promise).then((res) => {
+            if (settled) return
+            running.delete(r)
+            try {
+              results.push(res)
+              out.write(report.line(res, cwd))
+              if (res.failed) {
+                out.write(report.detail(res))
+                if (opts.bail) stop = true
+              }
+            } catch (err) {
+              stopWithError(err)
+              return
+            }
+            next()
+          }, stopWithError)
+        }
+      }
+
+      next()
+    })
+
+    out.write(report.summary(results, { total, ms: Date.now() - start, cwd }))
+  } finally {
+    if (listenerInstalled) process.off('SIGINT', abort)
+  }
+
+  const failed = results.filter((r) => r.failed).length
+  return { passed: results.length - failed, failed, results }
+}
+
+function validateJobs(jobs) {
+  if (typeof jobs !== 'number' || !Number.isSafeInteger(jobs) || jobs < 1) {
+    throw new TypeError('jobs must be a positive safe integer')
+  }
+}
+
+module.exports.validateJobs = validateJobs

package/lib/child.js

@@ -0,0 +1,66 @@
+const path = require('path')
+const { spawn } = require('child_process')
+const { Parser } = require('prettytap')
+
+const planLine = /^1\.\.(\d+)$/
+const resultLine = /^(?:not )?ok\b/
+
+function validateTap(results) {
+  // An empty stream is handled by the existing "no TAP output" report. Do not
+  // turn that into a second, less useful validation error.
+  if (!results.foundTapData) return null
+
+  const header = results.lines.findIndex((line) => /^TAP version \d+$/.test(line))
+  const tapLines = results.lines.slice(header + 1)
+  const plans = tapLines.map((line) => line.match(planLine)).filter(Boolean)
+  if (plans.length === 0) return 'missing TAP plan'
+  if (plans.length > 1) return 'multiple TAP plans'
+
+  const expectedTests = Number(plans[0][1])
+  if (!Number.isSafeInteger(expectedTests)) return 'invalid TAP plan count'
+  const observedTests = tapLines.filter((line) => resultLine.test(line)).length
+  if (observedTests !== expectedTests) {
+    return `TAP plan expected ${expectedTests} tests but observed ${observedTests}`
+  }
+
+  return null
+}
+
+module.exports = function runFile(file, { runtime, args, cwd }) {
+  const start = Date.now()
+  const child = spawn(runtime, [...args, path.relative(cwd, file)], {
+    cwd,
+    stdio: ['ignore', 'pipe', 'pipe']
+  })
+  const parser = new Parser()
+  let stderr = ''
+
+  child.stdout.setEncoding('utf8').on('data', (chunk) => parser.write(chunk))
+  child.stderr.setEncoding('utf8').on('data', (chunk) => {
+    stderr += chunk
+  })
+
+  const promise = new Promise((resolve) => {
+    let settled = false
+    const done = (code, signal) => {
+      if (settled) return
+      settled = true
+      parser.end()
+      const results = parser.results
+      const validationError = validateTap(results)
+      if (validationError !== null) {
+        results.validationError = validationError
+        stderr += `TAP validation failed: ${validationError}\n`
+      }
+      const failed =
+        !results.isPassing() || validationError !== null || code !== 0 || signal !== null
+      resolve({ file, results, code, signal, stderr, failed, ms: Date.now() - start })
+    }
+    child.on('error', (err) => {
+      stderr += err.message + '\n'
+    })
+    child.on('close', done)
+  })
+
+  return { promise, kill: () => child.kill() }
+}

package/lib/manifest.js

@@ -0,0 +1,105 @@
+const fs = require('fs')
+const { fileURLToPath, pathToFileURL } = require('url')
+
+const HEADER = '// This runner is auto-generated by Brittle'
+const IMPORT = /^const test = \(await import\((['"])brittle\1\)\)\.default;?$/
+const FUNCTION = /^async\s+function runTests\s*\(\s*\)\s*\{$/
+const LOAD = /^(if \(isBare\) )?await test\.load\(import\.meta\.resolve\((['"])([^'"]+)\2\)\);?$/
+
+module.exports = function expand(file, { bare }) {
+  const specifiers = parse(fs.readFileSync(file, 'utf8'))
+  if (specifiers === null) return [file]
+
+  const files = []
+  for (const { guarded, specifier } of specifiers) {
+    if (guarded && !bare) continue
+    const resolved = resolve(file, specifier)
+    if (resolved === null) return [file]
+    files.push(resolved)
+  }
+  return files.length > 0 ? files : [file]
+}
+
+// Recognize only the small declarative wrapper emitted by brittle-make-test.
+// Anything else must run as the original file so setup and inline tests remain
+// in the same process and unsupported control flow is never guessed at.
+function parse(source) {
+  const lines = source.split(/\r?\n/)
+  let i = 0
+
+  const blank = () => {
+    while (i < lines.length && lines[i].trim() === '') i++
+  }
+  const line = (pattern) => {
+    if (i >= lines.length || !pattern.test(lines[i].trim())) return false
+    i++
+    return true
+  }
+
+  blank()
+  if (lines[i]?.trim() === HEADER) i++
+  blank()
+  if (!line(/^await runTests\(\);?$/)) return null
+  blank()
+  if (!line(FUNCTION)) return null
+  blank()
+  if (!line(IMPORT)) return null
+  blank()
+  if (!line(/^test\.pause\(\);?$/)) return null
+
+  blank()
+  let hasIsBare = false
+  if (line(/^const isBare = typeof Bare !== (['"])undefined\1;?$/)) {
+    hasIsBare = true
+    blank()
+  }
+
+  const loads = []
+  let hasGuardedLoad = false
+  while (i < lines.length) {
+    const current = lines[i].trim()
+    if (current === '') {
+      blank()
+      continue
+    }
+    if (current === 'test.resume()' || current === 'test.resume();') break
+
+    const match = LOAD.exec(current)
+    if (!match) return null
+    if (match[1]) hasGuardedLoad = true
+    loads.push({ guarded: !!match[1], specifier: match[3] })
+    i++
+  }
+
+  if (!line(/^test\.resume\(\);?$/)) return null
+  blank()
+  if (!line(/^}$/)) return null
+  blank()
+  if (i !== lines.length) return null
+  if (hasGuardedLoad && !hasIsBare) return null
+  return loads
+}
+
+function resolve(file, specifier) {
+  // Keep the accepted subset equivalent to import.meta.resolve for relative
+  // file specifiers. A process can only be started with a filesystem path.
+  // The recognizer intentionally does not decode JavaScript string escapes.
+  // Reject them rather than resolving a different path from the runner.
+  if (
+    specifier.includes('\\') ||
+    (specifier !== '.' &&
+      specifier !== '..' &&
+      !specifier.startsWith('./') &&
+      !specifier.startsWith('../'))
+  ) {
+    return null
+  }
+
+  try {
+    const url = new URL(specifier, pathToFileURL(file))
+    if (url.protocol !== 'file:' || url.hostname || url.search || url.hash) return null
+    return fileURLToPath(url)
+  } catch {
+    return null
+  }
+}

package/lib/report.js

@@ -0,0 +1,42 @@
+const path = require('path')
+const { SpecFormatter, bold, faint, green, red } = require('prettytap')
+
+const secs = (ms) => (ms / 1000).toFixed(1) + 's'
+const indent = (text) =>
+  text
+    .split('\n')
+    .map((line) => (line ? '    ' + line : line))
+    .join('\n')
+
+function header({ total, runtime, jobs }) {
+  return faint(`${total} files · ${path.basename(runtime)} · jobs=${jobs}`) + '\n\n'
+}
+
+function line(res, cwd) {
+  const name = path.relative(cwd, res.file)
+  if (res.failed) return `${red('✗')} ${bold(name)} ${faint('· ' + secs(res.ms))}\n`
+  return `${green('✓')} ${name} ${faint(`· ${res.results.expectedTests} tests · ${secs(res.ms)}`)}\n`
+}
+
+function detail(res) {
+  let out = ''
+  if (res.results.foundTapData) {
+    const spec = new SpecFormatter()
+    out += spec.formatToString(res.results) + spec.summaryToString()
+  }
+  out += res.stderr
+  if (!res.results.foundTapData) out += red('no TAP output') + '\n'
+  if (res.code !== 0) out += red(`runner exited: ${res.signal ?? res.code}`) + '\n'
+  return indent(out.trimEnd()) + '\n\n'
+}
+
+function summary(results, { total, ms, cwd }) {
+  const failed = results.filter((r) => r.failed)
+  const tests = results.reduce((n, r) => n + Math.max(r.results.expectedTests, 0), 0)
+  const color = failed.length ? red : green
+  const out = `\n${color(bold(`${results.length - failed.length}/${total} files passed`))} ${faint(`· ${tests} tests · ${secs(ms)}`)}\n`
+  if (failed.length === 0) return out
+  return out + red('failed: ') + failed.map((r) => path.relative(cwd, r.file)).join(', ') + '\n'
+}
+
+module.exports = { header, line, detail, summary }

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "brittle-jobs",
+  "version": "0.1.0",
+  "description": "Run brittle test files concurrently, one process per file, on Node or Bare.",
+  "main": "index.js",
+  "bin": {
+    "brittle-jobs": "bin.js"
+  },
+  "files": [
+    "index.js",
+    "bin.js",
+    "lib"
+  ],
+  "scripts": {
+    "test": "brittle-node test/index.js",
+    "lint": "prettier . --check && lunte",
+    "format": "prettier . --write"
+  },
+  "prettier": "prettier-config-holepunch",
+  "dependencies": {
+    "paparam": "^1.13.0",
+    "prettytap": "^0.2.0"
+  },
+  "peerDependencies": {
+    "brittle": ">=4"
+  },
+  "devDependencies": {
+    "bare-runtime": "^1.30.0",
+    "brittle": "^4.1.0",
+    "lunte": "^1.8.4",
+    "prettier": "^3.6.2",
+    "prettier-config-holepunch": "^2.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/matheus1lva/brittle-jobs.git"
+  },
+  "license": "MIT"
+}