165 lines
3.9 KiB
Markdown
165 lines
3.9 KiB
Markdown
# TypeFlow - CLI Type Dependency Tracer
|
|
|
|
A CLI tool that traces TypeScript/JavaScript type dependencies through a codebase, visualizing type propagation, detecting type widening/narrowing issues, and identifying circular type dependencies.
|
|
|
|
## Features
|
|
|
|
- **Type Dependency Graph Visualization**: Generate visual dependency graphs showing how types relate to each other
|
|
- **Circular Dependency Detection**: Detect circular type dependencies that could cause issues
|
|
- **Type Widening Analysis**: Identify type widening issues like large unions, intersections, and use of `any`
|
|
- **Type Narrowing Analysis**: Detect excessive type narrowing and complex conditional types
|
|
- **Multiple Export Formats**: Export graphs to DOT, GraphML, or JSON formats
|
|
- **Watch Mode**: Monitor files for changes and incrementally analyze
|
|
- **CLI Interface**: Easy-to-use command-line interface with Commander.js
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
## Usage
|
|
|
|
### Analyze a directory
|
|
|
|
```bash
|
|
typeflow analyze ./src
|
|
```
|
|
|
|
### Analyze and export to DOT
|
|
|
|
```bash
|
|
typeflow analyze ./src -o output.dot -f dot
|
|
```
|
|
|
|
### Analyze and export to GraphML
|
|
|
|
```bash
|
|
typeflow analyze ./src -o output.graphml -f graphml
|
|
```
|
|
|
|
### Watch for changes
|
|
|
|
```bash
|
|
typeflow watch ./src
|
|
```
|
|
|
|
### Check for issues only
|
|
|
|
```bash
|
|
typeflow check ./src
|
|
```
|
|
|
|
### Initialize a config file
|
|
|
|
```bash
|
|
typeflow init
|
|
```
|
|
|
|
## Commands
|
|
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `analyze [path]` | Analyze type dependencies |
|
|
| `watch [path]` | Watch files and incrementally analyze |
|
|
| `export <input> <output>` | Export an existing analysis |
|
|
| `check [path]` | Check for issues without generating a graph |
|
|
| `init` | Initialize a typeflow config file |
|
|
|
|
## Options
|
|
|
|
### Analyze Command
|
|
|
|
| Option | Description |
|
|
|--------|-------------|
|
|
| `-o, --output <file>` | Output file for the graph |
|
|
| `-f, --format <format>` | Output format (dot, graphml, json) |
|
|
| `--no-circular` | Skip circular dependency detection |
|
|
| `--no-widening` | Skip type widening analysis |
|
|
| `--no-narrowing` | Skip type narrowing analysis |
|
|
| `--cluster-by <type>` | Cluster nodes by (file, kind) |
|
|
| `-d, --max-depth <number>` | Maximum dependency depth |
|
|
|
|
## Configuration
|
|
|
|
Create a `typeflow.config.json` file to customize behavior:
|
|
|
|
```json
|
|
{
|
|
"includePatterns": ["**/*.ts", "**/*.tsx"],
|
|
"excludePatterns": ["node_modules", "dist", "*.d.ts"],
|
|
"maxDepth": 10,
|
|
"exportFormats": ["dot", "graphml", "json"],
|
|
"analysis": {
|
|
"circularDependencies": true,
|
|
"typeWidening": true,
|
|
"typeNarrowing": true
|
|
}
|
|
}
|
|
```
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Build the project
|
|
npm run build
|
|
|
|
# Run tests
|
|
npm test
|
|
|
|
# Run linter
|
|
npm run lint
|
|
|
|
# Format code
|
|
npm run format
|
|
|
|
# Watch mode
|
|
npm run watch
|
|
|
|
# Run CLI directly
|
|
npm run dev -- analyze ./src
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
typeflow/
|
|
├── src/
|
|
│ ├── cli.ts # CLI entry point
|
|
│ ├── index.ts # Main exports
|
|
│ ├── parsers/ # AST parsing
|
|
│ │ ├── typeParser.ts
|
|
│ │ ├── importParser.ts
|
|
│ │ ├── interfaceParser.ts
|
|
│ │ └── typeAliasParser.ts
|
|
│ ├── analyzers/ # Analysis modules
|
|
│ │ ├── dependencyGraph.ts
|
|
│ │ ├── circularDetector.ts
|
|
│ │ ├── typeWidening.ts
|
|
│ │ └── typeNarrowing.ts
|
|
│ ├── exporters/ # Export formats
|
|
│ │ ├── dotExporter.ts
|
|
│ │ ├── graphmlExporter.ts
|
|
│ │ └── jsonExporter.ts
|
|
│ ├── utils/ # Utilities
|
|
│ │ ├── fileFinder.ts
|
|
│ │ ├── typeUtils.ts
|
|
│ │ ├── astUtils.ts
|
|
│ │ └── watcher.ts
|
|
│ └── types/ # Type definitions
|
|
│ ├── index.ts
|
|
│ ├── ast.ts
|
|
│ └── graph.ts
|
|
├── test/ # Tests
|
|
├── bin/ # CLI binary
|
|
└── package.json
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|