politty 0.1.0 → 0.1.2

package/dist/docs/index.cjs

@@ -27,6 +27,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 //#endregion
 const require_schema_extractor = require('../schema-extractor-B9D3Rf22.cjs');
 const require_subcommand_router = require('../subcommand-router-Vf-0w9P4.cjs');
+let zod = require("zod");
 let node_fs = require("node:fs");
 node_fs = __toESM(node_fs);
 let node_path = require("node:path");
@@ -36,13 +37,13 @@ node_path = __toESM(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)}\``;
 }
@@ -66,7 +67,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} |`);
 	}
@@ -132,8 +133,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} |`);
@@ -167,7 +168,7 @@ function renderOptionsList(info) {
 /**
 * Generate anchor from command path
 */
-function generateAnchor(commandPath) {
+function generateAnchor$1(commandPath) {
 	return commandPath.join("-").toLowerCase();
 }
 /**
@@ -193,10 +194,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);
@@ -224,8 +225,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} |`);
@@ -257,7 +258,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} |`);
 	}
@@ -288,10 +289,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);
@@ -380,8 +381,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,
@@ -396,11 +397,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,
@@ -419,8 +420,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,
@@ -437,8 +438,8 @@ 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, opts);
+				return withHeading ? `**Examples**\n\n${content}` : content;
 			};
 			const context = {
 				examples: info.examples,
@@ -671,7 +672,7 @@ async function executeSingleExample(example, rootCommand, commandPath) {
 	collector.start();
 	let success = true;
 	try {
-		const { runCommand } = await Promise.resolve().then(() => require("../runner-pmoTWUXY.cjs"));
+		const { runCommand } = await Promise.resolve().then(() => require("../runner-BkhekqT9.cjs"));
 		const result = await runCommand(rootCommand, argv);
 		success = result.success;
 		if (!result.success && result.error) console.error(result.error.message);
@@ -1206,6 +1207,225 @@ function initDocFile(config, fileSystem) {
 	else for (const filePath of Object.keys(config.files)) deleteFile(filePath, fileSystem);
 }
 
+//#endregion
+//#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 require_schema_extractor.extractFields(zod.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
 exports.COMMAND_MARKER_PREFIX = COMMAND_MARKER_PREFIX;
 exports.UPDATE_GOLDEN_ENV = UPDATE_GOLDEN_ENV;
@@ -1222,10 +1442,12 @@ exports.executeExamples = executeExamples;
 exports.formatDiff = formatDiff;
 exports.generateDoc = generateDoc;
 exports.initDocFile = initDocFile;
+exports.renderArgsTable = renderArgsTable;
 exports.renderArgumentsList = renderArgumentsList;
 exports.renderArgumentsListFromArray = renderArgumentsListFromArray;
 exports.renderArgumentsTable = renderArgumentsTable;
 exports.renderArgumentsTableFromArray = renderArgumentsTableFromArray;
+exports.renderCommandIndex = renderCommandIndex;
 exports.renderExamplesDefault = renderExamplesDefault;
 exports.renderOptionsList = renderOptionsList;
 exports.renderOptionsListFromArray = renderOptionsListFromArray;