@cldmv/vitest-runner 1.0.3 → 1.1.0

package/README.md

@@ -53,7 +53,11 @@ vitest-runner [OPTIONS] [PATTERNS...]
 | `--solo-pattern <pat>` | Run files matching this path substring solo (one at a time) before the worker pool; repeatable |
 | `--no-error-details` | Hide inline error blocks — show only counts in the summary |
 | `--coverage-quiet` | Implies `--coverage`; suppress per-file output and show only a live progress bar and final summaries |
-| `--log-file <path>` | Write a clean (ANSI-stripped) copy of all output to this file; implies `--coverage-quiet` when set without it. Defaults to `coverage/coverage-run.log` when `--coverage-quiet` is active |
+| `--log-file <path>` | Write a clean (ANSI-stripped) copy of all output to this file. Defaults to `coverage/coverage-run.log` when `--coverage-quiet` is active |
+| `--suppress-file-output` | Suppress per-file runner output blocks in any mode |
+| `--suppress-passing-files` | Hide the `PASSED TEST FILES` section in the final summary |
+| `--no-top-summary` | Hide `TOP MEMORY USERS` and `TOP DURATION` summary sections |
+| `--json` | Print a JSON run report (no runner text output) |
 | `--help`, `-h` | Print this help and exit |
 
 ### Test patterns
@@ -128,6 +132,12 @@ VITEST_HEAP_MB=8192 vitest-runner --workers 2 src/tests/heavy
 
 # Suppress error details in the summary
 vitest-runner --no-error-details
+
+# JSON output for automation
+vitest-runner --json
+
+# JSON output without top summary arrays
+vitest-runner --json --no-top-summary
 ```
 
 ---
@@ -141,9 +151,9 @@ import { run } from 'vitest-runner';
 const { run } = await require('vitest-runner');
 ```
 
-### `run(options)` → `Promise<number>`
+### `run(options)` → `Promise<number | object>`
 
