vitest-bats 0.0.1

package/matchers.js

@@ -0,0 +1,310 @@
+import { BATS_RESULT_BRAND } from "./runtime.js";
+import { validate } from "./schema.js";
+
+//#region src/matchers.ts
+function ensureBatsResult(received) {
+	if (received !== null && typeof received === "object" && received[BATS_RESULT_BRAND] === true) return received;
+	throw new Error("vitest-bats matcher: expected received value to be a BatsResult (the value returned by hello.run() or hello.exec())");
+}
+function ctx(r) {
+	const stderr = r.stderr.length > 200 ? `${r.stderr.slice(0, 200)}…` : r.stderr;
+	const tail = stderr ? `\n  stderr: ${stderr}` : "";
+	return `\n  status: ${r.status}${tail}`;
+}
+function getPath(obj, path) {
+	const parts = [];
+	for (const m of path.matchAll(/([^.[\]]+)|\[(\d+)\]/g)) if (m[1] !== void 0) parts.push(m[1]);
+	else if (m[2] !== void 0) parts.push(Number(m[2]));
+	let current = obj;
+	for (const part of parts) {
+		if (current === null || current === void 0 || typeof current !== "object") return {
+			found: false,
+			value: void 0
+		};
+		if (typeof part === "number") {
+			if (!Array.isArray(current) || part >= current.length) return {
+				found: false,
+				value: void 0
+			};
+			current = current[part];
+		} else {
+			if (!(part in current)) return {
+				found: false,
+				value: void 0
+			};
+			current = current[part];
+		}
+	}
+	return {
+		found: true,
+		value: current
+	};
+}
+function deepEqual(a, b) {
+	if (Object.is(a, b)) return true;
+	if (typeof a !== typeof b) return false;
+	if (a === null || b === null) return false;
+	if (Array.isArray(a)) {
+		if (!Array.isArray(b) || a.length !== b.length) return false;
+		return a.every((x, i) => deepEqual(x, b[i]));
+	}
+	if (typeof a === "object" && typeof b === "object") {
+		const aKeys = Object.keys(a);
+		const bKeys = Object.keys(b);
+		if (aKeys.length !== bKeys.length) return false;
+		return aKeys.every((k) => deepEqual(a[k], b[k]));
+	}
+	return false;
+}
+function partialMatch(actual, expected) {
+	if (expected === null || typeof expected !== "object") return deepEqual(actual, expected);
+	if (Array.isArray(expected)) {
+		if (!Array.isArray(actual)) return false;
+		return expected.every((e, i) => partialMatch(actual[i], e));
+	}
+	if (typeof actual !== "object" || actual === null) return false;
+	return Object.keys(expected).every((k) => partialMatch(actual[k], expected[k]));
+}
+/**
+* The 23 `expect.extend` matchers registered by `vitest-bats/setup` (auto-injected
+* by {@link BatsPlugin}). Cover status, stdout/stderr, lines, mock calls, JSON
+* values, and schema validation against a `BatsResult`.
+* @public
+*/
+const batsMatchers = {
+	toSucceed(received) {
+		const r = ensureBatsResult(received);
+		return {
+			pass: r.status === 0,
+			message: () => r.status === 0 ? `expected script not to succeed, but it did${ctx(r)}` : `expected script to succeed${ctx(r)}`
+		};
+	},
+	toFail(received, code) {
+		const r = ensureBatsResult(received);
+		const pass = code === void 0 ? r.status !== 0 : r.status === code;
+		return {
+			pass,
+			message: () => code === void 0 ? `expected script ${pass ? "not " : ""}to fail${ctx(r)}` : `expected script to fail with code ${code}${ctx(r)}`
+		};
+	},
+	toHaveOutput(received, text) {
+		const r = ensureBatsResult(received);
+		return {
+			pass: r.output === text,
+			message: () => `expected output to be ${JSON.stringify(text)}, got ${JSON.stringify(r.output)}${ctx(r)}`
+		};
+	},
+	toContainOutput(received, text) {
+		const r = ensureBatsResult(received);
+		return {
+			pass: r.output.includes(text),
+			message: () => `expected output to contain ${JSON.stringify(text)}\n  output: ${JSON.stringify(r.output)}${ctx(r)}`
+		};
+	},
+	toMatchOutput(received, pattern) {
+		const r = ensureBatsResult(received);
+		const re = pattern instanceof RegExp ? pattern : new RegExp(pattern);
+		return {
+			pass: re.test(r.output),
+			message: () => `expected output to match ${re}\n  output: ${JSON.stringify(r.output)}${ctx(r)}`
+		};
+	},
+	toHaveEmptyOutput(received) {
+		const r = ensureBatsResult(received);
+		return {
+			pass: r.output === "",
+			message: () => `expected output to be empty\n  output: ${JSON.stringify(r.output)}${ctx(r)}`
+		};
+	},
+	toHaveStderr(received, text) {
+		const r = ensureBatsResult(received);
+		return {
+			pass: r.stderr === text,
+			message: () => `expected stderr to be ${JSON.stringify(text)}, got ${JSON.stringify(r.stderr)}`
+		};
+	},
+	toContainStderr(received, text) {
+		const r = ensureBatsResult(received);
+		return {
+			pass: r.stderr.includes(text),
+			message: () => `expected stderr to contain ${JSON.stringify(text)}\n  stderr: ${JSON.stringify(r.stderr)}`
+		};
+	},
+	toMatchStderr(received, pattern) {
+		const r = ensureBatsResult(received);
+		const re = pattern instanceof RegExp ? pattern : new RegExp(pattern);
+		return {
+			pass: re.test(r.stderr),
+			message: () => `expected stderr to match ${re}\n  stderr: ${JSON.stringify(r.stderr)}`
+		};
+	},
+	toHaveLine(received, index, text) {
+		const r = ensureBatsResult(received);
+		return {
+			pass: r.lines[index] === text,
+			message: () => `expected lines[${index}] to be ${JSON.stringify(text)}, got ${JSON.stringify(r.lines[index])}${ctx(r)}`
+		};
+	},
+	toHaveLineContaining(received, text, index) {
+		const r = ensureBatsResult(received);
+		return {
+			pass: index !== void 0 ? Boolean(r.lines[index]?.includes(text)) : r.lines.some((l) => l.includes(text)),
+			message: () => index !== void 0 ? `expected lines[${index}] to contain ${JSON.stringify(text)}, got ${JSON.stringify(r.lines[index])}${ctx(r)}` : `expected some line to contain ${JSON.stringify(text)}\n  output: ${JSON.stringify(r.output)}${ctx(r)}`
+		};
+	},
+	toHaveLineMatching(received, pattern, index) {
+		const r = ensureBatsResult(received);
+		const re = pattern instanceof RegExp ? pattern : new RegExp(pattern);
+		return {
+			pass: index !== void 0 ? Boolean(r.lines[index] && re.test(r.lines[index])) : r.lines.some((l) => re.test(l)),
+			message: () => index !== void 0 ? `expected lines[${index}] to match ${re}, got ${JSON.stringify(r.lines[index])}${ctx(r)}` : `expected some line to match ${re}\n  output: ${JSON.stringify(r.output)}${ctx(r)}`
+		};
+	},
+	toHaveLineCount(received, n) {
+		const r = ensureBatsResult(received);
+		return {
+			pass: r.lines.length === n,
+			message: () => `expected ${n} line(s), got ${r.lines.length}`
+		};
+	},
+	toOutputJson(received) {
+		const r = ensureBatsResult(received);
+		try {
+			r.json();
+			return {
+				pass: true,
+				message: () => "expected output not to be valid JSON, but it was"
+			};
+		} catch (err) {
+			return {
+				pass: false,
+				message: () => `expected output to be valid JSON: ${err.message}\n  output: ${JSON.stringify(r.output)}`
+			};
+		}
+	},
+	toEqualJson(received, expected) {
+		const r = ensureBatsResult(received);
+		let parsed;
+		try {
+			parsed = r.json();
+		} catch (err) {
+			return {
+				pass: false,
+				message: () => `expected output to be valid JSON: ${err.message}`
+			};
+		}
+		return {
+			pass: deepEqual(parsed, expected),
+			message: () => `expected JSON output to deep-equal ${JSON.stringify(expected)}, got ${JSON.stringify(parsed)}`
+		};
+	},
+	toMatchJson(received, partial) {
+		const r = ensureBatsResult(received);
+		let parsed;
+		try {
+			parsed = r.json();
+		} catch (err) {
+			return {
+				pass: false,
+				message: () => `expected output to be valid JSON: ${err.message}`
+			};
+		}
+		return {
+			pass: partialMatch(parsed, partial),
+			message: () => `expected JSON output to match ${JSON.stringify(partial)}, got ${JSON.stringify(parsed)}`
+		};
+	},
+	toHaveJsonValue(received, path, expected) {
+		const r = ensureBatsResult(received);
+		let parsed;
+		try {
+			parsed = r.json();
+		} catch (err) {
+			return {
+				pass: false,
+				message: () => `expected output to be valid JSON: ${err.message}`
+			};
+		}
+		const { found, value } = getPath(parsed, path);
+		return {
+			pass: found && deepEqual(value, expected),
+			message: () => !found ? `expected JSON path ${JSON.stringify(path)} to exist` : `expected JSON path ${JSON.stringify(path)} to equal ${JSON.stringify(expected)}, got ${JSON.stringify(value)}`
+		};
+	},
+	toHaveJsonPath(received, path) {
+		const r = ensureBatsResult(received);
+		let parsed;
+		try {
+			parsed = r.json();
+		} catch (err) {
+			return {
+				pass: false,
+				message: () => `expected output to be valid JSON: ${err.message}`
+			};
+		}
+		const { found } = getPath(parsed, path);
+		return {
+			pass: found,
+			message: () => `expected JSON path ${JSON.stringify(path)} to exist`
+		};
+	},
+	toMatchSchema(received, schema) {
+		const r = ensureBatsResult(received);
+		let parsed;
+		try {
+			parsed = r.json();
+		} catch (err) {
+			return {
+				pass: false,
+				message: () => `expected output to be valid JSON: ${err.message}`
+			};
+		}
+		const v = validate(schema, parsed);
+		return {
+			pass: v.ok,
+			message: () => v.ok ? "expected output not to match schema, but it did" : `expected output to match schema, but validation failed:\n${v.issues.map((i) => `  - ${i}`).join("\n")}`
+		};
+	},
+	toMatchJsonSchema(received, schema) {
+		const r = ensureBatsResult(received);
+		let parsed;
+		try {
+			parsed = r.json();
+		} catch (err) {
+			return {
+				pass: false,
+				message: () => `expected output to be valid JSON: ${err.message}`
+			};
+		}
+		const v = validate(schema, parsed);
+		return {
+			pass: v.ok,
+			message: () => v.ok ? "expected output not to match JSON schema, but it did" : `expected output to match JSON schema, but validation failed:\n${v.issues.map((i) => `  - ${i}`).join("\n")}`
+		};
+	},
+	toHaveInvoked(received, cmd, opts) {
+		const calls = ensureBatsResult(received).calls[cmd] ?? [];
+		const expectedArgs = opts?.args;
+		return {
+			pass: calls.length > 0 && (expectedArgs === void 0 || calls.some((c) => deepEqual(c.args, expectedArgs))),
+			message: () => expectedArgs === void 0 ? `expected ${cmd} to have been invoked at least once. calls: ${JSON.stringify(calls)}` : `expected ${cmd} to have been invoked with args ${JSON.stringify(expectedArgs)}. calls: ${JSON.stringify(calls)}`
+		};
+	},
+	toHaveInvokedTimes(received, cmd, n) {
+		const calls = ensureBatsResult(received).calls[cmd] ?? [];
+		return {
+			pass: calls.length === n,
+			message: () => `expected ${cmd} to have been invoked ${n} time(s), got ${calls.length}`
+		};
+	},
+	toHaveInvokedExactly(received, cmd, calls) {
+		const actual = ensureBatsResult(received).calls[cmd] ?? [];
+		return {
+			pass: deepEqual(actual, calls),
+			message: () => `expected ${cmd} call history to deep-equal ${JSON.stringify(calls)}, got ${JSON.stringify(actual)}`
+		};
+	}
+};
+
+//#endregion
+export { batsMatchers };

