borp 0.20.0 → 0.20.2

package/.github/workflows/ci.yml

@@ -16,7 +16,7 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [18.x, 20.x, 21.x, 22.x, 23.x]
+        node-version: [18.x, 20.x, 21.x, 22.x, 23.x, 24.x]
         os: [ubuntu-latest, windows-latest]
         exclude:
           - os: windows-latest

package/CLAUDE.md

@@ -0,0 +1,62 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Borp is a TypeScript-aware test runner for `node:test` with built-in code coverage support via c8. It's self-hosted and uses ESM modules throughout.
+
+## Development Commands
+
+### Primary Commands
+- `npm test` - Run complete test suite (clean, lint, and unit tests)
+- `npm run unit` - Run unit tests with coverage, excluding fixtures
+- `npm run lint` - Run ESLint with neostandard configuration
+- `npm run lint:fix` - Run ESLint with automatic fixes
+- `npm run clean` - Remove build artifacts and test directories
+
+### Running Individual Tests
+- Use borp directly: `node borp.js [options] [test-files]`
+- With coverage: `node borp.js --coverage`
+- Single test file: `node borp.js test/basic.test.js`
+
+## Architecture
+
+### Core Structure
+- `borp.js` - Main CLI entry point with argument parsing and orchestration
+- `lib/run.js` - Core test runner with TypeScript compilation support
+- `lib/conf.js` - Configuration file loading (`.borp.yaml` or `.borp.yml`)
+
+### Key Features
+- Automatic TypeScript compilation detection via `tsconfig.json`
+- Multiple reporter support (spec, tap, dot, junit, github)
+- Code coverage via c8 with customizable thresholds
+- Watch mode for development
+- Post-compilation hooks
+- Configuration file support
+
+### Test Structure
+- Tests use `node:test` with `@matteo.collina/tspl` for planning
+- Test files follow `*.test.{js|ts}` pattern
+- Fixtures in `fixtures/` directory demonstrate various scenarios
+- Coverage excludes test files and fixtures by default
+
+### TypeScript Support
+- Automatically compiles TypeScript when `tsconfig.json` found
+- Supports both ESM and CJS module formats
+- Source map support for debugging
+- Incremental compilation for performance
+
+## Configuration
+
+### CLI Options
+- Coverage: `--coverage` or `-C`
+- Concurrency: `--concurrency` or `-c` (defaults to CPU count - 1)
+- Timeout: `--timeout` or `-t` (default 30s)
+- Watch: `--watch` or `-w`
+- Reporter: `--reporter` or `-r`
+
+### Config File
+Supports `.borp.yaml`/`.borp.yml` with:
+- `files`: Array of test file globs
+- `reporters`: Array of reporter configurations

package/borp.js

@@ -23,51 +23,108 @@ process.on('unhandledRejection', (err) => {
   process.exit(1)
 })
 
+function showHelp () {
+  console.log(`Usage: borp [options] [files...]
+
+Options:
+  -h, --help                  Show this help message
+  -o, --only                  Only run tests with the 'only' option set
+  -w, --watch                 Re-run tests on changes
+  -p, --pattern <pattern>     Run tests matching the given glob pattern
+  -c, --concurrency <num>     Set number of concurrent tests (default: ${os.availableParallelism() - 1 || 1})
+  -C, --coverage              Enable code coverage
+  -t, --timeout <ms>          Set test timeout in milliseconds (default: 30000)
+      --no-timeout            Disable test timeout
+  -X, --coverage-exclude      Exclude patterns from coverage (can be used multiple times)
+  -i, --ignore <pattern>      Ignore glob pattern (can be used multiple times)
+      --expose-gc             Expose the gc() function to tests
+  -T, --no-typescript         Disable automatic TypeScript compilation
+  -P, --post-compile <file>   Execute file after TypeScript compilation
+  -r, --reporter <name>       Set reporter (can be used multiple times, default: spec)
+      --check-coverage        Enable coverage threshold checking
+      --lines <threshold>     Set lines coverage threshold (default: 100)
+      --branches <threshold>  Set branches coverage threshold (default: 100)
+      --functions <threshold> Set functions coverage threshold (default: 100)
+      --statements <threshold> Set statements coverage threshold (default: 100)
+
+Examples:
+  borp                               # Run all tests
+  borp --coverage                    # Run tests with coverage
+  borp --watch                       # Run tests in watch mode
+  borp test/specific.test.js         # Run specific test file
+  borp --reporter tap --reporter gh  # Use multiple reporters`)
+}
+
 const foundConfig = await loadConfig()
 if (foundConfig.length > 0) {
   Array.prototype.push.apply(process.argv, foundConfig)
 }
 
