feat(traverse): improve type dependency analysis (#11)

Improve the type dependency analysis by:

- Using a dedicated `DependencyAnalyzer` class to handle the analysis
- Extracting interface references from type aliases and type alias references from interfaces
- Determining the correct processing order for interfaces and type aliases

This ensures that the code generation process can handle complex type dependencies
correctly, allowing for more robust and reliable schema generation.

Author: DaxServer

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 renamed to 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-file-resolver.ts renamed to src/traverse/dependency-file-resolver.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 {