diff --git a/.kiro/steering/code-generation-flow.md b/.kiro/steering/code-generation-flow.md new file mode 120000 index 0000000..878c518 --- /dev/null +++ b/.kiro/steering/code-generation-flow.md @@ -0,0 +1 @@ +../../docs/code-generation-flow.md \ No newline at end of file diff --git a/.kiro/steering/dependency-management.md b/.kiro/steering/dependency-management.md new file mode 120000 index 0000000..5c29a31 --- /dev/null +++ b/.kiro/steering/dependency-management.md @@ -0,0 +1 @@ +../../docs/dependency-management.md \ No newline at end of file diff --git a/.kiro/steering/generic-types.md b/.kiro/steering/generic-types.md new file mode 120000 index 0000000..4e102a5 --- /dev/null +++ b/.kiro/steering/generic-types.md @@ -0,0 +1 @@ +../../docs/generic-types.md \ No newline at end of file diff --git a/.kiro/steering/handler-system.md b/.kiro/steering/handler-system.md new file mode 120000 index 0000000..d1ad0cd --- /dev/null +++ b/.kiro/steering/handler-system.md @@ -0,0 +1 @@ +../../docs/handler-system.md \ No newline at end of file diff --git a/.kiro/steering/import-resolution.md b/.kiro/steering/import-resolution.md new file mode 120000 index 0000000..ee8cd64 --- /dev/null +++ b/.kiro/steering/import-resolution.md @@ -0,0 +1 @@ +../../docs/import-resolution.md \ No newline at end of file diff --git a/.kiro/steering/interface-inheritance.md b/.kiro/steering/interface-inheritance.md new file mode 120000 index 0000000..d2844b8 --- /dev/null +++ b/.kiro/steering/interface-inheritance.md @@ -0,0 +1 @@ +../../docs/interface-inheritance.md \ No newline at end of file diff --git a/.kiro/steering/parser-system.md b/.kiro/steering/parser-system.md new file mode 120000 index 0000000..c0acc9c --- /dev/null +++ b/.kiro/steering/parser-system.md @@ -0,0 +1 @@ +../../docs/parser-system.md \ No newline at end of file diff --git a/.kiro/steering/project-overview.md b/.kiro/steering/project-overview.md new file mode 120000 index 0000000..29367ea --- /dev/null +++ b/.kiro/steering/project-overview.md @@ -0,0 +1 @@ +../../docs/overview.md \ No newline at end of file diff --git a/.kiro/steering/system-architecture.md b/.kiro/steering/system-architecture.md new file mode 120000 index 0000000..d5de3a1 --- /dev/null +++ b/.kiro/steering/system-architecture.md @@ -0,0 +1 @@ +../../docs/architecture.md \ No newline at end of file diff --git a/.kiro/steering/testing-strategy.md b/.kiro/steering/testing-strategy.md new file mode 120000 index 0000000..71646ae --- /dev/null +++ b/.kiro/steering/testing-strategy.md @@ -0,0 +1 @@ +../../docs/testing.md \ No newline at end of file diff --git a/.kiro/steering/utilities.md b/.kiro/steering/utilities.md new file mode 120000 index 0000000..b78b234 --- /dev/null +++ b/.kiro/steering/utilities.md @@ -0,0 +1 @@ +../../docs/utilities.md \ No newline at end of file diff --git a/.trae/rules/architecture.md b/.trae/rules/architecture.md new file mode 120000 index 0000000..d5de3a1 --- /dev/null +++ b/.trae/rules/architecture.md @@ -0,0 +1 @@ +../../docs/architecture.md \ No newline at end of file diff --git a/.trae/rules/code-generation-flow.md b/.trae/rules/code-generation-flow.md new file mode 120000 index 0000000..878c518 --- /dev/null +++ b/.trae/rules/code-generation-flow.md @@ -0,0 +1 @@ +../../docs/code-generation-flow.md \ No newline at end of file diff --git a/.trae/rules/dependency-management.md b/.trae/rules/dependency-management.md new file mode 120000 index 0000000..5c29a31 --- /dev/null +++ b/.trae/rules/dependency-management.md @@ -0,0 +1 @@ +../../docs/dependency-management.md \ No newline at end of file diff --git a/.trae/rules/generic-types.md b/.trae/rules/generic-types.md new file mode 120000 index 0000000..4e102a5 --- /dev/null +++ b/.trae/rules/generic-types.md @@ -0,0 +1 @@ +../../docs/generic-types.md \ No newline at end of file diff --git a/.trae/rules/handler-system.md b/.trae/rules/handler-system.md new file mode 120000 index 0000000..d1ad0cd --- /dev/null +++ b/.trae/rules/handler-system.md @@ -0,0 +1 @@ +../../docs/handler-system.md \ No newline at end of file diff --git a/.trae/rules/import-resolution.md b/.trae/rules/import-resolution.md new file mode 120000 index 0000000..ee8cd64 --- /dev/null +++ b/.trae/rules/import-resolution.md @@ -0,0 +1 @@ +../../docs/import-resolution.md \ No newline at end of file diff --git a/.trae/rules/interface-inheritance.md b/.trae/rules/interface-inheritance.md new file mode 120000 index 0000000..d2844b8 --- /dev/null +++ b/.trae/rules/interface-inheritance.md @@ -0,0 +1 @@ +../../docs/interface-inheritance.md \ No newline at end of file diff --git a/.trae/rules/overview.md b/.trae/rules/overview.md new file mode 120000 index 0000000..29367ea --- /dev/null +++ b/.trae/rules/overview.md @@ -0,0 +1 @@ +../../docs/overview.md \ No newline at end of file diff --git a/.trae/rules/parser-system.md b/.trae/rules/parser-system.md new file mode 120000 index 0000000..c0acc9c --- /dev/null +++ b/.trae/rules/parser-system.md @@ -0,0 +1 @@ +../../docs/parser-system.md \ No newline at end of file diff --git a/.trae/rules/project_architecture.md b/.trae/rules/project_architecture.md deleted file mode 120000 index 708f0d2..0000000 --- a/.trae/rules/project_architecture.md +++ /dev/null @@ -1 +0,0 @@ -ARCHITECTURE.md \ No newline at end of file diff --git a/.trae/rules/testing.md b/.trae/rules/testing.md new file mode 120000 index 0000000..71646ae --- /dev/null +++ b/.trae/rules/testing.md @@ -0,0 +1 @@ +../../docs/testing.md \ No newline at end of file diff --git a/.trae/rules/utilities.md b/.trae/rules/utilities.md new file mode 120000 index 0000000..b78b234 --- /dev/null +++ b/.trae/rules/utilities.md @@ -0,0 +1 @@ +../../docs/utilities.md \ No newline at end of file diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index a3cd867..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,404 +0,0 @@ -# Architecture - -## Table of Contents - -- [Overview](#overview) -- [Core Components](#core-components) - - [Code Generation Flow](#code-generation-flow) - - [TypeBox Printer](#typebox-printer) - - [Dependency Management](#dependency-management) - - [Parser System](#parser-system) - - [Handler System](#handler-system) - - [Import Resolution](#import-resolution) - - [Input Handling](#input-handling) - - [Interface Inheritance](#interface-inheritance) - - [Utility Functions](#utility-functions) -- [Process Overview](#process-overview) -- [Basic Usage](#basic-usage) -- [Testing](#testing) - -## Overview - -`@daxserver/validation-schema-codegen` is a comprehensive codegen tool for validation schemas that transforms TypeScript type definitions into TypeBox validation schemas. This project serves as an enhanced alternative to `@sinclair/typebox-codegen`, providing superior type handling capabilities and advanced dependency management through graph-based analysis. - -### Supported TypeScript Constructs - -- **Type Definitions**: Type aliases, interfaces, enums, and function declarations -- **Generic Types**: Generic interfaces and type aliases with type parameters and proper constraint handling -- **Complex Types**: Union and intersection types, nested object structures, template literal types -- **Utility Types**: Built-in support for Pick, Omit, Partial, Required, Record, Readonly, and other TypeScript utility types -- **Advanced Features**: Conditional types, mapped types, keyof operators, indexed access types -- **JavaScript Built-in Types**: Native support for Date type using TypeBox's JavaScript type system -- **Import Resolution**: Cross-file type dependencies with qualified naming and circular dependency handling - -## Core Components - -The main logic for code generation resides in the file. Its primary function, `generateCode`, takes a `GenerateCodeOptions` object as input and returns a string containing the generated TypeBox code. The input can be either a file path or source code string, with support for relative imports when using existing project contexts. - -### Code Generation Flow - -The `generateCode` function in orchestrates the entire code generation process: - -1. **Input Processing**: Creates a `SourceFile` from input using `createSourceFileFromInput` -2. **Generic Type Detection**: Checks for generic interfaces and type aliases to determine required TypeBox imports (including `TSchema`) -3. **Output File Creation**: Creates a new output file with necessary `@sinclair/typebox` imports using `createOutputFile` -4. **Dependency Traversal**: Uses `DependencyTraversal` to analyze and sort all type dependencies -5. **Code Generation**: Processes sorted nodes using `TypeBoxPrinter` in `printSortedNodes` -6. **Output Formatting**: Returns the formatted TypeBox schema code - -### TypeBox Printer - -The class orchestrates the parsing and printing of TypeScript nodes into TypeBox schemas: - -- **Unified Processing**: Handles type aliases, interfaces, enums, and function declarations through a single interface -- **Parser Coordination**: Utilizes dedicated parsers (`TypeAliasParser`, `InterfaceParser`, `EnumParser`, `FunctionDeclarationParser`) -- **Type Tracking**: Maintains a `processedTypes` set to avoid redundant processing -- **Output Management**: Coordinates with the output `SourceFile` and TypeScript printer - -### Dependency Management - -The system uses a sophisticated graph-based dependency management approach centered around the `DependencyTraversal` class: - -#### Architecture Overview - -The dependency system consists of three main components: - -1. **DependencyTraversal**: - Main orchestrator -2. **FileGraph**: - Tracks file-level dependencies -3. **NodeGraph**: - Manages type-level dependencies - -#### Process Flow - -1. **Local Type Collection**: Adds all types from the main source file -2. **Import Processing**: Recursively processes import declarations -3. **Dependency Extraction**: Analyzes type references to build dependency graph for all supported TypeScript constructs: - - **Type Aliases**: Extracts dependencies from type alias declarations - - **Interfaces**: Analyzes interface property types and heritage clauses - - **Enums**: Processes enum member value dependencies - - **Functions**: Extracts dependencies from parameter types, return types, and type parameters -4. **Topological Sorting**: Returns nodes in proper dependency order - -#### Graph Visualization - -The system includes interactive graph visualization capabilities through the `GraphVisualizer` utility: - -- **Sigma.js Integration**: Uses ES6 modules with unpkg CDN for interactive HTML-based graph visualization -- **Custom Node Shapes**: Implements WebGL-based custom node programs for different TypeScript constructs: - - **Diamond**: Interface types (rotated square program) - - **Square**: Type alias declarations - - **Triangle**: Enum declarations - - **Star**: Function declarations - - **Circle**: Default/other types -- **ForceAtlas2 Layout**: Single optimized layout algorithm for automatic node positioning with gravity and scaling controls -- **Enhanced Node Differentiation**: - - **Size Variation**: Different node sizes based on type and importance (main code vs imported) - - **Color Coding**: Type-specific colors with intensity variation based on import nesting level - - **Shape Mapping**: Direct visual shape differentiation using custom WebGL node programs - - **Visual Legend**: CSS-styled legend showing actual shape representations -- **Import Nesting Visualization**: Color intensity reflects import depth, with main code having brightest colors -- **Interactive Features**: Click events for node details, zoom/pan capabilities, and hover tooltips -- **Export Options**: Generates standalone HTML files with embedded visualization and complete styling -- **WebGL Programs**: Custom node renderers extending `@sigma/node-square` and `@sigma/node-border` packages - -### Parser System - -The parser system is built around a base class architecture in : - -#### Base Parser - -The provides: - -- Common interface for all parsers -- Shared access to output `SourceFile`, TypeScript printer, and processed types tracking -- Abstract `parse` method for implementation by specific parsers - -#### Specialized Parsers - -1. **InterfaceParser**: - Handles both regular and generic interfaces using the unified `GenericTypeUtils` flow for consistency with type aliases -2. **TypeAliasParser**: - Processes both regular and generic type alias declarations using `GenericTypeUtils.createGenericArrowFunction` -3. **EnumParser**: - Handles enum declarations -4. **FunctionParser**: - Processes function declarations -5. **ImportParser**: - Handles import resolution - -### Handler System - -The handler system in provides TypeBox-specific type conversion through a hierarchical architecture: - -#### Handler Categories - -1. **Base Handlers**: Foundation classes including and specialized base classes -2. **Collection Handlers**: , , , -3. **Object Handlers**: (returns raw TypeBox expressions for generic interfaces, allowing parser-level arrow function wrapping), -4. **Reference Handlers**: , , , , -5. **Readonly Handlers**: , -6. **Simple Handlers**: , -7. **Advanced Handlers**: , , -8. **Function Handlers**: -9. **JavaScript Type Handlers**: - Handles JavaScript built-in types like Date using TypeBox's extended type system -10. **Type Query Handlers**: , -11. **Access Handlers**: , - -#### Readonly Type Handling - -The system provides comprehensive support for TypeScript's two distinct readonly constructs through a dual-handler approach: - -1. **Readonly Utility Type**: `Readonly` - Handled by - - Registered as a type reference handler for `Readonly` type references - - Processes `TypeReferenceNode` with identifier "Readonly" - - Generates `Type.Readonly(innerType)` for utility type syntax - -2. **Readonly Array Modifier**: `readonly T[]` - Handled by - - Extends `TypeOperatorBaseHandler` for `ReadonlyKeyword` operator - - Processes `TypeOperatorTypeNode` with `SyntaxKind.ReadonlyKeyword` - - Generates `Type.Readonly(innerType)` for array modifier syntax - - Registered as a fallback handler to handle complex readonly patterns - -This dual approach ensures proper handling of both TypeScript readonly constructs: - -- `type ReadonlyUser = Readonly` (utility type) -- `type ReadonlyArray = readonly string[]` (array modifier) -- `type ReadonlyTuple = readonly [string, number]` (tuple modifier) - -#### JavaScript Built-in Type Support - -The system provides comprehensive support for JavaScript built-in types through specialized handlers: - -- **Date Type Handler**: The handles TypeScript's `Date` type references and converts them to TypeBox's `Type.Date()` schema -- **Type Reference Registration**: JavaScript built-in types are registered in the `typeReferenceHandlers` map for O(1) lookup performance -- **Extended Type System**: Leverages TypeBox's JavaScript type system for types that extend beyond standard JSON Schema - -#### Handler Management - -The class orchestrates all handlers through: - -- **Handler Caching**: Caches handler instances for performance optimization -- **Type Reference Mapping**: O(1) lookup for built-in types like Date, utility types like Partial, and other type references -- **Fallback System**: Provides fallback handlers for complex cases including readonly array modifiers - -### Import Resolution - -The import resolution system handles complex import scenarios: - -- **Multi-level Imports**: Supports nested import chains of any depth -- **Circular Import Detection**: Prevents infinite loops during traversal -- **Qualified Naming**: Resolves type name collisions across files - -### Input Handling - -The module provides flexible input processing capabilities for the code generation system. It supports multiple input methods and handles various edge cases related to file resolution and import validation. - -#### InputOptions Interface - -The `InputOptions` interface defines the available input parameters: - -```typescript -export interface InputOptions { - filePath?: string // Path to TypeScript file - sourceCode?: string // TypeScript source code as string - callerFile?: string // Context file path for relative import resolution - project?: Project // Existing ts-morph Project instance -} -``` - -#### Input Processing Features - -1. **Dual Input Support**: Accepts either file paths or source code strings -2. **Path Resolution**: Handles both absolute and relative file paths with proper validation -3. **Relative Import Validation**: Prevents relative imports in string-based source code unless a `callerFile` context is provided -4. **Project Context Sharing**: Supports passing existing `ts-morph` Project instances to maintain import resolution context -5. **Error Handling**: Provides clear error messages for invalid inputs and unresolvable paths - -#### Usage Patterns - -- **File Path Input**: Automatically resolves and loads TypeScript files from disk -- **Source Code Input**: Processes TypeScript code directly from strings with validation -- **Project Context**: Enables proper relative import resolution when working with in-memory source files - -### Generic Type Support - -The codebase provides comprehensive support for both generic interfaces and generic type aliases, enabling complex type transformations and reusable type definitions. - -#### Generic Type Aliases - -The `TypeAliasParser` handles both regular and generic type aliases through specialized processing: - -1. **Type Parameter Detection**: Automatically detects type parameters using `typeAlias.getTypeParameters()` -2. **Function Generation**: Creates TypeBox functions for generic type aliases with proper parameter constraints -3. **TSchema Constraints**: Applies `TSchema` constraints to all type parameters for TypeBox compatibility -4. **Static Type Generation**: Generates corresponding TypeScript type aliases using `Static>>` - -#### Generic Interface Support - -Generic interfaces are processed through the `InterfaceParser` using a consistent architectural pattern that mirrors the type alias flow: - -1. **Unified Generic Processing**: The interface parser now uses the same `GenericTypeUtils.createGenericArrowFunction` flow as type aliases for consistency -2. **Raw Expression Handling**: The `InterfaceTypeHandler` returns raw TypeBox expressions for generic interfaces, allowing the parser to handle arrow function wrapping -3. **Parameter Constraint Handling**: Converts TypeScript type parameter constraints to `TSchema` constraints using shared utilities -4. **Function-Based Schema Generation**: Creates TypeBox schema functions that accept type parameters through the standardized generic arrow function pattern -5. **Type Safety Preservation**: Maintains full TypeScript type safety through proper static type aliases using `Static>>` -6. **Architectural Consistency**: Both generic interfaces and type aliases now follow the same code generation pattern, improving maintainability and reducing duplication - -#### Complex Generic Scenarios - -The system supports advanced generic patterns including: - -- **Multiple Type Parameters**: Functions with multiple generic parameters (e.g., `ApiResponse`) -- **Nested Generic Types**: Generic types that reference other generic types -- **Utility Type Combinations**: Complex combinations like `Partial>>` -- **Type Parameter Propagation**: Proper handling of type parameters across nested type references - -### Interface Inheritance - -The codebase provides comprehensive support for TypeScript interface inheritance through a sophisticated dependency resolution and code generation system: - -#### Dependency-Ordered Processing - -1. **Separate Graph Analysis**: Uses with specialized FileGraph and NodeGraph classes to analyze complex relationships between interfaces and type aliases -2. **Specialized Graph Processing**: Leverages NodeGraph's topological sorting for robust type dependency ordering with domain-specific optimizations -3. **Type-Focused Processing**: NodeGraph handles type node dependencies independently from file dependencies for cleaner separation of concerns -4. **Topological Sorting**: Uses `NodeGraph.getNodesToPrint()` to ensure types are processed in correct dependency order to prevent "type not found" errors -5. **Circular Dependency Detection**: The NodeGraph provides built-in circular dependency detection specifically for type relationships with detailed error reporting - -#### TypeBox Composite Generation - -Interface inheritance is implemented using TypeBox's `Type.Composite` functionality: - -- **Base Interface Reference**: Extended interfaces reference their base interfaces by name as identifiers -- **Property Combination**: The `InterfaceTypeHandler` generates `Type.Composite([BaseInterface, Type.Object({...})])` for extended interfaces -- **Type Safety**: Generated code maintains full TypeScript type safety through proper static type aliases -- **Generic Type Parameter Handling**: Uses `TSchema` as the constraint for TypeBox compatibility instead of preserving original TypeScript constraints - -#### Implementation Details - -- **Heritage Clause Processing**: The processes `extends` clauses by extracting referenced type names -- **Identifier Generation**: Base interface references are converted to TypeScript identifiers rather than attempting recursive type resolution -- **TypeBox Constraint Normalization**: Generic type parameters use `TSchema` constraints for TypeBox schema compatibility -- **Error Prevention**: The dependency ordering prevents "No handler found for type" errors that occur when extended interfaces are processed before their base interfaces - -### Utility Functions - -The directory provides essential utilities for the TypeBox code generation process: - -#### Core Utility Modules - -- : Contains the core logic for converting TypeScript type nodes into TypeBox `Type` expressions. `getTypeBoxType` takes a `TypeNode` as input and returns a `ts.Node` representing the equivalent TypeBox schema. -- : Generates and adds the `export type [TypeName] = Static` declaration to the output source file. This declaration is essential for enabling TypeScript's static type inference from the dynamically generated TypeBox schemas, ensuring type safety at compile time. -- : Contains general utility functions that support the TypeBox code generation process, such as helper functions for string manipulation or AST node creation. -- : Provides shared utilities for extracting string literal keys from union or literal types, used by Pick and Omit type handlers to avoid code duplication. -- : Contains common Node type checking utilities for `canHandle` methods, including functions for checking SyntaxKind, TypeOperator patterns, and TypeReference patterns. -- : Processes literal type nodes within template literals, handling the conversion of embedded literal values into TypeBox expressions for template literal type generation. - -#### Template Literal Processing - -- **Template Literal Type Processor**: Handles the complex parsing and conversion of TypeScript template literal types into TypeBox `TemplateLiteral` expressions -- **Literal Node Processing**: Converts various literal types (string, number, boolean) within template contexts -- **Pattern Recognition**: Identifies and processes template literal patterns with embedded type expressions - -#### Key Extraction System - -- **String Key Extraction**: Extracts string literal keys from union types and object type literals for use in utility type handlers -- **TypeBox Expression Generation**: Converts extracted keys into appropriate TypeBox array expressions -- **Shared Utilities**: Provides reusable key extraction logic for Pick, Omit, and other utility type handlers to avoid code duplication - -#### Generic Type Utilities - -The module provides shared utilities for consistent generic type handling across parsers: - -- **Generic Arrow Function Creation**: `createGenericArrowFunction` creates standardized arrow functions for generic types with proper type parameter constraints -- **Type Parameter Processing**: Converts TypeScript type parameters to TypeBox-compatible function parameters with `TSchema` constraints -- **Variable Statement Generation**: `addTypeBoxVariableStatement` creates consistent variable declarations for TypeBox schemas -- **Generic Type Alias Generation**: `addGenericTypeAlias` creates standardized static type aliases using `Static>>` -- **Architectural Consistency**: Ensures both interface and type alias parsers follow the same generic type processing pattern - -## Process Overview - -1. **Input**: A TypeScript source file containing `enum`, `type alias`, `interface`, and `function` declarations. -2. **Parsing**: `ts-morph` parses the input TypeScript file into an Abstract Syntax Tree (AST). -3. **Centralized Dependency Traversal**: The `DependencyTraversal.startTraversal()` method orchestrates the complete dependency collection and ordering process: - -- Collects local types from the main source file -- Recursively traverses import chains to gather all dependencies -- Establishes dependency relationships between all types -- Returns topologically sorted nodes for processing - -4. **Sequential Node Processing**: The sorted nodes are processed sequentially using specialized parsers, ensuring dependencies are handled before dependent types. -5. **TypeBox Schema Generation**: For each node, the corresponding TypeBox schema is constructed using appropriate `Type` methods (e.g., `Type.Enum`, `Type.Object`, `Type.Function`, etc.). This process involves sophisticated mapping of TypeScript types to their TypeBox equivalents. -6. **Static Type Generation**: Alongside each TypeBox schema, a TypeScript `type` alias is generated using `Static` to provide compile-time type safety and seamless integration with existing TypeScript code. -7. **Output**: A new TypeScript file (as a string) containing the generated TypeBox schemas and static type aliases, ready to be written to disk or integrated into your application. - -## Basic Usage - -```typescript -const result = generateCode({ - sourceCode: sourceFile.getFullText(), - callerFile: sourceFile.getFilePath(), -}) -``` - -### Using File Path - -```typescript -const result = generateCode({ - filePath: './types.ts', -}) -``` - -## Testing - -### Test Structure - -- **Unit Tests**: Individual component testing using Bun's test framework -- **Integration Tests**: End-to-end testing of the complete generation pipeline -- **Type Safety Tests**: Validation of generated TypeBox schemas -- **Edge Case Coverage**: Testing of complex scenarios and error conditions - -### Quality Tools - -- **TypeScript Compiler**: Type checking with `bun tsc` -- **ESLint**: Code quality and style enforcement -- **Prettier**: Consistent code formatting -- **Bun Test**: Fast and reliable test execution - -### TDD Cycle - -1. **Red Phase**: Write failing tests that define the desired functionality -2. **Green Phase**: Implement the minimal code necessary to make tests pass -3. **Refactor Phase**: Improve code quality while maintaining test coverage - -### Running Tests - -The project uses Bun as the test runner. Here are the key commands for running tests: - -```bash -# Run all tests -bun test - -# Run a specific test file -bun test tests/handlers/typebox/function-types.test.ts - -# Run tests in a specific directory -bun test tests/ -``` - -### TDD Workflow for New Features - -When implementing new type handlers or features: - -1. **Start with Tests**: Create test cases in the appropriate test file (e.g., `tests/handlers/typebox/function-types.test.ts` for function-related features) -2. **Run Tests First**: Execute `bun test tests/handlers/typebox/[test-file]` to confirm tests fail as expected -3. **Implement Handler**: Create or modify the type handler to make tests pass -4. **Verify Implementation**: Run tests again to ensure they pass -5. **Integration Testing**: Run the full test suite with `bun test` to ensure no regressions - -### Best Practices - -- Write tests before implementing functionality -- Keep tests focused and atomic -- Use descriptive test names that explain the expected behavior -- Test both positive and negative cases -- Include edge cases and error conditions -- Run specific tests frequently during development -- Run the full test suite before committing changes -- Run any specific tests with path like `bun test tests/handlers/typebox/function-types.test.ts` -- Run any specific test cases using command like `bun test tests/handlers/typebox/function-types.test.ts -t function types` -- If tests keep failing, take help from tsc, lint commands to detect for any issues diff --git a/README.md b/README.md index b8a9c1a..a06ad48 100644 --- a/README.md +++ b/README.md @@ -1,26 +1,68 @@ -# TypeBox Codegen Fork +`@daxserver/validation-schema-codegen` transforms TypeScript type definitions into TypeBox validation schemas. It handles complex type relationships and manages dependencies through graph-based analysis. -This project is a code generation tool designed to automate the creation of TypeBox schemas from existing TypeScript source files. It leverages the `ts-morph` library to parse TypeScript code and extract structural information from various constructs, including: +## Usage -- **Type Aliases**: Converts TypeScript type aliases into corresponding TypeBox definitions. -- **Enums**: Transforms TypeScript enums into TypeBox enum schemas. -- **Interfaces**: Processes TypeScript interfaces to generate TypeBox object schemas. -- **Function Declarations**: Analyzes function signatures to create TypeBox schemas for their parameters and return types. +```typescript +import { generateCode } from '@daxserver/validation-schema-codegen' -The primary goal is to streamline the process of defining data validation and serialization schemas by generating them directly from your TypeScript types, ensuring type safety and consistency across your application. +// Using source code string +const result = generateCode({ + sourceCode: ` + interface User { + id: string; + name: string; + email?: string; + } + `, + callerFile: './src/types.ts', +}) -## Installation +// Using file path +const result = generateCode({ + filePath: './types.ts', +}) +``` + +### Generated Output + +```typescript +import { Type, Static } from '@sinclair/typebox' + +export const User = Type.Object({ + id: Type.String(), + name: Type.String(), + email: Type.Optional(Type.String()), +}) + +export type User = Static +``` -To get started with this project, first ensure you have Bun installed. Then, install the project dependencies by running: +## Development Workflow + +### Testing ```bash -bun install +# Run all tests +bun test + +# Run specific test file +bun test tests/handlers/typebox/function-types.test.ts + +# Type checking +bun typecheck + +# Linting +bun lint + +# Formatting +bun format ``` -## Scripts +## Contributing -This project includes several utility scripts to help with development and maintenance: +When contributing to the project: -- `bun run format`: This script uses Prettier to automatically format all code files, ensuring consistent code style across the project. -- `bun run typecheck`: Runs the TypeScript compiler (`tsc`) with the `--noEmit` flag to perform a type check on the entire codebase. This helps catch type-related errors early in the development process. -- `bun run lint`: Executes ESLint to analyze the code for potential errors, stylistic issues, and adherence to best practices. This helps maintain code quality and consistency. +1. Read the relevant documentation sections for the area you're working on +2. Follow the TDD workflow outlined in [Testing Strategy](./docs/testing.md) +3. Ensure your changes align with the architectural patterns described in the documentation +4. Update documentation as needed for new features or changes diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..1d876aa --- /dev/null +++ b/docs/architecture.md @@ -0,0 +1,30 @@ +# Architecture + +``` +Input → Parser → Dependency Analysis → Handler System → Printer → Output +``` + +## Components + +1. **Input Handler** - Processes file paths or source code strings +2. **Parser System** - Parses TypeScript AST using ts-morph +3. **Dependency Analysis** - Builds dependency graph and sorts types +4. **Handler System** - Converts TypeScript types to TypeBox expressions +5. **Printer** - Generates output code + +## Process + +1. Parse TypeScript source to AST +2. Extract type declarations +3. Build dependency graph +4. Sort types by dependencies +5. Convert each type to TypeBox expression +6. Generate output code + +## Key Files + +- `src/index.ts` - Main entry point +- `src/parsers/` - TypeScript AST parsers +- `src/handlers/` - Type conversion handlers +- `src/traverse/` - Dependency analysis +- `src/printer/` - Code generation diff --git a/docs/code-generation-flow.md b/docs/code-generation-flow.md new file mode 100644 index 0000000..863948d --- /dev/null +++ b/docs/code-generation-flow.md @@ -0,0 +1,75 @@ +# Code Generation Flow + +Process for transforming TypeScript types to TypeBox schemas. + +## Main Pipeline + +```typescript +export function generateCode(options: InputOptions): string +``` + +### Steps + +1. **Input Processing** - Create SourceFile from input +2. **Generic Detection** - Check for generic types to determine imports +3. **Output Setup** - Create output file with TypeBox imports +4. **Dependency Analysis** - Use DependencyTraversal to sort types +5. **Code Generation** - Process nodes through TypeBoxPrinter +6. **Output** - Return formatted code + +## Input Types + +```typescript +interface InputOptions { + filePath?: string // File path + sourceCode?: string // Source code string + callerFile?: string // Context for relative imports + project?: Project // Existing ts-morph Project +} +``` + +## Processing Stages + +### 1. Input Handling + +- File path: Load and parse TypeScript file +- Source code: Process in-memory code with validation +- Project reuse: Share ts-morph Project instances + +### 2. Dependency Analysis + +Three-tier approach: + +- **DependencyTraversal** - Orchestrates analysis +- **FileGraph** - File-level dependencies +- **NodeGraph** - Type-level dependencies and sorting + +### 3. Type Conversion + +Each type processed through specialized parsers: + +- Type aliases → TypeAliasParser +- Interfaces → InterfaceParser +- Enums → EnumParser +- Functions → FunctionDeclarationParser + +### 4. Code Generation + +For each type: + +1. Generate TypeBox schema variable +2. Generate static type alias +3. Handle generic types with arrow functions + +## Output Format + +```typescript +import { Type, Static } from '@sinclair/typebox' + +export const User = Type.Object({ + id: Type.String(), + name: Type.String(), +}) + +export type User = Static +``` diff --git a/docs/dependency-management.md b/docs/dependency-management.md new file mode 100644 index 0000000..1608c4a --- /dev/null +++ b/docs/dependency-management.md @@ -0,0 +1,56 @@ +# Dependency Management + +Graph-based dependency analysis for proper type processing order. + +## Components + +### DependencyTraversal + +Main orchestrator in `src/traverse/dependency-traversal.ts`: + +- Coordinates dependency collection +- Returns topologically sorted nodes + +### FileGraph + +Manages file-level dependencies in `src/traverse/file-graph.ts`: + +- Tracks import relationships +- Detects circular imports + +### NodeGraph + +Handles type-level dependencies in `src/traverse/node-graph.ts`: + +- Maps type relationships +- Performs topological sorting +- Detects circular type dependencies + +## Process + +1. Collect local types from main file +2. Process import chains recursively +3. Extract type dependencies +4. Build dependency graph +5. Topological sort for processing order + +## Circular Dependencies + +### Detection + +- File-level: A imports B, B imports A +- Type-level: Type A references Type B, Type B references Type A + +### Resolution + +- Forward declarations using `Type.Ref()` +- Error reporting with dependency chains + +## Visualization + +`GraphVisualizer` generates interactive HTML visualizations: + +- Sigma.js integration +- Custom node shapes for different types +- Color coding by import depth +- WebGL rendering for performance diff --git a/docs/generic-types.md b/docs/generic-types.md new file mode 100644 index 0000000..abf841f --- /dev/null +++ b/docs/generic-types.md @@ -0,0 +1,59 @@ +# Generic Types + +Supports generic interfaces and type aliases. + +## Processing + +Both interfaces and type aliases use `GenericTypeUtils.createGenericArrowFunction` for consistency. + +### Type Aliases + +```typescript +// TypeScript +type ApiResponse = { data: T; success: boolean } + +// Generated TypeBox +export const ApiResponse = (T: T) => + Type.Object({ + data: T, + success: Type.Boolean(), + }) + +export type ApiResponse = Static>> +``` + +### Interfaces + +```typescript +// TypeScript +interface Repository { + findById(id: string): Promise +} + +// Generated TypeBox +export const Repository = (T: T) => + Type.Object({ + findById: Type.Function([Type.String()], Type.Promise(T)), + }) +``` + +## Type Parameters + +All type parameters use `TSchema` constraints for TypeBox compatibility: + +```typescript +// TypeScript: T extends object +// TypeBox: T extends TSchema +``` + +## Multiple Parameters + +```typescript +type Result = { success: true; data: T } | { success: false; error: E } + +export const Result = (T: T, E: E) => + Type.Union([ + Type.Object({ success: Type.Literal(true), data: T }), + Type.Object({ success: Type.Literal(false), error: E }), + ]) +``` diff --git a/docs/handler-system.md b/docs/handler-system.md new file mode 100644 index 0000000..c6c157d --- /dev/null +++ b/docs/handler-system.md @@ -0,0 +1,62 @@ +# Handler System + +Converts TypeScript type nodes to TypeBox expressions. + +## Base Handler + +```typescript +export abstract class BaseTypeHandler { + abstract canHandle(node: TypeNode): boolean + abstract handle(node: TypeNode): ts.Node +} +``` + +## Handler Categories + +### Simple Types + +- `SimpleTypeHandler` - string, number, boolean, null, undefined +- `LiteralTypeHandler` - string/number/boolean literals + +### Collections + +- `ArrayTypeHandler` - T[] +- `TupleTypeHandler` - [T, U] +- `UnionTypeHandler` - T | U +- `IntersectionTypeHandler` - T & U + +### Objects + +- `ObjectTypeHandler` - { prop: T } +- `InterfaceTypeHandler` - interface references + +### Utility Types + +- `PartialTypeHandler` - Partial +- `RequiredTypeHandler` - Required +- `PickTypeHandler` - Pick +- `OmitTypeHandler` - Omit +- `RecordTypeHandler` - Record + +### Advanced + +- `TemplateLiteralTypeHandler` - `template ${string}` +- `KeyofTypeHandler` - keyof T +- `IndexedAccessTypeHandler` - T[K] + +## Handler Management + +`TypeBoxTypeHandlers` class manages all handlers: + +- Caches handler instances +- O(1) lookup for type references +- Fallback system for complex cases + +## Registration + +Handlers are registered in maps for efficient lookup: + +```typescript +this.typeReferenceHandlers.set('Partial', new PartialTypeHandler()) +this.typeReferenceHandlers.set('Date', new DateTypeHandler()) +``` diff --git a/docs/import-resolution.md b/docs/import-resolution.md new file mode 100644 index 0000000..a1de55b --- /dev/null +++ b/docs/import-resolution.md @@ -0,0 +1,63 @@ +# Import Resolution + +Handles imports and input processing across multiple files. + +## Input Handler + +`src/input-handler.ts` processes various input types: + +```typescript +interface InputOptions { + filePath?: string // Path to TypeScript file + sourceCode?: string // TypeScript source code + callerFile?: string // Context for relative imports + project?: Project // Existing ts-morph Project +} +``` + +## Import Processing + +### Multi-level Imports + +Supports nested import chains: + +```typescript +// File A imports File B +import { UserType } from './user-types' + +// File B imports File C +import { BaseEntity } from '../base/entity' +``` + +### Path Resolution + +- Relative imports: `./user`, `../base/entity` +- Absolute imports: `/src/types/user` +- Module imports: `@sinclair/typebox` + +### Circular Detection + +Uses visited file tracking to prevent infinite loops: + +```typescript +if (this.processingStack.has(filePath)) { + throw new Error(`Circular import detected: ${path}`) +} +``` + +## Qualified Naming + +Resolves type name collisions across files: + +```typescript +// user/types.ts exports User +// admin/types.ts exports User +// Generated: User_Types_User, Admin_Types_User +``` + +## Error Handling + +- File not found +- Permission errors +- Invalid import syntax +- Circular dependencies diff --git a/docs/interface-inheritance.md b/docs/interface-inheritance.md new file mode 100644 index 0000000..1a6ee1d --- /dev/null +++ b/docs/interface-inheritance.md @@ -0,0 +1,77 @@ +# Interface Inheritance + +Handles TypeScript interface inheritance using TypeBox composites. + +## Processing Order + +Uses dependency analysis to ensure base interfaces are processed before derived interfaces: + +```typescript +interface BaseEntity { + id: string +} + +interface User extends BaseEntity { + // Processed after BaseEntity + name: string +} +``` + +## TypeBox Composite Generation + +### Basic Inheritance + +```typescript +// TypeScript +interface AdminUser extends BaseUser { + permissions: string[] +} + +// Generated TypeBox +export const AdminUser = Type.Composite([ + BaseUser, + Type.Object({ + permissions: Type.Array(Type.String()), + }), +]) +``` + +### Multiple Inheritance + +```typescript +// TypeScript +interface Document extends Timestamped, Versioned { + title: string +} + +// Generated TypeBox +export const Document = Type.Composite([ + Timestamped, + Versioned, + Type.Object({ + title: Type.String(), + }), +]) +``` + +## Generic Inheritance + +```typescript +// TypeScript +interface ExtendedRepository extends BaseRepository { + findAll(): Promise +} + +// Generated TypeBox +export const ExtendedRepository = (T: T) => + Type.Composite([ + BaseRepository(T), + Type.Object({ + findAll: Type.Function([], Type.Promise(Type.Array(T))), + }), + ]) +``` + +## Error Prevention + +Dependency ordering prevents "type not found" errors by ensuring base interfaces are available when referenced. diff --git a/docs/overview.md b/docs/overview.md new file mode 100644 index 0000000..2a5f067 --- /dev/null +++ b/docs/overview.md @@ -0,0 +1,49 @@ +# Overview + +Transforms TypeScript types to TypeBox schemas. + +## Supported Types + +- Type aliases +- Interfaces (including generic and inheritance) +- Enums +- Functions +- Union/intersection types +- Utility types (Pick, Omit, Partial, Required, Record, Readonly) +- Template literal types +- Date type + +## Usage + +```typescript +import { generateCode } from '@daxserver/validation-schema-codegen' + +// From file +const result = generateCode({ filePath: './types.ts' }) + +// From string +const result = generateCode({ + sourceCode: 'interface User { id: string; }', + callerFile: './types.ts', +}) +``` + +## Output + +```typescript +import { Type, Static } from '@sinclair/typebox' + +export const User = Type.Object({ + id: Type.String(), +}) + +export type User = Static +``` + +## Documentation + +- [architecture.md](./architecture.md) - System architecture +- [parser-system.md](./parser-system.md) - TypeScript parsing +- [handler-system.md](./handler-system.md) - Type conversion +- [dependency-management.md](./dependency-management.md) - Dependency analysis +- [testing.md](./testing.md) - Testing diff --git a/docs/parser-system.md b/docs/parser-system.md new file mode 100644 index 0000000..4c82ccd --- /dev/null +++ b/docs/parser-system.md @@ -0,0 +1,26 @@ +# Parser System + +Parses TypeScript AST nodes and converts them to TypeBox schemas. + +## Base Parser + +All parsers extend `BaseParser` in `src/parsers/base-parser.ts`. + +## Parsers + +- **TypeAliasParser** - `src/parsers/parse-type-aliases.ts` +- **InterfaceParser** - `src/parsers/parse-interfaces.ts` +- **EnumParser** - `src/parsers/parse-enums.ts` +- **FunctionParser** - `src/parsers/parse-function-declarations.ts` +- **ImportParser** - `src/parsers/parse-imports.ts` + +## Processing + +1. `TypeBoxPrinter` coordinates all parsers +2. Processes nodes in dependency order +3. Each parser handles specific TypeScript constructs +4. Delegates type conversion to handler system + +## Generic Types + +Both interfaces and type aliases use `GenericTypeUtils.createGenericArrowFunction` for consistent generic processing. diff --git a/docs/testing.md b/docs/testing.md new file mode 100644 index 0000000..620b935 --- /dev/null +++ b/docs/testing.md @@ -0,0 +1,46 @@ +# Testing + +Uses Bun test runner with TDD approach. + +## Commands + +```bash +# Run all tests +bun test + +# Run specific test file +bun test tests/handlers/typebox/function-types.test.ts + +# Type checking +bun typecheck + +# Linting +bun lint + +# Formatting +bun format +``` + +## Test Structure + +``` +tests/ +├── handlers/typebox/ # Handler unit tests +├── parsers/ # Parser tests +├── traverse/ # Dependency analysis tests +└── utils/ # Utility tests +``` + +## TDD Workflow + +1. Write failing test +2. Implement minimal code to pass +3. Refactor while keeping tests green +4. Run full test suite before commit + +## Test Types + +- **Unit tests** - Individual components +- **Integration tests** - End-to-end generation +- **Type safety tests** - Generated schema validation +- **Edge case tests** - Error conditions and complex scenarios diff --git a/docs/utilities.md b/docs/utilities.md new file mode 100644 index 0000000..bae6013 --- /dev/null +++ b/docs/utilities.md @@ -0,0 +1,78 @@ +# Utilities + +Helper functions and modules for TypeBox code generation. + +## Core Utilities + +### TypeBox Conversion + +`src/utils/typebox-call.ts` - Main type conversion function: + +```typescript +export function getTypeBoxType(node: TypeNode): ts.Node { + const handlers = new TypeBoxTypeHandlers() + const handler = handlers.getHandler(node) + return handler.handle(node) +} +``` + +### Static Type Generation + +`src/utils/add-static-type-alias.ts` - Generates TypeScript type aliases: + +```typescript +// Generates: export type User = Static; +addStaticTypeAlias('User', outputFile) +``` + +### Generic Type Processing + +`src/utils/generic-type-utils.ts` - Shared generic utilities: + +- `createGenericArrowFunction` - Creates arrow functions for generic types +- `addGenericTypeAlias` - Generates static type aliases for generics + +### Key Extraction + +`src/utils/key-extraction-utils.ts` - Extracts keys from union/literal types: + +```typescript +// For Pick +extractKeysFromUnionType(keysType) // Returns ['id', 'name'] +``` + +### Node Type Checking + +`src/utils/node-type-utils.ts` - Type checking utilities: + +```typescript +NodeTypeUtils.isTypeReference(node, 'Partial') // Check if node is Partial +NodeTypeUtils.isReadonlyArrayType(node) // Check if readonly T[] +``` + +### Template Literal Processing + +`src/utils/template-literal-type-processor.ts` - Processes template literal types: + +```typescript +// Converts `user-${string}` to Type.TemplateLiteral([...]) +``` + +## Code Generation Helpers + +### TypeBox Imports + +Creates appropriate imports based on generic type usage: + +```typescript +// Basic: import { Type, Static } from '@sinclair/typebox'; +// With generics: import { Type, Static, TSchema } from '@sinclair/typebox'; +``` + +### Variable Statements + +Creates export variable declarations: + +```typescript +// export const User = Type.Object({...}); +```