vitest-runner 1.0.0

package/types/src/cli/args.d.mts

@@ -0,0 +1,56 @@
+/**
+ * Parse raw CLI arguments into structured runner options.
+ *
+ * Runner-specific flags are extracted; everything else (flags and their
+ * optional values) is forwarded to vitest as passthrough args.
+ * A flag that takes a value (where the next token does not start with `-`)
+ * consumes that token too.
+ *
+ * @param {string[]} args - Raw argument array (typically `process.argv.slice(2)`).
+ * @returns {ParsedArgs}
+ * @example
+ * parseArguments(['--test-list', 'tests.json', '--workers', '2', '--reporter=verbose']);
+ */
+export function parseArguments(args: string[]): ParsedArgs;
+export type ParsedArgs = {
+    /**
+     * - Path to a JSON file of test paths to run (`--test-list`).
+     */
+    testListFile: string | undefined;
+    /**
+     * - `false` when `--no-error-details` was passed.
+     */
+    showErrorDetails: boolean;
+    /**
+     * - Whether `--coverage-quiet` was passed.
+     */
+    coverageQuiet: boolean;
+    /**
+     * - Path for the coverage run log (`--log-file`); defaults to `coverage/coverage-run.log`.
+     */
+    logFile: string | undefined;
+    /**
+     * - Whether `--help` / `-h` was passed.
+     */
+    help: boolean;
+    /**
+     * - Worker count from `--workers <n>`, or undefined.
+     */
+    workers: number | undefined;
+    /**
+     * - Path substrings from `--solo-pattern <pattern>` (repeatable).
+     */
+    soloPatterns: string[];
+    /**
+     * - Compiled regex from `--file-pattern <regex>`, or undefined.
+     */
+    testFilePattern: RegExp | undefined;
+    /**
+     * - Flags forwarded verbatim to vitest.
+     */
+    vitestPassthroughArgs: string[];
+    /**
+     * - Non-flag positional arguments (file / folder patterns).
+     */
+    testPatterns: string[];
+};

package/types/src/cli/help.d.mts

@@ -0,0 +1,7 @@
+/**
+ * Print the full CLI help message to stdout.
+ * @returns {void}
+ * @example
+ * showHelp();
+ */
+export function showHelp(): void;

package/types/src/core/discover.d.mts

