@rexeus/typeweaver-gen 0.0.1

package/README.md

@@ -0,0 +1,267 @@
+# @rexeus/typeweaver-gen
+
+Code generation engine and utilities for TypeWeaver plugins.
+
+## Overview
+
+This package provides the plugin architecture and utilities that power TypeWeaver's extensible code
+generation system. It includes base classes, context utilities, and the plugin registry system.
+
+## Installation
+
+```bash
+npm install @rexeus/typeweaver-gen
+```
+
+**Peer Dependencies:**
+
+```bash
+npm install @rexeus/typeweaver-core
+```
+
+## Plugin Architecture
+
+### Creating a Plugin
+
+```typescript
+import { BasePlugin, type GeneratorContext } from "@rexeus/typeweaver-gen";
+
+export default class MyPlugin extends BasePlugin {
+  public name = "my-plugin";
+
+  public override generate(context: GeneratorContext): Promise<void> | void {
+    // Your generation logic here
+    const content = context.renderTemplate(templatePath, templateData);
+    context.writeFile("relative/path/to/output.ts", content);
+    context.addGeneratedFile("relative/path/to/output.ts");
+  }
+}
+```
+
+### Plugin Context
+
+The `GeneratorContext` provides utilities for code generation:
+
+```typescript
+interface GeneratorContext {
+  // Input/output directories
+  outputDir: string;
+  inputDir: string;
+  templateDir: string;
+  coreDir: string;
+
+  // Resource data
+  resources: GetResourcesResult;
+
+  // Configuration
+  config: PluginConfig;
+
+  // Utility functions
+  writeFile: (relativePath: string, content: string) => void;
+  renderTemplate: (templatePath: string, data: unknown) => string;
+  addGeneratedFile: (relativePath: string) => void;
+  getGeneratedFiles: () => string[];
+}
+```
+
+### Utility Functions
+
+#### `writeFile(relativePath, content)`
+
+Writes files relative to the output directory with automatic directory creation:
+
+```typescript
+context.writeFile("users/UserClient.ts", generatedClientCode);
+```
+
+#### `renderTemplate(templatePath, data)`
+
+Renders EJS templates with provided data:
+
+```typescript
+const content = context.renderTemplate(path.join(__dirname, "templates", "Client.ejs"), {
+  entityName,
+  operations,
+  coreDir: context.coreDir,
+});
+```
+
+#### `addGeneratedFile(relativePath)`
+
+Tracks generated files (automatically called by `writeFile`):
+
+```typescript
+context.addGeneratedFile("users/UserClient.ts");
+```
+
+## Resource System
+
+The resource system provides structured access to API definitions:
+
+### Resource Types
+
+```typescript
+interface GetResourcesResult {
+  entityResources: Record<string, OperationResource[]>;
+  sharedResponseResources: SharedResponseResource[];
+}
+
+interface OperationResource {
+  entityName: string;
+  definition: HttpOperationDefinition;
+  outputDir: string;
+  outputRequestFile: string;
+  outputResponseFile: string;
+  outputRequestValidationFile: string;
+  outputResponseValidationFile: string;
+  // ... more output file paths
+}
+
+interface SharedResponseResource {
+  name: string;
+  definition: HttpResponseDefinition;
+  outputDir: string;
+  outputFileName: string;
+  outputFile: string;
+}
+```
+
+### Using Resources
+
+```typescript
+export default class MyPlugin extends BasePlugin {
+  public name = "my-plugin";
+
+  public override generate(context: GeneratorContext): void {
+    // Iterate through entities
+    for (const [entityName, operations] of Object.entries(context.resources.entityResources)) {
+      // Generate entity-level code
+      this.generateEntityCode(entityName, operations, context);
+
+      // Generate operation-level code
+      for (const operation of operations) {
+        this.generateOperationCode(operation, context);
+      }
+    }
+
+    // Use shared responses
+    for (const sharedResponse of context.resources.sharedResponseResources) {
+      this.generateSharedResponse(sharedResponse, context);
+    }
+  }
+}
+```
+
+## Template System
+
+### Template Structure
+
+Templates should be placed in a `templates/` directory within your plugin:
+
+```
+my-plugin/
+├── src/
+│   ├── index.ts
+│   ├── MyGenerator.ts
+│   └── templates/
+│       ├── Client.ejs
+│       └── Router.ejs
+└── package.json
+```
+
+### Template Usage
+
+Templates receive context data and can use EJS syntax:
+
+```ejs
+<%# templates/Client.ejs %>
+import { ApiClient } from "<%= coreDir %>";
+
+export class <%= pascalCaseEntityName %>Client extends ApiClient {
+  <% for (const operation of operations) { %>
+  public <%= operation.operationId %>() {
+    // Generated method
+  }
+  <% } %>
+}
+```
+
+## Plugin Lifecycle
+
+### Lifecycle Hooks
+
+```typescript
+interface TypeWeaverPlugin {
+  /**
+   * Initialize the plugin
+   * Called before any generation happens
+   */
+  initialize?(context: PluginContext): Promise<void> | void;
+
+  /**
+   * Collect and transform resources
+   * Allows plugins to modify the resource collection
+   */
+  collectResources?(
+    resources: GetResourcesResult
+  ): Promise<GetResourcesResult> | GetResourcesResult;
+
+  /**
+   * Main generation logic
+   * Called with all resources and utilities
+   */
+  generate?(context: GeneratorContext): Promise<void> | void;
+
+  /**
+   * Finalize the plugin
+   * Called after all generation is complete
+   */
+  finalize?(context: PluginContext): Promise<void> | void;
+}
+```
+
+## Built-in Plugins
+
+TypeWeaver includes several built-in plugins:
+
+- **@rexeus/typeweaver-types** - TypeScript types and Zod validators
+- **@rexeus/typeweaver-clients** - HTTP API clients
+- **@rexeus/typeweaver-aws-cdk** - AWS CDK constructs and HTTP API routers
+
+## Best Practices
+
+### File Organization
+
+- Use consistent naming patterns for generated files
+- Organize output by entity or feature
+- Include proper imports and exports
+
+### Template Design
+
+- Keep templates focused and modular
+- Use consistent variable naming
+- Include proper TypeScript types in generated code
+
+### Error Handling
+
+- Validate input data before generation
+- Provide clear error messages
+- Handle edge cases gracefully
+
+```typescript
+export default class MyPlugin extends BasePlugin {
+  public name = "my-plugin";
+
+  public override generate(context: GeneratorContext): void {
+    try {
+      // Generation logic
+    } catch (error) {
+      throw new Error(`Plugin ${this.name} failed: ${error.message}`);
+    }
+  }
+}
+```
+
+## License
+
+ISC © Dennis Wentzien 2025

