You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
feat(dependency-traversal): Implement comprehensive type dependency traversal (#12)
This commit introduces a comprehensive type dependency traversal implementation
that combines AST traversal, dependency collection, and analysis. The key
changes are:
- Implement `DependencyTraversal` class that manages the dependency graph using
Graphology library
- Add methods to extract interface and type alias references from type
declarations
- Introduce `TypeReferenceExtractor` interface to allow customization of type
reference extraction
- Implement `ProcessingOrderResult` to analyze the optimal processing order for
interfaces and type aliases
These changes enable efficient management of type dependencies, which is
crucial for generating code that respects the correct order of type
declarations.
Copy file name to clipboardExpand all lines: ARCHITECTURE.md
+79-19Lines changed: 79 additions & 19 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -75,14 +75,17 @@ The main logic for code generation resides in the <mcfile name="ts-morph-codegen
75
75
76
76
The code generation process includes sophisticated import resolution and dependency management to handle complex type hierarchies and multi-level import chains:
77
77
78
-
#### DependencyCollector
78
+
#### DependencyTraversal
79
79
80
-
The <mcfilename="dependency-collector.ts"path="src/traverse/dependency-collector.ts"></mcfile> module implements a `DependencyCollector` class that:
80
+
The <mcfilename="dependency-traversal.ts"path="src/traverse/dependency-traversal.ts"></mcfile> module implements a unified `DependencyTraversal` class that exclusively uses Graphology for all dependency management:
81
81
82
+
-**Graphology-Only Architecture**: Uses Graphology's DirectedGraph exclusively for all dependency tracking, eliminating Map-based and other tracking mechanisms
83
+
-**Unified Data Management**: All dependency information is stored and managed through the Graphology graph structure with node attributes
84
+
-**Topological Sorting**: Employs graphology-dag for robust dependency ordering with circular dependency detection and preference-based sorting
82
85
-**Traverses Import Chains**: Recursively follows import declarations to collect all type dependencies from external files
83
-
-**Builds Dependency Graph**: Creates a comprehensive map of type dependencies, tracking which types depend on which other types
84
-
-**Topological Sorting**: Performs topological sorting to ensure types are generated in the correct dependency order
85
86
-**Handles Multi-level Imports**: Supports complex scenarios with 3+ levels of nested imports (e.g., `TypeA` imports `TypeB` which imports `TypeC`)
87
+
-**Graph-Based Caching**: Uses Graphology node attributes for caching type information and dependency relationships
88
+
-**Export-Aware Ordering**: Provides specialized ordering logic for `exportEverything=false` scenarios to ensure proper dependency resolution
86
89
87
90
#### Key Features
88
91
@@ -93,19 +96,58 @@ The <mcfile name="dependency-collector.ts" path="src/traverse/dependency-collect
93
96
94
97
#### Implementation Details
95
98
96
-
The import resolution process works in two phases:
99
+
The import resolution process works in three phases using the unified architecture:
97
100
98
101
1.**Collection Phase**:
99
-
-`DependencyCollector.collectFromImports()` traverses all import declarations
100
-
-`DependencyCollector.addLocalTypes()` adds local type aliases
101
-
- Dependencies are tracked in a `Map<string, TypeInfo>` structure
102
+
-`DependencyTraversal.collectFromImports()` traverses all import declarations using integrated AST traversal
103
+
-`DependencyTraversal.addLocalTypes()` adds local type aliases with unified type reference extraction
104
+
- Dependencies are tracked using Graphology's DirectedGraph with nodes and edges representing type relationships
102
105
103
-
2.**Generation Phase**:
104
-
-`DependencyCollector.getTopologicallySortedTypes()` returns types in dependency order
106
+
2.**Analysis Phase**:
107
+
-`DependencyTraversal.getTopologicallySortedTypesWithPreference()` performs dependency ordering with export-aware preferences
108
+
- Uses graphology-dag for circular dependency detection and topological sorting
109
+
- Handles complex dependency scenarios including imported vs. local type ordering based on `exportEverything` flag
110
+
111
+
3.**Generation Phase**:
112
+
-`DependencyTraversal.getTopologicallySortedTypes()` returns types in dependency order
105
113
-`TypeAliasParser.parseWithImportFlag()` generates code with appropriate export handling
106
114
- Types are processed sequentially in the sorted order
107
115
108
-
This approach ensures that complex import scenarios work correctly and generated code compiles without dependency errors.
116
+
This unified approach ensures robust handling of complex import scenarios, circular dependencies, and generates code that compiles without dependency errors while maintaining optimal performance through reduced module boundaries.
117
+
118
+
### Unified Dependency Management
119
+
120
+
The dependency management system is built on a unified architecture that integrates all dependency-related functionality:
121
+
122
+
#### DependencyTraversal Integration
123
+
124
+
The <mcfilename="dependency-traversal.ts"path="src/traverse/dependency-traversal.ts"></mcfile> module provides comprehensive dependency management:
125
+
126
+
-**Integrated AST Traversal**: Combines AST traversal logic with dependency collection for optimal performance
127
+
-**Direct Graphology Usage**: Uses Graphology's DirectedGraph directly for dependency tracking without abstraction layers
128
+
-**Unified Type Reference Extraction**: Consolidates type reference extraction logic within the main traversal module
129
+
-**Export-Aware Processing**: Implements specialized logic for handling `exportEverything=false` scenarios with proper dependency ordering
130
+
-**Performance Optimization**: Eliminates module boundaries and reduces function call overhead through unified architecture
131
+
132
+
#### Graph-Based Dependency Resolution
133
+
134
+
The unified module leverages Graphology's ecosystem for robust dependency management:
135
+
136
+
-**DirectedGraph**: Uses Graphology's optimized graph data structure for dependency relationships
137
+
-**Topological Sorting**: Employs `topologicalSort` from `graphology-dag` for dependency ordering with circular dependency detection
138
+
-**Preference-Based Ordering**: Implements `getTopologicallySortedTypesWithPreference()` for export-aware type ordering
139
+
-**Memory Efficiency**: Direct Graphology usage provides optimal memory management for large dependency graphs
140
+
-**Type Safety**: Full TypeScript support through graphology-types package
141
+
142
+
#### Simplified Architecture Benefits
143
+
144
+
The Graphology-only approach provides several advantages:
145
+
146
+
-**Simplified Architecture**: Eliminates multiple tracking mechanisms (Map-based dependencies, visitedFiles, various caches) in favor of a single graph-based solution
147
+
-**Enhanced Performance**: Direct Graphology operations provide optimized graph algorithms and data structures
148
+
-**Improved Maintainability**: Single dependency tracking mechanism reduces complexity and potential inconsistencies
149
+
-**Better Memory Management**: Graphology's optimized memory handling for large dependency graphs
150
+
-**Unified Data Model**: All dependency information stored consistently in graph nodes and edges
109
151
110
152
## Interface Inheritance Support
111
153
@@ -115,13 +157,13 @@ The codebase provides comprehensive support for TypeScript interface inheritance
115
157
116
158
The main codegen logic in <mcfilename="ts-morph-codegen.ts"path="src/ts-morph-codegen.ts"></mcfile> implements sophisticated processing order management:
117
159
118
-
1.**Dependency Analysis**: Uses `InterfaceTypeDependencyAnalyzer` to analyze complex relationships between interfaces and type aliases
119
-
2.**Conditional Processing**: Handles three scenarios:
3.**Topological Sorting**: Ensures types are processed in correct dependency order to prevent "type not found" errors
124
-
4.**Circular Dependency Detection**: The algorithm detects and handles circular inheritance scenarios gracefully
160
+
1.**Unified Dependency Analysis**: Uses <mcfilename="dependency-traversal.ts"path="src/traverse/dependency-traversal.ts"></mcfile> with integrated graph-based architecture to analyze complex relationships between interfaces and type aliases
161
+
2.**Direct Graph Processing**: Leverages Graphology's DirectedGraph and topological sorting for robust dependency ordering without abstraction layers
162
+
3.**Export-Aware Processing**: Handles dependency ordering based on `exportEverything` flag:
163
+
-`exportEverything=true`: Prioritizes imported types for consistent ordering
164
+
-`exportEverything=false`: Ensures dependency-aware ordering while respecting local type preferences
165
+
4.**Topological Sorting**: Uses `getTopologicallySortedTypesWithPreference()` to ensure types are processed in correct dependency order to prevent "type not found" errors
166
+
5.**Circular Dependency Detection**: The graph-based algorithm detects and handles circular inheritance scenarios gracefully with detailed error reporting
125
167
126
168
### TypeBox Composite Generation
127
169
@@ -277,7 +319,25 @@ When implementing new type handlers or modifying existing ones, it is crucial to
277
319
278
320
## Performance Optimizations
279
321
280
-
Several optimizations have been implemented to improve the performance of the code generation process, particularly for import resolution:
322
+
Several optimizations have been implemented to improve the performance of the code generation process, particularly for import resolution and dependency management:
323
+
324
+
### Unified Dependency Management with Graphology
325
+
326
+
The project uses **Graphology** through a unified architecture for all dependency graph operations, providing:
327
+
328
+
-**Production-Ready Graph Library**: Leverages Graphology's battle-tested graph data structures and algorithms
329
+
-**Optimized Performance**: Benefits from Graphology's highly optimized internal implementations for graph operations
330
+
-**Advanced Graph Algorithms**: Direct access to specialized algorithms through Graphology ecosystem (graphology-dag, graphology-traversal)
331
+
-**Type Safety**: Full TypeScript support through graphology-types package
332
+
-**Memory Efficiency**: Graphology's optimized memory management for large graphs
333
+
-**Unified Architecture**: Single module eliminates abstraction layers and reduces complexity
334
+
335
+
#### Core Architecture
336
+
337
+
-**DependencyTraversal**: Uses Graphology's `DirectedGraph` exclusively for all dependency tracking, with no fallback to Map-based structures
338
+
-**Integrated Topological Sorting**: Leverages `topologicalSort` from `graphology-dag` for ordering dependencies with export-aware preferences
339
+
-**Graph-Based Data Storage**: All dependency information, visited files, and type metadata stored as Graphology node attributes
340
+
-**Export-Aware Processing**: Implements specialized ordering logic for different export scenarios using graph-based algorithms
0 commit comments