politty 0.1.1 → 0.2.0

package/dist/docs/index.js

@@ -1,5 +1,6 @@
-import { n as getExtractedFields } from "../schema-extractor-Dk5Z0Iei.js";
-import { i as createLogCollector, n as resolveLazyCommand } from "../subcommand-router-BiSvDXHg.js";
+import { n as getExtractedFields, t as extractFields } from "../schema-extractor-D0q5Fj2R.js";
+import { i as createLogCollector, n as resolveLazyCommand } from "../subcommand-router-D9QSLX56.js";
+import { z } from "zod";
 import * as fs from "node:fs";
 import * as path from "node:path";
 
@@ -7,13 +8,13 @@ import * as path from "node:path";
 /**
 * Escape markdown special characters in table cells
 */
-function escapeTableCell(str) {
+function escapeTableCell$2(str) {
 	return str.replace(/\|/g, "\\|").replace(/\n/g, " ");
 }
 /**
 * Format default value for display
 */
-function formatDefaultValue(value) {
+function formatDefaultValue$1(value) {
 	if (value === void 0) return "-";
 	return `\`${JSON.stringify(value)}\``;
 }
@@ -37,7 +38,7 @@ function renderArgumentsTable(info) {
 	lines.push("| Argument | Description | Required |");
 	lines.push("|----------|-------------|----------|");
 	for (const arg of info.positionalArgs) {
-		const desc = escapeTableCell(arg.description ?? "");
+		const desc = escapeTableCell$2(arg.description ?? "");
 		const required = arg.required ? "Yes" : "No";
 		lines.push(`| \`${arg.name}\` | ${desc} | ${required} |`);
 	}
@@ -103,8 +104,8 @@ function renderOptionsTable(info) {
 		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);
+		const desc = escapeTableCell$2(opt.description ?? "");
+		const defaultVal = formatDefaultValue$1(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} |`);
@@ -138,7 +139,7 @@ function renderOptionsList(info) {
 /**
 * Generate anchor from command path
 */
-function generateAnchor(commandPath) {
+function generateAnchor$1(commandPath) {
 	return commandPath.join("-").toLowerCase();
 }
 /**
@@ -164,10 +165,10 @@ function renderSubcommandsTable(info, generateAnchors = true) {
 	const fileMap = info.fileMap;
 	for (const sub of info.subCommands) {
 		const fullName = sub.fullPath.join(" ");
-		const desc = escapeTableCell(sub.description ?? "");
+		const desc = escapeTableCell$2(sub.description ?? "");
 		const subCommandPath = sub.fullPath.join(" ");
 		if (generateAnchors) {
-			const anchor = generateAnchor(sub.fullPath);
+			const anchor = generateAnchor$1(sub.fullPath);
 			const subFile = fileMap?.[subCommandPath];
 			if (currentFile && subFile && currentFile !== subFile) {
 				const relativePath = getRelativePath(currentFile, subFile);
@@ -195,8 +196,8 @@ function renderOptionsTableFromArray(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);
+		const desc = escapeTableCell$2(opt.description ?? "");
+		const defaultVal = formatDefaultValue$1(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} |`);
@@ -228,7 +229,7 @@ function renderArgumentsTableFromArray(args) {
 	lines.push("| Argument | Description | Required |");
 	lines.push("|----------|-------------|----------|");
 	for (const arg of args) {
-		const desc = escapeTableCell(arg.description ?? "");
+		const desc = escapeTableCell$2(arg.description ?? "");
 		const required = arg.required ? "Yes" : "No";
 		lines.push(`| \`${arg.name}\` | ${desc} | ${required} |`);
 	}
@@ -259,10 +260,10 @@ function renderSubcommandsTableFromArray(subcommands, info, generateAnchors = tr
 	const fileMap = info.fileMap;
 	for (const sub of subcommands) {
 		const fullName = sub.fullPath.join(" ");
-		const desc = escapeTableCell(sub.description ?? "");
+		const desc = escapeTableCell$2(sub.description ?? "");
 		const subCommandPath = sub.fullPath.join(" ");
 		if (generateAnchors) {
-			const anchor = generateAnchor(sub.fullPath);
+			const anchor = generateAnchor$1(sub.fullPath);
 			const subFile = fileMap?.[subCommandPath];
 			if (currentFile && subFile && currentFile !== subFile) {
 				const relativePath = getRelativePath(currentFile, subFile);
@@ -290,6 +291,7 @@ function renderSubcommandsTableFromArray(subcommands, info, generateAnchors = tr
 function renderExamplesDefault(examples, results, opts) {
 	if (examples.length === 0) return "";
 	const showOutput = opts?.showOutput ?? true;
+	const prefix = opts?.commandPrefix ? `${opts.commandPrefix} ` : "";
 	const lines = [];
 	for (let i = 0; i < examples.length; i++) {
 		const example = examples[i];
@@ -298,7 +300,7 @@ function renderExamplesDefault(examples, results, opts) {
 		lines.push(`**${example.desc}**`);
 		lines.push("");
 		lines.push("```bash");
-		lines.push(`$ ${example.cmd}`);
+		lines.push(`$ ${prefix}${example.cmd}`);
 		if (showOutput) {
 			if (result) {
 				if (result.stdout) lines.push(result.stdout);
@@ -351,8 +353,8 @@ function createCommandRenderer(options = {}) {
 			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 content = style === "table" ? renderArgumentsTableFromArray(args) : renderArgumentsListFromArray(args);
+				return withHeading ? `**Arguments**\n\n${content}` : content;
 			};
 			const context = {
 				args: info.positionalArgs,
@@ -367,11 +369,11 @@ function createCommandRenderer(options = {}) {
 			}
 		}
 		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 renderOpts = (opts, renderOpts) => {
+				const style = renderOpts?.style ?? optionStyle;
+				const withHeading = renderOpts?.withHeading ?? true;
+				const content = style === "table" ? renderOptionsTableFromArray(opts) : renderOptionsListFromArray(opts);
+				return withHeading ? `**Options**\n\n${content}` : content;
 			};
 			const context = {
 				options: info.options,
@@ -390,8 +392,8 @@ function createCommandRenderer(options = {}) {
 			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 content = renderSubcommandsTableFromArray(subs, info, anchors);
+				return withHeading ? `**Commands**\n\n${content}` : content;
 			};
 			const context = {
 				subcommands: info.subCommands,
@@ -408,8 +410,11 @@ function createCommandRenderer(options = {}) {
 		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 content = renderExamplesDefault(examples, results, {
+					commandPrefix: info.fullCommandPath,
+					...opts
+				});
+				return withHeading ? `**Examples**\n\n${content}` : content;
 			};
 			const context = {
 				examples: info.examples,
@@ -598,11 +603,11 @@ async function buildCommandInfo(command, rootName, commandPath = []) {
 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(" ");
+	async function traverse(cmd, path) {
+		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 resolveLazyCommand(subCmd), [...path$1, name]);
+		if (cmd.subCommands) for (const [name, subCmd] of Object.entries(cmd.subCommands)) await traverse(await resolveLazyCommand(subCmd), [...path, name]);
 	}
 	await traverse(command, []);
 	return result;
@@ -642,7 +647,7 @@ async function executeSingleExample(example, rootCommand, commandPath) {
 	collector.start();
 	let success = true;
 	try {
-		const { runCommand } = await import("../runner-KCql2UKz.js");
+		const { runCommand } = await import("../runner-DzzbIwEy.js");
 		const result = await runCommand(rootCommand, argv);
 		success = result.success;
 		if (!result.success && result.error) console.error(result.error.message);
@@ -770,8 +775,8 @@ function containsWildcard(pattern) {
 * matchesWildcard("config get", "config *") // true
 * matchesWildcard("greet", "*") // true
 */
-function matchesWildcard(path$1, pattern) {
-	const pathSegments = path$1 === "" ? [] : path$1.split(" ");
+function matchesWildcard(path, pattern) {
+	const pathSegments = path === "" ? [] : path.split(" ");
 	const patternSegments = pattern === "" ? [] : pattern.split(" ");
 	if (pathSegments.length !== patternSegments.length) return false;
 	for (let i = 0; i < patternSegments.length; i++) {
@@ -793,15 +798,15 @@ function expandWildcardPattern(pattern, allCommands) {
 * 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) {
+function matchesIgnorePattern(path, ignorePattern) {
 	if (containsWildcard(ignorePattern)) {
-		if (matchesWildcard(path$1, ignorePattern)) return true;
-		const pathSegments = path$1 === "" ? [] : path$1.split(" ");
+		if (matchesWildcard(path, ignorePattern)) return true;
+		const pathSegments = path === "" ? [] : path.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);
+	return isSubcommandOf(path, ignorePattern);
 }
 /**
 * Expand command paths to include all subcommands (with wildcard support)
@@ -812,11 +817,11 @@ function expandCommandPaths(commandPaths, allCommands) {
 		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);
+			for (const path of allCommands.keys()) if (isSubcommandOf(path, match)) expanded.add(path);
 		}
 	} else {
 		if (allCommands.has(cmdPath)) expanded.add(cmdPath);
-		for (const path$1 of allCommands.keys()) if (isSubcommandOf(path$1, cmdPath)) expanded.add(path$1);
+		for (const path of allCommands.keys()) if (isSubcommandOf(path, cmdPath)) expanded.add(path);
 	}
 	return Array.from(expanded);
 }
@@ -824,8 +829,8 @@ function expandCommandPaths(commandPaths, allCommands) {
 * Filter out ignored commands (with wildcard support)
 */
 function filterIgnoredCommands(commandPaths, ignores) {
-	return commandPaths.filter((path$1) => {
-		return !ignores.some((ignorePattern) => matchesIgnorePattern(path$1, ignorePattern));
+	return commandPaths.filter((path) => {
+		return !ignores.some((ignorePattern) => matchesIgnorePattern(path, ignorePattern));
 	});
 }
 /**
@@ -858,7 +863,7 @@ function validateIgnoresExist(ignores, allCommands) {
 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);
+	for (const path of commandPaths) if ((path === "" ? 0 : path.split(" ").length) === 1 && !topLevelPaths.includes(path)) topLevelPaths.push(path);
 	const result = [];
 	const visited = /* @__PURE__ */ new Set();
 	function addWithChildren(cmdPath) {
@@ -873,7 +878,7 @@ function sortDepthFirst(commandPaths, specifiedOrder) {
 		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);
+	for (const path of commandPaths) if (!visited.has(path)) result.push(path);
 	return result;
 }
 /**
@@ -1178,5 +1183,224 @@ function initDocFile(config, 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 };
+//#region src/docs/render-args.ts
+/**
+* Extract ResolvedFieldMeta array from ArgsShape
+*
+* This converts a raw args shape (like `commonArgs`) into the
+* ResolvedFieldMeta format used by politty's rendering functions.
+*/
+function extractArgsFields(args) {
+	return extractFields(z.object(args)).fields;
+}
+/**
+* Render args definition as a markdown options table
+*
+* This function takes raw args definitions (like `commonArgs`) and
+* renders them as a markdown table suitable for documentation.
+*
+* @example
+* import { renderArgsTable } from "politty/docs";
+* import { commonArgs, workspaceArgs } from "./args";
+*
+* const table = renderArgsTable({
+*   ...commonArgs,
+*   ...workspaceArgs,
+* });
+* // | Option | Alias | Description | Default |
+* // |--------|-------|-------------|---------|
+* // | `--env-file <ENV_FILE>` | `-e` | Path to environment file | - |
+* // ...
+*
+* @param args - Args shape (Record of string keys to Zod schemas with arg() metadata)
+* @param options - Rendering options
+* @returns Rendered markdown table string
+*/
+function renderArgsTable(args, options) {
+	const optionFields = extractArgsFields(args).filter((f) => !f.positional);
+	if (optionFields.length === 0) return "";
+	if (options?.columns) return renderFilteredTable(optionFields, options.columns);
+	return renderOptionsTableFromArray(optionFields);
+}
+/**
+* Escape markdown special characters in table cells
+*/
+function escapeTableCell$1(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 table with filtered columns
+*/
+function renderFilteredTable(options, columns) {
+	const lines = [];
+	const headerCells = [];
+	const separatorCells = [];
+	for (const col of columns) switch (col) {
+		case "option":
+			headerCells.push("Option");
+			separatorCells.push("------");
+			break;
+		case "alias":
+			headerCells.push("Alias");
+			separatorCells.push("-----");
+			break;
+		case "description":
+			headerCells.push("Description");
+			separatorCells.push("-----------");
+			break;
+		case "default":
+			headerCells.push("Default");
+			separatorCells.push("-------");
+			break;
+		case "env":
+			headerCells.push("Env");
+			separatorCells.push("---");
+			break;
+	}
+	lines.push(`| ${headerCells.join(" | ")} |`);
+	lines.push(`| ${separatorCells.join(" | ")} |`);
+	for (const opt of options) {
+		const cells = [];
+		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}>\``;
+				cells.push(optionName);
+				break;
+			}
+			case "alias":
+				cells.push(opt.alias ? `\`-${opt.alias}\`` : "-");
+				break;
+			case "description":
+				cells.push(escapeTableCell$1(opt.description ?? ""));
+				break;
+			case "default":
+				cells.push(formatDefaultValue(opt.defaultValue));
+				break;
+			case "env": {
+				const envNames = opt.env ? Array.isArray(opt.env) ? opt.env.map((e) => `\`${e}\``).join(", ") : `\`${opt.env}\`` : "-";
+				cells.push(envNames);
+				break;
+			}
+		}
+		lines.push(`| ${cells.join(" | ")} |`);
+	}
+	return lines.join("\n");
+}
+
+//#endregion
+//#region src/docs/render-index.ts
+/**
+* Escape markdown special characters in table cells
+*/
+function escapeTableCell(str) {
+	return str.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+/**
+* Generate anchor from command path
+*/
+function generateAnchor(commandPath) {
+	return commandPath.replace(/\s+/g, "-").toLowerCase();
+}
+/**
+* Check if a command is a leaf (has no subcommands)
+*/
+function isLeafCommand(info) {
+	return info.subCommands.length === 0;
+}
+/**
+* Expand commands to include their subcommands
+* If a command has subcommands, recursively find all commands under it
+*
+* @param commandPaths - Command paths to expand
+* @param allCommands - Map of all available commands
+* @param leafOnly - If true, only include leaf commands; if false, include all commands
+*/
+function expandCommands(commandPaths, allCommands, leafOnly) {
+	const result = [];
+	for (const cmdPath of commandPaths) {
+		const info = allCommands.get(cmdPath);
+		if (!info) continue;
+		if (isLeafCommand(info)) result.push(cmdPath);
+		else for (const [path, pathInfo] of allCommands) if (cmdPath === "" ? path.length > 0 : path.startsWith(cmdPath + " ") || path === cmdPath) {
+			if (isLeafCommand(pathInfo) || !leafOnly) result.push(path);
+		}
+	}
+	return result;
+}
+/**
+* Render a single category section
+*/
+function renderCategory(category, allCommands, headingLevel, leafOnly) {
+	const h = "#".repeat(headingLevel);
+	const lines = [];
+	lines.push(`${h} [${category.title}](${category.docPath})`);
+	lines.push("");
+	lines.push(category.description);
+	lines.push("");
+	const commandPaths = expandCommands(category.commands, allCommands, leafOnly);
+	lines.push("| Command | Description |");
+	lines.push("|---------|-------------|");
+	for (const cmdPath of commandPaths) {
+		const info = allCommands.get(cmdPath);
+		if (!info) continue;
+		if (leafOnly && !isLeafCommand(info)) continue;
+		const displayName = cmdPath || info.name;
+		const anchor = generateAnchor(displayName);
+		const desc = escapeTableCell(info.description ?? "");
+		lines.push(`| [${displayName}](${category.docPath}#${anchor}) | ${desc} |`);
+	}
+	return lines.join("\n");
+}
+/**
+* Render command index from categories
+*
+* Generates a category-based index of commands with links to documentation.
+*
+* @example
+* const categories: CommandCategory[] = [
+*   {
+*     title: "Application Commands",
+*     description: "Commands for managing applications.",
+*     commands: ["init", "generate", "apply"],
+*     docPath: "./cli/application.md",
+*   },
+* ];
+*
+* const index = await renderCommandIndex(mainCommand, categories);
+* // ### [Application Commands](./cli/application.md)
+* //
+* // Commands for managing applications.
+* //
+* // | Command | Description |
+* // |---------|-------------|
+* // | [init](./cli/application.md#init) | Initialize a project |
+* // ...
+*
+* @param command - Root command to extract command information from
+* @param categories - Category definitions for grouping commands
+* @param options - Rendering options
+* @returns Rendered markdown string
+*/
+async function renderCommandIndex(command, categories, options) {
+	const headingLevel = options?.headingLevel ?? 3;
+	const leafOnly = options?.leafOnly ?? true;
+	const allCommands = await collectAllCommands(command);
+	const sections = [];
+	for (const category of categories) {
+		const section = renderCategory(category, allCommands, headingLevel, leafOnly);
+		sections.push(section);
+	}
+	return sections.join("\n\n");
+}
+
+//#endregion
+export { COMMAND_MARKER_PREFIX, UPDATE_GOLDEN_ENV, assertDocMatch, buildCommandInfo, collectAllCommands, commandEndMarker, commandStartMarker, compareWithExisting, createCommandRenderer, defaultRenderers, executeExamples, formatDiff, generateDoc, initDocFile, renderArgsTable, renderArgumentsList, renderArgumentsListFromArray, renderArgumentsTable, renderArgumentsTableFromArray, renderCommandIndex, renderExamplesDefault, renderOptionsList, renderOptionsListFromArray, renderOptionsTable, renderOptionsTableFromArray, renderSubcommandsTable, renderSubcommandsTableFromArray, renderUsage, resolveLazyCommand, writeFile };
 //# sourceMappingURL=index.js.map