depgraph

A lightweight CLI tool to analyze and visualize dependency graphs in your codebase. Detect circular dependencies, unused imports, and generate visual dependency maps.

Features

• 🔍 Detect circular dependencies in JavaScript/TypeScript and Python projects
• 📊 Generate ASCII dependency trees
• 🎯 Find unused imports
• 🚀 Fast and zero-config
• 🌳 Show dependency depth and complexity metrics

Installation

npm install -g depgraph
# or
pip install depgraph

Usage

Analyze a directory

depgraph analyze ./src

Check for circular dependencies

depgraph circular ./src

Generate visual dependency tree

depgraph tree ./src/index.js

Find unused imports

depgraph unused ./src

Example Output

Analyzing dependency graph...

📦 ./src/index.js
  ├─ ./utils/logger.js
  │  └─ ./config/settings.js
  ├─ ./api/routes.js
  │  ├─ ./middleware/auth.js
  │  └─ ./controllers/user.js
  └─ ./database/connect.js

⚠️  Circular dependency detected:
  ./api/routes.js → ./middleware/auth.js → ./api/routes.js

📊 Metrics:
  Total modules: 24
  Max depth: 4
  Circular dependencies: 1
  Unused imports: 3

Configuration

Create a .depgraphrc.json in your project root:

{
  "ignore": ["node_modules", "dist", "build"],
  "extensions": [".js", ".ts", ".jsx", ".tsx", ".py"],
  "maxDepth": 10
}

API

const { analyzeDependencies, findCircular } = require('depgraph');

const graph = analyzeDependencies('./src');
const circles = findCircular(graph);

console.log(circles);

How It Works

1. Parses import/require statements using AST analysis
2. Builds a directed graph of module dependencies
3. Uses depth-first search to detect cycles
4. Tracks import usage across the codebase

Supported Languages

• JavaScript (ES6 imports, CommonJS require)
• TypeScript
• Python (import statements)

License

MIT

Contributing

Pull requests welcome! Please read CONTRIBUTING.md first.

Roadmap

• Support for more languages (Go, Rust, Java)
• Interactive web UI visualization
• GitHub Action for CI/CD integration
• Export to JSON/GraphML/DOT formats
• Identify potential code splitting opportunities