vitest-runner 1.0.0

package/src/cli/help.mjs

@@ -0,0 +1,80 @@
+/**
+ * @fileoverview CLI help text for the vitest-runner binary.
+ * @module vitest-runner/src/cli/help
+ */
+
+import chalk from "chalk";
+
+/**
+ * Print the full CLI help message to stdout.
+ * @returns {void}
+ * @example
+ * showHelp();
+ */
+export function showHelp() {
+	console.log(`
+${chalk.bold("Vitest Sequential Runner")}
+Runs each test file in its own Vitest process to avoid OOM issues.
+
+${chalk.bold("USAGE:")}
+  vitest-runner [OPTIONS] [PATTERNS]
+
+${chalk.bold("SPECIAL FLAGS:")}
+  --test-list <file>      Run only the files listed in a JSON array file
+  --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 first (repeatable)
+  --no-error-details      Hide detailed error output (show only counts)
+  --coverage-quiet        Implies --coverage; show progress bar + final summaries only
+  --log-file <path>       Path for the coverage run log (default: coverage/coverage-run.log; implies --coverage-quiet)
+  --help, -h              Show this help message
+
+${chalk.bold("TEST PATTERNS:")}
+  [file]                  Run a specific test file (supports partial paths)
+  [folder]                Run all tests in a folder
+
+  Examples:
+    src/tests/config/background.test.vitest.mjs
+    src/tests/metadata
+    background.test.vitest.mjs
+
+${chalk.bold("VITEST FLAGS:")}
+  All standard Vitest CLI flags are supported and passed through:
+  -t, --testNamePattern   Filter tests by name pattern (regex)
+  --reporter              Change reporter (verbose, dot, json, etc.)
+  --coverage              Run full-suite coverage (blob-per-file + mergeReports)
+  --bail                  Stop on first failure
+
+  See the Vitest documentation for the full list.
+
+${chalk.bold("ENVIRONMENT VARIABLES:")}
+  VITEST_HEAP_MB         Set max heap size per test (default: Node.js default)
+  VITEST_WORKERS         Number of parallel workers (default: 4, overridden by --workers)
+  # Run all tests
+  vitest-runner
+
+  # Run a specific file (partial path ok)
+  vitest-runner src/tests/config/background.test.vitest.mjs
+
+  # Run only the files listed in a JSON file
+  vitest-runner --test-list my-tests.json
+
+  # Filter by test name
+  vitest-runner src/tests/metadata -t "lazy materialization"
+
+  # Run with 2 workers
+  vitest-runner --workers 2
+
+  # Run files matching a pattern solo first, then the rest in parallel
+  vitest-runner --solo-pattern listener-cleanup/ --solo-pattern heavy/
+
+  # Hide detailed errors
+  vitest-runner --no-error-details
+
+  # Coverage with quiet output + progress bar
+  vitest-runner --coverage --coverage-quiet
+
+  # Custom heap and workers
+  VITEST_HEAP_MB=8192 vitest-runner --workers 2 src/tests/heavy
+`);
+}

package/src/core/discover.mjs

