tryscript 0.1.1 → 0.1.3

package/README.md

@@ -1,61 +1,26 @@
 # tryscript
 
-[![CI](https://github.com/jlevy/tryscript/actions/workflows/ci.yml/badge.svg)](https://github.com/jlevy/tryscript/actions/workflows/ci.yml)
-[![Coverage](https://raw.githubusercontent.com/jlevy/tryscript/main/badges/packages/tryscript/coverage-total.svg)](https://raw.githubusercontent.com/jlevy/tryscript/main/badges/packages/tryscript/coverage-total.svg)
+[![CI](https://github.com/jlevy/tryscript/actions/workflows/ci.yml/badge.svg)](https://github.com/jlevy/tryscript/actions/runs/20774584634)
+[![Coverage](https://raw.githubusercontent.com/jlevy/tryscript/main/badges/packages/tryscript/coverage-total.svg)](https://github.com/jlevy/tryscript/actions/runs/20774584634)
 [![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).
 
+> [!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).
+> 
+> You can see what you think, but 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).
+
 ## What It Does
 
 Write CLI tests as Markdown. tryscript runs commands, captures output, and compares against expected results. Tests become documentation; documentation becomes tests.
 
-````markdown
-# Test: Basic echo
-
-```console
-$ echo "hello world"
-hello world
-? 0
-```
-
-# Test: Grep with pattern matching
-
-```console
-$ ls -la | grep ".md"
-[..]README.md
-...
-? 0
-```
-````
-
-The `[..]` matches any text on that line. The `...` matches zero or more lines. These "elision patterns" let tests handle dynamic output gracefully.
-
-## Quick Start
-
-```bash
-# Install
-pnpm add -D tryscript
-
-# Run tests
-npx tryscript run tests/
-
-# Update expected output when behavior changes
-npx tryscript run --update tests/
-```
-
-## Features
-
-- **Markdown format** - Tests are readable documentation
-- **Elision patterns** - Handle variable output: `[..]`, `...`, `[CWD]`, `[ROOT]`, `[EXE]`
-- **Custom patterns** - Define regex patterns for timestamps, versions, UUIDs
-- **Update mode** - Regenerate expected output with `--update`
-- **Sandbox mode** - Isolate tests in temp directories
-- **Code coverage** - Track coverage from subprocess execution with `--coverage`
-
-## Example Test File
-
 ````markdown
 ---
 env:
@@ -91,15 +56,54 @@ $ my-cli unknown-command 2>&1
 Error: unknown command 'unknown-command'
 ? 1
 ```
+
+# Test: Check output file contents
+
+```console
+$ my-cli process data.json > output.txt && grep "success" output.txt
+[..]success[..]
+? 0
+```
 ````
 
+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.
+
+## Quick Start
+
+```bash
+# Install
+pnpm add -D tryscript
+
+# For coverage support (optional)
+pnpm add -D c8
+
+# For accurate line counts when merging with vitest (optional)
+pnpm add -D c8 monocart-coverage-reports
+
+# Run tests
+npx tryscript run tests/
+
+# Update expected output when behavior changes
+npx tryscript run --update tests/
+```
+
+## Features
+
+- **Markdown format** - Tests are readable documentation
+- **Elision patterns** - Handle variable output: `[..]`, `...`, `[CWD]`, `[ROOT]`, `[EXE]`
+- **Custom patterns** - Define regex patterns for timestamps, versions, UUIDs
+- **Update mode** - Regenerate expected output with `--update`
+- **Sandbox mode** - Isolate tests in temp directories
+- **Code coverage** - Track coverage from subprocess execution with `--coverage` (experimental; use `--coverage-monocart` for best accuracy)
+
 ## CLI Reference
 
 ```bash
-tryscript run [files...]  # Run golden tests
-tryscript docs            # Show syntax quick reference
-tryscript readme          # Show this documentation
-tryscript --help          # Show all options
+tryscript run [files...]          # Run golden tests
+tryscript coverage <commands...>  # Run commands with merged coverage
+tryscript docs                    # Show syntax quick reference
+tryscript readme                  # Show this documentation
+tryscript --help                  # Show all options
 ```
 
 For complete syntax reference, run `tryscript docs` or see the [reference documentation](https://github.com/jlevy/tryscript/blob/main/docs/tryscript-reference.md).
@@ -113,6 +117,11 @@ For complete syntax reference, run `tryscript docs` or see the [reference docume
 | `--filter <regex>` | Filter tests by name |
 | `--verbose` | Show detailed output |
 | `--coverage` | Collect code coverage (requires c8) |
+| `--coverage-monocart` | Use monocart for accurate line counts (requires monocart-coverage-reports) |
+| `--coverage-exclude-node-modules` | Exclude node_modules from coverage (default: true) |
+| `--coverage-exclude <pattern>` | Exclude patterns from coverage |
+
+> **Note**: Coverage features are experimental. See the [reference documentation](packages/tryscript/docs/tryscript-reference.md#code-coverage) for details on merged coverage, monocart integration, and sourcemap requirements.
 
 ## Development
 

package/dist/bin.cjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 
 
-const require_src = require('./src-CxUUK92Q.cjs');
+const require_src = require('./src-rTwoOhL4.cjs');
 let node_url = require("node:url");
 let node_fs = require("node:fs");
 let node_path = require("node:path");
@@ -23,10 +23,8 @@ let atomically = require("atomically");
 const colors = {
 	success: (s) => picocolors.default.green(s),
 	error: (s) => picocolors.default.red(s),
-	info: (s) => picocolors.default.cyan(s),
 	warn: (s) => picocolors.default.yellow(s),
-	muted: (s) => picocolors.default.gray(s),
-	bold: (s) => picocolors.default.bold(s)
+	info: (s) => picocolors.default.cyan(s)
 };
 /**
 * Status indicators with emoji.
@@ -183,7 +181,7 @@ function buildUpdatedBlock(block, result) {
 * Find the c8 executable path.
 * Checks local node_modules/.bin first, then falls back to npx.
 */
-function findC8Path() {
+function findC8Path$1() {
 	const localPaths = [(0, node_path.resolve)(process.cwd(), "node_modules", ".bin", "c8"), (0, node_path.resolve)(process.cwd(), "..", "..", "node_modules", ".bin", "c8")];
 	for (const localPath of localPaths) if ((0, node_fs.existsSync)(localPath)) return localPath;
 	return "npx c8";
@@ -192,18 +190,18 @@ function findC8Path() {
 * Check if c8 is available in the current environment.
 */
 async function isC8Available() {
-	const c8Path = findC8Path();
-	return new Promise((resolve$1) => {
+	const c8Path = findC8Path$1();
+	return new Promise((resolve$2) => {
 		const isNpx = c8Path === "npx c8";
 		const proc = (0, node_child_process.spawn)(isNpx ? "npx" : c8Path, isNpx ? ["c8", "--version"] : ["--version"], {
 			shell: false,
 			stdio: "ignore"
 		});
 		proc.on("close", (code) => {
-			resolve$1(code === 0);
+			resolve$2(code === 0);
 		});
 		proc.on("error", () => {
-			resolve$1(false);
+			resolve$2(false);
 		});
 	});
 }
@@ -229,7 +227,7 @@ function getCoverageEnv(ctx) {
 */
 async function generateCoverageReport(ctx) {
 	const { options, tempDir } = ctx;
-	const c8Path = findC8Path();
+	const c8Path = findC8Path$1();
 	const reportArgs = [
 		"report",
 		"--temp-directory",
@@ -240,6 +238,12 @@ async function generateCoverageReport(ctx) {
 		options.src,
 		"--all",
 		...options.include.flatMap((pattern) => ["--include", pattern]),
+		...options.exclude.flatMap((pattern) => ["--exclude", pattern]),
+		...options.excludeNodeModules ? ["--exclude-node-modules"] : ["--no-exclude-node-modules"],
+		...options.excludeAfterRemap ? ["--exclude-after-remap"] : [],
+		...options.skipFull ? ["--skip-full"] : [],
+		...options.allowExternal ? ["--allowExternal"] : [],
+		...options.monocart ? ["--experimental-monocart"] : [],
 		...options.reporters.flatMap((reporter) => ["--reporter", reporter])
 	];
 	const isNpx = c8Path === "npx c8";
@@ -278,9 +282,9 @@ 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.").action(runCommand);
+	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);
 }
-async function runCommand(files, options) {
+async function runCommand$1(files, options) {
 	const startTime = Date.now();
 	const opts = {
 		diff: options.diff !== false,
@@ -310,7 +314,13 @@ async function runCommand(files, options) {
 		coverageCtx = await createCoverageContext({
 			...globalConfig.coverage,
 			reportsDir: options.coverageDir ?? globalConfig.coverage?.reportsDir,
-			reporters: options.coverageReporter ?? globalConfig.coverage?.reporters
+			reporters: options.coverageReporter ?? globalConfig.coverage?.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
 		});
 		coverageEnv = getCoverageEnv(coverageCtx);
 	}
@@ -394,6 +404,223 @@ async function runCommand(files, options) {
 	process.exit(summary.totalFailed > 0 ? 1 : 0);
 }
 
+//#endregion
+//#region src/cli/commands/coverage.ts
+/**
+* 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);
+}
+/**
+* Run a command with inherited coverage environment.
+*/
+async function runCommand(command, env) {
+	return new Promise((resolve$2) => {
+		const proc = (0, node_child_process.spawn)(command, [], {
+			stdio: "inherit",
+			env: {
+				...process.env,
+				...env
+			},
+			shell: true
+		});
+		proc.on("close", (code) => {
+			resolve$2({
+				success: code === 0,
+				code: code ?? 1
+			});
+		});
+		proc.on("error", (err) => {
+			logError(`Failed to run command: ${err.message}`);
+			resolve$2({
+				success: false,
+				code: 1
+			});
+		});
+	});
+}
+/**
+* Find the c8 executable path.
+* Can be overridden via TRYSCRIPT_C8_COMMAND env var for testing.
+*/
+function findC8Path() {
+	const override = process.env.TRYSCRIPT_C8_COMMAND;
+	if (override) return override;
+	const localPaths = [(0, node_path.resolve)(process.cwd(), "node_modules", ".bin", "c8"), (0, node_path.resolve)(process.cwd(), "..", "..", "node_modules", ".bin", "c8")];
+	for (const localPath of localPaths) if ((0, node_fs.existsSync)(localPath)) return localPath;
+	return null;
+}
+/**
+* Get coverage file statistics from temp directory.
+*/
+async function getCoverageStats(tempDir) {
+	try {
+		const coverageFiles = (await (0, node_fs_promises.readdir)(tempDir)).filter((f) => f.startsWith("coverage-") && f.endsWith(".json"));
+		let totalBytes = 0;
+		for (const file of coverageFiles) {
+			const fileStat = await (0, node_fs_promises.stat)((0, node_path.join)(tempDir, file));
+			totalBytes += fileStat.size;
+		}
+		return {
+			fileCount: coverageFiles.length,
+			totalBytes,
+			files: coverageFiles
+		};
+	} catch {
+		return {
+			fileCount: 0,
+			totalBytes: 0,
+			files: []
+		};
+	}
+}
+/**
+* Generate a text-only coverage report for debugging (doesn't write files).
+*/
+async function generateTextReport(tempDir, options, label) {
+	const c8Path = findC8Path();
+	if (!c8Path) return;
+	const include = options.include ?? ["dist/**"];
+	const exclude = options.exclude ?? [];
+	const tempReportsDir = await (0, node_fs_promises.mkdtemp)((0, node_path.join)((0, node_os.tmpdir)(), "tryscript-coverage-report-"));
+	const reportArgs = [
+		"report",
+		"--temp-directory",
+		tempDir,
+		"--reports-dir",
+		tempReportsDir,
+		"--src",
+		options.src ?? "src",
+		"--all",
+		...include.flatMap((pattern) => ["--include", pattern]),
+		...exclude.flatMap((pattern) => ["--exclude", pattern]),
+		...options.excludeNodeModules !== false ? ["--exclude-node-modules"] : ["--no-exclude-node-modules"],
+		...options.excludeAfterRemap ? ["--exclude-after-remap"] : [],
+		...options.monocart ? ["--experimental-monocart"] : [],
+		"--reporter",
+		"text"
+	];
+	console.error(colors.info(`\n--- Coverage after: ${label} ---`));
+	await new Promise((resolve$2) => {
+		const proc = (0, node_child_process.spawn)(c8Path, reportArgs, {
+			stdio: "inherit",
+			shell: false
+		});
+		proc.on("close", () => {
+			resolve$2();
+		});
+		proc.on("error", () => {
+			resolve$2();
+		});
+	});
+	await (0, node_fs_promises.rm)(tempReportsDir, {
+		recursive: true,
+		force: true
+	});
+}
+/**
+* Generate c8 coverage report.
+*/
+async function generateReport(tempDir, options) {
+	const c8Path = findC8Path();
+	if (!c8Path) {
+		logError("c8 not found. Install with: npm install -D c8");
+		return false;
+	}
+	const reporters = options.reporters ?? [
+		"text",
+		"json",
+		"json-summary",
+		"lcov",
+		"html"
+	];
+	const include = options.include ?? ["dist/**"];
+	const exclude = options.exclude ?? [];
+	const reportArgs = [
+		"report",
+		"--temp-directory",
+		tempDir,
+		"--reports-dir",
+		options.reportsDir ?? "coverage",
+		"--src",
+		options.src ?? "src",
+		"--all",
+		...include.flatMap((pattern) => ["--include", pattern]),
+		...exclude.flatMap((pattern) => ["--exclude", pattern]),
+		...options.excludeNodeModules !== false ? ["--exclude-node-modules"] : ["--no-exclude-node-modules"],
+		...options.excludeAfterRemap ? ["--exclude-after-remap"] : [],
+		...options.skipFull ? ["--skip-full"] : [],
+		...options.allowExternal ? ["--allowExternal"] : [],
+		...options.monocart ? ["--experimental-monocart"] : [],
+		...reporters.flatMap((reporter) => ["--reporter", reporter])
+	];
+	return new Promise((resolve$2) => {
+		const proc = (0, node_child_process.spawn)(c8Path, reportArgs, {
+			stdio: "inherit",
+			shell: false
+		});
+		proc.on("close", (code) => {
+			resolve$2(code === 0);
+		});
+		proc.on("error", (err) => {
+			logError(`Failed to generate coverage report: ${err.message}`);
+			resolve$2(false);
+		});
+	});
+}
+async function coverageCommand(commands, options) {
+	if (commands.length === 0) {
+		logError("No commands specified. Usage: tryscript coverage \"cmd1\" \"cmd2\"");
+		process.exit(1);
+	}
+	if (!findC8Path()) {
+		logError("Coverage requires c8. Install with: npm install -D c8");
+		process.exit(1);
+	}
+	const parsedOptions = {
+		...options,
+		reporters: options.reporters ? typeof options.reporters === "string" ? options.reporters.split(",") : options.reporters : void 0,
+		include: options.include ? typeof options.include === "string" ? options.include.split(",") : options.include : void 0,
+		exclude: options.exclude ? typeof options.exclude === "string" ? options.exclude.split(",") : options.exclude : void 0
+	};
+	const coverageTemp = await (0, node_fs_promises.mkdtemp)((0, node_path.join)((0, node_os.tmpdir)(), "tryscript-coverage-"));
+	const coverageEnv = { NODE_V8_COVERAGE: coverageTemp };
+	console.error(colors.info(`Collecting V8 coverage to ${coverageTemp}`));
+	let hasFailures = false;
+	let previousFileCount = 0;
+	try {
+		for (let i = 0; i < commands.length; i++) {
+			const command = commands[i];
+			console.error(colors.info(`\n=== Running command ${i + 1}/${commands.length}: ${command} ===`));
+			const result = await runCommand(command, coverageEnv);
+			if (!result.success) {
+				logWarn(`Command exited with code ${result.code}: ${command}`);
+				hasFailures = true;
+			}
+			const stats = await getCoverageStats(coverageTemp);
+			const newFiles = stats.fileCount - previousFileCount;
+			const bytesKB = (stats.totalBytes / 1024).toFixed(1);
+			console.error(colors.info(`\nV8 coverage: ${stats.fileCount} files (${newFiles} new), ${bytesKB} KB total`));
+			if (newFiles === 0) logWarn("No new coverage files from this command. This may indicate the command doesn't write to NODE_V8_COVERAGE.");
+			if (parsedOptions.verbose && stats.fileCount > 0) await generateTextReport(coverageTemp, parsedOptions, command);
+			previousFileCount = stats.fileCount;
+		}
+		console.error(colors.info("\n=== Generating merged 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"}/`));
+	} finally {
+		await (0, node_fs_promises.rm)(coverageTemp, {
+			recursive: true,
+			force: true
+		});
+	}
+	if (hasFailures) process.exit(1);
+}
+
 //#endregion
 //#region src/cli/commands/readme.ts
 /**
@@ -473,7 +700,7 @@ function isInteractive$1() {
 */
 function showReadme(options) {
 	try {
-		const formatted = formatMarkdown$1(loadReadme(), !options?.raw && isInteractive$1());
+		const formatted = formatMarkdown$1(loadReadme(), options?.color ?? (!options?.raw && isInteractive$1()));
 		console.log(formatted);
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
@@ -485,7 +712,7 @@ function showReadme(options) {
 * Register the readme command.
 */
 function registerReadmeCommand(program) {
-	program.command("readme").description("Display README documentation").option("--raw", "Output raw markdown without formatting").action(showReadme);
+	program.command("readme").description("Display README documentation").option("--raw", "Output raw markdown without formatting").option("--color", "Force colorized output (for testing)").action(showReadme);
 }
 
 //#endregion
@@ -565,9 +792,9 @@ function isInteractive() {
 * Register the docs command.
 */
 function registerDocsCommand(program) {
-	program.command("docs").description("Display concise syntax reference").option("--raw", "Output raw markdown without formatting").action((options) => {
+	program.command("docs").description("Display concise syntax reference").option("--raw", "Output raw markdown without formatting").option("--color", "Force colorized output (for testing)").action((options) => {
 		try {
-			const formatted = formatMarkdown(loadDocs(), !options.raw && isInteractive());
+			const formatted = formatMarkdown(loadDocs(), options.color ?? (!options.raw && isInteractive()));
 			console.log(formatted);
 		} catch (error) {
 			const message = error instanceof Error ? error.message : String(error);
@@ -587,6 +814,7 @@ function registerDocsCommand(program) {
 function run(argv) {
 	const program = withColoredHelp(new commander.Command().name("tryscript").version(require_src.VERSION, "--version", "Show version number").description("Golden testing for CLI applications").showHelpAfterError("(use --help for usage)"));
 	registerRunCommand(program);
+	registerCoverageCommand(program);
 	registerReadmeCommand(program);
 	registerDocsCommand(program);
 	program.action(() => {