Metadata-Version: 2.4
Name: codaviz
Version: 0.5.0
Summary: Analyze and visualize complexity hotspots in Python codebases.
Author: Stefane Fermigier
Author-email: Stefane Fermigier <sf@abilian.com>
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Dist: cognitive-complexity>=1.3
Requires-Dist: cyclopts>=3.0
Requires-Dist: jinja2>=3.1
Requires-Dist: mccabe>=0.7
Requires-Dist: radon>=6.0
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# codaviz

A lightweight CLI that analyzes complexity in Python codebases and emits a single, self-contained, interactive HTML report — a simpler, local alternative to SonarQube for spotting where to refactor.

Point it at a repo and it ranks **complexity hotspots**, draws a **treemap** (sized by lines of code, colored by a metric you pick), lets you **drill into any module** to read its functions and source, and flags **circular imports** and **over-threshold functions**. No server, no database, no network — the report is one HTML file you can open offline or email to a teammate.

![codaviz interactive report — treemap, top-modules chart, and per-function drill-down with cyclomatic + cognitive complexity](docs/images/screenshot.png)

## Quick start

codaviz is a [uv](https://docs.astral.sh/uv/) project. From a checkout:

```bash
uv sync                          # install
uv run codaviz /path/to/project  # writes ./report.html
open report.html                 # (macOS; use xdg-open on Linux)
```

Try it on codaviz itself:

```bash
uv run codaviz . && open report.html
```

To install it as a standalone command:

```bash
uv tool install .        # then, anywhere: codaviz /path/to/project
```

## Usage

```
codaviz [OPTIONS] [PATH]

  PATH                 Project directory to analyze (default: current dir)

  -f, --format         html | json | csv          (default: html)
  -o, --output FILE    Output file
                       (html → report.html; json/csv → stdout unless set)
      --no-source      Omit embedded source snippets (smaller, shareable report)
      --version        Show version and exit
  -h, --help           Show help and exit
```

Examples:

```bash
codaviz ~/src/myapp                     # interactive report.html
codaviz ~/src/myapp -o myapp.html       # custom output path
codaviz ~/src/myapp --no-source -o share.html   # no source embedded
codaviz ~/src/myapp -f json > data.json # raw entity data
codaviz ~/src/myapp -f csv  > data.csv  # one row per package/module/function
```

## The report

- **Treemap** — every module is a tile sized by lines of code and colored by the selected metric (greener = better, redder = worse). Click a package to zoom in.
- **Metric selector** — switch between **Maintainability index** (default), **max/total cyclomatic**, **max/total cognitive**, and **lines of code**; the treemap, bar chart, and table all re-rank instantly.
- **Hotspots table** — every module sorted by the selected metric, with LOC / MI / max & total cyclomatic / max & total cognitive / function count.
- **Function detail** — click a tile, bar, or row to see that module's functions, each with a **CC** (cyclomatic) and **Cog** (cognitive) badge, line number, and source snippet. Functions over either threshold get a "consider extracting" / "hard to follow" hint.
- **Circular imports** — modules that import each other (statically detected) are listed as cycles.

## What gets analyzed

Inside a git repo, codaviz analyzes the Python files git knows about — tracked **and** uncommitted — while honoring `.gitignore` (so `.venv`, build output, and ignored trees are skipped). Outside a repo, it walks the directory. On top of that it always skips common noise: virtualenvs, caches, `build/`, `dist/`, `node_modules/`, `site-packages/`, `migrations/`, and test files (`tests/`, `test_*.py`, `*_test.py`, `conftest.py`) unless you opt in.

## Metrics

| Metric | Meaning | Direction |
|---|---|---|
| **Cyclomatic (CC)** | McCabe complexity — branch/loop count + 1. Per function. Matches Ruff's C901 / `python -m mccabe`. | higher = worse |
| **Cognitive (Cog)** | SonarSource cognitive complexity — penalises *nesting*, ignores shorthand humans read easily. The better "how hard to understand" signal. Per function. | higher = worse |
| **Maintainability index (MI)** | radon's 0–100 composite (≥20 = A/good, 10–19 = B, <10 = C). Per module. Kept as the familiar number. | lower = worse |
| **SLOC** | Source lines of code (excludes blanks/comments). | — (used for tile size) |

Cyclomatic complexity comes from [`mccabe`](https://github.com/PyCQA/mccabe) (so the numbers match Ruff), cognitive from [`cognitive_complexity`](https://github.com/Melevir/cognitive_complexity), MI + SLOC from [`radon`](https://radon.readthedocs.io/), and circular imports from a static `ast` import graph (no code is executed).

## Configuration

Optional `[tool.codaviz]` table in the analyzed project's `pyproject.toml`:

```toml
[tool.codaviz]
exclude = ["generated/*.py", "vendor/**"]  # extra glob patterns to skip
max-complexity = 15                         # cyclomatic threshold for hints
max-cognitive = 15                          # cognitive threshold for hints
include-tests = false                       # set true to analyze test files too
```

## Known limitations

- **Nested defs**: closures and methods of function-local classes are folded into their enclosing function's score rather than listed separately — matching how Ruff/mccabe report the outer function.
- **Circular imports**: resolution favors false negatives over false positives — unusual layouts (some `src/` setups, namespace packages) may under-report. Relative imports always resolve correctly.
- **Color scale**: the badness ramp is green→amber→red with a "better → worse" legend and a numeric table as non-color channels; a fully colorblind-safe palette is a planned option.

## Development

```bash
make test     # uv run pytest
make lint     # ruff check + format check + type checks
make format   # ruff format + autofix
```

The test suite spans unit / integration / end-to-end tiers, including in-browser execution of the report's JavaScript via Node.

## Status

**0.5.0 — first public release.** Stable and usable: hotspots, treemap, drill-down, cyclomatic + cognitive complexity, maintainability index, circular imports, threshold hints, and HTML/JSON/CSV output. Planned next (in rough order): **churn-weighted hotspots** (complexity × git change-frequency), **coupling metrics** (afferent/efferent, instability), and **trends over time**. See [`notes/`](notes/) for the vision, spec, and implementation plan, and [`CHANGES.md`](CHANGES.md) for the changelog.

## Non-goals

Security scanning (use Bandit), runtime profiling (use `cProfile`/`scalene`), and test coverage (use `pytest-cov`) are out of scope — codaviz focuses on structural complexity.

## License

Apache License 2.0 — see [`LICENSE`](LICENSE).
