@vitest-agent/plugin 2.3.1 → 2.4.0

package/index.d.ts

@@ -4,6 +4,7 @@ import { Context, Effect, Layer, LogLevel, Option } from "effect";
 import { TestProjectInlineConfiguration } from "vitest/config";
 import { ResolvedConfig, VitestPluginContext } from "vitest/node";
 import { SourceMap } from "magic-string";
+import { WorkspacesSyncOptions } from "@effected/workspaces/node-sync";
 import * as NodeServices from "@effect/platform-node/NodeServices";
 import * as SqliteMigrator from "@effect/sql-sqlite-node/SqliteMigrator";
 //#region src/utils/tag.d.ts
@@ -31,6 +32,85 @@ declare class Tag {
   static make(name: string, options?: TagOptions): Tag;
 }
 //#endregion
+//#region src/utils/walker-fs.d.ts
+/**
+ * The filesystem operations the discovery walkers need, supplied by the
+ * caller. Node's built-ins satisfy it directly via {@link nodeWalkerFs}, which
+ * is what every production call site uses.
+ *
+ * The port exists because the walkers used to call `node:fs/promises` outright,
+ * which made them untestable against anything but a real temporary directory —
+ * a virtual filesystem cannot intercept a direct `node:fs` call. Every test in
+ * this package that exercised discovery therefore had to build, populate and
+ * tear down a real tmp tree.
+ *
+ * Deliberately NOT `fs.promises`-shaped: the walkers need exactly two
+ * operations, and a wider surface would invite call sites to reach past the
+ * port. It is also NOT shaped like `@effected/workspaces`'s `SyncFileSystem`
+ * (which this package consumes separately, in `discover-projects.ts`) — that
+ * port answers entry *names*, and the walkers need the entry *type* that
+ * `readdir({ withFileTypes: true })` returns in the same syscall. Reading names
+ * and then stat-ing each one is the syscall-doubling this module exists to
+ * avoid; see {@link WalkerEntry}.
+ *
+ * @packageDocumentation
+ */
+/**
+ * One directory entry, carrying the name and type together.
+ *
+ * A structural subset of Node's `Dirent`, so a real `Dirent` satisfies it
+ * verbatim and `readdir({ withFileTypes: true })` needs no adaptation.
+ * @public
+ */
+interface WalkerEntry {
+  /** The entry's own name, not a path. */
+  readonly name: string;
+  /** Whether this entry is a regular file. */
+  readonly isFile: () => boolean;
+  /** Whether this entry is a directory. */
+  readonly isDirectory: () => boolean;
+}
+/**
+ * The filesystem operations the discovery walkers need.
+ *
+ * Both operations may reject; every walker absorbs a rejection as "this path
+ * contributes nothing" rather than propagating it, matching the behavior the
+ * `node:fs` calls had when they were inline.
+ * @public
+ */
+interface WalkerFileSystem {
+  /**
+   * The entries inside the directory at `dir`, with their types. May reject —
+   * a rejection reads as an unreadable directory and skips it.
+   */
+  readonly readDirectory: (dir: string) => Promise<ReadonlyArray<WalkerEntry>>;
+  /**
+   * The type of the entry at `path`, or `null` when it does not exist or
+   * cannot be read. Never rejects.
+   */
+  readonly statEntry: (path: string) => Promise<WalkerEntryStat | null>;
+}
+/**
+ * What the walkers read off a `stat`: the entry's type, plus the modification
+ * time the discovery cache's directory signature is built from.
+ * @public
+ */
+interface WalkerEntryStat {
+  /** Whether the path holds a regular file. */
+  readonly isFile: boolean;
+  /** Whether the path holds a directory. */
+  readonly isDirectory: boolean;
+  /** Modification time in milliseconds since the epoch. */
+  readonly mtimeMs: number;
+}
+/**
+ * {@link WalkerFileSystem} over `node:fs/promises` — the binding every
+ * production call site uses, and the default when a walker is called without
+ * an explicit port.
+ * @public
+ */
+declare const nodeWalkerFs: WalkerFileSystem;
+//#endregion
 //#region src/utils/discover-strategy.d.ts
 /**
  * Resolved metadata about a discovered test module.
@@ -73,6 +153,12 @@ interface DiscoverInput {
   readonly workspaceRoot: string;
   /** Parsed `package.json` contents, when available. */
   readonly packageJson?: PackageJson;
