politty 0.4.14 → 0.4.16

package/dist/docs/index.cjs

@@ -1,12 +1,12 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
-const require_subcommand_router = require('../subcommand-router-C9ONv6Nq.cjs');
-const require_lazy = require('../lazy-AGV9Pkt5.cjs');
+const require_log_collector = require('../log-collector-Cd2_mv87.cjs');
+const require_subcommand_router = require('../subcommand-router-DQy0KZU-.cjs');
 let zod = require("zod");
-let node_util = require("node:util");
 let node_fs = require("node:fs");
-node_fs = require_subcommand_router.__toESM(node_fs);
+node_fs = require_log_collector.__toESM(node_fs, 1);
 let node_path = require("node:path");
-node_path = require_subcommand_router.__toESM(node_path);
+node_path = require_log_collector.__toESM(node_path, 1);
+let node_util = require("node:util");
 
 //#region src/docs/types.ts
 /**
@@ -114,6 +114,13 @@ function escapeTableCell$2(str) {
 	return str.replace(/\|/g, "\\|").replace(/\n/g, " ");
 }
 /**
+* Marker appended to a custom negation row/line so readers can see which
+* positive flag it negates (e.g. `--monochrome` → `(↔ \`--color\`)`).
+*/
+function negationRelationMarker(opt) {
+	return `(↔ \`--${opt.cliName}\`)`;
+}
+/**
 * Format default value for display
 */
 function formatDefaultValue$1(value) {
@@ -174,25 +181,39 @@ function resolvePlaceholder(opt) {
 }
 /**
 * Format option name for table display (e.g., `--dry-run` or `--port <PORT>`)
+*
+* Boolean fields with a custom inline `negation` (no separate description) are
+* shown as `\`--cache\` / \`--disable-cache\``.
 */
 function formatOptionName(opt) {
 	const placeholder = resolvePlaceholder(opt);
-	return opt.type === "boolean" ? `\`--${opt.cliName}\`` : `\`--${opt.cliName} <${placeholder}>\``;
+	if (opt.type === "boolean") {
+		const positive = `\`--${opt.cliName}\``;
+		if (opt.negationDisplay && !opt.negationDescription) return `${positive} / \`--${opt.negationDisplay}\``;
+		return positive;
+	}
+	return `\`--${opt.cliName} <${placeholder}>\``;
 }
 /**
-* Format option flags for list display (uses kebab-case cliName)
+* Format option flags for list display (uses kebab-case cliName).
+* Aliases are joined with `, `; the inline negation (when no separate
+* `negationDescription` is set) is appended with ` / ` so it stays
+* visually distinct from aliases, matching help and table output.
 */
 function formatOptionFlags(opt) {
 	const placeholder = resolvePlaceholder(opt);
 	const longFlag = opt.type === "boolean" ? `--${opt.cliName}` : `--${opt.cliName} <${placeholder}>`;
-	if (!opt.alias || opt.alias.length === 0) return `\`${longFlag}\``;
-	const shortParts = opt.alias.filter((a) => a.length === 1).map((a) => `\`-${a}\``);
-	const longParts = opt.alias.filter((a) => a.length > 1).map((a) => `\`--${a}\``);
-	return [
-		...shortParts,
-		`\`${longFlag}\``,
-		...longParts
-	].join(", ");
+	const parts = [];
+	if (opt.alias) {
+		for (const a of opt.alias) if (a.length === 1) parts.push(`\`-${a}\``);
+	}
+	parts.push(`\`${longFlag}\``);
+	if (opt.alias) {
+		for (const a of opt.alias) if (a.length > 1) parts.push(`\`--${a}\``);
+	}
+	const aliasJoined = parts.join(", ");
+	if (opt.type === "boolean" && opt.negationDisplay && !opt.negationDescription) return `${aliasJoined} / \`--${opt.negationDisplay}\``;
+	return aliasJoined;
 }
 /**
 * Format aliases for a markdown table cell
@@ -244,6 +265,12 @@ function renderOptionsTable(info) {
 			const envNames = formatEnvNames(opt.env);
 			lines.push(`| ${optionName} | ${alias} | ${desc} | ${required} | ${defaultVal} | ${envNames} |`);
 		} else lines.push(`| ${optionName} | ${alias} | ${desc} | ${required} | ${defaultVal} |`);
+		if (opt.type === "boolean" && opt.negationDisplay && opt.negationDescription) {
+			const negName = `\`--${opt.negationDisplay}\``;
+			const negDesc = `${escapeTableCell$2(opt.negationDescription)} ${negationRelationMarker(opt)}`;
+			if (hasEnv) lines.push(`| ${negName} | - | ${negDesc} | ${required} | - | - |`);
+			else lines.push(`| ${negName} | - | ${negDesc} | ${required} | - |`);
+		}
 	}
 	return lines.join("\n");
 }
@@ -268,6 +295,7 @@ function renderOptionsList(info) {
 		const defaultVal = opt.defaultValue !== void 0 ? ` (default: ${JSON.stringify(opt.defaultValue)})` : "";
 		const envInfo = formatEnvInfo(opt.env);
 		lines.push(`- ${flags}${desc}${required}${defaultVal}${envInfo}`);
+		if (opt.type === "boolean" && opt.negationDisplay && opt.negationDescription) lines.push(`- \`--${opt.negationDisplay}\` - ${opt.negationDescription} ${negationRelationMarker(opt)}`);
 	}
 	return lines.join("\n");
 }
@@ -278,40 +306,19 @@ function generateAnchor$1(commandPath) {
 	return commandPath.join("-").toLowerCase();
 }
 /**
-* Generate relative path from one file to another
+* Generate relative path from one file to another.
+* Always emits forward slashes so Markdown links remain portable across OSes.
 */
 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] ?? "");
