graph

## 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 ```bash 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 - Wedge angle = module share of the drawn symbols; a wedge reaching the rim with few rings is sparse, many tight rings is dense - Centre of a wedge = its hubs (highest degree over the chosen relations); the rim = leaves - Hover: the blue web is the symbol's edges; the detail panel (click) shows the signature (syntax-highlighted via bundled highlight.js grammars for the index's languages), its `file:start-end`, and the connected symbols grouped by relation and direction (Calls / Called by, Uses / Used by, Implements..., `xN` = several call sites). Hopping through those lists builds a breadcrumb trail at the top of the card (back arrow steps back, first crumb recovers the starting symbol; Alt+Left or Backspace = back, Esc = close, `/` = search). Pin to hub drags or pins a symbol into the centre - Camera: drag to pan (the corner cluster's pan button toggles it), wheel or pinch to zoom toward the pointer, zoom in / zoom out / fit in the bottom-right cluster (fit recentres the whole disc; double-click does the same) - Legend eye hides a module and the rest regrow into a full circle; legend label pushes the module out and rings it -- highlight and visibility are separate axes - Heatmap day hover haloes the symbols added that day; click pins the day and fills those symbols in the neutral `--today` colour. The ribbon below brushes the whole history; year chips jump to a year - 51% of the default-kind symbols on a typical index have no Calls edge (constants, type aliases, trait items): they are the `(unlinked)` group. Narrow `--kinds`, widen `--relation`, or `--unlinked drop` -- see the table above ## Pick by question - "what is the shape of this codebase / module family" -> this skill - "what depends on this one symbol / what breaks" -> the sibling x-ray skill's `visualize-dump.js` (2D layered call DAG by default; `--3d` for the force view): `node ${CLAUDE_SKILL_DIR}/../x-ray/visualize-dump.js <name> [depth]` - "how is one module organised" -> x-ray `visualize-tree.js` (collapsible tree; `--radial` for the poster); "which modules call which" -> x-ray `visualize-bundle.js --depth N` - The x-ray pages share this skill's design tokens and the light/dark toggle ## Files `graph.mjs` (CLI + assembly), `lib/dump.mjs` (dump reader), `lib/adapter.mjs` (dump -> disc data), `lib/dates.mjs` (blame line dates + cache, first-commit fallback, mtime), `lib/vendor.mjs` (vendored-bundle reader: strips unreachable network calls, count-gated), `shell.html` + `page.html` + `page.css` + `page.js` + `vendor/` (the vault-graph page, MIT -- see `UPSTREAM.md` for the pin and the tagged hunks), `vendor/hljs/` (highlight.js core + per-language grammars, BSD-3-Clause -- `BUILD.md` there has the recipe; only grammars for languages present in the dump are inlined), `assets/logo-mask.svg` (the mark in the hub, painted with the wedge colours).