@cldmv/vitest-runner 1.1.0 → 1.4.2

package/README.md

@@ -7,7 +7,7 @@ Sequential Vitest runner that spawns each test file in its own child process to
 - Auto-detects your vitest config; accepts an explicit path if needed
 - All standard Vitest CLI flags are forwarded unchanged
 - Usable as a **CLI binary** or as a **programmatic Node.js API**
-- Pure ESM with a CJS shim for `require()` compatibility
+- Pure ESM source, bundled to a real CJS build for `require()` compatibility
 
 [![npm version]][npm_version_url] [![npm downloads]][npm_downloads_url] <!-- [![GitHub release]][github_release_url] -->[![GitHub downloads]][github_downloads_url] [![Last commit]][last_commit_url] <!-- [![Release date]][release_date_url] -->[![npm last update]][npm_last_update_url] [![Coverage]][coverage_url]
 
@@ -15,6 +15,24 @@ Sequential Vitest runner that spawns each test file in its own child process to
 
 ---
 
+## ✨ What's New
+
+### Latest: v1.4.0 (September 2026)
+
+- **A real build, and a CLI that finally works when installed** — `dist/` (library) and `bin/` (CLI) are now bundled with tsup instead of hand-written; a one-character npm packaging bug that silently stripped the `bin` field is fixed, so `vitest-runner` now works as an installed command for the first time.
+- **Runner-owned scratch directories** — a per-run scratch root is created and cleaned up automatically, with a `makeRunTmpDir(label)` helper for test files instead of managing your own `mkdtemp` base.
+- **CI/release automation completed** — the v4 staging-branch workflow set is now full (auto-merging the release PR on approval, `dependabot.yml`, and the rest), and every file header is normalized.
+- [View full v1.4.0 Changelog](https://github.com/CLDMV/vitest-runner/blob/master/docs/changelog/v1/v1.4.0.md)
+
+### Recent Releases
+
+- **v1.3.3** (September 2026) — Dependency bump (`brace-expansion`, `postcss`) via Dependabot.
+- **v1.3.2** (September 2026) — CI: pass `BOT_NAME`/`BOT_EMAIL` through to the v4 release/feature-PR workflows.
+- **v1.3.0** (July 2026) — Onboarded onto the CLDMV v4 staging-branch release flow.
+- **v1.2.0** (June 2026) — Added coverage `blobsDir` + `mergeReports` options.
+
+---
+
 ## Requirements
 
 - Node.js ≥ 18
@@ -45,20 +63,24 @@ vitest-runner [OPTIONS] [PATTERNS...]
 
 ### Runner flags
 
-| Flag | Description |
-|------|-------------|
-| `--test-list <file>` | Run only the files listed in a JSON array file instead of scanning |
-| `--file-pattern <regex>` | Override the file discovery regex (default: `\.test\.vitest\.(?:js\|mjs\|cjs)$`) |
-| `--workers <n>` | Number of parallel workers (default: `4` or `VITEST_WORKERS`) |
-| `--solo-pattern <pat>` | Run files matching this path substring solo (one at a time) before the worker pool; repeatable |
-| `--no-error-details` | Hide inline error blocks — show only counts in the summary |
-| `--coverage-quiet` | Implies `--coverage`; suppress per-file output and show only a live progress bar and final summaries |
-| `--log-file <path>` | Write a clean (ANSI-stripped) copy of all output to this file. Defaults to `coverage/coverage-run.log` when `--coverage-quiet` is active |
-| `--suppress-file-output` | Suppress per-file runner output blocks in any mode |
-| `--suppress-passing-files` | Hide the `PASSED TEST FILES` section in the final summary |
-| `--no-top-summary` | Hide `TOP MEMORY USERS` and `TOP DURATION` summary sections |
-| `--json` | Print a JSON run report (no runner text output) |
-| `--help`, `-h` | Print this help and exit |
+| Flag                       | Description                                                                                                                              |
+| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
+| `--test-list <file>`       | Run only the files listed in a JSON array file instead of scanning                                                                       |
+| `--file-pattern <regex>`   | Override the file discovery regex (default: `\.test\.vitest\.(?:js\|mjs\|cjs)$`)                                                         |
+| `--workers <n>`            | Number of parallel workers (default: `4` or `VITEST_WORKERS`)                                                                            |
+| `--solo-pattern <pat>`     | Run files matching this path substring solo (one at a time) before the worker pool; repeatable                                           |
+| `--no-error-details`       | Hide inline error blocks — show only counts in the summary                                                                               |
+| `--coverage-quiet`         | Implies `--coverage`; suppress per-file output and show only a live progress bar and final summaries                                     |
+| `--log-file <path>`        | Write a clean (ANSI-stripped) copy of all output to this file. Defaults to `coverage/coverage-run.log` when `--coverage-quiet` is active |
+| `--suppress-file-output`   | Suppress per-file runner output blocks in any mode                                                                                       |
+| `--suppress-passing-files` | Hide the `PASSED TEST FILES` section in the final summary                                                                                |
+| `--no-top-summary`         | Hide `TOP MEMORY USERS` and `TOP DURATION` summary sections                                                                              |
+| `--json`                   | Print a JSON run report (no runner text output)                                                                                          |
+| `--blobs-dir <path>`       | Directory for per-file coverage blobs (default: `.vitest-coverage-blobs`, relative to `cwd`)                                             |
+| `--no-merge-reports`       | Produce the coverage blobs but skip the merge and summary, leaving them in `--blobs-dir` for an external merge step                      |
+| `--keep-tmp`               | Keep this run's scratch directory instead of removing it on completion                                                                   |
+| `--scratch-dir <path>`     | Per-run scratch root, relative to `cwd` (default: `tmp/vitest-runner`)                                                                   |
+| `--help`, `-h`             | Print this help and exit                                                                                                                 |
 
 ### Test patterns
 
@@ -95,10 +117,10 @@ vitest-runner --bail
 
 ### Environment variables
 
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `VITEST_HEAP_MB` | *(none)* | `--max-old-space-size` ceiling passed to every child process |
-| `VITEST_WORKERS` | `4` | Maximum parallel worker slots in the non-solo phase (overridden by `--workers`) |
+| Variable         | Default  | Description                                                                     |
+| ---------------- | -------- | ------------------------------------------------------------------------------- |
+| `VITEST_HEAP_MB` | _(none)_ | `--max-old-space-size` ceiling passed to every child process                    |
+| `VITEST_WORKERS` | `4`      | Maximum parallel worker slots in the non-solo phase (overridden by `--workers`) |
 
 ### Examples
 
@@ -145,10 +167,10 @@ vitest-runner --json --no-top-summary
 ## Programmatic API
 
 ```js
-import { run } from 'vitest-runner';
+import { run } from "vitest-runner";
 
 // CommonJS
-const { run } = await require('vitest-runner');
+const { run } = require("vitest-runner");
 ```
 
 ### `run(options)` → `Promise<number | object>`
@@ -156,10 +178,10 @@ const { run } = await require('vitest-runner');
 Runs the test suite and resolves with an exit code (`0` = all passed, `1` = any failure) by default. When `json: true` is passed, it returns a structured JSON report object (including `exitCode`) instead of printing runner text output.
 
 ```js
-import { run } from 'vitest-runner';
+import { run } from "vitest-runner";
 
 const code = await run({
-  testDir: 'src/tests',
+	testDir: "src/tests"
 });
 
 process.exit(code);
@@ -167,33 +189,54 @@ process.exit(code);
 
 #### Options
 
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `cwd` | `string` | `process.cwd()` | Absolute project root directory |
-| `testDir` | `string` | `cwd` | Directory (absolute or relative to `cwd`) to scan for `*.test.vitest.{js,mjs}` files |
-| `vitestConfig` | `string` | auto-detect | Explicit vitest config path; when omitted the runner walks standard config names (`vitest.config.ts`, `vite.config.ts`, etc.) relative to `cwd` |
-| `testPatterns` | `string[]` | `[]` | File / folder patterns to filter — empty means all files in `testDir` |
-| `testListFile` | `string` | `undefined` | Path to a JSON array of test file paths; when set, scanning is skipped entirely |
-| `testFilePattern` | `RegExp` | `DEFAULT_TEST_FILE_PATTERN` | Regex matched against file names during discovery (`*.test.vitest.{js,mjs,cjs}` by default) |
-| `vitestArgs` | `string[]` | `[]` | Extra CLI args forwarded verbatim to every vitest invocation |
-| `showErrorDetails` | `boolean` | `true` | Print inline error blocks under each failed file in the summary |
-| `coverageQuiet` | `boolean` | `false` | Suppress per-file output; show only the progress bar and final summaries |
-| `suppressFileOutput` | `boolean` | `false` | Suppress per-file runner output blocks in all modes |
-| `suppressPassingFiles` | `boolean` | `false` | Hide passed-file rows in the final summary |
-| `topSummary` | `boolean` | `true` | Show or hide top memory/duration summary sections (and JSON arrays) |
-| `json` | `boolean` | `false` | Return a JSON report object instead of printing text output |
-| `workers` | `number` | `4` | Maximum parallel worker slots (overrides `VITEST_WORKERS`) |
-| `worstCoverageCount` | `number` | `10` | Rows in the worst-coverage table after a coverage run (`0` disables it) |
-| `maxOldSpaceMb` | `number` | `undefined` | Global `--max-old-space-size` ceiling in MB (overrides `VITEST_HEAP_MB`) |
-| `earlyRunPatterns` | `string[]` | `[]` | Path substrings — matching files run solo (one at a time) before the parallel worker pool starts |
-| `perFileHeapOverrides` | `PerFileHeapOverride[]` | `[]` | Per-file minimum heap ceilings; the maximum of this and `maxOldSpaceMb` wins |
-| `conditions` | `string[]` | `[]` | Additional `--conditions` Node flags forwarded to children |
-| `nodeEnv` | `string` | `'development'` | Value written to `NODE_ENV` in child processes |
+| Option                 | Type                    | Default                        | Description                                                                                                                                                                                                                                              |
+| ---------------------- | ----------------------- | ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `cwd`                  | `string`                | `process.cwd()`                | Absolute project root directory                                                                                                                                                                                                                          |
+| `testDir`              | `string`                | `cwd`                          | Directory (absolute or relative to `cwd`) to scan for `*.test.vitest.{js,mjs}` files                                                                                                                                                                     |
+| `vitestConfig`         | `string`                | auto-detect                    | Explicit vitest config path; when omitted the runner walks standard config names (`vitest.config.ts`, `vite.config.ts`, etc.) relative to `cwd`                                                                                                          |
+| `testPatterns`         | `string[]`              | `[]`                           | File / folder patterns to filter — empty means all files in `testDir`                                                                                                                                                                                    |
+| `testListFile`         | `string`                | `undefined`                    | Path to a JSON array of test file paths; when set, scanning is skipped entirely                                                                                                                                                                          |
+| `testFilePattern`      | `RegExp`                | `DEFAULT_TEST_FILE_PATTERN`    | Regex matched against file names during discovery (`*.test.vitest.{js,mjs,cjs}` by default)                                                                                                                                                              |
+| `vitestArgs`           | `string[]`              | `[]`                           | Extra CLI args forwarded verbatim to every vitest invocation                                                                                                                                                                                             |
+| `showErrorDetails`     | `boolean`               | `true`                         | Print inline error blocks under each failed file in the summary                                                                                                                                                                                          |
+| `coverageQuiet`        | `boolean`               | `false`                        | Suppress per-file output; show only the progress bar and final summaries                                                                                                                                                                                 |
+| `suppressFileOutput`   | `boolean`               | `false`                        | Suppress per-file runner output blocks in all modes                                                                                                                                                                                                      |
+| `suppressPassingFiles` | `boolean`               | `false`                        | Hide passed-file rows in the final summary                                                                                                                                                                                                               |
+| `topSummary`           | `boolean`               | `true`                         | Show or hide top memory/duration summary sections (and JSON arrays)                                                                                                                                                                                      |
+| `json`                 | `boolean`               | `false`                        | Return a JSON report object instead of printing text output                                                                                                                                                                                              |
+| `workers`              | `number`                | `4`                            | Maximum parallel worker slots (overrides `VITEST_WORKERS`)                                                                                                                                                                                               |
+| `worstCoverageCount`   | `number`                | `10`                           | Rows in the worst-coverage table after a coverage run (`0` disables it)                                                                                                                                                                                  |
+| `blobsDir`             | `string`                | `<cwd>/.vitest-coverage-blobs` | Directory for per-file coverage blobs. Relative paths resolve against `cwd`. Always cleared at the start of a coverage run                                                                                                                               |
+| `mergeReports`         | `boolean`               | `true`                         | When `true`, blobs are merged via `vitest --mergeReports`, the coverage summary is printed, and `blobsDir` is deleted. When `false`, the run stops after producing blobs — no merge, no summary — and `blobsDir` is left populated for an external merge |
+| `maxOldSpaceMb`        | `number`                | `undefined`                    | Global `--max-old-space-size` ceiling in MB (overrides `VITEST_HEAP_MB`)                                                                                                                                                                                 |
+| `earlyRunPatterns`     | `string[]`              | `[]`                           | Path substrings — matching files run solo (one at a time) before the parallel worker pool starts                                                                                                                                                         |
+| `perFileHeapOverrides` | `PerFileHeapOverride[]` | `[]`                           | Per-file minimum heap ceilings; the maximum of this and `maxOldSpaceMb` wins                                                                                                                                                                             |
+| `conditions`           | `string[]`              | `[]`                           | Additional `--conditions` Node flags forwarded to children                                                                                                                                                                                               |
+| `nodeEnv`              | `string`                | `'development'`                | Value written to `NODE_ENV` in child processes                                                                                                                                                                                                           |
+| `scratchDir`           | `string`                | `'tmp/vitest-runner'`          | Per-run scratch root, relative to `cwd` (or absolute). A subdirectory is created per file invocation and exposed to it via `VITEST_RUNNER_TMP`                                                                                                           |
+| `keepTmp`              | `boolean`               | `false`                        | Keep the run's scratch root instead of removing it on completion (normal exit, failure, or SIGINT/SIGTERM)                                                                                                                                               |
+
+### Scratch directories (`VITEST_RUNNER_TMP` / `makeRunTmpDir`)
+
+Every run gets its own scratch root (`<scratchDir>/<pid>-<timestamp>/`), created before any file runs and removed once the run completes — on success, on failure, and on SIGINT/SIGTERM — unless `keepTmp` is set. Each file invocation gets its own subdirectory under that root, exposed to the child as `process.env.VITEST_RUNNER_TMP`. Stale roots left by a crashed prior run (dead PID) are swept at the start of the next run.
+
+From a test file, use `makeRunTmpDir(label)` to get a fresh, uniquely-named subdirectory instead of managing your own `mkdtemp` base:
+
+```js
+import { makeRunTmpDir } from "vitest-runner";
+
+const dir = makeRunTmpDir("my-fixture"); // a fresh directory under VITEST_RUNNER_TMP
+```
+
+CLI flags: `--scratch-dir <path>` and `--keep-tmp` (see [Runner flags](#runner-flags) below).
 
 #### `PerFileHeapOverride`
 
 ```ts
-{ pattern: string; heapMb: number }
+{
+	pattern: string;
+	heapMb: number;
+}
 ```
 
 `pattern` is a substring matched against the normalised (forward-slash) file path. The first match wins and is compared against the global `maxOldSpaceMb`; the larger value is used.
@@ -202,42 +245,40 @@ process.exit(code);
 
 ```js
 // Run all tests under src/tests/ (cwd defaults to process.cwd())
-await run({ testDir: 'src/tests' });
+await run({ testDir: "src/tests" });
 
 // Run only the config and metadata suites
 await run({
-  testDir: 'src/tests',
-  testPatterns: ['src/tests/config', 'src/tests/metadata'],
+	testDir: "src/tests",
+	testPatterns: ["src/tests/config", "src/tests/metadata"]
 });
 
 // Coverage run (OOM-safe blob + merge mode)
 await run({
-  testDir: 'src/tests',
-  vitestArgs: ['--coverage'],
+	testDir: "src/tests",
+	vitestArgs: ["--coverage"]
 });
 
 // Quiet coverage with live progress bar
 await run({
-  testDir: 'src/tests',
-  coverageQuiet: true,
+	testDir: "src/tests",
+	coverageQuiet: true
 });
 
 // Machine-readable output (no text logs)
 const report = await run({
-  testDir: 'src/tests',
-  json: true,
+	testDir: "src/tests",
+	json: true
 });
 
 console.log(report.exitCode);
 
 // Give heap-heavy files a larger ceiling while keeping the global limit lower
 await run({
-  testDir: 'src/tests',
-  maxOldSpaceMb: 2048,
-  earlyRunPatterns: ['listener-cleanup/'],
-  perFileHeapOverrides: [
-    { pattern: 'listener-cleanup/', heapMb: 6144 },
-  ],
+	testDir: "src/tests",
+	maxOldSpaceMb: 2048,
+	earlyRunPatterns: ["listener-cleanup/"],
+	perFileHeapOverrides: [{ pattern: "listener-cleanup/", heapMb: 6144 }]
 });
 ```
 
@@ -259,6 +300,28 @@ This avoids the OOM crash that occurs when a single vitest process holds coverag
 
 The log file path can be overridden with `--log-file <path>`. Passing `--log-file` by itself only enables log mirroring (it does not enable coverage mode).
 
+### Producing blobs for an external merge
+
+Set `mergeReports: false` (CLI: `--no-merge-reports`) to stop the run after the per-file blobs are written. The internal `vitest --mergeReports` call and the coverage summary are skipped, and `blobsDir` is left intact instead of being deleted. The blobs directory is still cleared at the **start** of each run, so it only ever contains the current run's output.
+
+This is useful when a second coverage blob set (for example, a browser-mode run with a different coverage transform) needs to be merged together with the node-mode blobs. Point both runs at known directories with `blobsDir`, then merge them in one external `vitest --mergeReports` step:
+
+```js
+// Node-mode blobs, no internal merge
+await run({
+	testDir: "src/tests",
+	vitestArgs: ["--coverage"],
+	blobsDir: ".coverage-blobs/node",
+	mergeReports: false
+});
+
+// (separately produce browser-mode blobs into .coverage-blobs/browser)
+// then merge both blob sets in a single external step:
+//   vitest --mergeReports .coverage-blobs --coverage
+```
+
+The exit code still reflects test pass/fail; there is just no coverage-merge result to fold in.
+
 ---
 
 ## Test list files
@@ -266,11 +329,7 @@ The log file path can be overridden with `--log-file <path>`. Passing `--log-fil
 A test list file is a plain JSON array of test file paths (relative to `cwd`):
 
 ```json
-[
-  "src/tests/auth/login.test.vitest.mjs",
-  "src/tests/auth/register.test.vitest.mjs",
-  "src/tests/config/defaults.test.vitest.mjs"
-]
+["src/tests/auth/login.test.vitest.mjs", "src/tests/auth/register.test.vitest.mjs", "src/tests/config/defaults.test.vitest.mjs"]
 ```
 
 Pass `--test-list <file>` (CLI) or `testListFile: 'path/to/list.json'` (API) to run exactly those files instead of scanning `testDir`.
@@ -281,7 +340,7 @@ Pass `--test-list <file>` (CLI) or `testListFile: 'path/to/list.json'` (API) to
 
 By default, the runner discovers files matching:
 
-```
+```text
 *.test.vitest.js
 *.test.vitest.mjs
 *.test.vitest.cjs
@@ -297,37 +356,41 @@ vitest-runner --file-pattern '\.spec\.ts$'
 ```
 
 ```js
-await run({ cwd, testDir: 'src', testFilePattern: /\.spec\.ts$/i });
+await run({ cwd, testDir: "src", testFilePattern: /\.spec\.ts$/i });
 ```
 
 ---
 
 ## Source layout
 
-```
-index.mjs              ← ESM entry (re-exports src/runner.mjs)
-index.cjs              ← CJS shim (dynamic import of index.mjs)
-bin/
-  vitest-runner.mjs    ← CLI binary
+```text
+dist/                  ← built library entry (npm run build / tsup) — generated, not committed
+  index.mjs            ← bundled ESM entry
+  index.cjs            ← bundled CJS entry (real sync require, generated from the same source)
+bin/                   ← built CLI binary (npm run build / tsup) — generated, not committed
+  vitest-runner.mjs    ← bundled CLI, from src/bin/vitest-runner.mjs (shebang preserved)
 src/
   runner.mjs           ← main run() API + re-exports
+  bin/
+    vitest-runner.mjs  ← CLI entry SOURCE — run this directly for source-level dev/testing
   utils/
     ansi.mjs           ← stripAnsi, colourPct
     duration.mjs       ← formatDuration
     env.mjs            ← buildNodeOptions
     resolve.mjs        ← resolveBin, resolveVitestConfig
   core/
-    discover.mjs       ← discoverVitestFiles, sortWithPriority
+    discover.mjs       ← discoverVitestFiles, sortWithPriority, computeFilterConflicts
     parse.mjs          ← parseVitestOutput, deduplicateErrors
     spawn.mjs          ← runSingleFile, runVitestDirect, runMergeReports
     report.mjs         ← printCoverageSummary, printMergeOutput
     progress.mjs       ← createCoverageProgressTracker
+    scratch.mjs        ← makeRunTmpDir + the scratch-directory lifecycle
   cli/
     args.mjs           ← parseArguments
     help.mjs           ← showHelp
 ```
 
-All sub-module utilities are re-exported from the root entry point, so deep imports are optional.
+`src/` is not published — only `dist/`, `bin/`, and `types/` ship (see [Programmatic API](#programmatic-api) for the `vitest-runner-dev` export condition, used when developing against a workspace/local checkout instead of the published package). All sub-module utilities are re-exported from the root entry point, so deep imports are optional.
 
 ---
 
@@ -341,15 +404,15 @@ MIT
 <!-- [release date]: https://img.shields.io/github/release-date/CLDMV/vitest-runner?style=for-the-badge&logo=github&logoColor=white&labelColor=181717 -->
 <!-- [release_date_url]: https://github.com/CLDMV/vitest-runner/releases -->
 
-[npm version]: https://img.shields.io/npm/v/vitest-runner.svg?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837
+[npm version]: https://img.shields.io/npm/v/%40cldmv%2Fvitest-runner.svg?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837
 [npm_version_url]: https://www.npmjs.com/package/@cldmv/vitest-runner
-[npm downloads]: https://img.shields.io/npm/dm/vitest-runner.svg?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837
+[npm downloads]: https://img.shields.io/npm/dm/%40cldmv%2Fvitest-runner.svg?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837
 [npm_downloads_url]: https://www.npmjs.com/package/@cldmv/vitest-runner
 [github downloads]: https://img.shields.io/github/downloads/CLDMV/vitest-runner/total?style=for-the-badge&logo=github&logoColor=white&labelColor=181717
 [github_downloads_url]: https://github.com/CLDMV/vitest-runner/releases
 [last commit]: https://img.shields.io/github/last-commit/CLDMV/vitest-runner?style=for-the-badge&logo=github&logoColor=white&labelColor=181717
 [last_commit_url]: https://github.com/CLDMV/vitest-runner/commits
-[npm last update]: https://img.shields.io/npm/last-update/vitest-runner?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837
+[npm last update]: https://img.shields.io/npm/last-update/%40cldmv%2Fvitest-runner?style=for-the-badge&logo=npm&logoColor=white&labelColor=CB3837
 [npm_last_update_url]: https://www.npmjs.com/package/@cldmv/vitest-runner
 [coverage]: https://img.shields.io/endpoint?url=https%3A%2F%2Fraw.githubusercontent.com%2FCLDMV%2Fvitest-runner%2Fbadges%2Fcoverage.json&style=for-the-badge&logo=vitest&logoColor=white
 [coverage_url]: https://github.com/CLDMV/vitest-runner/blob/badges/coverage.json