topographer

Visualization of repo changes.

A collapsible dependency graph of a codebase, excluding 3rd-party modules. Node labels are the file/module name. Edges indicate a dependency/import.

Node colors:

• blue — unchanged in this commit
• green — added in this commit
• orange — modified in this commit
• red — deleted in this commit

Edge style:

• solid — direct dependency
• dashed — dynamic import

Usage

Run the script in the repo root:

npx topographer [options] [root]

Options:

• -o, --out <file> — Output HTML file (default: .topographer/map.html under root; topo.json and crap.jsonl land beside it)
• -r, --root <dir> — Repo root to scan (default: current directory)
• --no-crap — Skip CRAP annotation (CC² × (1−cov)³ + CC; on by default)
• --coverage <file> — Coverage report (Istanbul coverage-final.json or LCOV); default: auto-detect under coverage/
• -v, --version — Print version and exit
• -h, --help — Show this help

If it's not a git repo, everything is treated as "this commit". If it is a git repo, the current state is "this commit".

Outputs

• map.html — Interactive visualization of the dependency graph with optional CRAP risk view overlay.
• topo.json — Serialized graph (nodes, links, git status, manifest, and annotations unless --no-crap).
• crap.jsonl — Per-function CRAP scores and metadata (one JSON record per line, sorted by CRAP score descending, no-coverage functions last). Skipped with --no-crap.

All three land in ./.topographer/ by default (or beside the -o target), and the CLI prints each written path on completion.

Risk View

CRAP annotation runs by default (skip with --no-crap). The risk view highlights files by function complexity and coverage — click the Risk toggle in the map to enable it:

• Heat halo (color #e25822) — Size and opacity scale with the maximum CRAP score in the file (larger and more opaque = more risky)
• Gray dashed halo — File has no numeric CRAP score at all (every function lacks coverage data); a file with even one scored function gets a heat halo instead. Null coverage is distinct from 0% coverage.

Collapsed nodes display a badge showing the max CRAP score and count of above-threshold functions across the node's hidden subtree (not just the node's own file). Functions without coverage data are visibly separate from those with 0% coverage, making it clear where coverage is missing vs. explicitly low.