@@ -0,0 +1,75 @@
+/**
+ * Recursively discover all Vitest test files under a directory.
+ * Skips `node_modules` and hidden directories (names starting with `.`).
+ *
+ * @param {string} dir - Absolute path of the directory to scan.
+ * @param {string} cwd - Project root used to compute relative paths.
+ * @param {RegExp} [pattern=DEFAULT_TEST_FILE_PATTERN] - Regex tested against the file name.
+ * @returns {Promise<string[]>} Paths relative to `cwd`.
+ * @example
+ * const files = await discoverFilesInDir('/project/src/tests', '/project');
+ */
+export function discoverFilesInDir(dir: string, cwd: string, pattern?: RegExp): Promise<string[]>;
+/**
+ * Sort test files alphabetically while hoisting files matching `earlyRunPatterns`
+ * to the front (in pattern-declaration order, then alphabetically within each group).
+ *
+ * @param {string[]} files - File paths to sort.
+ * @param {string[]} [earlyRunPatterns=[]] - Substrings — files whose path contains one run first.
+ * @returns {string[]} Sorted file paths.
+ * @example
+ * sortWithPriority(files, ['listener-cleanup/']);
+ */
+export function sortWithPriority(files: string[], earlyRunPatterns?: string[]): string[];
+/**
+ * @typedef {Object} DiscoverOptions
+ * @property {string} cwd - Project root directory.
+ * @property {string} [testDir] - Root directory to search for test files (defaults to `cwd`).
+ * @property {string[]} [testPatterns=[]] - File / folder patterns to filter (empty = all files).
+ * @property {string} [testListFile] - Path to a JSON array of test file paths to run instead of scanning.
+ * @property {RegExp} [testFilePattern] - Regex to match file names (default: `DEFAULT_TEST_FILE_PATTERN`).
+ * @property {string[]} [earlyRunPatterns=[]] - Path substrings for files that must run solo first.
+ */
+/**
+ * Discover Vitest test files according to the provided options.
+ *
+ * | Scenario | Behaviour |
+ * |---|---|
+ * | `testListFile` set | Reads the exact file list from that JSON file. |
+ * | Patterns provided | Resolves each as file / directory, falls back to partial-path match. |
+ * | No patterns | Returns all test files found under `testDir`. |
+ *
+ * @param {DiscoverOptions} opts
+ * @returns {Promise<string[]>} Sorted array of test file paths relative to `cwd`.
+ * @example
+ * const files = await discoverVitestFiles({ cwd: '/project', testDir: '/project/src/tests' });
+ */
+export function discoverVitestFiles(opts: DiscoverOptions): Promise<string[]>;
+/** Default pattern matching all supported Vitest test file extensions. */
+export const DEFAULT_TEST_FILE_PATTERN: RegExp;
+export type DiscoverOptions = {
+    /**
+     * - Project root directory.
+     */
+    cwd: string;
+    /**
+     * - Root directory to search for test files (defaults to `cwd`).
+     */
+    testDir?: string;
+    /**
+     * - File / folder patterns to filter (empty = all files).
+     */
+    testPatterns?: string[];
+    /**
+     * - Path to a JSON array of test file paths to run instead of scanning.
+     */
+    testListFile?: string;
+    /**
+     * - Regex to match file names (default: `DEFAULT_TEST_FILE_PATTERN`).
+     */
+    testFilePattern?: RegExp;
+    /**
+     * - Path substrings for files that must run solo first.
+     */
+    earlyRunPatterns?: string[];
+};

package/types/src/core/parse.d.mts

@@ -0,0 +1,73 @@
+/**
+ * @typedef {Object} ParsedVitestResult
+ * @property {number} testFilesPass - Number of test files that passed.
+ * @property {number} testFilesFail - Number of test files that failed.
+ * @property {number} testsPass - Number of individual tests that passed.
+ * @property {number} testsFail - Number of individual tests that failed.
+ * @property {number} testsSkip - Number of individual tests that were skipped.
+ * @property {number} duration - Duration in milliseconds (from Vitest output).
+ * @property {number|null} heapMb - Peak heap usage in MB, or `null` if not reported.
+ * @property {string[]} errors - Array of raw error blocks (with ANSI codes).
+ */
+/**
+ * Parse raw Vitest stdout/stderr output into structured result data.
+ *
+ * Extracts test-file counts, individual test counts, duration, heap usage,
+ * and error blocks.  Counts are parsed from ANSI-stripped output; error blocks
+ * are captured from the original coloured output.
+ *
+ * @param {string} output - Combined raw stdout + stderr from a vitest child process.
+ * @returns {ParsedVitestResult}
+ * @example
+ * const result = parseVitestOutput(rawOutput);
+ * console.log(result.testsPass, result.testsFail);
+ */
+export function parseVitestOutput(output: string): ParsedVitestResult;
+/**
+ * Deduplicate similar FAIL lines that differ only by their `Config:` value.
+ *
+ * When the same test file fails across multiple matrix configs vitest emits
+ * one FAIL line per config.  This collapses them into a single line listing
+ * all configs as an array, keeping output concise.
+ *
+ * @param {string[]} errors - Array of raw error blocks (each a complete FAIL section).
+ * @returns {string} Deduplicated error text joined as a single string.
+ * @example
+ * const deduped = deduplicateErrors(result.errors);
+ * console.log(deduped);
+ */
+export function deduplicateErrors(errors: string[]): string;
+export type ParsedVitestResult = {
+    /**
+     * - Number of test files that passed.
+     */
+    testFilesPass: number;
+    /**
+     * - Number of test files that failed.
+     */
+    testFilesFail: number;
+    /**
+     * - Number of individual tests that passed.
+     */
+    testsPass: number;
+    /**
+     * - Number of individual tests that failed.
+     */
+    testsFail: number;
+    /**
+     * - Number of individual tests that were skipped.
+     */
+    testsSkip: number;
+    /**
+     * - Duration in milliseconds (from Vitest output).
+     */
+    duration: number;
+    /**
+     * - Peak heap usage in MB, or `null` if not reported.
+     */
+    heapMb: number | null;
+    /**
+     * - Array of raw error blocks (with ANSI codes).
+     */
+    errors: string[];
+};

package/types/src/core/progress.d.mts

@@ -0,0 +1,30 @@
+/**
+ * Create a live progress tracker that renders to stdout.
+ *
+ * In TTY mode a spinner + bar overwrites the current line on each update.
+ * In non-TTY mode a plain-text line is printed at most once every two seconds,
+ * plus once on every `onComplete` call.
+ *
+ * @param {number} total - Total number of files to process.
+ * @returns {{ onStart: () => void, onComplete: (failedRun: boolean) => void, finish: () => void }}
+ * @example
+ * const progress = createCoverageProgressTracker(120);
+ * progress.onStart();
+ * progress.onComplete(false);
+ * progress.finish();
+ */
+export function createCoverageProgressTracker(total: number): {
+    onStart: () => void;
+    onComplete: (failedRun: boolean) => void;
+    finish: () => void;
+};
+/**
+ * A no-op progress tracker used when quiet mode is disabled (progress is
+ * handled via `console.log` inline).
+ * @type {{ onStart: () => void, onComplete: (failedRun: boolean) => void, finish: () => void }}
+ */
+export const noopProgressTracker: {
+    onStart: () => void;
+    onComplete: (failedRun: boolean) => void;
+    finish: () => void;
+};

package/types/src/core/report.d.mts

@@ -0,0 +1,47 @@
+/**
+ * Print verbose output for files that failed during a quiet coverage run.
+ *
+ * @param {Array<{file: string, code: number, rawOutput: string}>} failedResults
+ * @returns {void}
+ * @example
+ * printQuietCoverageFailureDetails(failedResults);
+ */
+export function printQuietCoverageFailureDetails(failedResults: Array<{
+    file: string;
+    code: number;
+    rawOutput: string;
+}>): void;
+/**
+ * Print the captured output from a quiet `--mergeReports` step.
+ *
+ * On success prints only the coverage block (from "% Coverage report from v8").
+ * On failure prints the full raw output to stderr.
+ *
+ * @param {number} exitCode - The merge process exit code.
+ * @param {string} output - Raw stdout + stderr from the merge process.
+ * @returns {void}
+ */
+export function printMergeOutput(exitCode: number, output: string): void;
+/**
+ * Compute a coverage-summary-style object from a raw V8/Istanbul `coverage-final.json`.
+ *
+ * @param {Record<string, object>} finalData - Parsed `coverage-final.json` contents.
+ * @returns {{ total: object, [filePath: string]: object }} Istanbul coverage-summary format.
+ */
+export function computeSummaryFromFinal(finalData: Record<string, object>): {
+    total: object;
+    [filePath: string]: object;
+};
+/**
+ * Read the coverage JSON produced after a `mergeReports` run and print a
+ * worst-offenders table plus overall-coverage totals.
+ *
+ * Tries `coverage-summary.json` first; falls back to computing from
+ * `coverage-final.json` if that is not present.
+ *
+ * @param {string} cwd - Project root (used to make absolute file paths relative).
+ * @param {string[]} extraCoverageArgs - Passthrough `--coverage.*` args (checked for `reportsDirectory`).
+ * @param {number} [worstCount=10] - Number of worst-coverage files to show (0 = skip table).
+ * @returns {Promise<void>}
+ */
+export function printCoverageSummary(cwd: string, extraCoverageArgs: string[], worstCount?: number): Promise<void>;

package/types/src/core/spawn.d.mts

