Tools · Open Code Review (OCR)

Graph Intelligence

↩ architecture.html · generated 2026-08-14

Graph Intelligence — How the Graphs Were Built

To understand OCR beyond what's inferable from the README, we ran two local, no-API-key code-intelligence tools over the actual Go source in samples/open-code-review/ and used their real output to verify the module map and diagrams rather than guessing at package structure. Raw exports live under tool-outputs/ — see its README for full detail; this page is the how/why.

What we ran

CodeGraph (@colbymchenry/codegraph)

A tree-sitter + SQLite knowledge-graph builder. Indexed the full repo.

Metric Value
Files indexed 435 (278 Go + JS/TS/Python/YAML doc tooling)
Nodes 7,416 (3,173 functions · 866 methods · 220 structs · 66 interfaces · 59 classes · 1,989 imports)
Edges 23,976 (10,883 calls · 7,403 contains · 2,466 instantiates · 1,927 references · 1,250 imports · 47 implements)

We queried the SQLite index directly (no built-in "module dependency" export command in this CodeGraph version) with tools/gen_module_dependencies.py — a small, reusable script that aggregates call/reference edges by top-level Go package (internal/<pkg> or cmd/<pkg>) and ranks symbols by call-in fan-out. Output: tool-outputs/codegraph/module_dependencies.json, which drives diagrams/04_module_dependencies.svg.

The highest-fan-in ("god") symbols confirm the design read from source: internal/llm.Error (the shared retry-boundary error wrapper, 793 in-calls — every provider call funnels through it), internal/session.New and internal/agent.New (session/agent bootstrap), and internal/tool.NewRegistry/Register (every tool wire-up point).

Graphify (graphifyy)

A NetworkX + Leiden clustering knowledge-graph builder. Ran the code-only pass (graphify update, no LLM API key configured or needed for AST extraction).

Metric Value
Nodes 4,448 (3,591 touch .go files)
Edges 6,670
Communities 341 (299 touching .go files)

A note on this run's cluster granularity. Graphify's Go extraction in this environment produced file-level nodes (one node per .go file, not one per function/struct symbol as its Python extraction typically does), so its Leiden communities land close to 1:1 with source files rather than forming the broad cross-file thematic clusters seen when Graphify runs on a Python codebase. Rather than ship 299 nearly-meaningless "Community N" labels, we derived a package-level rollup — same "never ship raw output" rule as any graph tool — in tool-outputs/graphify/graphify_communities_summary.md: the 40 largest communities, each with its dominant Go package and example files. Every internal/* package (scan, session, llm, llmloop, diff, tool, config, ...) does appear as its own dominant cluster, which is the useful confirmation — the CodeGraph module-edge data above is the primary source for the actual dependency diagram.

Readable views we built

File What it gives you
architecture.html Interactive explainer — Simple/Technical toggle, review-lifecycle stepper, 13 module boxes each answering "what happens / how the model is chosen / what's deterministic".
diagrams/module-graph.html Same 13-module flow, standalone (no narrative sections) — for sharing just the map.
tool-outputs/README.md Index of every raw export, cross-checked against the docs written from source reading.

Tools not run here

Same gap as any sandboxed build: Serena (LSP-backed symbol navigation) needs a running Go language server, and grepai (embedding-based semantic search) needs a local or remote embedding provider (e.g. Ollama). Neither is configured in this environment. Setup is unchanged from the Visa project's own docs/tools/graph-intelligence.md — point either at samples/open-code-review/ once you have a local Go LSP / Ollama running:

# Serena — symbol-level navigation over the Go package
uv tool install -p 3.13 serena-agent && serena init
# then ask your MCP-connected agent to use find_symbol / find_referencing_symbols
# over samples/open-code-review/internal/

# grepai — semantic search
brew install yoanbernabeu/tap/grepai && ollama pull nomic-embed-text
cd samples/open-code-review && grepai init && grepai watch &
grepai search "where does OCR decide which files are eligible for review"

How to refresh these graphs after code changes

CodeGraph and Graphify both need to build their SQLite/JSON indexes on local disk — a networked or FUSE-mounted project folder can hit disk I/O error on codegraph init. Index a local copy, then copy just the derived JSON/Markdown outputs back:

rsync -a samples/open-code-review/ /tmp/ocr-work/ --exclude .codegraph --exclude .graphify
cd /tmp/ocr-work

npx -y @colbymchenry/codegraph init . -f
python3 <path-to-project>/tools/gen_module_dependencies.py \
  --db .codegraph/codegraph.db --out module_dependencies.json

npx -y graphifyy update .   # code-only pass, no LLM key needed

# copy module_dependencies.json, .graphify/graph.json, .graphify/GRAPH_REPORT.md,
# and .codegraph/codegraph.db back into tool-outputs/{codegraph,graphify}/

Then re-render the diagrams: dot -Tsvg diagrams/src/04_module_dependencies.dot -o diagrams/04_module_dependencies.svg (regenerate the .dot from the refreshed JSON first if the top-N edges changed), and re-run python3 tools/generate_architecture_html.py if any module's narrative changed.