/graph

name: graph
description: Whole-codebase structural map of the codanna index as one self-contained HTML disc. Wedges per top-level module, concentric rings with hubs at the centre, hover or click a symbol to light its edge web, search, hide or highlight modules, brush a date range on the ribbon timeline (symbols dated by git blame), heatmap of symbols added per day, per-module colour picker. Use when the question is about the shape of the whole codebase or a module family (what is central, which modules talk, where the hubs sit), not one symbol's neighbourhood. Needs codanna >= 0.14 (`codanna dump`).
allowed-tools: Bash(codanna:*), Bash(node:*), Read, Grep, Glob

What it draws

One HTML file, no server: the codanna index rendered as a pie chart of symbols. Each top-level module owns a wedge sized by its share; inside a wedge symbols fill rings from the centre outwards, best-connected first, so hubs sit near the middle and leaves on the rim. Unlinked symbols form their own inner group. Above the disc a heatmap shows symbols added per day (each symbol dated by the oldest surviving line of its span, via git blame). Hover or click a symbol to see its edge web and the connected symbols; the legend hides (eye) or highlights (label) modules and submodules; the ribbon under the heatmap brushes a date range (drag its handles, use the date fields, or click a year chip) and Refresh replays the codebase growing oldest-first.

Run

node ${CLAUDE_SKILL_DIR}/graph.mjs                      # whole index, Calls edges, default kinds
node ${CLAUDE_SKILL_DIR}/graph.mjs --root crate::indexing   # one module family
node ${CLAUDE_SKILL_DIR}/graph.mjs --relation calls,uses,implements,extends
node ${CLAUDE_SKILL_DIR}/graph.mjs --kinds function,method,struct,trait --dates none --light

• Runs `codanna dump` in the project (`--from graph.jsonl` reuses a saved dump, `--binary PATH` picks the binary)
• Output: `.codanna/visualizations/graph-disc-<timestamp>.html`, opened in the browser (`--no-open` to skip, `--out FILE` to place it)
• `--group <wedge>[/<tint>]` -- wedge axis `module` (default), `language`, or `kind`; tint axis `module` (default), `kind`, or `visibility`. The wedge is the angle (share, neighbours adjacent); the tint is the legend tree inside it (three biggest get their own shade, the rest pool). `module/kind` keeps the structure and shows what each module is made of; `language/module` for polyglot indexes; `module/visibility` for API surface per module; `kind/module` is a census (edges cross everywhere)
• `--root PREFIX` scopes to a module prefix (`crate::` is dropped, `.`/`::`/`/` all separate segments); applies to the module segments whatever the wedge axis
• `--kinds` defaults to Function, Method, Struct, Class, Trait, Enum, Interface, TypeAlias, Constant, Macro
• `--relation` defaults to `calls`; any of calls, uses, implements, extends, defines, comma-separated
• `--dates blame|git|none` -- `blame` (default) dates every symbol by the oldest surviving line of its span (`git blame -M` over the working tree; per-file JSON cache at `.codanna/visualizations/dates-cache.json` keyed by content hash, so warm runs spawn no blame -- delete the file to reset); `git` uses the file's first-commit day (cheap, but a refactor reads as mass birth); `none` leaves the timeline and heatmap empty
• `--unlinked include|drop` -- `drop` removes symbols with no edge over the chosen relations at build time (smaller file, smaller disc); in the page, the legend eye on `(unlinked)` hides the same set with the cascade animation
• `--name NAME` sets the title (default: project directory name); `--light` builds the light theme

Scoping and filters: what to apply when

Start whole-index once to see module shares and hubs, then scope. The disc is smooth to a few thousand symbols; hover and filters fall to ~10 fps near 10,000 (the CLI says so above 4,000). Measured on the codanna self index (14,003 symbols):

| Situation | Apply | Effect on self index | |---|---|---| | First look, whole codebase | defaults | 9,983 symbols, 8,248 calls edges, 51% unlinked | | The hub hole dominates (`(unlinked)` is the biggest group) | `--unlinked drop` | 4,890 symbols, same 8,248 edges; or hide it in-page with its legend eye | | Many constants/aliases, few calls | `--kinds function,method,struct,class,trait,enum,interface` | 8,453 symbols, unlinked 42% | | Type-level structure matters (impls, inheritance, field types) | `--relation calls,uses,implements,extends` | 11,003 edges, unlinked 41%; both together: 10,305 edges, 32% | | Work inside one module family | `--root crate::indexing` (or `src/...` for path-derived languages) | 701 symbols, 6 groups, smooth hover | | "What is each module made of" (trait-heavy vs free functions) | `--group module/kind` | same wedges, tints = kinds | | Polyglot repo / monorepo, languages first | `--group language/module` | 15 language wedges on self, modules as tints | | Public surface vs internals per module | `--group module/visibility` | tints = public / private / crate... | | Census by symbol kind | `--group kind/module` | wedges = kinds; every call crosses the disc, read the counts | | More than twelve top-level groups | the twelve palette slots cycle; pin colours per module via the gear (persists in the browser) or right-click a legend row | repeats stay separated by wedge, rim label and legend row | | Heatmap/timeline empty or misleading (shallow clone, vendored code) | `--dates none` | both panels blank, disc unchanged | | Re-render without re-reading the index | `--from graph.jsonl` (from `codanna dump > graph.jsonl`) | same data, no dump run |

`defines` as a relation is containment; the legend tree already carries it, so add it only when you want container->member lines on the disc. `--root` matches module segments, so `crate::parsing::rust`, `parsing.rust` and `parsing/rust` are the same prefix; a symbol with no `module_path` falls back to its file path segments.

Reading it