package/package.json

@@ -0,0 +1,68 @@
+{
+	"name": "vitest-bats",
+	"version": "0.0.1",
+	"private": false,
+	"description": "Test bash scripts with kcov coverage directly in Vitest",
+	"keywords": [
+		"vitest",
+		"bats",
+		"bash",
+		"shell",
+		"testing",
+		"kcov",
+		"coverage",
+		"vitest-plugin"
+	],
+	"homepage": "https://github.com/spencerbeggs/vitest-bats#readme",
+	"bugs": {
+		"url": "https://github.com/spencerbeggs/vitest-bats/issues"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/spencerbeggs/vitest-bats.git",
+		"directory": "package"
+	},
+	"license": "MIT",
+	"author": {
+		"name": "C. Spencer Beggs",
+		"email": "spencer@beggs.codes",
+		"url": "https://spencerbeg.gs"
+	},
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./index.d.ts",
+			"import": "./index.js",
+			"default": "./index.js"
+		},
+		"./runtime": {
+			"types": "./runtime.d.ts",
+			"import": "./runtime.js",
+			"default": "./runtime.js"
+		},
+		"./setup": {
+			"types": "./setup.d.ts",
+			"import": "./setup.js",
+			"default": "./setup.js"
+		},
+		"./package.json": "./package.json"
+	},
+	"dependencies": {
+		"@standard-schema/spec": "^1.1.0",
+		"ajv": "^8.20.0",
+		"ajv-formats": "^3.0.1",
+		"fast-xml-parser": "^5.11.1",
+		"minimatch": "^10.2.6"
+	},
+	"peerDependencies": {
+		"vitest": "^4.1.0"
+	},
+	"peerDependenciesMeta": {
+		"vitest": {
+			"optional": false
+		}
+	},
+	"engines": {
+		"node": ">=24.11.0"
+	}
+}