+  /**
+   * Filesystem port the walkers read through. Defaults to `node:fs` when
+   * omitted, which is what every production call site does; tests inject a
+   * virtual volume instead of building a real temporary directory.
+   */
+  readonly fs?: WalkerFileSystem;
 }
 /**
  * Context object passed to a `ClassifyFn`.
@@ -938,6 +1024,16 @@ interface DiscoverProjectsOptions {
     readonly name: string;
     readonly path: string;
   }>;
+  /**
+   * Filesystem port the test-file and signature walks read through. Defaults
+   * to `node:fs`; tests inject a virtual volume instead of a real tmp tree.
+   */
+  readonly fs?: WalkerFileSystem;
+  /**
+   * Sync operations `@effected/workspaces` resolves the workspace root and
+   * package list through. Defaults to its `nodeSyncOps` binding.
+   */
+  readonly syncOps?: WorkspacesSyncOptions;
 }
 /**
  * Scan all workspace packages and additional entries through the active strategy and return projects + tags.
@@ -1006,7 +1102,7 @@ declare function combineClassifiers(...fns: ReadonlyArray<ClassifyFn>): Classify
  * @returns Absolute paths of matched test files
  * @public
  */
-declare function findTestFiles(dir: string, patterns: ReadonlyArray<string>): Promise<ReadonlyArray<string>>;
+declare function findTestFiles(dir: string, patterns: ReadonlyArray<string>, fs?: WalkerFileSystem): Promise<ReadonlyArray<string>>;
 //#endregion
 //#region src/layers/ReporterLive.d.ts
 /**
@@ -1247,5 +1343,5 @@ declare const COVERAGE_AUTOUPDATE: Readonly<{
   lenient: (n: number) => number;
 }>;
 //#endregion
-export { type AddProjectInput, AgentPlugin, type AgentPluginConstructorOptions, AgentReporter, type AgentReporterConstructorOptions, CONSOLE_REPORTERS, COVERAGE_AUTOUPDATE, COVERAGE_LEVELS, COVERAGE_LEVELS_PER_FILE, CURRENT_PLUGIN_VERSION, type ClassifyContext, type ClassifyFn, ConfigValidation, ConfigValidationLive, ConfigValidationTest, CoverageAnalyzer, CoverageAnalyzerLive, CoverageAnalyzerTest, type CoverageInput, CoverageLevel, type CoverageLevelName, type CoverageLevelPreset, type CoverageOptions, DefaultDiscoverStrategy, type DiscoverBuilder, type DiscoverInput, type PackageJson as DiscoverPackageJson, type DiscoverProjectsOptions, type DiscoverProjectsResult, type DiscoverResult, DiscoverStrategy, type DiscoverStrategyCreateOptions, type DiscoverStrategyExtendOptions, type InjectTagsResult, type ModuleInfo, ReporterLive, Tag, type TagOptions, type ValidationError, type ValidationInfo, type ValidationInput, type ValidationResult, type ValidationWarning, type VitestErrorLike, type VitestStackFrameLike, type VitestThresholdsInput, captureEnvVars, captureSettings, classifyByDirectory, classifyByFilename, combineClassifiers, discoverProjects, findTestFiles, hashSettings, processFailure, resolveCoverageInput, resolveThresholds, stripConsoleReporters, validateCoverageConfig };
+export { type AddProjectInput, AgentPlugin, type AgentPluginConstructorOptions, AgentReporter, type AgentReporterConstructorOptions, CONSOLE_REPORTERS, COVERAGE_AUTOUPDATE, COVERAGE_LEVELS, COVERAGE_LEVELS_PER_FILE, CURRENT_PLUGIN_VERSION, type ClassifyContext, type ClassifyFn, ConfigValidation, ConfigValidationLive, ConfigValidationTest, CoverageAnalyzer, CoverageAnalyzerLive, CoverageAnalyzerTest, type CoverageInput, CoverageLevel, type CoverageLevelName, type CoverageLevelPreset, type CoverageOptions, DefaultDiscoverStrategy, type DiscoverBuilder, type DiscoverInput, type PackageJson as DiscoverPackageJson, type DiscoverProjectsOptions, type DiscoverProjectsResult, type DiscoverResult, DiscoverStrategy, type DiscoverStrategyCreateOptions, type DiscoverStrategyExtendOptions, type InjectTagsResult, type ModuleInfo, ReporterLive, Tag, type TagOptions, type ValidationError, type ValidationInfo, type ValidationInput, type ValidationResult, type ValidationWarning, type VitestErrorLike, type VitestStackFrameLike, type VitestThresholdsInput, type WalkerEntry, type WalkerEntryStat, type WalkerFileSystem, captureEnvVars, captureSettings, classifyByDirectory, classifyByFilename, combineClassifiers, discoverProjects, findTestFiles, hashSettings, nodeWalkerFs, processFailure, resolveCoverageInput, resolveThresholds, stripConsoleReporters, validateCoverageConfig };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -8,6 +8,7 @@ import { captureEnvVars } from "./utils/capture-env.js";
 import { captureSettings, hashSettings } from "./utils/capture-settings.js";
 import { processFailure } from "./utils/process-failure.js";
 import { AgentReporter } from "./reporter.js";
+import { nodeWalkerFs } from "./utils/walker-fs.js";
 import { findTestFiles } from "./utils/find-test-files.js";
 import { Tag } from "./utils/tag.js";
 import { DefaultDiscoverStrategy, DiscoverStrategy } from "./utils/discover-strategy.js";
@@ -28,4 +29,4 @@ const COVERAGE_LEVELS_PER_FILE = AgentPlugin.COVERAGE_LEVELS_PER_FILE;
 const COVERAGE_AUTOUPDATE = AgentPlugin.COVERAGE_AUTOUPDATE;
 
 //#endregion
-export { AgentPlugin, AgentReporter, CONSOLE_REPORTERS, COVERAGE_AUTOUPDATE, COVERAGE_LEVELS, COVERAGE_LEVELS_PER_FILE, CURRENT_PLUGIN_VERSION, ConfigValidation, ConfigValidationLive, ConfigValidationTest, CoverageAnalyzer, CoverageAnalyzerLive, CoverageAnalyzerTest, CoverageLevel, DefaultDiscoverStrategy, DiscoverStrategy, ReporterLive, Tag, captureEnvVars, captureSettings, classifyByDirectory, classifyByFilename, combineClassifiers, discoverProjects, findTestFiles, hashSettings, processFailure, resolveCoverageInput, resolveThresholds, stripConsoleReporters, validateCoverageConfig };
+export { AgentPlugin, AgentReporter, CONSOLE_REPORTERS, COVERAGE_AUTOUPDATE, COVERAGE_LEVELS, COVERAGE_LEVELS_PER_FILE, CURRENT_PLUGIN_VERSION, ConfigValidation, ConfigValidationLive, ConfigValidationTest, CoverageAnalyzer, CoverageAnalyzerLive, CoverageAnalyzerTest, CoverageLevel, DefaultDiscoverStrategy, DiscoverStrategy, ReporterLive, Tag, captureEnvVars, captureSettings, classifyByDirectory, classifyByFilename, combineClassifiers, discoverProjects, findTestFiles, hashSettings, nodeWalkerFs, processFailure, resolveCoverageInput, resolveThresholds, stripConsoleReporters, validateCoverageConfig };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vitest-agent/plugin",
-	"version": "2.3.1",
+	"version": "2.4.0",
 	"private": false,
 	"description": "Vitest plugin for the vitest-agent ecosystem: owns persistence, classification, baselines, trends, and dispatches rendering to a configurable reporter.",
 	"keywords": [
@@ -41,13 +41,13 @@
 	"dependencies": {
 		"@effect/platform-node": "4.0.0-rc.109",
 		"@effect/sql-sqlite-node": "4.0.0-rc.109",
-		"@effected/workspaces": "^0.14.2",
-		"@vitest-agent/cli": "2.2.1",
-		"@vitest-agent/mcp": "2.3.1",
-		"@vitest-agent/reporter": "2.1.1",
-		"@vitest-agent/sdk": "2.4.1",
+		"@effected/workspaces": "^0.16.0",
+		"@vitest-agent/cli": "2.2.3",
+		"@vitest-agent/mcp": "2.3.3",
+		"@vitest-agent/reporter": "2.1.3",
+		"@vitest-agent/sdk": "2.4.3",
 		"effect": "4.0.0-rc.109",
-		"magic-string": "^1.2.0"
+		"magic-string": "^1.2.1"
 	},
 	"peerDependencies": {
 		"@vitest/coverage-istanbul": "^4.1.0",

package/plugin.js

@@ -100,7 +100,7 @@ const aggregatedReporterByVitest = /* @__PURE__ */ new WeakSet();
 *
 * @public
 */
