@vitest-agent/plugin 1.0.0

package/services/ConfigValidation.js

@@ -0,0 +1,11 @@
+import { Context } from "effect";
+
+//#region src/services/ConfigValidation.ts
+/**
+* Effect service for validating Vitest + plugin coverage configuration.
+* @public
+*/
+var ConfigValidation = class extends Context.Tag("vitest-agent/ConfigValidation")() {};
+
+//#endregion
+export { ConfigValidation };

package/services/CoverageAnalyzer.js

@@ -0,0 +1,11 @@
+import { Context } from "effect";
+
+//#region src/services/CoverageAnalyzer.ts
+/**
+* Effect service for processing istanbul coverage maps into structured reports.
+* @public
+*/
+var CoverageAnalyzer = class extends Context.Tag("vitest-agent/CoverageAnalyzer")() {};
+
+//#endregion
+export { CoverageAnalyzer };

package/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.58.9"
+    }
+  ]
+}

package/utils/build-module-info.js

@@ -0,0 +1,62 @@
+import { toPosixPath } from "./to-posix-path.js";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, relative } from "node:path";
+
+//#region src/utils/build-module-info.ts
+const NOT_FOUND = {
+	packageName: "",
+	packagePath: ""
+};
+const cache = /* @__PURE__ */ new Map();
+const resolvePackageInfo = (filePath) => {
+	let dir = dirname(filePath);
+	const visited = [];
+	while (true) {
+		const cached = cache.get(dir);
+		if (cached !== void 0) {
+			for (const v of visited) cache.set(v, cached);
+			return cached;
+		}
+		visited.push(dir);
+		const pkgJsonPath = `${dir}/package.json`;
+		if (existsSync(pkgJsonPath)) try {
+			const pkg = JSON.parse(readFileSync(pkgJsonPath, "utf8"));
+			const result = {
+				packageName: typeof pkg.name === "string" ? pkg.name : "",
+				packagePath: dir
+			};
+			for (const v of visited) cache.set(v, result);
+			return result;
+		} catch {}
+		const parent = dirname(dir);
+		if (parent === dir) {
+			for (const v of visited) cache.set(v, NOT_FOUND);
+			return NOT_FOUND;
+		}
+		dir = parent;
+	}
+};
+/**
+* Build a {@link ModuleInfo} for the given file path by walking up the
+* directory tree to locate the nearest `package.json`. Results are cached
+* per directory so the walk runs at most once per workspace package across
+* the whole test run.
+*
+* Query strings (Vite virtual module suffixes like `?v=1234`) are stripped
+* before the walk so the cache key is always a clean filesystem path.
+*/
+const buildModuleInfo = (filePath) => {
+	const queryIndex = filePath.indexOf("?");
+	const cleanId = queryIndex === -1 ? filePath : filePath.slice(0, queryIndex);
+	const { packageName, packagePath } = resolvePackageInfo(cleanId);
+	return {
+		path: cleanId,
+		relativePath: toPosixPath(relative(process.cwd(), cleanId)),
+		filename: basename(cleanId),
+		packageName,
+		packagePath
+	};
+};
+
+//#endregion
+export { buildModuleInfo };

package/utils/build-reporter-kit.js

