politty 0.4.15 → 0.5.0

package/dist/docs/index.cjs

@@ -1,12 +1,12 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
 const require_log_collector = require('../log-collector-Cd2_mv87.cjs');
-const require_subcommand_router = require('../subcommand-router-CqZX3orq.cjs');
+const require_schema_extractor = require('../schema-extractor-SLPgBNgZ.cjs');
 let zod = require("zod");
-let node_util = require("node:util");
 let node_fs = require("node:fs");
 node_fs = require_log_collector.__toESM(node_fs, 1);
 let node_path = require("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,15 +306,13 @@ 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
@@ -318,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");
 }
@@ -399,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");
 }
@@ -650,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" })
 };
 
@@ -756,12 +792,12 @@ function deleteFile(filePath, fileSystem = node_fs) {
 * Build CommandInfo from a command
 */
 async function buildCommandInfo(command, rootName, commandPath = []) {
-	const extracted = require_subcommand_router.getExtractedFields(command);
+	const extracted = require_schema_extractor.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 require_subcommand_router.resolveLazyCommand(subCmd);
+		const resolved = await require_schema_extractor.resolveLazyCommand(subCmd);
 		const fullPath = [...commandPath, name];
 		subCommands.push({
 			name,
@@ -797,7 +833,7 @@ async function collectAllCommands(command, rootName) {
 		const info = await buildCommandInfo(cmd, root, path);
 		const pathKey = path.join(" ");
 		result.set(pathKey, info);
-		if (cmd.subCommands) for (const [name, subCmd] of Object.entries(cmd.subCommands)) await traverse(await require_subcommand_router.resolveLazyCommand(subCmd), [...path, name]);
+		if (cmd.subCommands) for (const [name, subCmd] of Object.entries(cmd.subCommands)) await traverse(await require_schema_extractor.resolveLazyCommand(subCmd), [...path, name]);
 	}
 	await traverse(command, []);
 	return result;
@@ -837,7 +873,7 @@ async function executeSingleExample(example, rootCommand, commandPath) {
 	collector.start();
 	let success = true;
 	try {
-		const { runCommand } = await Promise.resolve().then(() => require("../runner-CriXJlm4.cjs")).then((n) => n.runner_exports);
+		const { runCommand } = await Promise.resolve().then(() => require("../runner-CRZ_7Y9i.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);
@@ -901,7 +937,7 @@ function parseExampleCmd(cmd) {
 * ResolvedFieldMeta format used by politty's rendering functions.
 */
 function extractArgsFields(args) {
-	return require_subcommand_router.extractFields(zod.z.object(args)).fields;
+	return require_schema_extractor.extractFields(zod.z.object(args)).fields;
 }
 /**
 * Render args definition as a markdown options table
@@ -985,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;
 			}
@@ -1008,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");
 }
@@ -1529,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_subcommand_router.extractFields(zod.z.object(argsShape)).fields.filter((field) => !field.positional);
+	return require_schema_extractor.extractFields(zod.z.object(argsShape)).fields.filter((field) => !field.positional);
 }
 /**
 * Compare option definitions for global-options compatibility.
@@ -1952,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_subcommand_router.extractFields(globalArgs).fields.filter((f) => !f.positional);
+		const optionFields = require_schema_extractor.extractFields(globalArgs).fields.filter((f) => !f.positional);
 		if (optionFields.length > 0) {
 			const globalShape = Object.fromEntries(optionFields.map((f) => [f.name, f.schema]));
 			rootDoc = {
@@ -2175,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);
@@ -2272,7 +2332,7 @@ exports.renderOptionsTableFromArray = renderOptionsTableFromArray;
 exports.renderSubcommandsTable = renderSubcommandsTable;
 exports.renderSubcommandsTableFromArray = renderSubcommandsTableFromArray;
 exports.renderUsage = renderUsage;
-exports.resolveLazyCommand = require_subcommand_router.resolveLazyCommand;
+exports.resolveLazyCommand = require_schema_extractor.resolveLazyCommand;
 exports.rootFooterEndMarker = rootFooterEndMarker;
 exports.rootFooterStartMarker = rootFooterStartMarker;
 exports.rootHeaderEndMarker = rootHeaderEndMarker;