SuperAPI AI Directory

module-map

General & other

View repository

Updated 10-16 01:33

About this skill

Module Map

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: → X it depends on, ← X depends 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-check job.

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 src for edges, package.json workspaces for the tree
  • Python: importlab or the stdlib ast module over the package tree
  • JVM/Gradle: gradle :app:dependencies plus package-level imports
  • Rust: cargo metadata for crates, mod/use for 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.