politty 0.0.1 → 0.1.0

package/dist/docs/index.js

@@ -0,0 +1,1182 @@
+import { n as getExtractedFields } from "../schema-extractor-Dk5Z0Iei.js";
+import { i as createLogCollector, n as resolveLazyCommand } from "../subcommand-router-BiSvDXHg.js";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+//#region src/docs/default-renderers.ts
+/**
+* Escape markdown special characters in table cells
+*/
+function escapeTableCell(str) {
+	return str.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+/**
+* Format default value for display
+*/
+function formatDefaultValue(value) {
+	if (value === void 0) return "-";
+	return `\`${JSON.stringify(value)}\``;
+}
+/**
+* Render usage line
+*/
+function renderUsage(info) {
+	const parts = [info.fullCommandPath];
+	if (info.options.length > 0) parts.push("[options]");
+	if (info.subCommands.length > 0) parts.push("[command]");
+	for (const arg of info.positionalArgs) if (arg.required) parts.push(`<${arg.name}>`);
+	else parts.push(`[${arg.name}]`);
+	return parts.join(" ");
+}
+/**
+* Render arguments as table
+*/
+function renderArgumentsTable(info) {
+	if (info.positionalArgs.length === 0) return "";
+	const lines = [];
+	lines.push("| Argument | Description | Required |");
+	lines.push("|----------|-------------|----------|");
+	for (const arg of info.positionalArgs) {
+		const desc = escapeTableCell(arg.description ?? "");
+		const required = arg.required ? "Yes" : "No";
+		lines.push(`| \`${arg.name}\` | ${desc} | ${required} |`);
+	}
+	return lines.join("\n");
+}
+/**
+* Render arguments as list
+*/
+function renderArgumentsList(info) {
+	if (info.positionalArgs.length === 0) return "";
+	const lines = [];
+	for (const arg of info.positionalArgs) {
+		const required = arg.required ? "(required)" : "(optional)";
+		const desc = arg.description ? ` - ${arg.description}` : "";
+		lines.push(`- \`${arg.name}\`${desc} ${required}`);
+	}
+	return lines.join("\n");
+}
+/**
+* Format environment variable info for display
+*/
+function formatEnvInfo(env) {
+	if (!env) return "";
+	return ` [env: ${(Array.isArray(env) ? env : [env]).join(", ")}]`;
+}
+/**
+* Format option flags (uses kebab-case cliName)
+*/
+function formatOptionFlags(opt) {
+	const parts = [];
+	const placeholder = opt.placeholder ?? opt.cliName.toUpperCase().replace(/-/g, "_");
+	const longFlag = opt.type === "boolean" ? `--${opt.cliName}` : `--${opt.cliName} <${placeholder}>`;
+	if (opt.alias) parts.push(`\`-${opt.alias}\`, \`${longFlag}\``);
+	else parts.push(`\`${longFlag}\``);
+	return parts.join("");
+}
+/**
+* Render options as markdown table
+*
+* Features:
+* - Uses kebab-case (cliName) for option names (e.g., `--dry-run` instead of `--dryRun`)
+* - Automatically adds Env column when any option has env configured
+* - Displays multiple env vars as comma-separated list
+*
+* @example
+* | Option | Alias | Description | Default | Env |
+* |--------|-------|-------------|---------|-----|
+* | `--dry-run` | `-d` | Dry run mode | `false` | - |
+* | `--port <PORT>` | - | Server port | - | `PORT`, `SERVER_PORT` |
+*/
+function renderOptionsTable(info) {
+	if (info.options.length === 0) return "";
+	const hasEnv = info.options.some((opt) => opt.env);
+	const lines = [];
+	if (hasEnv) {
+		lines.push("| Option | Alias | Description | Default | Env |");
+		lines.push("|--------|-------|-------------|---------|-----|");
+	} else {
+		lines.push("| Option | Alias | Description | Default |");
+		lines.push("|--------|-------|-------------|---------|");
+	}
+	for (const opt of info.options) {
+		const placeholder = opt.placeholder ?? opt.cliName.toUpperCase().replace(/-/g, "_");
+		const optionName = opt.type === "boolean" ? `\`--${opt.cliName}\`` : `\`--${opt.cliName} <${placeholder}>\``;
+		const alias = opt.alias ? `\`-${opt.alias}\`` : "-";
+		const desc = escapeTableCell(opt.description ?? "");
+		const defaultVal = formatDefaultValue(opt.defaultValue);
+		if (hasEnv) {
+			const envNames = opt.env ? Array.isArray(opt.env) ? opt.env.map((e) => `\`${e}\``).join(", ") : `\`${opt.env}\`` : "-";
+			lines.push(`| ${optionName} | ${alias} | ${desc} | ${defaultVal} | ${envNames} |`);
+		} else lines.push(`| ${optionName} | ${alias} | ${desc} | ${defaultVal} |`);
+	}
+	return lines.join("\n");
+}
+/**
+* Render options as markdown list
+*
+* Features:
+* - Uses kebab-case (cliName) for option names (e.g., `--dry-run` instead of `--dryRun`)
+* - Appends env info at the end of each option (e.g., `[env: PORT, SERVER_PORT]`)
+*
+* @example
+* - `-d`, `--dry-run` - Dry run mode (default: false)
+* - `--port <PORT>` - Server port [env: PORT, SERVER_PORT]
+*/
+function renderOptionsList(info) {
+	if (info.options.length === 0) return "";
+	const lines = [];
+	for (const opt of info.options) {
+		const flags = formatOptionFlags(opt);
+		const desc = opt.description ? ` - ${opt.description}` : "";
+		const defaultVal = opt.defaultValue !== void 0 ? ` (default: ${JSON.stringify(opt.defaultValue)})` : "";
+		const envInfo = formatEnvInfo(opt.env);
+		lines.push(`- ${flags}${desc}${defaultVal}${envInfo}`);
+	}
+	return lines.join("\n");
+}
+/**
+* Generate anchor from command path
+*/
+function generateAnchor(commandPath) {
+	return commandPath.join("-").toLowerCase();
+}
+/**
+* Generate relative path from one file to another
+*/
+function getRelativePath(from, to) {
+	const fromParts = from.split("/").slice(0, -1);
+	const toParts = to.split("/");
+	let commonLength = 0;
+	while (commonLength < fromParts.length && commonLength < toParts.length - 1 && fromParts[commonLength] === toParts[commonLength]) commonLength++;
+	const upCount = fromParts.length - commonLength;
+	return [...Array(upCount).fill(".."), ...toParts.slice(commonLength)].join("/") || (toParts[toParts.length - 1] ?? "");
+}
+/**
+* Render subcommands as table
+*/
+function renderSubcommandsTable(info, generateAnchors = true) {
+	if (info.subCommands.length === 0) return "";
+	const lines = [];
+	lines.push("| Command | Description |");
+	lines.push("|---------|-------------|");
+	const currentFile = info.filePath;
+	const fileMap = info.fileMap;
+	for (const sub of info.subCommands) {
+		const fullName = sub.fullPath.join(" ");
+		const desc = escapeTableCell(sub.description ?? "");
+		const subCommandPath = sub.fullPath.join(" ");
+		if (generateAnchors) {
+			const anchor = generateAnchor(sub.fullPath);
+			const subFile = fileMap?.[subCommandPath];
+			if (currentFile && subFile && currentFile !== subFile) {
+				const relativePath = getRelativePath(currentFile, subFile);
+				lines.push(`| [\`${fullName}\`](${relativePath}#${anchor}) | ${desc} |`);
+			} else lines.push(`| [\`${fullName}\`](#${anchor}) | ${desc} |`);
+		} else lines.push(`| \`${fullName}\` | ${desc} |`);
+	}
+	return lines.join("\n");
+}
+/**
+* Render options from array as table
+*/
+function renderOptionsTableFromArray(options) {
+	if (options.length === 0) return "";
+	const hasEnv = options.some((opt) => opt.env);
+	const lines = [];
+	if (hasEnv) {
+		lines.push("| Option | Alias | Description | Default | Env |");
+		lines.push("|--------|-------|-------------|---------|-----|");
+	} else {
+		lines.push("| Option | Alias | Description | Default |");
+		lines.push("|--------|-------|-------------|---------|");
+	}
+	for (const opt of options) {
+		const placeholder = opt.placeholder ?? opt.cliName.toUpperCase().replace(/-/g, "_");
+		const optionName = opt.type === "boolean" ? `\`--${opt.cliName}\`` : `\`--${opt.cliName} <${placeholder}>\``;
+		const alias = opt.alias ? `\`-${opt.alias}\`` : "-";
+		const desc = escapeTableCell(opt.description ?? "");
+		const defaultVal = formatDefaultValue(opt.defaultValue);
+		if (hasEnv) {
+			const envNames = opt.env ? Array.isArray(opt.env) ? opt.env.map((e) => `\`${e}\``).join(", ") : `\`${opt.env}\`` : "-";
+			lines.push(`| ${optionName} | ${alias} | ${desc} | ${defaultVal} | ${envNames} |`);
+		} else lines.push(`| ${optionName} | ${alias} | ${desc} | ${defaultVal} |`);
+	}
+	return lines.join("\n");
+}
+/**
+* Render options from array as list
+*/
+function renderOptionsListFromArray(options) {
+	if (options.length === 0) return "";
+	const lines = [];
+	for (const opt of options) {
+		const flags = formatOptionFlags(opt);
+		const desc = opt.description ? ` - ${opt.description}` : "";
+		const defaultVal = opt.defaultValue !== void 0 ? ` (default: ${JSON.stringify(opt.defaultValue)})` : "";
+		const envInfo = formatEnvInfo(opt.env);
+		lines.push(`- ${flags}${desc}${defaultVal}${envInfo}`);
+	}
+	return lines.join("\n");
+}
+/**
+* Render arguments from array as table
+*/
+function renderArgumentsTableFromArray(args) {
+	if (args.length === 0) return "";
+	const lines = [];
+	lines.push("| Argument | Description | Required |");
+	lines.push("|----------|-------------|----------|");
+	for (const arg of args) {
+		const desc = escapeTableCell(arg.description ?? "");
+		const required = arg.required ? "Yes" : "No";
+		lines.push(`| \`${arg.name}\` | ${desc} | ${required} |`);
+	}
+	return lines.join("\n");
+}
+/**
+* Render arguments from array as list
+*/
+function renderArgumentsListFromArray(args) {
+	if (args.length === 0) return "";
+	const lines = [];
+	for (const arg of args) {
+		const required = arg.required ? "(required)" : "(optional)";
+		const desc = arg.description ? ` - ${arg.description}` : "";
+		lines.push(`- \`${arg.name}\`${desc} ${required}`);
+	}
+	return lines.join("\n");
+}
+/**
+* Render subcommands from array as table
+*/
+function renderSubcommandsTableFromArray(subcommands, info, generateAnchors = true) {
+	if (subcommands.length === 0) return "";
+	const lines = [];
+	lines.push("| Command | Description |");
+	lines.push("|---------|-------------|");
+	const currentFile = info.filePath;
+	const fileMap = info.fileMap;
+	for (const sub of subcommands) {
+		const fullName = sub.fullPath.join(" ");
+		const desc = escapeTableCell(sub.description ?? "");
+		const subCommandPath = sub.fullPath.join(" ");
+		if (generateAnchors) {
+			const anchor = generateAnchor(sub.fullPath);
+			const subFile = fileMap?.[subCommandPath];
+			if (currentFile && subFile && currentFile !== subFile) {
+				const relativePath = getRelativePath(currentFile, subFile);
+				lines.push(`| [\`${fullName}\`](${relativePath}#${anchor}) | ${desc} |`);
+			} else lines.push(`| [\`${fullName}\`](#${anchor}) | ${desc} |`);
+		} else lines.push(`| \`${fullName}\` | ${desc} |`);
+	}
+	return lines.join("\n");
+}
+/**
+* Render examples as markdown
+*
+* @example
+* **Basic usage**
+*
+* ```bash
+* $ greet World
+* ```
+*
+* Output:
+* ```
+* Hello, World!
+* ```
+*/
+function renderExamplesDefault(examples, results, opts) {
+	if (examples.length === 0) return "";
+	const showOutput = opts?.showOutput ?? true;
+	const lines = [];
+	for (let i = 0; i < examples.length; i++) {
+		const example = examples[i];
+		if (!example) continue;
+		const result = results?.[i];
+		lines.push(`**${example.desc}**`);
+		lines.push("");
+		lines.push("```bash");
+		lines.push(`$ ${example.cmd}`);
+		if (showOutput) {
+			if (result) {
+				if (result.stdout) lines.push(result.stdout);
+				if (result.stderr) lines.push(`[stderr] ${result.stderr}`);
+			} else if (example.output) lines.push(example.output);
+		}
+		lines.push("```");
+		lines.push("");
+	}
+	while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+	return lines.join("\n");
+}
+/**
+* Create command renderer with options
+*/
+function createCommandRenderer(options = {}) {
+	const { headingLevel = 1, optionStyle = "table", generateAnchors = true, includeSubcommandDetails = true, renderDescription: customRenderDescription, renderUsage: customRenderUsage, renderArguments: customRenderArguments, renderOptions: customRenderOptions, renderSubcommands: customRenderSubcommands, renderNotes: customRenderNotes, renderFooter: customRenderFooter, renderExamples: customRenderExamples } = options;
+	return (info) => {
+		const lines = [];
+		const effectiveLevel = Math.min(headingLevel + (info.depth - 1), 6);
+		const h = "#".repeat(effectiveLevel);
+		const title = info.commandPath || info.name;
+		lines.push(`${h} ${title}`);
+		lines.push("");
+		if (info.description) {
+			const context = {
+				content: info.description,
+				heading: "",
+				info
+			};
+			const content = customRenderDescription ? customRenderDescription(context) : context.content;
+			if (content) {
+				lines.push(content);
+				lines.push("");
+			}
+		}
+		{
+			const context = {
+				content: `**Usage**\n\n\`\`\`\n${renderUsage(info)}\n\`\`\``,
+				heading: "**Usage**",
+				info
+			};
+			const content = customRenderUsage ? customRenderUsage(context) : context.content;
+			if (content) {
+				lines.push(content);
+				lines.push("");
+			}
+		}
+		if (info.positionalArgs.length > 0) {
+			const renderArgs = (args, opts) => {
+				const style = opts?.style ?? optionStyle;
+				const withHeading = opts?.withHeading ?? true;
+				const content$1 = style === "table" ? renderArgumentsTableFromArray(args) : renderArgumentsListFromArray(args);
+				return withHeading ? `**Arguments**\n\n${content$1}` : content$1;
+			};
+			const context = {
+				args: info.positionalArgs,
+				render: renderArgs,
+				heading: "**Arguments**",
+				info
+			};
+			const content = customRenderArguments ? customRenderArguments(context) : renderArgs(context.args);
+			if (content) {
+				lines.push(content);
+				lines.push("");
+			}
+		}
+		if (info.options.length > 0) {
+			const renderOpts = (opts, renderOpts$1) => {
+				const style = renderOpts$1?.style ?? optionStyle;
+				const withHeading = renderOpts$1?.withHeading ?? true;
+				const content$1 = style === "table" ? renderOptionsTableFromArray(opts) : renderOptionsListFromArray(opts);
+				return withHeading ? `**Options**\n\n${content$1}` : content$1;
+			};
+			const context = {
+				options: info.options,
+				render: renderOpts,
+				heading: "**Options**",
+				info
+			};
+			const content = customRenderOptions ? customRenderOptions(context) : renderOpts(context.options);
+			if (content) {
+				lines.push(content);
+				lines.push("");
+			}
+		}
+		if (info.subCommands.length > 0) {
+			const effectiveAnchors = generateAnchors && includeSubcommandDetails;
+			const renderSubs = (subs, opts) => {
+				const anchors = opts?.generateAnchors ?? effectiveAnchors;
+				const withHeading = opts?.withHeading ?? true;
+				const content$1 = renderSubcommandsTableFromArray(subs, info, anchors);
+				return withHeading ? `**Commands**\n\n${content$1}` : content$1;
+			};
+			const context = {
+				subcommands: info.subCommands,
+				render: renderSubs,
+				heading: "**Commands**",
+				info
+			};
+			const content = customRenderSubcommands ? customRenderSubcommands(context) : renderSubs(context.subcommands);
+			if (content) {
+				lines.push(content);
+				lines.push("");
+			}
+		}
+		if (info.examples && info.examples.length > 0) {
+			const renderEx = (examples, results, opts) => {
+				const withHeading = opts?.withHeading ?? true;
+				const content$1 = renderExamplesDefault(examples, results, opts);
+				return withHeading ? `**Examples**\n\n${content$1}` : content$1;
+			};
+			const context = {
+				examples: info.examples,
+				results: info.exampleResults,
+				render: renderEx,
+				heading: "**Examples**",
+				info
+			};
+			const content = customRenderExamples ? customRenderExamples(context) : renderEx(context.examples, context.results);
+			if (content) {
+				lines.push(content);
+				lines.push("");
+			}
+		}
+		if (info.notes) {
+			const context = {
+				content: `**Notes**\n\n${info.notes}`,
+				heading: "**Notes**",
+				info
+			};
+			const content = customRenderNotes ? customRenderNotes(context) : context.content;
+			if (content) {
+				lines.push(content);
+				lines.push("");
+			}
+		}
+		{
+			const context = {
+				content: "",
+				heading: "",
+				info
+			};
+			const content = customRenderFooter ? customRenderFooter(context) : context.content;
+			if (content) {
+				lines.push(content);
+				lines.push("");
+			}
+		}
+		while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+		lines.push("");
+		return lines.join("\n");
+	};
+}
+/**
+* Default renderers presets
+*/
+const defaultRenderers = {
+	command: (options) => createCommandRenderer(options),
+	tableStyle: createCommandRenderer({ optionStyle: "table" }),
+	listStyle: createCommandRenderer({ optionStyle: "list" })
+};
+
+//#endregion
+//#region src/docs/doc-comparator.ts
+/**
+* Compare generated content with existing file
+*/
+function compareWithExisting(generatedContent, filePath) {
+	const absolutePath = path.resolve(filePath);
+	if (!fs.existsSync(absolutePath)) return {
+		match: false,
+		fileExists: false
+	};
+	const existingContent = fs.readFileSync(absolutePath, "utf-8");
+	if (generatedContent === existingContent) return {
+		match: true,
+		fileExists: true
+	};
+	return {
+		match: false,
+		diff: formatDiff(existingContent, generatedContent),
+		fileExists: true
+	};
+}
+/**
+* Format diff between two strings in unified diff format
+*/
+function formatDiff(expected, actual) {
+	const expectedLines = expected.split("\n");
+	const actualLines = actual.split("\n");
+	const result = [];
+	result.push("--- existing");
+	result.push("+++ generated");
+	result.push("");
+	const maxLines = Math.max(expectedLines.length, actualLines.length);
+	let inChunk = false;
+	let chunkStart = 0;
+	const chunk = [];
+	const flushChunk = () => {
+		if (chunk.length > 0) {
+			result.push(`@@ -${chunkStart + 1},${chunk.length} @@`);
+			result.push(...chunk);
+			chunk.length = 0;
+		}
+		inChunk = false;
+	};
+	for (let i = 0; i < maxLines; i++) {
+		const expectedLine = expectedLines[i];
+		const actualLine = actualLines[i];
+		if (expectedLine === actualLine) {
+			if (inChunk) {
+				chunk.push(` ${expectedLine ?? ""}`);
+				const lastChangeIndex = chunk.findIndex((line, idx) => (line.startsWith("-") || line.startsWith("+")) && chunk.slice(idx + 1).every((l) => l.startsWith(" ")));
+				if (lastChangeIndex !== -1 && chunk.length - lastChangeIndex > 3) flushChunk();
+			}
+		} else {
+			if (!inChunk) {
+				inChunk = true;
+				chunkStart = i;
+				const contextStart = Math.max(0, i - 3);
+				for (let j = contextStart; j < i; j++) chunk.push(` ${expectedLines[j] ?? ""}`);
+			}
+			if (expectedLine !== void 0 && (actualLine === void 0 || expectedLine !== actualLine)) chunk.push(`-${expectedLine}`);
+			if (actualLine !== void 0 && (expectedLine === void 0 || expectedLine !== actualLine)) chunk.push(`+${actualLine}`);
+		}
+	}
+	flushChunk();
+	return result.join("\n");
+}
+/**
+* Write content to file, creating directories if needed
+*/
+function writeFile(filePath, content) {
+	const absolutePath = path.resolve(filePath);
+	const dir = path.dirname(absolutePath);
+	if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+	fs.writeFileSync(absolutePath, content, "utf-8");
+}
+/**
+* Read file content if it exists
+* Returns null if file does not exist
+*/
+function readFile(filePath) {
+	const absolutePath = path.resolve(filePath);
+	if (!fs.existsSync(absolutePath)) return null;
+	return fs.readFileSync(absolutePath, "utf-8");
+}
+/**
+* Delete file if it exists
+* @param filePath - Path to the file to delete
+* @param fileSystem - Optional fs implementation (useful when fs is mocked)
+*/
+function deleteFile(filePath, fileSystem = fs) {
+	const absolutePath = path.resolve(filePath);
+	if (fileSystem.existsSync(absolutePath)) fileSystem.unlinkSync(absolutePath);
+}
+
+//#endregion
+//#region src/docs/doc-generator.ts
+/**
+* Build CommandInfo from a command
+*/
+async function buildCommandInfo(command, rootName, commandPath = []) {
+	const extracted = getExtractedFields(command);
+	const positionalArgs = extracted?.fields.filter((f) => f.positional) ?? [];
+	const options = extracted?.fields.filter((f) => !f.positional) ?? [];
+	const subCommands = [];
+	if (command.subCommands) for (const [name, subCmd] of Object.entries(command.subCommands)) {
+		const resolved = await resolveLazyCommand(subCmd);
+		const fullPath = [...commandPath, name];
+		subCommands.push({
+			name,
+			description: resolved.description,
+			fullPath
+		});
+	}
+	return {
+		name: command.name ?? "",
+		description: command.description,
+		fullCommandPath: commandPath.length > 0 ? `${rootName} ${commandPath.join(" ")}` : rootName,
+		commandPath: commandPath.join(" "),
+		depth: commandPath.length + 1,
+		positionalArgs,
+		options,
+		subCommands,
+		extracted,
+		command,
+		notes: command.notes,
+		examples: command.examples
+	};
+}
+/**
+* Collect all commands with their paths
+* Returns a map of command path -> CommandInfo
+*/
+async function collectAllCommands(command, rootName) {
+	const root = rootName ?? command.name ?? "command";
+	const result = /* @__PURE__ */ new Map();
+	async function traverse(cmd, path$1) {
+		const info = await buildCommandInfo(cmd, root, path$1);
+		const pathKey = path$1.join(" ");
+		result.set(pathKey, info);
+		if (cmd.subCommands) for (const [name, subCmd] of Object.entries(cmd.subCommands)) await traverse(await resolveLazyCommand(subCmd), [...path$1, name]);
+	}
+	await traverse(command, []);
+	return result;
+}
+
+//#endregion
+//#region src/docs/example-executor.ts
+/**
+* Execute examples for a command and capture output
+*
+* @param examples - Examples to execute
+* @param config - Execution configuration (mock setup/cleanup)
+* @param rootCommand - Root command to execute against
+* @param commandPath - Command path for subcommands (e.g., ["config", "get"])
+* @returns Array of execution results with captured stdout/stderr
+*/
+async function executeExamples(examples, config, rootCommand, commandPath = []) {
+	const results = [];
+	if (config.mock) await config.mock();
+	try {
+		for (const example of examples) {
+			const result = await executeSingleExample(example, rootCommand, commandPath);
+			results.push(result);
+		}
+	} finally {
+		if (config.cleanup) await config.cleanup();
+	}
+	return results;
+}
+/**
+* Execute a single example and capture output
+*/
+async function executeSingleExample(example, rootCommand, commandPath) {
+	const exampleArgs = parseExampleCmd(example.cmd);
+	const argv = [...commandPath, ...exampleArgs];
+	const collector = createLogCollector({ passthrough: false });
+	collector.start();
+	let success = true;
+	try {
+		const { runCommand } = await import("../runner-C_m6ve-j.js");
+		const result = await runCommand(rootCommand, argv);
+		success = result.success;
+		if (!result.success && result.error) console.error(result.error.message);
+	} catch (error) {
+		success = false;
+		console.error(error instanceof Error ? error.message : String(error));
+	} finally {
+		collector.stop();
+	}
+	const logs = collector.getLogs();
+	const stdout = logs.entries.filter((e) => e.stream === "stdout").map((e) => e.message).join("\n");
+	const stderr = logs.entries.filter((e) => e.stream === "stderr").map((e) => e.message).join("\n");
+	return {
+		cmd: example.cmd,
+		desc: example.desc,
+		expectedOutput: example.output,
+		stdout,
+		stderr,
+		success
+	};
+}
+/**
+* Parse example command string into argv array
+* Handles quoted strings (single and double quotes)
+*
+* @example
+* parseExampleCmd('World') // ['World']
+* parseExampleCmd('--name "John Doe"') // ['--name', 'John Doe']
+* parseExampleCmd("--greeting 'Hello World'") // ['--greeting', 'Hello World']
+*/
+function parseExampleCmd(cmd) {
+	const args = [];
+	let current = "";
+	let inQuote = false;
+	let quoteChar = "";
+	for (let i = 0; i < cmd.length; i++) {
+		const char = cmd[i];
+		if ((char === "\"" || char === "'") && !inQuote) {
+			inQuote = true;
+			quoteChar = char;
+		} else if (char === quoteChar && inQuote) {
+			inQuote = false;
+			quoteChar = "";
+		} else if (char === " " && !inQuote) {
+			if (current) {
+				args.push(current);
+				current = "";
+			}
+		} else current += char;
+	}
+	if (current) args.push(current);
+	return args;
+}
+
+//#endregion
+//#region src/docs/types.ts
+/**
+* Environment variable name for update mode
+*/
+const UPDATE_GOLDEN_ENV = "POLITTY_DOCS_UPDATE";
+/**
+* Marker prefix for command sections in generated documentation
+* Format: <!-- politty:command:<path>:start --> ... <!-- politty:command:<path>:end -->
+*/
+const COMMAND_MARKER_PREFIX = "politty:command";
+/**
+* Generate start marker for a command section
+*/
+function commandStartMarker(commandPath) {
+	return `<!-- ${COMMAND_MARKER_PREFIX}:${commandPath}:start -->`;
+}
+/**
+* Generate end marker for a command section
+*/
+function commandEndMarker(commandPath) {
+	return `<!-- ${COMMAND_MARKER_PREFIX}:${commandPath}:end -->`;
+}
+
+//#endregion
+//#region src/docs/golden-test.ts
+/**
+* Apply formatter to content if provided
+* Supports both sync and async formatters
+*/
+async function applyFormatter(content, formatter) {
+	if (!formatter) return content;
+	return await formatter(content);
+}
+/**
+* Check if update mode is enabled via environment variable
+*/
+function isUpdateMode() {
+	const value = process.env[UPDATE_GOLDEN_ENV];
+	return value === "true" || value === "1";
+}
+/**
+* Normalize file mapping entry to FileConfig
+*/
+function normalizeFileConfig(config) {
+	if (Array.isArray(config)) return { commands: config };
+	return config;
+}
+/**
+* Check if a command path is a subcommand of another
+*/
+function isSubcommandOf(childPath, parentPath) {
+	if (parentPath === "") return true;
+	if (childPath === parentPath) return true;
+	return childPath.startsWith(parentPath + " ");
+}
+/**
+* Check if a pattern contains wildcards
+*/
+function containsWildcard(pattern) {
+	return pattern.includes("*");
+}
+/**
+* Check if a command path matches a wildcard pattern
+* - `*` matches any single command segment
+* - Pattern segments are space-separated
+*
+* @example
+* matchesWildcard("config get", "* *") // true
+* matchesWildcard("config", "* *") // false
+* matchesWildcard("config get", "config *") // true
+* matchesWildcard("greet", "*") // true
+*/
+function matchesWildcard(path$1, pattern) {
+	const pathSegments = path$1 === "" ? [] : path$1.split(" ");
+	const patternSegments = pattern === "" ? [] : pattern.split(" ");
+	if (pathSegments.length !== patternSegments.length) return false;
+	for (let i = 0; i < patternSegments.length; i++) {
+		const patternSeg = patternSegments[i];
+		const pathSeg = pathSegments[i];
+		if (patternSeg !== "*" && patternSeg !== pathSeg) return false;
+	}
+	return true;
+}
+/**
+* Expand a wildcard pattern to matching command paths
+*/
+function expandWildcardPattern(pattern, allCommands) {
+	const matches = [];
+	for (const cmdPath of allCommands.keys()) if (matchesWildcard(cmdPath, pattern)) matches.push(cmdPath);
+	return matches;
+}
+/**
+* Check if a path matches any ignore pattern (with wildcard support)
+* For wildcard patterns, also ignores subcommands of matched commands
+*/
+function matchesIgnorePattern(path$1, ignorePattern) {
+	if (containsWildcard(ignorePattern)) {
+		if (matchesWildcard(path$1, ignorePattern)) return true;
+		const pathSegments = path$1 === "" ? [] : path$1.split(" ");
+		const patternSegments = ignorePattern === "" ? [] : ignorePattern.split(" ");
+		if (pathSegments.length > patternSegments.length) return matchesWildcard(pathSegments.slice(0, patternSegments.length).join(" "), ignorePattern);
+		return false;
+	}
+	return isSubcommandOf(path$1, ignorePattern);
+}
+/**
+* Expand command paths to include all subcommands (with wildcard support)
+*/
+function expandCommandPaths(commandPaths, allCommands) {
+	const expanded = /* @__PURE__ */ new Set();
+	for (const cmdPath of commandPaths) if (containsWildcard(cmdPath)) {
+		const matches = expandWildcardPattern(cmdPath, allCommands);
+		for (const match of matches) {
+			expanded.add(match);
+			for (const path$1 of allCommands.keys()) if (isSubcommandOf(path$1, match)) expanded.add(path$1);
+		}
+	} else {
+		if (allCommands.has(cmdPath)) expanded.add(cmdPath);
+		for (const path$1 of allCommands.keys()) if (isSubcommandOf(path$1, cmdPath)) expanded.add(path$1);
+	}
+	return Array.from(expanded);
+}
+/**
+* Filter out ignored commands (with wildcard support)
+*/
+function filterIgnoredCommands(commandPaths, ignores) {
+	return commandPaths.filter((path$1) => {
+		return !ignores.some((ignorePattern) => matchesIgnorePattern(path$1, ignorePattern));
+	});
+}
+/**
+* Validate that there are no conflicts between files and ignores (with wildcard support)
+*/
+function validateNoConflicts(filesCommands, ignores, allCommands) {
+	const conflicts = [];
+	for (const filePattern of filesCommands) {
+		const filePaths = containsWildcard(filePattern) ? expandWildcardPattern(filePattern, allCommands) : [filePattern];
+		for (const filePath of filePaths) for (const ignorePattern of ignores) if (containsWildcard(ignorePattern)) {
+			if (matchesWildcard(filePath, ignorePattern)) conflicts.push(`"${filePath}" is both in files and ignored by "${ignorePattern}"`);
+		} else if (filePath === ignorePattern || isSubcommandOf(filePath, ignorePattern)) conflicts.push(`"${filePath}" is both in files and ignored by "${ignorePattern}"`);
+	}
+	if (conflicts.length > 0) throw new Error(`Conflict between files and ignores:\n  - ${conflicts.join("\n  - ")}`);
+}
+/**
+* Validate that all ignored paths exist in the command tree (with wildcard support)
+*/
+function validateIgnoresExist(ignores, allCommands) {
+	const nonExistent = [];
+	for (const ignorePattern of ignores) if (containsWildcard(ignorePattern)) {
+		if (expandWildcardPattern(ignorePattern, allCommands).length === 0) nonExistent.push(`"${ignorePattern}"`);
+	} else if (!allCommands.has(ignorePattern)) nonExistent.push(`"${ignorePattern}"`);
+	if (nonExistent.length > 0) throw new Error(`Ignored command paths do not exist: ${nonExistent.join(", ")}`);
+}
+/**
+* Sort command paths in depth-first order while preserving the specified command order
+* Parent commands are immediately followed by their subcommands
+*/
+function sortDepthFirst(commandPaths, specifiedOrder) {
+	const pathSet = new Set(commandPaths);
+	const topLevelPaths = specifiedOrder.filter((cmd) => pathSet.has(cmd));
+	for (const path$1 of commandPaths) if ((path$1 === "" ? 0 : path$1.split(" ").length) === 1 && !topLevelPaths.includes(path$1)) topLevelPaths.push(path$1);
+	const result = [];
+	const visited = /* @__PURE__ */ new Set();
+	function addWithChildren(cmdPath) {
+		if (visited.has(cmdPath) || !pathSet.has(cmdPath)) return;
+		visited.add(cmdPath);
+		result.push(cmdPath);
+		const children = commandPaths.filter((p) => {
+			if (p === cmdPath || visited.has(p)) return false;
+			if (cmdPath === "") return p.split(" ").length === 1;
+			return p.startsWith(cmdPath + " ") && p.split(" ").length === cmdPath.split(" ").length + 1;
+		}).sort((a, b) => a.localeCompare(b));
+		for (const child of children) addWithChildren(child);
+	}
+	for (const topLevel of topLevelPaths) addWithChildren(topLevel);
+	for (const path$1 of commandPaths) if (!visited.has(path$1)) result.push(path$1);
+	return result;
+}
+/**
+* Generate file header from FileConfig
+*/
+function generateFileHeader(fileConfig) {
+	if (!fileConfig.title && !fileConfig.description) return null;
+	const parts = [];
+	if (fileConfig.title) parts.push(`# ${fileConfig.title}`);
+	if (fileConfig.description) {
+		parts.push("");
+		parts.push(fileConfig.description);
+	}
+	parts.push("");
+	return parts.join("\n");
+}
+/**
+* Extract a command section from content using markers
+* Returns the content between start and end markers (including markers)
+*/
+function extractCommandSection(content, commandPath) {
+	const startMarker = commandStartMarker(commandPath);
+	const endMarker = commandEndMarker(commandPath);
+	const startIndex = content.indexOf(startMarker);
+	if (startIndex === -1) return null;
+	const endIndex = content.indexOf(endMarker, startIndex);
+	if (endIndex === -1) return null;
+	return content.slice(startIndex, endIndex + endMarker.length);
+}
+/**
+* Replace a command section in content using markers
+* Returns the updated content with the new section
+*/
+function replaceCommandSection(content, commandPath, newSection) {
+	const startMarker = commandStartMarker(commandPath);
+	const endMarker = commandEndMarker(commandPath);
+	const startIndex = content.indexOf(startMarker);
+	if (startIndex === -1) return null;
+	const endIndex = content.indexOf(endMarker, startIndex);
+	if (endIndex === -1) return null;
+	return content.slice(0, startIndex) + newSection + content.slice(endIndex + endMarker.length);
+}
+/**
+* Insert a command section at the correct position based on specified order
+* Returns the updated content with the section inserted at the right position
+*/
+function insertCommandSection(content, commandPath, newSection, specifiedOrder) {
+	const targetIndex = specifiedOrder.indexOf(commandPath);
+	if (targetIndex === -1) return content.trimEnd() + "\n\n" + newSection + "\n";
+	for (let i = targetIndex + 1; i < specifiedOrder.length; i++) {
+		const nextCmd = specifiedOrder[i];
+		if (nextCmd === void 0) continue;
+		const nextMarker = commandStartMarker(nextCmd);
+		const nextIndex = content.indexOf(nextMarker);
+		if (nextIndex !== -1) {
+			let insertPos = nextIndex;
+			while (insertPos > 0 && content[insertPos - 1] === "\n") insertPos--;
+			if (insertPos < nextIndex) insertPos++;
+			return content.slice(0, insertPos) + newSection + "\n" + content.slice(nextIndex);
+		}
+	}
+	for (let i = targetIndex - 1; i >= 0; i--) {
+		const prevCmd = specifiedOrder[i];
+		if (prevCmd === void 0) continue;
+		const prevEndMarker = commandEndMarker(prevCmd);
+		const prevEndIndex = content.indexOf(prevEndMarker);
+		if (prevEndIndex !== -1) {
+			const insertPos = prevEndIndex + prevEndMarker.length;
+			return content.slice(0, insertPos) + "\n" + newSection + content.slice(insertPos);
+		}
+	}
+	return content.trimEnd() + "\n" + newSection + "\n";
+}
+/**
+* Find which file contains a specific command
+*/
+function findFileForCommand(commandPath, files, allCommands, ignores) {
+	for (const [filePath, fileConfigRaw] of Object.entries(files)) {
+		const specifiedCommands = normalizeFileConfig(fileConfigRaw).commands;
+		if (filterIgnoredCommands(expandCommandPaths(specifiedCommands, allCommands), ignores).includes(commandPath)) return filePath;
+	}
+	return null;
+}
+/**
+* Find which target commands are contained in a file
+* Also expands each target command to include subcommands that are NOT explicitly in specifiedCommands
+*/
+function findTargetCommandsInFile(targetCommands, filePath, files, allCommands, ignores) {
+	const fileConfigRaw = files[filePath];
+	if (!fileConfigRaw) return [];
+	const specifiedCommands = normalizeFileConfig(fileConfigRaw).commands;
+	const commandPaths = filterIgnoredCommands(expandCommandPaths(specifiedCommands, allCommands), ignores);
+	const expandedTargets = /* @__PURE__ */ new Set();
+	for (const targetCmd of targetCommands) {
+		if (!commandPaths.includes(targetCmd)) continue;
+		expandedTargets.add(targetCmd);
+		for (const cmdPath of commandPaths) if (isSubcommandOf(cmdPath, targetCmd) && !specifiedCommands.includes(cmdPath)) expandedTargets.add(cmdPath);
+	}
+	return Array.from(expandedTargets);
+}
+/**
+* Generate a single command section with markers
+*/
+function generateCommandSection(cmdPath, allCommands, render, filePath, fileMap) {
+	const info = allCommands.get(cmdPath);
+	if (!info) return null;
+	const renderedSection = render({
+		...info,
+		filePath,
+		fileMap
+	});
+	return [
+		commandStartMarker(cmdPath),
+		renderedSection,
+		commandEndMarker(cmdPath)
+	].join("\n");
+}
+/**
+* Generate markdown for a file containing multiple commands
+* Each command section is wrapped with markers for partial validation
+*/
+function generateFileMarkdown(commandPaths, allCommands, render, filePath, fileMap, specifiedOrder, fileConfig) {
+	const sections = [];
+	const header = fileConfig ? generateFileHeader(fileConfig) : null;
+	if (header) sections.push(header);
+	const sortedPaths = sortDepthFirst(commandPaths, specifiedOrder ?? []);
+	for (const cmdPath of sortedPaths) {
+		const section = generateCommandSection(cmdPath, allCommands, render, filePath, fileMap);
+		if (section) sections.push(section);
+	}
+	return sections.join("\n");
+}
+/**
+* Build a map of command path to file path
+*/
+function buildFileMap(files, allCommands, ignores) {
+	const fileMap = {};
+	for (const [filePath, fileConfigRaw] of Object.entries(files)) {
+		const specifiedCommands = normalizeFileConfig(fileConfigRaw).commands;
+		const commandPaths = filterIgnoredCommands(expandCommandPaths(specifiedCommands, allCommands), ignores);
+		for (const cmdPath of commandPaths) fileMap[cmdPath] = filePath;
+	}
+	return fileMap;
+}
+/**
+* Execute examples for commands based on configuration
+*/
+async function executeConfiguredExamples(allCommands, examplesConfig, rootCommand) {
+	for (const [cmdPath, cmdConfig] of Object.entries(examplesConfig)) {
+		const commandInfo = allCommands.get(cmdPath);
+		if (!commandInfo?.examples?.length) continue;
+		const config = cmdConfig === true ? {} : cmdConfig;
+		const commandPath = cmdPath ? cmdPath.split(" ") : [];
+		commandInfo.exampleResults = await executeExamples(commandInfo.examples, config, rootCommand, commandPath);
+	}
+}
+/**
+* Generate documentation from command definition
+*/
+async function generateDoc(config) {
+	const { command, files, ignores = [], format = {}, formatter, examples: examplesConfig, targetCommands } = config;
+	const updateMode = isUpdateMode();
+	const allCommands = await collectAllCommands(command);
+	if (examplesConfig) await executeConfiguredExamples(allCommands, examplesConfig, command);
+	const allFilesCommands = [];
+	for (const fileConfigRaw of Object.values(files)) {
+		const fileConfig = normalizeFileConfig(fileConfigRaw);
+		allFilesCommands.push(...fileConfig.commands);
+	}
+	validateIgnoresExist(ignores, allCommands);
+	validateNoConflicts(allFilesCommands, ignores, allCommands);
+	const fileMap = buildFileMap(files, allCommands, ignores);
+	const results = [];
+	let hasError = false;
+	if (targetCommands && targetCommands.length > 0) {
+		for (const targetCommand of targetCommands) if (!findFileForCommand(targetCommand, files, allCommands, ignores)) throw new Error(`Target command "${targetCommand}" not found in any file configuration`);
+	}
+	for (const [filePath, fileConfigRaw] of Object.entries(files)) {
+		const fileConfig = normalizeFileConfig(fileConfigRaw);
+		const specifiedCommands = fileConfig.commands;
+		if (specifiedCommands.length === 0) continue;
+		const commandPaths = filterIgnoredCommands(expandCommandPaths(specifiedCommands, allCommands), ignores);
+		if (commandPaths.length === 0) continue;
+		const minDepth = Math.min(...commandPaths.map((p) => allCommands.get(p)?.depth ?? 1));
+		const adjustedHeadingLevel = Math.max(1, (format?.headingLevel ?? 1) - (minDepth - 1));
+		const fileRenderer = createCommandRenderer({
+			...format,
+			headingLevel: adjustedHeadingLevel
+		});
+		const render = fileConfig.render ?? fileRenderer;
+		if (targetCommands !== void 0 && targetCommands.length > 0) {
+			const fileTargetCommands = findTargetCommandsInFile(targetCommands, filePath, files, allCommands, ignores);
+			if (fileTargetCommands.length === 0) continue;
+			let existingContent = readFile(filePath);
+			let fileStatus = "match";
+			const diffs = [];
+			for (const targetCommand of fileTargetCommands) {
+				const rawSection = generateCommandSection(targetCommand, allCommands, render, filePath, fileMap);
+				if (!rawSection) throw new Error(`Target command "${targetCommand}" not found in commands`);
+				const header = targetCommand === "" && fileConfig ? generateFileHeader(fileConfig) : null;
+				const generatedSection = await applyFormatter(header ? `${header}\n${rawSection}` : rawSection, formatter);
+				if (!existingContent) {
+					if (updateMode) {
+						writeFile(filePath, generatedSection);
+						existingContent = generatedSection;
+						fileStatus = "created";
+					} else {
+						hasError = true;
+						fileStatus = "diff";
+						diffs.push(`File does not exist. Target command "${targetCommand}" section cannot be validated.`);
+					}
+					continue;
+				}
+				const existingSection = extractCommandSection(existingContent, targetCommand);
+				const generatedSectionOnly = extractCommandSection(generatedSection, targetCommand);
+				if (!generatedSectionOnly) throw new Error(`Generated content does not contain section for command "${targetCommand}"`);
+				if (!existingSection) {
+					if (updateMode) {
+						existingContent = insertCommandSection(existingContent, targetCommand, generatedSectionOnly, specifiedCommands);
+						writeFile(filePath, existingContent);
+						if (fileStatus !== "created") fileStatus = "updated";
+					} else {
+						hasError = true;
+						fileStatus = "diff";
+						diffs.push(`Existing file does not contain section for command "${targetCommand}"`);
+					}
+					continue;
+				}
+				if (existingSection !== generatedSectionOnly) if (updateMode) {
+					const updatedContent = replaceCommandSection(existingContent, targetCommand, generatedSectionOnly);
+					if (updatedContent) {
+						existingContent = updatedContent;
+						writeFile(filePath, existingContent);
+						if (fileStatus !== "created") fileStatus = "updated";
+					} else throw new Error(`Failed to replace section for command "${targetCommand}"`);
+				} else {
+					hasError = true;
+					fileStatus = "diff";
+					diffs.push(formatDiff(existingSection, generatedSectionOnly));
+				}
+			}
+			results.push({
+				path: filePath,
+				status: fileStatus,
+				diff: diffs.length > 0 ? diffs.join("\n\n") : void 0
+			});
+		} else {
+			const generatedMarkdown = await applyFormatter(generateFileMarkdown(commandPaths, allCommands, render, filePath, fileMap, specifiedCommands, fileConfig), formatter);
+			const comparison = compareWithExisting(generatedMarkdown, filePath);
+			if (comparison.match) results.push({
+				path: filePath,
+				status: "match"
+			});
+			else if (updateMode) {
+				writeFile(filePath, generatedMarkdown);
+				results.push({
+					path: filePath,
+					status: comparison.fileExists ? "updated" : "created"
+				});
+			} else {
+				hasError = true;
+				results.push({
+					path: filePath,
+					status: "diff",
+					diff: comparison.diff
+				});
+			}
+		}
+	}
+	return {
+		success: !hasError,
+		files: results,
+		error: hasError ? `Documentation is out of date. Run with ${UPDATE_GOLDEN_ENV}=true to update.` : void 0
+	};
+}
+/**
+* Assert that documentation matches golden files
+* Throws an error if there are differences and update mode is not enabled
+*/
+async function assertDocMatch(config) {
+	const result = await generateDoc(config);
+	if (!result.success) {
+		const diffMessages = result.files.filter((f) => f.status === "diff").map((f) => {
+			let msg = `File: ${f.path}\n`;
+			if (f.diff) msg += f.diff;
+			return msg;
+		}).join("\n\n");
+		throw new Error(`Documentation does not match golden files.\n\n${diffMessages}\n\nRun with ${UPDATE_GOLDEN_ENV}=true to update the documentation.`);
+	}
+}
+/**
+* Initialize documentation files by deleting them
+* Only deletes when update mode is enabled (POLITTY_DOCS_UPDATE=true)
+* Use this in beforeAll to ensure skipped tests don't leave stale sections
+* @param config - Config containing files to initialize, or a single file path
+* @param fileSystem - Optional fs implementation (useful when fs is mocked)
+*/
+function initDocFile(config, fileSystem) {
+	if (!isUpdateMode()) return;
+	if (typeof config === "string") deleteFile(config, fileSystem);
+	else for (const filePath of Object.keys(config.files)) deleteFile(filePath, fileSystem);
+}
+
+//#endregion
+export { COMMAND_MARKER_PREFIX, UPDATE_GOLDEN_ENV, assertDocMatch, buildCommandInfo, collectAllCommands, commandEndMarker, commandStartMarker, compareWithExisting, createCommandRenderer, defaultRenderers, executeExamples, formatDiff, generateDoc, initDocFile, renderArgumentsList, renderArgumentsListFromArray, renderArgumentsTable, renderArgumentsTableFromArray, renderExamplesDefault, renderOptionsList, renderOptionsListFromArray, renderOptionsTable, renderOptionsTableFromArray, renderSubcommandsTable, renderSubcommandsTableFromArray, renderUsage, resolveLazyCommand, writeFile };
+//# sourceMappingURL=index.js.map