politty 0.2.2 → 0.3.1

package/dist/docs/index.cjs

@@ -42,6 +42,7 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 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_util = require("node:util");
 let node_fs = require("node:fs");
 node_fs = __toESM(node_fs);
 let node_path = require("node:path");
@@ -749,6 +750,232 @@ function parseExampleCmd(cmd) {
 	return args;
 }
 
+//#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 "required":
+			headerCells.push("Required");
+			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 "required":
+				cells.push(opt.required ? "Yes" : "No");
+				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
 //#region src/docs/types.ts
 /**
@@ -772,6 +999,40 @@ function commandStartMarker(commandPath) {
 function commandEndMarker(commandPath) {
 	return `<!-- ${COMMAND_MARKER_PREFIX}:${commandPath}:end -->`;
 }
+/**
+* Marker prefix for global options sections in generated documentation
+* Format: <!-- politty:global-options:start --> ... <!-- politty:global-options:end -->
+*/
+const GLOBAL_OPTIONS_MARKER_PREFIX = "politty:global-options";
+/**
+* Generate start marker for a global options section
+*/
+function globalOptionsStartMarker() {
+	return `<!-- ${GLOBAL_OPTIONS_MARKER_PREFIX}:start -->`;
+}
+/**
+* Generate end marker for a global options section
+*/
+function globalOptionsEndMarker() {
+	return `<!-- ${GLOBAL_OPTIONS_MARKER_PREFIX}:end -->`;
+}
+/**
+* Marker prefix for index sections in generated documentation
+* Format: <!-- politty:index:start --> ... <!-- politty:index:end -->
+*/
+const INDEX_MARKER_PREFIX = "politty:index";
+/**
+* Generate start marker for an index section
+*/
+function indexStartMarker() {
+	return `<!-- ${INDEX_MARKER_PREFIX}:start -->`;
+}
+/**
+* Generate end marker for an index section
+*/
+function indexEndMarker() {
+	return `<!-- ${INDEX_MARKER_PREFIX}:end -->`;
+}
 
 //#endregion
 //#region src/docs/golden-test.ts
