Metadata-Version: 2.4
Name: pycodeatlas
Version: 0.1.0
Summary: Understand your codebase. Delete with confidence.
Project-URL: Homepage, https://github.com/avkad3/codeatlas
Project-URL: Repository, https://github.com/avkad3/codeatlas
Project-URL: Issues, https://github.com/avkad3/codeatlas/issues
Author-email: Aditya Vijay Kumar <avkad3@gmail.com>
License: MIT
Keywords: code-quality,dead-code,dependency-graph,static-analysis
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Requires-Dist: click>=8.0
Requires-Dist: networkx>=3.0
Requires-Dist: rich>=13.0
Provides-Extra: dev
Requires-Dist: mypy>=1.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.0; extra == 'dev'
Requires-Dist: pytest>=7.0; extra == 'dev'
Requires-Dist: ruff>=0.1.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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

```bash
pip install codeatlas
```

Or install from source:

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

---

## Quick Start

```bash
# 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:

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

---

## Configuration

Add to your `pyproject.toml`:

```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

```bash
$ 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)**