Using the app

Paste a GitHub URL into the box at the top of the app and press the button. A file, folder, branch, pull request, commit or comparison all work, and the button says what you’ll get: Render PR #874 for a pull request, Map repository for a repository (it opens as Guide), Search for anything that isn’t a link. You can also type a repository’s name to search for it, pick it, and then type to find its files and functions.

Try it on a pull request

The toolbar

Once something is drawn, a toolbar sits above it. Some controls show only in some views.

Zoom. A row of five levels, with − and + buttons at the ends. Each level answers one question, and the question shows next to the control.

Level	Question
Headers	What is in this file, and what does each function promise?
Outline	What does it decide, and where can it leave?
Schematic	What does it do, step by step, in plain words?
Denoised	The code without comments, docstrings and logs
Full	The code exactly as written

A ? in the toolbar’s right corner opens How much detail. On a wide screen the levels are buttons. On a phone they are the slider along the bottom edge. Changing level, in either place, keeps the line you were reading where it was. Scrolling picks a new line.

View options. A button that opens a panel. On a phone it is an icon.

• Grouping (Coarse, Medium or Fine): how many modules a folder is split into.
• Include tests: tests are left out of the module reading unless this is on.
• Nested functions: for the Functions list. A pull request does not show this.
• Don’t collapse huge functions: very large functions open folded; this draws them in full.

Complex first. A button above the functions. It focuses the most complex function and walks Next and Previous from most complex to least. Turning it off leaves focus and returns to source order. On a pull request it walks the changed functions, including ones in other files, and a function that is still being compared can take the lead until you choose one yourself. On a phone the button is an icon.

Focus. Every function has a Focus button in its header, next to the copy icon: a ring with a dot, then the word. It shows that function alone. What is around it fades, or, with Fold far, folds away. Out steps out one level, Previous and Next move to the neighbour, and Exit leaves. On a phone those are icons; the words stay the buttons’ names. The same button is on each changed function of a pull request, and Next there continues through the review. f focuses the function under the pointer, j and k move, and Esc steps out.

Settings. A button in the toolbar’s right corner, for choices that hold everywhere:

• Open at: the level a card draws when you open it from Headers.
• Color code by nesting depth: draw Schematic and Outline as colored boxes that get warmer the deeper the code is nested, instead of indented like the code.

Settings, the zoom level, the theme, and which functions you marked seen are saved in this browser only.

Key. A button next to View options that opens a small legend naming every kind of row. On a phone it is an icon.

◆ guard: if … → exit

loadUser(id)

returns early if !id→ return null

returns early if !known(id)→ return null

returns return fetchUser(id)

The Key lists: loop, guard (if … → exit), if/else, switch, callback (own scope), DB read, DB write, HTTP, goroutine/chan/lock, and how nesting shows: “blocks indent with nesting” (with Nested boxes, “fill warms with nesting depth”). A guard is a check that leaves the function at once, drawn as one row with a ◆.

A pull request

A pull request, commit or comparison opens at the Schematic level. Each function the change added, removed or changed is drawn as a diff.

Start here. Up to five functions to read first. They are ranked by how much more complex they got, then by how much of them changed. An entry also says when a function gained or lost exits, since a new way out is easy to miss. The list fills in as files are compared.

Seen. Each function has a Seen box. Tick it as you read, or press s. The left list shows how many you have done, as “N of M seen”, and the page says when you have seen them all. The ticks are kept in your browser, for that pull request at that head commit. A new push starts a fresh list, and nothing you ticked before is ticked on it for you.

After a push. When you come back to a pull request you ticked functions on before, one line at the top says what changed since, and each function says where it stands:

• Seen in 1a2b3c4, unchanged. You ticked it on that revision. Its code and the flow around its calls are the same now. A reformat or a comment does not count as a change. This is a note, not a tick: the box stays empty until you tick it on this revision.
• Needs another look. You ticked it, and the function has changed since. The line under its name says how, in the words Flow changes uses (for example, “Early return removed before save(record).”), and selecting it opens that comparison with the lines marked. Show only what needs another look at the top narrows the page to these. n goes to the next function that is neither seen nor unchanged.
• No note. A function is only matched to what you saw when it has the same file and name, and that name is the only one of its kind in the file. A renamed or moved function, or one of several with the same name, is not matched. If another function here has exactly the same code as one you saw, the card says so, as a hint; it is still unseen.