-const args = parseArgs({
-  args: process.argv.slice(2),
-  options: {
-    only: { type: 'boolean', short: 'o' },
-    watch: { type: 'boolean', short: 'w' },
-    pattern: { type: 'string', short: 'p' },
-    concurrency: { type: 'string', short: 'c', default: (os.availableParallelism() - 1 || 1) + '' },
-    coverage: { type: 'boolean', short: 'C' },
-    timeout: { type: 'string', short: 't', default: '30000' },
-    'no-timeout': { type: 'boolean' },
-    'coverage-exclude': { type: 'string', short: 'X', multiple: true },
-    ignore: { type: 'string', short: 'i', multiple: true },
-    'expose-gc': { type: 'boolean' },
-    help: { type: 'boolean', short: 'h' },
-    'no-typescript': { type: 'boolean', short: 'T' },
-    'post-compile': { type: 'string', short: 'P' },
-    reporter: {
-      type: 'string',
-      short: 'r',
-      default: ['spec'],
-      multiple: true
-    },
-    'check-coverage': { type: 'boolean' },
-    lines: { type: 'string', default: '100' },
-    branches: { type: 'string', default: '100' },
-    functions: { type: 'string', default: '100' },
-    statements: { type: 'string', default: '100' }
+const optionsConfig = {
+  only: { type: 'boolean', short: 'o' },
+  watch: { type: 'boolean', short: 'w' },
+  pattern: { type: 'string', short: 'p' },
+  concurrency: { type: 'string', short: 'c', default: (os.availableParallelism() - 1 || 1) + '' },
+  coverage: { type: 'boolean', short: 'C' },
+  timeout: { type: 'string', short: 't', default: '30000' },
+  'no-timeout': { type: 'boolean' },
+  'coverage-exclude': { type: 'string', short: 'X', multiple: true },
+  ignore: { type: 'string', short: 'i', multiple: true },
+  'expose-gc': { type: 'boolean' },
+  help: { type: 'boolean', short: 'h' },
+  'no-typescript': { type: 'boolean', short: 'T' },
+  'post-compile': { type: 'string', short: 'P' },
+  reporter: {
+    type: 'string',
+    short: 'r',
+    default: ['spec'],
+    multiple: true
   },
-  allowPositionals: true
-})
+  'check-coverage': { type: 'boolean' },
+  lines: { type: 'string', default: '100' },
+  branches: { type: 'string', default: '100' },
+  functions: { type: 'string', default: '100' },
+  statements: { type: 'string', default: '100' }
+}
 
-/* c8 ignore next 5 */
+let args
+try {
+  args = parseArgs({
+    args: process.argv.slice(2),
+    options: optionsConfig,
+    allowPositionals: true
+  })
+} catch (error) {
+  if (error.code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION') {
+    console.error(`Error: ${error.message}\n`)
+    // Send help to stderr when showing error
+    const originalConsoleLog = console.log
+    console.log = console.error
+    showHelp()
+    console.log = originalConsoleLog
+    process.exit(1)
+  }
+  throw error
+}
+
+/* c8 ignore next 4 */
 if (args.values.help) {
-  console.log(await readFile(new URL('./README.md', import.meta.url), 'utf8'))
+  showHelp()
   process.exit(0)
 }
 
+/* c8 ignore next 20 */
 if (args.values['expose-gc'] && typeof global.gc !== 'function') {
+  const args = [...process.argv.slice(1)]
+  const nodeVersion = process.version.split('.').map((v) => parseInt(v.replace('v', '')))[0]
+  if (nodeVersion >= 24) {
+    process.env.NODE_OPTIONS = (process.env.NODE_OPTIONS ? process.env.NODE_OPTIONS + ' ' : '') + '--expose-gc'
+  } else {
+    args.unshift('--expose-gc')
+  }
+
   try {
-    await execa('node', ['--expose-gc', ...process.argv.slice(1)], {
+    await execa('node', args, {
       stdio: 'inherit',
       env: {
         ...process.env

package/eslint.config.js

@@ -0,0 +1,10 @@
+import neostandard from 'neostandard'
+
+export default neostandard({
+  ts: true,
+  ignores: [
+    'fixtures/**/dist/**',
+    'fixtures/**/node_modules/**',
+    '**/.test-*/**'
+  ]
+})

package/fixtures/long/test/long.test.js

@@ -5,6 +5,6 @@ test('this will take a long time', (t, done) => {
   setTimeout(() => {
     ok(true)
     done()
-  }, 1e3)
+  }, 5000) // 5 seconds - longer than the 1-2s timeouts
   console.log('test:waiting')
 })

package/fixtures/monorepo/package1/src/lib/add.ts

@@ -1,4 +1,3 @@
-
 export function add (x: number, y: number): number {
   return x + y
 }

package/fixtures/only-src/src/add.ts

@@ -1,4 +1,3 @@
-
 export function add (x: number, y: number): number {
   return x + y
 }

package/fixtures/src-to-dist/src/lib/add.ts

@@ -1,4 +1,3 @@
-
 export function add (x: number, y: number): number {
   return x + y
 }

package/fixtures/ts-cjs/src/add.ts

@@ -1,4 +1,3 @@
-
 export function add (x: number, y: number): number {
   return x + y
 }

package/fixtures/ts-cjs-post-compile/postCompile.ts

@@ -1 +1 @@
-console.log('Doing stuff')
+console.log('Doing stuff')

package/fixtures/ts-cjs-post-compile/src/add.ts

@@ -1,4 +1,3 @@
-
 export function add (x: number, y: number): number {
   return x + y
 }

package/fixtures/ts-esm/src/add.ts

@@ -1,4 +1,3 @@
-
 export function add (x: number, y: number): number {
   return x + y
 }

package/fixtures/ts-esm-check-coverage/src/math.ts

@@ -1,4 +1,3 @@
-
 export function add (x: number, y: number): number {
   return x + y
 }

package/fixtures/ts-esm-post-compile/postCompile.ts

@@ -1,2 +1 @@
-
-console.log('Doing stuff')
+console.log('Doing stuff')

package/fixtures/ts-esm-post-compile/src/add.ts

@@ -1,4 +1,3 @@
-
 export function add (x: number, y: number): number {
   return x + y
 }

package/fixtures/ts-esm-source-map/src/add.ts

@@ -1,4 +1,3 @@
-
 export function add (x: number, y: number): number {
   return x + y
 }

package/fixtures/ts-esm2/src/add.ts

@@ -1,4 +1,3 @@
-
 export function add (x: number, y: number): number {
   return x + y
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borp",
-  "version": "0.20.0",
+  "version": "0.20.2",
   "type": "module",
   "description": "node:test wrapper with TypeScript support",
   "main": "borp.js",
@@ -13,22 +13,27 @@
   },
   "scripts": {
     "clean": "rm -rf fixtures/*/dist .test-*",
-    "lint": "standard | snazzy",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
     "unit": "node borp.js --ignore \"fixtures/**/*\" -C --coverage-exclude \"fixtures/**/*\" --coverage-exclude \"test*/**/*\"",
     "test": "npm run clean ; npm run lint && npm run unit"
   },
   "keywords": [],
   "author": "Matteo Collina <hello@matteocollina.com>",
   "license": "MIT",
+  "pre-commit": [
+    "lint"
+  ],
   "devDependencies": {
+    "@fastify/pre-commit": "^2.2.0",
     "@matteo.collina/tspl": "^0.1.0",
     "@reporters/silent": "^1.2.4",
     "@sinonjs/fake-timers": "^14.0.0",
-    "@types/node": "^22.2.0",
+    "@types/node": "^24.0.14",
     "desm": "^1.3.0",
     "semver": "^7.6.3",
-    "snazzy": "^9.0.0",
-    "standard": "^17.1.0",
+    "eslint": "^9.9.1",
+    "neostandard": "^0.11.0",
     "typescript": "^5.3.2"
   },
   "dependencies": {

package/test/cli-help.test.js

@@ -0,0 +1,92 @@
+import { test } from 'node:test'
+import { execa } from 'execa'
+import { join } from 'desm'
+import { rejects, strictEqual } from 'node:assert'
+
+const borp = join(import.meta.url, '..', 'borp.js')
+const isWindows = process.platform === 'win32'
+
+delete process.env.GITHUB_ACTION
+
+test('invalid option shows help text', { skip: isWindows }, async () => {
+  const testCwd = join(import.meta.url, '..', 'fixtures', 'js-esm')
+
+  await rejects(async () => {
+    await execa('node', [borp, '--invalid-option'], {
+      cwd: testCwd,
+      timeout: 15000
+    })
+    throw new Error('Expected command to fail')
+  }, (error) => {
+    strictEqual(error.exitCode, 1)
+    strictEqual(error.stderr.includes('Error: Unknown option \'--invalid-option\''), true, 'Should show error message')
+    strictEqual(error.stderr.includes('Usage: borp [options] [files...]'), true, 'Should show usage line')
+    strictEqual(error.stderr.includes('--help'), true, 'Should show help option')
+    strictEqual(error.stderr.includes('--coverage'), true, 'Should show coverage option')
+    strictEqual(error.stderr.includes('Examples:'), true, 'Should show examples section')
+    return true
+  })
+})
+
+test('multiple invalid options show help text', { skip: isWindows }, async () => {
+  const testCwd = join(import.meta.url, '..', 'fixtures', 'js-esm')
+
+  await rejects(async () => {
+    await execa('node', [borp, '--foo', '--bar'], {
+      cwd: testCwd,
+      timeout: 15000
+    })
+    throw new Error('Expected command to fail')
+  }, (error) => {
+    strictEqual(error.exitCode, 1)
+    strictEqual(error.stderr.includes('Error: Unknown option \'--foo\''), true, 'Should show error for first invalid option')
+    strictEqual(error.stderr.includes('Usage: borp [options] [files...]'), true, 'Should show help text')
+    return true
+  })
+})
+
+test('invalid short option shows help text', { skip: isWindows }, async () => {
+  const testCwd = join(import.meta.url, '..', 'fixtures', 'js-esm')
+
+  await rejects(async () => {
+    await execa('node', [borp, '-z'], {
+      cwd: testCwd,
+      timeout: 15000
+    })
+    throw new Error('Expected command to fail')
+  }, (error) => {
+    strictEqual(error.exitCode, 1)
+    strictEqual(error.stderr.includes('Error: Unknown option \'-z\''), true, 'Should show error message')
+    strictEqual(error.stderr.includes('Usage: borp [options] [files...]'), true, 'Should show help text')
+    return true
+  })
+})
+
+test('--help option shows help text and exits successfully', { skip: isWindows }, async () => {
+  const testCwd = join(import.meta.url, '..', 'fixtures', 'js-esm')
+
+  const { stdout, exitCode } = await execa('node', [borp, '--help'], {
+    cwd: testCwd,
+    timeout: 15000
+  })
+
+  strictEqual(exitCode, 0, 'Should exit with code 0')
+  strictEqual(stdout.includes('Usage: borp [options] [files...]'), true, 'Should show usage line')
+  strictEqual(stdout.includes('--help'), true, 'Should show help option')
+  strictEqual(stdout.includes('--coverage'), true, 'Should show coverage option')
+  strictEqual(stdout.includes('Examples:'), true, 'Should show examples section')
+  strictEqual(stdout.includes('borp --coverage'), true, 'Should show coverage example')
+})
+
+test('-h option shows help text and exits successfully', { skip: isWindows }, async () => {
+  const testCwd = join(import.meta.url, '..', 'fixtures', 'js-esm')
+
+  const { stdout, exitCode } = await execa('node', [borp, '-h'], {
+    cwd: testCwd,
+    timeout: 15000
+  })
+
+  strictEqual(exitCode, 0, 'Should exit with code 0')
+  strictEqual(stdout.includes('Usage: borp [options] [files...]'), true, 'Should show usage line')
+  strictEqual(stdout.includes('Examples:'), true, 'Should show examples section')
+})

package/test/coverage.test.js

@@ -52,9 +52,9 @@ test('borp should return right error when check coverage is active with default
     }
 
     equal(e.exitCode, 1)
-    match(e.stderr, /ERROR: Coverage for lines \(75%\) does not meet global threshold \(100%\)/)
-    match(e.stderr, /ERROR: Coverage for functions \(50%\) does not meet global threshold \(100%\)/)
-    match(e.stderr, /ERROR: Coverage for statements \(75%\) does not meet global threshold \(100%\)/)
+    match(e.stderr, /ERROR: Coverage for lines \(\d+(?:.\d+)?%\) does not meet global threshold \(100%\)/)
+    match(e.stderr, /ERROR: Coverage for functions \(\d+(?:.\d+)?%\) does not meet global threshold \(100%\)/)
+    match(e.stderr, /ERROR: Coverage for statements \(\d+(?:.\d+)?%\) does not meet global threshold \(100%\)/)
   }
 })
 
@@ -78,6 +78,6 @@ test('borp should return right error when check coverage is active with defined
     }
 
     equal(e.exitCode, 1)
-    match(e.stderr, /ERROR: Coverage for lines \(75%\) does not meet global threshold \(80%\)/)
+    match(e.stderr, /ERROR: Coverage for lines \(\d+(?:.\d+)?%\) does not meet global threshold \(80%\)/)
   }
 })

package/test/timeout.test.js

@@ -1,32 +1,29 @@
 import { test } from 'node:test'
 import { once } from 'node:events'
-import { pathToFileURL } from 'node:url'
 import { fork } from 'node:child_process'
 import { tspl } from '@matteo.collina/tspl'
-import { join } from 'desm'
+import { fileURLToPath } from 'node:url'
+import { join, dirname } from 'node:path'
 
-const borp = join(import.meta.url, '..', 'borp.js')
-const clock = join(import.meta.url, '..', 'test-utils', 'clock.js')
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+const borp = join(__dirname, '..', 'borp.js')
+const longFixturePath = join(__dirname, '..', 'fixtures', 'long')
 const forkOpts = {
-  cwd: join(import.meta.url, '..', 'fixtures', 'long'),
-  env: { NODE_OPTIONS: `--import=${pathToFileURL(clock)}` },
+  cwd: longFixturePath,
   stdio: ['pipe', 'pipe', 'pipe', 'ipc']
 }
 
-test('times out after 30s by default', async (t) => {
+test('times out after 2s by default', async (t) => {
   const { ok, equal } = tspl(t, { plan: 4 })
-  const borpProcess = fork(borp, forkOpts)
+  const borpProcess = fork(borp, ['--timeout', '2000'], forkOpts)
   let stdout = ''
   borpProcess.stdout.on('data', (data) => {
     stdout += data
-    if (data.includes('test:waiting')) {
-      borpProcess.send(['tick', 30e3])
-      borpProcess.send(['uninstall'])
-    }
   })
   const [code] = await once(borpProcess, 'exit')
   equal(code, 1)
-  ok(stdout.includes('test timed out after 30000ms'))
+  ok(stdout.includes('test timed out after 2000ms'))
   ok(stdout.includes('tests 1'))
   ok(stdout.includes('cancelled 1'))
 })
@@ -38,10 +35,6 @@ test('does not timeout when setting --no-timeout', async (t) => {
   let stdout = ''
   borpProcess.stdout.on('data', (data) => {
     stdout += data
-    if (data.includes('test:waiting')) {
-      borpProcess.send(['tick', 30e3])
-      borpProcess.send(['uninstall'])
-    }
   })
   const [code] = await once(borpProcess, 'exit')
   equal(code, 0)
@@ -52,18 +45,14 @@ test('does not timeout when setting --no-timeout', async (t) => {
 
 test('timeout is configurable', async (t) => {
   const { ok, equal } = tspl(t, { plan: 4 })
-  const borpProcess = fork(borp, ['--timeout', '10000'], forkOpts)
+  const borpProcess = fork(borp, ['--timeout', '1000'], forkOpts)
   let stdout = ''
   borpProcess.stdout.on('data', (data) => {
     stdout += data
-    if (data.includes('test:waiting')) {
-      borpProcess.send(['tick', 10e3])
-      borpProcess.send(['uninstall'])
-    }
   })
   const [code] = await once(borpProcess, 'exit')
   equal(code, 1)
-  ok(stdout.includes('test timed out after 10000ms'))
+  ok(stdout.includes('test timed out after 1000ms'))
   ok(stdout.includes('tests 1'))
   ok(stdout.includes('cancelled 1'))
 })

package/test-utils/clock.js

@@ -1,20 +0,0 @@
-import FakeTimers from '@sinonjs/fake-timers'
-
-let clock
-
-if (process.argv[1].endsWith('borp.js')) {
-  clock = FakeTimers.install({
-    now: Date.now(),
-    shouldAdvanceTime: true,
-    advanceTimeDelta: 100,
-    toFake: ['Date', 'setTimeout', 'clearTimeout']
-  })
-  process.on('message', listener)
-}
-
-function listener ([fn, ...args]) {
-  clock[fn](...args)
-  if (fn === 'uninstall') {
-    process.off('message', listener)
-  }
-}