From a DeepWiki study of xai-org/grok-build's graph engineering (session research, 2026-08-04):
What grok-build has
- A terminal Mermaid layout engine (
xai-grok-markdown/mermaid.rs): real Sugiyama-style layered drawing — DFS rank assignment (compute_ranks), barycenter crossing minimization with alternating down/up sweeps (order_ranks), lane-tracked edge routing (skip edges route around boxes; shared-target back edges merge into one lane), nested subgraph frames with BT/RL flips. A strict fallback contract: unparseable/oversized graphs (node caps, subgraph depth caps, width overflow) render the source in a styled box instead of attempting layout — bounded worst case, adversarial-input tests prove it.
- A code-nav graph (
xai_codebase_graph): symbols/definitions/references, built lazily, refreshed on FsChanged/GitHeadChanged events, queried via goto-definition / find-references / index-status ops. Notably gated to their web client only, and — per the research — not used to self-generate diagrams or auto-assemble context.
What graff should take
A. Terminal mermaid rendering (parity). When a model response contains a ```mermaid fence, the TUI should lay it out and draw it as box art instead of printing raw fence text. Scope v1 to flowchart/graph TD|LR, port the same algorithm shape (rank → barycenter sweeps → lane routing) in Zig, and adopt grok-build's fallback contract verbatim: parse failure or size caps → the fenced source in a bordered block with a hint. Their adversarial tests (10k-node chains, 8-deep subgraph nesting) are the test plan.
B. codedb-generated diagrams (past parity). graff already fronts a code graph richer than grok-build's def/refs index — codedb's callers, callpath, deps, outline. grok-build renders only model-authored mermaid; graff can generate mermaid from ground truth: a /graph <symbol> REPL command (and/or a graph tool the model can call) that asks codedb for callers/callees/deps of a symbol and emits the mermaid straight into the same renderer. Architecture answers become diagrams derived from the actual code graph, not from the model's recollection — no hallucinated edges.
C. Explicitly NOT taking: the code-nav index itself (codedb already exceeds it: structural queries vs def/refs; the codedbGuard already routes the model there), and their client-capability gating model.
Constraints
- New modules (mermaid_layout.zig, mermaid_render.zig, graph_cmd.zig) — several TUI files sit at/near the 600 cap.
- Fallback contract is load-bearing: a TUI must never hang or corrupt borders on adversarial model output; port their caps and the border-integrity tests (no '┼' corruption, skip-edge entry markers).
- Renderer is pure text-in/text-out → fully unit-testable without a PTY.
Research links: https://deepwiki.com/xai-org/grok-build (code graph gating: MvpAgent code_nav_eligibility; mermaid: compute_ranks/order_ranks/place_lr and mermaid_worker.rs out-of-process PNG path, which we skip for v1).
🤖 Generated with Claude Code
https://claude.ai/code/session_01QbsV84fdmf39Bh2RF8LdPs
From a DeepWiki study of xai-org/grok-build's graph engineering (session research, 2026-08-04):
What grok-build has
xai-grok-markdown/mermaid.rs): real Sugiyama-style layered drawing — DFS rank assignment (compute_ranks), barycenter crossing minimization with alternating down/up sweeps (order_ranks), lane-tracked edge routing (skip edges route around boxes; shared-target back edges merge into one lane), nested subgraph frames with BT/RL flips. A strict fallback contract: unparseable/oversized graphs (node caps, subgraph depth caps, width overflow) render the source in a styled box instead of attempting layout — bounded worst case, adversarial-input tests prove it.xai_codebase_graph): symbols/definitions/references, built lazily, refreshed onFsChanged/GitHeadChangedevents, queried via goto-definition / find-references / index-status ops. Notably gated to their web client only, and — per the research — not used to self-generate diagrams or auto-assemble context.What graff should take
A. Terminal mermaid rendering (parity). When a model response contains a ```mermaid fence, the TUI should lay it out and draw it as box art instead of printing raw fence text. Scope v1 to flowchart/graph TD|LR, port the same algorithm shape (rank → barycenter sweeps → lane routing) in Zig, and adopt grok-build's fallback contract verbatim: parse failure or size caps → the fenced source in a bordered block with a hint. Their adversarial tests (10k-node chains, 8-deep subgraph nesting) are the test plan.
B. codedb-generated diagrams (past parity). graff already fronts a code graph richer than grok-build's def/refs index — codedb's
callers,callpath,deps,outline. grok-build renders only model-authored mermaid; graff can generate mermaid from ground truth: a/graph <symbol>REPL command (and/or agraphtool the model can call) that asks codedb for callers/callees/deps of a symbol and emits the mermaid straight into the same renderer. Architecture answers become diagrams derived from the actual code graph, not from the model's recollection — no hallucinated edges.C. Explicitly NOT taking: the code-nav index itself (codedb already exceeds it: structural queries vs def/refs; the codedbGuard already routes the model there), and their client-capability gating model.
Constraints
Research links: https://deepwiki.com/xai-org/grok-build (code graph gating: MvpAgent code_nav_eligibility; mermaid: compute_ranks/order_ranks/place_lr and mermaid_worker.rs out-of-process PNG path, which we skip for v1).
🤖 Generated with Claude Code
https://claude.ai/code/session_01QbsV84fdmf39Bh2RF8LdPs