@@ -0,0 +1,114 @@
+/**
+ * @typedef {Object} SingleFileResult
+ * @property {string} file - Test file path.
+ * @property {number} code - Process exit code.
+ * @property {number} duration - Run duration in milliseconds.
+ * @property {number} testFilesPass
+ * @property {number} testFilesFail
+ * @property {number} testsPass
+ * @property {number} testsFail
+ * @property {number} testsSkip
+ * @property {number|null} heapMb
+ * @property {string[]} errors
+ * @property {string} rawOutput
+ */
+/**
+ * Run a single Vitest test file in a child process and return parsed results.
+ *
+ * @param {string} filePath - Test file path (relative to `cwd` or absolute).
+ * @param {SpawnBaseOptions & { vitestArgs?: string[], streamOutput?: boolean }} opts
+ * @returns {Promise<SingleFileResult>}
+ * @example
+ * const result = await runSingleFile('src/tests/foo.test.vitest.mjs', {
+ *   cwd: '/project',
+ *   vitestBin: '/project/node_modules/.bin/vitest',
+ *   vitestConfig: '/project/vitest.config.ts',
+ * });
+ */
+export function runSingleFile(filePath: string, opts: SpawnBaseOptions & {
+    vitestArgs?: string[];
+    streamOutput?: boolean;
+}): Promise<SingleFileResult>;
+/**
+ * Run Vitest directly (all files in one process) with inherited stdio.
+ *
+ * @param {SpawnBaseOptions & { vitestArgs?: string[] }} opts
+ * @returns {Promise<number>} Process exit code.
+ * @example
+ * const code = await runVitestDirect({
+ *   cwd: '/project',
+ *   vitestBin: '/project/node_modules/.bin/vitest',
+ *   vitestArgs: ['--reporter=verbose'],
+ * });
+ */
+export function runVitestDirect(opts: SpawnBaseOptions & {
+    vitestArgs?: string[];
+}): Promise<number>;
+/**
+ * Merge blob reports from individual coverage runs into a single coverage report
+ * using `vitest --mergeReports`.
+ *
+ * @param {string} blobsDir - Directory containing the `.blob` files to merge.
+ * @param {SpawnBaseOptions & { extraCoverageArgs?: string[], quietOutput?: boolean }} opts
+ * @returns {Promise<{ exitCode: number, output: string }>}
+ * @example
+ * const { exitCode } = await runMergeReports('/project/.vitest-blobs', {
+ *   cwd: '/project',
+ *   vitestBin: '/project/node_modules/.bin/vitest',
+ * });
+ */
+export function runMergeReports(blobsDir: string, opts: SpawnBaseOptions & {
+    extraCoverageArgs?: string[];
+    quietOutput?: boolean;
+}): Promise<{
+    exitCode: number;
+    output: string;
+}>;
+export type SpawnBaseOptions = {
+    /**
+     * - Working directory for the child process.
+     */
+    cwd: string;
+    /**
+     * - Absolute path to the vitest binary.
+     */
+    vitestBin: string;
+    /**
+     * - Vitest config path (omit to let vitest auto-detect).
+     */
+    vitestConfig: string | undefined;
+    /**
+     * - Optional `--max-old-space-size` ceiling.
+     */
+    maxOldSpaceMb: number | undefined;
+    /**
+     * - Additional `--conditions` flags.
+     */
+    conditions?: string[];
+    /**
+     * - Value for `NODE_ENV`.
+     */
+    nodeEnv?: string;
+};
+export type SingleFileResult = {
+    /**
+     * - Test file path.
+     */
+    file: string;
+    /**
+     * - Process exit code.
+     */
+    code: number;
+    /**
+     * - Run duration in milliseconds.
+     */
+    duration: number;
+    testFilesPass: number;
+    testFilesFail: number;
+    testsPass: number;
+    testsFail: number;
+    testsSkip: number;
+    heapMb: number | null;
+    errors: string[];
+    rawOutput: string;
+};

package/types/src/runner.d.mts

