feat(compiler-config): Implement automatic script target detection and identifier validation (#19)

The changes in this commit introduce a new `CompilerConfig` singleton that manages the TypeScript compiler options and script target configuration for the codegen system.

The key changes are:

1. Automatic script target detection: The system now automatically determines the appropriate TypeScript script target from the `ts-morph` Project's compiler options.

2. Identifier validation: Property names in generated TypeBox objects are validated using TypeScript's built-in utilities (`ts.isIdentifierStart()` and `ts.isIdentifierPart()`). This ensures compatibility with the detected script target.

3. Configuration management: The `CompilerConfig` singleton provides a centralized way to manage the script target configuration, allowing it to be overridden per-project as needed.

4. Default behavior: When no explicit target is specified, the system falls back to `ts.ScriptTarget.Latest`, providing maximum compatibility with modern JavaScript features.

5. Integration points: The configuration system is integrated with various components of the codegen system, including the Input Handler, Code Generation, Identifier Utils, and Object Handlers.

These changes improve the overall robustness and flexibility of the codegen system, ensuring that the generated code is compatible with the target JavaScript environment.

Author: DaxServer

docs/compiler-configuration.md

@@ -0,0 +1,65 @@
+# Compiler Configuration
+
+The codegen system automatically adapts to TypeScript compiler options to ensure generated code is compatible with the target JavaScript environment.
+
+## Script Target Detection
+
+The system automatically determines the appropriate TypeScript script target using a two-tier approach:
+
+1. **Project Configuration** - Uses the target specified in the ts-morph Project's compiler options
+2. **Environment Detection** - When no explicit target is found, detects the appropriate target based on the runtime TypeScript version
+
+## Identifier Validation
+
+Property names in generated TypeBox objects are validated using TypeScript's built-in utilities:
+
+- `ts.isIdentifierStart()` - validates first character
+- `ts.isIdentifierPart()` - validates remaining characters
+
+The validation respects the detected script target to ensure compatibility:
+
+```typescript
+// With ES5 target
+interface Example {
+  validName: string // → validName: Type.String()
+  'invalid-name': number // → 'invalid-name': Type.Number()
+  '123invalid': boolean // → '123invalid': Type.Boolean()
+}
+```
+
+## Configuration Management
+
+The `CompilerConfig` singleton manages script target configuration:
+
+- **Singleton Pattern** - Ensures consistent configuration across the application
+- **Environment Detection** - Automatically detects appropriate targets from TypeScript version
+- **Project Override** - Respects explicit targets from ts-morph Project configuration
+- **Runtime Configuration** - Allows manual target specification when needed
+
+## Environment-Based Target Detection
+
+When no explicit target is specified in the project configuration, the system automatically detects an appropriate target based on the TypeScript version:
+
+- **TypeScript 5.2+** → ES2023
+- **TypeScript 5.0+** → ES2022
+- **TypeScript 4.9+** → ES2022
+- **TypeScript 4.7+** → ES2021
+- **TypeScript 4.5+** → ES2020
+- **TypeScript 4.2+** → ES2019
+- **TypeScript 4.1+** → ES2018
+- **TypeScript 4.0+** → ES2017
+- **TypeScript 3.8+** → ES2017
+- **TypeScript 3.6+** → ES2016
+- **TypeScript 3.4+** → ES2015
+- **Older versions** → ES5
+
+This ensures generated code uses language features that are supported by the available TypeScript compiler, avoiding compatibility issues.
+
+## Integration Points
+
+The configuration system integrates with:
+
+- **Input Handler** - Initializes config when creating source files
+- **Code Generation** - Uses config for output file creation
+- **Identifier Utils** - Validates property names with correct target
+- **Object Handlers** - Determines property name formatting

docs/handler-system.md

@@ -30,6 +30,14 @@ export abstract class BaseTypeHandler {
 - `ObjectTypeHandler` - { prop: T }
 - `InterfaceTypeHandler` - interface references
 
+Object property names are extracted using the TypeScript compiler API through `PropertySignature.getNameNode()`. The system handles different property name formats:
+
+- **Identifiers** (`prop`) - extracted using `nameNode.getText()` and preserved as identifiers
+- **String literals** (`'prop-name'`, `"prop name"`) - extracted using `nameNode.getLiteralValue()` and validated for identifier compatibility
+- **Numeric literals** (`123`) - extracted using `nameNode.getLiteralValue().toString()` and treated as identifiers
+
+The system uses TypeScript's built-in character validation utilities (`ts.isIdentifierStart` and `ts.isIdentifierPart`) with runtime-determined script targets to determine if property names can be safely used as unquoted identifiers in the generated code. The script target is automatically determined from the ts-morph Project's compiler options, ensuring compatibility with the target JavaScript environment while maintaining optimal output format.
+
 ### Utility Types
 
 - `PartialTypeHandler` - Partial<T>

docs/overview.md

@@ -46,5 +46,6 @@ export type User = Static<typeof User>
 - [architecture.md](./architecture.md) - System architecture
 - [parser-system.md](./parser-system.md) - TypeScript parsing
 - [handler-system.md](./handler-system.md) - Type conversion
+- [compiler-configuration.md](./compiler-configuration.md) - Compiler options and script targets
 - [dependency-management.md](./dependency-management.md) - Dependency analysis
 - [testing.md](./testing.md) - Testing

docs/utilities.md

@@ -50,6 +50,18 @@ NodeTypeUtils.isTypeReference(node, 'Partial') // Check if node is Partial<T>
 NodeTypeUtils.isReadonlyArrayType(node) // Check if readonly T[]
 ```
 
+### Identifier Validation
+
+`src/utils/identifier-utils.ts` - JavaScript identifier validation:
+
+```typescript
+isValidIdentifier('validName') // true
+isValidIdentifier('123invalid') // false
+isValidIdentifier('𝒜') // true - supports Unicode characters
+```
+
+Validates JavaScript identifiers using TypeScript's built-in utilities with full Unicode support, including characters outside the Basic Multilingual Plane.
+
 ### Template Literal Processing
 
 `src/utils/template-literal-type-processor.ts` - Processes template literal types:

src/handlers/typebox/collection/array-type-handler.ts

@@ -1,4 +1,6 @@
 import { CollectionBaseHandler } from '@daxserver/validation-schema-codegen/handlers/typebox/collection/collection-base-handler'
+import { getTypeBoxType } from '@daxserver/validation-schema-codegen/utils/typebox-call'
+import { makeTypeCall } from '@daxserver/validation-schema-codegen/utils/typebox-codegen-utils'
 import { ArrayTypeNode, Node, ts } from 'ts-morph'
 
 export class ArrayTypeHandler extends CollectionBaseHandler {
@@ -7,6 +9,8 @@ export class ArrayTypeHandler extends CollectionBaseHandler {
   }
 
   handle(node: ArrayTypeNode): ts.Expression {
-    return this.processSingleType(node.getElementTypeNode(), 'Array')
+    const typeboxType = getTypeBoxType(node.getElementTypeNode())
+
+    return makeTypeCall('Array', [typeboxType])
   }
 }

src/handlers/typebox/collection/collection-base-handler.ts

@@ -10,14 +10,4 @@ export abstract class CollectionBaseHandler extends BaseTypeHandler {
 
     return makeTypeCall(typeBoxFunction, [arrayLiteral])
   }
-
-  protected processSingleType(node: Node, typeBoxFunction: string): ts.Expression {
-    return makeTypeCall(typeBoxFunction, [getTypeBoxType(node)])
-  }
-
-  protected validateNonEmptyCollection(nodes: Node[], typeName: string): void {
-    if (nodes.length === 0) {
-      throw new Error(`${typeName} must have at least one type`)
-    }
-  }
 }

src/handlers/typebox/date-type-handler.ts

@@ -9,8 +9,7 @@ export class DateTypeHandler extends BaseTypeHandler {
     return Node.isIdentifier(typeName) && typeName.getText() === 'Date'
   }
 
-  // eslint-disable-next-line @typescript-eslint/no-unused-vars
-  handle(_node: TypeReferenceNode): ts.Expression {
+  handle(): ts.Expression {
     return makeTypeCall('Date')
   }
 }

src/handlers/typebox/indexed-access-type-handler.ts

@@ -1,7 +1,7 @@
 import { BaseTypeHandler } from '@daxserver/validation-schema-codegen/handlers/typebox/base-type-handler'
 import { getTypeBoxType } from '@daxserver/validation-schema-codegen/utils/typebox-call'
 import { makeTypeCall } from '@daxserver/validation-schema-codegen/utils/typebox-codegen-utils'
-import { IndexedAccessTypeNode, Node, ts } from 'ts-morph'
+import { IndexedAccessTypeNode, Node, ts, TypeNode } from 'ts-morph'
 
 export class IndexedAccessTypeHandler extends BaseTypeHandler {
   canHandle(node: Node): boolean {
@@ -14,8 +14,8 @@ export class IndexedAccessTypeHandler extends BaseTypeHandler {
 
     // Handle special case: typeof A[number] where A is a readonly tuple
     if (
-      objectType?.isKind(ts.SyntaxKind.TypeQuery) &&
-      indexType?.isKind(ts.SyntaxKind.NumberKeyword)
+      objectType.isKind(ts.SyntaxKind.TypeQuery) &&
+      indexType.isKind(ts.SyntaxKind.NumberKeyword)
     ) {
       return this.handleTypeofArrayAccess(objectType, node)
     }
@@ -42,31 +42,28 @@ export class IndexedAccessTypeHandler extends BaseTypeHandler {
       const typeAlias = sourceFile.getTypeAlias(typeName)
       if (typeAlias) {
         const tupleUnion = this.extractTupleUnion(typeAlias.getTypeNode())
-        if (tupleUnion) {
-          return tupleUnion
-        }
+        if (tupleUnion) return tupleUnion
       }
 
       // Then try to find a variable declaration
       const variableDeclaration = sourceFile.getVariableDeclaration(typeName)
       if (variableDeclaration) {
         const tupleUnion = this.extractTupleUnion(variableDeclaration.getTypeNode())
-        if (tupleUnion) {
-          return tupleUnion
-        }
+        if (tupleUnion) return tupleUnion
       }
     }
 
     // Fallback to default Index behavior
     const typeboxObjectType = getTypeBoxType(typeQuery)
     const typeboxIndexType = getTypeBoxType(indexedAccessType.getIndexTypeNode())
+
     return makeTypeCall('Index', [typeboxObjectType, typeboxIndexType])
   }
 
-  private extractTupleUnion(typeNode: Node | undefined): ts.Expression | null {
+  private extractTupleUnion(typeNode: TypeNode | undefined): ts.Expression | null {
     if (!typeNode) return null
 
-    let actualTupleType: Node | undefined = typeNode
+    let actualTupleType: TypeNode = typeNode
 
     // Handle readonly modifier (TypeOperator)
     if (typeNode.isKind(ts.SyntaxKind.TypeOperator)) {
@@ -75,7 +72,7 @@ export class IndexedAccessTypeHandler extends BaseTypeHandler {
     }
 
     // Check if it's a tuple type
-    if (actualTupleType?.isKind(ts.SyntaxKind.TupleType)) {
+    if (actualTupleType.isKind(ts.SyntaxKind.TupleType)) {
       const tupleType = actualTupleType.asKindOrThrow(ts.SyntaxKind.TupleType)
       const elements = tupleType.getElements()
 

src/handlers/typebox/keyof-type-handler.ts

@@ -1,21 +1,16 @@
 import { BaseTypeHandler } from '@daxserver/validation-schema-codegen/handlers/typebox/base-type-handler'
 import { makeTypeCall } from '@daxserver/validation-schema-codegen/utils/typebox-codegen-utils'
-import { Node, SyntaxKind, ts } from 'ts-morph'
+import { LiteralTypeNode, Node, SyntaxKind, ts } from 'ts-morph'
 
 export class LiteralTypeHandler extends BaseTypeHandler {
   canHandle(node: Node): boolean {
     return Node.isLiteralTypeNode(node) || Node.isTrueLiteral(node) || Node.isFalseLiteral(node)
   }
 
-  handle(node: Node): ts.Expression {
-    if (!Node.isLiteralTypeNode(node)) {
-      return makeTypeCall('Any')
-    }
-
+  handle(node: LiteralTypeNode): ts.Expression {
     const literal = node.getLiteral()
-    const literalKind = literal.getKind()
 
-    switch (literalKind) {
+    switch (literal.getKind()) {
       case SyntaxKind.StringLiteral:
         return makeTypeCall('Literal', [
           ts.factory.createStringLiteral(literal.getText().slice(1, -1)),