politty 0.0.1 → 0.1.1
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.
- package/README.md +297 -28
- package/dist/arg-registry-ClI2WGgH.d.cts +89 -0
- package/dist/arg-registry-ClI2WGgH.d.cts.map +1 -0
- package/dist/arg-registry-D4NsqcNZ.d.ts +89 -0
- package/dist/arg-registry-D4NsqcNZ.d.ts.map +1 -0
- package/dist/augment.cjs +0 -0
- package/dist/augment.d.cts +17 -0
- package/dist/augment.d.cts.map +1 -0
- package/dist/augment.d.ts +17 -0
- package/dist/augment.d.ts.map +1 -0
- package/dist/augment.js +1 -0
- package/dist/command-Bgd-yIwv.cjs +25 -0
- package/dist/command-Bgd-yIwv.cjs.map +1 -0
- package/dist/command-CvKyk4ag.js +20 -0
- package/dist/command-CvKyk4ag.js.map +1 -0
- package/dist/completion/index.cjs +595 -0
- package/dist/completion/index.cjs.map +1 -0
- package/dist/completion/index.d.cts +153 -0
- package/dist/completion/index.d.cts.map +1 -0
- package/dist/completion/index.d.ts +153 -0
- package/dist/completion/index.d.ts.map +1 -0
- package/dist/completion/index.js +588 -0
- package/dist/completion/index.js.map +1 -0
- package/dist/docs/index.cjs +1239 -0
- package/dist/docs/index.cjs.map +1 -0
- package/dist/docs/index.d.cts +500 -0
- package/dist/docs/index.d.cts.map +1 -0
- package/dist/docs/index.d.ts +500 -0
- package/dist/docs/index.d.ts.map +1 -0
- package/dist/docs/index.js +1182 -0
- package/dist/docs/index.js.map +1 -0
- package/dist/index.cjs +29 -0
- package/dist/index.d.cts +478 -0
- package/dist/index.d.cts.map +1 -0
- package/dist/index.d.ts +478 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +5 -0
- package/dist/runner-BZuYiRhi.cjs +1492 -0
- package/dist/runner-BZuYiRhi.cjs.map +1 -0
- package/dist/runner-D2BXiWtg.cjs +4 -0
- package/dist/runner-DceWXOwD.js +1372 -0
- package/dist/runner-DceWXOwD.js.map +1 -0
- package/dist/runner-KCql2UKz.js +4 -0
- package/dist/schema-extractor-B9D3Rf22.cjs +354 -0
- package/dist/schema-extractor-B9D3Rf22.cjs.map +1 -0
- package/dist/schema-extractor-D-Eo7I77.d.cts +303 -0
- package/dist/schema-extractor-D-Eo7I77.d.cts.map +1 -0
- package/dist/schema-extractor-Dk5Z0Iei.js +324 -0
- package/dist/schema-extractor-Dk5Z0Iei.js.map +1 -0
- package/dist/schema-extractor-kkajLb9E.d.ts +303 -0
- package/dist/schema-extractor-kkajLb9E.d.ts.map +1 -0
- package/dist/subcommand-router-BiSvDXHg.js +153 -0
- package/dist/subcommand-router-BiSvDXHg.js.map +1 -0
- package/dist/subcommand-router-Vf-0w9P4.cjs +189 -0
- package/dist/subcommand-router-Vf-0w9P4.cjs.map +1 -0
- package/package.json +108 -6
|
@@ -0,0 +1,500 @@
|
|
|
1
|
+
import { n as ResolvedFieldMeta, p as Example, s as AnyCommand, t as ExtractedFields } from "../schema-extractor-D-Eo7I77.cjs";
|
|
2
|
+
import * as fs from "node:fs";
|
|
3
|
+
|
|
4
|
+
//#region src/executor/subcommand-router.d.ts
|
|
5
|
+
|
|
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: AnyCommand | (() => Promise<AnyCommand>)): Promise<AnyCommand>;
|
|
13
|
+
//#endregion
|
|
14
|
+
//#region src/docs/types.d.ts
|
|
15
|
+
/**
|
|
16
|
+
* Command information for rendering
|
|
17
|
+
*/
|
|
18
|
+
interface CommandInfo {
|
|
19
|
+
/** Command name */
|
|
20
|
+
name: string;
|
|
21
|
+
/** Command description */
|
|
22
|
+
description?: string | undefined;
|
|
23
|
+
/** Full command path (e.g., "my-cli config get") */
|
|
24
|
+
fullCommandPath: string;
|
|
25
|
+
/** Command path relative to root (e.g., "" for root, "config" for subcommand) */
|
|
26
|
+
commandPath: string;
|
|
27
|
+
/** Command depth (1 for root commands, 2 for subcommands, etc.) */
|
|
28
|
+
depth: number;
|
|
29
|
+
/** Positional arguments */
|
|
30
|
+
positionalArgs: ResolvedFieldMeta[];
|
|
31
|
+
/** Options (non-positional arguments) */
|
|
32
|
+
options: ResolvedFieldMeta[];
|
|
33
|
+
/** Subcommand information */
|
|
34
|
+
subCommands: SubCommandInfo[];
|
|
35
|
+
/** Extracted field information from schema */
|
|
36
|
+
extracted: ExtractedFields | null;
|
|
37
|
+
/** Original command object */
|
|
38
|
+
command: AnyCommand;
|
|
39
|
+
/** Additional notes */
|
|
40
|
+
notes?: string | undefined;
|
|
41
|
+
/** File path where this command is rendered (for cross-file links) */
|
|
42
|
+
filePath?: string | undefined;
|
|
43
|
+
/** Map of command path to file path (for cross-file links) */
|
|
44
|
+
fileMap?: Record<string, string> | undefined;
|
|
45
|
+
/** Example definitions from command */
|
|
46
|
+
examples?: Example[] | undefined;
|
|
47
|
+
/** Example execution results (populated when examples are executed) */
|
|
48
|
+
exampleResults?: ExampleExecutionResult[] | undefined;
|
|
49
|
+
}
|
|
50
|
+
/**
|
|
51
|
+
* Subcommand information
|
|
52
|
+
*/
|
|
53
|
+
interface SubCommandInfo {
|
|
54
|
+
/** Subcommand name */
|
|
55
|
+
name: string;
|
|
56
|
+
/** Subcommand description */
|
|
57
|
+
description?: string | undefined;
|
|
58
|
+
/** Full command path */
|
|
59
|
+
fullPath: string[];
|
|
60
|
+
}
|
|
61
|
+
/**
|
|
62
|
+
* Example execution result
|
|
63
|
+
*/
|
|
64
|
+
interface ExampleExecutionResult {
|
|
65
|
+
/** Command arguments that were executed */
|
|
66
|
+
cmd: string;
|
|
67
|
+
/** Description of the example */
|
|
68
|
+
desc: string;
|
|
69
|
+
/** Expected output (if defined in example) */
|
|
70
|
+
expectedOutput?: string | undefined;
|
|
71
|
+
/** Captured stdout */
|
|
72
|
+
stdout: string;
|
|
73
|
+
/** Captured stderr */
|
|
74
|
+
stderr: string;
|
|
75
|
+
/** Whether execution was successful */
|
|
76
|
+
success: boolean;
|
|
77
|
+
}
|
|
78
|
+
/**
|
|
79
|
+
* Example execution config for a specific command path
|
|
80
|
+
* If a command path is specified in ExampleConfig, its examples will be executed
|
|
81
|
+
*/
|
|
82
|
+
interface ExampleCommandConfig {
|
|
83
|
+
/** Mock setup before running examples */
|
|
84
|
+
mock?: () => void | Promise<void>;
|
|
85
|
+
/** Mock cleanup after running examples */
|
|
86
|
+
cleanup?: () => void | Promise<void>;
|
|
87
|
+
}
|
|
88
|
+
/**
|
|
89
|
+
* Example execution configuration
|
|
90
|
+
* Key is command path (e.g., "", "config", "config get")
|
|
91
|
+
* All specified command paths will have their examples executed
|
|
92
|
+
*
|
|
93
|
+
* @example
|
|
94
|
+
* // With mock setup
|
|
95
|
+
* { "": { mock: () => mockFs(), cleanup: () => restoreFs() } }
|
|
96
|
+
*
|
|
97
|
+
* // Without mock (just execute)
|
|
98
|
+
* { "user": true }
|
|
99
|
+
*/
|
|
100
|
+
type ExampleConfig = Record<string, ExampleCommandConfig | true>;
|
|
101
|
+
/**
|
|
102
|
+
* Render function type for custom markdown generation
|
|
103
|
+
*/
|
|
104
|
+
type RenderFunction = (info: CommandInfo) => string;
|
|
105
|
+
/**
|
|
106
|
+
* Section render function type (legacy)
|
|
107
|
+
* @param defaultContent - The default rendered content for this section
|
|
108
|
+
* @param info - Command information
|
|
109
|
+
* @returns The final content to render (return empty string to hide section)
|
|
110
|
+
* @deprecated Use context-based render functions instead
|
|
111
|
+
*/
|
|
112
|
+
type SectionRenderFunction = (defaultContent: string, info: CommandInfo) => string;
|
|
113
|
+
/**
|
|
114
|
+
* Render options for options/arguments
|
|
115
|
+
*/
|
|
116
|
+
interface RenderContentOptions {
|
|
117
|
+
/** Style for rendering */
|
|
118
|
+
style?: "table" | "list";
|
|
119
|
+
/** Include heading (default: true) */
|
|
120
|
+
withHeading?: boolean;
|
|
121
|
+
}
|
|
122
|
+
/**
|
|
123
|
+
* Options render context
|
|
124
|
+
*/
|
|
125
|
+
interface OptionsRenderContext {
|
|
126
|
+
/** Options to render */
|
|
127
|
+
options: ResolvedFieldMeta[];
|
|
128
|
+
/** Render function that accepts options and optional rendering options */
|
|
129
|
+
render: (options: ResolvedFieldMeta[], opts?: RenderContentOptions) => string;
|
|
130
|
+
/** Heading prefix (e.g., "###") */
|
|
131
|
+
heading: string;
|
|
132
|
+
/** Command information */
|
|
133
|
+
info: CommandInfo;
|
|
134
|
+
}
|
|
135
|
+
type OptionsRenderFunction = (context: OptionsRenderContext) => string;
|
|
136
|
+
/**
|
|
137
|
+
* Arguments render context
|
|
138
|
+
*/
|
|
139
|
+
interface ArgumentsRenderContext {
|
|
140
|
+
/** Arguments to render */
|
|
141
|
+
args: ResolvedFieldMeta[];
|
|
142
|
+
/** Render function that accepts arguments and optional rendering options */
|
|
143
|
+
render: (args: ResolvedFieldMeta[], opts?: RenderContentOptions) => string;
|
|
144
|
+
/** Heading prefix (e.g., "###") */
|
|
145
|
+
heading: string;
|
|
146
|
+
/** Command information */
|
|
147
|
+
info: CommandInfo;
|
|
148
|
+
}
|
|
149
|
+
type ArgumentsRenderFunction = (context: ArgumentsRenderContext) => string;
|
|
150
|
+
/**
|
|
151
|
+
* Subcommands render options
|
|
152
|
+
*/
|
|
153
|
+
interface SubcommandsRenderOptions {
|
|
154
|
+
/** Generate anchor links */
|
|
155
|
+
generateAnchors?: boolean;
|
|
156
|
+
/** Include heading (default: true) */
|
|
157
|
+
withHeading?: boolean;
|
|
158
|
+
}
|
|
159
|
+
/**
|
|
160
|
+
* Subcommands render context
|
|
161
|
+
*/
|
|
162
|
+
interface SubcommandsRenderContext {
|
|
163
|
+
/** Subcommands to render */
|
|
164
|
+
subcommands: SubCommandInfo[];
|
|
165
|
+
/** Render function that accepts subcommands and optional rendering options */
|
|
166
|
+
render: (subcommands: SubCommandInfo[], opts?: SubcommandsRenderOptions) => string;
|
|
167
|
+
/** Heading prefix (e.g., "###") */
|
|
168
|
+
heading: string;
|
|
169
|
+
/** Command information */
|
|
170
|
+
info: CommandInfo;
|
|
171
|
+
}
|
|
172
|
+
type SubcommandsRenderFunction = (context: SubcommandsRenderContext) => string;
|
|
173
|
+
/**
|
|
174
|
+
* Examples render options
|
|
175
|
+
*/
|
|
176
|
+
interface ExamplesRenderOptions {
|
|
177
|
+
/** Include heading (default: true) */
|
|
178
|
+
withHeading?: boolean;
|
|
179
|
+
/** Show execution output (default: true when results available) */
|
|
180
|
+
showOutput?: boolean;
|
|
181
|
+
}
|
|
182
|
+
/**
|
|
183
|
+
* Examples render context
|
|
184
|
+
*/
|
|
185
|
+
interface ExamplesRenderContext {
|
|
186
|
+
/** Examples to render */
|
|
187
|
+
examples: Example[];
|
|
188
|
+
/** Execution results (if examples were executed) */
|
|
189
|
+
results?: ExampleExecutionResult[] | undefined;
|
|
190
|
+
/** Render function that accepts examples, results, and optional rendering options */
|
|
191
|
+
render: (examples: Example[], results?: ExampleExecutionResult[], opts?: ExamplesRenderOptions) => string;
|
|
192
|
+
/** Heading prefix (e.g., "###") */
|
|
193
|
+
heading: string;
|
|
194
|
+
/** Command information */
|
|
195
|
+
info: CommandInfo;
|
|
196
|
+
}
|
|
197
|
+
type ExamplesRenderFunction = (context: ExamplesRenderContext) => string;
|
|
198
|
+
/**
|
|
199
|
+
* Simple section render context (for description, usage, notes, footer)
|
|
200
|
+
*/
|
|
201
|
+
interface SimpleRenderContext {
|
|
202
|
+
/** Default content */
|
|
203
|
+
content: string;
|
|
204
|
+
/** Heading prefix (e.g., "###") */
|
|
205
|
+
heading: string;
|
|
206
|
+
/** Command information */
|
|
207
|
+
info: CommandInfo;
|
|
208
|
+
}
|
|
209
|
+
type SimpleRenderFunction = (context: SimpleRenderContext) => string;
|
|
210
|
+
/**
|
|
211
|
+
* Default renderer customization options
|
|
212
|
+
*/
|
|
213
|
+
interface DefaultRendererOptions {
|
|
214
|
+
/** Heading level (default: 1) */
|
|
215
|
+
headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
|
|
216
|
+
/** Option display style */
|
|
217
|
+
optionStyle?: "table" | "list";
|
|
218
|
+
/** Generate anchor links to subcommands */
|
|
219
|
+
generateAnchors?: boolean;
|
|
220
|
+
/** Include subcommand details */
|
|
221
|
+
includeSubcommandDetails?: boolean;
|
|
222
|
+
/** Custom renderer for description section */
|
|
223
|
+
renderDescription?: SimpleRenderFunction;
|
|
224
|
+
/** Custom renderer for usage section */
|
|
225
|
+
renderUsage?: SimpleRenderFunction;
|
|
226
|
+
/** Custom renderer for arguments section */
|
|
227
|
+
renderArguments?: ArgumentsRenderFunction;
|
|
228
|
+
/** Custom renderer for options section */
|
|
229
|
+
renderOptions?: OptionsRenderFunction;
|
|
230
|
+
/** Custom renderer for subcommands section */
|
|
231
|
+
renderSubcommands?: SubcommandsRenderFunction;
|
|
232
|
+
/** Custom renderer for notes section */
|
|
233
|
+
renderNotes?: SimpleRenderFunction;
|
|
234
|
+
/** Custom renderer for footer (default content is empty) */
|
|
235
|
+
renderFooter?: SimpleRenderFunction;
|
|
236
|
+
/** Custom renderer for examples section */
|
|
237
|
+
renderExamples?: ExamplesRenderFunction;
|
|
238
|
+
}
|
|
239
|
+
/**
|
|
240
|
+
* Per-file configuration with custom renderer
|
|
241
|
+
*/
|
|
242
|
+
interface FileConfig {
|
|
243
|
+
/** Command paths to include in this file (e.g., ["", "user", "config get"]) */
|
|
244
|
+
commands: string[];
|
|
245
|
+
/** Custom renderer for this file (optional) */
|
|
246
|
+
render?: RenderFunction;
|
|
247
|
+
/** File title (prepended to the file content) */
|
|
248
|
+
title?: string;
|
|
249
|
+
/** File description (added after title) */
|
|
250
|
+
description?: string;
|
|
251
|
+
}
|
|
252
|
+
/**
|
|
253
|
+
* File mapping configuration
|
|
254
|
+
* Key: output file path (e.g., "docs/cli.md")
|
|
255
|
+
* Value: command paths array or FileConfig object
|
|
256
|
+
*
|
|
257
|
+
* @example
|
|
258
|
+
* // Simple: single file with multiple commands
|
|
259
|
+
* { "docs/cli.md": ["", "user", "config"] }
|
|
260
|
+
*
|
|
261
|
+
* // With custom renderer
|
|
262
|
+
* { "docs/cli.md": { commands: [""], render: customRenderer } }
|
|
263
|
+
*/
|
|
264
|
+
type FileMapping = Record<string, string[] | FileConfig>;
|
|
265
|
+
/**
|
|
266
|
+
* generateDoc configuration
|
|
267
|
+
*/
|
|
268
|
+
interface GenerateDocConfig {
|
|
269
|
+
/** Command to generate documentation for */
|
|
270
|
+
command: AnyCommand;
|
|
271
|
+
/** File output configuration (command path -> file mapping) */
|
|
272
|
+
files: FileMapping;
|
|
273
|
+
/** Command paths to ignore (including their subcommands) */
|
|
274
|
+
ignores?: string[];
|
|
275
|
+
/** Default renderer options (used when render is not specified per file) */
|
|
276
|
+
format?: DefaultRendererOptions;
|
|
277
|
+
/** Formatter function to apply to generated content before comparison */
|
|
278
|
+
formatter?: FormatterFunction;
|
|
279
|
+
/** Example execution configuration (per command path) */
|
|
280
|
+
examples?: ExampleConfig;
|
|
281
|
+
/**
|
|
282
|
+
* Target command paths to validate (e.g., ["read", "config get"])
|
|
283
|
+
* When specified, only these commands' sections are validated.
|
|
284
|
+
* The full document structure is used to maintain cross-file links.
|
|
285
|
+
*/
|
|
286
|
+
targetCommands?: string[];
|
|
287
|
+
}
|
|
288
|
+
/**
|
|
289
|
+
* generateDoc result
|
|
290
|
+
*/
|
|
291
|
+
interface GenerateDocResult {
|
|
292
|
+
/** Whether all files matched or were updated successfully */
|
|
293
|
+
success: boolean;
|
|
294
|
+
/** File processing results */
|
|
295
|
+
files: Array<{
|
|
296
|
+
/** File path */
|
|
297
|
+
path: string;
|
|
298
|
+
/** Status of this file */
|
|
299
|
+
status: "match" | "created" | "updated" | "diff";
|
|
300
|
+
/** Diff content (only when status is "diff") */
|
|
301
|
+
diff?: string | undefined;
|
|
302
|
+
}>;
|
|
303
|
+
/** Error message (when success is false) */
|
|
304
|
+
error?: string | undefined;
|
|
305
|
+
}
|
|
306
|
+
/**
|
|
307
|
+
* Formatter function type
|
|
308
|
+
* Formats generated content before comparison
|
|
309
|
+
*/
|
|
310
|
+
type FormatterFunction = (content: string) => string | Promise<string>;
|
|
311
|
+
/**
|
|
312
|
+
* Environment variable name for update mode
|
|
313
|
+
*/
|
|
314
|
+
declare const UPDATE_GOLDEN_ENV = "POLITTY_DOCS_UPDATE";
|
|
315
|
+
/**
|
|
316
|
+
* Marker prefix for command sections in generated documentation
|
|
317
|
+
* Format: <!-- politty:command:<path>:start --> ... <!-- politty:command:<path>:end -->
|
|
318
|
+
*/
|
|
319
|
+
declare const COMMAND_MARKER_PREFIX = "politty:command";
|
|
320
|
+
/**
|
|
321
|
+
* Generate start marker for a command section
|
|
322
|
+
*/
|
|
323
|
+
declare function commandStartMarker(commandPath: string): string;
|
|
324
|
+
/**
|
|
325
|
+
* Generate end marker for a command section
|
|
326
|
+
*/
|
|
327
|
+
declare function commandEndMarker(commandPath: string): string;
|
|
328
|
+
//#endregion
|
|
329
|
+
//#region src/docs/default-renderers.d.ts
|
|
330
|
+
/**
|
|
331
|
+
* Render usage line
|
|
332
|
+
*/
|
|
333
|
+
declare function renderUsage(info: CommandInfo): string;
|
|
334
|
+
/**
|
|
335
|
+
* Render arguments as table
|
|
336
|
+
*/
|
|
337
|
+
declare function renderArgumentsTable(info: CommandInfo): string;
|
|
338
|
+
/**
|
|
339
|
+
* Render arguments as list
|
|
340
|
+
*/
|
|
341
|
+
declare function renderArgumentsList(info: CommandInfo): string;
|
|
342
|
+
/**
|
|
343
|
+
* Render options as markdown table
|
|
344
|
+
*
|
|
345
|
+
* Features:
|
|
346
|
+
* - Uses kebab-case (cliName) for option names (e.g., `--dry-run` instead of `--dryRun`)
|
|
347
|
+
* - Automatically adds Env column when any option has env configured
|
|
348
|
+
* - Displays multiple env vars as comma-separated list
|
|
349
|
+
*
|
|
350
|
+
* @example
|
|
351
|
+
* | Option | Alias | Description | Default | Env |
|
|
352
|
+
* |--------|-------|-------------|---------|-----|
|
|
353
|
+
* | `--dry-run` | `-d` | Dry run mode | `false` | - |
|
|
354
|
+
* | `--port <PORT>` | - | Server port | - | `PORT`, `SERVER_PORT` |
|
|
355
|
+
*/
|
|
356
|
+
declare function renderOptionsTable(info: CommandInfo): string;
|
|
357
|
+
/**
|
|
358
|
+
* Render options as markdown list
|
|
359
|
+
*
|
|
360
|
+
* Features:
|
|
361
|
+
* - Uses kebab-case (cliName) for option names (e.g., `--dry-run` instead of `--dryRun`)
|
|
362
|
+
* - Appends env info at the end of each option (e.g., `[env: PORT, SERVER_PORT]`)
|
|
363
|
+
*
|
|
364
|
+
* @example
|
|
365
|
+
* - `-d`, `--dry-run` - Dry run mode (default: false)
|
|
366
|
+
* - `--port <PORT>` - Server port [env: PORT, SERVER_PORT]
|
|
367
|
+
*/
|
|
368
|
+
declare function renderOptionsList(info: CommandInfo): string;
|
|
369
|
+
/**
|
|
370
|
+
* Render subcommands as table
|
|
371
|
+
*/
|
|
372
|
+
declare function renderSubcommandsTable(info: CommandInfo, generateAnchors?: boolean): string;
|
|
373
|
+
/**
|
|
374
|
+
* Render options from array as table
|
|
375
|
+
*/
|
|
376
|
+
declare function renderOptionsTableFromArray(options: ResolvedFieldMeta[]): string;
|
|
377
|
+
/**
|
|
378
|
+
* Render options from array as list
|
|
379
|
+
*/
|
|
380
|
+
declare function renderOptionsListFromArray(options: ResolvedFieldMeta[]): string;
|
|
381
|
+
/**
|
|
382
|
+
* Render arguments from array as table
|
|
383
|
+
*/
|
|
384
|
+
declare function renderArgumentsTableFromArray(args: ResolvedFieldMeta[]): string;
|
|
385
|
+
/**
|
|
386
|
+
* Render arguments from array as list
|
|
387
|
+
*/
|
|
388
|
+
declare function renderArgumentsListFromArray(args: ResolvedFieldMeta[]): string;
|
|
389
|
+
/**
|
|
390
|
+
* Render subcommands from array as table
|
|
391
|
+
*/
|
|
392
|
+
declare function renderSubcommandsTableFromArray(subcommands: SubCommandInfo[], info: CommandInfo, generateAnchors?: boolean): string;
|
|
393
|
+
/**
|
|
394
|
+
* Render examples as markdown
|
|
395
|
+
*
|
|
396
|
+
* @example
|
|
397
|
+
* **Basic usage**
|
|
398
|
+
*
|
|
399
|
+
* ```bash
|
|
400
|
+
* $ greet World
|
|
401
|
+
* ```
|
|
402
|
+
*
|
|
403
|
+
* Output:
|
|
404
|
+
* ```
|
|
405
|
+
* Hello, World!
|
|
406
|
+
* ```
|
|
407
|
+
*/
|
|
408
|
+
declare function renderExamplesDefault(examples: Example[], results?: ExampleExecutionResult[], opts?: ExamplesRenderOptions): string;
|
|
409
|
+
/**
|
|
410
|
+
* Create command renderer with options
|
|
411
|
+
*/
|
|
412
|
+
declare function createCommandRenderer(options?: DefaultRendererOptions): RenderFunction;
|
|
413
|
+
/**
|
|
414
|
+
* Default renderers presets
|
|
415
|
+
*/
|
|
416
|
+
declare const defaultRenderers: {
|
|
417
|
+
/** Standard command documentation */
|
|
418
|
+
command: (options?: DefaultRendererOptions) => RenderFunction;
|
|
419
|
+
/** Table style options (default) */
|
|
420
|
+
tableStyle: RenderFunction;
|
|
421
|
+
/** List style options */
|
|
422
|
+
listStyle: RenderFunction;
|
|
423
|
+
};
|
|
424
|
+
//#endregion
|
|
425
|
+
//#region src/docs/doc-comparator.d.ts
|
|
426
|
+
/**
|
|
427
|
+
* Comparison result
|
|
428
|
+
*/
|
|
429
|
+
interface CompareResult {
|
|
430
|
+
/** Whether the content matches */
|
|
431
|
+
match: boolean;
|
|
432
|
+
/** Diff content (only when match is false) */
|
|
433
|
+
diff?: string;
|
|
434
|
+
/** Whether the file exists */
|
|
435
|
+
fileExists: boolean;
|
|
436
|
+
}
|
|
437
|
+
/**
|
|
438
|
+
* Compare generated content with existing file
|
|
439
|
+
*/
|
|
440
|
+
declare function compareWithExisting(generatedContent: string, filePath: string): CompareResult;
|
|
441
|
+
/**
|
|
442
|
+
* Format diff between two strings in unified diff format
|
|
443
|
+
*/
|
|
444
|
+
declare function formatDiff(expected: string, actual: string): string;
|
|
445
|
+
/**
|
|
446
|
+
* Write content to file, creating directories if needed
|
|
447
|
+
*/
|
|
448
|
+
declare function writeFile(filePath: string, content: string): void;
|
|
449
|
+
/**
|
|
450
|
+
* Minimal fs interface for deleteFile
|
|
451
|
+
*/
|
|
452
|
+
interface DeleteFileFs {
|
|
453
|
+
existsSync: typeof fs.existsSync;
|
|
454
|
+
unlinkSync: typeof fs.unlinkSync;
|
|
455
|
+
}
|
|
456
|
+
//#endregion
|
|
457
|
+
//#region src/docs/doc-generator.d.ts
|
|
458
|
+
/**
|
|
459
|
+
* Build CommandInfo from a command
|
|
460
|
+
*/
|
|
461
|
+
declare function buildCommandInfo(command: AnyCommand, rootName: string, commandPath?: string[]): Promise<CommandInfo>;
|
|
462
|
+
/**
|
|
463
|
+
* Collect all commands with their paths
|
|
464
|
+
* Returns a map of command path -> CommandInfo
|
|
465
|
+
*/
|
|
466
|
+
declare function collectAllCommands(command: AnyCommand, rootName?: string): Promise<Map<string, CommandInfo>>;
|
|
467
|
+
//#endregion
|
|
468
|
+
//#region src/docs/example-executor.d.ts
|
|
469
|
+
/**
|
|
470
|
+
* Execute examples for a command and capture output
|
|
471
|
+
*
|
|
472
|
+
* @param examples - Examples to execute
|
|
473
|
+
* @param config - Execution configuration (mock setup/cleanup)
|
|
474
|
+
* @param rootCommand - Root command to execute against
|
|
475
|
+
* @param commandPath - Command path for subcommands (e.g., ["config", "get"])
|
|
476
|
+
* @returns Array of execution results with captured stdout/stderr
|
|
477
|
+
*/
|
|
478
|
+
declare function executeExamples(examples: Example[], config: ExampleCommandConfig, rootCommand: AnyCommand, commandPath?: string[]): Promise<ExampleExecutionResult[]>;
|
|
479
|
+
//#endregion
|
|
480
|
+
//#region src/docs/golden-test.d.ts
|
|
481
|
+
/**
|
|
482
|
+
* Generate documentation from command definition
|
|
483
|
+
*/
|
|
484
|
+
declare function generateDoc(config: GenerateDocConfig): Promise<GenerateDocResult>;
|
|
485
|
+
/**
|
|
486
|
+
* Assert that documentation matches golden files
|
|
487
|
+
* Throws an error if there are differences and update mode is not enabled
|
|
488
|
+
*/
|
|
489
|
+
declare function assertDocMatch(config: GenerateDocConfig): Promise<void>;
|
|
490
|
+
/**
|
|
491
|
+
* Initialize documentation files by deleting them
|
|
492
|
+
* Only deletes when update mode is enabled (POLITTY_DOCS_UPDATE=true)
|
|
493
|
+
* Use this in beforeAll to ensure skipped tests don't leave stale sections
|
|
494
|
+
* @param config - Config containing files to initialize, or a single file path
|
|
495
|
+
* @param fileSystem - Optional fs implementation (useful when fs is mocked)
|
|
496
|
+
*/
|
|
497
|
+
declare function initDocFile(config: Pick<GenerateDocConfig, "files"> | string, fileSystem?: DeleteFileFs): void;
|
|
498
|
+
//#endregion
|
|
499
|
+
export { type ArgumentsRenderContext, type ArgumentsRenderFunction, COMMAND_MARKER_PREFIX, type CommandInfo, type DefaultRendererOptions, type DeleteFileFs, type ExampleCommandConfig, type ExampleConfig, type ExampleExecutionResult, type ExamplesRenderContext, type ExamplesRenderFunction, type ExamplesRenderOptions, type FileConfig, type FileMapping, type FormatterFunction, type GenerateDocConfig, type GenerateDocResult, type OptionsRenderContext, type OptionsRenderFunction, type RenderContentOptions, type RenderFunction, type SectionRenderFunction, type SimpleRenderContext, type SimpleRenderFunction, type SubCommandInfo, type SubcommandsRenderContext, type SubcommandsRenderFunction, type SubcommandsRenderOptions, UPDATE_GOLDEN_ENV, assertDocMatch, buildCommandInfo, collectAllCommands, commandEndMarker, commandStartMarker, compareWithExisting, createCommandRenderer, defaultRenderers, executeExamples, formatDiff, generateDoc, initDocFile, renderArgumentsList, renderArgumentsListFromArray, renderArgumentsTable, renderArgumentsTableFromArray, renderExamplesDefault, renderOptionsList, renderOptionsListFromArray, renderOptionsTable, renderOptionsTableFromArray, renderSubcommandsTable, renderSubcommandsTableFromArray, renderUsage, resolveLazyCommand, writeFile };
|
|
500
|
+
//# sourceMappingURL=index.d.cts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.cts","names":[],"sources":["../../src/executor/subcommand-router.ts","../../src/docs/types.ts","../../src/docs/default-renderers.ts","../../src/docs/doc-comparator.ts","../../src/docs/doc-generator.ts","../../src/docs/example-executor.ts","../../src/docs/golden-test.ts"],"sourcesContent":[],"mappings":"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"}
|