code-analysis

Code analysis

The output is a map: what exists, how it fits together, and where the danger is. A map is judged by whether someone can navigate with it, not by how much of the territory it mentions.

Analysis fails by exhaustiveness — describing every module at equal depth produces a document with the same information density as the source, and no reason to read it. Depth must be unequal, concentrated where the risk and the change is.

1. Read the outside before the inside

Before opening source files, read what the project says about itself and what it demonstrably does: README, entry points, public API or route definitions, configuration, CI pipeline, dependency manifest, and the shape of the test suite.

This gives you the intended architecture. The gap between it and the real one is a finding.

Done when: you can state what the system does, who calls it, and what it calls.

2. Find the spine

Every codebase has a small number of paths that carry most of the value. Trace one all the way through — a request from entry to response, a job from trigger to side effect.

Follow it end to end before branching. The spine teaches you the project's real conventions, its layering, and where its abstractions leak, far faster than reading modules in isolation.

Done when: you can narrate one complete path through the system, naming each hop.

3. Let the repository tell you where the risk is

History is evidence and costs almost nothing to gather. Where change concentrates, risk concentrates.

git log --format=%H --since="1 year ago" | wc -l
git log --name-only --format= --since="1 year ago" | sort | uniq -c | sort -rn | head -20

Cross-reference the churn list against size and test coverage. The intersection — large, frequently changed, poorly tested — is where incidents come from, and it is the most valuable paragraph in your report.

Also worth a look: files changed by many different authors (shared, so conventions drift), and files changed by exactly one author who has left.