@@ -0,0 +1,167 @@
+/**
+ * @fileoverview Test-file discovery utilities.
+ * @module vitest-runner/src/core/discover
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/** Default pattern matching all supported Vitest test file extensions. */
+export const DEFAULT_TEST_FILE_PATTERN = /\.test\.vitest\.(?:js|mjs|cjs)$/i;
+
+/**
+ * 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 async function discoverFilesInDir(dir, cwd, pattern = DEFAULT_TEST_FILE_PATTERN) {
+	const queue = [dir];
+	const files = [];
+
+	while (queue.length) {
+		const current = queue.pop();
+		let entries;
+		try {
+			entries = await fs.readdir(current, { withFileTypes: true });
+		} catch {
+			continue;
+		}
+
+		for (const entry of entries) {
+			if (entry.isDirectory()) {
+				if (entry.name === "node_modules" || entry.name.startsWith(".")) continue;
+				queue.push(path.join(current, entry.name));
+				continue;
+			}
+
+			if (entry.isFile() && pattern.test(entry.name)) {
+				files.push(path.relative(cwd, path.join(current, entry.name)));
+			}
+		}
+	}
+
+	return files;
+}
+
+/**
+ * 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, earlyRunPatterns = []) {
+	const early = [];
+	const rest = [];
+
+	for (const file of files) {
+		const normalized = file.replace(/\\/g, "/");
+		const priorityIndex = earlyRunPatterns.findIndex((pat) => normalized.includes(pat));
+		if (priorityIndex !== -1) {
+			early.push({ file, priorityIndex });
+		} else {
+			rest.push(file);
+		}
+	}
+
+	early.sort((a, b) => a.priorityIndex - b.priorityIndex || a.file.localeCompare(b.file));
+	rest.sort((a, b) => a.localeCompare(b));
+
+	return [...early.map((e) => e.file), ...rest];
+}
+
+/**
+ * @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 async function discoverVitestFiles(opts) {
+	const { cwd, testDir, testPatterns = [], testListFile, testFilePattern = DEFAULT_TEST_FILE_PATTERN, earlyRunPatterns = [] } = opts;
+
+	const resolvedTestDir = testDir ? (path.isAbsolute(testDir) ? testDir : path.resolve(cwd, testDir)) : cwd;
+
+	if (testListFile) {
+		const resolvedListPath = path.isAbsolute(testListFile) ? testListFile : path.resolve(cwd, testListFile);
+
+		let testList;
+		try {
+			const content = await fs.readFile(resolvedListPath, "utf8");
+			testList = JSON.parse(content);
+		} catch (err) {
+			throw new Error(`Failed to read test list file "${resolvedListPath}": ${err.message}`);
+		}
+
+		if (!Array.isArray(testList)) {
+			throw new Error(`Test list file "${resolvedListPath}" must contain a JSON array of test file paths`);
+		}
+
+		console.log(`📋 Loading test list from: ${path.relative(cwd, resolvedListPath)}`);
+		return sortWithPriority(testList, earlyRunPatterns);
+	}
+
+	if (testPatterns.length === 0) {
+		const files = await discoverFilesInDir(resolvedTestDir, cwd, testFilePattern);
+		return sortWithPriority(files, earlyRunPatterns);
+	}
+
+	const files = [];
+
+	for (const pattern of testPatterns) {
+		const absPath = path.isAbsolute(pattern) ? pattern : path.resolve(cwd, pattern);
+
+		let stat = null;
+		try {
+			stat = await fs.stat(absPath);
+		} catch {
+			// path doesn't exist — fall through to partial-match
+		}
+
+		if (stat?.isFile()) {
+			if (testFilePattern.test(absPath)) {
+				files.push(path.relative(cwd, absPath));
+			}
+		} else if (stat?.isDirectory()) {
+			files.push(...(await discoverFilesInDir(absPath, cwd, testFilePattern)));
+		} else {
+			// Partial-path matching against all files in testDir
+			const allFiles = await discoverFilesInDir(resolvedTestDir, cwd, testFilePattern);
+			const matched = allFiles.filter((f) => f.replace(/\\/g, "/").includes(pattern.replace(/\\/g, "/")));
+
+			if (matched.length > 0) {
+				files.push(...matched);
+			} else {
+				console.warn(`⚠️  No matches found for: ${pattern}`);
+			}
+		}
+	}
+
+	return sortWithPriority([...new Set(files)], earlyRunPatterns);
+}

package/src/core/parse.mjs

@@ -0,0 +1,167 @@
+/**
+ * @fileoverview Vitest output parsing and error deduplication utilities.
+ * @module vitest-runner/src/core/parse
+ */
+
+import { stripAnsi } from "../utils/ansi.mjs";
+
+/**
+ * @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) {
+	const cleanOutput = stripAnsi(output);
+
+	const result = {
+		testFilesPass: 0,
+		testFilesFail: 0,
+		testsPass: 0,
+		testsFail: 0,
+		testsSkip: 0,
+		duration: 0,
+		heapMb: null,
+		errors: []
+	};
+
+	// "Test Files  1 passed (1)" / "Test Files  1 failed | 2 passed (3)"
+	const testFilesLineMatch = cleanOutput.match(/Test Files\s+(.+)/);
+	if (testFilesLineMatch) {
+		const line = testFilesLineMatch[1];
+		const passMatch = line.match(/(\d+)\s+passed/);
+		const failMatch = line.match(/(\d+)\s+failed/);
+		if (passMatch) result.testFilesPass = parseInt(passMatch[1], 10);
+		if (failMatch) result.testFilesFail = parseInt(failMatch[1], 10);
+	}
+
+	// "Tests  82 passed (82)" / "Tests  2 failed | 4 passed (6)"
+	const testsLineMatch = cleanOutput.match(/^\s*Tests\s+(.+)$/m);
+	if (testsLineMatch) {
+		const line = testsLineMatch[1];
+		const passMatch = line.match(/(\d+)\s+passed/);
+		const failMatch = line.match(/(\d+)\s+failed/);
+		const skipMatch = line.match(/(\d+)\s+skipped/);
+		if (passMatch) result.testsPass = parseInt(passMatch[1], 10);
+		if (failMatch) result.testsFail = parseInt(failMatch[1], 10);
+		if (skipMatch) result.testsSkip = parseInt(skipMatch[1], 10);
+	}
+
+	// "Duration  Xs"
+	const durationMatch = cleanOutput.match(/Duration\s+([\d.]+)s/);
+	if (durationMatch) {
+		result.duration = parseFloat(durationMatch[1]) * 1000;
+	}
+
+	// "N MB heap used"
+	const heapMatch = cleanOutput.match(/(\d+)\s*MB\s+heap\s+used/i);
+	if (heapMatch) {
+		result.heapMb = parseInt(heapMatch[1], 10);
+	}
+
+	// Error blocks — captured from the raw (coloured) output
+	const failedSectionStart = output.indexOf("Failed Tests");
+	if (failedSectionStart !== -1) {
+		const failedSectionEnd = output.indexOf("\n Test Files", failedSectionStart);
+		const errorSection =
+			failedSectionEnd !== -1 ? output.substring(failedSectionStart, failedSectionEnd) : output.substring(failedSectionStart);
+
+		// eslint-disable-next-line no-control-regex
+		const failPattern = /FAIL\s*(?:\x1B\[[0-9;]*[a-zA-Z]|\s)*tests\//g;
+		const matches = [...errorSection.matchAll(failPattern)];
+
+		for (let i = 0; i < matches.length; i++) {
+			const matchPos = matches[i].index;
+			const lineStart = errorSection.lastIndexOf("\n", matchPos);
+			const actualStart = lineStart === -1 ? 0 : lineStart;
+
+			const matchEnd = i < matches.length - 1 ? matches[i + 1].index : errorSection.length;
+			const nextLineStart = errorSection.lastIndexOf("\n", matchEnd);
+			const actualEnd = nextLineStart === -1 ? matchEnd : nextLineStart;
+
+			const errorBlock = errorSection.substring(actualStart, actualEnd).trim();
+			if (errorBlock) result.errors.push(errorBlock);
+		}
+	}
+
+	return result;
+}
+
+/**
+ * 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) {
+	const fullText = errors.join("\n");
+	const lines = fullText.split("\n");
+
+	const failLineMap = new Map();
+	const lineIndices = new Map();
+
+	lines.forEach((line, idx) => {
+		if (line.includes("FAIL") && line.includes("Config:")) {
+			lineIndices.set(line, idx);
+
+			const cleaned = stripAnsi(line);
+			const match = cleaned.match(/^(.+Config:\s+)'*([^'>]+)'*(.+)$/);
+			if (match) {
+				const [, before, config, after] = match;
+				const pattern = `${before.trim()}|||${after.trim()}`;
+
+				if (!failLineMap.has(pattern)) {
+					failLineMap.set(pattern, { lines: [], configs: [] });
+				}
+				failLineMap.get(pattern).lines.push(line);
+				failLineMap.get(pattern).configs.push(config.replace(/'/g, ""));
+			}
+		}
+	});
+
+	const skipIndices = new Set();
+
+	for (const [, data] of failLineMap.entries()) {
+		if (data.configs.length > 1) {
+			for (let i = 1; i < data.lines.length; i++) {
+				const idx = lineIndices.get(data.lines[i]);
+				skipIndices.add(idx);
+			}
+
+			const firstLine = data.lines[0];
+			const configArray = `[${data.configs.map((c) => `'${c}'`).join(",")}]`;
+			const consolidated = stripAnsi(firstLine).replace(/(Config:\s+)'*[^'>]+'*/, `$1${configArray}`);
+
+			const firstIdx = lineIndices.get(firstLine);
+			lines[firstIdx] = consolidated;
+		}
+	}
+
+	return lines.filter((_, idx) => !skipIndices.has(idx)).join("\n");
+}