If what you saw was not saved in a form that can be compared, the function says so and counts as needing another look.

Before, Diff, Side by side and After. The Show control in the toolbar switches every function at once, and stays in view as you scroll. Diff is the default, with + for added rows and − for removed rows. Side by side draws Before and After in two columns on every function, at every zoom level. For an added or removed function, the missing side’s column says so. Before and After draw one version of the function on its own. Your choice is kept in this browser for the next pull request. On a phone the choices are icons (Before, Diff, After); Side by side is not offered, and the word Seen on each function is a checkbox alone.

Focus on a change. Each changed function has the same Focus control as a file. Next and Previous move through the changed functions in the pull request, across files. Complex first starts at the most complex of those drawn so far.

One function side by side. In Diff, a changed function also has its own Side by side button, which draws just that function in two columns. The button then reads Unified.

Badges. Each function has a badge: changed, added or removed. In the left list it is a mark: ~ changed, + added, − removed. Its chips read like cognitive 3 → 6 (+3, more complex). Metrics explains the colors.

price(order)

returns early if !order→ return null

returns removed −return order.total

returns early added +if order.comp→ return 0

returns added +return tax(order.total)

Unchanged code. A run of statements that did not change is folded into one row, ⋯ unchanged: 4 statements, with the kinds of statements it holds. Click it to open it.

Unchanged lines. At Denoised and Full, the diff shows up to 10 unchanged lines around each change and folds the rest into a bar such as ⋯ 48 unchanged lines. ↓ 20 opens the next 20 lines under the code above the bar, ↑ 20 the 20 lines over the code below it, and Show all the whole run. Bars at the top and bottom open the file’s lines above and below the function, 20 at a time.

ship(order)

cognitive 1cyclomatic 2nesting 1exits 210 lines

returns early added +if !order.items.length→ return 0

const rate = lookup(order.zone)

⋯ unchanged: 4 statements

const weight = total(order.items)

const box = pick(weight)

label(order, box)

log(order.id)

pack(order, box)

returns removed −return rate * weight

returns added +return rate * weight + fee(order)

Modules. Above the files, the same module reading as a folder, for the folders the change touches. Open a changed file and the page goes to it. A long diff leaves this closed until you open it.

Tests. Changed test files are listed under their own Tests heading in the left list, after the other files.

When a file fails. If a file can not be compared, the page says “Could not compare this file” and offers Retry and Show plain diff. The plain diff is the file’s patch as text.

A repository or folder

A repository or folder opens as modules, on a desktop and on a phone. The modules are colored by how they connect. Most dependencies is the row sort, and the default: the first row depends on other modules here. Least dependencies lists modules that depend on nothing in this folder first. On a phone the switch is an icon. The number on a module is the reading order. Previous and Next sit in a bar at the top, the same buttons as on a function. ↑ Modules goes back to the list. Open a module to see what it imports, what imports it, and its files, each as a row. The page does not pan or zoom. Open a file and its functions draw at Headers, with none of them expanded. Grouping and Include tests apply to this reading. An address with no view=, or with view=map, opens the modules. plate=part and part= open one module. A pull request uses this same reading for the folders the change touches.

Hotspots. Under a file’s functions, collapsed until you open it: the most complex functions in that file, by cognitive complexity. Each one opens at its function.

Search. Once a repository is open, the box at the top searches its files and its functions. The functions come from the files already analyzed.

Links to a function

Open a function and the address changes to include it: #fn=name:line, and &file=path when the page holds several files. The copy icon, in the header cluster with Focus and the ⋯ menu, copies that address. Anyone who opens it lands on the function. If the line has moved, the link still finds the function when its name is unique. A focus also adds spot= to the address, so the same function is focused when the link is opened.

Keyboard shortcuts

Press ? in the app to see the list. The keys do nothing while you type in a field.

Key	What it does
f	Focus the function under the pointer
j	Next function
k	Previous function
n	Next unseen function (pull request, commit, comparison)
s	Mark the current function seen, or not (pull request, commit, comparison)
+	Zoom in: more detail
−	Zoom out: less detail
?	Show or hide the list
Esc	Close the shortcut list, then step out of focus

On a folder, + and − move through the reading order. They do not zoom.