@principal-ai/subsystems-core 0.29.0

package/src/codegen/type-generator.ts

@@ -0,0 +1,560 @@
+/**
+ * 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());
+  },
+};