@@ -0,0 +1,97 @@
+/**
+ * Run all discovered Vitest test files sequentially (with a configurable worker
+ * pool for the non-solo phase) and return an exit code.
+ *
+ * @param {RunOptions} opts
+ * @returns {Promise<number>} `0` on full pass, `1` on any failure.
+ */
+export function run(opts: RunOptions): Promise<number>;
+export { formatDuration } from "./utils/duration.mjs";
+export { buildNodeOptions } from "./utils/env.mjs";
+export type PerFileHeapOverride = {
+    /**
+     * - Substring matched against the normalised file path.
+     */
+    pattern: string;
+    /**
+     * - Minimum heap ceiling in MB for matching files.
+     */
+    heapMb: number;
+};
+export type RunOptions = {
+    /**
+     * - Absolute project root directory.
+     */
+    cwd: string;
+    /**
+     * - Directory to scan for test files (relative or absolute; defaults to `cwd`).
+     */
+    testDir?: string;
+    /**
+     * - Explicit vitest config path; auto-detected from `cwd` when omitted.
+     */
+    vitestConfig?: string;
+    /**
+     * - File / folder patterns to filter (empty = all files in `testDir`).
+     */
+    testPatterns?: string[];
+    /**
+     * - Path to a JSON array of test file paths; when set, scanning is skipped.
+     */
+    testListFile?: string;
+    /**
+     * - Regex matched against file names when scanning (default: `*.test.vitest.{js,mjs,cjs}`).
+     */
+    testFilePattern?: RegExp;
+    /**
+     * - Extra CLI args forwarded verbatim to every vitest invocation.
+     */
+    vitestArgs?: string[];
+    /**
+     * - Print inline error blocks under each failed file.
+     */
+    showErrorDetails?: boolean;
+    /**
+     * - Suppress per-file output; show only progress bar + summaries.
+     */
+    coverageQuiet?: boolean;
+    /**
+     * - Maximum number of parallel worker slots.
+     */
+    workers?: number;
+    /**
+     * - Rows in the worst-coverage table (0 = disable).
+     */
+    worstCoverageCount?: number;
+    /**
+     * - Global `--max-old-space-size` ceiling; per-file overrides may raise it.
+     */
+    maxOldSpaceMb?: number;
+    /**
+     * - Path substrings — matching files run solo before the worker pool.
+     */
+    earlyRunPatterns?: string[];
+    /**
+     * - Per-file minimum heap overrides.
+     */
+    perFileHeapOverrides?: PerFileHeapOverride[];
+    /**
+     * - Additional `--conditions` Node flags forwarded to children.
+     */
+    conditions?: string[];
+    /**
+     * - Value for `NODE_ENV` in child processes.
+     */
+    nodeEnv?: string;
+    /**
+     * -
+     */
+    _testResultsOverride?: object[] | null;
+};
+export { resolveBin, resolveVitestConfig } from "./utils/resolve.mjs";
+export { discoverVitestFiles, sortWithPriority, discoverFilesInDir } from "./core/discover.mjs";
+export { parseVitestOutput, deduplicateErrors } from "./core/parse.mjs";
+export { runSingleFile, runVitestDirect, runMergeReports } from "./core/spawn.mjs";
+export { createCoverageProgressTracker, noopProgressTracker } from "./core/progress.mjs";
+export { printCoverageSummary, printMergeOutput, printQuietCoverageFailureDetails } from "./core/report.mjs";
+export { stripAnsi, colourPct } from "./utils/ansi.mjs";

package/types/src/utils/ansi.d.mts

@@ -0,0 +1,22 @@
+/**
+ * @fileoverview ANSI escape-code helpers.
+ * @module vitest-runner/src/utils/ansi
+ */
+/**
+ * Strip ANSI colour/style escape codes from a string.
+ * @param {string} text - Input text that may contain ANSI codes.
+ * @returns {string} Clean text without escape codes.
+ * @example
+ * stripAnsi('\x1B[32mhello\x1B[0m'); // 'hello'
+ */
+export function stripAnsi(text: string): string;
+/**
+ * Colour-code a coverage percentage value using chalk.
+ * ≥ 80 % → green, ≥ 50 % → yellow, < 50 % → red.
+ * @param {import('chalk').ChalkInstance} chalk - Chalk instance supplied by the caller.
+ * @param {number} pct - Coverage percentage 0–100.
+ * @returns {string} Chalk-coloured, right-aligned percentage string.
+ * @example
+ * colourPct(chalk, 75.5); // yellow '  75.50'
+ */
+export function colourPct(chalk: import("chalk").ChalkInstance, pct: number): string;

