Getting started¶

Requirements¶

Python 3.12 or newer.
Optionally git: inside a repository codaviz uses git to find source files and honour .gitignore. Outside one it falls back to a filesystem walk.

Install¶

codaviz is a uv project. From a checkout:

uv (from a checkout)As a standalone commandpip

uv sync                      # Python analysis only
uv sync --extra treesitter   # + JS/TS, Go, Ruby, Rust, Java, PHP
uv run codaviz /path/to/project

uv tool install .                 # Python only
uv tool install ".[treesitter]"   # all languages
codaviz /path/to/project

pip install codaviz               # Python only
pip install "codaviz[treesitter]" # all languages
codaviz /path/to/project

The treesitter extra pulls in tree-sitter and tree-sitter-language-pack. Without it, non-Python files are skipped silently, so a project with no Python in it gets an empty report and no error. Check what is registered with:

python -c "from codaviz.plugins import all_extensions; print(sorted(all_extensions()))"

Your first report¶

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

The report is a single self-contained HTML file: the chart library, the styles, the application script, and the analysis payload are all inlined. It works offline, from a file:// URL, and survives being emailed.

Sharing a report

Source snippets are embedded by default so you can read a function without leaving the page. Pass --no-source to leave them out: a smaller file, and no code in something you hand to someone outside the project.

Set your thresholds¶

codaviz flags functions above a cyclomatic or cognitive threshold. The defaults are 15 and 15. Override them in the analyzed project's pyproject.toml:

[tool.codaviz]
max-complexity = 10
max-cognitive = 12

See Configuration for the full table.

Development¶

make test     # uv run pytest
make lint     # ruff check + format check + type checks (ty, pyrefly, mypy)
make format   # ruff format + autofix

The test suite is tiered: tests/a_unit, tests/b_integration, tests/c_e2e, with pytest markers unit, integration, and e2e. The end-to-end tier includes running the report's JavaScript in Node.

To build this documentation:

make docs        # build into docs/site
make docs-serve  # live preview on http://localhost:8000