-const CURRENT_PLUGIN_VERSION = "2.3.1";
+const CURRENT_PLUGIN_VERSION = "2.4.0";
 const TEST_FILE_DIR_RE = new RegExp(`/(?:${SRC_DIR}|${TEST_DIR})/`);
 const isTestFile = (id) => isTestFileName(id) && TEST_FILE_DIR_RE.test(id);
 /**

package/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.58.12"
+      "packageVersion": "7.58.13"
     }
   ]
 }

package/utils/discover-projects.js

@@ -1,22 +1,22 @@
 import { toPosixPath } from "./to-posix-path.js";
+import { nodeWalkerFs } from "./walker-fs.js";
 import { DefaultDiscoverStrategy } from "./discover-strategy.js";
 import { isTestShapedPackage } from "./is-test-shaped-package.js";
 import { NON_DISCOVERABLE_DIRS, SRC_DIR, TEST_DIR } from "@vitest-agent/sdk";
 import { isAbsolute, join, normalize, relative } from "node:path";
-import { readdir, stat } from "node:fs/promises";
 import { findWorkspaceRootSync, getWorkspacePackagesSync } from "@effected/workspaces";
 import { nodeSyncOps } from "@effected/workspaces/node-sync";
 
 //#region src/utils/discover-projects.ts
 const DISCOVERY_LAST_SCAN_SYMBOL = Symbol.for("vitest-agent:discovery:last-scan-at");
 const warnedDeclinedPackagePaths = /* @__PURE__ */ new Set();
