webview

Serve the knowledge graph database in an interactive web visualisation — pan and zoom, filter by node kind, search symbols, and inspect a node’s edges.

Source: src/commands/webview_command.ts · front-end: contribs/webview

Synopsis

npx codespine webview [options]

Arguments

None.

Options

What it does

1. Resolves the database path and checks it exists. If not, it prints an error (database not found … — run extract then load first), sets exit code 1, and returns.
2. Resolves the GitHub source. It prefers the provenance extract recorded in the database — the exact commit and in-repo prefix that was parsed — and falls back to detecting it live from --source. A found source is injected as window.GRAPH_SOURCE, so every node can deep-link to its declaration on GitHub at that commit; when neither is available, file paths render as plain text.
3. Reads the whole graph once at startup. It opens the Kùzu store and runs two Cypher queries — one for all nodes, one for all edges — then serializes the result into a JavaScript snippet that assigns window.GRAPH_DATA. It logs how many nodes and edges were loaded.
4. Starts a plain Node http server:
   • GET /js_autogenerated/graph_data.js returns the in-memory graph snippet. This is the script the page loads on boot.
   • Every other path is served as a static file from the bundled contribs/webview/web directory (/ maps to index.html).
   • The static file path is normalized and confined to the web root, so requests cannot escape the directory with .. traversal. Anything outside it, or any missing file, returns 404 not found.
5. Prints the URL and waits. Stop it with Ctrl+C.

Served MIME types cover .html, .css, .js, .json, .png, and .svg; anything else falls back to application/octet-stream.

The visualisation

The page is a single interactive graph (Cytoscape) with a control sidebar:

• Search — find any symbol or file by name and jump to it.
• Colour by — switch the node encoding between structural (node kind), runtime (a self-time heat map, after enrich), and community (the module index from cluster, drawn with a legend).
• Filter — toggle node kinds and edge kinds on and off to isolate one layer (just CALLS, say, or hide Parameter nodes); hide whole communities.
• Inspect — click a node for its details and one-hop edges, and follow it to its exact line on GitHub (below).
• Theme — dark or light, following the system preference.

GitHub links

When the served graph carries source provenance — recorded by extract at build time, or detected live from --source — each node links to its declaration on GitHub at the exact parsed commit. Built outside a git checkout, and with no --source fallback, the visualisation shows plain-text paths instead.

Output

loaded ~390 nodes, ~1.3k edges from /…/.codespine/graph.kuzu
✓ serving the knowledge graph at http://localhost:4173/
  press Ctrl+C to stop

Examples

# serve the default database on the default port
npx codespine webview
 
# choose a port
npx codespine webview --port 8080
 
# point GitHub links at a specific checkout when the graph recorded no source
npx codespine webview --source ../my-project

Notes and caveats

• The graph is read once, at startup. Edits to the database after the server starts are not reflected — re-run extract and load, then restart webview to see changes.
• The whole graph is sent to the browser in one payload. This is fine for the graphs this tool produces; very large graphs will produce a large initial download.
• Holding the database open here can block a concurrent load. Stop the server before reloading.
• The static assets are resolved relative to the command’s own module, so the same command works both from src/ (via tsx) and from the published dist/ package.

See also

• load — build the database webview serves.
• contribs/webview — the front-end this command serves.