@@ -0,0 +1,49 @@
+import { osc8 } from "@vitest-agent/sdk";
+
+//#region src/utils/build-reporter-kit.ts
+const buildReporterKit = (input) => {
+	const consoleOutput = input.consoleMode === "silent" ? "silent" : "failures";
+	const githubSummary = input.githubActions;
+	const githubSummaryFile = process.env.GITHUB_STEP_SUMMARY;
+	const config = {
+		executor: input.executor,
+		consoleMode: input.consoleMode,
+		mcp: input.mcp,
+		consoleOutput,
+		omitPassingTests: true,
+		coverageConsoleLimit: 10,
+		includeBareZero: false,
+		githubActions: input.githubActions,
+		githubSummary,
+		format: input.format,
+		detail: input.detail,
+		noColor: input.noColor,
+		coverageMode: input.coverageMode,
+		transport: input.transport,
+		...input.dbPath !== void 0 && { dbPath: input.dbPath },
+		...input.projectFilter !== void 0 && { projectFilter: input.projectFilter },
+		...githubSummaryFile !== void 0 && { githubSummaryFile },
+		...input.runCommand !== void 0 && { runCommand: input.runCommand },
+		...input.coverageThresholds !== void 0 && { coverageThresholds: input.coverageThresholds },
+		...input.coverageTargets !== void 0 && { coverageTargets: input.coverageTargets },
+		...input.passWithNoTests !== void 0 && { passWithNoTests: input.passWithNoTests }
+	};
+	const osc8Enabled = !input.noColor && (input.env === "terminal" || input.env === "agent-shell");
+	return {
+		config,
+		stdEnv: input.env,
+		stdOsc8: (url, label) => osc8(url, label, { enabled: osc8Enabled }),
+		...input.runEvents !== void 0 && { runEvents: input.runEvents }
+	};
+};
+/**
+* Normalize the result of {@link VitestAgentReporterFactory} to an array.
+* The factory contract allows returning either a single reporter or an
+* array of reporters; the plugin always works with the array form.
+*/
+const normalizeReporters = (result) => {
+	return Array.isArray(result) ? result : [result];
+};
+
+//#endregion
+export { buildReporterKit, normalizeReporters };

package/utils/capture-env.js

@@ -0,0 +1,23 @@
+//#region src/utils/capture-env.ts
+const ALWAYS_CAPTURE = [
+	"CI",
+	"NODE_ENV",
+	"VITEST_MODE"
+];
+/**
+* Capture CI and GitHub Actions environment variables for persistence.
+* @param env - The process environment record to read from
+* @returns A filtered map of relevant environment variable keys and values
+* @public
+*/
+function captureEnvVars(env) {
+	const result = {};
+	for (const key of ALWAYS_CAPTURE) if (env[key] !== void 0) result[key] = env[key];
+	if (env.GITHUB_ACTIONS) {
+		for (const [key, value] of Object.entries(env)) if (value !== void 0 && (key.startsWith("GITHUB_") || key.startsWith("RUNNER_"))) result[key] = value;
+	}
+	return result;
+}
+
+//#endregion
+export { captureEnvVars };

package/utils/capture-settings.js

@@ -0,0 +1,54 @@
+import { createHash } from "node:crypto";
+
+//#region src/utils/capture-settings.ts
+/**
+* Extract a serializable settings snapshot from the resolved Vitest config.
+* @param config - The resolved Vitest config record
+* @param vitestVersion - The running Vitest version string
+* @returns A `SettingsInput` ready for persistence
+* @public
+*/
+function captureSettings(config, vitestVersion) {
+	const pool = config.pool;
+	const environment = config.environment;
+	const testTimeout = config.testTimeout;
+	const hookTimeout = config.hookTimeout;
+	const slowTestThreshold = config.slowTestThreshold;
+	const maxConcurrency = config.maxConcurrency;
+	const maxWorkers = config.maxWorkers;
+	const isolate = config.isolate;
+	const bail = config.bail;
+	const globals = config.globals;
+	const fileParallelism = config.fileParallelism;
+	const sequenceSeed = config.sequence?.seed;
+	const coverageProvider = config.coverage?.provider;
+	return {
+		vitestVersion,
+		...pool !== void 0 && { pool },
+		...environment !== void 0 && { environment },
+		...testTimeout !== void 0 && { testTimeout },
+		...hookTimeout !== void 0 && { hookTimeout },
+		...slowTestThreshold !== void 0 && { slowTestThreshold },
+		...maxConcurrency !== void 0 && { maxConcurrency },
+		...maxWorkers !== void 0 && { maxWorkers },
+		...isolate !== void 0 && { isolate },
+		...bail !== void 0 && { bail },
+		...globals !== void 0 && { globals },
+		...fileParallelism !== void 0 && { fileParallelism },
+		...sequenceSeed !== void 0 && { sequenceSeed },
+		...coverageProvider !== void 0 && { coverageProvider }
+	};
+}
+/**
+* Compute a stable SHA-256 hash of a settings record for change detection.
+* @param settings - The settings record to hash (keys are sorted for stability)
+* @returns A hex-encoded SHA-256 digest
+* @public
+*/
+function hashSettings(settings) {
+	const json = JSON.stringify(settings, Object.keys(settings).sort());
+	return createHash("sha256").update(json).digest("hex");
+}
+
+//#endregion
+export { captureSettings, hashSettings };