@@ -781,7 +1042,9 @@ function commandEndMarker(commandPath) {
 */
 async function applyFormatter(content, formatter) {
 	if (!formatter) return content;
-	return await formatter(content);
+	const formatted = await formatter(content);
+	if (!content.endsWith("\n") && formatted.endsWith("\n")) return formatted.slice(0, -1);
+	return formatted;
 }
 /**
 * Check if update mode is enabled via environment variable
@@ -795,6 +1058,7 @@ function isUpdateMode() {
 */
 function normalizeFileConfig(config) {
 	if (Array.isArray(config)) return { commands: config };
+	if (!("commands" in config) || !Array.isArray(config.commands)) throw new Error("Invalid file config: object form must include a \"commands\" array. Use [] to skip generation intentionally.");
 	return config;
 }
 /**
@@ -881,6 +1145,31 @@ function filterIgnoredCommands(commandPaths, ignores) {
 	});
 }
 /**
+* Resolve wildcards to direct matches without subcommand expansion.
+* Returns the "top-level" commands for use in CommandCategory.commands,
+* where expandCommands in render-index handles subcommand expansion.
+*/
+function resolveTopLevelCommands(specifiedCommands, allCommands) {
+	const result = [];
+	for (const cmdPath of specifiedCommands) if (containsWildcard(cmdPath)) result.push(...expandWildcardPattern(cmdPath, allCommands));
+	else if (allCommands.has(cmdPath)) result.push(cmdPath);
+	return result;
+}
+/**
+* Resolve file command configuration to concrete command paths.
+* This applies wildcard/subcommand expansion and ignore filtering.
+*/
+function resolveConfiguredCommandPaths(fileConfigRaw, allCommands, ignores) {
+	const fileConfig = normalizeFileConfig(fileConfigRaw);
+	const specifiedCommands = fileConfig.commands;
+	return {
+		fileConfig,
+		specifiedCommands,
+		commandPaths: filterIgnoredCommands(expandCommandPaths(specifiedCommands, allCommands), ignores),
+		topLevelCommands: filterIgnoredCommands(resolveTopLevelCommands(specifiedCommands, allCommands), ignores)
+	};
+}
+/**
 * Validate that there are no conflicts between files and ignores (with wildcard support)
 */
 function validateNoConflicts(filesCommands, ignores, allCommands) {
@@ -928,13 +1217,13 @@ function sortDepthFirst(commandPaths, specifiedOrder) {
 	for (const path of commandPaths) if (!visited.has(path)) result.push(path);
 	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.title) {
+		const heading = "#".repeat(fileConfig.headingLevel ?? 1);
+		parts.push(`${heading} ${fileConfig.title}`);
+	}
 	if (fileConfig.description) {
 		parts.push("");
 		parts.push(fileConfig.description);
@@ -943,6 +1232,51 @@ function generateFileHeader(fileConfig) {
 	return parts.join("\n");
 }
 /**
+* Extract a leading file header (title and optional description paragraph)
+*/
+function extractFileHeader(content) {
+	if (!/^#{1,6} /.test(content)) return null;
+	const titleEnd = content.indexOf("\n");
+	if (titleEnd === -1) return content;
+	let cursor = titleEnd + 1;
+	if (content[cursor] === "\n") cursor += 1;
+	while (cursor < content.length) {
+		const lineEnd = content.indexOf("\n", cursor);
+		const line = lineEnd === -1 ? content.slice(cursor) : content.slice(cursor, lineEnd);
+		if (line.length === 0 || /^#{1,6}\s/.test(line) || line.startsWith("<!-- politty:")) break;
+		cursor = lineEnd === -1 ? content.length : lineEnd + 1;
+	}
+	return content.slice(0, cursor);
+}
+/**
+* Validate and optionally update configured file header
+*/
+function processFileHeader(existingContent, fileConfig, updateMode) {
+	const generatedHeader = generateFileHeader(fileConfig);
+	if (!generatedHeader) return {
+		content: existingContent,
+		hasError: false,
+		wasUpdated: false
+	};
+	if (existingContent.startsWith(generatedHeader)) return {
+		content: existingContent,
+		hasError: false,
+		wasUpdated: false
+	};
+	const existingHeader = extractFileHeader(existingContent) ?? "";
+	if (!updateMode) return {
+		content: existingContent,
+		diff: formatDiff(existingHeader, generatedHeader),
+		hasError: true,
+		wasUpdated: false
+	};
+	return {
+		content: `${generatedHeader}${(existingHeader ? existingContent.slice(existingHeader.length) : existingContent).replace(/^\n+/, "")}`,
+		hasError: false,
+		wasUpdated: true
+	};
+}
+/**
 * Extract a command section from content using markers
 * Returns the content between start and end markers (including markers)
 */
@@ -956,6 +1290,18 @@ function extractCommandSection(content, commandPath) {
 	return content.slice(startIndex, endIndex + endMarker.length);
 }
 /**
+* Collect command paths from command start markers in content.
+*/
+function collectCommandMarkerPaths(content) {
+	const markerPattern = /<!--\s*politty:command:(.*?):start\s*-->/g;
+	const paths = [];
+	for (const match of content.matchAll(markerPattern)) paths.push(match[1] ?? "");
+	return paths;
+}
+function formatCommandPath(commandPath) {
+	return commandPath === "" ? "<root>" : commandPath;
+}
+/**
 * Replace a command section in content using markers
 * Returns the updated content with the new section
 */
@@ -987,25 +1333,291 @@ function insertCommandSection(content, commandPath, newSection, specifiedOrder)
 			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);
+	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";
+}
+/**
+* Extract a marker section from content
+* Returns the content between start and end markers (including markers)
+*/
+function extractMarkerSection(content, startMarker, endMarker) {
+	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 marker section in content
+* Returns the updated content with the new section
+*/
+function replaceMarkerSection(content, startMarker, endMarker, newSection) {
+	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);
+}
+/**
+* Check if config is the { args, options? } shape (not shorthand ArgsShape)
+*
+* Distinguishes between:
+* - { args: ArgsShape, options?: ArgsTableOptions } → returns true
+* - ArgsShape (e.g., { verbose: ZodType, args: ZodType }) → returns false
+*
+* The key insight is that in the { args, options? } shape, config.args is an ArgsShape
+* (Record of ZodTypes), while in shorthand, config itself is the ArgsShape and config.args
+* would be a single ZodType if user has an option named "args".
+*/
+function isGlobalOptionsConfigWithOptions(config) {
+	if (typeof config !== "object" || config === null || !("args" in config)) return false;
+	return !(config.args instanceof zod.z.ZodType);
+}
+/**
+* Collect option fields that are actually rendered by global options markers.
+* Positional args are not rendered in args tables, so they must not be excluded.
+*/
+function collectRenderableGlobalOptionFields(argsShape) {
+	return require_schema_extractor.extractFields(zod.z.object(argsShape)).fields.filter((field) => !field.positional);
+}
+/**
+* Compare option definitions for global-options compatibility.
+*/
+function areGlobalOptionsEquivalent(a, b) {
+	const { schema: _aSchema, ...aRest } = a;
+	const { schema: _bSchema, ...bRest } = b;
+	return (0, node_util.isDeepStrictEqual)(aRest, bRest);
+}
+/**
+* Normalize rootDoc.globalOptions to { args, options? } form.
+*/
+function normalizeGlobalOptions(config) {
+	if (!config) return void 0;
+	return isGlobalOptionsConfigWithOptions(config) ? config : { args: config };
+}
+/**
+* Collect global option definitions from rootDoc.
+* Global options are intentionally applied to all generated command sections.
+*/
+function collectGlobalOptionDefinitions(rootDoc) {
+	const globalOptions = /* @__PURE__ */ new Map();
+	if (!rootDoc?.globalOptions) return globalOptions;
+	const normalized = normalizeGlobalOptions(rootDoc.globalOptions);
+	if (!normalized) return globalOptions;
+	for (const field of collectRenderableGlobalOptionFields(normalized.args)) globalOptions.set(field.name, field);
+	return globalOptions;
+}
+/**
+* Derive CommandCategory[] from files mapping.
+* Category title/description come from the first command in each file entry.
+*/
+function deriveIndexFromFiles(files, rootDocPath, allCommands, ignores) {
+	const categories = [];
+	for (const [filePath, fileConfigRaw] of Object.entries(files)) {
+		const { commandPaths, topLevelCommands } = resolveConfiguredCommandPaths(fileConfigRaw, allCommands, ignores);
+		if (commandPaths.length === 0) continue;
+		const docPath = "./" + node_path.relative(node_path.dirname(rootDocPath), filePath).replace(/\\/g, "/");
+		const firstCmdPath = commandPaths[0];
+		const cmdInfo = firstCmdPath !== void 0 ? allCommands.get(firstCmdPath) : void 0;
+		categories.push({
+			title: cmdInfo?.name ?? node_path.basename(filePath, node_path.extname(filePath)),
+			description: cmdInfo?.description ?? "",
+			commands: topLevelCommands,
+			docPath
+		});
+	}
+	return categories;
+}
+/**
+* Collect command paths that are actually documented in configured files.
+*/
+function collectDocumentedCommandPaths(files, allCommands, ignores) {
+	const documentedCommandPaths = /* @__PURE__ */ new Set();
+	for (const fileConfigRaw of Object.values(files)) {
+		const { commandPaths } = resolveConfiguredCommandPaths(fileConfigRaw, allCommands, ignores);
+		for (const commandPath of commandPaths) documentedCommandPaths.add(commandPath);
+	}
+	return documentedCommandPaths;
+}
+/**
+* Collect command paths that are targeted in configured files.
+*/
+function collectTargetDocumentedCommandPaths(targetCommands, files, allCommands, ignores) {
+	const documentedTargetCommandPaths = /* @__PURE__ */ new Set();
+	for (const filePath of Object.keys(files)) {
+		const targetCommandsInFile = findTargetCommandsInFile(targetCommands, filePath, files, allCommands, ignores);
+		for (const commandPath of targetCommandsInFile) documentedTargetCommandPaths.add(commandPath);
+	}
+	return documentedTargetCommandPaths;
+}
+/**
+* Validate that excluded command options match globalOptions definitions.
+*/
+function validateGlobalOptionCompatibility(documentedCommandPaths, allCommands, globalOptions) {
+	if (globalOptions.size === 0) return;
+	const conflicts = [];
+	for (const commandPath of documentedCommandPaths) {
+		const info = allCommands.get(commandPath);
+		if (!info) continue;
+		for (const option of info.options) {
+			const globalOption = globalOptions.get(option.name);
+			if (!globalOption) continue;
+			if (!areGlobalOptionsEquivalent(globalOption, option)) conflicts.push(`Command "${formatCommandPath(commandPath)}" option "--${option.cliName}" does not match globalOptions definition for "${option.name}".`);
+		}
+	}
+	if (conflicts.length > 0) throw new Error(`Invalid globalOptions configuration:\n  - ${conflicts.join("\n  - ")}`);
+}
+/**
+* Generate global options section content with markers
+*/
+function generateGlobalOptionsSection(config) {
+	const startMarker = globalOptionsStartMarker();
+	const endMarker = globalOptionsEndMarker();
+	return [
+		startMarker,
+		renderArgsTable(config.args, config.options),
+		endMarker
+	].join("\n");
+}
+/**
+* Generate index section content with markers
+*/
+async function generateIndexSection(categories, command, options) {
+	const startMarker = indexStartMarker();
+	const endMarker = indexEndMarker();
+	return [
+		startMarker,
+		await renderCommandIndex(command, categories, options),
+		endMarker
+	].join("\n");
+}
+/**
+* Normalize a doc file path for equivalence checks.
+*/
+function normalizeDocPathForComparison(filePath) {
+	return node_path.resolve(filePath);
+}
+/**
+* Process global options marker in file content
+* Returns result with updated content and any diffs
+*/
+async function processGlobalOptionsMarker(existingContent, globalOptionsConfig, updateMode, formatter) {
+	let content = existingContent;
+	const diffs = [];
+	let hasError = false;
+	let wasUpdated = false;
+	const startMarker = globalOptionsStartMarker();
+	const endMarker = globalOptionsEndMarker();
+	const generatedSection = await applyFormatter(generateGlobalOptionsSection(globalOptionsConfig), formatter);
+	const existingSection = extractMarkerSection(content, startMarker, endMarker);
+	if (!existingSection) {
+		hasError = true;
+		diffs.push(`Global options marker not found in file. Expected markers:\n${startMarker}\n...\n${endMarker}`);
+		return {
+			content,
+			diffs,
+			hasError,
+			wasUpdated
+		};
+	}
+	if (existingSection !== generatedSection) if (updateMode) {
+		const updated = replaceMarkerSection(content, startMarker, endMarker, generatedSection);
+		if (updated) {
+			content = updated;
+			wasUpdated = true;
+		} else {
+			hasError = true;
+			diffs.push("Failed to replace global options section");
+		}
+	} else {
+		hasError = true;
+		diffs.push(formatDiff(existingSection, generatedSection));
+	}
+	return {
+		content,
+		diffs,
+		hasError,
+		wasUpdated
+	};
+}
+/**
+* Process index marker in file content
+* Returns result with updated content and any diffs.
+* If the marker is not present in the file, the section is silently skipped.
+*/
+async function processIndexMarker(existingContent, categories, command, updateMode, formatter, indexOptions) {
+	let content = existingContent;
+	const diffs = [];
+	let hasError = false;
+	let wasUpdated = false;
+	const startMarker = indexStartMarker();
+	const endMarker = indexEndMarker();
+	const hasStartMarker = content.includes(startMarker);
+	const hasEndMarker = content.includes(endMarker);
+	if (!hasStartMarker && !hasEndMarker) return {
+		content,
+		diffs,
+		hasError,
+		wasUpdated
+	};
+	if (!hasStartMarker || !hasEndMarker) {
+		hasError = true;
+		diffs.push("Index marker section is malformed: both start and end markers are required.");
+		return {
+			content,
+			diffs,
+			hasError,
+			wasUpdated
+		};
+	}
+	const existingSection = extractMarkerSection(content, startMarker, endMarker);
+	if (!existingSection) {
+		hasError = true;
+		diffs.push("Index marker section is malformed: start marker must appear before end marker.");
+		return {
+			content,
+			diffs,
+			hasError,
+			wasUpdated
+		};
+	}
+	const generatedSection = await applyFormatter(await generateIndexSection(categories, command, indexOptions), formatter);
+	if (existingSection !== generatedSection) if (updateMode) {
+		const updated = replaceMarkerSection(content, startMarker, endMarker, generatedSection);
+		if (updated) {
+			content = updated;
+			wasUpdated = true;
+		} else {
+			hasError = true;
+			diffs.push("Failed to replace index section");
 		}
+	} else {
+		hasError = true;
+		diffs.push(formatDiff(existingSection, generatedSection));
 	}
-	return content.trimEnd() + "\n" + newSection + "\n";
+	return {
+		content,
+		diffs,
+		hasError,
+		wasUpdated
+	};
 }
 /**
 * 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;
+		const { commandPaths } = resolveConfiguredCommandPaths(fileConfigRaw, allCommands, ignores);
+		if (commandPaths.includes(commandPath)) return filePath;
 	}
 	return null;
 }
@@ -1016,8 +1628,7 @@ function findFileForCommand(commandPath, files, allCommands, ignores) {
 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 { specifiedCommands, commandPaths } = resolveConfiguredCommandPaths(fileConfigRaw, allCommands, ignores);
 	const expandedTargets = /* @__PURE__ */ new Set();
 	for (const targetCmd of targetCommands) {
 		if (!commandPaths.includes(targetCmd)) continue;
@@ -1056,7 +1667,7 @@ function generateFileMarkdown(commandPaths, allCommands, render, filePath, fileM
 		const section = generateCommandSection(cmdPath, allCommands, render, filePath, fileMap);
 		if (section) sections.push(section);
 	}
-	return sections.join("\n");
+	return `${sections.join("\n")}\n`;
 }
 /**
 * Build a map of command path to file path
@@ -1064,8 +1675,7 @@ function generateFileMarkdown(commandPaths, allCommands, render, filePath, fileM
 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);
+		const { commandPaths } = resolveConfiguredCommandPaths(fileConfigRaw, allCommands, ignores);
 		for (const cmdPath of commandPaths) fileMap[cmdPath] = filePath;
 	}
 	return fileMap;
@@ -1086,10 +1696,21 @@ async function executeConfiguredExamples(allCommands, examplesConfig, rootComman
 * Generate documentation from command definition
 */
 async function generateDoc(config) {
-	const { command, files, ignores = [], format = {}, formatter, examples: examplesConfig, targetCommands } = config;
+	const { command, rootDoc, files, ignores = [], format = {}, formatter, examples: examplesConfig, targetCommands } = config;
 	const updateMode = isUpdateMode();
+	if (rootDoc) {
+		const normalizedRootDocPath = normalizeDocPathForComparison(rootDoc.path);
+		if (Object.keys(files).some((filePath) => normalizeDocPathForComparison(filePath) === normalizedRootDocPath)) throw new Error(`rootDoc.path "${rootDoc.path}" must not also appear as a key in files.`);
+	}
 	const allCommands = await collectAllCommands(command);
 	if (examplesConfig) await executeConfiguredExamples(allCommands, examplesConfig, command);
+	const hasTargetCommands = targetCommands !== void 0 && targetCommands.length > 0;
+	if (hasTargetCommands) {
+		for (const targetCommand of targetCommands) if (!findFileForCommand(targetCommand, files, allCommands, ignores)) throw new Error(`Target command "${targetCommand}" not found in any file configuration`);
+	}
+	const globalOptionDefinitions = collectGlobalOptionDefinitions(rootDoc);
+	validateGlobalOptionCompatibility(hasTargetCommands ? collectTargetDocumentedCommandPaths(targetCommands, files, allCommands, ignores) : collectDocumentedCommandPaths(files, allCommands, ignores), allCommands, globalOptionDefinitions);
+	if (globalOptionDefinitions.size > 0) for (const info of allCommands.values()) info.options = info.options.filter((opt) => !globalOptionDefinitions.has(opt.name));
 	const allFilesCommands = [];
 	for (const fileConfigRaw of Object.values(files)) {
 		const fileConfig = normalizeFileConfig(fileConfigRaw);
@@ -1100,15 +1721,14 @@ async function generateDoc(config) {
 	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;
+		const { fileConfig, specifiedCommands, commandPaths } = resolveConfiguredCommandPaths(fileConfigRaw, allCommands, ignores);
 		if (specifiedCommands.length === 0) continue;
-		const commandPaths = filterIgnoredCommands(expandCommandPaths(specifiedCommands, allCommands), ignores);
 		if (commandPaths.length === 0) continue;
+		const fileTargetCommands = hasTargetCommands ? findTargetCommandsInFile(targetCommands, filePath, files, allCommands, ignores) : [];
+		if (hasTargetCommands && fileTargetCommands.length === 0) continue;
+		let fileStatus = "match";
+		const diffs = [];
 		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({
@@ -1116,12 +1736,8 @@ async function generateDoc(config) {
 			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;
+		if (hasTargetCommands) {
 			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`);
@@ -1167,33 +1783,75 @@ async function generateDoc(config) {
 					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) {
+			if (comparison.match) {} else if (updateMode) {
 				writeFile(filePath, generatedMarkdown);
-				results.push({
-					path: filePath,
-					status: comparison.fileExists ? "updated" : "created"
-				});
+				fileStatus = comparison.fileExists ? "updated" : "created";
 			} else {
 				hasError = true;
-				results.push({
-					path: filePath,
-					status: "diff",
-					diff: comparison.diff
-				});
+				fileStatus = "diff";
+				if (comparison.diff) diffs.push(comparison.diff);
+			}
+		}
+		if (diffs.length > 0) fileStatus = "diff";
+		results.push({
+			path: filePath,
+			status: fileStatus,
+			diff: diffs.length > 0 ? diffs.join("\n\n") : void 0
+		});
+	}
+	if (rootDoc) {
+		const rootDocFilePath = rootDoc.path;
+		let rootDocStatus = "match";
+		const rootDocDiffs = [];
+		const existingContent = readFile(rootDocFilePath);
+		if (existingContent === null) {
+			hasError = true;
+			rootDocStatus = "diff";
+			rootDocDiffs.push("File does not exist. Cannot validate rootDoc markers.");
+		} else {
+			let content = existingContent;
+			let markerUpdated = false;
+			const rootDocFileConfig = { title: command.name };
+			if (rootDoc.headingLevel !== void 0) rootDocFileConfig.headingLevel = rootDoc.headingLevel;
+			if (command.description !== void 0) rootDocFileConfig.description = command.description;
+			const headerResult = processFileHeader(content, rootDocFileConfig, updateMode);
+			content = headerResult.content;
+			if (headerResult.diff) rootDocDiffs.push(headerResult.diff);
+			if (headerResult.hasError) hasError = true;
+			if (headerResult.wasUpdated) markerUpdated = true;
+			const unexpectedCommandMarkers = Array.from(new Set(collectCommandMarkerPaths(content)));
+			if (unexpectedCommandMarkers.length > 0) {
+				hasError = true;
+				rootDocDiffs.push(`Found unexpected command marker sections in rootDoc: ${unexpectedCommandMarkers.map((commandPath) => `"${formatCommandPath(commandPath)}"`).join(", ")}.`);
+			}
+			const normalizedGlobalOptions = normalizeGlobalOptions(rootDoc.globalOptions);
+			if (normalizedGlobalOptions) {
+				const globalOptionsResult = await processGlobalOptionsMarker(content, normalizedGlobalOptions, updateMode, formatter);
+				content = globalOptionsResult.content;
+				rootDocDiffs.push(...globalOptionsResult.diffs);
+				if (globalOptionsResult.hasError) hasError = true;
+				if (globalOptionsResult.wasUpdated) markerUpdated = true;
+			}
+			const derivedCategories = deriveIndexFromFiles(files, rootDocFilePath, allCommands, ignores);
+			const indexResult = await processIndexMarker(content, derivedCategories, command, updateMode, formatter, rootDoc.index);
+			content = indexResult.content;
+			rootDocDiffs.push(...indexResult.diffs);
+			if (indexResult.hasError) hasError = true;
+			if (indexResult.wasUpdated) markerUpdated = true;
+			if (updateMode && markerUpdated) {
+				writeFile(rootDocFilePath, content);
+				if (rootDocStatus === "match") rootDocStatus = "updated";
 			}
 		}
+		if (rootDocDiffs.length > 0) rootDocStatus = "diff";
+		results.push({
+			path: rootDocFilePath,
+			status: rootDocStatus,
+			diff: rootDocDiffs.length > 0 ? rootDocDiffs.join("\n\n") : void 0
+		});
 	}
 	return {
 		success: !hasError,
@@ -1229,234 +1887,10 @@ 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 "required":
-			headerCells.push("Required");
-			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 "required":
-				cells.push(opt.required ? "Yes" : "No");
-				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.GLOBAL_OPTIONS_MARKER_PREFIX = GLOBAL_OPTIONS_MARKER_PREFIX;
+exports.INDEX_MARKER_PREFIX = INDEX_MARKER_PREFIX;
 exports.UPDATE_GOLDEN_ENV = UPDATE_GOLDEN_ENV;
 exports.__exportAll = __exportAll;
 exports.__toESM = __toESM;
@@ -1471,6 +1905,10 @@ exports.defaultRenderers = defaultRenderers;
 exports.executeExamples = executeExamples;
 exports.formatDiff = formatDiff;
 exports.generateDoc = generateDoc;
+exports.globalOptionsEndMarker = globalOptionsEndMarker;
+exports.globalOptionsStartMarker = globalOptionsStartMarker;
+exports.indexEndMarker = indexEndMarker;
+exports.indexStartMarker = indexStartMarker;
 exports.initDocFile = initDocFile;
 exports.renderArgsTable = renderArgsTable;
 exports.renderArgumentsList = renderArgumentsList;