-Runs the test suite and resolves with an exit code (`0` = all passed, `1` = any failure). Does **not** call `process.exit` — that is the caller's responsibility.
+Runs the test suite and resolves with an exit code (`0` = all passed, `1` = any failure) by default. When `json: true` is passed, it returns a structured JSON report object (including `exitCode`) instead of printing runner text output.
 
 ```js
 import { run } from 'vitest-runner';
@@ -168,6 +178,10 @@ process.exit(code);
 | `vitestArgs` | `string[]` | `[]` | Extra CLI args forwarded verbatim to every vitest invocation |
 | `showErrorDetails` | `boolean` | `true` | Print inline error blocks under each failed file in the summary |
 | `coverageQuiet` | `boolean` | `false` | Suppress per-file output; show only the progress bar and final summaries |
+| `suppressFileOutput` | `boolean` | `false` | Suppress per-file runner output blocks in all modes |
+| `suppressPassingFiles` | `boolean` | `false` | Hide passed-file rows in the final summary |
+| `topSummary` | `boolean` | `true` | Show or hide top memory/duration summary sections (and JSON arrays) |
+| `json` | `boolean` | `false` | Return a JSON report object instead of printing text output |
 | `workers` | `number` | `4` | Maximum parallel worker slots (overrides `VITEST_WORKERS`) |
 | `worstCoverageCount` | `number` | `10` | Rows in the worst-coverage table after a coverage run (`0` disables it) |
 | `maxOldSpaceMb` | `number` | `undefined` | Global `--max-old-space-size` ceiling in MB (overrides `VITEST_HEAP_MB`) |
@@ -208,6 +222,14 @@ await run({
   coverageQuiet: true,
 });
 
+// Machine-readable output (no text logs)
+const report = await run({
+  testDir: 'src/tests',
+  json: true,
+});
+
+console.log(report.exitCode);
+
 // Give heap-heavy files a larger ceiling while keeping the global limit lower
 await run({
   testDir: 'src/tests',
@@ -235,7 +257,7 @@ This avoids the OOM crash that occurs when a single vitest process holds coverag
 
 `--coverage-quiet` / `coverageQuiet: true` suppresses all per-file output and renders a live progress bar instead. On completion it prints the coverage table and any failures verbosely. When running in this mode, output is also mirrored to `coverage/coverage-run.log` (CLI only) with ANSI colour codes stripped so the file is human-readable in any editor.
 
-The log file path can be overridden with `--log-file <path>`. Passing `--log-file` alone (without `--coverage-quiet`) also enables quiet mode and log mirroring.
+The log file path can be overridden with `--log-file <path>`. Passing `--log-file` by itself only enables log mirroring (it does not enable coverage mode).
 
 ---
 

package/bin/vitest-runner.mjs

@@ -3,7 +3,7 @@
  * @fileoverview CLI entry point for the vitest-runner binary.
  * @module vitest-runner/bin/vitest-runner
  *
- * Mirrors its own output to a log file when --coverage-quiet is set, then
+ * Mirrors its own output to a log file when --coverage-quiet or --log-file is set, then
  * delegates all logic to `src/runner.mjs` via the programmatic `run()` API.
  */
 
@@ -23,7 +23,7 @@ if (args.help) {
 
 // Mirror all output (excluding progress bar lines) to a log file
 // when running in --coverage-quiet mode (or when --log-file is set).
-if (args.coverageQuiet || args.logFile) {
+if ((args.coverageQuiet || args.logFile) && !args.json) {
 	const cwd = process.cwd();
 	const resolvedLogFile = args.logFile
 		? path.isAbsolute(args.logFile)
@@ -62,25 +62,34 @@ if (args.coverageQuiet || args.logFile) {
 const cwd = process.cwd();
 
 const vitestArgs = [...args.vitestPassthroughArgs];
-if ((args.coverageQuiet || args.logFile) && !vitestArgs.some((a) => a === "--coverage" || a.startsWith("--coverage."))) {
+if (args.coverageQuiet && !vitestArgs.some((a) => a === "--coverage" || a.startsWith("--coverage."))) {
 	vitestArgs.unshift("--coverage");
 }
 
-run({
-	cwd,
-	testPatterns: args.testPatterns,
-	testListFile: args.testListFile,
-	testFilePattern: args.testFilePattern,
-	vitestArgs,
-	showErrorDetails: args.showErrorDetails,
-	coverageQuiet: args.coverageQuiet,
-	...(args.workers !== undefined && { workers: args.workers }),
-	...(args.soloPatterns.length > 0 && { earlyRunPatterns: args.soloPatterns })
-})
-	.then((code) => {
-		process.exit(code);
-	})
-	.catch((err) => {
-		console.error("Fatal error:", err);
-		process.exit(1);
+try {
+	const runResult = await run({
+		cwd,
+		testPatterns: args.testPatterns,
+		testListFile: args.testListFile,
+		testFilePattern: args.testFilePattern,
+		vitestArgs,
+		showErrorDetails: args.showErrorDetails,
+		coverageQuiet: args.coverageQuiet,
+		suppressFileOutput: args.suppressFileOutput,
+		suppressPassingFiles: args.suppressPassingFiles,
+		topSummary: args.topSummary,
+		json: args.json,
+		...(args.workers !== undefined && { workers: args.workers }),
+		...(args.soloPatterns.length > 0 && { earlyRunPatterns: args.soloPatterns })
 	});
+
+	if (args.json) {
+		process.stdout.write(`${JSON.stringify(runResult, null, 2)}\n`);
+		process.exit(typeof runResult === "object" && runResult !== null && "exitCode" in runResult ? runResult.exitCode : 1);
+	}
+
+	process.exit(typeof runResult === "number" ? runResult : 1);
+} catch (err) {
+	console.error("Fatal error:", err);
+	process.exit(1);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@cldmv/vitest-runner",
-	"version": "1.0.3",
+	"version": "1.1.0",
 	"description": "Sequential Vitest runner to avoid OOM issues with large test suites",
 	"type": "module",
 	"main": "index.cjs",

package/src/cli/args.mjs

@@ -9,6 +9,10 @@
  * @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 {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).
@@ -23,6 +27,10 @@ const RUNNER_FLAGS = new Set([
 	"--no-error-details",
 	"--coverage-quiet",
 	"--log-file",
+	"--suppress-file-output",
+	"--suppress-passing-files",
+	"--no-top-summary",
+	"--json",
 	"--workers",
 	"--solo-pattern",
 	"--file-pattern",
@@ -51,6 +59,10 @@ export function parseArguments(args) {
 	let showErrorDetails = true;
 	let coverageQuiet = false;
 	let logFile;
+	let suppressFileOutput = false;
+	let suppressPassingFiles = false;
+	let topSummary = true;
+	let json = false;
 	let workers;
 	let help = false;
 	let testFilePattern;
@@ -69,6 +81,14 @@ export function parseArguments(args) {
 			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 === "--workers") {
 			workers = parseInt(args[++i], 10);
 		} else if (arg.startsWith("--workers=")) {
@@ -100,6 +120,10 @@ export function parseArguments(args) {
 		showErrorDetails,
 		coverageQuiet,
 		logFile,
+		suppressFileOutput,
+		suppressPassingFiles,
+		topSummary,
+		json,
 		help,
 		workers,
 		soloPatterns,

package/src/cli/help.mjs

@@ -26,7 +26,11 @@ ${chalk.bold("SPECIAL FLAGS:")}
   --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 the coverage run log (default: coverage/coverage-run.log; implies --coverage-quiet)
+  --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
   --help, -h              Show this help message
 
 ${chalk.bold("TEST PATTERNS:")}

package/src/core/report.mjs

@@ -150,9 +150,18 @@ export function computeSummaryFromFinal(finalData) {
  * @param {string} cwd - Project root (used to make absolute file paths relative).
  * @param {string[]} extraCoverageArgs - Passthrough `--coverage.*` args (checked for `reportsDirectory`).
  * @param {number} [worstCount=10] - Number of worst-coverage files to show (0 = skip table).
- * @returns {Promise<void>}
+ * @param {{silent?: boolean}} [options] - Output controls.
+ * @returns {Promise<{
+ *  coverageDir: string,
+ *  total: object,
+ *  worstFiles: Array<{file: string, lines: number, stmts: number, fns: number, branches: number}>,
+ *  worstFilesShown: number,
+ *  worstFilesTotal: number,
+ *  summary: object
+ * }|null>}
  */
-export async function printCoverageSummary(cwd, extraCoverageArgs, worstCount = 10) {
+export async function printCoverageSummary(cwd, extraCoverageArgs, worstCount = 10, options = {}) {
+	const { silent = false } = options;
 	let coverageDir = path.resolve(cwd, "coverage");
 	const repoDirArg = extraCoverageArgs.find((a) => a.startsWith("--coverage.reportsDirectory="));
 	if (repoDirArg) {
@@ -170,8 +179,8 @@ export async function printCoverageSummary(cwd, extraCoverageArgs, worstCount =
 			const content = await fs.readFile(path.join(coverageDir, "coverage-final.json"), "utf8");
 			summary = computeSummaryFromFinal(JSON.parse(content));
 		} catch {
-			console.log(chalk.dim("  (no coverage JSON found — skipping summary)"));
-			return;
+			if (!silent) console.log(chalk.dim("  (no coverage JSON found — skipping summary)"));
+			return null;
 		}
 	}
 
@@ -188,29 +197,59 @@ export async function printCoverageSummary(cwd, extraCoverageArgs, worstCount =
 			}))
 			.filter((r) => Math.min(r.lines, r.stmts, r.fns, r.branches) < 100)
 			.sort((a, b) => Math.min(a.lines, a.stmts, a.fns, a.branches) - Math.min(b.lines, b.stmts, b.fns, b.branches));
+		const rowsToShow = fileRows.slice(0, worstCount);
 
-		console.log("\n" + chalk.bold("📉 WORST COVERAGE FILES (lowest metric)"));
-		console.log("-".repeat(80));
+		if (!silent) {
+			console.log("\n" + chalk.bold("📉 WORST COVERAGE FILES (lowest metric)"));
+			console.log("-".repeat(80));
 
-		const rowsToShow = fileRows.slice(0, worstCount);
-		rowsToShow.forEach(({ file, lines, stmts, fns, branches }) => {
-			const worst = Math.min(lines, stmts, fns, branches);
-			const extras = chalk.dim(
-				`lines ${lines.toFixed(0)}% | stmts ${stmts.toFixed(0)}% | fns ${fns.toFixed(0)}% | branches ${branches.toFixed(0)}%`
-			);
-			console.log(`  ${colourPct(chalk, worst)}%  ${chalk.dim(file)}  ${extras}`);
-		});
+			rowsToShow.forEach(({ file, lines, stmts, fns, branches }) => {
+				const worst = Math.min(lines, stmts, fns, branches);
+				const extras = chalk.dim(
+					`lines ${lines.toFixed(0)}% | stmts ${stmts.toFixed(0)}% | fns ${fns.toFixed(0)}% | branches ${branches.toFixed(0)}%`
+				);
+				console.log(`  ${colourPct(chalk, worst)}%  ${chalk.dim(file)}  ${extras}`);
+			});
+
+			if (fileRows.length > worstCount) {
+				console.log(chalk.dim(`  ... and ${fileRows.length - worstCount} more files`));
+			}
+		}
 
-		if (fileRows.length > worstCount) {
-			console.log(chalk.dim(`  ... and ${fileRows.length - worstCount} more files`));
+		const tl = total.lines?.pct ?? 0;
+		const ts = total.statements?.pct ?? 0;
+		const tf = total.functions?.pct ?? 0;
+		const tb = total.branches?.pct ?? 0;
+		if (!silent) {
+			console.log(
+				`\n  ${chalk.bold("Coverage")}  ${colourPct(chalk, tl)}% lines ${chalk.dim("|")} ${colourPct(chalk, ts)}% statements ${chalk.dim("|")} ${colourPct(chalk, tf)}% functions ${chalk.dim("|")} ${colourPct(chalk, tb)}% branches`
+			);
 		}
+		return {
+			coverageDir,
+			total,
+			worstFiles: rowsToShow,
+			worstFilesShown: rowsToShow.length,
+			worstFilesTotal: fileRows.length,
+			summary
+		};
 	}
 
 	const tl = total.lines?.pct ?? 0;
 	const ts = total.statements?.pct ?? 0;
 	const tf = total.functions?.pct ?? 0;
 	const tb = total.branches?.pct ?? 0;
-	console.log(
-		`\n  ${chalk.bold("Coverage")}  ${colourPct(chalk, tl)}% lines ${chalk.dim("|")} ${colourPct(chalk, ts)}% statements ${chalk.dim("|")} ${colourPct(chalk, tf)}% functions ${chalk.dim("|")} ${colourPct(chalk, tb)}% branches`
-	);
+	if (!silent) {
+		console.log(
+			`\n  ${chalk.bold("Coverage")}  ${colourPct(chalk, tl)}% lines ${chalk.dim("|")} ${colourPct(chalk, ts)}% statements ${chalk.dim("|")} ${colourPct(chalk, tf)}% functions ${chalk.dim("|")} ${colourPct(chalk, tb)}% branches`
+		);
+	}
+	return {
+		coverageDir,
+		total,
+		worstFiles: [],
+		worstFilesShown: 0,
+		worstFilesTotal: 0,
+		summary
+	};
 }

package/src/runner.mjs

@@ -55,6 +55,10 @@ import { colourPct } from "./utils/ansi.mjs";
  * @property {string[]} [vitestArgs=[]] - Extra CLI args forwarded verbatim to every vitest invocation.
  * @property {boolean} [showErrorDetails=true] - Print inline error blocks under each failed file.
  * @property {boolean} [coverageQuiet=false] - Suppress per-file output; show only progress bar + summaries.
+ * @property {boolean} [suppressFileOutput=false] - Suppress per-file runner output blocks in all modes.
+ * @property {boolean} [suppressPassingFiles=false] - Hide passed-file rows in the final summary.
+ * @property {boolean} [topSummary=true] - Show top memory and duration summary sections.
+ * @property {boolean} [json=false] - Return a JSON run report instead of printing text output.
  * @property {number} [workers=4] - Maximum number of parallel worker slots.
  * @property {number} [worstCoverageCount=10] - Rows in the worst-coverage table (0 = disable).
  * @property {number} [maxOldSpaceMb] - Global `--max-old-space-size` ceiling; per-file overrides may raise it.
@@ -96,7 +100,7 @@ function getHeapForFile(filePath, globalMaxMb, overrides) {
  * pool for the non-solo phase) and return an exit code.
  *
  * @param {RunOptions} opts
- * @returns {Promise<number>} `0` on full pass, `1` on any failure.
+ * @returns {Promise<number|object>} `0`/`1` by default; JSON report object when `opts.json` is true.
  */
 export async function run(opts) {
 	const {
@@ -108,6 +112,10 @@ export async function run(opts) {
 		vitestArgs: rawVitestArgs = [],
 		showErrorDetails = true,
 		coverageQuiet = false,
+		suppressFileOutput = false,
+		suppressPassingFiles = false,
+		topSummary = true,
+		json = false,
 		workers = parseInt(process.env.VITEST_WORKERS ?? "4", 10),
 		worstCoverageCount = 10,
 		earlyRunPatterns = [],
@@ -119,6 +127,7 @@ export async function run(opts) {
 	} = opts;
 
 	const maxOldSpaceMb = opts.maxOldSpaceMb ?? (process.env.VITEST_HEAP_MB ? parseInt(process.env.VITEST_HEAP_MB, 10) : undefined);
+	const emitTextOutput = !json;
 
 	// Resolve vitest binary and config
 	const vitestBin = resolveBin(cwd, "vitest", "vitest");
@@ -149,9 +158,28 @@ export async function run(opts) {
 		const allTestFiles = await discoverVitestFiles({ cwd, testDir, testPatterns, testListFile, testFilePattern, earlyRunPatterns });
 
 		if (allTestFiles.length === 0) {
-			console.log(
-				testPatterns.length > 0 ? `❌ No Vitest test files found matching: ${testPatterns.join(", ")}` : "❌ No Vitest test files found"
-			);
+			const noTestsMessage =
+				testPatterns.length > 0 ? `❌ No Vitest test files found matching: ${testPatterns.join(", ")}` : "❌ No Vitest test files found";
+			if (emitTextOutput) console.log(noTestsMessage);
+			if (json) {
+				return {
+					exitCode: 1,
+					mode: "coverage",
+					message: noTestsMessage,
+					options: {
+						cwd,
+						testDir,
+						testPatterns,
+						testListFile,
+						workers,
+						coverageQuiet,
+						suppressFileOutput,
+						suppressPassingFiles,
+						topSummary,
+						vitestArgs
+					}
+				};
+			}
 			return 1;
 		}
 
@@ -161,15 +189,17 @@ export async function run(opts) {
 
 		const soloFiles = allTestFiles.filter((f) => earlyRunPatterns.some((p) => f.replace(/\\/g, "/").includes(p)));
 		const parallelFiles = allTestFiles.filter((f) => !earlyRunPatterns.some((p) => f.replace(/\\/g, "/").includes(p)));
+		const suppressPerFileCoverageOutput = coverageQuiet || suppressFileOutput || json;
+		const showCoverageProgress = coverageQuiet && !json;
 
-		if (!coverageQuiet) {
+		if (!coverageQuiet && !suppressFileOutput && emitTextOutput) {
 			console.log(`\n🧪 Running ${allTestFiles.length} test files for coverage (blob + merge mode)`);
 			console.log(`⚙️  Workers: ${workers} (${soloFiles.length} solo first, then parallel)`);
 			if (maxOldSpaceMb) console.log(`🧠 Heap limit: ${maxOldSpaceMb} MB`);
 			console.log("");
 		}
 
-		const progress = coverageQuiet ? createCoverageProgressTracker(allTestFiles.length) : noopProgressTracker;
+		const progress = showCoverageProgress ? createCoverageProgressTracker(allTestFiles.length) : noopProgressTracker;
 		const coverageResults = [];
 		let blobIndex = 0;
 
@@ -182,7 +212,7 @@ export async function run(opts) {
 			const blobPath = path.join(blobsDir, `run-${blobIndex}.blob`);
 			blobIndex++;
 
-			if (!coverageQuiet) {
+			if (!suppressPerFileCoverageOutput && emitTextOutput) {
 				console.log(`\n${"=".repeat(80)}`);
 				console.log(`▶️  ${filePath}`);
 				console.log("=".repeat(80));
@@ -204,13 +234,13 @@ export async function run(opts) {
 				...spawnBase,
 				maxOldSpaceMb: getHeapForFile(filePath, maxOldSpaceMb, perFileHeapOverrides),
 				vitestArgs: blobArgs,
-				streamOutput: !coverageQuiet
+				streamOutput: !suppressPerFileCoverageOutput
 			});
 
 			coverageResults.push(result);
 			progress.onComplete(result.code !== 0);
 
-			if (!coverageQuiet) {
+			if (!suppressPerFileCoverageOutput && emitTextOutput) {
 				const durationSec = (result.duration / 1000).toFixed(2);
 				if (result.code === 0) {
 					const heapInfo = result.heapMb ? ` | ${result.heapMb} MB heap` : "";
@@ -223,7 +253,9 @@ export async function run(opts) {
 
 		// Phase 1: solo files — one at a time
 		for (const filePath of soloFiles) {
-			await runCoverageFile(filePath).catch((err) => console.error(`Error running ${filePath}:`, err));
+			await runCoverageFile(filePath).catch((err) => {
+				if (emitTextOutput) console.error(`Error running ${filePath}:`, err);
+			});
 		}
 
 		// Phase 2: parallel files with worker pool
@@ -234,7 +266,9 @@ export async function run(opts) {
 			while (coverageFileIndex < parallelFiles.length && coverageActivePromises.size < workers) {
 				const filePath = parallelFiles[coverageFileIndex++];
 				const promise = runCoverageFile(filePath)
-					.catch((err) => console.error(`Error running ${filePath}:`, err))
+					.catch((err) => {
+						if (emitTextOutput) console.error(`Error running ${filePath}:`, err);
+					})
 					.finally(() => coverageActivePromises.delete(promise));
 				coverageActivePromises.add(promise);
 			}
@@ -246,11 +280,48 @@ export async function run(opts) {
 
 		const blobFiles = (await fs.readdir(blobsDir).catch(() => [])).filter((f) => f.endsWith(".blob"));
 		if (blobFiles.length === 0) {
-			console.error("❌ No coverage blobs were generated — coverage report cannot be produced");
+			const message = "❌ No coverage blobs were generated — coverage report cannot be produced";
+			if (emitTextOutput) console.error(message);
+			if (json) {
+				return {
+					exitCode: 1,
+					mode: "coverage",
+					message,
+					options: {
+						cwd,
+						testDir,
+						testPatterns,
+						testListFile,
+						workers,
+						coverageQuiet,
+						suppressFileOutput,
+						suppressPassingFiles,
+						topSummary,
+						showErrorDetails,
+						worstCoverageCount,
+						vitestArgs
+					},
+					totals: {
+						testFiles: allTestFiles.length,
+						failedFiles: coverageResults.filter((r) => r.code !== 0).length,
+						passedFiles: coverageResults.filter((r) => r.code === 0).length
+					},
+					results: {
+						all: coverageResults,
+						failed: coverageResults.filter((r) => r.code !== 0)
+					},
+					merge: {
+						blobFiles: 0,
+						exitCode: 1,
+						output: ""
+					},
+					coverageSummary: null
+				};
+			}
 			return 1;
 		}
 
-		if (!coverageQuiet) {
+		if (!coverageQuiet && !suppressFileOutput && emitTextOutput) {
 			console.log(`\n${"=".repeat(80)}`);
 			console.log(`📊 Merging ${blobFiles.length} coverage blobs into final report...`);
 			console.log("=".repeat(80));
@@ -260,14 +331,14 @@ export async function run(opts) {
 			...spawnBase,
 			maxOldSpaceMb,
 			extraCoverageArgs,
-			quietOutput: coverageQuiet
+			quietOutput: coverageQuiet || json
 		});
 
-		if (coverageQuiet) {
+		if (coverageQuiet && emitTextOutput) {
 			printMergeOutput(mergeExitCode, mergeOutput);
 		}
 
-		await printCoverageSummary(cwd, extraCoverageArgs, worstCoverageCount);
+		const coverageSummary = await printCoverageSummary(cwd, extraCoverageArgs, worstCoverageCount, { silent: json });
 
 		// Clean up blobs and temp dirs
 		await Promise.all([
@@ -276,18 +347,81 @@ export async function run(opts) {
 		]);
 
 		const coverageFailed = coverageResults.filter((r) => r.code !== 0);
-		if (coverageQuiet) printQuietCoverageFailureDetails(coverageFailed);
+		if (coverageQuiet && emitTextOutput) printQuietCoverageFailureDetails(coverageFailed);
+
+		const exitCode = coverageFailed.length > 0 ? 1 : mergeExitCode;
+		if (json) {
+			const coverageWithHeap = coverageResults.filter((r) => r.heapMb !== null);
+			return {
+				exitCode,
+				mode: "coverage",
+				options: {
+					cwd,
+					testDir,
+					testPatterns,
+					testListFile,
+					workers,
+					coverageQuiet,
+					suppressFileOutput,
+					suppressPassingFiles,
+					topSummary,
+					showErrorDetails,
+					worstCoverageCount,
+					vitestArgs
+				},
+				totals: {
+					testFiles: allTestFiles.length,
+					failedFiles: coverageFailed.length,
+					passedFiles: coverageResults.length - coverageFailed.length
+				},
+				results: {
+					all: coverageResults,
+					failed: coverageFailed
+				},
+				merge: {
+					blobFiles: blobFiles.length,
+					exitCode: mergeExitCode,
+					output: mergeOutput
+				},
+				coverageSummary,
+				...(topSummary
+					? {
+							topMemoryUsers: [...coverageWithHeap].sort((a, b) => b.heapMb - a.heapMb).slice(0, 10),
+							topDuration: [...coverageResults].sort((a, b) => b.duration - a.duration).slice(0, 10)
+						}
+					: {})
+			};
+		}
 
-		return coverageFailed.length > 0 ? 1 : mergeExitCode;
+		return exitCode;
 	}
 
 	// ─── STANDARD (NON-COVERAGE) MODE ────────────────────────────────────────────
 	const testFiles = await discoverVitestFiles({ cwd, testDir, testPatterns, testListFile, testFilePattern, earlyRunPatterns });
 
 	if (testFiles.length === 0) {
-		console.log(
-			testPatterns.length > 0 ? `❌ No Vitest test files found matching: ${testPatterns.join(", ")}` : "❌ No Vitest test files found"
-		);
+		const noTestsMessage =
+			testPatterns.length > 0 ? `❌ No Vitest test files found matching: ${testPatterns.join(", ")}` : "❌ No Vitest test files found";
+		if (emitTextOutput) console.log(noTestsMessage);
+		if (json) {
+			return {
+				exitCode: 1,
+				mode: "standard",
+				message: noTestsMessage,
+				options: {
+					cwd,
+					testDir,
+					testPatterns,
+					testListFile,
+					workers,
+					coverageQuiet,
+					suppressFileOutput,
+					suppressPassingFiles,
+					topSummary,
+					vitestArgs
+				}
+			};
+		}
 		return 1;
 	}
 
@@ -297,15 +431,17 @@ export async function run(opts) {
 	const scriptStartTime = Date.now();
 	const scriptStartTimeFormatted = new Date().toLocaleTimeString("en-US", { hour12: false });
 
-	if (testPatterns.length > 0) {
+	if (emitTextOutput && !suppressFileOutput && testPatterns.length > 0) {
 		console.log(`\n🧪 Running ${testFiles.length} test files matching: ${testPatterns.join(", ")}`);
-	} else {
+	} else if (emitTextOutput && !suppressFileOutput) {
 		console.log(`\n🧪 Running ${testFiles.length} test files (${soloFiles.length} solo first, then parallel)`);
 	}
-	console.log(`⚙️  Workers: ${workers}`);
-	if (maxOldSpaceMb) console.log(`🧠 Heap limit: ${maxOldSpaceMb} MB`);
-	if (vitestArgs.length > 0) console.log(`🔧 Vitest args: ${vitestArgs.join(" ")}`);
-	console.log("");
+	if (emitTextOutput && !suppressFileOutput) {
+		console.log(`⚙️  Workers: ${workers}`);
+		if (maxOldSpaceMb) console.log(`🧠 Heap limit: ${maxOldSpaceMb} MB`);
+		if (vitestArgs.length > 0) console.log(`🔧 Vitest args: ${vitestArgs.join(" ")}`);
+		console.log("");
+	}
 
 	const results = [...(_testResultsOverride ?? [])];
 
@@ -315,22 +451,27 @@ export async function run(opts) {
 	 * @returns {Promise<import('./core/spawn.mjs').SingleFileResult>}
 	 */
 	const runTestFile = async (filePath) => {
-		console.log(`\n${"=".repeat(80)}`);
-		console.log(`▶️  ${filePath}`);
-		console.log("=".repeat(80));
+		if (!suppressFileOutput && emitTextOutput) {
+			console.log(`\n${"=".repeat(80)}`);
+			console.log(`▶️  ${filePath}`);
+			console.log("=".repeat(80));
+		}
 
 		const result = await runSingleFile(filePath, {
 			...spawnBase,
 			maxOldSpaceMb: getHeapForFile(filePath, maxOldSpaceMb, perFileHeapOverrides),
-			vitestArgs
+			vitestArgs,
+			streamOutput: !suppressFileOutput && !json
 		});
 
-		const durationSec = (result.duration / 1000).toFixed(2);
-		if (result.code === 0) {
-			const heapInfo = result.heapMb ? ` | ${result.heapMb} MB heap` : "";
-			console.log(`\n✅ PASSED (${durationSec}s${heapInfo})\n`);
-		} else {
-			console.log(`\n❌ FAILED (exit code ${result.code}, ${durationSec}s)\n`);
+		if (!suppressFileOutput && emitTextOutput) {
+			const durationSec = (result.duration / 1000).toFixed(2);
+			if (result.code === 0) {
+				const heapInfo = result.heapMb ? ` | ${result.heapMb} MB heap` : "";
+				console.log(`\n✅ PASSED (${durationSec}s${heapInfo})\n`);
+			} else {
+				console.log(`\n❌ FAILED (exit code ${result.code}, ${durationSec}s)\n`);
+			}
 		}
 
 		return result;
@@ -340,7 +481,7 @@ export async function run(opts) {
 		// Phase 1: solo files
 		for (const filePath of soloFiles) {
 			const result = await runTestFile(filePath).catch((err) => {
-				console.error(`Error running ${filePath}:`, err);
+				if (emitTextOutput) console.error(`Error running ${filePath}:`, err);
 				return null;
 			});
 			if (result) results.push(result);
@@ -355,7 +496,9 @@ export async function run(opts) {
 				const filePath = parallelFiles[index++];
 				const promise = runTestFile(filePath)
 					.then((result) => results.push(result))
-					.catch((err) => console.error(`Error running ${filePath}:`, err))
+					.catch((err) => {
+						if (emitTextOutput) console.error(`Error running ${filePath}:`, err);
+					})
 					.finally(() => activePromises.delete(promise));
 				activePromises.add(promise);
 			}
@@ -373,12 +516,69 @@ export async function run(opts) {
 	const totalDuration = results.reduce((s, r) => s + r.duration, 0);
 	const failedFiles = results.filter((r) => r.code !== 0);
 	const passedFiles = results.filter((r) => r.code === 0);
+	const exitCode = failedFiles.length > 0 ? 1 : 0;
+	const scriptMemory = process.memoryUsage();
+	const scriptHeapMb = Math.round(scriptMemory.heapUsed / 1024 / 1024);
+	const scriptRssMb = Math.round(scriptMemory.rss / 1024 / 1024);
+	const withHeap = results.filter((r) => r.heapMb !== null);
+	const actualDurationSec = ((Date.now() - scriptStartTime) / 1000).toFixed(2);
+	const testsDurationSec = (totalDuration / 1000).toFixed(2);
+
+	if (json) {
+		return {
+			exitCode,
+			mode: "standard",
+			options: {
+				cwd,
+				testDir,
+				testPatterns,
+				testListFile,
+				workers,
+				coverageQuiet,
+				suppressFileOutput,
+				suppressPassingFiles,
+				topSummary,
+				showErrorDetails,
+				worstCoverageCount,
+				vitestArgs
+			},
+			totals: {
+				testFilesPass: totalTestFilesPass,
+				testFilesFail: totalTestFilesFail,
+				testsPass: totalTestsPass,
+				testsFail: totalTestsFail,
+				testsSkip: totalTestsSkip,
+				totalTests: totalTestsPass + totalTestsFail + totalTestsSkip
+			},
+			timing: {
+				startAt: scriptStartTimeFormatted,
+				wallClockSeconds: Number(actualDurationSec),
+				testsSeconds: Number(testsDurationSec)
+			},
+			heap: {
+				scriptHeapMb,
+				scriptRssMb,
+				maxHeapMb: withHeap.length > 0 ? Math.max(...withHeap.map((r) => r.heapMb)) : null,
+				avgHeapMb: withHeap.length > 0 ? Number((withHeap.reduce((sum, r) => sum + r.heapMb, 0) / withHeap.length).toFixed(0)) : null
+			},
+			results: {
+				all: results,
+				passed: passedFiles,
+				failed: failedFiles
+			},
+			...(topSummary
+				? {
+						topMemoryUsers: [...withHeap].sort((a, b) => b.heapMb - a.heapMb).slice(0, 10),
+						topDuration: [...results].sort((a, b) => b.duration - a.duration).slice(0, 10)
+					}
+				: {})
+		};
+	}
 
 	console.log("\n" + "=".repeat(80));
 
 	// Top memory users
-	const withHeap = results.filter((r) => r.heapMb !== null);
-	if (withHeap.length > 0) {
+	if (topSummary && withHeap.length > 0) {
 		console.log("\n" + chalk.bold("🧠 TOP MEMORY USERS"));
 		console.log("-".repeat(80));
 		[...withHeap]
@@ -390,7 +590,7 @@ export async function run(opts) {
 	}
 
 	// Top duration
-	if (results.length > 0) {
+	if (topSummary && results.length > 0) {
 		console.log("\n" + chalk.bold("⏱️  TOP DURATION"));
 		console.log("-".repeat(80));
 		[...results]
@@ -403,7 +603,7 @@ export async function run(opts) {
 	}
 
 	// Passed files
-	if (passedFiles.length > 0) {
+	if (passedFiles.length > 0 && !suppressPassingFiles) {
 		console.log("\n" + "=".repeat(80));
 		console.log(chalk.bold.green("✓ PASSED TEST FILES"));
 		console.log("=".repeat(80));
@@ -468,13 +668,8 @@ export async function run(opts) {
 	console.log(`      ${chalk.bold("Tests")}  ${testsParts.join(` ${chalk.dim("|")} `)} ${chalk.dim(`(${totalTests})`)}`);
 	console.log(`   ${chalk.bold("Start at")}  ${scriptStartTimeFormatted}`);
 
-	const actualDurationSec = ((Date.now() - scriptStartTime) / 1000).toFixed(2);
-	const testsDurationSec = (totalDuration / 1000).toFixed(2);
 	console.log(`   ${chalk.bold("Duration")}  ${actualDurationSec}s ${chalk.dim(`(tests ${testsDurationSec}s)`)}`);
 
-	const scriptMemory = process.memoryUsage();
-	const scriptHeapMb = Math.round(scriptMemory.heapUsed / 1024 / 1024);
-	const scriptRssMb = Math.round(scriptMemory.rss / 1024 / 1024);
 	if (withHeap.length > 0) {
 		const maxHeap = Math.max(...withHeap.map((r) => r.heapMb));
 		const avgHeap = (withHeap.reduce((s, r) => s + r.heapMb, 0) / withHeap.length).toFixed(0);
@@ -483,9 +678,7 @@ export async function run(opts) {
 		console.log(`       ${chalk.bold("Heap")}  script ${scriptHeapMb} MB (RSS ${scriptRssMb} MB)`);
 	}
 
-	if (failedFiles.length > 0) {
-		return 1;
-	}
+	if (failedFiles.length > 0) return 1;
 
 	console.log(`\n✅ All ${passedFiles.length} test files passed\n`);
 	return 0;

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

@@ -29,6 +29,22 @@ export type ParsedArgs = {
      * - Path for the coverage run log (`--log-file`); defaults to `coverage/coverage-run.log`.
      */
     logFile: string | undefined;
+    /**
+     * - Suppress per-file runner output blocks (`--suppress-file-output`).
+     */
+    suppressFileOutput: boolean;
+    /**
+     * - Suppress the passed-files section in the final summary (`--suppress-passing-files`).
+     */
+    suppressPassingFiles: boolean;
+    /**
+     * - Show top-summary sections for memory and duration (`true` by default, disabled by `--no-top-summary`).
+     */
+    topSummary: boolean;
+    /**
+     * - Emit a JSON run report instead of text output (`--json`).
+     */
+    json: boolean;
     /**
      * - Whether `--help` / `-h` was passed.
      */

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

@@ -42,6 +42,29 @@ export function computeSummaryFromFinal(finalData: Record<string, object>): {
  * @param {string} cwd - Project root (used to make absolute file paths relative).
  * @param {string[]} extraCoverageArgs - Passthrough `--coverage.*` args (checked for `reportsDirectory`).
  * @param {number} [worstCount=10] - Number of worst-coverage files to show (0 = skip table).
- * @returns {Promise<void>}
+ * @param {{silent?: boolean}} [options] - Output controls.
+ * @returns {Promise<{
+ *  coverageDir: string,
+ *  total: object,
+ *  worstFiles: Array<{file: string, lines: number, stmts: number, fns: number, branches: number}>,
+ *  worstFilesShown: number,
+ *  worstFilesTotal: number,
+ *  summary: object
+ * }|null>}
  */
-export function printCoverageSummary(cwd: string, extraCoverageArgs: string[], worstCount?: number): Promise<void>;
+export function printCoverageSummary(cwd: string, extraCoverageArgs: string[], worstCount?: number, options?: {
+    silent?: boolean;
+}): Promise<{
+    coverageDir: string;
+    total: object;
+    worstFiles: Array<{
+        file: string;
+        lines: number;
+        stmts: number;
+        fns: number;
+        branches: number;
+    }>;
+    worstFilesShown: number;
+    worstFilesTotal: number;
+    summary: object;
+} | null>;

package/types/src/runner.d.mts

@@ -3,9 +3,9 @@
  * pool for the non-solo phase) and return an exit code.
  *
  * @param {RunOptions} opts
- * @returns {Promise<number>} `0` on full pass, `1` on any failure.
+ * @returns {Promise<number|object>} `0`/`1` by default; JSON report object when `opts.json` is true.
  */
-export function run(opts: RunOptions): Promise<number>;
+export function run(opts: RunOptions): Promise<number | object>;
 export { formatDuration } from "./utils/duration.mjs";
 export { buildNodeOptions } from "./utils/env.mjs";
 export type PerFileHeapOverride = {
@@ -55,6 +55,22 @@ export type RunOptions = {
      * - Suppress per-file output; show only progress bar + summaries.
      */
     coverageQuiet?: boolean;
+    /**
+     * - Suppress per-file runner output blocks in all modes.
+     */
+    suppressFileOutput?: boolean;
+    /**
+     * - Hide passed-file rows in the final summary.
+     */
+    suppressPassingFiles?: boolean;
+    /**
+     * - Show top memory and duration summary sections.
+     */
+    topSummary?: boolean;
+    /**
+     * - Return a JSON run report instead of printing text output.
+     */
+    json?: boolean;
     /**
      * - Maximum number of parallel worker slots.
      */