package/dist/index.d.ts

@@ -0,0 +1,263 @@
+import { IHttpOperationDefinition, IHttpResponseDefinition } from '@rexeus/typeweaver-core';
+
+type GetResourcesResult = {
+    entityResources: EntityResources;
+    sharedResponseResources: SharedResponseResource[];
+};
+type ExtendedResponseDefinition = IHttpResponseDefinition & {
+    statusCodeName: string;
+};
+type EntityName = string;
+type OperationResource = {
+    sourceDir: string;
+    sourceFile: string;
+    sourceFileName: string;
+    definition: Omit<IHttpOperationDefinition, "responses"> & {
+        responses: ExtendedResponseDefinition[];
+    };
+    outputDir: string;
+    entityName: EntityName;
+    outputRequestFile: string;
+    outputRequestFileName: string;
+    outputResponseFile: string;
+    outputResponseFileName: string;
+    outputRequestValidationFile: string;
+    outputRequestValidationFileName: string;
+    outputResponseValidationFile: string;
+    outputResponseValidationFileName: string;
+    outputClientFile: string;
+    outputClientFileName: string;
+};
+type EntityResources = Record<EntityName, OperationResource[]>;
+type SharedResponseResource = IHttpResponseDefinition & {
+    isShared: true;
+    sourceDir: string;
+    sourceFile: string;
+    sourceFileName: string;
+    outputFile: string;
+    outputFileName: string;
+    outputDir: string;
+};
+
+/**
+ * Configuration for a TypeWeaver plugin
+ */
+type PluginConfig = Record<string, unknown>;
+/**
+ * Context provided to plugins during initialization and finalization
+ */
+interface PluginContext {
+    outputDir: string;
+    inputDir: string;
+    config: PluginConfig;
+}
+/**
+ * Context provided to plugins during generation
+ */
+interface GeneratorContext extends PluginContext {
+    resources: GetResourcesResult;
+    templateDir: string;
+    coreDir: string;
+    writeFile: (relativePath: string, content: string) => void;
+    renderTemplate: (templatePath: string, data: unknown) => string;
+    addGeneratedFile: (relativePath: string) => void;
+    getGeneratedFiles: () => string[];
+}
+/**
+ * Plugin metadata
+ */
+interface PluginMetadata {
+    name: string;
+}
+/**
+ * TypeWeaver plugin interface
+ */
+interface TypeWeaverPlugin extends PluginMetadata {
+    /**
+     * Initialize the plugin
+     * Called before any generation happens
+     */
+    initialize?(context: PluginContext): Promise<void> | void;
+    /**
+     * Collect and transform resources
+     * Allows plugins to modify the resource collection
+     */
+    collectResources?(resources: GetResourcesResult): Promise<GetResourcesResult> | GetResourcesResult;
+    /**
+     * Main generation logic
+     * Called with all resources and utilities
+     */
+    generate?(context: GeneratorContext): Promise<void> | void;
+    /**
+     * Finalize the plugin
+     * Called after all generation is complete
+     */
+    finalize?(context: PluginContext): Promise<void> | void;
+}
+/**
+ * Plugin constructor type
+ */
+type PluginConstructor = new (config?: PluginConfig) => TypeWeaverPlugin;
+/**
+ * Plugin module export
+ */
+interface PluginModule {
+    default: PluginConstructor;
+}
+/**
+ * Plugin registration entry
+ */
+interface PluginRegistration {
+    name: string;
+    plugin: TypeWeaverPlugin;
+    config?: PluginConfig;
+}
+/**
+ * TypeWeaver configuration
+ */
+interface TypeWeaverConfig {
+    input: string;
+    output: string;
+    plugins?: Array<string | [string, PluginConfig]>;
+    prettier?: boolean;
+    clean?: boolean;
+}
+/**
+ * Plugin loading error
+ */
+declare class PluginLoadError extends Error {
+    pluginName: string;
+    constructor(pluginName: string, message: string);
+}
+/**
+ * Plugin dependency error
+ */
+declare class PluginDependencyError extends Error {
+    pluginName: string;
+    missingDependency: string;
+    constructor(pluginName: string, missingDependency: string);
+}
+
+/**
+ * Base class for TypeWeaver plugins
+ * Provides default implementations and common utilities
+ */
+declare abstract class BasePlugin implements TypeWeaverPlugin {
+    abstract name: string;
+    description?: string;
+    author?: string;
+    depends?: string[];
+    protected config: PluginConfig;
+    constructor(config?: PluginConfig);
+    /**
+     * Default implementation - override in subclasses if needed
+     */
+    initialize(context: PluginContext): Promise<void>;
+    /**
+     * Default implementation - override in subclasses if needed
+     */
+    collectResources(resources: GetResourcesResult): GetResourcesResult;
+    /**
+     * Main generation logic - must be implemented by subclasses
+     */
+    abstract generate(context: GeneratorContext): Promise<void> | void;
+    /**
+     * Default implementation - override in subclasses if needed
+     */
+    finalize(context: PluginContext): Promise<void>;
+    /**
+     * Copy lib files from plugin package to generated lib folder
+     */
+    protected copyLibFiles(context: GeneratorContext, libSourceDir: string, libNamespace: string): void;
+}
+
+/**
+ * Base class for template-based generator plugins
+ * Provides utilities for working with EJS templates
+ */
+declare abstract class BaseTemplatePlugin extends BasePlugin {
+    /**
+     * Render an EJS template with the given data
+     */
+    protected renderTemplate(templatePath: string, data: unknown): string;
+    /**
+     * Write a file relative to the output directory
+     */
+    protected writeFile(context: GeneratorContext, relativePath: string, content: string): void;
+    /**
+     * Ensure a directory exists
+     */
+    protected ensureDir(context: GeneratorContext, relativePath: string): void;
+    /**
+     * Get the template path for this plugin
+     */
+    protected getTemplatePath(context: GeneratorContext, templateName: string): string;
+}
+
+/**
+ * Registry for managing TypeWeaver plugins
+ */
+declare class PluginRegistry {
+    private plugins;
+    constructor();
+    /**
+     * Register a plugin
+     */
+    register(plugin: TypeWeaverPlugin, config?: unknown): void;
+    /**
+     * Get a registered plugin
+     */
+    get(name: string): PluginRegistration | undefined;
+    /**
+     * Get all registered plugins
+     */
+    getAll(): PluginRegistration[];
+    /**
+     * Check if a plugin is registered
+     */
+    has(name: string): boolean;
+    /**
+     * Clear all registered plugins (except required ones)
+     */
+    clear(): void;
+}
+
+/**
+ * Builder for plugin contexts
+ */
+declare class PluginContextBuilder {
+    private generatedFiles;
+    /**
+     * Create a basic plugin context
+     */
+    createPluginContext(params: {
+        outputDir: string;
+        inputDir: string;
+        config: PluginConfig;
+    }): PluginContext;
+    /**
+     * Create a generator context with utilities
+     */
+    createGeneratorContext(params: {
+        outputDir: string;
+        inputDir: string;
+        config: PluginConfig;
+        resources: GetResourcesResult;
+        templateDir: string;
+        coreDir: string;
+    }): GeneratorContext;
+    /**
+     * Get all generated files
+     */
+    getGeneratedFiles(): string[];
+    /**
+     * Clear generated files tracking
+     */
+    clearGeneratedFiles(): void;
+}
+
+declare class Path {
+    static relative(from: string, to: string): string;
+}
+
+export { BasePlugin, BaseTemplatePlugin, type EntityName, type EntityResources, type ExtendedResponseDefinition, type GeneratorContext, type GetResourcesResult, type OperationResource, Path, type PluginConfig, type PluginConstructor, type PluginContext, PluginContextBuilder, PluginDependencyError, PluginLoadError, type PluginMetadata, type PluginModule, type PluginRegistration, PluginRegistry, type SharedResponseResource, type TypeWeaverConfig, type TypeWeaverPlugin };