padrone 1.0.0 → 1.2.0

package/src/codegen/code-builder.ts

@@ -0,0 +1,226 @@
+import type { CodeBuilder, CodeBuildResult } from './types.ts';
+
+interface ImportEntry {
+  specifiers: Set<string>;
+  defaultSpecifier?: string;
+  typeOnly: boolean;
+}
+
+interface CodeLine {
+  type: 'line' | 'raw' | 'block-open' | 'block-close';
+  content: string;
+}
+
+class CodeBuilderImpl implements CodeBuilder {
+  private imports = new Map<string, ImportEntry>();
+  private lines: CodeLine[] = [];
+  private indent: number;
+
+  constructor(indent = 0) {
+    this.indent = indent;
+  }
+
+  import(specifier: string | string[], source: string): CodeBuilder {
+    const specs = Array.isArray(specifier) ? specifier : [specifier];
+    const existing = this.imports.get(source);
+    if (existing) {
+      for (const s of specs) existing.specifiers.add(s);
+      // If we're adding a value import and existing was type-only, downgrade to value
+      existing.typeOnly = false;
+    } else {
+      this.imports.set(source, { specifiers: new Set(specs), typeOnly: false });
+    }
+    return this;
+  }
+
+  importDefault(name: string, source: string): CodeBuilder {
+    const existing = this.imports.get(source);
+    if (existing) {
+      existing.defaultSpecifier = name;
+      existing.typeOnly = false;
+    } else {
+      this.imports.set(source, { specifiers: new Set(), defaultSpecifier: name, typeOnly: false });
+    }
+    return this;
+  }
+
+  importType(specifier: string | string[], source: string): CodeBuilder {
+    const specs = Array.isArray(specifier) ? specifier : [specifier];
+    const existing = this.imports.get(source);
+    if (existing) {
+      for (const s of specs) existing.specifiers.add(s);
+      // Don't downgrade: if existing is value import, keep it as value
+    } else {
+      this.imports.set(source, { specifiers: new Set(specs), typeOnly: true });
+    }
+    return this;
+  }
+
+  line(code?: string): CodeBuilder {
+    this.lines.push({ type: 'line', content: code ?? '' });
+    return this;
+  }
+
+  block(
+    openOrBuilder: string | ((b: CodeBuilder) => CodeBuilder),
+    builderOrClose?: string | ((b: CodeBuilder) => CodeBuilder),
+    closeOrBuilder?: string | ((b: CodeBuilder) => CodeBuilder),
+  ): CodeBuilder {
+    let open: string | undefined;
+    let close: string | undefined;
+    let builder: (b: CodeBuilder) => CodeBuilder;
+
+    if (typeof openOrBuilder === 'function') {
+      // block(builder)
+      builder = openOrBuilder;
+    } else if (typeof builderOrClose === 'function') {
+      // block(open, builder, close?)
+      open = openOrBuilder;
+      builder = builderOrClose;
+      close = typeof closeOrBuilder === 'string' ? closeOrBuilder : undefined;
+    } else if (typeof closeOrBuilder === 'function') {
+      // block(open, close, builder)
+      open = openOrBuilder;
+      close = typeof builderOrClose === 'string' ? builderOrClose : undefined;
+      builder = closeOrBuilder;
+    } else {
+      throw new Error('Invalid block() arguments');
+    }
+
+    // Always push block-open to increment indent
+    this.lines.push({ type: 'block-open', content: open ?? '' });
+
+    const inner = new CodeBuilderImpl(this.indent + 1);
+    builder(inner);
+
+    // Merge inner imports into ours
+    for (const [source, entry] of inner.imports) {
+      const existing = this.imports.get(source);
+      if (existing) {
+        for (const s of entry.specifiers) existing.specifiers.add(s);
+        if (entry.defaultSpecifier) existing.defaultSpecifier = entry.defaultSpecifier;
+        if (!entry.typeOnly) existing.typeOnly = false;
+      } else {
+        this.imports.set(source, {
+          specifiers: new Set(entry.specifiers),
+          defaultSpecifier: entry.defaultSpecifier,
+          typeOnly: entry.typeOnly,
+        });
+      }
+    }
+
+    // Merge inner lines with extra indentation
+    for (const line of inner.lines) {
+      this.lines.push(line);
+    }
+
+    // Always push block-close to decrement indent
+    this.lines.push({ type: 'block-close', content: close ?? '' });
+
+    return this;
+  }
+
+  comment(text: string): CodeBuilder {
+    this.lines.push({ type: 'line', content: `// ${text}` });
+    return this;
+  }
+
+  docComment(text: string): CodeBuilder {
+    const lines = text.split('\n');
+    if (lines.length === 1) {
+      this.lines.push({ type: 'line', content: `/** ${text} */` });
+    } else {
+      this.lines.push({ type: 'line', content: '/**' });
+      for (const line of lines) {
+        this.lines.push({ type: 'line', content: ` * ${line}` });
+      }
+      this.lines.push({ type: 'line', content: ' */' });
+    }
+    return this;
+  }
+
+  todoComment(text: string): CodeBuilder {
+    this.lines.push({ type: 'line', content: `// TODO: ${text}` });
+    return this;
+  }
+
+  raw(code: string): CodeBuilder {
+    this.lines.push({ type: 'raw', content: code });
+    return this;
+  }
+
+  build(): CodeBuildResult {
+    const parts: string[] = [];
+
+    // Emit imports first
+    if (this.imports.size > 0) {
+      const typeImports: string[] = [];
+      const valueImports: string[] = [];
+
+      for (const [source, entry] of this.imports) {
+        const specs = [...entry.specifiers].sort();
+        const namedPart =
+          specs.length > 0 ? (specs.length === 1 && !specs[0]!.includes(' ') ? `{ ${specs[0]} }` : `{ ${specs.join(', ')} }`) : null;
+        const specStr = entry.defaultSpecifier
+          ? namedPart
+            ? `${entry.defaultSpecifier}, ${namedPart}`
+            : entry.defaultSpecifier
+          : namedPart!;
+
+        const line = entry.typeOnly ? `import type ${specStr} from '${source}'` : `import ${specStr} from '${source}'`;
+
+        if (entry.typeOnly) {
+          typeImports.push(line);
+        } else {
+          valueImports.push(line);
+        }
+      }
+
+      // Value imports first, then type imports
+      parts.push([...valueImports, ...typeImports].join('\n'));
+      parts.push('');
+    }
+
+    // Emit code lines
+    let currentIndent = this.indent;
+    for (const line of this.lines) {
+      if (line.type === 'raw') {
+        parts.push(line.content);
+      } else if (line.type === 'block-open') {
+        if (line.content) {
+          const indent = '  '.repeat(currentIndent);
+          parts.push(`${indent}${line.content}`);
+        }
+        currentIndent++;
+      } else if (line.type === 'block-close') {
+        currentIndent--;
+        if (line.content) {
+          const indent = '  '.repeat(currentIndent);
+          parts.push(`${indent}${line.content}`);
+        }
+      } else {
+        // Regular line
+        if (line.content === '') {
+          parts.push('');
+        } else {
+          const indent = '  '.repeat(currentIndent);
+          parts.push(`${indent}${line.content}`);
+        }
+      }
+    }
+
+    return {
+      text: parts.join('\n'),
+      imports: new Map(
+        [...this.imports].map(([source, entry]) => [source, { specifiers: new Set(entry.specifiers), typeOnly: entry.typeOnly }]),
+      ),
+    };
+  }
+}
+
+/**
+ * Create a new CodeBuilder for constructing TypeScript source files.
+ */
+export function createCodeBuilder(): CodeBuilder {
+  return new CodeBuilderImpl();
+}

package/src/codegen/discovery.ts

@@ -0,0 +1,232 @@
+import { parseFishCompletions } from './parsers/fish.ts';
+import { parseHelpOutput } from './parsers/help.ts';
+import { mergeCommandMeta } from './parsers/merge.ts';
+import { parseZshCompletions } from './parsers/zsh.ts';
+import type { CommandMeta, GeneratorLogger } from './types.ts';
+
+export type DiscoverySource = 'help' | 'fish' | 'zsh';
+
+export 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;
+}
+
+export 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.
+ */
+export async function discoverCli(options: DiscoveryOptions): Promise<DiscoveryResult> {
+  const { command, sources = ['help'], depth, delay = 50, log, timeout = 10000 } = options;
+
+  const warnings: string[] = [];
+  let invocations = 0;
+
+  const results: CommandMeta[] = [];
+
+  // Source 1: --help recursive crawl
+  if (sources.includes('help')) {
+    log?.info(`Discovering ${command} via --help...`);
+    const helpResult = await crawlHelp(command, [], {
+      depth,
+      delay,
+      timeout,
+      log,
+      onInvocation: () => {
+        invocations++;
+      },
+      onWarning: (msg) => {
+        warnings.push(msg);
+      },
+    });
+    results.push(helpResult);
+  }
+
+  // Source 2: Fish completions
+  if (sources.includes('fish')) {
+    log?.info(`Parsing fish completions for ${command}...`);
+    const fishText = await getCompletionScript(command, 'fish', timeout);
+    if (fishText) {
+      results.push(parseFishCompletions(fishText));
+    } else {
+      warnings.push('Could not obtain fish completion script');
+    }
+  }
+
+  // Source 3: Zsh completions
+  if (sources.includes('zsh')) {
+    log?.info(`Parsing zsh completions for ${command}...`);
+    const zshText = await getCompletionScript(command, 'zsh', timeout);
+    if (zshText) {
+      results.push(parseZshCompletions(zshText));
+    } else {
+      warnings.push('Could not obtain zsh completion script');
+    }
+  }
+
+  const merged = results.length > 0 ? mergeCommandMeta(...results) : { name: command };
+
+  // Ensure the root has the correct name
+  if (!merged.name) merged.name = command;
+
+  return { command: merged, invocations, warnings };
+}
+
+interface CrawlOptions {
+  depth?: number;
+  delay: number;
+  timeout: number;
+  log?: GeneratorLogger;
+  onInvocation: () => void;
+  onWarning: (msg: string) => void;
+}
+
+/**
+ * Breadth-first crawl of --help output.
+ */
+async function crawlHelp(command: string, prefixArgs: string[], options: CrawlOptions): Promise<CommandMeta> {
+  const fullCmd = [command, ...prefixArgs].join(' ');
+
+  options.onInvocation();
+  const helpText = await runHelp(command, prefixArgs, options.timeout);
+
+  if (!helpText) {
+    options.onWarning(`No help output from: ${fullCmd} --help`);
+    return { name: prefixArgs[prefixArgs.length - 1] || command };
+  }
+
+  const name = prefixArgs[prefixArgs.length - 1] || command;
+  const parsed = parseHelpOutput(helpText, { name });
+
+  options.log?.info(`  ${fullCmd}: ${parsed.subcommands?.length || 0} subcommands, ${parsed.arguments?.length || 0} options`);
+
+  // Recurse into subcommands breadth-first
+  const currentDepth = prefixArgs.length;
+  if (parsed.subcommands && parsed.subcommands.length > 0 && (options.depth === undefined || currentDepth < options.depth)) {
+    const resolvedSubs: CommandMeta[] = [];
+
+    for (const sub of parsed.subcommands) {
+      if (options.delay > 0) {
+        await sleep(options.delay);
+      }
+      const resolved = await crawlHelp(command, [...prefixArgs, sub.name], options);
+      // Preserve description from parent's subcommand list if child didn't have one
+      if (!resolved.description && sub.description) {
+        resolved.description = sub.description;
+      }
+      resolvedSubs.push(resolved);
+    }
+
+    parsed.subcommands = resolvedSubs;
+  }
+
+  return parsed;
+}
+
+/**
+ * Run `<cmd> --help` or `<cmd> help` and return combined stdout+stderr.
+ */
+async function runHelp(command: string, args: string[], timeout: number): Promise<string | null> {
+  // Try --help first
+  let result = await runCommand(command, [...args, '--help'], timeout);
+  if (result) return result;
+
+  // Some CLIs use `help <cmd>` instead
+  if (args.length > 0) {
+    result = await runCommand(command, ['help', ...args], timeout);
+    if (result) return result;
+  }
+
+  return null;
+}
+
+/**
+ * Run a command and return its combined output, or null on failure.
+ */
+async function runCommand(command: string, args: string[], timeout: number): Promise<string | null> {
+  try {
+    const proc = Bun.spawn([command, ...args], {
+      stdout: 'pipe',
+      stderr: 'pipe',
+      stdin: 'ignore',
+    });
+
+    const timer = setTimeout(() => proc.kill(), timeout);
+
+    const [_exitCode, stdoutBuf, stderrBuf] = await Promise.all([
+      proc.exited,
+      new Response(proc.stdout).arrayBuffer(),
+      new Response(proc.stderr).arrayBuffer(),
+    ]);
+
+    clearTimeout(timer);
+
+    const stdout = new TextDecoder().decode(stdoutBuf).trim();
+    const stderr = new TextDecoder().decode(stderrBuf).trim();
+
+    // Some CLIs output help to stderr, some exit non-zero on --help
+    const combined = stdout || stderr;
+    if (!combined) return null;
+
+    // Basic sanity check: help text usually has some structure
+    if (combined.length < 10) return null;
+
+    return combined;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Try to get a shell completion script for a command.
+ * Checks both `<cmd> completion <shell>` and well-known file paths.
+ */
+async function getCompletionScript(command: string, shell: 'fish' | 'zsh', timeout: number): Promise<string | null> {
+  // Try `<cmd> completion <shell>`
+  const completionArgs = ['completion', shell];
+  let result = await runCommand(command, completionArgs, timeout);
+  if (result) return result;
+
+  // Try `<cmd> completions <shell>`
+  result = await runCommand(command, ['completions', shell], timeout);
+  if (result) return result;
+
+  // Try reading from well-known paths
+  const paths =
+    shell === 'fish'
+      ? [`/usr/share/fish/vendor_completions.d/${command}.fish`, `/usr/local/share/fish/vendor_completions.d/${command}.fish`]
+      : [`/usr/share/zsh/site-functions/_${command}`, `/usr/local/share/zsh/site-functions/_${command}`];
+
+  for (const path of paths) {
+    try {
+      const file = Bun.file(path);
+      if (await file.exists()) {
+        return await file.text();
+      }
+    } catch {}
+  }
+
+  return null;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/codegen/file-emitter.ts

@@ -0,0 +1,73 @@
+import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import type { CodeBuildResult, EmitResult, FileEmitter, FileEmitterOptions } from './types.ts';
+
+interface QueuedFile {
+  path: string;
+  content: string;
+}
+
+class FileEmitterImpl implements FileEmitter {
+  private files: QueuedFile[] = [];
+  private options: FileEmitterOptions;
+
+  constructor(options: FileEmitterOptions) {
+    this.options = options;
+  }
+
+  addFile(path: string, content: string | CodeBuildResult): void {
+    const text = typeof content === 'string' ? content : content.text;
+    const fullContent = this.options.header ? `${this.options.header}\n\n${text}` : text;
+
+    this.files.push({ path, content: fullContent });
+  }
+
+  async emit(): Promise<EmitResult> {
+    const result: EmitResult = {
+      written: [],
+      skipped: [],
+      errors: [],
+    };
+
+    const outDir = resolve(this.options.outDir);
+
+    for (const file of this.files) {
+      const fullPath = join(outDir, file.path);
+
+      try {
+        // Check if file already exists
+        if (existsSync(fullPath) && !this.options.overwrite) {
+          result.skipped.push(file.path);
+          continue;
+        }
+
+        if (this.options.dryRun) {
+          result.written.push(file.path);
+          continue;
+        }
+
+        // Ensure directory exists
+        const dir = dirname(fullPath);
+        mkdirSync(dir, { recursive: true });
+
+        // Write the file
+        writeFileSync(fullPath, file.content, 'utf-8');
+        result.written.push(file.path);
+      } catch (err) {
+        result.errors.push({
+          file: file.path,
+          error: err instanceof Error ? err : new Error(String(err)),
+        });
+      }
+    }
+
+    return result;
+  }
+}
+
+/**
+ * Create a FileEmitter for writing multiple generated files to disk.
+ */
+export function createFileEmitter(options: FileEmitterOptions): FileEmitter {
+  return new FileEmitterImpl(options);
+}

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

@@ -0,0 +1,16 @@
+import type { CodeBuilder, GeneratorContext } from '../types.ts';
+
+/**
+ * Generate an index.ts barrel file that re-exports all given files.
+ */
+export function generateBarrelFile(files: string[], ctx: GeneratorContext): CodeBuilder {
+  const code = ctx.createCodeBuilder();
+
+  for (const file of files) {
+    // Strip .ts extension for the import path and ensure relative path
+    const importPath = file.startsWith('./') ? file : `./${file}`;
+    code.line(`export * from '${importPath}'`);
+  }
+
+  return code;
+}