padrone 1.1.0 → 1.2.0

package/src/codegen/generators/command-file.ts

@@ -0,0 +1,184 @@
+import { fieldMetaToCode } from '../schema-to-code.ts';
+import type { CodeBuilder, CommandMeta, FieldMeta, GeneratorContext } from '../types.ts';
+
+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',
+]);
+
+/** Convert a command name to a safe JS identifier (camelCase, reserved-word-safe). */
+export function toSafeIdentifier(name: string): string {
+  const camel = name.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase());
+  if (/^\d/.test(camel)) return `_${camel}`;
+  if (JS_RESERVED.has(camel)) return `_${camel}`;
+  return camel;
+}
+
+/** Build the exported function name for a command (e.g. 'repo' → 'repoCommand'). */
+export function toCommandFunctionName(name: string): string {
+  return `${toSafeIdentifier(name)}Command`;
+}
+
+export 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().
+ */
+export function generateCommandFile(command: CommandMeta, ctx: GeneratorContext, options?: CommandFileOptions): CodeBuilder {
+  const code = ctx.createCodeBuilder();
+
+  const hasArgs = (command.arguments && command.arguments.length > 0) || (command.positionals && command.positionals.length > 0);
+
+  if (hasArgs) {
+    code.import('z', 'zod/v4');
+  }
+
+  code.importType('AnyPadroneBuilder', 'padrone');
+
+  // Import subcommand modules
+  if (options?.subcommands) {
+    for (const sub of options.subcommands) {
+      code.import([sub.varName], sub.importPath);
+    }
+  }
+
+  code.line();
+
+  if (command.deprecated) {
+    const msg = typeof command.deprecated === 'string' ? command.deprecated : 'This command is deprecated';
+    code.comment(`@deprecated ${msg}`);
+  }
+
+  const fnName = toCommandFunctionName(command.name);
+  code.line(`export function ${fnName}<T extends AnyPadroneBuilder>(cmd: T) {`);
+  code.line(`  return cmd`);
+
+  // .configure()
+  const configParts: string[] = [];
+  if (command.description) {
+    configParts.push(`description: ${JSON.stringify(command.description)}`);
+  }
+  if (command.deprecated) {
+    configParts.push(`deprecated: ${typeof command.deprecated === 'string' ? JSON.stringify(command.deprecated) : 'true'}`);
+  }
+  if (configParts.length > 0) {
+    code.line(`    .configure({ ${configParts.join(', ')} })`);
+  }
+
+  // .arguments()
+  if (hasArgs) {
+    const allFields = [...(command.arguments || []), ...(command.positionals || [])];
+    const schemaCode = fieldMetaToCode(allFields);
+
+    const positionalNames = (command.positionals || []).map((p) => (p.type === 'array' ? `'...${p.name}'` : `'${p.name}'`));
+    const fieldsMap = buildFieldsMap(allFields);
+    const hasMetaOptions = positionalNames.length > 0 || fieldsMap;
+
+    if (hasMetaOptions) {
+      code.line(`    .arguments(${schemaCode.code}, {`);
+      if (positionalNames.length > 0) {
+        code.line(`      positional: [${positionalNames.join(', ')}],`);
+      }
+      if (fieldsMap) {
+        code.line(`      fields: ${fieldsMap},`);
+      }
+      code.line(`    })`);
+    } else {
+      code.line(`    .arguments(${schemaCode.code})`);
+    }
+  }
+
+  // .command() calls for subcommands
+  if (options?.subcommands) {
+    for (const sub of options.subcommands) {
+      const nameArg =
+        sub.aliases && sub.aliases.length > 0
+          ? `[${JSON.stringify(sub.name)}, ${sub.aliases.map((a) => JSON.stringify(a)).join(', ')}]`
+          : JSON.stringify(sub.name);
+      code.line(`    .command(${nameArg}, ${sub.varName})`);
+    }
+  }
+
+  // .wrap() or .action()
+  if (options?.wrap) {
+    const wrapParts: string[] = [];
+    wrapParts.push(`command: ${JSON.stringify(options.wrap.command)}`);
+    if (options.wrap.args && options.wrap.args.length > 0) {
+      wrapParts.push(`args: [${options.wrap.args.map((a) => JSON.stringify(a)).join(', ')}]`);
+    }
+    code.line(`    .wrap({ ${wrapParts.join(', ')} })`);
+  } else {
+    code.line(`    .action((args) => { /* TODO */ })`);
+  }
+
+  code.line(`}`);
+
+  return code;
+}
+
+function buildFieldsMap(fields: FieldMeta[]): string | null {
+  const entries: string[] = [];
+  for (const field of fields) {
+    if (field.aliases && field.aliases.length > 0) {
+      const alias =
+        field.aliases.length === 1 ? JSON.stringify(field.aliases[0]) : `[${field.aliases.map((a) => JSON.stringify(a)).join(', ')}]`;
+      const key = /^[a-zA-Z_$][\w$]*$/.test(field.name) ? field.name : JSON.stringify(field.name);
+      entries.push(`${key}: { alias: ${alias} }`);
+    }
+  }
+  if (entries.length === 0) return null;
+  return `{ ${entries.join(', ')} }`;
+}

