SYS.13 / GRAPH
The project as a graph
One [snapshot](/docs/snapshots), five readings. Each answers a different question, and none of them costs a request beyond the blob already loaded.
The five tabs
What each one is for.
| Tab | Answers |
|---|---|
| GRAPH | What talks to what |
| MAP | Where the code actually lives, and what crosses between folders |
| TREE | What the repository is made of, and where coupling crosses the structure |
| EXPLORE | A question, a path, an impact trace |
| INSIGHTS | Subsystems, hub nodes, cycles, and things that look wrong |
Why MAP exists next to GRAPH
A simulation and a derivation are different kinds of picture.
GRAPH draws a force simulation: every node’s position is the outcome of forces, so at several hundred nodes it is a hairball, and where a thing sits tells you nothing about what it is.
MAP has the opposite property. A rectangle’s position is derived from its path, so the picture is the repository’s folder structure and cannot be anything else. Two analyses put the same file in the same place, and every box checks against a directory listing. Area is files beneath, and the treemap is squarified rather than sliced — the naive alternative produces slivers whose area the eye cannot compare and whose labels will not fit.
The rules both scenes keep
Mostly about what the drawing is not allowed to imply.
- Filtering dims, never hides. Isolating one neighbourhood composes with a subsystem filter rather than replacing it.
- Every cap says it is a cap —
+N moreon a tree node, a hidden-label count in the corner, a partial-graph banner above a truncated view. - A label that did not fit is counted on screen. A label merely scrolled off the side is not: it is not in view, and counting it would make the readout meaningless the moment you zoom in.
- Edge direction is drawn as a gradient, faint at the source and full at what is depended upon. A gradient is only a convention, so the legend states it.
- Both tiers label the same nodes. The 3D scene positions HTML labels over the canvas and the 2D scene draws them into it, and they share one ranking.
Driving it from the keyboard
One tab stop, and a stated way out.
- Arrow keys
- Orbit the 3D scene, or pan the flat one.
- + / −
- Zoom.
- 0
- Reframe.
- Tab
- Walk the labelled nodes, in the order the label ranking produced.
- Enter
- Open the selected node, moving focus into the inspector.
- Escape
- Leave the scene.
Asking the graph a question
Nothing in this path is generated.
EXPLORE offers four traversals — what depends on this, what this depends on, how these two are connected, and what a question touches. The answer is a subgraph, and every node in it is a real file or symbol extracted from your repository.
Direction is the whole of an impact trace. Inbound is what breaks; outbound is what you must understand before changing it. They are not interchangeable, and answering one with the other gives a real list of real files that confidently answers the opposite question.
The same traversals are available from the terminal as pskl impact, pskl why and pskl ask. See The CLI.