🗺️ CodeMap

Static analysis tool that maps Python codebases. Dependency graphs, call graphs, and code complexity visualization.

---

What is CodeMap?

CodeMap reads any Python codebase and tells you how it's wired together:

• Which files import which, the module-level dependency graph
• Which functions call which, the call graph at the symbol level
• Where the tangled parts are, complexity hotspots and circular dependencies

Point it at any project, get an X-ray of its structure in under 30 seconds.

Why this exists

When you join a new codebase, or come back to your own after six months, the hardest question is "where does anything live?" CodeMap answers that question visually, so you stop guessing and start reading the right files.

Quick example

After installation:

codemap analyze path/to/your_file.py

You get a Rich-formatted breakdown of every import, top-level function, class (with its methods), and call site in the file. Sample output (analyzing CodeMap's own CLI module): ╭──── 🗺️ CodeMap Analysis ────╮ │ src/codemap/cli.py │ ╰──────────────────────────────╯ ╭──────── Imports (9) ─────────╮ │ future annotations │ │ pathlib Path │ │ typer typer │ │ rich.console Console │ │ ... │ ╰──────────────────────────────╯ ╭─────── Functions (4) ────────╮ │ hello () line 30 │ │ version () line 41 │ │ analyze (path) line 47 │ │ main () line 72 │ ╰──────────────────────────────╯

Status

🚧 In active development.

Phase 1, Foundation ✅

• Project scaffold (src layout, pyproject.toml, hatchling)
• Typer CLI with hello and version commands
• Ruff + mypy + pytest config
• GitHub Actions CI on Python 3.11 and 3.12

Phase 2, AST parser ✅

• Domain models (immutable, slotted dataclasses)
• Import extraction (import x, from x import y, aliases, dotted, relative)
• Top-level function extraction (sync and async)
• Class extraction with methods
• Call-site extraction (Name and Attribute callees, <unknown> for the rest)
• parse_file(path) integration entry point
• codemap analyze <path> CLI command with Rich output
• 85 tests passing across the engine and CLI

Phase 3, Dependency graph 🔜

• Multi-file project analysis
• Module-level dependency graph
• Circular dependency detection

Phase 4, Complexity and visualization 🔜

• Cyclomatic complexity per function
• Hotspot detection
• Graph export (DOT, JSON, HTML)

Tech stack

• Python 3.11+
• ast (Python standard library) for parsing
• Typer + Rich for the CLI and pretty terminal output
• pytest + ruff for testing and linting

Local setup

git clone https://github.com/Purrnanssh/codemap.git
cd codemap
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
pytest

License

MIT, see LICENSE.

---

Built by Purrnanssh Sinha.