tryscript 0.1.5 → 0.1.7

package/dist/bin.mjs

@@ -1,18 +1,18 @@
 #!/usr/bin/env node
 
 
-import { a as createExecutionContext, c as parseTestFile, d as mergeConfig, f as resolveCoverageConfig, i as cleanupExecutionContext, n as matchOutput, o as runAfterHook, s as runBlock, t as VERSION, u as loadConfig } from "./src-CC3xA1cp.mjs";
+import { b as resolveCoverageConfig, f as cleanupExecutionContext, g as parseTestFile, h as runBlock, m as runAfterHook, p as createExecutionContext, r as writeCaptureLog, s as expandTestFile, t as VERSION, u as matchOutput, v as loadConfig, y as mergeConfig } from "./src-BQxIhzgF.mjs";
 import { fileURLToPath } from "node:url";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { spawn } from "node:child_process";
 import { access, mkdtemp, readFile, readdir, rm, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
+import { writeFile } from "atomically";
 import { Command } from "commander";
 import fg from "fast-glob";
 import pc from "picocolors";
 import { createPatch } from "diff";
-import { writeFile } from "atomically";
 
 //#region src/cli/lib/shared.ts
 /**
@@ -134,9 +134,10 @@ function reportSummary(summary, _options) {
 async function updateTestFile(file, results) {
 	let content = file.rawContent;
 	const changes = [];
-	const blocksWithResults = file.blocks.map((block, i) => ({
+	const resultByBlock = new Map(results.map((result) => [result.block, result]));
+	const blocksWithResults = [...file.blocks].map((block) => ({
 		block,
-		result: results[i]
+		result: resultByBlock.get(block)
 	})).reverse();
 	for (const { block, result } of blocksWithResults) {
 		if (!result) continue;
@@ -159,15 +160,248 @@ async function updateTestFile(file, results) {
 * Build an updated console block with new expected output.
 */
 function buildUpdatedBlock(block, result) {
-	const lines = ["```console", ...block.command.split("\n").map((line, i) => {
+	const fence = "`".repeat(/^(`+)/.exec(block.rawContent)?.[1]?.length ?? 3);
+	const commandLines = block.command.split("\n").map((line, i) => {
 		return i === 0 ? `$ ${line}` : `> ${line}`;
-	})];
+	});
+	const lines = [`${fence}console`, ...commandLines];
 	const trimmedOutput = result.actualOutput.trimEnd();
 	if (trimmedOutput) lines.push(trimmedOutput);
-	lines.push(`? ${result.actualExitCode}`, "```");
+	lines.push(`? ${result.actualExitCode}`, fence);
 	return lines.join("\n");
 }
 
+//#endregion
+//#region src/lib/lcov.ts
+/**
+* LCOV parsing, merging, and writing utilities.
+*
+* LCOV format reference:
+* - SF: Source file path
+* - DA:linenum,hitcount - Line data
+* - FN:linenum,funcname - Function definition
+* - FNDA:hitcount,funcname - Function hit data
+* - FNF: Functions found count
+* - FNH: Functions hit count
+* - BRF: Branches found count
+* - BRH: Branches hit count
+* - BRDA:line,block,branch,taken - Branch data
+* - LF: Lines found count
+* - LH: Lines hit count
+* - end_of_record - End of file record
+*/
+/**
+* Parse LCOV content into structured data.
+*/
+function parseLcov(content) {
+	const files = /* @__PURE__ */ new Map();
+	let currentFile = null;
+	for (const line of content.split("\n")) {
+		const trimmed = line.trim();
+		if (trimmed.startsWith("SF:")) {
+			const path = trimmed.slice(3);
+			currentFile = {
+				path,
+				lines: /* @__PURE__ */ new Map(),
+				functions: /* @__PURE__ */ new Map(),
+				branches: []
+			};
+			files.set(path, currentFile);
+		} else if (trimmed.startsWith("DA:") && currentFile) {
+			const parts = trimmed.slice(3).split(",");
+			const lineNumber = parseInt(parts[0], 10);
+			const hitCount = parseInt(parts[1], 10);
+			currentFile.lines.set(lineNumber, {
+				lineNumber,
+				hitCount
+			});
+		} else if (trimmed.startsWith("FN:") && currentFile) {
+			const parts = trimmed.slice(3).split(",");
+			const lineNumber = parseInt(parts[0], 10);
+			const name = parts.slice(1).join(",");
+			if (!currentFile.functions.has(name)) currentFile.functions.set(name, {
+				name,
+				lineNumber,
+				hitCount: 0
+			});
+			else currentFile.functions.get(name).lineNumber = lineNumber;
+		} else if (trimmed.startsWith("FNDA:") && currentFile) {
+			const parts = trimmed.slice(5).split(",");
+			const hitCount = parseInt(parts[0], 10);
+			const name = parts.slice(1).join(",");
+			if (currentFile.functions.has(name)) currentFile.functions.get(name).hitCount = hitCount;
+			else currentFile.functions.set(name, {
+				name,
+				lineNumber: 0,
+				hitCount
+			});
+		} else if (trimmed.startsWith("BRDA:") && currentFile) {
+			const parts = trimmed.slice(5).split(",");
+			currentFile.branches.push({
+				line: parseInt(parts[0], 10),
+				block: parseInt(parts[1], 10),
+				branch: parseInt(parts[2], 10),
+				taken: parts[3] === "-" ? -1 : parseInt(parts[3], 10)
+			});
+		} else if (trimmed === "end_of_record") currentFile = null;
+	}
+	return { files };
+}
+/**
+* Merge multiple LCOV data structures, taking max hit counts.
+*/
+function mergeLcov(...lcovs) {
+	const merged = /* @__PURE__ */ new Map();
+	for (const lcov of lcovs) for (const [path, file] of lcov.files) if (!merged.has(path)) merged.set(path, {
+		path,
+		lines: new Map(file.lines),
+		functions: new Map(file.functions),
+		branches: [...file.branches]
+	});
+	else {
+		const existing = merged.get(path);
+		for (const [lineNum, lineData] of file.lines) {
+			const existingLine = existing.lines.get(lineNum);
+			if (existingLine) existingLine.hitCount = Math.max(existingLine.hitCount, lineData.hitCount);
+			else existing.lines.set(lineNum, { ...lineData });
+		}
+		for (const [name, funcData] of file.functions) {
+			const existingFunc = existing.functions.get(name);
+			if (existingFunc) existingFunc.hitCount = Math.max(existingFunc.hitCount, funcData.hitCount);
+			else existing.functions.set(name, { ...funcData });
+		}
+		for (const branch of file.branches) {
+			const existingBranch = existing.branches.find((b) => b.line === branch.line && b.block === branch.block && b.branch === branch.branch);
+			if (existingBranch) {
+				if (branch.taken >= 0) existingBranch.taken = existingBranch.taken >= 0 ? Math.max(existingBranch.taken, branch.taken) : branch.taken;
+			} else existing.branches.push({ ...branch });
+		}
+	}
+	return { files: merged };
+}
+/**
+* Convert LCOV data back to LCOV format string.
+*/
+function formatLcov(lcov) {
+	const lines = [];
+	for (const file of lcov.files.values()) {
+		lines.push(`SF:${file.path}`);
+		const sortedFunctions = [...file.functions.values()].sort((a, b) => a.lineNumber - b.lineNumber);
+		for (const func of sortedFunctions) lines.push(`FN:${func.lineNumber},${func.name}`);
+		for (const func of sortedFunctions) lines.push(`FNDA:${func.hitCount},${func.name}`);
+		const fnf = file.functions.size;
+		const fnh = [...file.functions.values()].filter((f) => f.hitCount > 0).length;
+		lines.push(`FNF:${fnf}`);
+		lines.push(`FNH:${fnh}`);
+		for (const branch of file.branches) {
+			const taken = branch.taken < 0 ? "-" : branch.taken.toString();
+			lines.push(`BRDA:${branch.line},${branch.block},${branch.branch},${taken}`);
+		}
+		const brf = file.branches.length;
+		const brh = file.branches.filter((b) => b.taken > 0).length;
+		lines.push(`BRF:${brf}`);
+		lines.push(`BRH:${brh}`);
+		const sortedLines = [...file.lines.values()].sort((a, b) => a.lineNumber - b.lineNumber);
+		for (const line of sortedLines) lines.push(`DA:${line.lineNumber},${line.hitCount}`);
+		const lf = file.lines.size;
+		const lh = [...file.lines.values()].filter((l) => l.hitCount > 0).length;
+		lines.push(`LF:${lf}`);
+		lines.push(`LH:${lh}`);
+		lines.push("end_of_record");
+	}
+	return lines.join("\n") + "\n";
+}
+/**
+* Convert LCOV data to JSON summary format (compatible with istanbul/vitest).
+*/
+function lcovToJsonSummary(lcov) {
+	const withPct = (total, covered) => ({
+		total,
+		covered,
+		skipped: 0,
+		pct: total > 0 ? parseFloat((covered / total * 100).toFixed(2)) : 100
+	});
+	const totals = {
+		lines: {
+			total: 0,
+			covered: 0
+		},
+		functions: {
+			total: 0,
+			covered: 0
+		},
+		branches: {
+			total: 0,
+			covered: 0
+		}
+	};
+	const summary = { total: {
+		lines: withPct(0, 0),
+		statements: withPct(0, 0),
+		functions: withPct(0, 0),
+		branches: withPct(0, 0),
+		branchesTrue: {
+			total: 0,
+			covered: 0,
+			skipped: 0,
+			pct: 100
+		}
+	} };
+	for (const file of lcov.files.values()) {
+		const linesTotal = file.lines.size;
+		const linesCovered = [...file.lines.values()].filter((l) => l.hitCount > 0).length;
+		const funcsTotal = file.functions.size;
+		const funcsCovered = [...file.functions.values()].filter((f) => f.hitCount > 0).length;
+		const branchesTotal = file.branches.length;
+		const branchesCovered = file.branches.filter((b) => b.taken > 0).length;
+		summary[file.path] = {
+			lines: withPct(linesTotal, linesCovered),
+			statements: withPct(linesTotal, linesCovered),
+			functions: withPct(funcsTotal, funcsCovered),
+			branches: withPct(branchesTotal, branchesCovered)
+		};
+		totals.lines.total += linesTotal;
+		totals.lines.covered += linesCovered;
+		totals.functions.total += funcsTotal;
+		totals.functions.covered += funcsCovered;
+		totals.branches.total += branchesTotal;
+		totals.branches.covered += branchesCovered;
+	}
+	summary.total = {
+		lines: withPct(totals.lines.total, totals.lines.covered),
+		statements: withPct(totals.lines.total, totals.lines.covered),
+		functions: withPct(totals.functions.total, totals.functions.covered),
+		branches: withPct(totals.branches.total, totals.branches.covered),
+		branchesTrue: {
+			total: 0,
+			covered: 0,
+			skipped: 0,
+			pct: 100
+		}
+	};
+	return summary;
+}
+/**
+* Read and parse an LCOV file.
+*/
+function readLcovFile(path) {
+	return parseLcov(readFileSync(path, "utf8"));
+}
+/**
+* Write LCOV data to a file.
+*/
+function writeLcovFile(path, lcov) {
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, formatLcov(lcov));
+}
+/**
+* Write JSON summary to a file.
+*/
+function writeJsonSummary(path, summary) {
+	mkdirSync(dirname(path), { recursive: true });
+	writeFileSync(path, JSON.stringify(summary, null, 2));
+}
+
 //#endregion
 //#region src/lib/coverage.ts
 /**
@@ -273,6 +507,33 @@ async function cleanupCoverageContext(ctx) {
 		});
 	} catch {}
 }
+/**
+* Merge external LCOV file with generated coverage.
+* Reads the generated lcov.info, merges with external LCOV, and writes back.
+* Also generates coverage-summary.json for badge generation.
+*
+* @returns Object with merged coverage percentages, or null if merge failed
+*/
+function mergeExternalCoverage(reportsDir, externalLcovPath) {
+	const generatedLcovPath = join(reportsDir, "lcov.info");
+	if (!existsSync(externalLcovPath)) {
+		console.error(`External LCOV file not found: ${externalLcovPath}`);
+		return null;
+	}
+	if (!existsSync(generatedLcovPath)) {
+		console.error(`Generated LCOV file not found: ${generatedLcovPath}`);
+		console.error("Make sure \"lcov\" is included in reporters");
+		return null;
+	}
+	const mergedLcov = mergeLcov(readLcovFile(externalLcovPath), readLcovFile(generatedLcovPath));
+	writeLcovFile(generatedLcovPath, mergedLcov);
+	const summary = lcovToJsonSummary(mergedLcov);
+	writeJsonSummary(join(reportsDir, "coverage-summary.json"), summary);
+	return {
+		lines: summary.total.lines.pct,
+		functions: summary.total.functions.pct
+	};
+}
 
 //#endregion
 //#region src/cli/commands/run.ts
@@ -280,10 +541,32 @@ async function cleanupCoverageContext(ctx) {
 * Register the run command.
 */
 function registerRunCommand(program) {
-	program.command("run").description("Run golden tests").argument("[files...]", "Test files to run (default: **/*.tryscript.md)").option("--update", "Update golden files with actual output").option("--diff", "Show diff on failure (default: true)").option("--no-diff", "Hide diff on failure").option("--fail-fast", "Stop on first failure").option("--filter <pattern>", "Filter tests by name pattern").option("--verbose", "Show detailed output including passing test output").option("--quiet", "Suppress non-essential output (only show failures)").option("--coverage", "Enable code coverage collection (requires c8)").option("--coverage-dir <dir>", "Coverage output directory (default: coverage-tryscript)").option("--coverage-reporter <reporter...>", "Coverage reporters (default: text, html). Can be specified multiple times.").option("--coverage-exclude <pattern...>", "Patterns to exclude from coverage (c8 --exclude). Can be specified multiple times.").option("--coverage-exclude-node-modules", "Exclude node_modules from coverage (c8 --exclude-node-modules, default: true)").option("--no-coverage-exclude-node-modules", "Include node_modules in coverage (c8 --no-exclude-node-modules)").option("--coverage-exclude-after-remap", "Apply exclude logic after sourcemap remapping (c8 --exclude-after-remap)").option("--coverage-skip-full", "Hide files with 100% coverage (c8 --skip-full)").option("--coverage-allow-external", "Allow files from outside cwd (c8 --allowExternal)").option("--coverage-monocart", "Use monocart for accurate line counts, better for merging with vitest (c8 --experimental-monocart)").action(runCommand$1);
+	program.command("run").description("Run golden tests").argument("[files...]", "Test files to run (default: **/*.tryscript.md)").option("--update", "Update golden files with actual output").option("--diff", "Show diff on failure (default: true)").option("--no-diff", "Hide diff on failure").option("--fail-fast", "Stop on first failure").option("--filter <pattern>", "Filter tests by name pattern").option("--verbose", "Show detailed output including passing test output").option("--quiet", "Suppress non-essential output (only show failures)").option("--expand", "Expand unknown wildcards (??? and [??]) with actual output").option("--expand-generic", "Expand unknown and generic wildcards with actual output").option("--expand-all", "Expand all wildcards (including named patterns) with actual output").option("--capture-log <path>", "Write wildcard capture log to YAML file").option("--coverage", "Enable code coverage collection (requires c8)").option("--coverage-dir <dir>", "Coverage output directory (default: coverage-tryscript)").option("--coverage-reporter <reporter...>", "Coverage reporters (default: text, html). Can be specified multiple times.").option("--coverage-exclude <pattern...>", "Patterns to exclude from coverage (c8 --exclude). Can be specified multiple times.").option("--coverage-exclude-node-modules", "Exclude node_modules from coverage (c8 --exclude-node-modules, default: true)").option("--no-coverage-exclude-node-modules", "Include node_modules in coverage (c8 --no-exclude-node-modules)").option("--coverage-exclude-after-remap", "Apply exclude logic after sourcemap remapping (c8 --exclude-after-remap)").option("--coverage-skip-full", "Hide files with 100% coverage (c8 --skip-full)").option("--coverage-allow-external", "Allow files from outside cwd (c8 --allowExternal)").option("--coverage-monocart", "Use monocart for accurate line counts, better for merging with vitest (c8 --experimental-monocart)").option("--merge-lcov <path>", "Merge coverage from an existing LCOV file (e.g., from vitest --coverage)").action(runCommand$1);
+}
+/**
+* Count unknown wildcard tokens (`???` and `[??]`) in expected output.
+*/
+function countUnknownWildcards(expectedOutput) {
+	return (expectedOutput.match(/\[\?\?]/g) ?? []).length + (expectedOutput.match(/\?\?\?\n/g) ?? []).length;
 }
 async function runCommand$1(files, options) {
 	const startTime = Date.now();
+	if ([
+		options.expand,
+		options.expandGeneric,
+		options.expandAll
+	].filter(Boolean).length > 1) {
+		logError("--expand, --expand-generic, and --expand-all are mutually exclusive");
+		process.exit(1);
+	}
+	let expandLevel;
+	if (options.expand) expandLevel = "unknown";
+	else if (options.expandGeneric) expandLevel = "generic";
+	else if (options.expandAll) expandLevel = "all";
+	if (expandLevel && options.update) {
+		logError("--expand* flags and --update are mutually exclusive");
+		process.exit(1);
+	}
 	const opts = {
 		diff: options.diff !== false,
 		verbose: options.verbose ?? false,
@@ -309,20 +592,32 @@ async function runCommand$1(files, options) {
 			logError("Coverage requires c8. Install with: npm install -D c8");
 			process.exit(1);
 		}
+		let reporters = options.coverageReporter ?? globalConfig.coverage?.reporters;
+		if (options.mergeLcov) {
+			if (!reporters) reporters = [
+				"text",
+				"html",
+				"lcov"
+			];
+			else if (!reporters.includes("lcov")) reporters = [...reporters, "lcov"];
+		}
 		coverageCtx = await createCoverageContext({
 			...globalConfig.coverage,
 			reportsDir: options.coverageDir ?? globalConfig.coverage?.reportsDir,
-			reporters: options.coverageReporter ?? globalConfig.coverage?.reporters,
+			reporters,
 			exclude: options.coverageExclude ?? globalConfig.coverage?.exclude,
 			excludeNodeModules: options.coverageExcludeNodeModules ?? globalConfig.coverage?.excludeNodeModules,
 			excludeAfterRemap: options.coverageExcludeAfterRemap ?? globalConfig.coverage?.excludeAfterRemap,
 			skipFull: options.coverageSkipFull ?? globalConfig.coverage?.skipFull,
 			allowExternal: options.coverageAllowExternal ?? globalConfig.coverage?.allowExternal,
-			monocart: options.coverageMonocart ?? globalConfig.coverage?.monocart
+			monocart: options.coverageMonocart ?? globalConfig.coverage?.monocart,
+			mergeLcov: options.mergeLcov ?? globalConfig.coverage?.mergeLcov
 		});
 		coverageEnv = getCoverageEnv(coverageCtx);
 	}
 	const fileResults = [];
+	const fileContexts = /* @__PURE__ */ new Map();
+	const filePatterns = /* @__PURE__ */ new Map();
 	let shouldStop = false;
 	for (const filePath of testFiles) {
 		if (shouldStop) break;
@@ -338,6 +633,7 @@ async function runCommand$1(files, options) {
 		if (blocksToRun.length === 0) continue;
 		const ctx = await createExecutionContext(config, filePath, coverageEnv);
 		const results = [];
+		let fileContext;
 		try {
 			for (const block of blocksToRun) {
 				const result = await runBlock(block, ctx);
@@ -364,6 +660,12 @@ async function runCommand$1(files, options) {
 				}
 			}
 			await runAfterHook(ctx);
+			fileContext = {
+				root: ctx.testDir,
+				cwd: ctx.cwd
+			};
+			fileContexts.set(filePath, fileContext);
+			filePatterns.set(filePath, config.patterns ?? {});
 		} finally {
 			await cleanupExecutionContext(ctx);
 		}
@@ -379,7 +681,14 @@ async function runCommand$1(files, options) {
 			const { updated, changes } = await updateTestFile(testFile, results);
 			if (updated) console.error(colors.warn(`  ${status.update} Updated: ${changes.join(", ")}`));
 		}
+		if (expandLevel && fileContext) {
+			const { expanded, expandedCount, changes } = await expandTestFile(testFile, results, expandLevel, fileContext, config.patterns ?? {});
+			if (expanded) console.error(colors.warn(`  ${status.update} Expanded ${expandedCount} wildcard(s): ${changes.join(", ")}`));
+		}
 	}
+	let totalUnknownWildcards = 0;
+	for (const fr of fileResults) for (const block of fr.file.blocks) totalUnknownWildcards += countUnknownWildcards(block.expectedOutput);
+	if (totalUnknownWildcards > 0) logWarn(`${totalUnknownWildcards} unknown wildcard(s) found (??? or [??]). These are temporary and should be expanded. Use --expand to fill them in.`);
 	const summary = {
 		files: fileResults,
 		totalPassed: fileResults.reduce((sum, f) => sum + f.results.filter((r) => r.passed).length, 0),
@@ -388,11 +697,25 @@ async function runCommand$1(files, options) {
 		duration: Date.now() - startTime
 	};
 	reportSummary(summary, opts);
+	if (options.captureLog) try {
+		await writeCaptureLog(options.captureLog, fileResults, (file) => fileContexts.get(file.path) ?? {
+			root: process.cwd(),
+			cwd: process.cwd()
+		}, (file) => filePatterns.get(file.path) ?? {});
+		console.error(colors.info(`Capture log written to ${options.captureLog}`));
+	} catch (error) {
+		logError(`Failed to write capture log: ${error instanceof Error ? error.message : String(error)}`);
+	}
 	if (coverageCtx) {
 		console.error("\nGenerating coverage report...");
 		try {
 			await generateCoverageReport(coverageCtx);
 			console.error(colors.success(`Coverage report written to ${coverageCtx.options.reportsDir}/`));
+			if (coverageCtx.options.mergeLcov) {
+				console.error(`Merging with external coverage: ${coverageCtx.options.mergeLcov}`);
+				const merged = mergeExternalCoverage(coverageCtx.options.reportsDir, coverageCtx.options.mergeLcov);
+				if (merged) console.error(colors.success(`Merged coverage: ${merged.lines}% lines, ${merged.functions}% functions`));
+			}
 		} catch (error) {
 			logError(`Failed to generate coverage report: ${error instanceof Error ? error.message : String(error)}`);
 		} finally {
@@ -408,7 +731,7 @@ async function runCommand$1(files, options) {
 * Register the coverage command.
 */
 function registerCoverageCommand(program) {
-	program.command("coverage").description("Run commands with merged V8 coverage").argument("<commands...>", "Commands to run (each will inherit coverage environment)").option("--reports-dir <dir>", "Coverage output directory (default: coverage)").option("--reporters <reporters>", "Comma-separated coverage reporters (default: text,json,json-summary,lcov,html)").option("--include <patterns>", "Comma-separated patterns to include in coverage").option("--exclude <patterns>", "Comma-separated patterns to exclude from coverage").option("--exclude-node-modules", "Exclude node_modules from coverage (default: true)", true).option("--no-exclude-node-modules", "Include node_modules in coverage").option("--exclude-after-remap", "Apply exclude logic after sourcemap remapping").option("--skip-full", "Hide files with 100% coverage").option("--allow-external", "Allow files from outside cwd").option("--monocart", "Use monocart for accurate line counts (recommended for merging)").option("--src <dir>", "Source directory for sourcemap remapping (default: src)").option("--verbose", "Show coverage summary after each command for debugging").action(coverageCommand);
+	program.command("coverage").description("Run commands with merged V8 coverage").argument("<commands...>", "Commands to run (each will inherit coverage environment)").option("--reports-dir <dir>", "Coverage output directory (default: coverage)").option("--reporters <reporters>", "Comma-separated coverage reporters (default: text,json,json-summary,lcov,html)").option("--include <patterns>", "Comma-separated patterns to include in coverage").option("--exclude <patterns>", "Comma-separated patterns to exclude from coverage").option("--exclude-node-modules", "Exclude node_modules from coverage (default: true)", true).option("--no-exclude-node-modules", "Include node_modules in coverage").option("--exclude-after-remap", "Apply exclude logic after sourcemap remapping").option("--skip-full", "Hide files with 100% coverage").option("--allow-external", "Allow files from outside cwd").option("--monocart", "Use monocart for accurate line counts (recommended for merging)").option("--src <dir>", "Source directory for sourcemap remapping (default: src)").option("--verbose", "Show coverage summary after each command for debugging").option("--merge-lcov <path>", "Merge coverage from an existing LCOV file (e.g., from vitest --coverage)").action(coverageCommand);
 }
 /**
 * Run a command with inherited coverage environment.
@@ -604,12 +927,32 @@ async function coverageCommand(commands, options) {
 			if (parsedOptions.verbose && stats.fileCount > 0) await generateTextReport(coverageTemp, parsedOptions, command);
 			previousFileCount = stats.fileCount;
 		}
-		console.error(colors.info("\n=== Generating merged coverage report ==="));
+		console.error(colors.info("\n=== Generating coverage report ==="));
 		if (!await generateReport(coverageTemp, parsedOptions)) {
 			logError("Failed to generate coverage report");
 			process.exit(1);
 		}
-		console.error(colors.success(`\nCoverage report written to ${parsedOptions.reportsDir ?? "coverage"}/`));
+		const reportsDir = parsedOptions.reportsDir ?? "coverage";
+		if (parsedOptions.mergeLcov) {
+			const externalLcovPath = parsedOptions.mergeLcov;
+			const generatedLcovPath = join(reportsDir, "lcov.info");
+			if (!existsSync(externalLcovPath)) {
+				logError(`External LCOV file not found: ${externalLcovPath}`);
+				process.exit(1);
+			}
+			if (!existsSync(generatedLcovPath)) {
+				logError(`Generated LCOV file not found: ${generatedLcovPath}`);
+				logError("Make sure \"lcov\" is included in reporters");
+				process.exit(1);
+			}
+			console.error(colors.info(`\nMerging with external coverage: ${externalLcovPath}`));
+			const mergedLcov = mergeLcov(readLcovFile(externalLcovPath), readLcovFile(generatedLcovPath));
+			writeLcovFile(generatedLcovPath, mergedLcov);
+			const summary = lcovToJsonSummary(mergedLcov);
+			writeJsonSummary(join(reportsDir, "coverage-summary.json"), summary);
+			console.error(colors.success(`\nMerged coverage: ${summary.total.lines.pct}% lines, ${summary.total.functions.pct}% functions`));
+		}
+		console.error(colors.success(`\nCoverage report written to ${reportsDir}/`));
 	} finally {
 		await rm(coverageTemp, {
 			recursive: true,