tryscript 0.1.5 → 0.1.7

package/README.md

@@ -1,25 +1,43 @@
 # tryscript
 
-[![CI](https://github.com/jlevy/tryscript/actions/workflows/ci.yml/badge.svg)](https://github.com/jlevy/tryscript/actions/runs/21087258139)
-[![Coverage](https://raw.githubusercontent.com/jlevy/tryscript/main/badges/packages/tryscript/coverage-total.svg)](https://github.com/jlevy/tryscript/actions/runs/21087258139)
+[![Follow @ojoshe on X](https://img.shields.io/badge/follow_%40ojoshe-black?logo=x&logoColor=white)](https://x.com/ojoshe)
+[![CI](https://github.com/jlevy/tryscript/actions/workflows/ci.yml/badge.svg)](https://github.com/jlevy/tryscript/actions/runs/22267140455)
+[![Coverage](https://raw.githubusercontent.com/jlevy/tryscript/main/badges/packages/tryscript/coverage-total.svg)](https://github.com/jlevy/tryscript/actions/runs/22267140455)
 [![npm version](https://img.shields.io/npm/v/tryscript)](https://www.npmjs.com/package/tryscript)
-[![X Follow](https://img.shields.io/twitter/follow/ojoshe)](https://x.com/ojoshe)
 
-Golden testing for CLI applications - a TypeScript port of [trycmd](https://github.com/assert-rs/trycmd).
+**Powerful, agent-friendly testing of CLI applications via golden tests**
 
 > [!NOTE]
 > 100% of the code and specs in this repository were written by Claude Code.
 > The design and management and prompting was by me ([jlevy](https://github.com/jlevy)) supported by  the workflows, agent rules,
-> and other research docs in [Speculate](https://github.com/jlevy/speculate).
+> and other research docs in [tbd](https://github.com/jlevy/tbd).
 > 
-> You can see what you think, but I find the code quality higher than most agent-written code I've
+> I find the code quality higher than most agent-written code I've
 > seen because of the spec-driven process.
 > You can review the architecture doc and all of the specs all of the specs in [docs/project](docs/project).
 > The general research, guideline, and rules docs I use are in [docs/general](docs/general).
 
+## Why?
+
+Write CLI tests as Markdown. tryscript runs commands, captures output, and compares against expected results:
+
+- Tests are clear and maintainable for agents and humans: tests become documentation; documentation becomes tests
+- Inner state and working can be exposed for greater test coverage at no extra cost
+- Things are quick to implement or test using arbitrary shell commands
+
+This began as a TypeScript port of [trycmd](https://github.com/assert-rs/trycmd) but I (well, Claude and friends)
+have since enhanced it to be more agent-friendly and self-documenting as a CLI.
+
+For a bit more philosophy on why golden tests are so useful, you (or your friendly agent)
+should read [tbd](https://github.com/jlevy/tbd)’s guidelines doc:
+
+```bash
+npx --yes get-tbd@latest guidelines golden-testing-guidelines
+```
+
 ## What It Does
 
-Write CLI tests as Markdown. tryscript runs commands, captures output, and compares against expected results. Tests become documentation; documentation becomes tests.
+An example test:
 
 ````markdown
 ---
@@ -68,6 +86,16 @@ $ my-cli process data.json > output.txt && grep "success" output.txt
 
 The `[..]` matches any text on that line. The `...` matches zero or more lines. These "elision patterns" let tests handle dynamic output gracefully. Any shell command works - pipes, redirects, environment variables, etc.
 
+### Wildcard Categories
+
+Tryscript supports three categories of wildcards, in order of preference:
+
+1. **Named patterns** (`[HASH]`, `[VERSION]`, `[CWD]`, etc.) -- Typed dynamic values with specific meaning. Preferred when the output has a known structure.
+2. **Unknown wildcards** (`[??]`, `???`) -- Temporary placeholders for output you haven't filled in yet. Intended to be expanded with `--expand` before finalizing tests.
+3. **Generic wildcards** (`[..]`, `...`) -- Intentional omission of unpredictable or irrelevant output. Use when the exact value doesn't matter for the test.
+
+Use `--expand` to automatically fill in unknown wildcards with actual output after a successful run.
+
 ## Quick Start
 
 ```bash
@@ -90,7 +118,8 @@ npx tryscript run --update tests/
 ## Features
 
 - **Markdown format** - Tests are readable documentation
-- **Elision patterns** - Handle variable output: `[..]`, `...`, `[CWD]`, `[ROOT]`, `[EXE]`
+- **Elision patterns** - Handle variable output: `[..]`, `...`, `[??]`, `???`, `[CWD]`, `[ROOT]`, `[EXE]`
+- **Wildcard expansion** - Fill in `[??]`/`???` placeholders with actual output via `--expand`
 - **Custom patterns** - Define regex patterns for timestamps, versions, UUIDs
 - **Update mode** - Regenerate expected output with `--update`
 - **Sandbox mode** - Isolate tests in temp directories
@@ -113,6 +142,10 @@ For complete syntax reference, run `tryscript docs` or see the [reference docume
 | Option | Description |
 | --- | --- |
 | `--update` | Update test files with actual output |
+| `--expand` | Expand unknown wildcards (`???`/`[??]`) with actual output |
+| `--expand-generic` | Expand unknown + generic wildcards |
+| `--expand-all` | Expand all wildcards (including named patterns) |
+| `--capture-log <path>` | Write wildcard capture log to YAML file |
 | `--fail-fast` | Stop on first failure |
 | `--filter <regex>` | Filter tests by name |
 | `--verbose` | Show detailed output |

package/dist/bin.cjs

@@ -1,20 +1,20 @@
 #!/usr/bin/env node
 
 
-const require_src = require('./src-D-bd-j9T.cjs');
+const require_src = require('./src-BIZMxxIt.cjs');
 let node_url = require("node:url");
 let node_fs = require("node:fs");
 let node_path = require("node:path");
 let node_child_process = require("node:child_process");
 let node_fs_promises = require("node:fs/promises");
 let node_os = require("node:os");
+let atomically = require("atomically");
 let commander = require("commander");
 let fast_glob = require("fast-glob");
 fast_glob = require_src.__toESM(fast_glob);
 let picocolors = require("picocolors");
 picocolors = require_src.__toESM(picocolors);
 let diff = require("diff");
-let atomically = require("atomically");
 
 //#region src/cli/lib/shared.ts
 /**
@@ -136,9 +136,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;
@@ -161,15 +162,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((0, node_fs.readFileSync)(path, "utf8"));
+}
+/**
+* Write LCOV data to a file.
+*/
+function writeLcovFile(path, lcov) {
+	(0, node_fs.mkdirSync)((0, node_path.dirname)(path), { recursive: true });
+	(0, node_fs.writeFileSync)(path, formatLcov(lcov));
+}
+/**
+* Write JSON summary to a file.
+*/
+function writeJsonSummary(path, summary) {
+	(0, node_fs.mkdirSync)((0, node_path.dirname)(path), { recursive: true });
+	(0, node_fs.writeFileSync)(path, JSON.stringify(summary, null, 2));
+}
+
 //#endregion
 //#region src/lib/coverage.ts
 /**
@@ -275,6 +509,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 = (0, node_path.join)(reportsDir, "lcov.info");
+	if (!(0, node_fs.existsSync)(externalLcovPath)) {
+		console.error(`External LCOV file not found: ${externalLcovPath}`);
+		return null;
+	}
+	if (!(0, node_fs.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((0, node_path.join)(reportsDir, "coverage-summary.json"), summary);
+	return {
+		lines: summary.total.lines.pct,
+		functions: summary.total.functions.pct
+	};
+}
 
 //#endregion
 //#region src/cli/commands/run.ts
@@ -282,10 +543,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,
@@ -311,20 +594,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;
@@ -340,6 +635,7 @@ async function runCommand$1(files, options) {
 		if (blocksToRun.length === 0) continue;
 		const ctx = await require_src.createExecutionContext(config, filePath, coverageEnv);
 		const results = [];
+		let fileContext;
 		try {
 			for (const block of blocksToRun) {
 				const result = await require_src.runBlock(block, ctx);
@@ -366,6 +662,12 @@ async function runCommand$1(files, options) {
 				}
 			}
 			await require_src.runAfterHook(ctx);
+			fileContext = {
+				root: ctx.testDir,
+				cwd: ctx.cwd
+			};
+			fileContexts.set(filePath, fileContext);
+			filePatterns.set(filePath, config.patterns ?? {});
 		} finally {
 			await require_src.cleanupExecutionContext(ctx);
 		}
@@ -381,7 +683,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 require_src.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),
@@ -390,11 +699,25 @@ async function runCommand$1(files, options) {
 		duration: Date.now() - startTime
 	};
 	reportSummary(summary, opts);
+	if (options.captureLog) try {
+		await require_src.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 {
@@ -410,7 +733,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.
@@ -606,12 +929,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 = (0, node_path.join)(reportsDir, "lcov.info");
+			if (!(0, node_fs.existsSync)(externalLcovPath)) {
+				logError(`External LCOV file not found: ${externalLcovPath}`);
+				process.exit(1);
+			}
+			if (!(0, node_fs.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((0, node_path.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 (0, node_fs_promises.rm)(coverageTemp, {
 			recursive: true,