@principal-ai/subsystems-core 0.29.0 → 0.31.0

package/src/codegen/type-generator.ts

@@ -1,560 +0,0 @@
-/**
- * Type Generator
- *
- * Generates TypeScript types from canvas event schemas.
- * Similar to how GraphQL Code Generator works for GraphQL schemas,
- * or how OpenAPI generators work for API specs.
- *
- * Precedents:
- * - GraphQL Code Generator: graphql-code-generator.com
- * - OpenAPI Generator: openapi-generator.tech
- * - Protobuf: generates code from .proto files
- * - Zod: runtime validation with TypeScript inference
- */
-
-import type { ExtendedCanvas, PVEventSchema, PVEventFieldSchema, ExtendedCanvasNode } from '../types/canvas';
-import { isOtelEventNode, isStandardCanvasNode } from '../types/canvas';
-import type { ComponentLibrary } from '../types/library';
-
-/**
- * Code generation options
- */
-export interface CodegenOptions {
-  /** Output language (extensible for future languages) */
-  language: 'typescript' | 'python' | 'go' | 'rust';
-  /** Style preferences */
-  style?: {
-    /** Use readonly for immutable types */
-    readonly?: boolean;
-    /** Use strict null checks */
-    strictNullChecks?: boolean;
-    /** Generate JSDoc comments */
-    includeDocComments?: boolean;
-  };
-  /** Namespace/module name */
-  namespace?: string;
-}
-
-/**
- * Generated code result
- */
-export interface CodegenResult {
-  /** Generated code content */
-  code: string;
-  /** File extension for the language */
-  extension: string;
-  /** Suggested filename */
-  filename: string;
-}
-
-/**
- * Abstract code generator interface
- *
- * This allows us to implement generators for different languages
- * following the same pattern as OpenAPI generators.
- */
-export interface CodeGenerator {
-  /** Target language */
-  language: string;
-  /** Generate code from canvas */
-  generate(canvas: ExtendedCanvas, options?: CodegenOptions, library?: ComponentLibrary): CodegenResult;
-}
-
-/**
- * TypeScript Type Generator
- *
- * Generates TypeScript types from canvas event schemas.
- * Similar to GraphQL Code Generator but for canvas schemas.
- */
-export class TypeScriptGenerator implements CodeGenerator {
-  language = 'typescript';
-
-  generate(canvas: ExtendedCanvas, options?: CodegenOptions, library?: ComponentLibrary): CodegenResult {
-    const opts = {
-      readonly: options?.style?.readonly ?? false,
-      strictNullChecks: options?.style?.strictNullChecks ?? true,
-      includeDocComments: options?.style?.includeDocComments ?? true,
-      namespace: options?.namespace,
-    };
-
-    const lines: string[] = [];
-
-    // File header
-    lines.push('/**');
-    lines.push(` * Generated types from canvas: ${canvas.name || canvas.pv?.name || 'Untitled'}`);
-    lines.push(' *');
-    lines.push(' * DO NOT EDIT MANUALLY - This file is auto-generated');
-    lines.push(' * Generated by @principal-ai/subsystems-core');
-    lines.push(' *');
-    lines.push(` * Canvas: ${canvas.pv?.description || 'No description'}`);
-    lines.push(' */');
-    lines.push('');
-
-    // Namespace (if specified)
-    if (opts.namespace) {
-      lines.push(`export namespace ${opts.namespace} {`);
-    }
-
-    // Group nodes by base ID (strip numeric suffixes like -1, -2, etc.)
-    // This allows multiple nodes representing states of the same component
-    // to be grouped into a single namespace
-    if (canvas.nodes) {
-      const nodeGroups = new Map<string, Array<{ nodeId: string; eventSchema: PVEventSchema }>>();
-
-      for (const node of canvas.nodes) {
-        let eventSchema: PVEventSchema | undefined;
-
-        // Check for OTEL event node (top-level event/eventRef fields)
-        if (isOtelEventNode(node)) {
-          if (node.event) {
-            eventSchema = node.event;
-          } else if (node.eventRef) {
-            eventSchema = this.resolveLibraryEvent(node.eventRef, library);
-            if (!eventSchema) {
-              console.warn(
-                `Node '${node.id}' references unknown library event '${node.eventRef}'`
-              );
-              continue;
-            }
-          }
-        }
-        // Check for standard node with pv.event/pv.eventRef
-        else if (isStandardCanvasNode(node)) {
-          if (node.pv?.event) {
-            eventSchema = node.pv.event;
-          } else if (node.pv?.eventRef) {
-            eventSchema = this.resolveLibraryEvent(node.pv.eventRef, library);
-            if (!eventSchema) {
-              console.warn(
-                `Node '${node.id}' references unknown library event '${node.pv.eventRef}'`
-              );
-              continue;
-            }
-          }
-        }
-
-        if (eventSchema) {
-          // Group by base ID (e.g., "graph-converter-1" -> "graph-converter")
-          const baseId = node.id.replace(/-\d+$/, '');
-          if (!nodeGroups.has(baseId)) {
-            nodeGroups.set(baseId, []);
-          }
-          nodeGroups.get(baseId)!.push({ nodeId: node.id, eventSchema });
-        }
-      }
-
-      // Generate types for each component group
-      for (const [baseId, nodes] of nodeGroups) {
-        lines.push(...this.generateComponentTypes(baseId, nodes, opts));
-        lines.push('');
-      }
-    }
-
-    // Generate union type of all event names
-    lines.push(...this.generateEventNameUnion(canvas, opts, library));
-    lines.push('');
-
-    // Generate event emitter helper type
-    lines.push(...this.generateEmitterTypes(canvas, opts));
-
-    // Close namespace
-    if (opts.namespace) {
-      lines.push('}');
-    }
-
-    const code = lines.join('\n');
-    const filename = this.generateFilename(canvas);
-
-    return {
-      code,
-      extension: 'ts',
-      filename,
-    };
-  }
-
-  /**
-   * Generate types for a component (group of related nodes)
-   * Groups multiple node instances (e.g., graph-converter-1, graph-converter-2)
-   * into a single namespace with all their events
-   */
-  private generateComponentTypes(
-    baseId: string,
-    nodes: Array<{ nodeId: string; eventSchema: PVEventSchema }>,
-    opts: { readonly: boolean; strictNullChecks: boolean; includeDocComments: boolean }
-  ): string[] {
-    const lines: string[] = [];
-    const typeName = this.nodeIdToTypeName(baseId);
-
-    if (opts.includeDocComments) {
-      lines.push(`/**`);
-      lines.push(` * Event types for component: ${baseId}`);
-      lines.push(` */`);
-    }
-
-    lines.push(`export namespace ${typeName} {`);
-
-    // Generate interface for each event in the component
-    const interfaceNames: string[] = [];
-    const eventNames: string[] = [];
-
-    for (const { eventSchema } of nodes) {
-      lines.push(...this.generateEventInterface(eventSchema.name, eventSchema, opts));
-      lines.push('');
-      interfaceNames.push(this.eventNameToTypeName(eventSchema.name));
-      eventNames.push(eventSchema.name);
-    }
-
-    // Export union of all event types
-    if (opts.includeDocComments) {
-      lines.push('  /**');
-      lines.push(`   * All event types for ${baseId}`);
-      lines.push('   */');
-    }
-    if (interfaceNames.length === 1) {
-      lines.push(`  export type Event = ${interfaceNames[0]};`);
-    } else {
-      lines.push(`  export type Event = ${interfaceNames.join(' | ')};`);
-    }
-    lines.push('');
-
-    // Generate event name union
-    if (opts.includeDocComments) {
-      lines.push('  /**');
-      lines.push(`   * All event names for ${baseId}`);
-      lines.push('   */');
-    }
-    if (eventNames.length === 1) {
-      lines.push(`  export type EventName = '${eventNames[0]}';`);
-    } else {
-      lines.push(`  export type EventName = ${eventNames.map(n => `'${n}'`).join(' | ')};`);
-    }
-
-    lines.push('}');
-
-    return lines;
-  }
-
-  private generateNodeTypes(
-    nodeId: string,
-    eventSchema: PVEventSchema,
-    opts: { readonly: boolean; strictNullChecks: boolean; includeDocComments: boolean }
-  ): string[] {
-    const lines: string[] = [];
-    const typeName = this.nodeIdToTypeName(nodeId);
-
-    if (opts.includeDocComments) {
-      lines.push(`/**`);
-      lines.push(` * Event type for node: ${nodeId}`);
-      lines.push(` */`);
-    }
-
-    lines.push(`export namespace ${typeName} {`);
-
-    // Generate interface for the single event
-    lines.push(...this.generateEventInterface(eventSchema.name, eventSchema, opts));
-    lines.push('');
-
-    // Export the event type directly (no union needed for single event)
-    const interfaceName = this.eventNameToTypeName(eventSchema.name);
-    lines.push('  /**');
-    lines.push(`   * Event type for ${nodeId}`);
-    lines.push('   */');
-    lines.push(`  export type Event = ${interfaceName};`);
-    lines.push('');
-
-    // Generate event name literal
-    lines.push('  /**');
-    lines.push(`   * Event name for ${nodeId}`);
-    lines.push('   */');
-    lines.push(`  export type EventName = '${eventSchema.name}';`);
-
-    lines.push('}');
-
-    return lines;
-  }
-
-  private generateEventInterface(
-    eventName: string,
-    schema: PVEventSchema,
-    opts: { readonly: boolean; strictNullChecks: boolean; includeDocComments: boolean }
-  ): string[] {
-    const lines: string[] = [];
-    const interfaceName = this.eventNameToTypeName(eventName);
-    const readonly = opts.readonly ? 'readonly ' : '';
-
-    if (opts.includeDocComments) {
-      lines.push('  /**');
-      lines.push(`   * ${schema.description}`);
-      lines.push('   */');
-    }
-
-    lines.push(`  export interface ${interfaceName} {`);
-
-    // Event name as literal type
-    lines.push(`    ${readonly}name: '${eventName}';`);
-
-    // Attributes
-    lines.push(`    ${readonly}attributes: {`);
-
-    for (const [fieldName, fieldSchema] of Object.entries(schema.attributes)) {
-      const optional = !fieldSchema.required && opts.strictNullChecks ? '?' : '';
-      const type = this.fieldTypeToTsType(fieldSchema);
-
-      if (opts.includeDocComments && fieldSchema.description) {
-        lines.push(`      /** ${fieldSchema.description} */`);
-      }
-
-      lines.push(`      ${readonly}'${fieldName}'${optional}: ${type};`);
-    }
-
-    lines.push('    };');
-    lines.push('  }');
-
-    return lines;
-  }
-
-  private generateEventNameUnion(
-    canvas: ExtendedCanvas,
-    opts: { includeDocComments: boolean },
-    library?: ComponentLibrary
-  ): string[] {
-    const lines: string[] = [];
-    const allEventNames = new Set<string>();
-
-    if (canvas.nodes) {
-      for (const node of canvas.nodes) {
-        // Check for OTEL event node (top-level event/eventRef fields)
-        if (isOtelEventNode(node)) {
-          if (node.event?.name) {
-            allEventNames.add(node.event.name);
-          } else if (node.eventRef) {
-            const eventSchema = this.resolveLibraryEvent(node.eventRef, library);
-            if (eventSchema) {
-              allEventNames.add(eventSchema.name);
-            }
-          }
-        }
-        // Check for standard node with pv.event/pv.eventRef
-        else if (isStandardCanvasNode(node)) {
-          if (node.pv?.event?.name) {
-            allEventNames.add(node.pv.event.name);
-          } else if (node.pv?.eventRef) {
-            const eventSchema = this.resolveLibraryEvent(node.pv.eventRef, library);
-            if (eventSchema) {
-              allEventNames.add(eventSchema.name);
-            }
-          }
-        }
-      }
-    }
-
-    if (allEventNames.size === 0) {
-      return lines;
-    }
-
-    if (opts.includeDocComments) {
-      lines.push('/**');
-      lines.push(' * Union of all event names in the canvas');
-      lines.push(' */');
-    }
-
-    lines.push(`export type AllEventNames = ${Array.from(allEventNames).map(n => `'${n}'`).join(' | ')};`);
-
-    return lines;
-  }
-
-  private generateEmitterTypes(
-    canvas: ExtendedCanvas,
-    opts: { includeDocComments: boolean }
-  ): string[] {
-    const lines: string[] = [];
-
-    if (opts.includeDocComments) {
-      lines.push('/**');
-      lines.push(' * Type-safe event emitter for a specific node');
-      lines.push(' *');
-      lines.push(' * @example');
-      lines.push(' * ```typescript');
-      lines.push(' * const emit: NodeEmitter<GraphConverter.EventName, GraphConverter.Event> = ...');
-      lines.push(" * emit('conversion.started', {");
-      lines.push(" *   name: 'conversion.started',");
-      lines.push(' *   attributes: { ... }');
-      lines.push(' * });');
-      lines.push(' * ```');
-      lines.push(' */');
-    }
-
-    lines.push('export type NodeEmitter<');
-    lines.push('  TEventName extends string,');
-    lines.push('  TEvent extends { name: TEventName; attributes: Record<string, any> }');
-    lines.push('> = (event: TEvent) => void;');
-    lines.push('');
-
-    if (opts.includeDocComments) {
-      lines.push('/**');
-      lines.push(' * Type-safe event emitter by event name');
-      lines.push(' *');
-      lines.push(' * @example');
-      lines.push(' * ```typescript');
-      lines.push(' * const emit: NodeEmitterByName<GraphConverter.Event> = ...');
-      lines.push(" * emit('conversion.started', {");
-      lines.push(" *   'config.nodeTypes': 2,");
-      lines.push(" *   'config.edgeTypes': 1");
-      lines.push(' * });');
-      lines.push(' * ```');
-      lines.push(' */');
-    }
-
-    lines.push('export type NodeEmitterByName<');
-    lines.push('  TEvent extends { name: string; attributes: Record<string, any> }');
-    lines.push('> = <TName extends TEvent[\'name\']>(');
-    lines.push('  eventName: TName,');
-    lines.push('  attributes: Extract<TEvent, { name: TName }>[\'attributes\']');
-    lines.push(') => void;');
-
-    return lines;
-  }
-
-  private nodeIdToTypeName(nodeId: string): string {
-    // Convert kebab-case or snake_case to PascalCase
-    return nodeId
-      .split(/[-_]/)
-      .map(part => part.charAt(0).toUpperCase() + part.slice(1))
-      .join('');
-  }
-
-  private eventNameToTypeName(eventName: string): string {
-    // Convert "conversion.started" to "ConversionStarted"
-    return eventName
-      .split('.')
-      .map(part => part.charAt(0).toUpperCase() + part.slice(1))
-      .join('');
-  }
-
-  private fieldTypeToTsType(fieldSchema: PVEventFieldSchema): string {
-    switch (fieldSchema.type) {
-      case 'string':
-        return 'string';
-      case 'number':
-        return 'number';
-      case 'boolean':
-        return 'boolean';
-      case 'array':
-        return 'any[]';
-      case 'object':
-        return 'Record<string, any>';
-      default:
-        return 'any';
-    }
-  }
-
-  private generateFilename(canvas: ExtendedCanvas): string {
-    const name = canvas.pv?.name || 'canvas';
-    // Convert to kebab-case
-    const kebab = name
-      .toLowerCase()
-      .replace(/\s+/g, '-')
-      .replace(/[^a-z0-9-]/g, '');
-    return `${kebab}.types.ts`;
-  }
-
-  /**
-   * Resolve an event schema from library by event name
-   */
-  private resolveLibraryEvent(eventName: string, library?: ComponentLibrary): PVEventSchema | undefined {
-    if (!library?.eventSchemas) {
-      return undefined;
-    }
-
-    const librarySchema = library.eventSchemas[eventName];
-    if (!librarySchema) {
-      return undefined;
-    }
-
-    // Convert library schema (without name) to full PVEventSchema
-    return {
-      name: eventName,
-      description: librarySchema.description,
-      attributes: librarySchema.attributes,
-    };
-  }
-}
-
-/**
- * Generate types from canvas
- *
- * @example
- * ```typescript
- * import fs from 'fs';
- * import { generateTypes } from '@principal-ai/subsystems-core';
- *
- * const canvas = JSON.parse(fs.readFileSync('my-flow.canvas', 'utf-8'));
- * const result = generateTypes(canvas, { language: 'typescript' });
- *
- * fs.writeFileSync(result.filename, result.code);
- * ```
- */
-export function generateTypes(
-  canvas: ExtendedCanvas,
-  options: CodegenOptions = { language: 'typescript' },
-  library?: ComponentLibrary
-): CodegenResult {
-  const generator = getGenerator(options.language);
-  return generator.generate(canvas, options, library);
-}
-
-/**
- * Get code generator for a language
- */
-function getGenerator(language: CodegenOptions['language']): CodeGenerator {
-  switch (language) {
-    case 'typescript':
-      return new TypeScriptGenerator();
-    case 'python':
-      // TODO: Implement Python generator
-      throw new Error('Python generator not yet implemented. See TypeScriptGenerator as reference.');
-    case 'go':
-      // TODO: Implement Go generator
-      throw new Error('Go generator not yet implemented. See TypeScriptGenerator as reference.');
-    case 'rust':
-      // TODO: Implement Rust generator
-      throw new Error('Rust generator not yet implemented. See TypeScriptGenerator as reference.');
-    default:
-      throw new Error(`Unsupported language: ${language}`);
-  }
-}
-
-/**
- * Registry of available generators
- *
- * This allows external packages to register custom generators:
- *
- * @example
- * ```typescript
- * import { generatorRegistry } from '@principal-ai/subsystems-core';
- *
- * class PythonGenerator implements CodeGenerator {
- *   language = 'python';
- *   generate(canvas, options) { ... }
- * }
- *
- * generatorRegistry.register(new PythonGenerator());
- * ```
- */
-export const generatorRegistry = {
-  generators: new Map<string, CodeGenerator>([
-    ['typescript', new TypeScriptGenerator()],
-  ]),
-
-  register(generator: CodeGenerator) {
-    this.generators.set(generator.language, generator);
-  },
-
-  get(language: string): CodeGenerator | undefined {
-    return this.generators.get(language);
-  },
-
-  list(): string[] {
-    return Array.from(this.generators.keys());
-  },
-};