padrone 1.0.0 → 1.2.0

package/dist/codegen/index.d.mts

@@ -0,0 +1,305 @@
+import { StandardSchemaV1 } from "@standard-schema/spec";
+
+//#region src/codegen/types.d.ts
+/**
+ * Metadata for a single field/option/flag parsed from CLI help or completion data.
+ */
+interface FieldMeta {
+  name: string;
+  type: 'string' | 'number' | 'boolean' | 'array' | 'enum' | 'unknown';
+  /** For arrays: the item type */
+  items?: string;
+  /** For enums: the allowed values */
+  enumValues?: string[];
+  description?: string;
+  default?: unknown;
+  required?: boolean;
+  aliases?: string[];
+  positional?: boolean;
+  /** Mark fields the parser wasn't confident about */
+  ambiguous?: boolean;
+}
+/**
+ * Intermediate representation for a CLI command.
+ * All parsers produce these, all generators consume them.
+ */
+interface CommandMeta {
+  name: string;
+  description?: string;
+  aliases?: string[];
+  /** Named options/flags */
+  arguments?: FieldMeta[];
+  /** Positional arguments */
+  positionals?: FieldMeta[];
+  /** Recursive subcommands */
+  subcommands?: CommandMeta[];
+  examples?: string[];
+  deprecated?: boolean | string;
+}
+/**
+ * Logger interface for generators to report progress.
+ */
+interface GeneratorLogger {
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+  success(message: string): void;
+}
+/**
+ * Shared context passed to all generators.
+ */
+interface GeneratorContext {
+  /** Target output directory */
+  outDir: string;
+  /** Code builder factory */
+  createCodeBuilder: () => CodeBuilder;
+  /** File emitter for writing output */
+  emitter: FileEmitter;
+  /** Template engine */
+  template: TemplateFunction;
+  /** User-facing logger */
+  log: GeneratorLogger;
+}
+/**
+ * Result from CodeBuilder.build()
+ */
+interface CodeBuildResult {
+  /** The formatted source string */
+  text: string;
+  /** Resolved import map for deduplication across files */
+  imports: Map<string, {
+    specifiers: Set<string>;
+    typeOnly: boolean;
+  }>;
+}
+/**
+ * Fluent builder for constructing TypeScript source files.
+ */
+interface CodeBuilder {
+  /** Add a named import: import { specifier } from source */
+  import(specifier: string | string[], source: string): CodeBuilder;
+  /** Add a default import: import name from source */
+  importDefault(name: string, source: string): CodeBuilder;
+  /** Add a type-only import: import type { specifier } from source */
+  importType(specifier: string | string[], source: string): CodeBuilder;
+  /** Add a line of code (empty string or no argument for blank line) */
+  line(code?: string): CodeBuilder;
+  /** Add a nested block with automatic indentation */
+  block(builder: (b: CodeBuilder) => CodeBuilder): CodeBuilder;
+  /** Add a nested block with open/close strings */
+  block(open: string, builder: (b: CodeBuilder) => CodeBuilder, close?: string): CodeBuilder;
+  /** Add a nested block with open string, close string override, and builder */
+  block(open: string, close: string, builder: (b: CodeBuilder) => CodeBuilder): CodeBuilder;
+  /** Add a single-line comment */
+  comment(text: string): CodeBuilder;
+  /** Add a JSDoc comment */
+  docComment(text: string): CodeBuilder;
+  /** Add a TODO comment */
+  todoComment(text: string): CodeBuilder;
+  /** Add raw pre-formatted code (no indentation adjustment) */
+  raw(code: string): CodeBuilder;
+  /** Build the final source string */
+  build(): CodeBuildResult;
+}
+/**
+ * Result from FileEmitter.emit()
+ */
+interface EmitResult {
+  /** Files that were written */
+  written: string[];
+  /** Files that were skipped (already exist, no overwrite) */
+  skipped: string[];
+  /** Files that failed to write */
+  errors: {
+    file: string;
+    error: Error;
+  }[];
+}
+/**
+ * Options for creating a FileEmitter.
+ */
+interface FileEmitterOptions {
+  /** Target output directory */
+  outDir: string;
+  /** Header comment prepended to every file */
+  header?: string;
+  /** How to handle existing files: true = overwrite, false = skip */
+  overwrite?: boolean;
+  /** Print what would be written without writing */
+  dryRun?: boolean;
+}
+/**
+ * Manages writing multiple generated files to disk.
+ */
+interface FileEmitter {
+  /** Queue a file for writing */
+  addFile(path: string, content: string | CodeBuildResult): void;
+  /** Write all queued files to disk */
+  emit(): Promise<EmitResult>;
+}
+/**
+ * Template function returned by template().
+ */
+type TemplateFunction = (text: string) => (data: Record<string, unknown>) => string;
+//#endregion
+//#region src/codegen/code-builder.d.ts
+/**
+ * Create a new CodeBuilder for constructing TypeScript source files.
+ */
+declare function createCodeBuilder(): CodeBuilder;
+//#endregion
+//#region src/codegen/discovery.d.ts
+type DiscoverySource = 'help' | 'fish' | 'zsh';
+interface DiscoveryOptions {
+  /** The command to discover (e.g. 'gh', 'docker', 'kubectl'). */
+  command: string;
+  /** Which parsing sources to use. Default: ['help'] */
+  sources?: DiscoverySource[];
+  /** Max subcommand depth. 0 = root only, undefined = unlimited. */
+  depth?: number;
+  /** Delay in ms between help invocations. Default: 50 */
+  delay?: number;
+  /** Logger for progress reporting. */
+  log?: GeneratorLogger;
+  /** Timeout per help invocation in ms. Default: 10000 */
+  timeout?: number;
+}
+interface DiscoveryResult {
+  /** The discovered command tree. */
+  command: CommandMeta;
+  /** Number of help invocations made. */
+  invocations: number;
+  /** Errors encountered (non-fatal). */
+  warnings: string[];
+}
+/**
+ * Discover CLI structure by running --help recursively and optionally
+ * parsing shell completion scripts.
+ */
+declare function discoverCli(options: DiscoveryOptions): Promise<DiscoveryResult>;
+//#endregion
+//#region src/codegen/file-emitter.d.ts
+/**
+ * Create a FileEmitter for writing multiple generated files to disk.
+ */
+declare function createFileEmitter(options: FileEmitterOptions): FileEmitter;
+//#endregion
+//#region src/codegen/generators/barrel-file.d.ts
+/**
+ * Generate an index.ts barrel file that re-exports all given files.
+ */
+declare function generateBarrelFile(files: string[], ctx: GeneratorContext): CodeBuilder;
+//#endregion
+//#region src/codegen/generators/command-file.d.ts
+interface CommandFileOptions {
+  /** Wrap config: generates .wrap() instead of .action(). */
+  wrap?: {
+    /** The external command to wrap (e.g. 'gh'). */command: string; /** Fixed args preceding the options (e.g. ['pr', 'list']). */
+    args?: string[];
+  };
+  /** Subcommand references to wire into this command via .command() calls. */
+  subcommands?: {
+    name: string;
+    varName: string;
+    importPath: string;
+    aliases?: string[];
+  }[];
+}
+/**
+ * Generate a single Padrone command file from a CommandMeta.
+ * Produces a named function that chains .configure(), .arguments(), and .wrap() or .action().
+ */
+declare function generateCommandFile(command: CommandMeta, ctx: GeneratorContext, options?: CommandFileOptions): CodeBuilder;
+//#endregion
+//#region src/codegen/generators/command-tree.d.ts
+interface CommandTreeOptions {
+  /** When set, generates .wrap() calls instead of .action(). */
+  wrap?: {
+    /** The external command being wrapped (e.g. 'gh'). */command: string;
+  };
+}
+/**
+ * Walk a CommandMeta tree and emit one file per command plus a root program file.
+ * Maps nested subcommands to a directory structure.
+ */
+declare function generateCommandTree(root: CommandMeta, ctx: GeneratorContext, options?: CommandTreeOptions): void;
+//#endregion
+//#region src/codegen/parsers/fish.d.ts
+/**
+ * Parse fish shell completion scripts into CommandMeta.
+ *
+ * Fish completions use the `complete` builtin:
+ *   complete -c <command> -s <short> -l <long> -d <description> -a <arguments> -r -f
+ */
+declare function parseFishCompletions(text: string): CommandMeta;
+//#endregion
+//#region src/codegen/parsers/help.d.ts
+interface ParseHelpOptions {
+  /** Name to use for the root command if not detected from the help text */
+  name?: string;
+}
+/**
+ * Parse --help text output into CommandMeta.
+ * Handles common styles: GNU coreutils, Go cobra, Python argparse, Node commander/yargs, gh CLI.
+ */
+declare function parseHelpOutput(text: string, options?: ParseHelpOptions): CommandMeta;
+//#endregion
+//#region src/codegen/parsers/merge.d.ts
+/**
+ * Deep-merge multiple CommandMeta from different sources.
+ * Deduplicates fields, resolves conflicts, and combines subcommands.
+ *
+ * Later sources take precedence for descriptions and types,
+ * unless the earlier source was more specific (non-ambiguous).
+ */
+declare function mergeCommandMeta(...sources: CommandMeta[]): CommandMeta;
+//#endregion
+//#region src/codegen/parsers/zsh.d.ts
+/**
+ * Parse zsh completion function definitions into CommandMeta.
+ *
+ * Zsh completions typically use _arguments or compadd:
+ *   _arguments \
+ *     '-v[verbose mode]' \
+ *     '--output=[output file]:filename:_files' \
+ *     '1:command:(start stop restart)'
+ */
+declare function parseZshCompletions(text: string): CommandMeta;
+//#endregion
+//#region src/codegen/schema-to-code.d.ts
+interface SchemaToCodeResult {
+  /** The generated Zod source code */
+  code: string;
+  /** Imports needed (e.g. ['z']) */
+  imports: string[];
+}
+/**
+ * Generate Zod source code from a Standard Schema instance by introspecting
+ * its `~standard.jsonSchema` interface.
+ */
+declare function schemaToCode(schema: StandardSchemaV1): SchemaToCodeResult;
+/**
+ * Build a real Zod schema from FieldMeta objects.
+ * Returns the schema as Zod source code, since we can't dynamically import Zod here
+ * (codegen has no runtime dependency on padrone's main entry point).
+ */
+declare function fieldMetaToCode(fields: FieldMeta[]): SchemaToCodeResult;
+//#endregion
+//#region src/codegen/template.d.ts
+/**
+ * Lightweight string template engine.
+ *
+ * Syntax:
+ * - `{{var}}` — interpolation
+ * - `{{#arr}}...{{/arr}}` — iteration (`.` refers to current item)
+ * - `{{#bool}}...{{/bool}}` — conditional blocks
+ * - `{{>partial}}` — include a named sub-template
+ */
+type TemplateRenderer = (data: Record<string, unknown>, partials?: Record<string, string>) => string;
+/**
+ * Compile a template string into a reusable render function.
+ */
+declare function template(text: string): TemplateRenderer;
+//#endregion
+export { type CodeBuildResult, type CodeBuilder, type CommandFileOptions, type CommandMeta, type CommandTreeOptions, type DiscoveryOptions, type DiscoveryResult, type DiscoverySource, type EmitResult, type FieldMeta, type FileEmitter, type FileEmitterOptions, type GeneratorContext, type GeneratorLogger, type TemplateFunction, createCodeBuilder, createFileEmitter, discoverCli, fieldMetaToCode, generateBarrelFile, generateCommandFile, generateCommandTree, mergeCommandMeta, parseFishCompletions, parseHelpOutput, parseZshCompletions, schemaToCode, template };
+//# sourceMappingURL=index.d.mts.map

package/dist/codegen/index.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.mts","names":[],"sources":["../../src/codegen/types.ts","../../src/codegen/code-builder.ts","../../src/codegen/discovery.ts","../../src/codegen/file-emitter.ts","../../src/codegen/generators/barrel-file.ts","../../src/codegen/generators/command-file.ts","../../src/codegen/generators/command-tree.ts","../../src/codegen/parsers/fish.ts","../../src/codegen/parsers/help.ts","../../src/codegen/parsers/merge.ts","../../src/codegen/parsers/zsh.ts","../../src/codegen/schema-to-code.ts","../../src/codegen/template.ts"],"mappings":"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"}