Contracts and edge cases

Platform spec article

Contracts and edge cases

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

LSP beskid.getGraph

Arguments: [{ projectUri: string, kind: string, entryUri?: string, workspaceUri?: string }]

Returns:

{
  "kind": "projectDeps",
  "mermaid": "flowchart LR\n...",
  "revision": "a1b2c3...",
  "warnings": [{ "code": "cycle", "message": "..." }],
  "metadata": {
    "nodes": [{ "id": "n0", "label": "demo", "kind": "root", "uri": "file://..." }],
    "focusedProjectUri": "file://..."
  }
}

Rule	Policy
G-01	LSP must route through beskid_queries::graph_mermaid on compilation_db
G-02	metadata.nodes is lightweight navigation data only — not a parallel graph model
G-03	hostComposition may return empty mermaid with warning no_host when entry has no launched host
G-04	Project dependency cycles must still fail at graph build; import cycles may render with warning styling

Deprecated command

beskid.getProjectGraph was removed. All clients must use beskid.getGraph with kind=projectDeps and read metadata.nodes for tree navigation.

CLI beskid graph

beskid graph [--kind project|workspace|module|imports|host] [--project PATH] [--entry PATH] [--mermaid] [--plain] [--out FILE]

Flag	Behavior
(default, TTY)	Render via graphs-tui
--mermaid	Raw Mermaid to stdout
Non-TTY	Auto --mermaid unless --tui forced

VS Code Graph Explorer

• Projects tree must remain for Targets / Dependencies / Source folders navigation.
• Graph Explorer panel must fetch beskid.getGraph and render bundled Mermaid locally (no CDN).
• Refresh must follow onRefreshWorkspaceUi and display revision badge.