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

npm install
npm run build

Usage

Analyze a directory

typeflow analyze ./src

Analyze and export to DOT

typeflow analyze ./src -o output.dot -f dot

Analyze and export to GraphML

typeflow analyze ./src -o output.graphml -f graphml

Watch for changes

typeflow watch ./src

Check for issues only

typeflow check ./src

Initialize a config file

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:

{
  "includePatterns": ["**/*.ts", "**/*.tsx"],
  "excludePatterns": ["node_modules", "dist", "*.d.ts"],
  "maxDepth": 10,
  "exportFormats": ["dot", "graphml", "json"],
  "analysis": {
    "circularDependencies": true,
    "typeWidening": true,
    "typeNarrowing": true
  }
}

Development

# 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