-async function warnIfDeclinedPackageIsTestShaped(pkg) {
+async function warnIfDeclinedPackageIsTestShaped(pkg, fs) {
 	const normPath = normalize(pkg.path);
 	if (warnedDeclinedPackagePaths.has(normPath)) return;
 	warnedDeclinedPackagePaths.add(normPath);
 	let testShaped;
 	try {
-		testShaped = await isTestShapedPackage(pkg.path);
+		testShaped = await isTestShapedPackage(pkg.path, fs);
 	} catch (error) {
 		warnedDeclinedPackagePaths.delete(normPath);
 		throw error;
@@ -44,16 +44,16 @@ const _cache = /* @__PURE__ */ new Map();
 * subprocess-e2e fixture that installs deps), and Node's recursive `readdir`
 * follows symlinked directories, so an unguarded call would walk into it.
 */
-async function computeDirSignature(dirPath) {
+async function computeDirSignature(dirPath, fs) {
 	const parts = [];
-	await walkDirSignature(dirPath, dirPath, parts);
+	await walkDirSignature(dirPath, dirPath, parts, fs);
 	parts.sort();
 	return parts.join("|");
 }
-async function walkDirSignature(root, dir, parts) {
+async function walkDirSignature(root, dir, parts, fs) {
 	let entries;
 	try {
-		entries = await readdir(dir, { withFileTypes: true });
+		entries = await fs.readDirectory(dir);
 	} catch {
 		return;
 	}
@@ -61,14 +61,11 @@ async function walkDirSignature(root, dir, parts) {
 		const fullPath = join(dir, ent.name);
 		if (ent.isDirectory()) {
 			if (NON_DISCOVERABLE_DIRS.has(ent.name)) continue;
-			await walkDirSignature(root, fullPath, parts);
+			await walkDirSignature(root, fullPath, parts, fs);
 		} else if (ent.isFile()) {
-			let mtimeMs;
-			try {
-				mtimeMs = (await stat(fullPath)).mtimeMs;
-			} catch {
-				continue;
-			}
+			const info = await fs.statEntry(fullPath);
+			if (info === null) continue;
+			const mtimeMs = info.mtimeMs;
 			const relPath = toPosixPath(relative(root, fullPath));
 			parts.push(`${relPath}:${mtimeMs}`);
 		}
@@ -85,11 +82,11 @@ async function walkDirSignature(root, dir, parts) {
 * test file anywhere else, so nothing else can change the emitted project list
 * (issue #227).
 */
-async function computeWorkspaceSignature(packages) {
+async function computeWorkspaceSignature(packages, fs) {
 	const parts = [];
 	for (const pkg of packages) {
-		const srcSig = await computeDirSignature(join(pkg.path, SRC_DIR));
-		const testSig = await computeDirSignature(join(pkg.path, TEST_DIR));
+		const srcSig = await computeDirSignature(join(pkg.path, SRC_DIR), fs);
+		const testSig = await computeDirSignature(join(pkg.path, TEST_DIR), fs);
 		parts.push(`${pkg.path}::src=${srcSig}::__test__=${testSig}`);
 	}
 	return parts.join("\n");
@@ -104,14 +101,16 @@ async function discoverProjects(options) {
 	const strategy = options?.strategy;
 	const cwd = options?.cwd;
 	const additionalEntries = options?.additionalEntries ?? [];
-	const root = findWorkspaceRootSync(cwd ?? process.cwd(), nodeSyncOps);
+	const fs = options?.fs ?? nodeWalkerFs;
+	const syncOps = options?.syncOps ?? nodeSyncOps;
+	const root = findWorkspaceRootSync(cwd ?? process.cwd(), syncOps);
 	if (!root) throw new Error(`[vitest-agent] Could not find workspace root from ${cwd ?? process.cwd()}. Ensure a pnpm-workspace.yaml or package.json with "workspaces" exists.`);
 	const useCache = strategy === void 0 && additionalEntries.length === 0;
 	const resolvedStrategy = strategy ?? new DefaultDiscoverStrategy();
-	const packages = getWorkspacePackagesSync(root, nodeSyncOps);
+	const packages = getWorkspacePackagesSync(root, syncOps);
 	let signature;
 	if (useCache) {
-		signature = await computeWorkspaceSignature(packages);
+		signature = await computeWorkspaceSignature(packages, fs);
 		const cached = _cache.get(root);
 		if (cached && cached.signature === signature) return cached.result;
 	}
@@ -123,10 +122,11 @@ async function discoverProjects(options) {
 			name: pkg.name,
 			path: pkg.path,
 			relativePath: toPosixPath(pkg.relativePath),
-			workspaceRoot: root
+			workspaceRoot: root,
+			fs
 		});
 		if (config !== null) configs.push(config);
-		else await warnIfDeclinedPackageIsTestShaped(pkg);
+		else await warnIfDeclinedPackageIsTestShaped(pkg, fs);
 		workspaceNames.add(pkg.name);
 		workspacePaths.add(normalize(pkg.path));
 	}
@@ -140,7 +140,8 @@ async function discoverProjects(options) {
 			name: entry.name,
 			path: normPath,
 			relativePath,
-			workspaceRoot: root
+			workspaceRoot: root,
+			fs
 		});
 		if (config === null) {
 			const strategyName = resolvedStrategy.constructor.name;

package/utils/discover-strategy.js

@@ -1,8 +1,8 @@
+import { nodeWalkerFs } from "./walker-fs.js";
 import { findTestFiles } from "./find-test-files.js";
 import { Tag } from "./tag.js";
 import { NON_DISCOVERABLE_DIRS, SRC_DIR, TEST_DIR, TEST_FILE_GLOB_SUFFIX, TEST_HELPER_DIRS } from "@vitest-agent/sdk";
 import { join, sep } from "node:path";
-import { stat } from "node:fs/promises";
 import { configDefaults } from "vitest/config";
 
 //#region src/utils/discover-strategy.ts
@@ -12,15 +12,11 @@ const SETUP_EXTS = [
 	"js",
 	"jsx"
 ];
-async function isFile(p) {
-	try {
-		return (await stat(p)).isFile();
-	} catch {
-		return false;
+async function detectSetupFile(pkgPath, fs) {
+	for (const ext of SETUP_EXTS) {
+		const candidate = join(pkgPath, `vitest.setup.${ext}`);
+		if ((await fs.statEntry(candidate))?.isFile === true) return `vitest.setup.${ext}`;
 	}
-}
-async function detectSetupFile(pkgPath) {
-	for (const ext of SETUP_EXTS) if (await isFile(join(pkgPath, `vitest.setup.${ext}`))) return `vitest.setup.${ext}`;
 	return null;
 }
 /**
@@ -112,8 +108,9 @@ var DefaultDiscoverStrategy = class extends DiscoverStrategy {
 		return ["unit"];
 	}
 	async buildProject(input) {
+		const fs = input.fs ?? nodeWalkerFs;
 		const srcPrefix = join(input.path, SRC_DIR);
-		const allFiles = await findTestFiles(input.path, [`${SRC_DIR}/**/${TEST_FILE_GLOB_SUFFIX}`, `${TEST_DIR}/**/${TEST_FILE_GLOB_SUFFIX}`]);
+		const allFiles = await findTestFiles(input.path, [`${SRC_DIR}/**/${TEST_FILE_GLOB_SUFFIX}`, `${TEST_DIR}/**/${TEST_FILE_GLOB_SUFFIX}`], fs);
 		if (allFiles.length === 0) return null;
 		const hasSrcTests = allFiles.some((f) => f.startsWith(`${srcPrefix}${sep}`) || f === srcPrefix);
 		const hasTestDirTests = allFiles.some((f) => !(f.startsWith(`${srcPrefix}${sep}`) || f === srcPrefix));
@@ -125,7 +122,7 @@ var DefaultDiscoverStrategy = class extends DiscoverStrategy {
 			...[SRC_DIR, TEST_DIR].flatMap((root) => [...NON_DISCOVERABLE_DIRS].map((d) => join(input.path, root, "**", d, "**"))),
 			...hasTestDirTests ? TEST_HELPER_DIRS.map((d) => join(input.path, TEST_DIR, "**", d, "**")) : []
 		];
-		const setupFile = await detectSetupFile(input.path);
+		const setupFile = await detectSetupFile(input.path, fs);
 		return {
 			extends: true,
 			test: {

package/utils/find-test-files.js

@@ -1,7 +1,7 @@
 import { toPosixPath } from "./to-posix-path.js";
+import { nodeWalkerFs } from "./walker-fs.js";
 import { NON_DISCOVERABLE_DIRS } from "@vitest-agent/sdk";
 import { join, relative } from "node:path";
-import { readdir } from "node:fs/promises";
 
 //#region src/utils/find-test-files.ts
 function globToRegex(pattern) {
@@ -70,17 +70,17 @@ function toRegexFragment(glob) {
 * @returns Absolute paths of matched test files
 * @public
 */
-async function findTestFiles(dir, patterns) {
+async function findTestFiles(dir, patterns, fs = nodeWalkerFs) {
 	if (patterns.length === 0) return [];
 	const matchers = patterns.map(globToRegex);
 	const results = [];
-	await walkDir(dir, dir, matchers, results);
+	await walkDir(dir, dir, matchers, results, fs);
 	return results;
 }
-async function walkDir(root, dir, matchers, results) {
+async function walkDir(root, dir, matchers, results, fs) {
 	let entries;
 	try {
-		entries = await readdir(dir, { withFileTypes: true });
+		entries = await fs.readDirectory(dir);
 	} catch {
 		return;
 	}
@@ -88,7 +88,7 @@ async function walkDir(root, dir, matchers, results) {
 	for (const ent of entries) {
 		if (NON_DISCOVERABLE_DIRS.has(ent.name)) continue;
 		const fullPath = join(dir, ent.name);
-		if (ent.isDirectory()) await walkDir(root, fullPath, matchers, results);
+		if (ent.isDirectory()) await walkDir(root, fullPath, matchers, results, fs);
 		else if (ent.isFile()) {
 			const rel = toPosixPath(relative(root, fullPath));
 			if (matchers.some((re) => re.test(rel))) results.push(fullPath);

package/utils/is-test-shaped-package.js

@@ -1,16 +1,9 @@
+import { nodeWalkerFs } from "./walker-fs.js";
 import { findTestFiles } from "./find-test-files.js";
 import { SRC_DIR, TEST_DIR, TEST_FILE_GLOB_SUFFIX } from "@vitest-agent/sdk";
 import { join } from "node:path";
-import { stat } from "node:fs/promises";
 
 //#region src/utils/is-test-shaped-package.ts
-async function isDirectory(p) {
-	try {
-		return (await stat(p)).isDirectory();
-	} catch {
-		return false;
-	}
-}
 /**
 * True when `pkgPath` looks like it was meant to hold tests: a `__test__/`
 * directory exists at the package root (regardless of what's inside it), or
@@ -31,9 +24,9 @@ async function isDirectory(p) {
 * it needs to catch.
 * @internal
 */
-async function isTestShapedPackage(pkgPath) {
-	if (await isDirectory(join(pkgPath, TEST_DIR))) return true;
-	return (await findTestFiles(pkgPath, [`${SRC_DIR}/**/${TEST_FILE_GLOB_SUFFIX}`])).length > 0;
+async function isTestShapedPackage(pkgPath, fs = nodeWalkerFs) {
+	if ((await fs.statEntry(join(pkgPath, TEST_DIR)))?.isDirectory === true) return true;
+	return (await findTestFiles(pkgPath, [`${SRC_DIR}/**/${TEST_FILE_GLOB_SUFFIX}`], fs)).length > 0;
 }
 
 //#endregion

package/utils/walker-fs.js

@@ -0,0 +1,27 @@
+import { readdir, stat } from "node:fs/promises";
+
+//#region src/utils/walker-fs.ts
+/**
+* {@link WalkerFileSystem} over `node:fs/promises` — the binding every
+* production call site uses, and the default when a walker is called without
+* an explicit port.
+* @public
+*/
+const nodeWalkerFs = {
+	readDirectory: async (dir) => await readdir(dir, { withFileTypes: true }),
+	statEntry: async (path) => {
+		try {
+			const info = await stat(path);
+			return {
+				isFile: info.isFile(),
+				isDirectory: info.isDirectory(),
+				mtimeMs: info.mtimeMs
+			};
+		} catch {
+			return null;
+		}
+	}
+};
+
+//#endregion
+export { nodeWalkerFs };