codaviz 0.5.0

Analyze and visualize complexity hotspots in Python codebases.

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.

Quick start

codaviz is a uv project. From a checkout:

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:

uv run codaviz . && open report.html

To install it as a standalone command:

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:

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 (so the numbers match Ruff), cognitive from cognitive_complexity, MI + SLOC from radon, 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:

[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

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/ for the vision, spec, and implementation plan, and 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.