@politty/zod 0.0.0

package/dist/docs.d.ts

@@ -0,0 +1,770 @@
+import { T as Example, U as SubCommandValue, X as ResolvedFieldMeta, Y as ExtractedFields, b as ArgsSchema, tt as SchemaLike, v as AnyCommand } from "./arg-registry-YaWTVu_x.js";
+import * as fs from "node:fs";
+//#region ../core/src/executor/subcommand-router.d.ts
+/**
+ * Resolve a lazy-loaded command (sync or async)
+ *
+ * @param cmd - The command or lazy loader function
+ * @returns The resolved command
+ */
+declare function resolveLazyCommand(cmd: SubCommandValue): Promise<AnyCommand>;
+//#endregion
+//#region ../core/src/docs/option-rows.d.ts
+/**
+ * Column identifiers for the options markdown table, in their canonical order.
+ */
+type ColumnId = "option" | "alias" | "description" | "required" | "default" | "env";
+//#endregion
+//#region ../core/src/docs/render-args.d.ts
+/**
+ * Args shape type (Record of string keys to field schemas of the CLI's
+ * schema library). This matches the typical structure of `commonArgs`,
+ * `workspaceArgs`, etc.
+ */
+type ArgsShape = Record<string, SchemaLike>;
+/**
+ * Options for rendering args table
+ */
+type ArgsTableOptions = {
+  /** Columns to include in the table (default: all columns) */
+  columns?: ColumnId[];
+};
+/**
+ * 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 field names to the CLI's schema-library schemas, with arg() metadata)
+ * @param options - Rendering options
+ * @returns Rendered markdown table string
+ */
+declare function renderArgsTable(args: ArgsShape, options?: ArgsTableOptions): string;
+//#endregion
+//#region ../core/src/docs/types.d.ts
+/** Heading level for markdown headings (1-6) */
+type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
+/**
+ * Options for rendering command index
+ */
+type CommandIndexOptions = {
+  /** Base heading level (default: 3, which renders as ###) */
+  headingLevel?: HeadingLevel;
+  /** Only include leaf commands (commands without subcommands). Default: true */
+  leafOnly?: boolean;
+};
+/**
+ * Command information for rendering
+ */
+interface CommandInfo {
+  /** Command name */
+  name: string;
+  /** Command description */
+  description?: string | undefined;
+  /** Alternative names (aliases) for this command */
+  aliases?: string[] | undefined;
+  /** Full command path (e.g., "my-cli config get") */
+  fullCommandPath: string;
+  /** Command path relative to root (e.g., "" for root, "config" for subcommand) */
+  commandPath: string;
+  /** Command depth (1 for root commands, 2 for subcommands, etc.) */
+  depth: number;
+  /** Positional arguments */
+  positionalArgs: ResolvedFieldMeta[];
+  /** Options (non-positional arguments) */
+  options: ResolvedFieldMeta[];
+  /** Subcommand information */
+  subCommands: SubCommandInfo[];
+  /** Extracted field information from schema */
+  extracted: ExtractedFields | null;
+  /** Original command object */
+  command: AnyCommand;
+  /** Additional notes */
+  notes?: string | undefined;
+  /** File path where this command is rendered (for cross-file links) */
+  filePath?: string | undefined;
+  /** Map of command path to file path (for cross-file links) */
+  fileMap?: Record<string, string> | undefined;
+  /** Example definitions from command */
+  examples?: Example[] | undefined;
+  /** Example execution results (populated when examples are executed) */
+  exampleResults?: ExampleExecutionResult[] | undefined;
+  /** Path to root document file (for global options link generation) */
+  rootDocPath?: string | undefined;
+  /** Whether global options exist (for global options link generation) */
+  hasGlobalOptions?: boolean;
+}
+/**
+ * Subcommand information
+ */
+interface SubCommandInfo {
+  /** Subcommand name */
+  name: string;
+  /** Subcommand description */
+  description?: string | undefined;
+  /** Alternative names (aliases) for this subcommand */
+  aliases?: string[] | undefined;
+  /** Full command path */
+  fullPath: string[];
+}
+/**
+ * Example execution result
+ */
+interface ExampleExecutionResult {
+  /** Command arguments that were executed */
+  cmd: string;
+  /** Description of the example */
+  desc: string;
+  /** Expected output (if defined in example) */
+  expectedOutput?: string | undefined;
+  /** Captured stdout */
+  stdout: string;
+  /** Captured stderr */
+  stderr: string;
+  /** Whether execution was successful */
+  success: boolean;
+}
+/**
+ * Example execution config for a specific command path
+ * If a command path is specified in ExampleConfig, its examples will be executed
+ */
+interface ExampleCommandConfig {
+  /** Mock setup before running examples */
+  mock?: () => void | Promise<void>;
+  /** Mock cleanup after running examples */
+  cleanup?: () => void | Promise<void>;
+}
+/**
+ * Example execution configuration
+ * Key is command path (e.g., "", "config", "config get")
+ * All specified command paths will have their examples executed
+ *
+ * @example
+ * // With mock setup
+ * { "": { mock: () => mockFs(), cleanup: () => restoreFs() } }
+ *
+ * // Without mock (just execute)
+ * { "user": true }
+ */
+type ExampleConfig = Record<string, ExampleCommandConfig | true>;
+/**
+ * Render function type for custom markdown generation
+ */
+type RenderFunction = (info: CommandInfo) => string;
+/**
+ * Section render function type (legacy)
+ * @param defaultContent - The default rendered content for this section
+ * @param info - Command information
+ * @returns The final content to render (return empty string to hide section)
+ * @deprecated Use context-based render functions instead
+ */
+type SectionRenderFunction = (defaultContent: string, info: CommandInfo) => string;
+/**
+ * Render options for options/arguments
+ */
+interface RenderContentOptions {
+  /** Style for rendering */
+  style?: "table" | "list";
+  /** Include heading (default: true) */
+  withHeading?: boolean;
+}
+/**
+ * Options render context
+ */
+interface OptionsRenderContext {
+  /** Options to render */
+  options: ResolvedFieldMeta[];
+  /** Render function that accepts options and optional rendering options */
+  render: (options: ResolvedFieldMeta[], opts?: RenderContentOptions) => string;
+  /** Heading prefix (e.g., "###") */
+  heading: string;
+  /** Command information */
+  info: CommandInfo;
+}
+type OptionsRenderFunction = (context: OptionsRenderContext) => string;
+/**
+ * Arguments render context
+ */
+interface ArgumentsRenderContext {
+  /** Arguments to render */
+  args: ResolvedFieldMeta[];
+  /** Render function that accepts arguments and optional rendering options */
+  render: (args: ResolvedFieldMeta[], opts?: RenderContentOptions) => string;
+  /** Heading prefix (e.g., "###") */
+  heading: string;
+  /** Command information */
+  info: CommandInfo;
+}
+type ArgumentsRenderFunction = (context: ArgumentsRenderContext) => string;
+/**
+ * Subcommands render options
+ */
+interface SubcommandsRenderOptions {
+  /** Generate anchor links */
+  generateAnchors?: boolean;
+  /** Include heading (default: true) */
+  withHeading?: boolean;
+}
+/**
+ * Subcommands render context
+ */
+interface SubcommandsRenderContext {
+  /** Subcommands to render */
+  subcommands: SubCommandInfo[];
+  /** Render function that accepts subcommands and optional rendering options */
+  render: (subcommands: SubCommandInfo[], opts?: SubcommandsRenderOptions) => string;
+  /** Heading prefix (e.g., "###") */
+  heading: string;
+  /** Command information */
+  info: CommandInfo;
+}
+type SubcommandsRenderFunction = (context: SubcommandsRenderContext) => string;
+/**
+ * Examples render options
+ */
+interface ExamplesRenderOptions {
+  /** Include heading (default: true) */
+  withHeading?: boolean;
+  /** Show execution output (default: true when results available) */
+  showOutput?: boolean;
+  /** Command prefix to prepend to example commands (e.g., "my-cli config get") */
+  commandPrefix?: string;
+}
+/**
+ * Examples render context
+ */
+interface ExamplesRenderContext {
+  /** Examples to render */
+  examples: Example[];
+  /** Execution results (if examples were executed) */
+  results?: ExampleExecutionResult[] | undefined;
+  /** Render function that accepts examples, results, and optional rendering options */
+  render: (examples: Example[], results?: ExampleExecutionResult[], opts?: ExamplesRenderOptions) => string;
+  /** Heading prefix (e.g., "###") */
+  heading: string;
+  /** Command information */
+  info: CommandInfo;
+}
+type ExamplesRenderFunction = (context: ExamplesRenderContext) => string;
+/**
+ * Simple section render context (for description, usage, notes, footer)
+ */
+interface SimpleRenderContext {
+  /** Default content */
+  content: string;
+  /** Heading prefix (e.g., "###") */
+  heading: string;
+  /** Command information */
+  info: CommandInfo;
+}
+type SimpleRenderFunction = (context: SimpleRenderContext) => string;
+/**
+ * Default renderer customization options
+ */
+interface DefaultRendererOptions {
+  /** Heading level (default: 1) */
+  headingLevel?: HeadingLevel;
+  /** Option display style */
+  optionStyle?: "table" | "list";
+  /** Generate anchor links to subcommands */
+  generateAnchors?: boolean;
+  /** Include subcommand details */
+  includeSubcommandDetails?: boolean;
+  /**
+   * Omit the `<!-- politty:...:start/end -->` section markers from the rendered
+   * output. Used by marker-free `files` generation. When markers are omitted the
+   * output can only be regenerated wholesale (sections can no longer be located
+   * and updated in place), which is exactly how marker-free `files` mode works.
+   */
+  markerless?: boolean;
+  /** Custom renderer for description section */
+  renderDescription?: SimpleRenderFunction;
+  /** Custom renderer for usage section */
+  renderUsage?: SimpleRenderFunction;
+  /** Custom renderer for arguments section */
+  renderArguments?: ArgumentsRenderFunction;
+  /** Custom renderer for options section */
+  renderOptions?: OptionsRenderFunction;
+  /** Custom renderer for subcommands section */
+  renderSubcommands?: SubcommandsRenderFunction;
+  /** Custom renderer for notes section */
+  renderNotes?: SimpleRenderFunction;
+  /** Custom renderer for footer (default content is empty) */
+  renderFooter?: SimpleRenderFunction;
+  /** Custom renderer for examples section */
+  renderExamples?: ExamplesRenderFunction;
+}
+/**
+ * Root document configuration
+ * The root document contains global options tables and command index sections.
+ */
+interface RootDocConfig {
+  /** Output file path */
+  path: string;
+  /**
+   * Global options configuration.
+   * ArgsShape directly, or { args, options } for render options.
+   */
+  globalOptions?: ArgsShape | {
+    args: ArgsShape;
+    options?: ArgsTableOptions;
+  };
+  /** Heading level for the file header (default: 1) */
+  headingLevel?: HeadingLevel;
+  /** Index section rendering options */
+  index?: CommandIndexOptions;
+}
+/**
+ * Root command customization for the root document.
+ * Controls the root document's title, description, header, and footer.
+ */
+interface RootCommandInfo {
+  /** Title (defaults to command.name) */
+  title?: string;
+  /** Description (defaults to command.description) */
+  description?: string;
+  /** Markdown placed after title/description */
+  header?: string;
+  /** Markdown placed at end of document */
+  footer?: string;
+}
+/**
+ * Path configuration for documentation output.
+ * Simpler alternative to FileMapping for common patterns.
+ *
+ * @example
+ * // All commands in one file
+ * path: "docs/CLI.md"
+ *
+ * // Split files: root + specific commands in separate files
+ * path: { root: "docs/CLI.md", commands: { "build": "docs/build.md" } }
+ */
+type PathConfig = string | {
+  root: string;
+  commands?: Record<string, string>;
+};
+/**
+ * Per-file configuration with custom renderer
+ */
+interface FileConfig {
+  /** Command paths to include in this file (e.g., ["", "user", "config get"]) */
+  commands: string[];
+  /** Custom renderer for this file (optional) */
+  render?: RenderFunction;
+  /** File title (prepended to the file content) */
+  title?: string;
+  /** File description (added after title) */
+  description?: string;
+  /** Skip subcommand expansion (commands are used as-is). @internal */
+  noExpand?: boolean;
+}
+/**
+ * File mapping configuration
+ * Key: output file path (e.g., "docs/cli.md")
+ * Value: command paths array or FileConfig object
+ *
+ * @example
+ * // Simple: single file with multiple commands
+ * { "docs/cli.md": ["", "user", "config"] }
+ *
+ * // With custom renderer
+ * { "docs/cli.md": { commands: [""], render: customRenderer } }
+ */
+type FileMapping = Record<string, string[] | FileConfig>;
+/**
+ * generateDoc configuration
+ */
+interface GenerateDocConfig {
+  /** Command to generate documentation for */
+  command: AnyCommand;
+  /**
+   * Root document configuration.
+   * The root document contains global options tables and command index sections.
+   * Title and description are derived from `command.name` and `command.description`.
+   */
+  rootDoc?: RootDocConfig;
+  /**
+   * Path configuration (simpler alternative to files).
+   * Mutually exclusive with `files`.
+   */
+  path?: PathConfig;
+  /** File output configuration (command path -> file mapping) */
+  files?: FileMapping;
+  /** Root command customization (title, description, header, footer) */
+  rootInfo?: RootCommandInfo;
+  /** Command paths to ignore (including their subcommands) */
+  ignores?: string[];
+  /** Default renderer options (used when render is not specified per file) */
+  format?: DefaultRendererOptions;
+  /** Formatter function to apply to generated content before comparison */
+  formatter?: FormatterFunction;
+  /** Example execution configuration (per command path) */
+  examples?: ExampleConfig;
+  /**
+   * Target command paths to validate (e.g., ["read", "config get"])
+   * When specified, only these commands' sections are validated.
+   * The full document structure is used to maintain cross-file links.
+   */
+  targetCommands?: string[];
+  /**
+   * Global args schema (runtime schema alternative).
+   * When provided, automatically derives `rootDoc.globalOptions` from this schema.
+   */
+  globalArgs?: ArgsSchema;
+  /**
+   * Template-based generation: output file path -> template file path.
+   * The template mixes handwritten markdown with {{politty:...}} placeholders.
+   * The output file is fully generated from the template and contains no
+   * politty markers. Can be combined with `files` or `path`.
+   */
+  templates?: Record<string, string>;
+  /**
+   * Declare that you will hand-customize the `files` output.
+   *
+   * Default `false`: the output is fully generated and regenerated wholesale on
+   * every run (with `targetCommands`, only files containing a target command are
+   * regenerated, but each such file is rebuilt in full). The output carries no
+   * `<!-- politty:...:start/end -->` markers — do not hand-edit it.
+   *
+   * Set to `true` when you want to hand-edit the output and have politty preserve
+   * your edits: generated sections are wrapped in markers and updated in place
+   * (with `targetCommands`), and handwritten content between them is kept. When a
+   * command in the generated output gains a section the file does not yet have,
+   * it is reported as a non-fatal warning (run with `POLITTY_DOCS_DOCTOR=true
+   * POLITTY_DOCS_UPDATE=true` to insert it, or leave it removed to opt that
+   * section out).
+   *
+   * This flag does not affect `path`/`rootDoc` output, which always uses markers
+   * to inject generated sections into a handwritten file, nor `templates`, which
+   * are always fully generated.
+   */
+  customizable?: boolean;
+}
+/**
+ * generateDoc result
+ */
+interface GenerateDocResult {
+  /** Whether all files matched or were updated successfully */
+  success: boolean;
+  /** File processing results */
+  files: Array<{
+    /** File path */
+    path: string;
+    /** Status of this file */
+    status: "match" | "created" | "updated" | "diff";
+    /** Diff content (only when status is "diff") */
+    diff?: string | undefined;
+  }>;
+  /** Error message (when success is false) */
+  error?: string | undefined;
+}
+/**
+ * Formatter function type
+ * Formats generated content before comparison
+ */
+type FormatterFunction = (content: string) => string | Promise<string>;
+/**
+ * Environment variable name for update mode
+ */
+declare const UPDATE_GOLDEN_ENV = "POLITTY_DOCS_UPDATE";
+/**
+ * Environment variable name for doctor mode.
+ * When enabled alone, detects and reports missing section markers (read-only).
+ * When combined with POLITTY_DOCS_UPDATE=true, auto-inserts missing markers.
+ */
+declare const DOCTOR_ENV = "POLITTY_DOCS_DOCTOR";
+/**
+ * All section types in rendering order
+ */
+declare const SECTION_TYPES: readonly ["heading", "description", "usage", "arguments", "options", "global-options-link", "subcommands", "examples", "notes"];
+/**
+ * Section types for command documentation markers
+ */
+type SectionType = (typeof SECTION_TYPES)[number];
+/**
+ * Marker prefix for command section markers in generated documentation
+ * Format: <!-- politty:command:<scope>:<type>:start --> ... <!-- politty:command:<scope>:<type>:end -->
+ */
+declare const SECTION_MARKER_PREFIX = "politty:command";
+/**
+ * Generate start marker for a command section
+ */
+declare function sectionStartMarker(type: SectionType, scope: string): string;
+/**
+ * Generate end marker for a command section
+ */
+declare function sectionEndMarker(type: SectionType, scope: string): string;
+/**
+ * Marker prefix for global options sections in generated documentation
+ * Format: <!-- politty:global-options:start --> ... <!-- politty:global-options:end -->
+ */
+declare const GLOBAL_OPTIONS_MARKER_PREFIX = "politty:global-options";
+/**
+ * Generate start marker for a global options section
+ */
+declare function globalOptionsStartMarker(): string;
+/**
+ * Generate end marker for a global options section
+ */
+declare function globalOptionsEndMarker(): string;
+/**
+ * Marker prefix for root header sections in generated documentation
+ */
+declare const ROOT_HEADER_MARKER_PREFIX = "politty:root-header";
+declare function rootHeaderStartMarker(): string;
+declare function rootHeaderEndMarker(): string;
+/**
+ * Marker prefix for root footer sections in generated documentation
+ */
+declare const ROOT_FOOTER_MARKER_PREFIX = "politty:root-footer";
+declare function rootFooterStartMarker(): string;
+declare function rootFooterEndMarker(): string;
+/**
+ * Marker prefix for index sections in generated documentation
+ * Format: <!-- politty:index:<scope>:start --> ... <!-- politty:index:<scope>:end -->
+ */
+declare const INDEX_MARKER_PREFIX = "politty:index";
+/**
+ * Generate start marker for an index section
+ */
+declare function indexStartMarker(scope: string): string;
+/**
+ * Generate end marker for an index section
+ */
+declare function indexEndMarker(scope: string): string;
+//#endregion
+//#region ../core/src/docs/default-renderers.d.ts
+/**
+ * Render usage line
+ */
+declare function renderUsage(info: CommandInfo): string;
+/**
+ * Render arguments as table
+ */
+declare function renderArgumentsTable(info: CommandInfo): string;
+/**
+ * Render arguments as list
+ */
+declare function renderArgumentsList(info: CommandInfo): string;
+/**
+ * Render options as markdown table
+ *
+ * Features:
+ * - Uses kebab-case (cliName) for option names (e.g., `--dry-run` instead of `--dryRun`)
+ * - Automatically adds Env column when any option has env configured
+ * - Displays multiple env vars as comma-separated list
+ *
+ * @example
+ * | Option | Alias | Description | Required | Default | Env |
+ * |--------|-------|-------------|----------|---------|-----|
+ * | `--dry-run` | `-d` | Dry run mode | No | `false` | - |
+ * | `--port <PORT>` | - | Server port | Yes | - | `PORT`, `SERVER_PORT` |
+ */
+declare function renderOptionsTable(info: CommandInfo): string;
+/**
+ * Render options as markdown list
+ *
+ * Features:
+ * - Uses kebab-case (cliName) for option names (e.g., `--dry-run` instead of `--dryRun`)
+ * - Appends env info at the end of each option (e.g., `[env: PORT, SERVER_PORT]`)
+ *
+ * @example
+ * - `-d`, `--dry-run` - Dry run mode (default: false)
+ * - `--port <PORT>` - Server port (required) [env: PORT, SERVER_PORT]
+ */
+declare function renderOptionsList(info: CommandInfo): string;
+/**
+ * Render subcommands as table
+ */
+declare function renderSubcommandsTable(info: CommandInfo, generateAnchors?: boolean): string;
+/**
+ * Render options from array as table
+ */
+declare function renderOptionsTableFromArray(options: ResolvedFieldMeta[]): string;
+/**
+ * Render options from array as list
+ */
+declare function renderOptionsListFromArray(options: ResolvedFieldMeta[]): string;
+/**
+ * Render arguments from array as table
+ */
+declare function renderArgumentsTableFromArray(args: ResolvedFieldMeta[]): string;
+/**
+ * Render arguments from array as list
+ */
+declare function renderArgumentsListFromArray(args: ResolvedFieldMeta[]): string;
+/**
+ * Render subcommands from array as table
+ */
+declare function renderSubcommandsTableFromArray(subcommands: SubCommandInfo[], info: CommandInfo, generateAnchors?: boolean): string;
+/**
+ * Render examples as markdown
+ *
+ * @example
+ * **Basic usage**
+ *
+ * ```bash
+ * $ greet World
+ * ```
+ *
+ * Output:
+ * ```
+ * Hello, World!
+ * ```
+ */
+declare function renderExamplesDefault(examples: Example[], results?: ExampleExecutionResult[], opts?: ExamplesRenderOptions): string;
+declare function createCommandRenderer(options?: DefaultRendererOptions): RenderFunction;
+/**
+ * Default renderers presets
+ */
+declare const defaultRenderers: {
+  /** Standard command documentation */
+  command: (options?: DefaultRendererOptions) => RenderFunction;
+  /** Table style options (default) */
+  tableStyle: RenderFunction;
+  /** List style options */
+  listStyle: RenderFunction;
+};
+//#endregion
+//#region ../core/src/docs/doc-comparator.d.ts
+/**
+ * Comparison result
+ */
+interface CompareResult {
+  /** Whether the content matches */
+  match: boolean;
+  /** Diff content (only when match is false) */
+  diff?: string;
+  /** Whether the file exists */
+  fileExists: boolean;
+}
+/**
+ * Compare generated content with existing file
+ */
+declare function compareWithExisting(generatedContent: string, filePath: string): CompareResult;
+/**
+ * Format diff between two strings in unified diff format
+ */
+declare function formatDiff(expected: string, actual: string): string;
+/**
+ * Write content to file, creating directories if needed
+ */
+declare function writeFile(filePath: string, content: string): void;
+/**
+ * Minimal fs interface for deleteFile
+ */
+interface DeleteFileFs {
+  existsSync: typeof fs.existsSync;
+  unlinkSync: typeof fs.unlinkSync;
+}
+//#endregion
+//#region ../core/src/docs/doc-generator.d.ts
+/**
+ * Build CommandInfo from a command
+ */
+declare function buildCommandInfo(command: AnyCommand, rootName: string, commandPath?: string[]): Promise<CommandInfo>;
+/**
+ * Collect all commands with their paths
+ * Returns a map of command path -> CommandInfo
+ */
+declare function collectAllCommands(command: AnyCommand, rootName?: string): Promise<Map<string, CommandInfo>>;
+//#endregion
+//#region ../core/src/docs/example-executor.d.ts
+/**
+ * Execute examples for a command and capture output
+ *
+ * @param examples - Examples to execute
+ * @param config - Execution configuration (mock setup/cleanup)
+ * @param rootCommand - Root command to execute against
+ * @param commandPath - Command path for subcommands (e.g., ["config", "get"])
+ * @returns Array of execution results with captured stdout/stderr
+ */
+declare function executeExamples(examples: Example[], config: ExampleCommandConfig, rootCommand: AnyCommand, commandPath?: string[]): Promise<ExampleExecutionResult[]>;
+//#endregion
+//#region ../core/src/docs/golden-test.d.ts
+/**
+ * Generate documentation from command definition
+ */
+declare function generateDoc(config: GenerateDocConfig): Promise<GenerateDocResult>;
+/**
+ * Assert that documentation matches golden files
+ * Throws an error if there are differences and update mode is not enabled
+ */
+declare function assertDocMatch(config: GenerateDocConfig): Promise<void>;
+/**
+ * Initialize documentation files by deleting them
+ * Only deletes when update mode is enabled (POLITTY_DOCS_UPDATE=true)
+ * Use this in beforeAll to ensure skipped tests don't leave stale sections
+ * @param config - Config containing files to initialize, or a single file path
+ * @param fileSystem - Optional fs implementation (useful when fs is mocked)
+ */
+declare function initDocFile(config: Pick<GenerateDocConfig, "files" | "templates" | "rootDoc"> | string, fileSystem?: DeleteFileFs): void;
+//#endregion
+//#region ../core/src/docs/render-index.d.ts
+/**
+ * Configuration for a command category
+ */
+type CommandCategory = {
+  /** Category title (e.g., "Application Commands") */
+  title: string;
+  /** Category description */
+  description: string;
+  /** Command paths to include (parent commands will auto-expand to leaf commands) */
+  commands: string[];
+  /** Optional post-expansion allowlist, used when a caller has already applied ignores */
+  allowedCommands?: string[];
+  /** Path to documentation file for links (e.g., "./cli/application.md") */
+  docPath: string;
+  /**
+   * When true, `commands` are used verbatim as index rows without expanding
+   * parent commands to their leaf subcommands. Used for template-derived
+   * categories where only explicitly rendered scopes have headings.
+   */
+  noExpand?: boolean;
+};
+/**
+ * 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
+ */
+declare function renderCommandIndex(command: AnyCommand, categories: CommandCategory[], options?: CommandIndexOptions): Promise<string>;
+//#endregion
+export { type ArgsShape, type ArgsTableOptions, type ArgumentsRenderContext, type ArgumentsRenderFunction, type CommandCategory, type CommandIndexOptions, type CommandInfo, DOCTOR_ENV, type DefaultRendererOptions, type DeleteFileFs, type ExampleCommandConfig, type ExampleConfig, type ExampleExecutionResult, type ExamplesRenderContext, type ExamplesRenderFunction, type ExamplesRenderOptions, type FileConfig, type FileMapping, type FormatterFunction, GLOBAL_OPTIONS_MARKER_PREFIX, type GenerateDocConfig, type GenerateDocResult, type HeadingLevel, INDEX_MARKER_PREFIX, type OptionsRenderContext, type OptionsRenderFunction, type PathConfig, ROOT_FOOTER_MARKER_PREFIX, ROOT_HEADER_MARKER_PREFIX, type RenderContentOptions, type RenderFunction, type RootCommandInfo, type RootDocConfig, SECTION_MARKER_PREFIX, SECTION_TYPES, type SectionRenderFunction, type SectionType, type SimpleRenderContext, type SimpleRenderFunction, type SubCommandInfo, type SubcommandsRenderContext, type SubcommandsRenderFunction, type SubcommandsRenderOptions, UPDATE_GOLDEN_ENV, assertDocMatch, buildCommandInfo, collectAllCommands, compareWithExisting, createCommandRenderer, defaultRenderers, executeExamples, formatDiff, generateDoc, globalOptionsEndMarker, globalOptionsStartMarker, indexEndMarker, indexStartMarker, initDocFile, renderArgsTable, renderArgumentsList, renderArgumentsListFromArray, renderArgumentsTable, renderArgumentsTableFromArray, renderCommandIndex, renderExamplesDefault, renderOptionsList, renderOptionsListFromArray, renderOptionsTable, renderOptionsTableFromArray, renderSubcommandsTable, renderSubcommandsTableFromArray, renderUsage, resolveLazyCommand, rootFooterEndMarker, rootFooterStartMarker, rootHeaderEndMarker, rootHeaderStartMarker, sectionEndMarker, sectionStartMarker, writeFile };