$ cat /projects/progmap.md

progmap

A static, LLM-free map of a Python codebase — definitions, calls, imports, cycles, and history in one portable HTML file.

year
2026
role
Design & engineering
stack
Python · AST · HTML
links
Source
A dark graph explorer showing a Python call graph with modules and metrics.

Brief

Understanding an unfamiliar Python codebase usually means holding three things at once: what is defined, what calls what, and what changed recently. Static analysers are powerful but heavy; LLM summaries are fluent but unaccountable. I wanted a map I could open from disk and trust.

Approach

progmap parses a project with Python’s ast module, resolves names with real lexical scoping, and emits a typed graph of definitions and relationships. A confidence model separates “unused” from “unused as far as this tool can prove”, with public API, tests, and framework handlers treated as roots. Git history contributes co-change coupling and hotspots next to the static call graph.

The output is one self-contained HTML file with an interactive explorer, plus map.json, a Markdown report, and an optional Graphviz export.

What I learned

Static analysis becomes useful when it admits uncertainty. Treating unused code as evidence rather than a verdict made the tool something I would actually run on a codebase I cared about. Keeping the output to one portable file — no server, no CDN, no telemetry — made sharing it trivial.