package/plugin.js

@@ -0,0 +1,208 @@
+import { execSync } from "node:child_process";
+import { existsSync, mkdirSync, realpathSync, writeFileSync } from "node:fs";
+import { type } from "node:os";
+import { basename, dirname, resolve } from "node:path";
+
+//#region src/plugin.ts
+function getCommandPath(command) {
+	try {
+		const result = execSync(`command -v ${command}`, {
+			encoding: "utf-8",
+			stdio: "pipe"
+		}).trim();
+		return result ? realpathSync(result) : null;
+	} catch {
+		return null;
+	}
+}
+function detectBatsLibraryPath(libraryName, fileName) {
+	const homeDir = process.env.HOME ?? "";
+	const possiblePaths = [];
+	if (process.env.XDG_CONFIG_HOME) possiblePaths.push(`${process.env.XDG_CONFIG_HOME}/${libraryName}/${fileName}`);
+	if (homeDir) possiblePaths.push(`${homeDir}/.config/${libraryName}/${fileName}`);
+	if (process.env.XDG_DATA_HOME) possiblePaths.push(`${process.env.XDG_DATA_HOME}/${libraryName}/${fileName}`);
+	if (homeDir) possiblePaths.push(`${homeDir}/.local/share/${libraryName}/${fileName}`);
+	possiblePaths.push(`/opt/homebrew/lib/${libraryName}/${fileName}`);
+	possiblePaths.push(`/usr/local/lib/${libraryName}/${fileName}`);
+	possiblePaths.push(`/usr/lib/${libraryName}/${fileName}`);
+	for (const path of possiblePaths) if (existsSync(path)) return dirname(realpathSync(path));
+	return null;
+}
+function getInstallCommand(name, onMacOS) {
+	const cmd = {
+		bats: {
+			mac: "brew install bats-core (requires >= 1.5)",
+			linux: "apt-get install bats (requires >= 1.5; some distros ship older — see https://github.com/bats-core/bats-core)"
+		},
+		"bats-support": {
+			mac: "brew install bats-support",
+			linux: "apt-get install bats-support"
+		},
+		kcov: {
+			mac: "brew install kcov",
+			linux: "apt-get install kcov"
+		},
+		jq: {
+			mac: "brew install jq",
+			linux: "apt-get install jq"
+		}
+	}[name];
+	return cmd ? onMacOS ? cmd.mac : cmd.linux : "See documentation";
+}
+function checkDependencies(options, coverageEnabled, onMacOS) {
+	const logLevel = options.logLevel ?? "errors-only";
+	const deps = [];
+	const batsPath = getCommandPath("bats");
+	let batsVersionOk = batsPath !== null;
+	if (batsPath) try {
+		const m = (execSync(`"${batsPath}" --version`, {
+			encoding: "utf-8",
+			stdio: "pipe"
+		}).trim().split(/\s+/).pop() ?? "").match(/^(\d+)\.(\d+)/);
+		if (!m) batsVersionOk = false;
+		else {
+			const major = Number(m[1]);
+			const minor = Number(m[2]);
+			batsVersionOk = major > 1 || major === 1 && minor >= 5;
+		}
+	} catch {
+		batsVersionOk = false;
+	}
+	deps.push({
+		name: "bats",
+		required: true,
+		available: batsVersionOk,
+		path: batsPath,
+		...batsPath && !batsVersionOk ? { warning: "BATS >= 1.5 required for --separate-stderr" } : {}
+	});
+	const supportPath = detectBatsLibraryPath("bats-support", "load.bash");
+	deps.push({
+		name: "bats-support",
+		required: true,
+		available: supportPath !== null,
+		path: supportPath
+	});
+	const jqPath = getCommandPath("jq");
+	deps.push({
+		name: "jq",
+		required: true,
+		available: jqPath !== null,
+		path: jqPath
+	});
+	if (coverageEnabled) {
+		const kcovPath = getCommandPath("kcov");
+		deps.push({
+			name: "kcov",
+			required: !onMacOS,
+			available: kcovPath !== null,
+			path: kcovPath,
+			...onMacOS && kcovPath ? { warning: "Partial coverage on macOS due to SIP - use Docker for full coverage" } : {}
+		});
+	}
+	if (batsPath) process.env.BATS_PATH = batsPath;
+	if (supportPath) process.env.BATS_SUPPORT_PATH = supportPath;
+	if (coverageEnabled) {
+		const kcovDep = deps.find((d) => d.name === "kcov");
+		if (kcovDep?.path) process.env.KCOV_PATH = kcovDep.path;
+	}
+	process.env.KCOV_LOG_LEVEL = logLevel;
+	if (logLevel === "verbose" || logLevel === "debug") for (const dep of deps) {
+		const pathInfo = dep.path ? ` (${dep.path})` : "";
+		if (dep.warning) console.warn(`  [vitest-bats] ${dep.name}${pathInfo} - ${dep.warning}`);
+		else if (dep.available) console.log(`  [vitest-bats] ${dep.name}${pathInfo}`);
+		else if (dep.required) console.error(`  [vitest-bats] ${dep.name} - MISSING (required)`);
+		else console.warn(`  [vitest-bats] ${dep.name} - not found (optional)`);
+	}
+	return deps;
+}
+function getMissingDeps(deps) {
+	return deps.filter((d) => d.required && !d.available);
+}
+function formatMissingDeps(missing, onMacOS) {
+	return `[vitest-bats] Missing required dependencies:\n${missing.map((d) => `  ${d.name}: ${getInstallCommand(d.name, onMacOS)}`).join("\n")}`;
+}
+const VIRTUAL_PREFIX = "\0bats:";
+/**
+* Vitest plugin that wires up `.sh` imports, dependency detection, coverage
+* option handling, matcher setup-file injection, and coverage reporter injection.
+* @public
+*/
+function BatsPlugin(options = {}) {
+	const registeredScripts = /* @__PURE__ */ new Set();
+	let cacheDir = null;
+	function writeManifest() {
+		if (!cacheDir) return;
+		writeFileSync(resolve(cacheDir, "scripts.json"), JSON.stringify([...registeredScripts], null, "	"), "utf-8");
+	}
+	return {
+		name: "vitest-bats",
+		enforce: "pre",
+		config(config) {
+			const setup = (config.test ?? {}).setupFiles;
+			return { test: { setupFiles: setup === void 0 ? ["vitest-bats/setup"] : Array.isArray(setup) ? [...setup, "vitest-bats/setup"] : [setup, "vitest-bats/setup"] } };
+		},
+		resolveId(source, importer) {
+			if (source.endsWith(".sh") && importer) {
+				const resolved = resolve(dirname(importer), source);
+				if (existsSync(resolved)) return VIRTUAL_PREFIX + resolved;
+			}
+			return null;
+		},
+		load(id) {
+			if (!id.startsWith(VIRTUAL_PREFIX)) return null;
+			const scriptPath = id.slice(6);
+			const scriptName = basename(scriptPath);
+			if (!registeredScripts.has(scriptPath)) {
+				registeredScripts.add(scriptPath);
+				writeManifest();
+			}
+			return ["import { ScriptBuilder } from \"vitest-bats/runtime\";", `export default new ScriptBuilder(${JSON.stringify(scriptPath)}, ${JSON.stringify(scriptName)});`].join("\n");
+		},
+		async configureVitest(ctx) {
+			const { vitest } = ctx;
+			const vitestCacheDir = vitest.config.cacheDir ?? vitest.vite?.config?.cacheDir ?? "node_modules/.vitest";
+			cacheDir = resolve(vitestCacheDir, "vitest-bats");
+			mkdirSync(cacheDir, { recursive: true });
+			const coverageCfg = vitest.config.coverage;
+			const coverageEnabled = coverageCfg?.enabled === true;
+			const onMacOS = type() === "Darwin";
+			const depsMode = options.deps ?? "error";
+			const deps = checkDependencies(options, coverageEnabled, onMacOS);
+			const missing = getMissingDeps(deps);
+			if (missing.length > 0) {
+				const msg = formatMissingDeps(missing, onMacOS);
+				if (depsMode === "error") throw new Error(msg);
+				console.warn(`\n  ${msg}`);
+				console.warn("  [vitest-bats] Running in degraded mode (deps: 'warn'). BATS integration tests will fail individually.\n");
+			}
+			const coverageMode = options.coverage ?? "auto";
+			const kcovAvailable = deps.some((d) => d.name === "kcov" && d.available);
+			const kcovReliable = kcovAvailable && !onMacOS;
+			let includeShCoverage = false;
+			if (coverageMode === true) {
+				if (!kcovAvailable) throw new Error("[vitest-bats] coverage: true requires kcov but it is not available. Install kcov or use coverage: 'auto' to skip shell coverage when unavailable.");
+				if (onMacOS) throw new Error("[vitest-bats] coverage: true is not supported on macOS (SIP blocks kcov ptrace). Use Docker for reliable shell coverage or coverage: 'auto'.");
+				includeShCoverage = true;
+			} else if (coverageMode === "auto") includeShCoverage = kcovReliable;
+			process.env.__VITEST_BATS_CACHE_DIR__ = cacheDir;
+			if (includeShCoverage) process.env.__VITEST_BATS_KCOV__ = "1";
+			if (coverageEnabled) {
+				const { BatsCoverageReporter } = await import("./coverage-reporter.js");
+				const rawThresholds = coverageCfg?.thresholds;
+				const thresholds = rawThresholds ? {
+					statements: rawThresholds.statements ?? 0,
+					branches: rawThresholds.branches ?? 0,
+					functions: rawThresholds.functions ?? 0,
+					lines: rawThresholds.lines ?? 0
+				} : void 0;
+				vitest.config.reporters.unshift(new BatsCoverageReporter(cacheDir, {
+					...thresholds ? { thresholds } : {},
+					statementPassThrough: !includeShCoverage
+				}));
+			}
+		}
+	};
+}
+
+//#endregion
+export { BatsPlugin };