package/utils/classify-helpers.js

@@ -0,0 +1,72 @@
+import { toPosixPath } from "./to-posix-path.js";
+
+//#region src/utils/classify-helpers.ts
+/**
+* Creates a ClassifyFn that maps filename suffix patterns to tag arrays.
+*
+* Accepts two forms:
+* - `Record<string, ReadonlyArray<string>>` — keys are exact suffix strings
+*   (e.g. ".int.test.ts"); matched via `String.prototype.endsWith` against
+*   `module.filename`.
+* - `ReadonlyArray<readonly [RegExp, ReadonlyArray<string>]>` — each tuple is a
+*   `[pattern, tags]` pair; matched via `RegExp.test` against `module.filename`.
+*   First match wins.
+*
+* No match returns an empty array.
+* @public
+*/
+function classifyByFilename(suffixMap) {
+	if (Array.isArray(suffixMap)) {
+		const entries = suffixMap;
+		return (ctx) => {
+			for (const [pattern, tags] of entries) if (pattern.test(ctx.module.filename)) return tags;
+			return [];
+		};
+	}
+	const entries = Object.entries(suffixMap);
+	return (ctx) => {
+		for (const [suffix, tags] of entries) if (ctx.module.filename.endsWith(suffix)) return tags;
+		return [];
+	};
+}
+/**
+* Creates a ClassifyFn that maps directory segment paths to tag arrays.
+*
+* Keys are directory-segment paths (e.g. `__test__/integration`). A module
+* matches when `module.relativePath` contains the segment with `/` boundaries.
+* Key `"integration"` matches `"integration/foo.test.ts"` and
+* `"src/integration/foo.test.ts"` but NOT `"my-integration-tests/foo.test.ts"`.
+*
+* No match returns `[]`.
+* @public
+*/
+function classifyByDirectory(dirMap) {
+	const entries = Object.entries(dirMap);
+	return (ctx) => {
+		const rel = toPosixPath(ctx.module.relativePath);
+		for (const [segment, tags] of entries) if (rel === segment || rel.startsWith(`${segment}/`) || rel.endsWith(`/${segment}`) || rel.includes(`/${segment}/`)) return tags;
+		return [];
+	};
+}
+/**
+* Composes multiple `ClassifyFn` values into one. Each classifier is called with
+* the same context; results are concatenated in order and deduplicated by tag
+* name (first occurrence wins). An empty list returns a function that always
+* returns `[]`.
+* @public
+*/
+function combineClassifiers(...fns) {
+	if (fns.length === 0) return (_ctx) => [];
+	return (ctx) => {
+		const seen = /* @__PURE__ */ new Set();
+		const result = [];
+		for (const fn of fns) for (const tag of fn(ctx)) if (!seen.has(tag)) {
+			seen.add(tag);
+			result.push(tag);
+		}
+		return result;
+	};
+}
+
+//#endregion
+export { classifyByDirectory, classifyByFilename, combineClassifiers };

package/utils/discover-projects.js