package/src/codegen/generators/command-tree.ts

@@ -0,0 +1,124 @@
+import { fieldMetaToCode } from '../schema-to-code.ts';
+import type { CommandMeta, GeneratorContext } from '../types.ts';
+import type { CommandFileOptions } from './command-file.ts';
+import { generateCommandFile, toCommandFunctionName } from './command-file.ts';
+
+export 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.
+ */
+export function generateCommandTree(root: CommandMeta, ctx: GeneratorContext, options?: CommandTreeOptions): void {
+  const rootImports: { name: string; varName: string; path: string; aliases?: string[] }[] = [];
+
+  // Recursively generate command files (depth-first so children exist before parents)
+  function walkCommands(cmd: CommandMeta, dirPath: string, parentArgs: string[]): void {
+    if (cmd === root) {
+      for (const sub of cmd.subcommands || []) {
+        walkCommands(sub, 'commands', []);
+      }
+      return;
+    }
+
+    const filePath = `${dirPath}/${cmd.name}.ts`;
+
+    // Recurse into subcommands first so we can reference them
+    const childRefs: { name: string; varName: string; importPath: string; aliases?: string[] }[] = [];
+    if (cmd.subcommands && cmd.subcommands.length > 0) {
+      for (const sub of cmd.subcommands) {
+        walkCommands(sub, `${dirPath}/${cmd.name}`, [...parentArgs, cmd.name]);
+        childRefs.push({
+          name: sub.name,
+          varName: toCommandFunctionName(sub.name),
+          importPath: `./${cmd.name}/${sub.name}.ts`,
+          aliases: sub.aliases,
+        });
+      }
+    }
+
+    const fileOptions: CommandFileOptions = {};
+    if (options?.wrap) {
+      fileOptions.wrap = { command: options.wrap.command, args: [...parentArgs, cmd.name] };
+    }
+    if (childRefs.length > 0) {
+      fileOptions.subcommands = childRefs;
+    }
+
+    const code = generateCommandFile(cmd, ctx, Object.keys(fileOptions).length > 0 ? fileOptions : undefined);
+    ctx.emitter.addFile(filePath, code.build());
+
+    rootImports.push({
+      name: cmd.name,
+      varName: toCommandFunctionName(cmd.name),
+      path: `./${filePath.replace(/\.ts$/, '.ts')}`,
+      aliases: cmd.aliases,
+    });
+  }
+
+  walkCommands(root, '', []);
+
+  // Generate root program.ts
+  const program = ctx.createCodeBuilder();
+
+  const rootHasArgs = (root.arguments && root.arguments.length > 0) || (root.positionals && root.positionals.length > 0);
+  if (rootHasArgs) {
+    program.import('z', 'zod/v4');
+  }
+  program.import(['createPadrone'], 'padrone');
+
+  // Only import direct children of root
+  const directChildren = rootImports.filter((imp) => imp.path.split('/').length <= 3);
+  for (const imp of directChildren) {
+    program.import([imp.varName], imp.path);
+  }
+
+  program.line();
+  program.line(`const program = createPadrone(${JSON.stringify(root.name)})`);
+
+  // .configure()
+  const configParts: string[] = [];
+  if (root.description) {
+    configParts.push(`description: ${JSON.stringify(root.description)}`);
+  }
+  if (configParts.length > 0) {
+    program.line(`  .configure({ ${configParts.join(', ')} })`);
+  }
+
+  // Root arguments (for programs that have options at the root level)
+  if (rootHasArgs) {
+    const allFields = [...(root.arguments || []), ...(root.positionals || [])];
+    const schemaCode = fieldMetaToCode(allFields);
+    program.line(`  .arguments(${schemaCode.code})`);
+  }
+
+  // Chain .command() calls for direct children
+  for (const imp of directChildren) {
+    const nameArg =
+      imp.aliases && imp.aliases.length > 0
+        ? `[${JSON.stringify(imp.name)}, ${imp.aliases.map((a) => JSON.stringify(a)).join(', ')}]`
+        : JSON.stringify(imp.name);
+    program.line(`  .command(${nameArg}, ${imp.varName})`);
+  }
+
+  // If root has no subcommands, add .wrap() or .action()
+  if (directChildren.length === 0 && options?.wrap) {
+    program.line(`  .wrap({ command: ${JSON.stringify(options.wrap.command)} })`);
+  }
+
+  program.line();
+  program.line(`export default program`);
+
+  ctx.emitter.addFile('program.ts', program.build());
+
+  // Generate index.ts
+  const index = ctx.createCodeBuilder();
+  index.line(`export { default } from './program.ts'`);
+  ctx.emitter.addFile('index.ts', index.build());
+}

