🤓 Latest Submissions
Codebase Autopsy
The problem: Documentation drift is one of the most common and hardest-to-catch forms of technical debt. A docstring says a function is "pure" or "read-only," but six refactors later it's quietly writing to disk or making network calls and nothing flags it. Code review catches this only if the reviewer happens to read both the docstring and the diff carefully; most don't. Static analysis tools check types and syntax, not whether a module still does what it says it does. The solution: Codebase Autopsy is a CLI pipeline that performs a structural and semantic audit of a Python codebase in three stages. First, it walks the repo and parses every file with Python's ast module, extracting each module's docstring, functions, classes, imports, and every call made at module and function scope without executing any code. Second, it builds a full import-dependency graph from that data, resolving both absolute and relative imports, detecting circular dependencies, and ranking modules by in-degree to surface architectural hubs. Third, for every module that has a docstring, it hands a structured summary of that module (its stated purpose plus what its functions actually call) to an LLM, which judges whether the declared purpose and the observed behavior still agree. The LLM returns a 0–10 drift score with concrete evidence not just a gut-feeling flag, but a paper trail: "this function claims no side effects, but it calls open() and a logger." Target users: engineering teams and solo maintainers with any codebase old enough to have accumulated drift which is nearly all of them. A developer runs one command against a repo path and gets back a ranked report: import cycles first, then the modules whose documentation and implementation have diverged worst, each with plain-English evidence they can act on immediately. What makes it unique: most drift/quality tools measure code against code (types, lint rules, test coverage). This measures code against its own stated intent, using structural facts extracted by ast not vibes as the evidence the LLM has to reason over. The graph layer also means drift scores aren't judged in isolation: a highly depended-upon module with a wrong docstring is a much bigger problem than an isolated one, and the report reflects that. Efficiency: parsing and graph-building are pure static analysis fast and free. The only paid step is the LLM call, and only for modules that actually have a docstring worth checking, so cost scales with how well-documented (and therefore how checkable) a repo already is.
27 Sep 2026
