Turn a Python repository into an architecture map you can inspect in a browser. Codebase Cartographer reads source locally with Python's AST, calculates complexity and dependency signals, then emits a deterministic JSON dataset, an SVG dependency graph, and a self-contained interactive HTML report.
- cyclomatic complexity and maximum nesting for every function;
- internal module edges, external packages, fan-in, and fan-out;
- circular dependencies using Tarjan's strongly connected components;
- PageRank-inspired module centrality;
- reverse-dependency change impact with direct and transitive blast radius;
- public API documentation coverage and TODO/FIXME/HACK markers;
- a composite risk score designed to prioritize review and testing work;
- actionable recommendations based on the detected hotspots.
No packages are required and no source code leaves your machine.
python cartographer.py demo_project --project-name "Orbital Notes Demo" --output-dir examplesOpen examples/report.html in a browser. You can also analyze another project:
python cartographer.py path/to/python-project --output-dir my-reportUse the optional risk gate in CI:
python cartographer.py src --fail-on-risk 60The command exits with status 2 when the highest module risk reaches the
specified threshold.
python -m unittest discover -s tests -vThe bundled demo_project intentionally contains a small circular dependency,
giving the example report something realistic to detect and explain.
The score is a prioritization heuristic, not a judgment of code quality. It
combines complexity, centrality, coupling, size, documentation gaps, cycles,
and parse errors. The full raw metrics remain available in analysis.json, so
teams can replace the score with their own policy.
Created with AI assistance as a transparent daily creative-coding project.