padrone 1.1.0 → 1.2.0

package/src/codegen/parsers/zsh.ts

@@ -0,0 +1,221 @@
+import type { CommandMeta, FieldMeta } from '../types.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)'
+ */
+export function parseZshCompletions(text: string): CommandMeta {
+  const result: CommandMeta = {
+    name: '',
+    arguments: [],
+    positionals: [],
+    subcommands: [],
+  };
+
+  // Try to detect command name from function name: _command() or #compdef command
+  const compdefMatch = text.match(/#compdef\s+(\S+)/);
+  if (compdefMatch) {
+    result.name = compdefMatch[1]!;
+  } else {
+    const funcMatch = text.match(/^_(\w+)\s*\(\)/m);
+    if (funcMatch) {
+      result.name = funcMatch[1]!;
+    }
+  }
+
+  // Find _arguments blocks
+  const argumentsBlocks = findArgumentsBlocks(text);
+
+  for (const block of argumentsBlocks) {
+    const specs = parseArgumentSpecs(block);
+    for (const spec of specs) {
+      if (spec.positional) {
+        result.positionals!.push(spec);
+      } else {
+        result.arguments!.push(spec);
+      }
+    }
+  }
+
+  // Find subcommand definitions from case statements or _describe
+  const subcommands = findSubcommands(text);
+  result.subcommands!.push(...subcommands);
+
+  if (result.arguments!.length === 0) delete result.arguments;
+  if (result.positionals!.length === 0) delete result.positionals;
+  if (result.subcommands!.length === 0) delete result.subcommands;
+
+  return result;
+}
+
+/**
+ * Extract _arguments blocks from zsh completion text.
+ * Handles backslash continuation lines.
+ */
+function findArgumentsBlocks(text: string): string[] {
+  const blocks: string[] = [];
+
+  // Join continuation lines
+  const joined = text.replace(/\\\n\s*/g, ' ');
+  const lines = joined.split('\n');
+
+  for (const line of lines) {
+    const match = line.match(/_arguments\s+(.+)/);
+    if (match) {
+      blocks.push(match[1]!);
+    }
+  }
+
+  return blocks;
+}
+
+/**
+ * Parse individual argument specs from an _arguments line.
+ */
+function parseArgumentSpecs(block: string): FieldMeta[] {
+  const results: FieldMeta[] = [];
+
+  // Split into individual specs (quoted strings)
+  const specs = extractQuotedStrings(block);
+
+  for (const spec of specs) {
+    const field = parseZshSpec(spec);
+    if (field) results.push(field);
+  }
+
+  return results;
+}
+
+/**
+ * Extract single-quoted strings from an _arguments block.
+ */
+function extractQuotedStrings(text: string): string[] {
+  const strings: string[] = [];
+  const regex = /'([^']+)'/g;
+  let match: RegExpExecArray | null;
+
+  while ((match = regex.exec(text)) !== null) {
+    strings.push(match[1]!);
+  }
+
+  return strings;
+}
+
+/**
+ * Parse a single zsh argument spec.
+ *
+ * Formats:
+ *   '-v[verbose mode]'                              → boolean flag
+ *   '--output=[output file]:filename:_files'         → string with value
+ *   '(-v --verbose)'{-v,--verbose}'[verbose mode]'   → flag with aliases
+ *   '*--flag[repeatable]'                            → array
+ *   '1:command:(start stop restart)'                 → positional enum
+ *   ':filename:_files'                               → positional
+ */
+function parseZshSpec(spec: string): FieldMeta | null {
+  // Positional argument: 'N:description:action' or ':description:action'
+  const positionalMatch = spec.match(/^(\d+)?:([^:]*):(.*)$/);
+  if (positionalMatch) {
+    const description = positionalMatch[2] || undefined;
+
+    // Check for enum values in (val1 val2 val3)
+    const enumMatch = positionalMatch[3]?.match(/^\(([^)]+)\)$/);
+    if (enumMatch) {
+      const values = enumMatch[1]!.split(/\s+/);
+      return {
+        name: description?.toLowerCase().replace(/\s+/g, '_') || `arg${positionalMatch[1] || '0'}`,
+        type: 'enum',
+        enumValues: values,
+        description,
+        positional: true,
+      };
+    }
+
+    return {
+      name: description?.toLowerCase().replace(/\s+/g, '_') || `arg${positionalMatch[1] || '0'}`,
+      type: 'string',
+      description,
+      positional: true,
+      ambiguous: true,
+    };
+  }
+
+  // Flag argument
+  const repeatable = spec.startsWith('*');
+  const flagSpec = repeatable ? spec.slice(1) : spec;
+
+  // Extract flag name and description
+  // Pattern: --flag=[description]:value_description:action
+  // Pattern: -f[description]
+  const flagMatch = flagSpec.match(/^(-{1,2}[\w-]+)(?:=?)(?:\[([^\]]*)\])?(?::([^:]*):?(.*))?$/);
+  if (!flagMatch) return null;
+
+  const rawName = flagMatch[1]!;
+  const description = flagMatch[2] || undefined;
+  const valueName = flagMatch[3] || undefined;
+
+  const name = rawName.replace(/^-+/, '').replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+  const hasValue = rawName.includes('=') || !!valueName;
+  let type: FieldMeta['type'] = hasValue ? 'string' : 'boolean';
+
+  if (repeatable) type = 'array';
+
+  // Check for enum values
+  let enumValues: string[] | undefined;
+  if (flagMatch[4]) {
+    const enumMatch = flagMatch[4].match(/^\(([^)]+)\)$/);
+    if (enumMatch) {
+      enumValues = enumMatch[1]!.split(/\s+/);
+      type = 'enum';
+    }
+  }
+
+  return {
+    name,
+    type,
+    description,
+    enumValues,
+  };
+}
+
+/**
+ * Find subcommand definitions from _describe calls or case statements.
+ */
+function findSubcommands(text: string): CommandMeta[] {
+  const subcommands: CommandMeta[] = [];
+  const seen = new Set<string>();
+
+  // Look for _describe patterns: _describe 'command' commands
+  // where commands is an array like: ('start:start the service' 'stop:stop the service')
+  const describeRegex = /\(([^)]+)\)/g;
+  const joined = text.replace(/\\\n\s*/g, ' ');
+
+  // Look for arrays of 'name:description' patterns near _describe
+  let match: RegExpExecArray | null;
+  while ((match = describeRegex.exec(joined)) !== null) {
+    const content = match[1]!;
+    const entries = content.match(/'([^']+)'/g) || content.match(/"([^"]+)"/g);
+    if (!entries) continue;
+
+    for (const entry of entries) {
+      const clean = entry.replace(/^['"]|['"]$/g, '');
+      const parts = clean.split(':');
+      if (parts.length >= 2 && /^[\w-]+$/.test(parts[0]!)) {
+        const name = parts[0]!;
+        if (seen.has(name)) continue;
+        seen.add(name);
+        subcommands.push({
+          name,
+          description: parts.slice(1).join(':'),
+        });
+      }
+    }
+  }
+
+  return subcommands;
+}