package/src/codegen/index.ts

@@ -0,0 +1,33 @@
+// Types
+
+// Core utilities
+export { createCodeBuilder } from './code-builder.ts';
+export type { DiscoveryOptions, DiscoveryResult, DiscoverySource } from './discovery.ts';
+// Discovery
+export { discoverCli } from './discovery.ts';
+export { createFileEmitter } from './file-emitter.ts';
+// Generators
+export { generateBarrelFile } from './generators/barrel-file.ts';
+export type { CommandFileOptions } from './generators/command-file.ts';
+export { generateCommandFile } from './generators/command-file.ts';
+export type { CommandTreeOptions } from './generators/command-tree.ts';
+export { generateCommandTree } from './generators/command-tree.ts';
+// Parsers
+export { parseFishCompletions } from './parsers/fish.ts';
+export { parseHelpOutput } from './parsers/help.ts';
+export { mergeCommandMeta } from './parsers/merge.ts';
+export { parseZshCompletions } from './parsers/zsh.ts';
+export { fieldMetaToCode, schemaToCode } from './schema-to-code.ts';
+export { template } from './template.ts';
+export type {
+  CodeBuilder,
+  CodeBuildResult,
+  CommandMeta,
+  EmitResult,
+  FieldMeta,
+  FileEmitter,
+  FileEmitterOptions,
+  GeneratorContext,
+  GeneratorLogger,
+  TemplateFunction,
+} from './types.ts';

package/src/codegen/parsers/fish.ts