package/types/src/utils/duration.d.mts

@@ -0,0 +1,13 @@
+/**
+ * @fileoverview Duration formatting utilities.
+ * @module vitest-runner/src/utils/duration
+ */
+/**
+ * Format a millisecond duration as a human-readable `m:ss` or `h:mm:ss` string.
+ * @param {number} ms - Duration in milliseconds.
+ * @returns {string} Formatted duration string.
+ * @example
+ * formatDuration(65000);    // '1:05'
+ * formatDuration(3661000);  // '1:01:01'
+ */
+export function formatDuration(ms: number): string;

package/types/src/utils/env.d.mts

@@ -0,0 +1,25 @@
+/**
+ * @fileoverview NODE_OPTIONS / environment helpers.
+ * @module vitest-runner/src/utils/env
+ */
+/**
+ * Build a `NODE_OPTIONS` string suitable for passing to child vitest processes.
+ *
+ * Merges any existing base value with optional `--max-old-space-size` and
+ * `--conditions` flags.  Each flag is only added once even if called multiple
+ * times with the same value.
+ *
+ * @param {Object} opts
+ * @param {number|undefined} opts.maxOldSpaceMb - Heap ceiling to add (omit or `undefined` to skip).
+ * @param {string[]} [opts.conditions=[]] - Additional `--conditions` values to append.
+ * @param {string} [opts.base] - Starting `NODE_OPTIONS` string; defaults to `process.env.NODE_OPTIONS`.
+ * @returns {string} Combined `NODE_OPTIONS` string (trimmed).
+ * @example
+ * buildNodeOptions({ maxOldSpaceMb: 4096, conditions: ['my-dev'] });
+ * // '--conditions=my-dev --max-old-space-size=4096'
+ */
+export function buildNodeOptions({ maxOldSpaceMb, conditions, base }: {
+    maxOldSpaceMb: number | undefined;
+    conditions?: string[];
+    base?: string;
+}): string;

package/types/src/utils/resolve.d.mts

@@ -0,0 +1,32 @@
+/**
+ * Resolve the absolute path of a binary shipped with an npm package.
+ *
+ * The `require` instance is rooted at `cwd` so the package is found in the
+ * consumer project's `node_modules`, not the runner's own.
+ *
+ * @param {string} cwd - Consumer project root to search from.
+ * @param {string} pkgName - The npm package name (e.g. `'vitest'`).
+ * @param {string} [binName=pkgName] - The bin alias key to look up.
+ * @returns {string} Absolute path to the binary entry point.
+ * @throws {Error} When the bin entry is not found in the package manifest.
+ * @example
+ * resolveBin('/my/project', 'vitest');
+ * // '/my/project/node_modules/vitest/dist/cli.mjs'
+ */
+export function resolveBin(cwd: string, pkgName: string, binName?: string): string;
+/**
+ * Resolve the vitest config path to use for a project.
+ *
+ * - If `configPath` is provided it is returned as-is (resolved absolute if relative).
+ * - Otherwise the function walks {@link DEFAULT_CONFIG_NAMES} relative to `cwd`
+ *   and returns the first file that exists.
+ * - Returns `undefined` when nothing is found, letting vitest use its own defaults.
+ *
+ * @param {string} cwd - Project root directory.
+ * @param {string|undefined} configPath - Explicit config path, or `undefined` for auto-detect.
+ * @returns {Promise<string|undefined>} Resolved absolute config path, or `undefined`.
+ * @example
+ * const cfg = await resolveVitestConfig('/my/project', undefined);
+ * // '/my/project/vitest.config.ts'  (if that file exists)
+ */
+export function resolveVitestConfig(cwd: string, configPath: string | undefined): Promise<string | undefined>;