feat(traverse): improve type dependency analysis

ARCHITECTURE.md

@@ -33,7 +33,7 @@
     - [TypeBoxTypeHandlers Optimizations](#typeboxtypehandlers-optimizations)
   - [Performance Testing](#performance-testing)
 - [Process Overview](#process-overview)
-- [Test-Driven Development (TDD) Approach](#test-driven-development-tdd-approach)
+- [Test-Driven Development](#test-driven-development)
   - [TDD Cycle](#tdd-cycle)
   - [Running Tests](#running-tests)
   - [TDD Workflow for New Features](#tdd-workflow-for-new-features)
@@ -77,7 +77,7 @@ The code generation process includes sophisticated import resolution and depende
 
 #### DependencyCollector
 
-The <mcfile name="dependency-collector.ts" path="src/utils/dependency-collector.ts"></mcfile> module implements a `DependencyCollector` class that:
+The <mcfile name="dependency-collector.ts" path="src/traverse/dependency-collector.ts"></mcfile> module implements a `DependencyCollector` class that:
 
 - **Traverses Import Chains**: Recursively follows import declarations to collect all type dependencies from external files
 - **Builds Dependency Graph**: Creates a comprehensive map of type dependencies, tracking which types depend on which other types
@@ -113,11 +113,15 @@ The codebase provides comprehensive support for TypeScript interface inheritance
 
 ### Dependency-Ordered Processing
 
-Interfaces are processed in dependency order using a topological sort algorithm implemented in <mcfile name="ts-morph-codegen.ts" path="src/ts-morph-codegen.ts"></mcfile>:
+The main codegen logic in <mcfile name="ts-morph-codegen.ts" path="src/ts-morph-codegen.ts"></mcfile> implements sophisticated processing order management:
 
-1. **Dependency Analysis**: The `getInterfaceProcessingOrder` function analyzes all interfaces to identify inheritance relationships
-2. **Topological Sorting**: Interfaces are sorted to ensure base interfaces are processed before extended interfaces
-3. **Circular Dependency Detection**: The algorithm detects and handles circular inheritance scenarios gracefully
+1. **Dependency Analysis**: Uses `InterfaceTypeDependencyAnalyzer` to analyze complex relationships between interfaces and type aliases
+2. **Conditional Processing**: Handles three scenarios:
+   - Interfaces depending on type aliases only
+   - Type aliases depending on interfaces only
+   - Both dependencies present (three-phase processing)
+3. **Topological Sorting**: Ensures types are processed in correct dependency order to prevent "type not found" errors
+4. **Circular Dependency Detection**: The algorithm detects and handles circular inheritance scenarios gracefully
 
 ### TypeBox Composite Generation
 
@@ -126,11 +130,13 @@ Interface inheritance is implemented using TypeBox's `Type.Composite` functional
 - **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 <mcfile name="interface-type-handler.ts" path="src/handlers/typebox/object/interface-type-handler.ts"></mcfile> 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
 
 ## Input Handling System
@@ -341,9 +347,9 @@ To ensure the dependency collection system performs efficiently under various sc
 5.  **Static Type Generation**: Alongside each TypeBox schema, a TypeScript `type` alias is generated using `Static<typeof ...>` to provide compile-time type safety and seamless integration with existing TypeScript code.
 6.  **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.
 
-## Test-Driven Development (TDD) Approach
+## Test-Driven Development
 
-This project follows a Test-Driven Development methodology to ensure code quality, maintainability, and reliability. The TDD workflow consists of three main phases:
+This project follows a Test-Driven Development (TDD) methodology to ensure code quality, maintainability, and reliability. The TDD workflow consists of three main phases:
 
 ### TDD Cycle
 

src/handlers/typebox/object/interface-type-handler.ts

@@ -69,10 +69,13 @@ export class InterfaceTypeHandler extends ObjectLikeBaseHandler {
     const functionTypeParams = typeParameters.map((typeParam) => {
       const paramName = typeParam.getName()
 
+      // Use TSchema as the constraint for TypeBox compatibility
+      const constraintNode = ts.factory.createTypeReferenceNode('TSchema', undefined)
+
       return ts.factory.createTypeParameterDeclaration(
         undefined,
         ts.factory.createIdentifier(paramName),
-        ts.factory.createTypeReferenceNode('TSchema', undefined),
+        constraintNode,
         undefined,
       )
     })

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

@@ -1,4 +1,5 @@
 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 { Node, ts, TypeReferenceNode } from 'ts-morph'
 
@@ -9,9 +10,23 @@ export class TypeReferenceHandler extends BaseTypeHandler {
 
   handle(node: TypeReferenceNode): ts.Expression {
     const referencedType = node.getTypeName()
+    const typeArguments = node.getTypeArguments()
 
     if (Node.isIdentifier(referencedType)) {
       const typeName = referencedType.getText()
+
+      // If there are type arguments, create a function call
+      if (typeArguments.length > 0) {
+        const typeBoxArgs = typeArguments.map((arg) => getTypeBoxType(arg))
+
+        return ts.factory.createCallExpression(
+          ts.factory.createIdentifier(typeName),
+          undefined,
+          typeBoxArgs,
+        )
+      }
+
+      // No type arguments, just return the identifier
       return ts.factory.createIdentifier(typeName)
     }
 

src/parsers/parse-interfaces.ts

@@ -107,10 +107,13 @@ export class InterfaceParser extends BaseParser {
     // Create type parameters for the type alias
     const typeParamDeclarations = typeParameters.map((typeParam) => {
       const paramName = typeParam.getName()
+      // Use TSchema as the constraint for TypeBox compatibility
+      const constraintNode = ts.factory.createTypeReferenceNode('TSchema', undefined)
+
       return ts.factory.createTypeParameterDeclaration(
         undefined,
         ts.factory.createIdentifier(paramName),
-        ts.factory.createTypeReferenceNode('TSchema', undefined),
+        constraintNode,
         undefined,
       )
     })

src/traverse/ast-traversal.ts

@@ -0,0 +1,111 @@
+import { InterfaceDeclaration, Node, TypeAliasDeclaration, TypeReferenceNode } from 'ts-morph'
+
+/**
+ * AST traversal patterns used in dependency analysis
+ */
+export class ASTTraversal {
+  private static cache = new Map<string, string[]>()
+
+  /**
+   * Extract interface names referenced by a type alias
+   */
+  static extractInterfaceReferences(
+    typeAlias: TypeAliasDeclaration,
+    interfaces: Map<string, InterfaceDeclaration>,
+  ): string[] {
+    const typeNode = typeAlias.getTypeNode()
+    if (!typeNode) return []
+
+    const cacheKey = `interface_refs_${typeNode.getText()}`
+    const cached = ASTTraversal.cache.get(cacheKey)
+    if (cached) return cached
+
+    const references: string[] = []
+    const visited = new Set<Node>()
+
+    const traverse = (node: Node): void => {
+      if (visited.has(node)) return
+      visited.add(node)
+
+      // Handle type references
+      if (Node.isTypeReference(node)) {
+        const typeRefNode = node as TypeReferenceNode
+        const typeName = typeRefNode.getTypeName().getText()
+
+        if (interfaces.has(typeName)) {
+          references.push(typeName)
+        }
+        // Continue traversing to handle type arguments in generic instantiations
+      }
+
+      // Use forEachChild for better performance
+      node.forEachChild(traverse)
+    }
+
+    traverse(typeNode)
+
+    // Cache the result
+    ASTTraversal.cache.set(cacheKey, references)
+    return references
+  }
+
+  /**
+   * Extract type alias names referenced by an interface (e.g., in type parameter constraints)
+   */
+  static extractTypeAliasReferences(
+    interfaceDecl: InterfaceDeclaration,
+    typeAliases: Map<string, TypeAliasDeclaration>,
+  ): string[] {
+    const cacheKey = `type_alias_refs_${interfaceDecl.getName()}_${interfaceDecl.getText()}`
+    const cached = ASTTraversal.cache.get(cacheKey)
+    if (cached) return cached
+
+    const references: string[] = []
+    const visited = new Set<Node>()
+
+    const traverse = (node: Node): void => {
+      if (visited.has(node)) return
+      visited.add(node)
+
+      // Handle type references
+      if (Node.isTypeReference(node)) {
+        const typeRefNode = node as TypeReferenceNode
+        const typeName = typeRefNode.getTypeName().getText()
+
+        if (typeAliases.has(typeName)) {
+          references.push(typeName)
+        }
+        return // No need to traverse children of type references
+      }
+
+      // Use forEachChild for better performance
+      node.forEachChild(traverse)
+    }
+
+    // Check type parameters for constraints
+    for (const typeParam of interfaceDecl.getTypeParameters()) {
+      const constraint = typeParam.getConstraint()
+      if (constraint) {
+        traverse(constraint)
+      }
+    }
+
+    // Check heritage clauses
+    for (const heritageClause of interfaceDecl.getHeritageClauses()) {
+      for (const typeNode of heritageClause.getTypeNodes()) {
+        traverse(typeNode)
+      }
+    }
+
+    // Cache the result
+    ASTTraversal.cache.set(cacheKey, references)
+    return references
+  }
+
+  /**
+   * Clear the internal cache
+   */
+  static clearCache(): void {
+    ASTTraversal.cache.clear()
+  }
+}

src/traverse/dependency-analyzer.ts

@@ -0,0 +1,140 @@
+import { ASTTraversal } from '@daxserver/validation-schema-codegen/traverse/ast-traversal'
+import { InterfaceDeclaration, TypeAliasDeclaration } from 'ts-morph'
+
+/**
+ * Dependency analyzer for determining processing order
+ */
+export class DependencyAnalyzer {
+  /**
+   * Extract interface names referenced by a type alias
+   */
+  extractInterfaceReferences(
+    typeAlias: TypeAliasDeclaration,
+    interfaces: Map<string, InterfaceDeclaration>,
+  ): string[] {
+    return ASTTraversal.extractInterfaceReferences(typeAlias, interfaces)
+  }
+
+  /**
+   * Extract type alias names referenced by an interface
+   */
+  extractTypeAliasReferences(
+    interfaceDecl: InterfaceDeclaration,
+    typeAliases: Map<string, TypeAliasDeclaration>,
+  ): string[] {
+    return ASTTraversal.extractTypeAliasReferences(interfaceDecl, typeAliases)
+  }
+
+  /**
+   * Check if any type aliases reference interfaces
+   */
+  hasInterfaceReferences(
+    typeAliases: TypeAliasDeclaration[],
+    interfaces: InterfaceDeclaration[],
+  ): boolean {
+    const interfaceMap = new Map<string, InterfaceDeclaration>()
+    for (const iface of interfaces) {
+      interfaceMap.set(iface.getName(), iface)
+    }
+
+    for (const typeAlias of typeAliases) {
+      const references = this.extractInterfaceReferences(typeAlias, interfaceMap)
+      if (references.length > 0) {
+        return true
+      }
+    }
+
+    return false
+  }
+
+  /**
+   * Get type aliases that reference interfaces, ordered by their dependencies
+   */
+  getTypeAliasesReferencingInterfaces(
+    typeAliases: TypeAliasDeclaration[],
+    interfaces: InterfaceDeclaration[],
+  ): { typeAlias: TypeAliasDeclaration; referencedInterfaces: string[] }[] {
+    const interfaceMap = new Map<string, InterfaceDeclaration>()
+    for (const iface of interfaces) {
+      interfaceMap.set(iface.getName(), iface)
+    }
+
+    const result: { typeAlias: TypeAliasDeclaration; referencedInterfaces: string[] }[] = []
+
+    for (const typeAlias of typeAliases) {
+      const references = this.extractInterfaceReferences(typeAlias, interfaceMap)
+      if (references.length > 0) {
+        result.push({
+          typeAlias,
+          referencedInterfaces: references,
+        })
+      }
+    }
+
+    return result
+  }
+
+  /**
+   * Determine the correct processing order for interfaces and type aliases
+   * Returns an object indicating which should be processed first
+   */
+  analyzeProcessingOrder(
+    typeAliases: TypeAliasDeclaration[],
+    interfaces: InterfaceDeclaration[],
+  ): {
+    processInterfacesFirst: boolean
+    typeAliasesDependingOnInterfaces: string[]
+    interfacesDependingOnTypeAliases: string[]
+  } {
+    const typeAliasMap = new Map<string, TypeAliasDeclaration>()
+    const interfaceMap = new Map<string, InterfaceDeclaration>()
+
+    for (const typeAlias of typeAliases) {
+      typeAliasMap.set(typeAlias.getName(), typeAlias)
+    }
+
+    for (const interfaceDecl of interfaces) {
+      interfaceMap.set(interfaceDecl.getName(), interfaceDecl)
+    }
+
+    const typeAliasesDependingOnInterfaces: string[] = []
+    const interfacesDependingOnTypeAliases: string[] = []
+
+    // Check type aliases that depend on interfaces
+    for (const typeAlias of typeAliases) {
+      const interfaceRefs = this.extractInterfaceReferences(typeAlias, interfaceMap)
+      if (interfaceRefs.length > 0) {
+        typeAliasesDependingOnInterfaces.push(typeAlias.getName())
+      }
+    }
+
+    // Check interfaces that depend on type aliases
+    for (const interfaceDecl of interfaces) {
+      const typeAliasRefs = this.extractTypeAliasReferences(interfaceDecl, typeAliasMap)
+      if (typeAliasRefs.length > 0) {
+        interfacesDependingOnTypeAliases.push(interfaceDecl.getName())
+      }
+    }
+
+    // Determine processing order:
+    // If interfaces depend on type aliases, process type aliases first
+    // If only type aliases depend on interfaces, process interfaces first
+    // If both have dependencies, process type aliases that interfaces depend on first,
+    // then interfaces, then type aliases that depend on interfaces
+    const processInterfacesFirst =
+      interfacesDependingOnTypeAliases.length === 0 && typeAliasesDependingOnInterfaces.length > 0
+
+    return {
+      processInterfacesFirst,
+      typeAliasesDependingOnInterfaces,
+      interfacesDependingOnTypeAliases,
+    }
+  }
+
+  /**
+   * Clear internal caches
+   */
+  clearCache(): void {
+    ASTTraversal.clearCache()
+  }
+}

src/utils/dependency-collector.ts → src/traverse/dependency-collector.ts

@@ -1,11 +1,11 @@
 import {
   DefaultFileResolver,
   type FileResolver,
-} from '@daxserver/validation-schema-codegen/utils/dependency-file-resolver'
+} from '@daxserver/validation-schema-codegen/traverse/dependency-file-resolver'
 import {
   DefaultTypeReferenceExtractor,
   type TypeReferenceExtractor,
-} from '@daxserver/validation-schema-codegen/utils/dependency-type'
+} from '@daxserver/validation-schema-codegen/traverse/dependency-type'
 import { ImportDeclaration, SourceFile, TypeAliasDeclaration } from 'ts-morph'
 
 export interface TypeDependency {

src/utils/dependency-type.ts → src/traverse/dependency-type.ts

@@ -1,4 +1,4 @@
-import type { TypeDependency } from '@daxserver/validation-schema-codegen/utils/dependency-collector'
+import type { TypeDependency } from '@daxserver/validation-schema-codegen/traverse/dependency-collector'
 import { Node, TypeReferenceNode } from 'ts-morph'
 
 export interface TypeReferenceExtractor {