Design model

Platform spec article

Design model

Back to Graph visualization ◎ Open feature 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

• Feature
  Graph visualization

  Parent feature hub

GraphSpec IR

Domain graphs (ProjectGraph, ModuleGraph, RegistrationDag) remain in beskid_analysis for correctness. Presentation flows through a domain-agnostic intermediate representation:

Field	Meaning
kind	GraphKind discriminator
nodes	Stable id, label, shape, style class, optional URI metadata
edges	Directed links with optional labels
subgraphs	Workspace members, module paths, DI scopes
warnings	Cycles, unresolved deps, empty host

GraphDocument

Field	Meaning
spec	Populated GraphSpec
mermaid	Rendered flowchart string from mermaid-builder
revision	Fingerprint for client cache invalidation

Salsa memoization

beskid_queries::graph_mermaid is the single cache host. Invalidation keys:

Kind	Inputs
projectDeps / workspace	ProjectSession, ManifestGenerationId
moduleTree / importClosure	FileText, unit_imports, assembly fingerprint
hostComposition	Entry text, syntax generation, composition snapshot

Presentation policy

• Mermaid flowchart is the only supported output format.
• CLI renders via graphs-tui; VS Code renders via bundled mermaid.min.js.
• Internal daggy graphs are never serialized directly to tooling.