CodeAtlas

Understand your codebase. Delete with confidence.

CodeAtlas is a Python static analysis tool that maps your code's real dependencies, finds dead code, and shows you exactly what breaks if you delete something.

---

Features

• Dead Code Detection — Finds truly unused, test-only, and uncovered code
• Impact Analysis — Shows what breaks if you delete any function or module
• Dependency Graph — Interactive D3.js visualization of your codebase
• Runtime Tracing — Captures dynamic calls (getattr, decorators) that static analysis misses
• Framework Support — Understands Django URLs, Flask blueprints, FastAPI routes
• Zero Config — Works out of the box, configurable via pyproject.toml

---

Installation

pip install codeatlas

Or install from source:

git clone https://github.com/yourusername/codeatlas
cd codeatlas
pip install -e ".[dev]"

---

Quick Start

# Initialize config in your project
codeatlas init .

# Analyze your codebase
codeatlas analyze .

# See what breaks if you delete a function
codeatlas impact . "src/billing.py::calculate_tax"

# Trace a test run for dynamic accuracy
codeatlas trace . pytest tests/

# Launch interactive web UI
codeatlas serve . --with-trace

---

Commands

Command	Description
codeatlas init <path>	Create .codeatlas.toml config
codeatlas analyze <path>	Build and display codebase analysis
codeatlas impact <path> <target>	Show deletion impact of a node
codeatlas trace <path> <command>	Run command with runtime tracing
codeatlas trace-summary <path>	Show trace database stats
codeatlas serve <path>	Launch interactive web UI

---

Node Naming

Targets use path::object syntax:

codeatlas impact . "utils.py::helper"          # function
codeatlas impact . "models.py::User"           # class
codeatlas impact . "app.py"                     # whole module

---

Configuration

Add to your pyproject.toml:

[tool.codeatlas]
entry_patterns = [
    "**/__main__.py",
    "**/manage.py",
    "**/cli.py",
]

test_patterns = [
    "**/test_*.py",
    "**/tests/**/*.py",
]

ignore_patterns = [
    "**/venv/**",
    "**/__pycache__/**",
    "**/migrations/**",
]

detect_django = true
detect_flask = true
detect_fastapi = true

[tool.codeatlas.trace]
sample_rate = 1.0
max_depth = 50
db = ".codeatlas/trace.db"

---

Sample Output

$ codeatlas analyze .

CodeAtlas Analysis: /home/user/myproject
Nodes: 1,247 | Edges: 3,891 | Entry points: 12 | Tests: 89

Dead Code: Truly unused: 23 | Test-only: 7 | Uncovered: 156
Truly unused
├── legacy/auth.py::old_hash
├── legacy/auth.py::deprecated_login
├── api/v1/routes.py::unused_endpoint
└── ... and 20 more

Cycles found: 3
  models.py → views.py → serializers.py → models.py
  utils.py → helpers.py → utils.py
  config.py → settings.py → config.py

Architectural bridges (high centrality):
┌─────────────────────┬────────┐
│ utils.py            │ 0.1842 │
│ api/middleware.py   │ 0.0921 │
│ models/base.py      │ 0.0673 │
└─────────────────────┴────────┘

---

Web UI

$ codeatlas serve . --with-trace

CodeAtlas Web UI
Project: /home/user/myproject
Graph: 1,247 nodes, 3,891 edges
Starting server...

CodeAtlas server running at http://localhost:8765

Opens a dark-themed interactive graph:

• Drag nodes to rearrange
• Scroll to zoom
• Click any node to see deletion impact
• Search to filter
• Show Cycles to highlight circular dependencies

---

How It Works

1. Static Analysis — Parses all .py files with ast, builds a dependency graph
2. Framework Bridges — Scans Django/Flask/FastAPI patterns for implicit dependencies
3. Runtime Tracing (optional) — sys.settrace captures dynamic calls
4. Graph Analysis — NetworkX computes reachability, cycles, centrality
5. Dead Code Classification:
   • Truly unused — unreachable from both tests and entry points
   • Test-only — only reachable from tests
   • Uncovered — reachable from production, never tested

---

Requirements

• Python 3.10+
• Dependencies: networkx, click, rich

---

License

MIT

**[Download README.md](sandbox:///mnt/agents/output/README.md)**