@@ -0,0 +1,68 @@
+import { toPosixPath } from "./to-posix-path.js";
+import { DefaultDiscoverStrategy } from "./discover-strategy.js";
+import { isAbsolute, join, normalize, relative } from "node:path";
+import { findWorkspaceRootSync, getWorkspacePackagesSync } from "workspaces-effect";
+
+//#region src/utils/discover-projects.ts
+const _cache = /* @__PURE__ */ new Map();
+/**
+* Scan all workspace packages and additional entries through the active strategy and return projects + tags.
+* @param options - Optional strategy, working directory, and extra project entries
+* @returns Resolved projects and tag definitions
+* @public
+*/
+async function discoverProjects(options) {
+	const strategy = options?.strategy;
+	const cwd = options?.cwd;
+	const additionalEntries = options?.additionalEntries ?? [];
+	const root = findWorkspaceRootSync(cwd ?? process.cwd());
+	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;
+	if (useCache) {
+		const cached = _cache.get(root);
+		if (cached) return cached;
+	}
+	const resolvedStrategy = strategy ?? new DefaultDiscoverStrategy();
+	const packages = getWorkspacePackagesSync(root);
+	const configs = [];
+	const workspaceNames = /* @__PURE__ */ new Set();
+	const workspacePaths = /* @__PURE__ */ new Set();
+	for (const pkg of packages) {
+		const config = await resolvedStrategy.buildProject({
+			name: pkg.name,
+			path: pkg.path,
+			relativePath: toPosixPath(pkg.relativePath),
+			workspaceRoot: root
+		});
+		if (config !== null) configs.push(config);
+		workspaceNames.add(pkg.name);
+		workspacePaths.add(normalize(pkg.path));
+	}
+	for (const entry of additionalEntries) {
+		const normPath = normalize(isAbsolute(entry.path) ? entry.path : join(root, entry.path));
+		if (workspaceNames.has(entry.name)) throw new Error(`[vitest-agent] .addProject() conflict: name "${entry.name}" already exists as a workspace package. Use a different name or omit the .addProject() call.`);
+		if (workspacePaths.has(normPath)) throw new Error(`[vitest-agent] .addProject() conflict: resolved path "${normPath}" already exists as a workspace package path. Remove the .addProject() call or adjust the path.`);
+		const relativePath = toPosixPath(relative(root, normPath));
+		const config = await resolvedStrategy.buildProject({
+			name: entry.name,
+			path: normPath,
+			relativePath,
+			workspaceRoot: root
+		});
+		if (config === null) {
+			const strategyName = resolvedStrategy.constructor.name;
+			throw new Error(`[vitest-agent] .addProject({ name: "${entry.name}", path: "${entry.path}" }) resolved to path "${normPath}" but ${strategyName} found no test files there. Ensure the directory contains test files matching the strategy's patterns.`);
+		}
+		configs.push(config);
+	}
+	const tags = [...resolvedStrategy.tagDefinitions];
+	const result = {
+		projects: configs.length > 0 ? configs : void 0,
+		tags
+	};
+	if (useCache) _cache.set(root, result);
+	return result;
+}
+
+//#endregion
+export { discoverProjects };

package/utils/discover-strategy.js