package/src/codegen/schema-to-code.ts

@@ -0,0 +1,199 @@
+import type { StandardSchemaV1 } from '@standard-schema/spec';
+import type { FieldMeta } from './types.ts';
+
+interface SchemaToCodeResult {
+  /** The generated Zod source code */
+  code: string;
+  /** Imports needed (e.g. ['z']) */
+  imports: string[];
+}
+
+/**
+ * Convert a JSON Schema property to Zod code.
+ */
+function jsonSchemaPropertyToZod(prop: Record<string, any>, required: boolean, ambiguous?: boolean): string {
+  let code: string;
+
+  const type = prop.type as string | undefined;
+  const enumValues = prop.enum as unknown[] | undefined;
+
+  if (enumValues && enumValues.length > 0) {
+    const values = enumValues.map((v) => JSON.stringify(v)).join(', ');
+    code = `z.enum([${values}])`;
+  } else if (type === 'string') {
+    code = 'z.string()';
+  } else if (type === 'number' || type === 'integer') {
+    code = 'z.number()';
+  } else if (type === 'boolean') {
+    code = 'z.boolean()';
+  } else if (type === 'array') {
+    const items = prop.items as Record<string, any> | undefined;
+    const itemCode = items ? jsonSchemaPropertyToZod(items, true) : 'z.unknown()';
+    code = `${itemCode}.array()`;
+  } else {
+    code = 'z.unknown()';
+  }
+
+  if (prop.default !== undefined) {
+    code += `.default(${JSON.stringify(prop.default)})`;
+  } else if (!required) {
+    code += '.optional()';
+  }
+
+  if (prop.description) {
+    code += `.describe(${JSON.stringify(prop.description)})`;
+  }
+
+  if (ambiguous) {
+    code += ' /* TODO: verify type */';
+  }
+
+  return code;
+}
+
+/**
+ * Generate Zod source code from a Standard Schema instance by introspecting
+ * its `~standard.jsonSchema` interface.
+ */
+export function schemaToCode(schema: StandardSchemaV1): SchemaToCodeResult {
+  try {
+    const jsonSchema = (schema as any)['~standard'].jsonSchema.input({ target: 'draft-2020-12' }) as Record<string, any>;
+    return jsonSchemaToCode(jsonSchema);
+  } catch {
+    return { code: 'z.unknown()', imports: ['z'] };
+  }
+}
+
+function jsonSchemaToCode(jsonSchema: Record<string, any>): SchemaToCodeResult {
+  if (jsonSchema.type === 'object' && jsonSchema.properties) {
+    const properties = jsonSchema.properties as Record<string, any>;
+    const required = new Set((jsonSchema.required as string[]) || []);
+
+    const entries = Object.entries(properties).map(([key, prop]) => {
+      const isRequired = required.has(key);
+      const zodCode = jsonSchemaPropertyToZod(prop as Record<string, any>, isRequired);
+      return `  ${key}: ${zodCode},`;
+    });
+
+    const code = `z.object({\n${entries.join('\n')}\n})`;
+    return { code, imports: ['z'] };
+  }
+
+  // Fallback for non-object schemas
+  const code = jsonSchemaPropertyToZod(jsonSchema, true);
+  return { code, imports: ['z'] };
+}
+
+/**
+ * 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).
+ */
+export function fieldMetaToCode(fields: FieldMeta[]): SchemaToCodeResult {
+  const entries = fields.map((field) => {
+    let code: string;
+
+    switch (field.type) {
+      case 'string':
+        code = 'z.string()';
+        break;
+      case 'number':
+        code = 'z.number()';
+        break;
+      case 'boolean':
+        code = 'z.boolean()';
+        break;
+      case 'array': {
+        const itemType = field.items || 'string';
+        const itemCode = itemType === 'number' ? 'z.number()' : 'z.string()';
+        code = `${itemCode}.array()`;
+        break;
+      }
+      case 'enum':
+        if (field.enumValues && field.enumValues.length > 0) {
+          const values = field.enumValues.map((v) => JSON.stringify(v)).join(', ');
+          code = `z.enum([${values}])`;
+        } else {
+          code = 'z.string()';
+        }
+        break;
+      default:
+        code = 'z.unknown()';
+        break;
+    }
+
+    if (field.default !== undefined) {
+      code += `.default(${JSON.stringify(field.default)})`;
+    } else if (!field.required) {
+      code += '.optional()';
+    }
+
+    if (field.description) {
+      code += `.describe(${JSON.stringify(field.description)})`;
+    }
+
+    if (field.ambiguous) {
+      code += ' /* TODO: verify type */';
+    }
+
+    const key = needsQuoting(field.name) ? JSON.stringify(field.name) : field.name;
+    return `  ${key}: ${code},`;
+  });
+
+  const code = `z.object({\n${entries.join('\n')}\n})`;
+  return { code, imports: ['z'] };
+}
+
+const JS_RESERVED = new Set([
+  'break',
+  'case',
+  'catch',
+  'continue',
+  'debugger',
+  'default',
+  'delete',
+  'do',
+  'else',
+  'export',
+  'extends',
+  'finally',
+  'for',
+  'function',
+  'if',
+  'import',
+  'in',
+  'instanceof',
+  'new',
+  'return',
+  'super',
+  'switch',
+  'this',
+  'throw',
+  'try',
+  'typeof',
+  'var',
+  'void',
+  'while',
+  'with',
+  'yield',
+  'class',
+  'const',
+  'enum',
+  'let',
+  'static',
+  'implements',
+  'interface',
+  'package',
+  'private',
+  'protected',
+  'public',
+  'await',
+  'async',
+]);
+
+/** Returns true if the name needs quoting to be a valid JS object key. */
+function needsQuoting(name: string): boolean {
+  if (JS_RESERVED.has(name)) return true;
+  // Must be a valid identifier: starts with letter/$/_, contains only word chars
+  return !/^[a-zA-Z_$][\w$]*$/.test(name);
+}

