Skip to content

Make the graph readable on big codebases: run order, paths, fewer boxes - #35

Merged
utkarsh5026 merged 1 commit into
mainfrom
graph-clarity
Oct 21, 2026
Merged

utkarsh5026 merged 1 commit into
mainfrom
graph-clarity

Conversation

@utkarsh5026

Copy link
Copy Markdown
Owner

On a big codebase the graph showed about 25 boxes of the same weight, with each function's calls in no particular order. This PR makes it readable top to bottom and lets you drill in.

What changes

A function's box lists what it does, in run order

  • One numbered row for each call: to its own functions, AWS, a library (SQLite, Redis, …) or HTTP, sorted by line.
  • Rows are indented inside loops and ifs, and tagged ↻ (in a loop) or if (only sometimes). Pointing at a row shows its line and the if test.
  • Each arrow leaves from its row, and the boxes a function calls are stacked in the same order, so you read down the box and across.
  • Calls not drawn are dimmed rows. Clicking one, or Open its calls ›, draws the graph from that function (JavaScript only, as before).
  • A box shows at most 6 rows plus "+N more", but never drops a row an arrow leaves from. Calls in a row to one service the same way are one row (SQLite PRAGMA (+3)).

Pointing at a box shows every path through it: up to the entry point and down to what it reaches. Pointing at S3 or a database shows every route there. Clicking a box keeps its paths lit while its code is open. Still CSS only.

Fewer boxes

  • 14 functions by default instead of 24. The command now uses the same constant as the analysis, so there's one number.
  • When not everything fits, a function that only passes on to one other doesn't get a box; a dashed "via f()" arrow runs past it.
  • On graphs of more than 10 functions, boxes leave out docstrings and when pills. Both are in the hover card, which now also says "Called only when …".

Effect

  • hermes-agent (404 functions): from 27 dense boxes to 17, each with at most about 7 rows in run order.
  • orders-service: lambda_handler() reads 1 read_orders(), 2 check(), 3 save(), 4 announce(), and those boxes stack in that order with no arrows crossing.

Checks

  • make check: lint, 42 tests, mkdocs build --strict, package.
  • New tests for the rows (order, indents, loop and if tags, merged rows, which row an arrow leaves from, run-order stacking) and for the paths kept in sight.
  • One test updated on purpose: run() only passes on to work(), so main() now reaches work() through "via run()".
  • Text snapshots are unchanged; the text output still lists calls the old way.
  • Screenshots remade; CHANGELOG.md, README.md, docs/usage.md and docs/reading.md updated.

🤖 Generated with Claude Code

- A function's box lists what it does in the order its code does it: a numbered
  row per call (its own functions, AWS, libraries, HTTP), indented inside loops
  and ifs, tagged with a loop mark or "if". Arrows leave from their row, and the
  boxes it calls are stacked in the same order. Calls not drawn are dimmed rows
  that open the function's own graph.
- Pointing at a box keeps every path through it in sight, up to the entry point
  and down to what it reaches; clicking keeps them lit while its code is open.
- 14 functions by default instead of 24; a function that only passes on to one
  other is drawn as a dashed "via" arrow instead of a box.
- Boxes on graphs of more than 10 functions leave out docstrings and when pills,
  which stay in the hover card (now with "Called only when ...").

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@utkarsh5026
utkarsh5026 merged commit 28e8eb0 into main Oct 21, 2026
8 checks passed
@utkarsh5026
utkarsh5026 deleted the graph-clarity branch October 21, 2026 03:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant