@vitest-agent/plugin 1.0.0

package/utils/inject-tags.js

@@ -0,0 +1,94 @@
+import * as acorn from "acorn";
+import { tsPlugin } from "acorn-typescript";
+import MagicString from "magic-string";
+
+//#region src/utils/inject-tags.ts
+const Parser = acorn.Parser.extend(tsPlugin());
+const TEST_NAMES = /* @__PURE__ */ new Set(["test", "it"]);
+function rootIdentifier(n) {
+	if (n.type === "Identifier") return n;
+	if (n.type === "MemberExpression") return rootIdentifier(n.object);
+	if (n.type === "CallExpression") return rootIdentifier(n.callee);
+	return null;
+}
+function isTestCallee(callee) {
+	const root = rootIdentifier(callee);
+	return !!root && TEST_NAMES.has(root.name);
+}
+function hasTagsField(objectExpression) {
+	const props = objectExpression.properties ?? [];
+	for (const p of props) {
+		if (p.type !== "Property") continue;
+		const key = p.key;
+		if (key.type === "Identifier" && key.name === "tags") return true;
+		if (key.type === "Literal" && key.value === "tags") return true;
+	}
+	return false;
+}
+function tagsLiteral(tags) {
+	return `[${tags.map((t) => JSON.stringify(t)).join(", ")}]`;
+}
+function walk(node, visit) {
+	visit(node);
+	for (const key of Object.keys(node)) {
+		if (key === "type" || key === "start" || key === "end" || key === "loc") continue;
+		const v = node[key];
+		if (Array.isArray(v)) {
+			for (const item of v) if (item && typeof item === "object" && "type" in item) walk(item, visit);
+		} else if (v && typeof v === "object" && "type" in v) walk(v, visit);
+	}
+}
+function injectTags(source, tags) {
+	if (tags.length === 0) return null;
+	let ast;
+	try {
+		ast = Parser.parse(source, {
+			ecmaVersion: "latest",
+			sourceType: "module",
+			locations: true
+		});
+	} catch {
+		return null;
+	}
+	const ms = new MagicString(source);
+	let mutated = false;
+	walk(ast, (node) => {
+		if (node.type !== "CallExpression") return;
+		const callee = node.callee;
+		if (!isTestCallee(callee)) return;
+		const args = node.arguments ?? [];
+		if (args.length < 2) return;
+		const last = args[args.length - 1];
+		if (!(last.type === "FunctionExpression" || last.type === "ArrowFunctionExpression")) return;
+		const optsCandidate = args.length >= 3 ? args[args.length - 2] : null;
+		if (optsCandidate) {
+			if (optsCandidate.type === "ObjectExpression") {
+				if (hasTagsField(optsCandidate)) return;
+				const lastProp = (optsCandidate.properties ?? []).at(-1);
+				if (lastProp === void 0) {
+					const insertPoint = optsCandidate.end - 1;
+					ms.appendLeft(insertPoint, `tags: ${tagsLiteral(tags)} `);
+				} else ms.appendLeft(lastProp.end, `, tags: ${tagsLiteral(tags)}`);
+				mutated = true;
+				return;
+			}
+			const optsStart = optsCandidate.start;
+			const optsEnd = optsCandidate.end;
+			const origExpr = source.slice(optsStart, optsEnd);
+			ms.overwrite(optsStart, optsEnd, `{ ...(${origExpr}), tags: ${tagsLiteral(tags)} }`);
+			mutated = true;
+			return;
+		}
+		const nameArg = args[0];
+		ms.appendRight(nameArg.end, `, { tags: ${tagsLiteral(tags)} }`);
+		mutated = true;
+	});
+	if (!mutated) return null;
+	return {
+		code: ms.toString(),
+		map: ms.generateMap({ hires: true })
+	};
+}
+
+//#endregion
+export { injectTags };

package/utils/process-failure.js

@@ -0,0 +1,89 @@
+import { computeFailureSignature, findFunctionBoundary } from "@vitest-agent/sdk";
+import { readFileSync } from "node:fs";
+
+//#region src/utils/process-failure.ts
+const FRAME_LINE_REGEX = /^\s*at\s+(?:([\w$.<>[\] ]+?)\s+)?\(?([^\n)]+):(\d+):(\d+)\)?\s*$/;
+const isFrameworkPath = (filePath) => filePath.includes("/node_modules/") || filePath.includes("vitest/dist") || filePath.includes("@vitest/") || filePath.startsWith("node:");
+const parseFramesFromStackString = (stack) => {
+	const frames = [];
+	let ordinal = 0;
+	for (const line of stack.split("\n")) {
+		const m = FRAME_LINE_REGEX.exec(line);
+		if (m === null) continue;
+		frames.push({
+			ordinal: ordinal++,
+			method: m[1] ?? null,
+			filePath: m[2],
+			line: Number.parseInt(m[3], 10),
+			col: Number.parseInt(m[4], 10),
+			sourceMapped: false
+		});
+	}
+	return frames;
+};
+const readSourceSafe = (filePath) => {
+	try {
+		return readFileSync(filePath, "utf-8");
+	} catch {
+		return null;
+	}
+};
+/**
+* Convert a Vitest error into structured frame inputs (with source-map and
+* function-boundary annotations) plus a stable failure signature.
+*
+* Returns `null` for the signature when no usable top frame is found
+* (error has no stack, or every frame is in framework code). Frames may
+* still be populated even when the signature is null.
+* @public
+*/
+const processFailure = (error) => {
+	const rawFrames = error.stacks !== void 0 && error.stacks.length > 0 ? error.stacks.map((f, ordinal) => ({
+		ordinal,
+		method: f.method ?? null,
+		filePath: f.file ?? "<unknown>",
+		line: f.line ?? 0,
+		col: f.column ?? 0,
+		sourceMapped: true
+	})) : error.stack !== void 0 ? parseFramesFromStackString(error.stack) : [];
+	const topFrame = rawFrames.find((f) => f.filePath !== "<unknown>" && !isFrameworkPath(f.filePath));
+	let topBoundaryLine = null;
+	let topFunctionName = null;
+	if (topFrame !== void 0) {
+		const lineForBoundary = topFrame.line;
+		const source = readSourceSafe(topFrame.filePath);
+		const boundary = source !== null ? findFunctionBoundary(source, lineForBoundary) : null;
+		if (boundary !== null) {
+			topBoundaryLine = boundary.line;
+			topFunctionName = boundary.name;
+		}
+	}
+	const frames = rawFrames.map((f) => {
+		return {
+			ordinal: f.ordinal,
+			method: f.method,
+			filePath: f.filePath,
+			line: f.line,
+			col: f.col,
+			...f.sourceMapped && { sourceMappedLine: f.line },
+			...topFrame !== void 0 && f.ordinal === topFrame.ordinal && topBoundaryLine !== null && { functionBoundaryLine: topBoundaryLine }
+		};
+	});
+	if (topFrame === void 0) return {
+		frames,
+		signatureHash: null
+	};
+	return {
+		frames,
+		signatureHash: computeFailureSignature({
+			error_name: error.name ?? "Error",
+			assertion_message: error.message,
+			top_frame_function_name: topFunctionName ?? topFrame.method ?? "<anonymous>",
+			top_frame_function_boundary_line: topBoundaryLine,
+			top_frame_raw_line: topFrame.line
+		})
+	};
+};
+
+//#endregion
+export { processFailure };

package/utils/resolve-thresholds.js

@@ -0,0 +1,65 @@
+//#region src/utils/resolve-thresholds.ts
+const METRIC_KEYS = /* @__PURE__ */ new Set([
+	"lines",
+	"functions",
+	"branches",
+	"statements"
+]);
+const RESERVED_KEYS = /* @__PURE__ */ new Set([
+	...METRIC_KEYS,
+	"100",
+	"perFile",
+	"autoUpdate"
+]);
+/**
+* Parse Vitest `coverage.thresholds` format into a normalized `ResolvedThresholds`.
+* @param input - The raw `coverage.thresholds` object from Vitest config
+* @returns Normalized thresholds with global, perFile, and pattern entries
+* @public
+*/
+function resolveThresholds(input) {
+	if (!input) return {
+		global: {},
+		perFile: false,
+		patterns: []
+	};
+	const global = {};
+	const patterns = [];
+	let perFile = false;
+	if (input["100"] === true) {
+		global.lines = 100;
+		global.functions = 100;
+		global.branches = 100;
+		global.statements = 100;
+	}
+	for (const key of METRIC_KEYS) {
+		const value = input[key];
+		if (typeof value === "number") global[key] = value;
+	}
+	if (input.perFile === true) perFile = true;
+	for (const [key, value] of Object.entries(input)) {
+		if (RESERVED_KEYS.has(key)) continue;
+		if (typeof value !== "object" || value === null) continue;
+		const patternMetrics = {};
+		const obj = value;
+		if (obj["100"] === true) {
+			patternMetrics.lines = 100;
+			patternMetrics.functions = 100;
+			patternMetrics.branches = 100;
+			patternMetrics.statements = 100;
+		}
+		for (const mk of METRIC_KEYS) {
+			const mv = obj[mk];
+			if (typeof mv === "number") patternMetrics[mk] = mv;
+		}
+		if (Object.keys(patternMetrics).length > 0) patterns.push([key, patternMetrics]);
+	}
+	return {
+		global,
+		perFile,
+		patterns
+	};
+}
+
+//#endregion
+export { resolveThresholds };

package/utils/route-rendered-output.js

@@ -0,0 +1,45 @@
+import { appendFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+
+//#region src/utils/route-rendered-output.ts
+/**
+* Route a {@link RenderedOutput} entry to its declared target.
+*
+* Centralizes the side-effects that user-supplied reporters get to stay
+* pure about: writing to stdout, appending to a github-summary file, or
+* writing to an arbitrary file path. The plugin's internal Vitest reporter
+* calls this once per `RenderedOutput` returned by the user's reporter(s).
+*
+* `github-summary` writes go to `kit.config.githubSummaryFile` if set,
+* otherwise `process.env.GITHUB_STEP_SUMMARY`. When neither is set the
+* write is silently dropped — the typical case is "we're not under
+* GitHub Actions and the user-supplied reporter shouldn't have produced
+* one anyway."
+*
+* `file` outputs require an explicit path embedded in the output (a
+* convention reporters should adopt; this helper currently treats `file`
+* as a no-op until we settle on a path field). The default reporter
+* never produces `file` outputs today, so this gap is theoretical.
+*
+* @internal
+*/
+const routeRenderedOutput = (output, options) => {
+	switch (output.target) {
+		case "stdout":
+			process.stdout.write(`${output.content.replace(/\n+$/, "")}\n`);
+			return;
+		case "github-summary": {
+			const path = options.githubSummaryFile ?? process.env.GITHUB_STEP_SUMMARY;
+			if (!path) return;
+			try {
+				mkdirSync(dirname(path), { recursive: true });
+				appendFileSync(path, output.content, "utf8");
+			} catch {}
+			return;
+		}
+		case "file": return;
+	}
+};
+
+//#endregion
+export { routeRenderedOutput };

package/utils/stringify-failure-value.js

@@ -0,0 +1,36 @@
+//#region src/utils/stringify-failure-value.ts
+/**
+* Converts a raw Vitest assertion value (`.expected` / `.actual`) into a
+* one-line string suitable for display in the stream renderer.
+*
+* The value stays within the Vitest-side error object; this helper
+* converts it to a string representation that crosses the ReportError
+* schema boundary. Returns `undefined` when there is no value to show
+* (i.e., the input is `undefined`).
+*
+* @packageDocumentation
+*/
+/**
+* Stringify a raw Vitest assertion `.expected` or `.actual` value into a
+* single-line string.
+*
+* - `undefined` → `undefined` (signals "no value — omit the field")
+* - `null` → `"null"`
+* - primitives (string, number, boolean, bigint) → `String(value)`
+* - objects / arrays → `JSON.stringify(value)`, falling back to
+*   `String(value)` for circular or otherwise un-serialisable values
+*/
+const stringifyFailureValue = (value) => {
+	if (value === void 0) return void 0;
+	if (value === null) return "null";
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return String(value);
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return String(value);
+	}
+};
+
+//#endregion
+export { stringifyFailureValue };

package/utils/strip-console-reporters.js

