Skip to content

Usage

codaviz [OPTIONS] [PATHS...]

Arguments

PATHS
Project directories to analyze. Defaults to the current directory. Pass several to merge a workspace into one report.

Options

Option Default Effect
-f, --format html Output format: html, json, or csv.
-o, --output FILE see below Where to write.
--no-source off Omit embedded source snippets from the HTML report.
--version — Print the version and exit.
-h, --help — Print help and exit.

An unrecognised --format value exits with status 2.

Where output goes

  • html: always a file, never stdout. Defaults to report.html in the current directory.
  • json and csv: stdout unless -o is given.

When codaviz writes a file it prints codaviz: wrote <path> to stderr, so codaviz -f json piped into another command stays clean.

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 entity
codaviz packages/*                              # merge a workspace into one report

Analyzing several roots

codaviz packages/core packages/web packages/cli

Each root is resolved to its own source root (so a src/ layout surfaces its real top-level packages), then all entities are merged by id:

  • Packages that several roots share, such as a namespace package like hop3 split across distributions, combine into one subtree.
  • Import cycles that cross root boundaries resolve, because module names are computed relative to each root's own source root.
  • A genuine duplicate module id across roots prints a warning on stderr and keeps the last one seen.

Which pyproject.toml is read

exclude and include-tests are read from each root's own pyproject.toml, so every project in a workspace keeps its own exclusion rules. The report-wide knobs (max-complexity, max-cognitive, treemap-depth) are read from the first root only, since there is one report.

What gets analyzed

Inside a git repository, codaviz asks git for the project's files:

git ls-files -z --cached --others --exclude-standard

That returns tracked and uncommitted files while honouring .gitignore, so a fresh checkout works and ignored trees like .venv never appear. Outside a repository codaviz prints a notice on stderr and walks the directory instead, pruning excluded directories as it goes.

Files are then filtered by extension (whatever the registered analyzers claim) and by the exclusion rules described in Configuration.

Each surviving file is dispatched to the analyzer that claims its extension. A file that cannot be read as UTF-8, or that the analyzer chokes on, is reported on stderr and skipped, so one bad file never aborts the run.

Exit status

Status Meaning
0 Analysis completed.
2 Unknown --format value.

A path that is not a directory is skipped with a stderr warning; it does not fail the run.