@@ -0,0 +1,163 @@
+import type { CommandMeta, FieldMeta } from '../types.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
+ */
+export function parseFishCompletions(text: string): CommandMeta {
+  const lines = text.split('\n');
+  const result: CommandMeta = {
+    name: '',
+    arguments: [],
+    subcommands: [],
+  };
+
+  const subcommandMap = new Map<string, CommandMeta>();
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+
+    // Match: complete -c <command> [options]
+    const completeMatch = trimmed.match(/^complete\s+/);
+    if (!completeMatch) continue;
+
+    const parts = parseCompleteLine(trimmed);
+    if (!parts) continue;
+
+    // Set root command name
+    if (!result.name && parts.command) {
+      result.name = parts.command;
+    }
+
+    // If this completion has a condition like "__fish_seen_subcommand_from <sub>"
+    // it belongs to a subcommand
+    const subcommandCondition = parts.condition?.match(/__fish_seen_subcommand_from\s+(\S+)/);
+    if (subcommandCondition) {
+      const subName = subcommandCondition[1]!;
+      let sub = subcommandMap.get(subName);
+      if (!sub) {
+        sub = { name: subName, arguments: [] };
+        subcommandMap.set(subName, sub);
+      }
+
+      if (parts.longFlag || parts.shortFlag) {
+        const field = completionToField(parts);
+        if (field) sub.arguments!.push(field);
+      }
+      continue;
+    }
+
+    // If this defines a subcommand (has -a with no flags)
+    if (parts.arguments && !parts.longFlag && !parts.shortFlag) {
+      // Arguments list could be subcommand names
+      const names = parts.arguments.split(/\s+/);
+      for (const name of names) {
+        if (!name || name.startsWith('(')) continue;
+        if (!subcommandMap.has(name)) {
+          subcommandMap.set(name, {
+            name,
+            description: parts.description,
+            arguments: [],
+          });
+        } else if (parts.description) {
+          subcommandMap.get(name)!.description = parts.description;
+        }
+      }
+      continue;
+    }
+
+    // Global option
+    if (parts.longFlag || parts.shortFlag) {
+      const field = completionToField(parts);
+      if (field) result.arguments!.push(field);
+    }
+  }
+
+  // Add subcommands
+  for (const sub of subcommandMap.values()) {
+    if (sub.arguments!.length === 0) delete sub.arguments;
+    result.subcommands!.push(sub);
+  }
+
+  if (result.arguments!.length === 0) delete result.arguments;
+  if (result.subcommands!.length === 0) delete result.subcommands;
+
+  return result;
+}
+
+interface CompleteParts {
+  command?: string;
+  shortFlag?: string;
+  longFlag?: string;
+  description?: string;
+  arguments?: string;
+  condition?: string;
+  requiresArg?: boolean;
+  noFiles?: boolean;
+}
+
+function parseCompleteLine(line: string): CompleteParts | null {
+  const parts: CompleteParts = {};
+
+  // Extract -c <command>
+  const cmdMatch = line.match(/-c\s+(\S+)/);
+  if (cmdMatch) parts.command = cmdMatch[1];
+
+  // Extract -s <short>
+  const shortMatch = line.match(/-s\s+(\S+)/);
+  if (shortMatch) parts.shortFlag = shortMatch[1];
+
+  // Extract -l <long>
+  const longMatch = line.match(/-l\s+(\S+)/);
+  if (longMatch) parts.longFlag = longMatch[1];
+
+  // Extract -d '<description>' or -d "<description>"
+  const descMatch = line.match(/-d\s+['"]([^'"]+)['"]/) || line.match(/-d\s+(\S+)/);
+  if (descMatch) parts.description = descMatch[1];
+
+  // Extract -a '<arguments>'
+  const argsMatch = line.match(/-a\s+['"]([^'"]+)['"]/) || line.match(/-a\s+(\S+)/);
+  if (argsMatch) parts.arguments = argsMatch[1];
+
+  // Extract -n '<condition>'
+  const condMatch = line.match(/-n\s+['"]([^'"]+)['"]/) || line.match(/-n\s+(\S+)/);
+  if (condMatch) parts.condition = condMatch[1];
+
+  // -r means requires argument
+  parts.requiresArg = /-r\b/.test(line);
+  // -f means no file completion
+  parts.noFiles = /-f\b/.test(line);
+
+  return parts;
+}
+
+function completionToField(parts: CompleteParts): FieldMeta | null {
+  const name = parts.longFlag ? parts.longFlag.replace(/-([a-z])/g, (_, c: string) => c.toUpperCase()) : parts.shortFlag || '';
+
+  if (!name) return null;
+
+  let type: FieldMeta['type'] = parts.requiresArg ? 'string' : 'boolean';
+  let enumValues: string[] | undefined;
+
+  // If -a provides specific values, treat as enum
+  if (parts.arguments) {
+    const values = parts.arguments.split(/\s+/).filter((v) => !v.startsWith('('));
+    if (values.length > 0 && values.length <= 20) {
+      enumValues = values;
+      type = 'enum';
+    }
+  }
+
+  const aliases = parts.shortFlag && parts.longFlag ? [`-${parts.shortFlag}`] : undefined;
+
+  return {
+    name,
+    type,
+    description: parts.description,
+    aliases,
+    enumValues,
+  };
+}