package/runtime.d.ts

@@ -0,0 +1,82 @@
+//#region src/runtime.d.ts
+/**
+ * A single recorded invocation of a mocked command, captured back to the test as
+ * part of {@link BatsResult.calls}.
+ * @public
+ */
+interface MockCall {
+  args: string[];
+}
+/**
+ * The raw fields decoded from a BATS run, wrapped by the {@link BatsResult} class.
+ * @public
+ */
+interface BatsResultData {
+  status: number;
+  output: string;
+  stderr: string;
+  calls: Record<string, MockCall[]>;
+}
+/**
+ * Symbol brand identifying a BatsResult instance. Used by matchers to
+ * detect BatsResult inputs in a way that survives:
+ * - Module-graph duplication (per-entry self-contained bundles produced as
+ *   the workaround for savvy-web/rslib-builder#158, where each entry has
+ *   its own copy of the BatsResult class — `instanceof` would fail).
+ * - Property name minification (a `constructor.name === "BatsResult"`
+ *   check would break under any minifier that renames classes).
+ *
+ * Registered with `Symbol.for(...)` so the symbol is shared across module
+ * graphs (the global symbol registry is process-wide).
+ * @internal
+ */
+declare const BATS_RESULT_BRAND: unique symbol;
+/**
+ * The value returned by `ScriptBuilder.run()`/`.exec()`. Wraps the raw exit status,
+ * stdout/stderr (whole and split into lines), and recorded mock calls; assert
+ * against it with the `expect.extend` matchers from `vitest-bats/setup`.
+ * @public
+ */
+declare class BatsResult {
+  /** @internal */
+  readonly [BATS_RESULT_BRAND] = true;
+  readonly status: number;
+  readonly output: string;
+  readonly stderr: string;
+  readonly lines: string[];
+  readonly stderr_lines: string[];
+  readonly calls: Record<string, MockCall[]>;
+  private _jsonCache;
+  constructor(data: BatsResultData);
+  json<T = unknown>(): T;
+}
+/**
+ * Resets every live `ScriptBuilder`'s `env()`/`flags()`/`mock()` configuration.
+ * Called automatically between tests by `vitest-bats/setup`'s `beforeEach` hook.
+ * @public
+ */
+declare function resetAllBuilders(): void;
+/**
+ * Test-writing API returned by a `.sh` import. Configure with `env()`/`flags()`/
+ * `mock()`, then terminate with `run(...args)` or `exec(shellExpr)` to get a
+ * {@link BatsResult}.
+ * @public
+ */
+declare class ScriptBuilder {
+  readonly path: string;
+  readonly name: string;
+  private _env;
+  private _flags;
+  private _stubs;
+  constructor(path: string, name: string);
+  env(vars: Record<string, string>): this;
+  flags(value: string): this;
+  mock(cmd: string, responses?: Record<string, string>): this;
+  run(...args: string[]): BatsResult;
+  exec(shellExpr: string): BatsResult;
+  reset(): void;
+  private execute;
+}
+//#endregion
+export { BATS_RESULT_BRAND, BatsResult, BatsResultData, MockCall, ScriptBuilder, resetAllBuilders };
+//# sourceMappingURL=runtime.d.ts.map