politty 0.7.0 → 0.9.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/dist/cli.js +1 -1
  2. package/dist/docs/index.d.ts +44 -2
  3. package/dist/docs/index.js +827 -43
  4. package/dist/index.js +1 -1
  5. package/dist/{runner-D43SkHt5.js → runner-APRZYXUS.js} +74 -3
  6. package/package.json +22 -67
  7. package/dist/arg-registry-DDJpsUea.d.cts +0 -942
  8. package/dist/arg-registry-DDJpsUea.d.cts.map +0 -1
  9. package/dist/arg-registry-DDJpsUea.d.ts.map +0 -1
  10. package/dist/augment.cjs +0 -0
  11. package/dist/augment.d.cts +0 -17
  12. package/dist/augment.d.cts.map +0 -1
  13. package/dist/augment.d.ts.map +0 -1
  14. package/dist/cli.cjs +0 -54
  15. package/dist/cli.cjs.map +0 -1
  16. package/dist/cli.d.cts +0 -1
  17. package/dist/cli.js.map +0 -1
  18. package/dist/completion/index.cjs +0 -23
  19. package/dist/completion/index.d.cts +0 -3
  20. package/dist/completion-CLHO3Xaz.cjs +0 -5769
  21. package/dist/completion-CLHO3Xaz.cjs.map +0 -1
  22. package/dist/completion-DHnVx9Zk.js.map +0 -1
  23. package/dist/docs/index.cjs +0 -2343
  24. package/dist/docs/index.cjs.map +0 -1
  25. package/dist/docs/index.d.cts +0 -710
  26. package/dist/docs/index.d.cts.map +0 -1
  27. package/dist/docs/index.d.ts.map +0 -1
  28. package/dist/docs/index.js.map +0 -1
  29. package/dist/index-DKGn3lIl.d.ts.map +0 -1
  30. package/dist/index-WyViqW59.d.cts +0 -663
  31. package/dist/index-WyViqW59.d.cts.map +0 -1
  32. package/dist/index.cjs +0 -45
  33. package/dist/index.d.cts +0 -685
  34. package/dist/index.d.cts.map +0 -1
  35. package/dist/index.d.ts.map +0 -1
  36. package/dist/log-collector-DK32-73m.js.map +0 -1
  37. package/dist/log-collector-DUqC427m.cjs +0 -185
  38. package/dist/log-collector-DUqC427m.cjs.map +0 -1
  39. package/dist/prompt/clack/index.cjs +0 -33
  40. package/dist/prompt/clack/index.cjs.map +0 -1
  41. package/dist/prompt/clack/index.d.cts +0 -18
  42. package/dist/prompt/clack/index.d.cts.map +0 -1
  43. package/dist/prompt/clack/index.d.ts.map +0 -1
  44. package/dist/prompt/clack/index.js.map +0 -1
  45. package/dist/prompt/index.cjs +0 -7
  46. package/dist/prompt/index.d.cts +0 -108
  47. package/dist/prompt/index.d.cts.map +0 -1
  48. package/dist/prompt/index.d.ts.map +0 -1
  49. package/dist/prompt/inquirer/index.cjs +0 -48
  50. package/dist/prompt/inquirer/index.cjs.map +0 -1
  51. package/dist/prompt/inquirer/index.d.cts +0 -18
  52. package/dist/prompt/inquirer/index.d.cts.map +0 -1
  53. package/dist/prompt/inquirer/index.d.ts.map +0 -1
  54. package/dist/prompt/inquirer/index.js.map +0 -1
  55. package/dist/prompt-Bs9e-Em3.cjs +0 -196
  56. package/dist/prompt-Bs9e-Em3.cjs.map +0 -1
  57. package/dist/prompt-Cc8Tfmdv.js.map +0 -1
  58. package/dist/runner-D43SkHt5.js.map +0 -1
  59. package/dist/runner-DvFvokV6.cjs +0 -2865
  60. package/dist/runner-DvFvokV6.cjs.map +0 -1
  61. package/dist/schema-extractor-BxSRwLrx.cjs +0 -710
  62. package/dist/schema-extractor-BxSRwLrx.cjs.map +0 -1
  63. package/dist/schema-extractor-Dqe7_kyQ.js.map +0 -1