+	const fromPosix = from.replace(/\\/g, "/");
+	const toPosix = to.replace(/\\/g, "/");
+	return node_path.default.posix.relative(node_path.default.posix.dirname(fromPosix), toPosix);
 }
 /**
 * 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$2(sub.description ?? "");
-		const subCommandPath = sub.fullPath.join(" ");
-		if (generateAnchors) {
-			const anchor = generateAnchor$1(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");
+	return renderSubcommandsTableFromArray(info.subCommands, info, generateAnchors);
 }
 /**
 * Render options from array as table
@@ -337,6 +344,12 @@ function renderOptionsTableFromArray(options) {
 			const envNames = formatEnvNames(opt.env);
 			lines.push(`| ${optionName} | ${alias} | ${desc} | ${required} | ${defaultVal} | ${envNames} |`);
 		} else lines.push(`| ${optionName} | ${alias} | ${desc} | ${required} | ${defaultVal} |`);
+		if (opt.type === "boolean" && opt.negationDisplay && opt.negationDescription) {
+			const negName = `\`--${opt.negationDisplay}\``;
+			const negDesc = `${escapeTableCell$2(opt.negationDescription)} ${negationRelationMarker(opt)}`;
+			if (hasEnv) lines.push(`| ${negName} | - | ${negDesc} | ${required} | - | - |`);
+			else lines.push(`| ${negName} | - | ${negDesc} | ${required} | - |`);
+		}
 	}
 	return lines.join("\n");
 }
@@ -418,6 +431,7 @@ function renderOptionsListFromArray(options) {
 		const defaultVal = opt.defaultValue !== void 0 ? ` (default: ${JSON.stringify(opt.defaultValue)})` : "";
 		const envInfo = formatEnvInfo(opt.env);
 		lines.push(`- ${flags}${desc}${required}${defaultVal}${envInfo}`);
+		if (opt.type === "boolean" && opt.negationDisplay && opt.negationDescription) lines.push(`- \`--${opt.negationDisplay}\` - ${opt.negationDescription} ${negationRelationMarker(opt)}`);
 	}
 	return lines.join("\n");
 }
@@ -454,23 +468,31 @@ function renderArgumentsListFromArray(args) {
 */
 function renderSubcommandsTableFromArray(subcommands, info, generateAnchors = true) {
 	if (subcommands.length === 0) return "";
+	const hasAliases = subcommands.some((s) => s.aliases && s.aliases.length > 0);
 	const lines = [];
-	lines.push("| Command | Description |");
-	lines.push("|---------|-------------|");
+	if (hasAliases) {
+		lines.push("| Command | Aliases | Description |");
+		lines.push("|---------|---------|-------------|");
+	} else {
+		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$2(sub.description ?? "");
 		const subCommandPath = sub.fullPath.join(" ");
+		const aliasCell = hasAliases ? sub.aliases && sub.aliases.length > 0 ? sub.aliases.map((a) => `\`${escapeTableCell$2(a)}\``).join(", ") : "-" : "";
+		let cmdCell;
 		if (generateAnchors) {
 			const anchor = generateAnchor$1(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} |`);
+			if (currentFile && subFile && currentFile !== subFile) cmdCell = `[\`${fullName}\`](${getRelativePath(currentFile, subFile)}#${anchor})`;
+			else cmdCell = `[\`${fullName}\`](#${anchor})`;
+		} else cmdCell = `\`${fullName}\``;
+		if (hasAliases) lines.push(`| ${cmdCell} | ${aliasCell} | ${desc} |`);
+		else lines.push(`| ${cmdCell} | ${desc} |`);
 	}
 	return lines.join("\n");
 }
@@ -537,14 +559,19 @@ function createCommandRenderer(options = {}) {
 		const h = "#".repeat(effectiveLevel);
 		const title = info.commandPath || info.name;
 		sections.push(wrapWithMarker("heading", scope, `${h} ${title}`));
-		if (info.description) {
-			const context = {
-				content: info.description,
-				heading: "",
-				info
-			};
-			const content = customRenderDescription ? customRenderDescription(context) : context.content;
-			if (content) sections.push(wrapWithMarker("description", scope, content));
+		{
+			const parts = [];
+			if (info.description) parts.push(info.description);
+			if (info.aliases && info.aliases.length > 0) parts.push(`**Aliases:** ${info.aliases.map((a) => `\`${a}\``).join(", ")}`);
+			if (parts.length > 0) {
+				const context = {
+					content: parts.join("\n\n"),
+					heading: "",
+					info
+				};
+				const content = customRenderDescription ? customRenderDescription(context) : context.content;
+				if (content) sections.push(wrapWithMarker("description", scope, content));
+			}
 		}
 		{
 			const context = {
@@ -656,8 +683,11 @@ function createCommandRenderer(options = {}) {
 * Default renderers presets
 */
 const defaultRenderers = {
+	/** Standard command documentation */
 	command: (options) => createCommandRenderer(options),
+	/** Table style options (default) */
 	tableStyle: createCommandRenderer({ optionStyle: "table" }),
+	/** List style options */
 	listStyle: createCommandRenderer({ optionStyle: "list" })
 };
 
@@ -762,7 +792,7 @@ function deleteFile(filePath, fileSystem = node_fs) {
 * Build CommandInfo from a command
 */
 async function buildCommandInfo(command, rootName, commandPath = []) {
-	const extracted = require_lazy.getExtractedFields(command);
+	const extracted = require_subcommand_router.getExtractedFields(command);
 	const positionalArgs = extracted?.fields.filter((f) => f.positional) ?? [];
 	const options = extracted?.fields.filter((f) => !f.positional) ?? [];
 	const subCommands = [];
@@ -772,12 +802,14 @@ async function buildCommandInfo(command, rootName, commandPath = []) {
 		subCommands.push({
 			name,
 			description: resolved.description,
+			aliases: resolved.aliases,
 			fullPath
 		});
 	}
 	return {
 		name: command.name ?? "",
 		description: command.description,
+		aliases: command.aliases,
 		fullCommandPath: commandPath.length > 0 ? `${rootName} ${commandPath.join(" ")}` : rootName,
 		commandPath: commandPath.join(" "),
 		depth: commandPath.length + 1,
@@ -837,11 +869,11 @@ async function executeExamples(examples, config, rootCommand, commandPath = [])
 async function executeSingleExample(example, rootCommand, commandPath) {
 	const exampleArgs = parseExampleCmd(example.cmd);
 	const argv = [...commandPath, ...exampleArgs];
-	const collector = require_subcommand_router.createLogCollector({ passthrough: false });
+	const collector = require_log_collector.createLogCollector({ passthrough: false });
 	collector.start();
 	let success = true;
 	try {
-		const { runCommand } = await Promise.resolve().then(() => require("../runner-CY5fOsSh.cjs")).then((n) => n.runner_exports);
+		const { runCommand } = await Promise.resolve().then(() => require("../runner-BcyR6Z8r.cjs")).then((n) => n.runner_exports);
 		const result = await runCommand(rootCommand, argv);
 		success = result.success;
 		if (!result.success && result.error) console.error(result.error.message);
@@ -905,7 +937,7 @@ function parseExampleCmd(cmd) {
 * ResolvedFieldMeta format used by politty's rendering functions.
 */
 function extractArgsFields(args) {
-	return require_lazy.extractFields(zod.z.object(args)).fields;
+	return require_subcommand_router.extractFields(zod.z.object(args)).fields;
 }
 /**
 * Render args definition as a markdown options table
@@ -989,7 +1021,11 @@ function renderFilteredTable(options, columns) {
 		for (const col of columns) switch (col) {
 			case "option": {
 				const placeholder = opt.placeholder ?? opt.cliName.toUpperCase().replace(/-/g, "_");
-				const optionName = opt.type === "boolean" ? `\`--${opt.cliName}\`` : `\`--${opt.cliName} <${placeholder}>\``;
+				let optionName;
+				if (opt.type === "boolean") {
+					optionName = `\`--${opt.cliName}\``;
+					if (opt.negationDisplay && !opt.negationDescription) optionName += ` / \`--${opt.negationDisplay}\``;
+				} else optionName = `\`--${opt.cliName} <${placeholder}>\``;
 				cells.push(optionName);
 				break;
 			}
@@ -1012,6 +1048,26 @@ function renderFilteredTable(options, columns) {
 			}
 		}
 		lines.push(`| ${cells.join(" | ")} |`);
+		if (opt.type === "boolean" && opt.negationDisplay && opt.negationDescription) {
+			const negCells = [];
+			for (const col of columns) switch (col) {
+				case "option":
+					negCells.push(`\`--${opt.negationDisplay}\``);
+					break;
+				case "description":
+					negCells.push(`${escapeTableCell$1(opt.negationDescription)} ${negationRelationMarker(opt)}`);
+					break;
+				case "required":
+					negCells.push(opt.required ? "Yes" : "No");
+					break;
+				case "alias":
+				case "default":
+				case "env":
+					negCells.push("-");
+					break;
+			}
+			lines.push(`| ${negCells.join(" | ")} |`);
+		}
 	}
 	return lines.join("\n");
 }
