$ 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.

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.