package/src/core/progress.mjs

@@ -0,0 +1,164 @@
+/**
+ * @fileoverview Live progress tracker for coverage runs.
+ * @module vitest-runner/src/core/progress
+ */
+
+import chalk from "chalk";
+import { formatDuration } from "../utils/duration.mjs";
+
+/**
+ * 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) {
+	const isTTY = Boolean(process.stdout.isTTY);
+	const spinnerFrames = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+	const barWidth = 26;
+	const startTime = Date.now();
+	let completed = 0;
+	let active = 0;
+	let failed = 0;
+	let frameIndex = 0;
+	let maxLineLength = 0;
+	let lastPlainLog = 0;
+	let spinnerTimer = null;
+
+	/**
+	 * Build the current progress line text.
+	 * @returns {string}
+	 */
+	function buildLine() {
+		const percent = total === 0 ? 100 : (completed / total) * 100;
+		const elapsedMs = Date.now() - startTime;
+		const avgPerFile = completed > 0 ? elapsedMs / completed : 0;
+		const etaMs = avgPerFile * Math.max(total - completed, 0);
+		const filled = Math.round((percent / 100) * barWidth);
+		const spinner = spinnerFrames[frameIndex % spinnerFrames.length];
+		const bar = `[${"=".repeat(filled)}${"-".repeat(Math.max(0, barWidth - filled))}]`;
+
+		let _percent = percent.toFixed(1).padStart(5);
+		if (percent < 30) {
+			_percent = chalk.red(_percent + "%");
+		} else if (percent < 70) {
+			_percent = chalk.rgb(255, 136, 0)(_percent + "%");
+		} else if (percent > 99) {
+			_percent = chalk.green(_percent + "%");
+		} else {
+			_percent = chalk.yellow(_percent + "%");
+		}
+
+		if (isTTY) {
+			return `${chalk.green(spinner)} ${chalk.green(bar)} ${chalk.bold(_percent)} ${completed}/${total} | active ${active} | failed ${failed} | ETA ${formatDuration(etaMs)} | elapsed ${formatDuration(elapsedMs)}`;
+		}
+
+		return `progress ${percent.toFixed(1)}% ${completed}/${total} | active ${active} | failed ${failed} | eta ${formatDuration(etaMs)} | elapsed ${formatDuration(elapsedMs)}`;
+	}
+
+	/**
+	 * Render the progress line to stdout.
+	 * @param {boolean} [forcePlainLog=false] - Force a plain log line in non-TTY mode.
+	 * @returns {void}
+	 */
+	function render(forcePlainLog = false) {
+		const line = buildLine();
+		frameIndex++;
+
+		if (isTTY) {
+			// eslint-disable-next-line no-control-regex
+			const visibleLength = line.replace(/\x1B\[[0-9;]*[a-zA-Z]/g, "").length;
+			maxLineLength = Math.max(maxLineLength, visibleLength);
+			process.stdout.write(`\r${line.padEnd(maxLineLength, " ")}`);
+			return;
+		}
+
+		const now = Date.now();
+		if (forcePlainLog || now - lastPlainLog >= 2000) {
+			console.log(line);
+			lastPlainLog = now;
+		}
+	}
+
+	/**
+	 * Start the periodic spinner redraw for TTY output.
+	 * @returns {void}
+	 */
+	function startSpinnerLoop() {
+		if (!isTTY || spinnerTimer) return;
+		spinnerTimer = setInterval(() => {
+			if (completed >= total && active === 0) return;
+			render();
+		}, 120);
+		spinnerTimer.unref?.();
+	}
+
+	/**
+	 * Stop the periodic spinner redraw loop.
+	 * @returns {void}
+	 */
+	function stopSpinnerLoop() {
+		if (!spinnerTimer) return;
+		clearInterval(spinnerTimer);
+		spinnerTimer = null;
+	}
+
+	render(true);
+	startSpinnerLoop();
+
+	return {
+		/**
+		 * Call when a file run starts (increments active count).
+		 * @returns {void}
+		 */
+		onStart() {
+			active++;
+			render();
+		},
+
+		/**
+		 * Call when a file run completes.
+		 * @param {boolean} failedRun - Whether the run exited with a non-zero code.
+		 * @returns {void}
+		 */
+		onComplete(failedRun) {
+			active = Math.max(0, active - 1);
+			completed++;
+			if (failedRun) failed++;
+			render(true);
+		},
+
+		/**
+		 * Stop the spinner and print the final progress line.
+		 * @returns {void}
+		 */
+		finish() {
+			stopSpinnerLoop();
+			render(true);
+			if (isTTY) process.stdout.write("\n");
+		}
+	};
+}
+
+/**
+ * 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 = {
+	/** @returns {void} */
+	onStart() {},
+	/** @param {boolean} _failedRun @returns {void} */
+	onComplete(_failedRun) {},
+	/** @returns {void} */
+	finish() {}
+};