borp 0.19.0 → 0.20.1

package/CLAUDE.md

@@ -0,0 +1,61 @@
+# 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 standard linter with snazzy formatter
+- `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,45 +23,93 @@ 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 + '' },
-    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)
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "borp",
-  "version": "0.19.0",
+  "version": "0.20.1",
   "type": "module",
   "description": "node:test wrapper with TypeScript support",
   "main": "borp.js",
@@ -23,8 +23,8 @@
   "devDependencies": {
     "@matteo.collina/tspl": "^0.1.0",
     "@reporters/silent": "^1.2.4",
-    "@sinonjs/fake-timers": "^13.0.2",
-    "@types/node": "^22.2.0",
+    "@sinonjs/fake-timers": "^14.0.0",
+    "@types/node": "^24.0.14",
     "desm": "^1.3.0",
     "semver": "^7.6.3",
     "snazzy": "^9.0.0",

package/test/cli.test.js

@@ -7,6 +7,15 @@ import path from 'node:path'
 
 const borp = join(import.meta.url, '..', 'borp.js')
 
+// Debug logging for Windows troubleshooting
+console.log('[DEBUG] Environment info:', {
+  platform: process.platform,
+  nodeVersion: process.version,
+  cwd: process.cwd(),
+  borpPath: borp,
+  __dirname: import.meta.url
+})
+
 delete process.env.GITHUB_ACTION
 
 test('limit concurrency', async () => {
@@ -154,3 +163,216 @@ test('Post compile script should be executed when --post-compile  is sent with c
 
   strictEqual(stdout.indexOf('Post compile hook complete') >= 0, true, 'Post compile message should be found in stdout')
 })
+
+test('invalid option shows help text', async () => {
+  console.log('[DEBUG] Starting invalid option test')
+  const testCwd = join(import.meta.url, '..', 'fixtures', 'js-esm')
+  console.log('[DEBUG] Test CWD:', testCwd)
+  console.log('[DEBUG] Borp path:', borp)
+  console.log('[DEBUG] Command:', 'node', [borp, '--invalid-option'])
+
+  await rejects(async () => {
+    console.log('[DEBUG] About to execute execa')
+    const startTime = Date.now()
+    try {
+      const result = await execa('node', [borp, '--invalid-option'], {
+        cwd: testCwd,
+        timeout: 15000, // 15 second timeout
+        windowsHide: process.platform === 'win32'
+      })
+      console.log('[DEBUG] Unexpected success:', result)
+      throw new Error('Expected command to fail')
+    } catch (error) {
+      const elapsed = Date.now() - startTime
+      console.log(`[DEBUG] Execa threw error after ${elapsed}ms:`, {
+        exitCode: error.exitCode,
+        timedOut: error.timedOut,
+        stderr: error.stderr?.substring(0, 200) + '...',
+        stdout: error.stdout?.substring(0, 200) + '...',
+        message: error.message
+      })
+
+      throw error
+    }
+  }, (error) => {
+    console.log('[DEBUG] In error handler, validating error:', {
+      exitCode: error.exitCode,
+      stderrLength: error.stderr?.length,
+      stdoutLength: error.stdout?.length
+    })
+
+    // Should exit with code 1
+    console.log('[DEBUG] Checking exit code:', error.exitCode)
+    strictEqual(error.exitCode, 1)
+
+    // Should show error message
+    const hasErrorMessage = error.stderr.includes('Error: Unknown option \'--invalid-option\'')
+    console.log('[DEBUG] Has error message:', hasErrorMessage)
+    console.log('[DEBUG] Stderr content:', error.stderr)
+    strictEqual(hasErrorMessage, true, 'Should show error message')
+
+    // Should show help text
+    const hasUsage = error.stderr.includes('Usage: borp [options] [files...]')
+    console.log('[DEBUG] Has usage line:', hasUsage)
+    strictEqual(hasUsage, true, 'Should show usage line')
+
+    const hasHelp = error.stderr.includes('--help')
+    console.log('[DEBUG] Has help option:', hasHelp)
+    strictEqual(hasHelp, true, 'Should show help option')
+
+    const hasCoverage = error.stderr.includes('--coverage')
+    console.log('[DEBUG] Has coverage option:', hasCoverage)
+    strictEqual(hasCoverage, true, 'Should show coverage option')
+
+    const hasExamples = error.stderr.includes('Examples:')
+    console.log('[DEBUG] Has examples section:', hasExamples)
+    strictEqual(hasExamples, true, 'Should show examples section')
+
+    console.log('[DEBUG] All assertions passed')
+    return true
+  })
+  console.log('[DEBUG] Test completed successfully')
+})
+
+test('multiple invalid options show help text', async () => {
+  console.log('[DEBUG] Starting multiple invalid options test')
+  const testCwd = join(import.meta.url, '..', 'fixtures', 'js-esm')
+  console.log('[DEBUG] Test CWD:', testCwd)
+
+  await rejects(async () => {
+    console.log('[DEBUG] About to execute execa with multiple invalid options')
+    const result = await execa('node', [borp, '--foo', '--bar'], {
+      cwd: testCwd,
+      timeout: 15000,
+      windowsHide: false
+    })
+    console.log('[DEBUG] Unexpected success:', result)
+    throw new Error('Expected command to fail')
+  }, (error) => {
+    console.log('[DEBUG] Multiple options error handler:', {
+      exitCode: error.exitCode,
+      stderrLength: error.stderr?.length
+    })
+
+    // Should exit with code 1 and show help for first invalid option
+    strictEqual(error.exitCode, 1)
+    const hasFooError = error.stderr.includes('Error: Unknown option \'--foo\'')
+    console.log('[DEBUG] Has foo error:', hasFooError)
+    strictEqual(hasFooError, true, 'Should show error for first invalid option')
+
+    const hasUsage = error.stderr.includes('Usage: borp [options] [files...]')
+    console.log('[DEBUG] Has usage in multiple options:', hasUsage)
+    strictEqual(hasUsage, true, 'Should show help text')
+    return true
+  })
+  console.log('[DEBUG] Multiple options test completed')
+})
+
+test('invalid short option shows help text', async () => {
+  console.log('[DEBUG] Starting invalid short option test')
+  const testCwd = join(import.meta.url, '..', 'fixtures', 'js-esm')
+  console.log('[DEBUG] Test CWD:', testCwd)
+
+  await rejects(async () => {
+    console.log('[DEBUG] About to execute execa with invalid short option')
+    const result = await execa('node', [borp, '-z'], {
+      cwd: testCwd,
+      timeout: 15000,
+      windowsHide: process.platform === 'win32'
+    })
+    console.log('[DEBUG] Unexpected success:', result)
+    throw new Error('Expected command to fail')
+  }, (error) => {
+    console.log('[DEBUG] Short option error handler:', {
+      exitCode: error.exitCode,
+      stderrLength: error.stderr?.length
+    })
+
+    strictEqual(error.exitCode, 1)
+    const hasZError = error.stderr.includes('Error: Unknown option \'-z\'')
+    console.log('[DEBUG] Has -z error:', hasZError)
+    strictEqual(hasZError, true, 'Should show error message')
+
+    const hasUsage = error.stderr.includes('Usage: borp [options] [files...]')
+    console.log('[DEBUG] Has usage in short option:', hasUsage)
+    strictEqual(hasUsage, true, 'Should show help text')
+    return true
+  })
+  console.log('[DEBUG] Short option test completed')
+})
+
+test('--help option shows help text and exits successfully', async () => {
+  console.log('[DEBUG] Starting --help option test')
+  const testCwd = join(import.meta.url, '..', 'fixtures', 'js-esm')
+  console.log('[DEBUG] Test CWD:', testCwd)
+
+  const startTime = Date.now()
+  const { stdout, exitCode } = await execa('node', [borp, '--help'], {
+    cwd: testCwd,
+    timeout: 15000,
+    windowsHide: process.platform === 'win32'
+  })
+  const elapsed = Date.now() - startTime
+
+  console.log(`[DEBUG] --help completed after ${elapsed}ms:`, {
+    exitCode,
+    stdoutLength: stdout?.length,
+    stdoutPreview: stdout?.substring(0, 100) + '...'
+  })
+
+  strictEqual(exitCode, 0, 'Should exit with code 0')
+
+  const hasUsage = stdout.includes('Usage: borp [options] [files...]')
+  console.log('[DEBUG] --help has usage:', hasUsage)
+  strictEqual(hasUsage, true, 'Should show usage line')
+
+  const hasHelpOption = stdout.includes('--help')
+  console.log('[DEBUG] --help has help option:', hasHelpOption)
+  strictEqual(hasHelpOption, true, 'Should show help option')
+
+  const hasCoverage = stdout.includes('--coverage')
+  console.log('[DEBUG] --help has coverage:', hasCoverage)
+  strictEqual(hasCoverage, true, 'Should show coverage option')
+
+  const hasExamples = stdout.includes('Examples:')
+  console.log('[DEBUG] --help has examples:', hasExamples)
+  strictEqual(hasExamples, true, 'Should show examples section')
+
+  const hasCoverageExample = stdout.includes('borp --coverage')
+  console.log('[DEBUG] --help has coverage example:', hasCoverageExample)
+  strictEqual(hasCoverageExample, true, 'Should show coverage example')
+
+  console.log('[DEBUG] --help test completed')
+})
+
+test('-h option shows help text and exits successfully', async () => {
+  console.log('[DEBUG] Starting -h option test')
+  const testCwd = join(import.meta.url, '..', 'fixtures', 'js-esm')
+  console.log('[DEBUG] Test CWD:', testCwd)
+
+  const startTime = Date.now()
+  const { stdout, exitCode } = await execa('node', [borp, '-h'], {
+    cwd: testCwd,
+    timeout: 15000,
+    windowsHide: process.platform === 'win32'
+  })
+  const elapsed = Date.now() - startTime
+
+  console.log(`[DEBUG] -h completed after ${elapsed}ms:`, {
+    exitCode,
+    stdoutLength: stdout?.length,
+    stdoutPreview: stdout?.substring(0, 100) + '...'
+  })
+
+  strictEqual(exitCode, 0, 'Should exit with code 0')
+
+  const hasUsage = stdout.includes('Usage: borp [options] [files...]')
+  console.log('[DEBUG] -h has usage:', hasUsage)
+  strictEqual(hasUsage, true, 'Should show usage line')
+
+  const hasExamples = stdout.includes('Examples:')
+  console.log('[DEBUG] -h has examples:', hasExamples)
+  strictEqual(hasExamples, true, 'Should show examples section')
+
+  console.log('[DEBUG] -h test completed')
+})