@cldmv/vitest-runner 1.2.0 → 1.4.3

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

@@ -77,4 +77,12 @@ export type ParsedArgs = {
      * - Non-flag positional arguments (file / folder patterns).
      */
     testPatterns: string[];
+    /**
+     * - Keep the run's scratch directory instead of removing it on completion (`--keep-tmp`).
+     */
+    keepTmp: boolean;
+    /**
+     * - Per-run scratch root, relative to `cwd` (`--scratch-dir`); defaults to `tmp/vitest-runner`.
+     */
+    scratchDir: string | undefined;
 };

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

@@ -21,6 +21,29 @@ export function discoverFilesInDir(dir: string, cwd: string, pattern?: RegExp):
  * sortWithPriority(files, ['listener-cleanup/']);
  */
 export function sortWithPriority(files: string[], earlyRunPatterns?: string[]): string[];
+/**
+ * Compute, for every file in `files`, the set of *other* files that Vitest's
+ * own CLI filter would spuriously also match when that file's path is passed
+ * as the filter argument.
+ *
+ * Vitest's `vitest run <filter>` matches any discovered test file whose path
+ * *contains* `<filter>` as a substring — not just an exact-path match. Two
+ * files that share the same basename (and immediate parent directory) at
+ * different depths — e.g. `tests/contract.test.vitest.mjs` and
+ * `packages/a/tests/contract.test.vitest.mjs` — collide because the shorter
+ * path is a trailing substring of the longer one, so filtering on the shorter
+ * path's exact string also matches the longer path's file. Passing an
+ * absolute path does not help: Vitest normalises to a root-relative path
+ * before matching.
+ *
+ * @param {string[]} files - File paths relative to the project root, as returned by discovery.
+ * @returns {Map<string, string[]>} Map from each file to the other files it would spuriously match (empty array when unambiguous).
+ * @example
+ * const conflicts = computeFilterConflicts(["tests/a.mjs", "pkg/tests/a.mjs"]);
+ * conflicts.get("tests/a.mjs"); // ["pkg/tests/a.mjs"]
+ * conflicts.get("pkg/tests/a.mjs"); // []
+ */
+export function computeFilterConflicts(files: string[]): Map<string, string[]>;
 /**
  * @typedef {Object} DiscoverOptions
  * @property {string} cwd - Project root directory.

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

@@ -0,0 +1,64 @@
+/**
+ * Check whether a process is still alive.
+ *
+ * @param {number} pid
+ * @returns {boolean}
+ */
+export function isPidAlive(pid: number): boolean;
+/**
+ * Remove scratch roots left behind by runs whose owning process is no longer alive
+ * (a crash or `kill -9` skips the normal exit-time cleanup).
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} scratchDir - Scratch base directory, relative to `cwd` (or absolute).
+ * @returns {Promise<void>}
+ */
+export function sweepStaleScratchRoots(cwd: string, scratchDir: string): Promise<void>;
+/**
+ * Create this run's scratch root: `<cwd>/<scratchDir>/<pid>-<timestamp>/`.
+ *
+ * @param {string} cwd - Project root.
+ * @param {string} scratchDir - Scratch base directory, relative to `cwd` (or absolute).
+ * @returns {Promise<string>} Absolute path to the created root.
+ */
+export function createRunScratchRoot(cwd: string, scratchDir: string): Promise<string>;
+/**
+ * Create a scratch subdirectory under the run root for one file invocation.
+ *
+ * @param {string} runRoot - This run's scratch root, from `createRunScratchRoot`.
+ * @param {number} index - A unique index for this invocation within the run.
+ * @returns {Promise<string>} Absolute path to the created directory.
+ */
+export function createFileScratchDir(runRoot: string, index: number): Promise<string>;
+/**
+ * Remove a run's scratch root (async, best-effort).
+ *
+ * @param {string} root
+ * @returns {Promise<void>}
+ */
+export function removeScratchRoot(root: string): Promise<void>;
+/**
+ * Remove a run's scratch root synchronously (best-effort) — used from a signal
+ * handler right before `process.exit()`, where async cleanup can't be awaited.
+ *
+ * @param {string} root
+ * @returns {void}
+ */
+export function removeScratchRootSync(root: string): void;
+/**
+ * Create a fresh, uniquely-named scratch subdirectory for the calling test file.
+ *
+ * Reads the run's scratch directory from `process.env.VITEST_RUNNER_TMP`, which
+ * vitest-runner sets in every spawned child. Call this from a test file to get
+ * isolated scratch space per test case without managing your own `mkdtemp` base.
+ *
+ * @param {string} label - A short, human-readable label used as the directory name prefix.
+ * @returns {string} Absolute path to the newly created directory.
+ * @throws {Error} When `VITEST_RUNNER_TMP` is not set (not running under vitest-runner).
+ * @example
+ * import { makeRunTmpDir } from "@cldmv/vitest-runner";
+ * const dir = makeRunTmpDir("my-fixture");
+ */
+export function makeRunTmpDir(label: string): string;
+/** Default scratch root, relative to `cwd`. */
+export const DEFAULT_SCRATCH_DIR: "tmp/vitest-runner";

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

