@vertz/codegen 0.2.0 → 0.2.3

package/README.md

@@ -1,242 +1,31 @@
 # @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.
+> **Internal package** — You don't use this directly. It powers `vertz codegen` behind the scenes.
 
-Code generation for Vertz applications. Generates TypeScript SDKs, CLIs, and type definitions from your Vertz app's intermediate representation (IR).
+Generates TypeScript SDKs, CLI clients, and type definitions from your Vertz app's compiled intermediate representation (IR). The generated code is fully type-safe — input/output types, schema types, and streaming event types are all preserved.
 
-## What it does
+## Who uses this
 
-`@vertz/codegen` transforms your Vertz app's compiled IR into:
+- **`@vertz/cli`** — The `vertz codegen` command invokes this package.
+- **Framework contributors** — See [INTERNALS.md](./INTERNALS.md) for generator architecture, custom generators, and the IR adapter.
 
-- **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
+## How it fits in
 
-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
-  }
-}
+Your Vertz app (*.ts)
+       ↓
+@vertz/compiler → AppIR (intermediate representation)
+       ↓
+@vertz/codegen → Generated SDK, CLI, types
+       ↓
+.vertz/generated/
 ```
 
 ## 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
+- [`@vertz/compiler`](../compiler) — Produces the IR that codegen consumes
+- [`@vertz/cli`](../cli) — Provides the `vertz codegen` command
+- [`@vertz/cli-runtime`](../cli-runtime) — Runtime for generated CLIs
 
 ## License
 

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-type GeneratorName = "typescript" | "cli";
+type GeneratorName = "typescript";
 interface CodegenPublishableConfig {
 	/** Package name, e.g., '@myapp/sdk' */
 	name: string;
@@ -17,16 +17,6 @@ interface CodegenTypescriptConfig {
 	/** 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[];
@@ -38,8 +28,6 @@ interface CodegenConfig {
 	incremental?: boolean;
 	/** TypeScript SDK options */
 	typescript?: CodegenTypescriptConfig;
-	/** CLI options */
-	cli?: CodegenCLIConfig;
 }
 interface ResolvedCodegenConfig {
 	generators: GeneratorName[];
@@ -47,7 +35,6 @@ interface ResolvedCodegenConfig {
 	format?: boolean;
 	incremental?: boolean;
 	typescript?: CodegenTypescriptConfig;
-	cli?: CodegenCLIConfig;
 }
 declare function defineCodegenConfig(config: CodegenConfig): CodegenConfig;
 declare function resolveCodegenConfig(config?: CodegenConfig): ResolvedCodegenConfig;
@@ -59,6 +46,7 @@ interface CodegenIR {
 	version?: string;
 	modules: CodegenModule[];
 	schemas: CodegenSchema[];
+	entities: CodegenEntityModule[];
 	auth: CodegenAuth;
 }
 interface CodegenModule {
@@ -150,6 +138,38 @@ interface SchemaNamingParts {
 	entity?: string;
 	part?: string;
 }
+interface CodegenEntityModule {
+	entityName: string;
+	operations: CodegenEntityOperation[];
+	actions: CodegenEntityAction[];
+}
+interface CodegenEntityOperation {
+	kind: "list" | "get" | "create" | "update" | "delete";
+	method: string;
+	path: string;
+	operationId: string;
+	inputSchema?: string;
+	outputSchema?: string;
+	resolvedFields?: CodegenResolvedField[];
+	responseFields?: CodegenResolvedField[];
+}
+/** Structured field info for schema generation. */
+interface CodegenResolvedField {
+	name: string;
+	tsType: "string" | "number" | "boolean" | "date" | "unknown";
+	optional: boolean;
+}
+interface CodegenEntityAction {
+	name: string;
+	method: string;
+	operationId: string;
+	path: string;
+	hasId: boolean;
+	inputSchema?: string;
+	outputSchema?: string;
+	resolvedInputFields?: CodegenResolvedField[];
+	resolvedOutputFields?: CodegenResolvedField[];
+}
 interface Generator {
 	readonly name: string;
 	generate(ir: CodegenIR, config: GeneratorConfig): GeneratedFile[];
@@ -212,6 +232,12 @@ interface GenerateResult {
 	incremental?: IncrementalResult;
 }
 /**
+* Merges the `imports` field from the generated package.json into the
+* project's root package.json. This enables `#generated` and
+* `#generated/types` subpath imports that enforce the public API surface.
+*/
+declare function mergeImportsToPackageJson(files: GeneratedFile[], outputDir: string): Promise<boolean>;
+/**
 * 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[]
@@ -219,45 +245,34 @@ interface GenerateResult {
 * 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;
+declare class ClientGenerator implements Generator {
+	readonly name = "client";
+	generate(ir: CodegenIR, config: GeneratorConfig): GeneratedFile[];
+	private generateClient;
+	private generatePackageJson;
+	private generateReadme;
+	private getEntityMethods;
+}
+declare class EntitySchemaGenerator implements Generator {
+	readonly name = "entity-schema";
+	generate(ir: CodegenIR, _config: GeneratorConfig): GeneratedFile[];
+	private generateEntitySchema;
+	private generateIndex;
+}
+declare class EntitySdkGenerator implements Generator {
+	readonly name = "entity-sdk";
+	generate(ir: CodegenIR, _config: GeneratorConfig): GeneratedFile[];
+	private generateEntitySdk;
+	private generateIndex;
+}
+declare class EntityTypesGenerator implements Generator {
+	readonly name = "entity-types";
+	generate(ir: CodegenIR, _config: GeneratorConfig): GeneratedFile[];
+	private generateEntityTypes;
+	private emitBodyType;
+	private emitResponseType;
+	private generateIndex;
+}
 /**
 * Returns a SHA-256 hex hash of the given content string.
 * Used for comparing generated file content against what is already on disk.
@@ -287,4 +302,4 @@ 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 };
+export { writeIncremental, validateCodegenConfig, toSnakeCase, toPascalCase, toKebabCase, toCamelCase, resolveCodegenConfig, renderImports, mergeImportsToPackageJson, mergeImports, jsonSchemaToTS, hashContent, generate, formatWithBiome, defineCodegenConfig, createCodegenPipeline, adaptIR, StreamingConfig, SchemaNamingParts, SchemaAnnotations, ResolvedCodegenConfig, OperationSchemaRefs, OperationAuth, OAuthFlows, JsonSchema, IncrementalResult, IncrementalOptions, Import, HttpMethod, GeneratorName, GeneratorConfig, Generator, GeneratedFile, GenerateResult, FileFragment, EntityTypesGenerator, EntitySdkGenerator, EntitySchemaGenerator, ConversionResult, ConversionContext, CodegenTypescriptConfig, CodegenSchema, CodegenResolvedField, CodegenPublishableConfig, CodegenPipeline, CodegenOperation, CodegenModule, CodegenIR, CodegenEntityOperation, CodegenEntityModule, CodegenEntityAction, CodegenConfig, CodegenAuthScheme, CodegenAuth, ClientGenerator };