package/src/codegen/template.ts

@@ -0,0 +1,69 @@
+/**
+ * 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.
+ */
+export function template(text: string): TemplateRenderer {
+  return (data: Record<string, unknown>, partials?: Record<string, string>) => {
+    return render(text, data, partials);
+  };
+}
+
+function render(text: string, data: Record<string, unknown>, partials?: Record<string, string>): string {
+  let result = text;
+
+  // Process block sections: {{#key}}...{{/key}}
+  result = result.replace(/\{\{#(\w+)\}\}([\s\S]*?)\{\{\/\1\}\}/g, (_match, key: string, body: string) => {
+    const value = data[key];
+
+    if (value === undefined || value === null || value === false) {
+      return '';
+    }
+
+    if (Array.isArray(value)) {
+      return value
+        .map((item) => {
+          if (typeof item === 'object' && item !== null) {
+            return render(body, item as Record<string, unknown>, partials);
+          }
+          // For primitive items, replace {{.}} with the item value
+          return body.replace(/\{\{\.\}\}/g, String(item));
+        })
+        .join('');
+    }
+
+    // Truthy conditional
+    if (typeof value === 'object') {
+      return render(body, value as Record<string, unknown>, partials);
+    }
+    return render(body, data, partials);
+  });
+
+  // Process partials: {{>partialName}}
+  if (partials) {
+    result = result.replace(/\{\{>(\w+)\}\}/g, (_match, name: string) => {
+      const partialText = partials[name];
+      if (!partialText) return '';
+      return render(partialText, data, partials);
+    });
+  }
+
+  // Process interpolation: {{var}}
+  result = result.replace(/\{\{(\w+)\}\}/g, (_match, key: string) => {
+    const value = data[key];
+    if (value === undefined || value === null) return '';
+    return String(value);
+  });
+
+  return result;
+}

package/src/codegen/types.ts

@@ -0,0 +1,143 @@
+/**
+ * Metadata for a single field/option/flag parsed from CLI help or completion data.
+ */
+export 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.
+ */
+export 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.
+ */
+export interface GeneratorLogger {
+  info(message: string): void;
+  warn(message: string): void;
+  error(message: string): void;
+  success(message: string): void;
+}
+
+/**
+ * Shared context passed to all generators.
+ */
+export 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()
+ */
+export 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.
+ */
+export 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()
+ */
+export 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.
+ */
+export 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.
+ */
+export 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().
+ */
+export type TemplateFunction = (text: string) => (data: Record<string, unknown>) => string;

package/src/colorizer.ts

@@ -16,7 +16,7 @@ const colors = {
 
 export type Colorizer = {
   command: (text: string) => string;
-  option: (text: string) => string;
+  arg: (text: string) => string;
   type: (text: string) => string;
   description: (text: string) => string;
   label: (text: string) => string;
@@ -29,7 +29,7 @@ export type Colorizer = {
 export function createColorizer(): Colorizer {
   return {
     command: (text: string) => `${colors.cyan}${colors.bold}${text}${colors.reset}`,
-    option: (text: string) => `${colors.green}${text}${colors.reset}`,
+    arg: (text: string) => `${colors.green}${text}${colors.reset}`,
     type: (text: string) => `${colors.yellow}${text}${colors.reset}`,
     description: (text: string) => `${colors.dim}${text}${colors.reset}`,
     label: (text: string) => `${colors.bold}${text}${colors.reset}`,