@@ -16,7 +16,7 @@
  * 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
+ * @param {SpawnBaseOptions & { vitestArgs?: string[], streamOutput?: boolean, excludePaths?: string[], extraEnv?: NodeJS.ProcessEnv }} opts
  * @returns {Promise<SingleFileResult>}
  * @example
  * const result = await runSingleFile('src/tests/foo.test.vitest.mjs', {
@@ -28,6 +28,8 @@
 export function runSingleFile(filePath: string, opts: SpawnBaseOptions & {
     vitestArgs?: string[];
     streamOutput?: boolean;
+    excludePaths?: string[];
+    extraEnv?: NodeJS.ProcessEnv;
 }): Promise<SingleFileResult>;
 /**
  * Run Vitest directly (all files in one process) with inherited stdio.

package/types/src/runner.d.mts

@@ -2,12 +2,19 @@
  * Run all discovered Vitest test files sequentially (with a configurable worker
  * pool for the non-solo phase) and return an exit code.
  *
+ * Owns the run's scratch directory lifecycle (`scratchDir`/`keepTmp`): sweeps stale
+ * roots from dead prior runs, creates this run's root, and removes it on every exit
+ * path — normal completion, a thrown error, or SIGINT/SIGTERM — unless `keepTmp` is
+ * set. The actual run logic lives in {@link runImpl}; this wrapper only exists to
+ * guarantee that cleanup regardless of how `runImpl` returns or throws.
+ *
  * @param {RunOptions} opts
  * @returns {Promise<number|object>} `0`/`1` by default; JSON report object when `opts.json` is true.
  */
 export function run(opts: RunOptions): Promise<number | object>;
 export { formatDuration } from "./utils/duration.mjs";
 export { buildNodeOptions } from "./utils/env.mjs";
+export { makeRunTmpDir } from "./core/scratch.mjs";
 export type PerFileHeapOverride = {
     /**
      * - Substring matched against the normalised file path.
@@ -107,6 +114,14 @@ export type RunOptions = {
      * - Value for `NODE_ENV` in child processes.
      */
     nodeEnv?: string;
+    /**
+     * - Per-run scratch root, relative to `cwd` (or absolute). A subdirectory is created per file invocation and exposed to it via `VITEST_RUNNER_TMP`.
+     */
+    scratchDir?: string;
+    /**
+     * - Keep the run's scratch root instead of removing it on completion (normal exit, failure, or SIGINT/SIGTERM).
+     */
+    keepTmp?: boolean;
     /**
      * -
      */

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

@@ -1,3 +1,15 @@
+/**
+ *	@Project: @cldmv/vitest-runner
+ *	@Filename: /src/utils/ansi.mjs
+ *	@Date: 2026-02-24T22:33:55-08:00 (1772001235)
+ *	@Author: Shinrai <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Shinrai <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-09-27 08:51:31 -07:00 (1790524291)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
 /**
  * @fileoverview ANSI escape-code helpers.
  * @module vitest-runner/src/utils/ansi

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

@@ -1,3 +1,15 @@
+/**
+ *	@Project: @cldmv/vitest-runner
+ *	@Filename: /src/utils/duration.mjs
+ *	@Date: 2026-02-24T22:33:55-08:00 (1772001235)
+ *	@Author: Shinrai <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Shinrai <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-09-27 08:51:31 -07:00 (1790524291)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
 /**
  * @fileoverview Duration formatting utilities.
  * @module vitest-runner/src/utils/duration

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

@@ -1,3 +1,15 @@
+/**
+ *	@Project: @cldmv/vitest-runner
+ *	@Filename: /src/utils/env.mjs
+ *	@Date: 2026-02-24T22:33:55-08:00 (1772001235)
+ *	@Author: Shinrai <CLDMV>
+ *	@Email: <Shinrai@users.noreply.github.com>
+ *	-----
+ *	@Last modified by: Shinrai <CLDMV> (Shinrai@users.noreply.github.com)
+ *	@Last modified time: 2026-09-27 08:51:31 -07:00 (1790524291)
+ *	-----
+ *	@Copyright: Copyright (c) 2013-2026 Catalyzed Motivation Inc. All rights reserved.
+ */
 /**
  * @fileoverview NODE_OPTIONS / environment helpers.
  * @module vitest-runner/src/utils/env

package/index.cjs

@@ -1,17 +0,0 @@
-/**
- * @fileoverview CJS shim — dynamically imports the ESM entry point so that
- * CommonJS callers can `require('vitest-runner')`.
- *
- * Because the package is pure ESM (`"type": "module"`) we cannot use `module.exports =`
- * directly; instead we export a promise and re-attach named exports once resolved.
- *
- * @example
- * // CommonJS usage
- * const { run } = await require('vitest-runner');
- */
-
-"use strict";
-
-// Async shim: re-export everything from the ESM module.
-// Callers must await the result or use .then().
-module.exports = import("./index.mjs");

package/index.mjs

@@ -1,5 +0,0 @@
-/**
- * @fileoverview ESM entry-point — re-exports the public API from src/runner.mjs.
- * @module vitest-runner
- */
-export * from "./src/runner.mjs";

package/src/cli/args.mjs

@@ -1,148 +0,0 @@
-/**
- * @fileoverview CLI argument parsing for the vitest-runner binary.
- * @module vitest-runner/src/cli/args
- */
-
-/**
- * @typedef {Object} ParsedArgs
- * @property {string|undefined} testListFile - Path to a JSON file of test paths to run (`--test-list`).
- * @property {boolean} showErrorDetails - `false` when `--no-error-details` was passed.
- * @property {boolean} coverageQuiet - Whether `--coverage-quiet` was passed.
- * @property {string|undefined} logFile - Path for the coverage run log (`--log-file`); defaults to `coverage/coverage-run.log`.
- * @property {boolean} suppressFileOutput - Suppress per-file runner output blocks (`--suppress-file-output`).
- * @property {boolean} suppressPassingFiles - Suppress the passed-files section in the final summary (`--suppress-passing-files`).
- * @property {boolean} topSummary - Show top-summary sections for memory and duration (`true` by default, disabled by `--no-top-summary`).
- * @property {boolean} json - Emit a JSON run report instead of text output (`--json`).
- * @property {string|undefined} blobsDir - Directory for per-file coverage blobs (`--blobs-dir`); defaults to `<cwd>/.vitest-coverage-blobs`.
- * @property {boolean} mergeReports - `false` when `--no-merge-reports` was passed; leaves blobs in `blobsDir` without merging.
- * @property {boolean} help - Whether `--help` / `-h` was passed.
- * @property {number|undefined} workers - Worker count from `--workers <n>`, or undefined.
- * @property {string[]} soloPatterns - Path substrings from `--solo-pattern <pattern>` (repeatable).
- * @property {RegExp|undefined} testFilePattern - Compiled regex from `--file-pattern <regex>`, or undefined.
- * @property {string[]} vitestPassthroughArgs - Flags forwarded verbatim to vitest.
- * @property {string[]} testPatterns - Non-flag positional arguments (file / folder patterns).
- */
-
-/** Runner-owned flags that must not be forwarded to vitest. */
-const RUNNER_FLAGS = new Set([
-	"--test-list",
-	"--no-error-details",
-	"--coverage-quiet",
-	"--log-file",
-	"--suppress-file-output",
-	"--suppress-passing-files",
-	"--no-top-summary",
-	"--json",
-	"--blobs-dir",
-	"--no-merge-reports",
-	"--workers",
-	"--solo-pattern",
-	"--file-pattern",
-	"--help",
-	"-h"
-]);
-
-/**
- * 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) {
-	const vitestPassthroughArgs = [];
-	const testPatterns = [];
-	const soloPatterns = [];
-	let testListFile;
-	let showErrorDetails = true;
-	let coverageQuiet = false;
-	let logFile;
-	let suppressFileOutput = false;
-	let suppressPassingFiles = false;
-	let topSummary = true;
-	let json = false;
-	let blobsDir;
-	let mergeReports = true;
-	let workers;
-	let help = false;
-	let testFilePattern;
-	for (let i = 0; i < args.length; i++) {
-		const arg = args[i];
-
-		if (arg === "--test-list") {
-			testListFile = args[++i];
-		} else if (arg.startsWith("--test-list=")) {
-			testListFile = arg.slice("--test-list=".length);
-		} else if (arg === "--no-error-details") {
-			showErrorDetails = false;
-		} else if (arg === "--coverage-quiet") {
-			coverageQuiet = true;
-		} else if (arg === "--log-file") {
-			logFile = args[++i];
-		} else if (arg.startsWith("--log-file=")) {
-			logFile = arg.slice("--log-file=".length);
-		} else if (arg === "--suppress-file-output") {
-			suppressFileOutput = true;
-		} else if (arg === "--suppress-passing-files") {
-			suppressPassingFiles = true;
-		} else if (arg === "--no-top-summary") {
-			topSummary = false;
-		} else if (arg === "--json") {
-			json = true;
-		} else if (arg === "--blobs-dir") {
-			blobsDir = args[++i];
-		} else if (arg.startsWith("--blobs-dir=")) {
-			blobsDir = arg.slice("--blobs-dir=".length);
-		} else if (arg === "--no-merge-reports") {
-			mergeReports = false;
-		} else if (arg === "--workers") {
-			workers = parseInt(args[++i], 10);
-		} else if (arg.startsWith("--workers=")) {
-			workers = parseInt(arg.slice("--workers=".length), 10);
-		} else if (arg === "--solo-pattern") {
-			soloPatterns.push(args[++i]);
-		} else if (arg.startsWith("--solo-pattern=")) {
-			soloPatterns.push(arg.slice("--solo-pattern=".length));
-		} else if (arg === "--file-pattern") {
-			testFilePattern = new RegExp(args[++i], "i");
-		} else if (arg.startsWith("--file-pattern=")) {
-			testFilePattern = new RegExp(arg.slice("--file-pattern=".length), "i");
-		} else if (arg === "--help" || arg === "-h") {
-			help = true;
-		} else if ((arg.startsWith("--") || arg.startsWith("-")) && !RUNNER_FLAGS.has(arg)) {
-			vitestPassthroughArgs.push(arg);
-			// Consume the next token if it looks like a value (not another flag)
-			if (i + 1 < args.length && !args[i + 1].startsWith("-")) {
-				vitestPassthroughArgs.push(args[++i]);
-			}
-		} else {
-			// Any remaining token (cannot start with '-'; those are caught above)
-			testPatterns.push(arg);
-		}
-	}
-
-	return {
-		testListFile,
-		showErrorDetails,
-		coverageQuiet,
-		logFile,
-		suppressFileOutput,
-		suppressPassingFiles,
-		topSummary,
-		json,
-		blobsDir,
-		mergeReports,
-		help,
-		workers,
-		soloPatterns,
-		testFilePattern,
-		vitestPassthroughArgs,
-		testPatterns
-	};
-}

package/src/cli/help.mjs

@@ -1,86 +0,0 @@
-/**
- * @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 mirrored runner output (default: coverage/coverage-run.log with --coverage-quiet)
-  --suppress-file-output  Suppress per-file runner output blocks
-  --suppress-passing-files  Hide the PASSED TEST FILES section in the final summary
-  --no-top-summary        Hide TOP MEMORY USERS and TOP DURATION sections
-  --json                  Emit JSON summary output instead of text logs
-  --blobs-dir <path>      Directory for per-file coverage blobs (default: .vitest-coverage-blobs)
-  --no-merge-reports      Leave coverage blobs in --blobs-dir without merging (for an external merge)
-  --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

@@ -1,167 +0,0 @@
-/**
- * @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}`, { cause: err });
-		}
-
-		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);
-}