politty 0.8.0 → 0.9.0

package/dist/docs/index.d.cts

@@ -1,752 +0,0 @@
-import { C as Example, J as ResolvedFieldMeta, V as SubCommandValue, _ as AnyCommand, q as ExtractedFields, v as ArgsSchema } from "../arg-registry-DDJpsUea.cjs";
-import { z } from "zod";
-import * as fs from "node:fs";
-
-//#region 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 src/docs/render-args.d.ts
-/**
- * Args shape type (Record of string keys to Zod schemas)
- * This matches the typical structure of `commonArgs`, `workspaceArgs`, etc.
- */
-type ArgsShape = Record<string, z.ZodType>;
-/**
- * Options for rendering args table
- */
-type ArgsTableOptions = {
-  /** Columns to include in the table (default: all columns) */columns?: ("option" | "alias" | "description" | "required" | "default" | "env")[];
-};
-/**
- * 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
- */
-declare function renderArgsTable(args: ArgsShape, options?: ArgsTableOptions): string;
-//#endregion
-//#region 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 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 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 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 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 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 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 };
-//# sourceMappingURL=index.d.cts.map