Graph visualization

Platform spec feature

Graph visualization

Back to Tooling ◎ Open in platform map

Spec standingStandard

Owner

Piotr Mikstacki pmikstacki@cybernomad.it

Submitter

Piotr Mikstacki pmikstacki@cybernomad.it

Current document

ADRs (2)

1. 0001-mermaid-single-format Mermaid is the only graph output format Accepted

   All user-visible compiler graphs are emitted as Mermaid flowcharts via mermaid-builder.

   Context

   Graph data was exported as bespoke LSP JSON, CLI ASCII trees, and unused edge arrays. Multiple presentation paths diverged from the same domain graphs.

   Decision

   1. beskid_graph renders all tooling graphs to Mermaid flowcharts using mermaid-builder only.
   2. No DOT, GraphViz, or hand-rolled ASCII graph renderers in compiler presentation code.
   3. CLI uses graphs-tui to display Mermaid in the terminal; VS Code uses bundled Mermaid.js.

   Consequences

   • Domain graphs in beskid_analysis (daggy, module tree) stay for compile correctness.
   • All consumers share one Mermaid string from Salsa memoization.

   Status

   Accepted — reference implementation in compiler/crates/beskid_graph/.

   Open full ADR page

2. 0002-salsa-graph-memoization Salsa stores generated graph Mermaid strings Accepted

   beskid_queries graph_mermaid tracked queries memoize Mermaid output with revision fingerprints.

   Context

   LSP getProjectGraph rebuilt domain graphs from disk on every call. CLI printed a flattened ASCII tree from CompilePlan, losing multi-hop structure.

   Decision

   1. graph_fingerprint and graph_mermaid are #[salsa::tracked] queries in beskid_queries::graph.
   2. LSP and CLI must read graphs through compilation_db, not ad-hoc rebuilds.
   3. Invalidation follows ManifestGenerationId, FileText, and assembly/composition revision inputs per graph kind.

   Consequences

   • Extension and CLI share the same cached Mermaid revision.
   • Manifest or lock edits invalidate project/workspace graphs without full process restart.

   Status

   Accepted — extends ADR D-COMP-BUILD-0021.

   Open full ADR page

Articles

• Contracts and edge cases LSP beskid.getGraph payload, CLI flags, and graph edge-case policy. article Standard Reviewed Sat May 30
• Design model GraphSpec IR, GraphKind, GraphPayload, and revision fingerprints. article Standard Reviewed Sat May 30

History

0 revisions (git unavailable at build; counts may be empty)

Open full history on GitHub

No commits recorded for this path.

Completeness

OKarea · 4 SpecSection(s) · 0 H2 heading(s)

Section id	Required	Found
what-this-feature-specifies	yes	yes
implementation-anchors	yes	yes

Full tree: run pnpm verify:platform-spec-layout (writes src/generated/platform-spec-layout-report.json).

Related spec docs

• Area
  VS Code extension

  Graph Explorer panel consumer

• Feature
  Dependency graph and cycle policy

  Project graph build authority

• Feature
  Analysis query diagnostics facade

  Salsa graph memoization

What this feature specifies

A single Mermaid-only presentation layer (beskid_graph) for compiler graph domains. CLI, LSP, and VS Code must consume cached Mermaid strings from beskid_queries — no duplicate graph builders in TypeScript or hand-rolled ASCII renderers.

Graph kinds

Kind	Source	When available
projectDeps	ProjectGraph	Always for a resolved Project.proj
workspace	Multiple member graphs	When opened folder contains Workspace.proj
moduleTree	ModuleGraph from program assembly	After entry resolves
importClosure	Unit import edges	After program assembly
hostComposition	DI registration DAG	When entry launches a native host

Implementation anchors

• compiler/crates/beskid_graph/ — IR, adapters, Mermaid render via mermaid-builder
• compiler/crates/beskid_queries/src/graph.rs — Salsa graph_mermaid / graph_fingerprint
• compiler/crates/beskid_lsp/src/commands/project_explorer/graph.rs — beskid.getGraph
• compiler/crates/beskid_cli/src/commands/graph.rs — beskid graph + graphs-tui
• beskid_vscode/src/graphs/ — Graph Explorer webview panel

Consumers

Consumer	Default output
CLI beskid graph	Terminal TUI via graphs-tui; --mermaid for raw string
LSP beskid.getGraph	JSON payload with mermaid, revision, warnings, metadata
VS Code Graph Explorer	Interactive Mermaid webview; Projects tree remains for navigation

Articles

• Mermaid is the only graph output formatAll user-visible compiler graphs are emitted as Mermaid flowcharts via mermaid-builder.
• Contracts and edge casesLSP beskid.getGraph payload, CLI flags, and graph edge-case policy.
• Design modelGraphSpec IR, GraphKind, GraphPayload, and revision fingerprints.