@@ -1533,7 +1589,7 @@ function isGlobalOptionsConfigWithOptions(config) {
 * Positional args are not rendered in args tables, so they must not be excluded.
 */
 function collectRenderableGlobalOptionFields(argsShape) {
-	return require_lazy.extractFields(zod.z.object(argsShape)).fields.filter((field) => !field.positional);
+	return require_subcommand_router.extractFields(zod.z.object(argsShape)).fields.filter((field) => !field.positional);
 }
 /**
 * Compare option definitions for global-options compatibility.
@@ -1956,7 +2012,7 @@ async function generateDoc(config) {
 	let rootDoc = config.rootDoc;
 	if (!rootDoc && usingPathConfig && (globalArgs || config.rootInfo)) rootDoc = { path: resolvedRootDocPath };
 	if (globalArgs && rootDoc && !rootDoc.globalOptions) {
-		const optionFields = require_lazy.extractFields(globalArgs).fields.filter((f) => !f.positional);
+		const optionFields = require_subcommand_router.extractFields(globalArgs).fields.filter((f) => !f.positional);
 		if (optionFields.length > 0) {
 			const globalShape = Object.fromEntries(optionFields.map((f) => [f.name, f.schema]));
 			rootDoc = {
@@ -2179,7 +2235,7 @@ async function generateDoc(config) {
 				if (globalOptionsResult.wasUpdated) markerUpdated = true;
 			}
 			const derivedCategories = deriveIndexFromFiles(files, rootDocFilePath, allCommands, ignores);
-			const indexScope = node_path.relative(process.cwd(), rootDocFilePath);
+			const indexScope = node_path.relative(process.cwd(), rootDocFilePath).replace(/\\/g, "/");
 			const indexResult = await processIndexMarker(content, derivedCategories, command, indexScope, updateMode, formatter, rootDoc.index);
 			content = indexResult.content;
 			rootDocDiffs.push(...indexResult.diffs);