# 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