@@ -0,0 +1,158 @@
+import { findTestFiles } from "./find-test-files.js";
+import { Tag } from "./tag.js";
+import { join, sep } from "node:path";
+import { stat } from "node:fs/promises";
+
+//#region src/utils/discover-strategy.ts
+const SETUP_EXTS = [
+	"ts",
+	"tsx",
+	"js",
+	"jsx"
+];
+const TEST_DIR_HELPER_DIRS = [
+	"utils",
+	"fixtures",
+	"snapshots"
+];
+async function isDir(p) {
+	try {
+		return (await stat(p)).isDirectory();
+	} catch {
+		return false;
+	}
+}
+async function isFile(p) {
+	try {
+		return (await stat(p)).isFile();
+	} catch {
+		return false;
+	}
+}
+async function detectSetupFile(pkgPath) {
+	for (const ext of SETUP_EXTS) if (await isFile(join(pkgPath, `vitest.setup.${ext}`))) return `vitest.setup.${ext}`;
+	return null;
+}
+/**
+* Abstract base for workspace discovery strategies. Implement `buildProject` and
+* `classify` to control which packages become Vitest projects and how their test
+* files are tagged. Use `DiscoverStrategy.create` to build a concrete instance
+* from plain functions, or extend `DefaultDiscoverStrategy` to layer on top of
+* the built-in unit/int/e2e heuristics.
+* @public
+*/
+var DiscoverStrategy = class {
+	static create(options) {
+		return new ConcreteDiscoverStrategy(options.tags, [options.classify], [options.buildProject]);
+	}
+};
+var ConcreteDiscoverStrategy = class ConcreteDiscoverStrategy extends DiscoverStrategy {
+	tags;
+	#classifyLayers;
+	#buildProjectLayers;
+	constructor(tags, classifyLayers, buildProjectLayers) {
+		super();
+		this.tags = tags;
+		this.#classifyLayers = classifyLayers;
+		this.#buildProjectLayers = buildProjectLayers;
+	}
+	get tagDefinitions() {
+		return this.tags.map((t) => t.definition);
+	}
+	classify(ctx) {
+		const baseLayer = this.#classifyLayers[0];
+		let inherited = baseLayer({
+			module: ctx.module,
+			tags: this.tags,
+			inherited: []
+		});
+		for (let i = 1; i < this.#classifyLayers.length; i++) {
+			const layer = this.#classifyLayers[i];
+			inherited = layer({
+				module: ctx.module,
+				tags: this.tags,
+				inherited
+			});
+		}
+		return inherited;
+	}
+	async buildProject(input) {
+		const baseLayer = this.#buildProjectLayers[0];
+		let result = await baseLayer(input);
+		for (let i = 1; i < this.#buildProjectLayers.length; i++) {
+			const layer = this.#buildProjectLayers[i];
+			result = await layer(input, result);
+		}
+		return result;
+	}
+	extend(options) {
+		const newTags = [...this.tags, ...options.additionalTags ?? []];
+		const newClassifyLayers = [...this.#classifyLayers];
+		if (options.classify) newClassifyLayers.push(options.classify);
+		const newBuildProjectLayers = [...this.#buildProjectLayers];
+		if (options.buildProject) newBuildProjectLayers.push(options.buildProject);
+		return new ConcreteDiscoverStrategy(newTags, newClassifyLayers, newBuildProjectLayers);
+	}
+};
+const DEFAULT_TAGS = [
+	Tag.make("unit"),
+	Tag.make("int", { timeout: 6e4 }),
+	Tag.make("e2e", {
+		timeout: 12e4,
+		retry: process.env.CI ? 2 : 0
+	})
+];
+const E2E_RE = /\.e2e\.(test|spec)\.(ts|tsx|js|jsx)$/;
+const INT_RE = /\.int\.(test|spec)\.(ts|tsx|js|jsx)$/;
+/**
+* The built-in `DiscoverStrategy` used by `AgentPlugin.discover` when no custom
+* strategy is supplied. Registers `unit`, `int` (60 s timeout), and `e2e`
+* (120 s timeout, retry in CI) tags and classifies test files by filename suffix
+* (`.int.test.*` → `"int"`, `.e2e.test.*` → `"e2e"`, everything else → `"unit"`).
+* @public
+*/
+var DefaultDiscoverStrategy = class extends DiscoverStrategy {
+	tags = DEFAULT_TAGS;
+	get tagDefinitions() {
+		return this.tags.map((t) => t.definition);
+	}
+	classify(ctx) {
+		if (E2E_RE.test(ctx.module.filename)) return ["e2e"];
+		if (INT_RE.test(ctx.module.filename)) return ["int"];
+		return ["unit"];
+	}
+	async buildProject(input) {
+		const hasTestDir = await isDir(join(input.path, "__test__"));
+		const srcPrefix = join(input.path, "src");
+		const testPrefix = join(input.path, "__test__");
+		const allFiles = await findTestFiles(input.path, ["src/**/*.{test,spec}.{ts,tsx,js,jsx}", "__test__/**/*.{test,spec}.{ts,tsx,js,jsx}"]);
+		if (allFiles.length === 0) return null;
+		const hasSrcTests = allFiles.some((f) => f.startsWith(`${srcPrefix}${sep}`) || f === srcPrefix);
+		const hasTestDirTests = allFiles.some((f) => f.startsWith(`${testPrefix}${sep}`) || f === testPrefix);
+		const include = [];
+		if (hasSrcTests) include.push(join(input.path, "src/**/*.{test,spec}.{ts,tsx,js,jsx}"));
+		if (hasTestDirTests) include.push(join(input.path, "__test__/**/*.{test,spec}.{ts,tsx,js,jsx}"));
+		const exclude = hasTestDir ? TEST_DIR_HELPER_DIRS.map((d) => join(input.path, `__test__/${d}/**`)) : void 0;
+		const setupFile = await detectSetupFile(input.path);
+		return {
+			extends: true,
+			test: {
+				name: input.name,
+				environment: "node",
+				include,
+				...exclude ? { exclude } : {},
+				...setupFile ? { setupFiles: [join(input.path, setupFile)] } : {}
+			}
+		};
+	}
+	extend(options) {
+		return DiscoverStrategy.create({
+			tags: this.tags,
+			classify: (ctx) => this.classify(ctx),
+			buildProject: (input) => this.buildProject(input)
+		}).extend(options);
+	}
+};
+
+//#endregion
+export { DefaultDiscoverStrategy, DiscoverStrategy };

package/utils/find-test-files.js

@@ -0,0 +1,94 @@
+import { toPosixPath } from "./to-posix-path.js";
+import { join, relative } from "node:path";
+import { readdir } from "node:fs/promises";
+
+//#region src/utils/find-test-files.ts
+const SKIP_DIRS = /* @__PURE__ */ new Set([
+	"node_modules",
+	".git",
+	"dist"
+]);
+function globToRegex(pattern) {
+	const alts = expandBraces(pattern).map(toRegexFragment);
+	return new RegExp(`^(?:${alts.join("|")})$`);
+}
+/** Expands the FIRST brace group found in a pattern string. Recursive to handle nesting. */
+function expandBraces(pattern) {
+	const open = pattern.indexOf("{");
+	if (open === -1) return [pattern];
+	const close = pattern.indexOf("}", open);
+	if (close === -1) return [pattern];
+	const prefix = pattern.slice(0, open);
+	const suffix = pattern.slice(close + 1);
+	const alternatives = pattern.slice(open + 1, close).split(",");
+	const results = [];
+	for (const alt of alternatives) for (const expanded of expandBraces(`${prefix}${alt}${suffix}`)) results.push(expanded);
+	return results;
+}
+/** Converts a brace-free glob string into a regex fragment (no ^ or $). */
+function toRegexFragment(glob) {
+	let result = "";
+	let i = 0;
+	while (i < glob.length) {
+		const ch = glob[i];
+		if (ch === "*") if (glob[i + 1] === "*") {
+			result += "(?:.+/|)";
+			i += 2;
+			if (glob[i] === "/") i++;
+		} else {
+			result += "[^/]*";
+			i++;
+		}
+		else if (ch === "?") {
+			result += "[^/]";
+			i++;
+		} else if (/[.+^${}()|[\]\\]/.test(ch)) {
+			result += `\\${ch}`;
+			i++;
+		} else {
+			result += ch;
+			i++;
+		}
+	}
+	return result;
+}
+/**
+* Async file walker that returns matched absolute paths.
+*
+* Walks `dir` recursively via `node:fs/promises`. Skips `node_modules`, `.git`,
+* and `dist` directories. Matches files against the supplied glob patterns
+* relative to `dir` (e.g. `"src/**\/*.test.ts"`).
+*
+* Returns an empty array if `dir` does not exist or no files match.
+* @param dir - Absolute path to the directory to walk
+* @param patterns - Glob patterns to match against (relative to `dir`)
+* @returns Absolute paths of matched test files
+* @public
+*/
+async function findTestFiles(dir, patterns) {
+	if (patterns.length === 0) return [];
+	const matchers = patterns.map(globToRegex);
+	const results = [];
+	await walkDir(dir, dir, matchers, results);
+	return results;
+}
+async function walkDir(root, dir, matchers, results) {
+	let entries;
+	try {
+		entries = await readdir(dir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	for (const ent of entries) {
+		if (SKIP_DIRS.has(ent.name)) continue;
+		const fullPath = join(dir, ent.name);
+		if (ent.isDirectory()) await walkDir(root, fullPath, matchers, results);
+		else if (ent.isFile()) {
+			const rel = toPosixPath(relative(root, fullPath));
+			if (matchers.some((re) => re.test(rel))) results.push(fullPath);
+		}
+	}
+}
+
+//#endregion
+export { findTestFiles };