@@ -0,0 +1,45 @@
+//#region src/utils/strip-console-reporters.ts
+/**
+* Built-in Vitest reporters that write to the console (stdout).
+* These are the reporters suppressed when an agent takes over console output.
+*
+* @privateRemarks
+* `"agent"` is the built-in Vitest reporter added in v4.1 that reduces
+* console noise for AI agents. We strip it because our reporter replaces
+* its functionality with structured markdown output.
+*
+* @see {@link https://vitest.dev/api/advanced/reporters.html | Vitest Reporter docs}
+* @internal
+*/
+const CONSOLE_REPORTERS = /* @__PURE__ */ new Set([
+	"default",
+	"verbose",
+	"tree",
+	"dot",
+	"tap",
+	"tap-flat",
+	"hanging-process",
+	"agent"
+]);
+/**
+* Filter out built-in console reporters from a Vitest reporters array.
+*
+* Keeps custom reporters (class instances, file paths) and non-console
+* built-in reporters (`json`, `junit`, `html`, `blob`, `github-actions`).
+* Used by `AgentPlugin` in agent mode to suppress noisy console output.
+*
+* @param reporters - The Vitest `config.reporters` array
+* @returns Filtered array with console reporters removed
+*
+* @internal
+*/
+function stripConsoleReporters(reporters) {
+	return reporters.filter((entry) => {
+		if (typeof entry === "string") return !CONSOLE_REPORTERS.has(entry);
+		if (Array.isArray(entry) && typeof entry[0] === "string") return !CONSOLE_REPORTERS.has(entry[0]);
+		return true;
+	});
+}
+
+//#endregion
+export { CONSOLE_REPORTERS, stripConsoleReporters };

package/utils/tag.js

@@ -0,0 +1,42 @@
+//#region src/utils/tag.ts
+const RESERVED = /* @__PURE__ */ new Set([
+	"and",
+	"or",
+	"not"
+]);
+const FORBIDDEN_CHAR = /[()&|!*\s]/;
+function validateTagName(name) {
+	if (!name) throw new Error("Tag name is empty");
+	if (RESERVED.has(name)) throw new Error(`Tag name "${name}" is reserved (and/or/not)`);
+	if (FORBIDDEN_CHAR.test(name)) throw new Error(`Tag name "${name}" contains an invalid character (no spaces, ()&|!*)`);
+}
+/**
+* A validated Vitest tag with its `name` string and a `TestTagDefinition` for registration.
+* @public
+*/
+var Tag = class Tag {
+	/** The tag name string (validated on construction). */
+	name;
+	/** The full `TestTagDefinition` object to pass to Vitest's `test.tags` config. */
+	definition;
+	constructor(name, options) {
+		this.name = name;
+		this.definition = {
+			name,
+			...options
+		};
+	}
+	/**
+	* Create a validated `Tag`.
+	* @param name - Tag identifier; must not be empty, reserved, or contain forbidden characters
+	* @param options - Optional timeout, retry, and other Vitest tag settings
+	* @returns A new `Tag` instance
+	*/
+	static make(name, options = {}) {
+		validateTagName(name);
+		return new Tag(name, options);
+	}
+};
+
+//#endregion
+export { Tag };

package/utils/to-posix-path.js

@@ -0,0 +1,35 @@
+//#region src/utils/to-posix-path.ts
+/**
+* Normalize a filesystem path to forward-slash separators.
+*
+* Single source of truth for the POSIX-style path strings the plugin uses
+* in three places where the path is compared against a slash-only pattern
+* or surfaced to user code that documents slash semantics:
+*
+* - `buildModuleInfo.relativePath` — consumed by user-supplied `ClassifyFn`
+*   implementations and by the bundled `classifyByDirectory` helper.
+* - `find-test-files` regex matching — `globToRegex` compiles patterns
+*   with `/` boundaries.
+* - `discoverProjects` `addProject` relativePath — passed to
+*   `strategy.buildProject` and exposed via `DiscoverInput.relativePath`.
+*
+* Always folds backslashes to forward slashes regardless of the host
+* platform. On POSIX the call is effectively a no-op for paths produced
+* by `node:path` operations (they never contain backslashes there) but
+* still defends against custom DiscoverStrategy implementations that
+* pass through a Windows-style path string. On Windows, where `node:path`
+* returns backslash separators, this folds them so glob matching and
+* slash-bounded segment checks both work without platform-specific
+* branching at every call site.
+*
+* Returns the input unchanged when no backslashes are present — only the
+* separator characters are touched. Callers that need the platform-native
+* form (e.g. for `readFile`) should pass the original path produced by
+* `join` rather than the value returned here.
+*/
+function toPosixPath(p) {
+	return p.indexOf("\\") === -1 ? p : p.split("\\").join("/");
+}
+
+//#endregion
+export { toPosixPath };