@@ -1,710 +0,0 @@
1
- import { C as Example, J as ResolvedFieldMeta, V as SubCommandValue, _ as AnyCommand, q as ExtractedFields, v as ArgsSchema } from "../arg-registry-DDJpsUea.cjs";
2
- import { z } from "zod";
3
- import * as fs from "node:fs";
4
-
5
- //#region src/executor/subcommand-router.d.ts
6
- /**
7
- * Resolve a lazy-loaded command (sync or async)
8
- *
9
- * @param cmd - The command or lazy loader function
10
- * @returns The resolved command
11
- */
12
- declare function resolveLazyCommand(cmd: SubCommandValue): Promise<AnyCommand>;
13
- //#endregion
14
- //#region src/docs/render-args.d.ts
15
- /**
16
- * Args shape type (Record of string keys to Zod schemas)
17
- * This matches the typical structure of `commonArgs`, `workspaceArgs`, etc.
18
- */
19
- type ArgsShape = Record<string, z.ZodType>;
20
- /**
21
- * Options for rendering args table
22
- */
23
- type ArgsTableOptions = {
24
- /** Columns to include in the table (default: all columns) */columns?: ("option" | "alias" | "description" | "required" | "default" | "env")[];
25
- };
26
- /**
27
- * Render args definition as a markdown options table
28
- *
29
- * This function takes raw args definitions (like `commonArgs`) and
30
- * renders them as a markdown table suitable for documentation.
31
- *
32
- * @example
33
- * import { renderArgsTable } from "politty/docs";
34
- * import { commonArgs, workspaceArgs } from "./args";
35
- *
36
- * const table = renderArgsTable({
37
- * ...commonArgs,
38
- * ...workspaceArgs,
39
- * });
40
- * // | Option | Alias | Description | Default |
41
- * // |--------|-------|-------------|---------|
42
- * // | `--env-file <ENV_FILE>` | `-e` | Path to environment file | - |
43
- * // ...
44
- *
45
- * @param args - Args shape (Record of string keys to Zod schemas with arg() metadata)
46
- * @param options - Rendering options
47
- * @returns Rendered markdown table string
48
- */
49
- declare function renderArgsTable(args: ArgsShape, options?: ArgsTableOptions): string;
50
- //#endregion
51
- //#region src/docs/types.d.ts
52
- /** Heading level for markdown headings (1-6) */
53
- type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
54
- /**
55
- * Options for rendering command index
56
- */
57
- type CommandIndexOptions = {
58
- /** Base heading level (default: 3, which renders as ###) */headingLevel?: HeadingLevel; /** Only include leaf commands (commands without subcommands). Default: true */
59
- leafOnly?: boolean;
60
- };
61
- /**
62
- * Command information for rendering
63
- */
64
- interface CommandInfo {
65
- /** Command name */
66
- name: string;
67
- /** Command description */
68
- description?: string | undefined;
69
- /** Alternative names (aliases) for this command */
70
- aliases?: string[] | undefined;
71
- /** Full command path (e.g., "my-cli config get") */
72
- fullCommandPath: string;
73
- /** Command path relative to root (e.g., "" for root, "config" for subcommand) */
74
- commandPath: string;
75
- /** Command depth (1 for root commands, 2 for subcommands, etc.) */
76
- depth: number;
77
- /** Positional arguments */
78
- positionalArgs: ResolvedFieldMeta[];
79
- /** Options (non-positional arguments) */
80
- options: ResolvedFieldMeta[];
81
- /** Subcommand information */
82
- subCommands: SubCommandInfo[];
83
- /** Extracted field information from schema */
84
- extracted: ExtractedFields | null;
85
- /** Original command object */
86
- command: AnyCommand;
87
- /** Additional notes */
88
- notes?: string | undefined;
89
- /** File path where this command is rendered (for cross-file links) */
90
- filePath?: string | undefined;
91
- /** Map of command path to file path (for cross-file links) */
92
- fileMap?: Record<string, string> | undefined;
93
- /** Example definitions from command */
94
- examples?: Example[] | undefined;
95
- /** Example execution results (populated when examples are executed) */
96
- exampleResults?: ExampleExecutionResult[] | undefined;
97
- /** Path to root document file (for global options link generation) */
98
- rootDocPath?: string | undefined;
99
- /** Whether global options exist (for global options link generation) */
100
- hasGlobalOptions?: boolean;
101
- }
102
- /**
103
- * Subcommand information
104
- */
105
- interface SubCommandInfo {
106
- /** Subcommand name */
107
- name: string;
108
- /** Subcommand description */
109
- description?: string | undefined;
110
- /** Alternative names (aliases) for this subcommand */
111
- aliases?: string[] | undefined;
112
- /** Full command path */
113
- fullPath: string[];
114
- }
115
- /**
116
- * Example execution result
117
- */
118
- interface ExampleExecutionResult {
119
- /** Command arguments that were executed */
120
- cmd: string;
121
- /** Description of the example */
122
- desc: string;
123
- /** Expected output (if defined in example) */
124
- expectedOutput?: string | undefined;
125
- /** Captured stdout */
126
- stdout: string;
127
- /** Captured stderr */
128
- stderr: string;
129
- /** Whether execution was successful */
130
- success: boolean;
131
- }
132
- /**
133
- * Example execution config for a specific command path
134
- * If a command path is specified in ExampleConfig, its examples will be executed
135
- */
136
- interface ExampleCommandConfig {
137
- /** Mock setup before running examples */
138
- mock?: () => void | Promise<void>;
139
- /** Mock cleanup after running examples */
140
- cleanup?: () => void | Promise<void>;
141
- }
142
- /**
143
- * Example execution configuration
144
- * Key is command path (e.g., "", "config", "config get")
145
- * All specified command paths will have their examples executed
146
- *
147
- * @example
148
- * // With mock setup
149
- * { "": { mock: () => mockFs(), cleanup: () => restoreFs() } }
150
- *
151
- * // Without mock (just execute)
152
- * { "user": true }
153
- */
154
- type ExampleConfig = Record<string, ExampleCommandConfig | true>;
155
- /**
156
- * Render function type for custom markdown generation
157
- */
158
- type RenderFunction = (info: CommandInfo) => string;
159
- /**
160
- * Section render function type (legacy)
161
- * @param defaultContent - The default rendered content for this section
162
- * @param info - Command information
163
- * @returns The final content to render (return empty string to hide section)
164
- * @deprecated Use context-based render functions instead
165
- */
166
- type SectionRenderFunction = (defaultContent: string, info: CommandInfo) => string;
167
- /**
168
- * Render options for options/arguments
169
- */
170
- interface RenderContentOptions {
171
- /** Style for rendering */
172
- style?: "table" | "list";
173
- /** Include heading (default: true) */
174
- withHeading?: boolean;
175
- }
176
- /**
177
- * Options render context
178
- */
179
- interface OptionsRenderContext {
180
- /** Options to render */
181
- options: ResolvedFieldMeta[];
182
- /** Render function that accepts options and optional rendering options */
183
- render: (options: ResolvedFieldMeta[], opts?: RenderContentOptions) => string;
184
- /** Heading prefix (e.g., "###") */
185
- heading: string;
186
- /** Command information */
187
- info: CommandInfo;
188
- }
189
- type OptionsRenderFunction = (context: OptionsRenderContext) => string;
190
- /**
191
- * Arguments render context
192
- */
193
- interface ArgumentsRenderContext {
194
- /** Arguments to render */
195
- args: ResolvedFieldMeta[];
196
- /** Render function that accepts arguments and optional rendering options */
197
- render: (args: ResolvedFieldMeta[], opts?: RenderContentOptions) => string;
198
- /** Heading prefix (e.g., "###") */
199
- heading: string;
200
- /** Command information */
201
- info: CommandInfo;
202
- }
203
- type ArgumentsRenderFunction = (context: ArgumentsRenderContext) => string;
204
- /**
205
- * Subcommands render options
206
- */
207
- interface SubcommandsRenderOptions {
208
- /** Generate anchor links */
209
- generateAnchors?: boolean;
210
- /** Include heading (default: true) */
211
- withHeading?: boolean;
212
- }
213
- /**
214
- * Subcommands render context
215
- */
216
- interface SubcommandsRenderContext {
217
- /** Subcommands to render */
218
- subcommands: SubCommandInfo[];
219
- /** Render function that accepts subcommands and optional rendering options */
220
- render: (subcommands: SubCommandInfo[], opts?: SubcommandsRenderOptions) => string;
221
- /** Heading prefix (e.g., "###") */
222
- heading: string;
223
- /** Command information */
224
- info: CommandInfo;
225
- }
226
- type SubcommandsRenderFunction = (context: SubcommandsRenderContext) => string;
227
- /**
228
- * Examples render options
229
- */
230
- interface ExamplesRenderOptions {
231
- /** Include heading (default: true) */
232
- withHeading?: boolean;
233
- /** Show execution output (default: true when results available) */
234
- showOutput?: boolean;
235
- /** Command prefix to prepend to example commands (e.g., "my-cli config get") */
236
- commandPrefix?: string;
237
- }
238
- /**
239
- * Examples render context
240
- */
241
- interface ExamplesRenderContext {
242
- /** Examples to render */
243
- examples: Example[];
244
- /** Execution results (if examples were executed) */
245
- results?: ExampleExecutionResult[] | undefined;
246
- /** Render function that accepts examples, results, and optional rendering options */
247
- render: (examples: Example[], results?: ExampleExecutionResult[], opts?: ExamplesRenderOptions) => string;
248
- /** Heading prefix (e.g., "###") */
249
- heading: string;
250
- /** Command information */
251
- info: CommandInfo;
252
- }
253
- type ExamplesRenderFunction = (context: ExamplesRenderContext) => string;
254
- /**
255
- * Simple section render context (for description, usage, notes, footer)
256
- */
257
- interface SimpleRenderContext {
258
- /** Default content */
259
- content: string;
260
- /** Heading prefix (e.g., "###") */
261
- heading: string;
262
- /** Command information */
263
- info: CommandInfo;
264
- }
265
- type SimpleRenderFunction = (context: SimpleRenderContext) => string;
266
- /**
267
- * Default renderer customization options
268
- */
269
- interface DefaultRendererOptions {
270
- /** Heading level (default: 1) */
271
- headingLevel?: HeadingLevel;
272
- /** Option display style */
273
- optionStyle?: "table" | "list";
274
- /** Generate anchor links to subcommands */
275
- generateAnchors?: boolean;
276
- /** Include subcommand details */
277
- includeSubcommandDetails?: boolean;
278
- /** Custom renderer for description section */
279
- renderDescription?: SimpleRenderFunction;
280
- /** Custom renderer for usage section */
281
- renderUsage?: SimpleRenderFunction;
282
- /** Custom renderer for arguments section */
283
- renderArguments?: ArgumentsRenderFunction;
284
- /** Custom renderer for options section */
285
- renderOptions?: OptionsRenderFunction;
286
- /** Custom renderer for subcommands section */
287
- renderSubcommands?: SubcommandsRenderFunction;
288
- /** Custom renderer for notes section */
289
- renderNotes?: SimpleRenderFunction;
290
- /** Custom renderer for footer (default content is empty) */
291
- renderFooter?: SimpleRenderFunction;
292
- /** Custom renderer for examples section */
293
- renderExamples?: ExamplesRenderFunction;
294
- }
295
- /**
296
- * Root document configuration
297
- * The root document contains global options tables and command index sections.
298
- */
299
- interface RootDocConfig {
300
- /** Output file path */
301
- path: string;
302
- /**
303
- * Global options configuration.
304
- * ArgsShape directly, or { args, options } for render options.
305
- */
306
- globalOptions?: ArgsShape | {
307
- args: ArgsShape;
308
- options?: ArgsTableOptions;
309
- };
310
- /** Heading level for the file header (default: 1) */
311
- headingLevel?: HeadingLevel;
312
- /** Index section rendering options */
313
- index?: CommandIndexOptions;
314
- }
315
- /**
316
- * Root command customization for the root document.
317
- * Controls the root document's title, description, header, and footer.
318
- */
319
- interface RootCommandInfo {
320
- /** Title (defaults to command.name) */
321
- title?: string;
322
- /** Description (defaults to command.description) */
323
- description?: string;
324
- /** Markdown placed after title/description */
325
- header?: string;
326
- /** Markdown placed at end of document */
327
- footer?: string;
328
- }
329
- /**
330
- * Path configuration for documentation output.
331
- * Simpler alternative to FileMapping for common patterns.
332
- *
333
- * @example
334
- * // All commands in one file
335
- * path: "docs/CLI.md"
336
- *
337
- * // Split files: root + specific commands in separate files
338
- * path: { root: "docs/CLI.md", commands: { "build": "docs/build.md" } }
339
- */
340
- type PathConfig = string | {
341
- root: string;
342
- commands?: Record<string, string>;
343
- };
344
- /**
345
- * Per-file configuration with custom renderer
346
- */
347
- interface FileConfig {
348
- /** Command paths to include in this file (e.g., ["", "user", "config get"]) */
349
- commands: string[];
350
- /** Custom renderer for this file (optional) */
351
- render?: RenderFunction;
352
- /** File title (prepended to the file content) */
353
- title?: string;
354
- /** File description (added after title) */
355
- description?: string;
356
- /** Skip subcommand expansion (commands are used as-is). @internal */
357
- noExpand?: boolean;
358
- }
359
- /**
360
- * File mapping configuration
361
- * Key: output file path (e.g., "docs/cli.md")
362
- * Value: command paths array or FileConfig object
363
- *
364
- * @example
365
- * // Simple: single file with multiple commands
366
- * { "docs/cli.md": ["", "user", "config"] }
367
- *
368
- * // With custom renderer
369
- * { "docs/cli.md": { commands: [""], render: customRenderer } }
370
- */
371
- type FileMapping = Record<string, string[] | FileConfig>;
372
- /**
373
- * generateDoc configuration
374
- */
375
- interface GenerateDocConfig {
376
- /** Command to generate documentation for */
377
- command: AnyCommand;
378
- /**
379
- * Root document configuration.
380
- * The root document contains global options tables and command index sections.
381
- * Title and description are derived from `command.name` and `command.description`.
382
- */
383
- rootDoc?: RootDocConfig;
384
- /**
385
- * Path configuration (simpler alternative to files).
386
- * Mutually exclusive with `files`.
387
- */
388
- path?: PathConfig;
389
- /** File output configuration (command path -> file mapping) */
390
- files?: FileMapping;
391
- /** Root command customization (title, description, header, footer) */
392
- rootInfo?: RootCommandInfo;
393
- /** Command paths to ignore (including their subcommands) */
394
- ignores?: string[];
395
- /** Default renderer options (used when render is not specified per file) */
396
- format?: DefaultRendererOptions;
397
- /** Formatter function to apply to generated content before comparison */
398
- formatter?: FormatterFunction;
399
- /** Example execution configuration (per command path) */
400
- examples?: ExampleConfig;
401
- /**
402
- * Target command paths to validate (e.g., ["read", "config get"])
403
- * When specified, only these commands' sections are validated.
404
- * The full document structure is used to maintain cross-file links.
405
- */
406
- targetCommands?: string[];
407
- /**
408
- * Global args schema (runtime schema alternative).
409
- * When provided, automatically derives `rootDoc.globalOptions` from this schema.
410
- */
411
- globalArgs?: ArgsSchema;
412
- }
413
- /**
414
- * generateDoc result
415
- */
416
- interface GenerateDocResult {
417
- /** Whether all files matched or were updated successfully */
418
- success: boolean;
419
- /** File processing results */
420
- files: Array<{
421
- /** File path */path: string; /** Status of this file */
422
- status: "match" | "created" | "updated" | "diff"; /** Diff content (only when status is "diff") */
423
- diff?: string | undefined;
424
- }>;
425
- /** Error message (when success is false) */
426
- error?: string | undefined;
427
- }
428
- /**
429
- * Formatter function type
430
- * Formats generated content before comparison
431
- */
432
- type FormatterFunction = (content: string) => string | Promise<string>;
433
- /**
434
- * Environment variable name for update mode
435
- */
436
- declare const UPDATE_GOLDEN_ENV = "POLITTY_DOCS_UPDATE";
437
- /**
438
- * Environment variable name for doctor mode.
439
- * When enabled alone, detects and reports missing section markers (read-only).
440
- * When combined with POLITTY_DOCS_UPDATE=true, auto-inserts missing markers.
441
- */
442
- declare const DOCTOR_ENV = "POLITTY_DOCS_DOCTOR";
443
- /**
444
- * All section types in rendering order
445
- */
446
- declare const SECTION_TYPES: readonly ["heading", "description", "usage", "arguments", "options", "global-options-link", "subcommands", "examples", "notes"];
447
- /**
448
- * Section types for command documentation markers
449
- */
450
- type SectionType = (typeof SECTION_TYPES)[number];
451
- /**
452
- * Marker prefix for command section markers in generated documentation
453
- * Format: <!-- politty:command:<scope>:<type>:start --> ... <!-- politty:command:<scope>:<type>:end -->
454
- */
455
- declare const SECTION_MARKER_PREFIX = "politty:command";
456
- /**
457
- * Generate start marker for a command section
458
- */
459
- declare function sectionStartMarker(type: SectionType, scope: string): string;
460
- /**
461
- * Generate end marker for a command section
462
- */
463
- declare function sectionEndMarker(type: SectionType, scope: string): string;
464
- /**
465
- * Marker prefix for global options sections in generated documentation
466
- * Format: <!-- politty:global-options:start --> ... <!-- politty:global-options:end -->
467
- */
468
- declare const GLOBAL_OPTIONS_MARKER_PREFIX = "politty:global-options";
469
- /**
470
- * Generate start marker for a global options section
471
- */
472
- declare function globalOptionsStartMarker(): string;
473
- /**
474
- * Generate end marker for a global options section
475
- */
476
- declare function globalOptionsEndMarker(): string;
477
- /**
478
- * Marker prefix for root header sections in generated documentation
479
- */
480
- declare const ROOT_HEADER_MARKER_PREFIX = "politty:root-header";
481
- declare function rootHeaderStartMarker(): string;
482
- declare function rootHeaderEndMarker(): string;
483
- /**
484
- * Marker prefix for root footer sections in generated documentation
485
- */
486
- declare const ROOT_FOOTER_MARKER_PREFIX = "politty:root-footer";
487
- declare function rootFooterStartMarker(): string;
488
- declare function rootFooterEndMarker(): string;
489
- /**
490
- * Marker prefix for index sections in generated documentation
491
- * Format: <!-- politty:index:<scope>:start --> ... <!-- politty:index:<scope>:end -->
492
- */
493
- declare const INDEX_MARKER_PREFIX = "politty:index";
494
- /**
495
- * Generate start marker for an index section
496
- */
497
- declare function indexStartMarker(scope: string): string;
498
- /**
499
- * Generate end marker for an index section
500
- */
501
- declare function indexEndMarker(scope: string): string;
502
- //#endregion
503
- //#region src/docs/default-renderers.d.ts
504
- /**
505
- * Render usage line
506
- */
507
- declare function renderUsage(info: CommandInfo): string;
508
- /**
509
- * Render arguments as table
510
- */
511
- declare function renderArgumentsTable(info: CommandInfo): string;
512
- /**
513
- * Render arguments as list
514
- */
515
- declare function renderArgumentsList(info: CommandInfo): string;
516
- /**
517
- * Render options as markdown table
518
- *
519
- * Features:
520
- * - Uses kebab-case (cliName) for option names (e.g., `--dry-run` instead of `--dryRun`)
521
- * - Automatically adds Env column when any option has env configured
522
- * - Displays multiple env vars as comma-separated list
523
- *
524
- * @example
525
- * | Option | Alias | Description | Required | Default | Env |
526
- * |--------|-------|-------------|----------|---------|-----|
527
- * | `--dry-run` | `-d` | Dry run mode | No | `false` | - |
528
- * | `--port <PORT>` | - | Server port | Yes | - | `PORT`, `SERVER_PORT` |
529
- */
530
- declare function renderOptionsTable(info: CommandInfo): string;
531
- /**
532
- * Render options as markdown list
533
- *
534
- * Features:
535
- * - Uses kebab-case (cliName) for option names (e.g., `--dry-run` instead of `--dryRun`)
536
- * - Appends env info at the end of each option (e.g., `[env: PORT, SERVER_PORT]`)
537
- *
538
- * @example
539
- * - `-d`, `--dry-run` - Dry run mode (default: false)
540
- * - `--port <PORT>` - Server port (required) [env: PORT, SERVER_PORT]
541
- */
542
- declare function renderOptionsList(info: CommandInfo): string;
543
- /**
544
- * Render subcommands as table
545
- */
546
- declare function renderSubcommandsTable(info: CommandInfo, generateAnchors?: boolean): string;
547
- /**
548
- * Render options from array as table
549
- */
550
- declare function renderOptionsTableFromArray(options: ResolvedFieldMeta[]): string;
551
- /**
552
- * Render options from array as list
553
- */
554
- declare function renderOptionsListFromArray(options: ResolvedFieldMeta[]): string;
555
- /**
556
- * Render arguments from array as table
557
- */
558
- declare function renderArgumentsTableFromArray(args: ResolvedFieldMeta[]): string;
559
- /**
560
- * Render arguments from array as list
561
- */
562
- declare function renderArgumentsListFromArray(args: ResolvedFieldMeta[]): string;
563
- /**
564
- * Render subcommands from array as table
565
- */
566
- declare function renderSubcommandsTableFromArray(subcommands: SubCommandInfo[], info: CommandInfo, generateAnchors?: boolean): string;
567
- /**
568
- * Render examples as markdown
569
- *
570
- * @example
571
- * **Basic usage**
572
- *
573
- * ```bash
574
- * $ greet World
575
- * ```
576
- *
577
- * Output:
578
- * ```
579
- * Hello, World!
580
- * ```
581
- */
582
- declare function renderExamplesDefault(examples: Example[], results?: ExampleExecutionResult[], opts?: ExamplesRenderOptions): string;
583
- declare function createCommandRenderer(options?: DefaultRendererOptions): RenderFunction;
584
- /**
585
- * Default renderers presets
586
- */
587
- declare const defaultRenderers: {
588
- /** Standard command documentation */command: (options?: DefaultRendererOptions) => RenderFunction; /** Table style options (default) */
589
- tableStyle: RenderFunction; /** List style options */
590
- listStyle: RenderFunction;
591
- };
592
- //#endregion
593
- //#region src/docs/doc-comparator.d.ts
594
- /**
595
- * Comparison result
596
- */
597
- interface CompareResult {
598
- /** Whether the content matches */
599
- match: boolean;
600
- /** Diff content (only when match is false) */
601
- diff?: string;
602
- /** Whether the file exists */
603
- fileExists: boolean;
604
- }
605
- /**
606
- * Compare generated content with existing file
607
- */
608
- declare function compareWithExisting(generatedContent: string, filePath: string): CompareResult;
609
- /**
610
- * Format diff between two strings in unified diff format
611
- */
612
- declare function formatDiff(expected: string, actual: string): string;
613
- /**
614
- * Write content to file, creating directories if needed
615
- */
616
- declare function writeFile(filePath: string, content: string): void;
617
- /**
618
- * Minimal fs interface for deleteFile
619
- */
620
- interface DeleteFileFs {
621
- existsSync: typeof fs.existsSync;
622
- unlinkSync: typeof fs.unlinkSync;
623
- }
624
- //#endregion
625
- //#region src/docs/doc-generator.d.ts
626
- /**
627
- * Build CommandInfo from a command
628
- */
629
- declare function buildCommandInfo(command: AnyCommand, rootName: string, commandPath?: string[]): Promise<CommandInfo>;
630
- /**
631
- * Collect all commands with their paths
632
- * Returns a map of command path -> CommandInfo
633
- */
634
- declare function collectAllCommands(command: AnyCommand, rootName?: string): Promise<Map<string, CommandInfo>>;
635
- //#endregion
636
- //#region src/docs/example-executor.d.ts
637
- /**
638
- * Execute examples for a command and capture output
639
- *
640
- * @param examples - Examples to execute
641
- * @param config - Execution configuration (mock setup/cleanup)
642
- * @param rootCommand - Root command to execute against
643
- * @param commandPath - Command path for subcommands (e.g., ["config", "get"])
644
- * @returns Array of execution results with captured stdout/stderr
645
- */
646
- declare function executeExamples(examples: Example[], config: ExampleCommandConfig, rootCommand: AnyCommand, commandPath?: string[]): Promise<ExampleExecutionResult[]>;
647
- //#endregion
648
- //#region src/docs/golden-test.d.ts
649
- /**
650
- * Generate documentation from command definition
651
- */
652
- declare function generateDoc(config: GenerateDocConfig): Promise<GenerateDocResult>;
653
- /**
654
- * Assert that documentation matches golden files
655
- * Throws an error if there are differences and update mode is not enabled
656
- */
657
- declare function assertDocMatch(config: GenerateDocConfig): Promise<void>;
658
- /**
659
- * Initialize documentation files by deleting them
660
- * Only deletes when update mode is enabled (POLITTY_DOCS_UPDATE=true)
661
- * Use this in beforeAll to ensure skipped tests don't leave stale sections
662
- * @param config - Config containing files to initialize, or a single file path
663
- * @param fileSystem - Optional fs implementation (useful when fs is mocked)
664
- */
665
- declare function initDocFile(config: Pick<GenerateDocConfig, "files"> | string, fileSystem?: DeleteFileFs): void;
666
- //#endregion
667
- //#region src/docs/render-index.d.ts
668
- /**
669
- * Configuration for a command category
670
- */
671
- type CommandCategory = {
672
- /** Category title (e.g., "Application Commands") */title: string; /** Category description */
673
- description: string; /** Command paths to include (parent commands will auto-expand to leaf commands) */
674
- commands: string[]; /** Path to documentation file for links (e.g., "./cli/application.md") */
675
- docPath: string;
676
- };
677
- /**
678
- * Render command index from categories
679
- *
680
- * Generates a category-based index of commands with links to documentation.
681
- *
682
- * @example
683
- * const categories: CommandCategory[] = [
684
- * {
685
- * title: "Application Commands",
686
- * description: "Commands for managing applications.",
687
- * commands: ["init", "generate", "apply"],
688
- * docPath: "./cli/application.md",
689
- * },
690
- * ];
691
- *
692
- * const index = await renderCommandIndex(mainCommand, categories);
693
- * // ### [Application Commands](./cli/application.md)
694
- * //
695
- * // Commands for managing applications.
696
- * //
697
- * // | Command | Description |
698
- * // |---------|-------------|
699
- * // | [init](./cli/application.md#init) | Initialize a project |
700
- * // ...
701
- *
702
- * @param command - Root command to extract command information from
703
- * @param categories - Category definitions for grouping commands
704
- * @param options - Rendering options
705
- * @returns Rendered markdown string
706
- */
707
- declare function renderCommandIndex(command: AnyCommand, categories: CommandCategory[], options?: CommandIndexOptions): Promise<string>;
708
- //#endregion
709
- 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 };
710
- //# sourceMappingURL=index.d.cts.map