@vertz/codegen 0.2.0

package/README.md

@@ -0,0 +1,243 @@
+# @vertz/codegen
+
+> ⚠️ **Internal package** — This package is an implementation detail of the Vertz framework. It is published for use by other `@vertz/*` packages. No API stability is guaranteed between versions.
+
+Code generation for Vertz applications. Generates TypeScript SDKs, CLIs, and type definitions from your Vertz app's intermediate representation (IR).
+
+## What it does
+
+`@vertz/codegen` transforms your Vertz app's compiled IR into:
+
+- **TypeScript SDK** — Type-safe client with generated methods for every route
+- **CLI** — Command-line interface with auto-generated commands
+- **Type definitions** — Input/output types for operations, schemas, and streaming events
+
+The codegen runs automatically during compilation (via `@vertz/compiler`) but can also be used standalone for custom generation workflows.
+
+## When it's used
+
+**Typical workflow:**
+
+1. You define routes, schemas, and modules in your Vertz app
+2. The Vertz compiler analyzes your code and produces an AppIR
+3. `@vertz/codegen` transforms the AppIR into SDK/CLI code
+4. Generated code is written to `.vertz/generated/` (or your custom output dir)
+
+**Manual usage:**
+
+If you need custom generation (e.g., generating code from an external API schema), you can use the codegen API directly:
+
+```typescript
+import { generate } from '@vertz/codegen';
+import type { AppIR } from '@vertz/compiler';
+
+const result = await generate(appIR, {
+  generators: ['typescript', 'cli'],
+  outputDir: './generated',
+  typescript: {
+    clientName: 'createMyClient',
+    schemas: true,
+  },
+  cli: {
+    enabled: true,
+  },
+});
+
+console.log(`Generated ${result.fileCount} files`);
+```
+
+## Configuration
+
+Use `defineCodegenConfig()` to configure code generation in your Vertz app:
+
+```typescript
+import { defineCodegenConfig } from '@vertz/codegen';
+
+export default defineCodegenConfig({
+  generators: ['typescript', 'cli'],
+  outputDir: '.vertz/generated',
+  format: true, // Format with Biome (default: true)
+  incremental: true, // Only write changed files (default: true)
+  
+  typescript: {
+    clientName: 'createClient', // SDK function name
+    schemas: true, // Re-export schemas (default: true)
+    publishable: {
+      name: '@myapp/sdk',
+      outputDir: './packages/sdk',
+      version: '1.0.0',
+    },
+  },
+  
+  cli: {
+    enabled: true,
+    publishable: {
+      name: '@myapp/cli',
+      binName: 'myapp',
+      outputDir: './packages/cli',
+      version: '1.0.0',
+    },
+  },
+});
+```
+
+## Public API
+
+### Configuration
+
+- **`defineCodegenConfig(config)`** — Define code generation config with type safety
+- **`resolveCodegenConfig(config?)`** — Resolve config with defaults
+- **`validateCodegenConfig(config)`** — Validate config and return errors
+
+### Generation
+
+- **`generate(appIR, config)`** — Generate code from AppIR
+  - Returns `GenerateResult` with file list, IR, and stats
+- **`createCodegenPipeline()`** — Create reusable generation pipeline
+  - Supports custom generators and incremental regeneration
+
+### TypeScript Generator
+
+Emit SDK components:
+
+- **`emitClientFile(ir)`** — Main SDK client file
+- **`emitModuleFile(module)`** — Module-specific client code
+- **`emitOperationMethod(op)`** — Individual operation methods
+- **`emitStreamingMethod(op)`** — Streaming operation methods
+- **`emitAuthStrategyBuilder(auth)`** — Auth strategy builders
+- **`emitSDKConfig(ir)`** — SDK configuration types
+
+Emit type definitions:
+
+- **`emitModuleTypesFile(module, schemas)`** — Module types
+- **`emitSharedTypesFile(schemas)`** — Shared types
+- **`emitOperationInputType(op)`** — Input types
+- **`emitOperationResponseType(op)`** — Response types
+- **`emitStreamingEventType(op)`** — Streaming event types
+- **`emitInterfaceFromSchema(schema)`** — Schema → TypeScript interface
+
+Emit package structure:
+
+- **`emitBarrelIndex(modules)`** — Barrel index file
+- **`emitSchemaReExports(schemas)`** — Schema re-exports
+- **`emitPackageJson(options)`** — package.json for publishable SDK
+
+### CLI Generator
+
+- **`emitManifestFile(ir)`** — CLI manifest (command definitions)
+- **`emitCommandDefinition(op)`** — Command definition from operation
+- **`emitModuleCommands(module)`** — Module commands
+- **`emitBinEntryPoint(options)`** — Executable entry point
+- **`scaffoldCLIPackageJson(options)`** — package.json for publishable CLI
+- **`scaffoldCLIRootIndex()`** — CLI root index file
+
+### Utilities
+
+- **`adaptIR(appIR)`** — Transform AppIR → CodegenIR
+- **`jsonSchemaToTS(schema)`** — Convert JSON Schema → TypeScript
+- **`hashContent(content)`** — Content-based hashing for incremental generation
+- **`writeIncremental(files, outputDir, options)`** — Write only changed files
+- **`formatWithBiome(code)`** — Format generated code
+
+Naming utilities:
+
+- **`toPascalCase(str)`** — `hello_world` → `HelloWorld`
+- **`toCamelCase(str)`** — `hello_world` → `helloWorld`
+- **`toKebabCase(str)`** — `HelloWorld` → `hello-world`
+- **`toSnakeCase(str)`** — `HelloWorld` → `hello_world`
+
+Import management:
+
+- **`mergeImports(imports)`** — Merge import statements
+- **`renderImports(imports)`** — Render imports as code
+
+## Custom Generators
+
+To create a custom generator, implement the `Generator` interface:
+
+```typescript
+import type { Generator, CodegenIR, GeneratedFile } from '@vertz/codegen';
+
+const myGenerator: Generator = {
+  name: 'my-generator',
+  run(ir: CodegenIR): GeneratedFile[] {
+    return [
+      {
+        path: 'output.txt',
+        content: `Generated from ${ir.modules.length} modules`,
+      },
+    ];
+  },
+};
+
+// Use in pipeline
+import { createCodegenPipeline } from '@vertz/codegen';
+
+const pipeline = createCodegenPipeline();
+pipeline.addGenerator(myGenerator);
+const result = await pipeline.run(appIR, config);
+```
+
+## Incremental Regeneration
+
+By default, codegen uses incremental mode to avoid rewriting unchanged files:
+
+```typescript
+const result = await generate(appIR, {
+  incremental: true, // default
+  outputDir: './generated',
+});
+
+console.log(result.incremental?.stats);
+// {
+//   written: 3,    // Files written (changed)
+//   skipped: 12,   // Files skipped (unchanged)
+//   deleted: 1,    // Stale files removed
+// }
+```
+
+This improves performance by:
+
+- Skipping file writes when content is identical (preserves timestamps)
+- Avoiding unnecessary TypeScript recompilation
+- Detecting and removing stale generated files
+
+## Type Safety
+
+All generated code is fully type-safe. The codegen preserves:
+
+- Input/output types from your routes
+- Schema types from `@vertz/schema`
+- Generic type parameters (e.g., auth context, streaming events)
+- Discriminated unions for operation responses
+
+Example generated SDK usage:
+
+```typescript
+import { createClient } from './.vertz/generated';
+
+const client = createClient({ baseURL: 'https://api.example.com' });
+
+// Fully typed
+const user = await client.users.getUser({ id: '123' });
+//    ^? { id: string; name: string; email: string }
+
+// Streaming with typed events
+const stream = client.events.subscribe();
+for await (const event of stream) {
+  if (event.type === 'user.created') {
+    console.log(event.data.user.name);
+    //          ^? string
+  }
+}
+```
+
+## Related Packages
+
+- **[@vertz/compiler](../compiler)** — Analyzes Vertz apps and produces AppIR
+- **[@vertz/cli](../cli)** — Provides `vertz codegen` command
+- **[@vertz/cli-runtime](../cli-runtime)** — Runtime for generated CLIs
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,290 @@
+type GeneratorName = "typescript" | "cli";
+interface CodegenPublishableConfig {
+	/** Package name, e.g., '@myapp/sdk' */
+	name: string;
+	/** Output directory for the package */
+	outputDir: string;
+	/** Package version. Default: '0.0.0' */
+	version?: string;
+}
+interface CodegenTypescriptConfig {
+	/** Generate schema re-exports. Default: true */
+	schemas?: boolean;
+	/** SDK client function name. Default: 'createClient' */
+	clientName?: string;
+	/** Generate as publishable npm package. Default: false */
+	publishable?: CodegenPublishableConfig;
+	/** Augmentable types for customer-specific type narrowing */
+	augmentableTypes?: string[];
+}
+interface CodegenCLIPublishableConfig extends CodegenPublishableConfig {
+	/** CLI binary name, e.g., 'myapp' */
+	binName: string;
+}
+interface CodegenCLIConfig {
+	/** Include in generation. Default: false */
+	enabled?: boolean;
+	/** Generate as publishable npm package. Default: false */
+	publishable?: CodegenCLIPublishableConfig;
+}
+interface CodegenConfig {
+	/** Generators to run. Default: ['typescript'] */
+	generators: GeneratorName[];
+	/** Output directory. Default: '.vertz/generated' */
+	outputDir?: string;
+	/** Whether to format output with Biome. Defaults to true. */
+	format?: boolean;
+	/** Whether to use incremental regeneration (only write changed files). Defaults to true. */
+	incremental?: boolean;
+	/** TypeScript SDK options */
+	typescript?: CodegenTypescriptConfig;
+	/** CLI options */
+	cli?: CodegenCLIConfig;
+}
+interface ResolvedCodegenConfig {
+	generators: GeneratorName[];
+	outputDir: string;
+	format?: boolean;
+	incremental?: boolean;
+	typescript?: CodegenTypescriptConfig;
+	cli?: CodegenCLIConfig;
+}
+declare function defineCodegenConfig(config: CodegenConfig): CodegenConfig;
+declare function resolveCodegenConfig(config?: CodegenConfig): ResolvedCodegenConfig;
+declare function validateCodegenConfig(config: CodegenConfig): string[];
+type HttpMethod = "GET" | "POST" | "PUT" | "DELETE" | "PATCH" | "HEAD" | "OPTIONS";
+type JsonSchema = Record<string, unknown>;
+interface CodegenIR {
+	basePath: string;
+	version?: string;
+	modules: CodegenModule[];
+	schemas: CodegenSchema[];
+	auth: CodegenAuth;
+}
+interface CodegenModule {
+	name: string;
+	operations: CodegenOperation[];
+}
+interface CodegenOperation {
+	operationId: string;
+	method: HttpMethod;
+	path: string;
+	description?: string;
+	tags: string[];
+	params?: JsonSchema;
+	query?: JsonSchema;
+	body?: JsonSchema;
+	headers?: JsonSchema;
+	response?: JsonSchema;
+	streaming?: StreamingConfig;
+	schemaRefs: OperationSchemaRefs;
+	auth?: OperationAuth;
+}
+interface StreamingConfig {
+	format: "sse" | "ndjson";
+	eventSchema?: JsonSchema;
+}
+interface OperationAuth {
+	required: boolean;
+	schemes: string[];
+}
+interface OperationSchemaRefs {
+	params?: string;
+	query?: string;
+	body?: string;
+	headers?: string;
+	response?: string;
+}
+interface CodegenAuth {
+	schemes: CodegenAuthScheme[];
+}
+type CodegenAuthScheme = {
+	type: "bearer";
+	name: string;
+	description?: string;
+} | {
+	type: "basic";
+	name: string;
+	description?: string;
+} | {
+	type: "apiKey";
+	name: string;
+	in: "header" | "query" | "cookie";
+	paramName: string;
+	description?: string;
+} | {
+	type: "oauth2";
+	name: string;
+	flows: OAuthFlows;
+	description?: string;
+};
+interface OAuthFlows {
+	authorizationCode?: {
+		authorizationUrl: string;
+		tokenUrl: string;
+		scopes: Record<string, string>;
+	};
+	clientCredentials?: {
+		tokenUrl: string;
+		scopes: Record<string, string>;
+	};
+	deviceCode?: {
+		deviceAuthorizationUrl: string;
+		tokenUrl: string;
+		scopes: Record<string, string>;
+	};
+}
+interface CodegenSchema {
+	name: string;
+	jsonSchema: JsonSchema;
+	annotations: SchemaAnnotations;
+}
+interface SchemaAnnotations {
+	description?: string;
+	deprecated?: boolean;
+	brand?: string;
+	namingParts: SchemaNamingParts;
+}
+interface SchemaNamingParts {
+	operation?: string;
+	entity?: string;
+	part?: string;
+}
+interface Generator {
+	readonly name: string;
+	generate(ir: CodegenIR, config: GeneratorConfig): GeneratedFile[];
+}
+interface GeneratedFile {
+	path: string;
+	content: string;
+}
+interface GeneratorConfig {
+	outputDir: string;
+	options: Record<string, unknown>;
+}
+interface Import {
+	from: string;
+	name: string;
+	isType: boolean;
+	alias?: string;
+}
+interface FileFragment {
+	content: string;
+	imports: Import[];
+}
+/**
+* Format generated files using Biome.
+*
+* Writes files to a temp directory with a standalone biome.json config,
+* runs `biome format --write --config-path <tempDir>`,
+* reads them back, and cleans up.
+*/
+declare function formatWithBiome(files: GeneratedFile[]): Promise<GeneratedFile[]>;
+import { AppIR } from "@vertz/compiler";
+interface IncrementalResult {
+	/** Files that were written (new or changed). */
+	written: string[];
+	/** Files that were skipped (content unchanged). */
+	skipped: string[];
+	/** Files that were removed (stale, only in clean mode). */
+	removed: string[];
+}
+interface IncrementalOptions {
+	/** If true, remove files in outputDir that are not in the generated set. */
+	clean?: boolean;
+}
+/**
+* Write generated files to disk incrementally:
+* - Only writes files whose content has changed (or are new).
+* - Optionally removes stale files that are no longer generated.
+*/
+declare function writeIncremental(files: GeneratedFile[], outputDir: string, options?: IncrementalOptions): Promise<IncrementalResult>;
+interface GenerateResult {
+	/** The files that were generated (paths relative to outputDir). */
+	files: GeneratedFile[];
+	/** The CodegenIR that was derived from the AppIR. */
+	ir: CodegenIR;
+	/** Number of files generated. */
+	fileCount: number;
+	/** Which generators were run. */
+	generators: string[];
+	/** Incremental write stats (only present when incremental mode is used). */
+	incremental?: IncrementalResult;
+}
+/**
+* Top-level orchestrator that ties together the full codegen pipeline:
+* 1. Converts AppIR to CodegenIR via the IR adapter
+* 2. Runs configured generators to produce GeneratedFile[]
+* 3. Optionally formats output with Biome
+* 4. Writes files to disk (incrementally when enabled)
+*/
+declare function generate(appIR: AppIR, config: ResolvedCodegenConfig): Promise<GenerateResult>;
+declare function emitCommandDefinition(op: CodegenOperation): string;
+declare function emitModuleCommands(module: CodegenModule): string;
+declare function emitManifestFile(ir: CodegenIR): GeneratedFile;
+interface BinEntryPointOptions {
+	cliName: string;
+	cliVersion: string;
+}
+declare function emitBinEntryPoint(options: BinEntryPointOptions): GeneratedFile;
+interface CLIPackageOptions {
+	packageName: string;
+	packageVersion?: string;
+	cliName: string;
+}
+declare function scaffoldCLIPackageJson(options: CLIPackageOptions): GeneratedFile;
+declare function scaffoldCLIRootIndex(): GeneratedFile;
+declare function emitSDKConfig(auth: CodegenAuth): FileFragment;
+declare function emitAuthStrategyBuilder(auth: CodegenAuth): FileFragment;
+declare function emitOperationMethod(op: CodegenOperation): FileFragment;
+declare function emitStreamingMethod(op: CodegenOperation): FileFragment;
+declare function emitModuleFile(module: CodegenModule): GeneratedFile;
+declare function emitClientFile(ir: CodegenIR): GeneratedFile;
+declare function emitSchemaReExports(schemas: CodegenSchema[]): GeneratedFile;
+interface PackageOptions {
+	packageName: string;
+	packageVersion?: string;
+}
+declare function emitBarrelIndex(ir: CodegenIR): GeneratedFile;
+declare function emitPackageJson(ir: CodegenIR, options: PackageOptions): GeneratedFile;
+declare function emitInterfaceFromSchema(schema: CodegenSchema): FileFragment;
+declare function emitOperationInputType(op: CodegenOperation): FileFragment;
+declare function emitOperationResponseType(op: CodegenOperation): FileFragment;
+declare function emitStreamingEventType(op: CodegenOperation): FileFragment;
+declare function emitModuleTypesFile(module: CodegenModule, schemas: CodegenSchema[]): GeneratedFile;
+declare function emitSharedTypesFile(schemas: CodegenSchema[]): GeneratedFile;
+/**
+* Emits a route map interface that maps route keys (e.g., 'GET /users/:id')
+* to their input/output types for type-safe test app usage.
+*/
+declare function emitRouteMapType(ir: CodegenIR): GeneratedFile;
+/**
+* Returns a SHA-256 hex hash of the given content string.
+* Used for comparing generated file content against what is already on disk.
+*/
+declare function hashContent(content: string): string;
+import { AppIR as AppIR2 } from "@vertz/compiler";
+declare function adaptIR(appIR: AppIR2): CodegenIR;
+interface ConversionContext {
+	namedTypes: Map<string, string>;
+	resolving: Set<string>;
+}
+interface ConversionResult {
+	type: string;
+	extractedTypes: Map<string, string>;
+}
+declare function jsonSchemaToTS(schema: JsonSchema, ctx?: ConversionContext): ConversionResult;
+interface CodegenPipeline {
+	validate(config: CodegenConfig): string[];
+	generate(ir: CodegenIR, config: CodegenConfig): GenerateResult;
+	resolveOutputDir(config: CodegenConfig): string;
+	resolveConfig(config: CodegenConfig): ReturnType<typeof resolveCodegenConfig>;
+}
+declare function createCodegenPipeline(): CodegenPipeline;
+declare function mergeImports(imports: Import[]): Import[];
+declare function renderImports(imports: Import[]): string;
+declare function toPascalCase(input: string): string;
+declare function toCamelCase(input: string): string;
+declare function toKebabCase(input: string): string;
+declare function toSnakeCase(input: string): string;
+export { writeIncremental, validateCodegenConfig, toSnakeCase, toPascalCase, toKebabCase, toCamelCase, scaffoldCLIRootIndex, scaffoldCLIPackageJson, resolveCodegenConfig, renderImports, mergeImports, jsonSchemaToTS, hashContent, generate, formatWithBiome, emitStreamingMethod, emitStreamingEventType, emitSharedTypesFile, emitSchemaReExports, emitSDKConfig, emitRouteMapType, emitPackageJson, emitOperationResponseType, emitOperationMethod, emitOperationInputType, emitModuleTypesFile, emitModuleFile, emitModuleCommands, emitManifestFile, emitInterfaceFromSchema, emitCommandDefinition, emitClientFile, emitBinEntryPoint, emitBarrelIndex, emitAuthStrategyBuilder, defineCodegenConfig, createCodegenPipeline, adaptIR, StreamingConfig, SchemaNamingParts, SchemaAnnotations, ResolvedCodegenConfig, PackageOptions, OperationSchemaRefs, OperationAuth, OAuthFlows, JsonSchema, IncrementalResult, IncrementalOptions, Import, HttpMethod, GeneratorName, GeneratorConfig, Generator, GeneratedFile, GenerateResult, FileFragment, ConversionResult, ConversionContext, CodegenTypescriptConfig, CodegenSchema, CodegenPublishableConfig, CodegenPipeline, CodegenOperation, CodegenModule, CodegenIR, CodegenConfig, CodegenCLIPublishableConfig, CodegenCLIConfig, CodegenAuthScheme, CodegenAuth, CLIPackageOptions, BinEntryPointOptions };