Look at the modules, not the code. Extract the dependency graph a repo actually has, then hand the human a browser for it: repo → packages → targets → files → declaration names. Source is never shown, because the point is to see the system without reading it.
Two steps, both deterministic:
repo ──▶ extract_swift.py ──▶ graph.json ──▶ render.py ──▶ module-map.html
parses the build schema one file, no CDN,
files + imports module-map/1 opens anywhere
Never draw this map from memory. An LLM asked to diagram a codebase produces the modules it remembers, in the layering it expects. The extractor is the whole value: the graph must come off disk. If no extractor exists for the stack, write one (see Other stacks) rather than guessing.
Running it
scripts/extract_swift.py <repo> -o graph.json # Swift: SPM + Xcode project + imports
scripts/render.py graph.json -o module-map.html # single self-contained file
Optional risk overlay - functions light up red/amber when they are dangerous to change:
crap.py --json --all ... > crap.json # from n0an/crap-check
scripts/extract_swift.py <repo> --crap crap.json -o graph.json
Report the layering to the human, not the file list: which module is the foundation, who depends on whom, which edges look wrong. Then give them the HTML path and let them drill.
extract_swift.py covers Package.swift (products, targets, dependencies incl. .product(name:package:)), *.xcodeproj/project.pbxproj (native targets, product types, remote SPM packages), and every import line in every .swift file. Imports resolve in order: local product → local target → declared external package → system framework. Unresolved names land under Frameworks (hidden by default).
Reading the explorer
- Cards are the children of the current node. Rows are dependency layers: dependents on top, foundations at the bottom. An arrow means depends on; its thickness is the number of edges behind it.
- Chips on a card are edges leaving the current view:
→ Xit depends on,← Xdepends on it. Click a chip to jump there. - Click a card to descend, Backspace or the breadcrumb to go up,
/to search, hover to isolate one module's edges. - Leaf level is names, not source: types and functions with line numbers, plus the CRAP badge when joined.
- Toggles:
imports(declared build dependencies only, when off),tests(test targets),frameworks(system SDKs, off by default).
What to look for
The map is a review instrument. Things it makes obvious:
- Cycles - the layout breaks them to draw, so a back-edge pointing up the page is a cycle. Those are architecture bugs, not layout noise.
- A foundation that depends on a leaf - a low module reaching up into an app module means the dependency is inverted.
- A god module - one card with an inbound chip count far above its neighbours. Splitting it is usually the highest-leverage change in the repo.
- A module with one dependent - candidate for merging back in.
- Red function badges under a healthy-looking module - the module boundary is fine, the internals are not. That is a
crap-checkjob.
Other stacks
The renderer takes any graph in the module-map/1 schema (references/graph-schema.md), so a new stack needs an extractor, not a new UI. Write one that walks the build files and the import statements and emits the same JSON:
- TypeScript/JS:
madge --json srcfor edges,package.jsonworkspaces for the tree - Python:
importlabor the stdlibastmodule over the package tree - JVM/Gradle:
gradle :app:dependenciesplus package-level imports - Rust:
cargo metadatafor crates,mod/usefor the inside
Keep the two rules: names and line numbers only (never file bodies), and nothing in the graph that was not read off disk.