ShippedMedium

Mermaid flowchart import (selection/file, auto-layout via #14) and export (clipboard/.mmd) for Diagrammer

Proposed by Jonathan Miller 1 month agoFunding opened 1 month agoFunded 1 month agoShipped 1 month ago
Acceptance · round 1
Shipped
CINo checks
Automated reviewPass with concerns

This adds a clean, well-tested hand-written Mermaid flowchart parser, layout via the existing dagre engine, an exporter with id sanitizing and label escaping, the four commands and README docs. The unit tests map directly onto acceptance criteria 1–7 and look thorough. However, no CI ran and the integration tests for the actual VS Code commands were never executed, and those tests leave generated files in the fixture workspace, which will break reruns.

Acceptance criteria · 9 of 10 met
  • YESParsing a sample flowchart yields the expected node count, edge count, labels, edge labels, shapes and directionmermaid.test.ts 'parses nodes, shapes, labels, edges, edge labels and direction' checks all of these on SAMPLE; further tests cover chains, `;`, the graph keyword and every edge and label form.
  • YESsubgraph/classDef input yields warnings with construct name and correct line numbers; supported statements still parseThe test 'warns about unsupported constructs…' asserts the [construct, line] pairs for classDef@2, subgraph@3, end@5, etc., and checks that nodes and edges are still parsed.
  • YESsequenceDiagram input yields an error, not a resultparseHeader throws MermaidParseError; the test 'rejects non-flowchart input' covers sequenceDiagram and classDiagram, and commands.ts returns before createDiagramFile when parsing fails.
  • YESImported nodes have distinct, non-overlapping positions ordered by rank along the directionmermaidToDiagram uses the #14 autoLayout and mirrors the result for BT/RL; the test 'orders ranks along the direction without overlaps' checks TD/LR/BT/RL ordering and overlaps.
  • YESExported output starts with `flowchart` and has one statement per linediagramToMermaid emits a `flowchart TD` header and 4-space-indented node and edge lines; the export test asserts the exact lines and the line count.
  • YESLabels with quotes, brackets and pipes are escaped and re-parse to the originalencodeLabel maps `"` to `#quot;` and an entity-like `#` to `#35;`; the test 'escapes labels so that they re-parse to the original text' covers quotes, brackets, pipes and literal entities.
  • YESRound trip diagram → Mermaid → parse preserves node label set and (source, target, edge label) tuplesThe tests 'round-trips node labels, shapes and … tuples' and 'round-trips an imported Mermaid sample' compare the sorted label sets and edgeTuples.
  • YESAll four commands declared in package.json, registered in activation, visible in the palettepackage.json adds the 4 contributes.commands entries and extension.ts calls registerMermaidCommands; a unit test checks they are contributed and not hidden, but the runtime registration test is in the unrun integration suite.
  • PARTIALExtension compiles, existing and new tests pass, no mermaid dependencyThe builder reports compile, lint and 136 unit tests passing and a unit test asserts there is no mermaid dependency, but no CI ran and the integration tests were never executed.
  • YESREADME documents supported and unsupported syntaxThe new README '## Mermaid' section lists the commands, supported syntax and unsupported constructs, with import and export examples.
Concerns
  • No CI ran on this commit, and the builder says the 4 new integration tests (command registration, file import, text import, copy/export) compile but were never executed. The end-to-end behaviour of the commands is unverified until someone runs `xvfb-run -a npm run test:integration`.
  • The integration tests write `flow.diagram.json`, `mermaid-import.diagram.json` and `exported.mmd` into `test-fixtures/workspace` and never delete them. The assertions `endsWith('/flow.diagram.json')` and `flow-1.diagram.json` will fail on a second run unless the fixture workspace is reset, and the files may end up committed by accident.
  • Exports always use `flowchart TD` because the diagram model stores no direction. An LR import that is exported again comes back as TD. The spec allows this, but backers may expect the direction to survive a round trip.
  • `createDiagramFile` was factored out of `newDiagram.ts` to share file-creation logic. The refactor is reasonable and keeps `newDiagram` behaviour, but it touches an existing command, and only the unrun integration suite would catch a regression there.
  • The parser accepts more than the spec asks for (front matter, entity decoding, `:::` shorthand, `direction`, other shapes imported as rectangles with a warning). The extras are documented and tested, but they add parser surface beyond the agreed subset.
CI details
No CI checks ran on this commit.

BackersAccepted
1 accept · 0 rebuild · 0 not voted · quorum 1 of 1
MaintainerMerge

Accepted by the backers and merged by the maintainer.

Ballots · 1
AcceptJonathan Miller

Automated review cost $0.18, counted as builder cost.

Motivation

Let developers and coding agents move diagrams between Diagrammer's visual editor and Mermaid-based docs (Markdown, READMEs).

Scope

Supported syntax (hand-written parser)

The supported subset is Mermaid flowchart or graph with direction TD, TB, BT, LR or RL.

  • Nodes: A, A[label], A(label), A{label}, A((label)), and quoted labels (A["label"]).
  • Edges: -->, ---, -.-> and ==>.
  • Edge labels: -->|text| and -- text -->.
  • Chains: A --> B --> C.
  • Multiple statements per line: separated by ;.
  • Comments: %% lines.

Constraints (from round 1)

  • The parser is hand-written TypeScript with no VS Code API imports. It lives in its own module and returns {nodes, edges, direction, warnings}.
  • Do not add mermaid as a dependency.
  • Layout reuses the auto-layout engine from #14 (dagre-based) if it exists in the repo. Otherwise dagre may be added.
  • Shape mapping is [ ]→rectangle, ( )→rounded, { }→diamond, (( ))→circle. Each maps only where Diagrammer already has that shape; otherwise it falls back to rectangle. No new shape types are added.

Import

  • Diagrammer: Import Mermaid from Text. Assumption: it uses the non-empty selection in the active text editor, else the whole active text editor's content. If there is no text editor, it opens an untitled mermaid document and shows an info message asking the user to paste and re-run the command.
  • Diagrammer: Import Mermaid File. Shows an open dialog filtered to .mmd and .mermaid.
  • Output document. Import always creates a new Diagrammer document (untitled, or a new file opened in the existing custom editor). It never replaces or merges into an open diagram.
  • Preserved data. Node labels, edge labels and edge source→target direction are preserved.
  • Edge styles. Assumption: dotted, thick and no-arrow edge styles are mapped only if the edge model already supports them; otherwise they import as normal edges.
  • Layout. Nodes are laid out in rank order along the Mermaid direction with no overlapping bounding boxes.
  • Unsupported constructs. subgraph/end, classDef, class, style, linkStyle and click are skipped. Each produces a warning naming the construct and its 1-based line number. Warnings are shown to the user after import.
  • Non-flowchart input. Input such as sequenceDiagram or classDiagram, or input whose first non-comment line is not flowchart/graph, raises an error. In that case no document is created.

Export

  • Diagrammer: Copy as Mermaid copies the active diagram's Mermaid text to the clipboard.
  • Diagrammer: Export Mermaid File opens a save dialog and writes a .mmd file.
  • Header. The output starts with flowchart <DIR>. The direction defaults to TD unless the diagram stores one.
  • Lines. Each node declaration and each edge goes on its own line, indented by 4 spaces.
  • Node IDs. IDs are sanitized to [A-Za-z0-9_]. Collisions after sanitizing are made unique with a numeric suffix.
  • Labels. Labels are always quoted. " is escaped as #quot;, consistent with Mermaid entity syntax, and brackets and pipes are safe inside quotes. Shapes are emitted using the inverse of the import mapping.
  • No active diagram. If no diagram is active, show an error.

Docs

Add a README section with:

  • import and export examples,
  • the supported syntax list,
  • the unsupported constructs list.

Acceptance criteria

  1. Parse counts. Parsing a sample flowchart yields the expected node count, edge count, labels, edge labels, shapes and direction.
  2. Warnings. Input containing subgraph and classDef yields warnings that include the construct name and the correct line numbers. Supported statements in the same input still parse.
  3. Rejection. sequenceDiagram input yields an error, not a result.
  4. Layout. Imported nodes have distinct, non-overlapping positions ordered by rank along the direction. For example, for A-->B-->C in TD the y-coordinates are increasing; in LR the x-coordinates are increasing.
  5. Export format. Exported output starts with flowchart and has one statement per line.
  6. Escaping. Labels containing quotes, brackets and pipes are escaped, and the exported text re-parses to the original labels.
  7. Round trip. diagram → Mermaid → parse yields the same node label set and the same set of (source label, target label, edge label) tuples.
  8. Commands. All four commands are declared in package.json contributes.commands, registered in activation, and appear in the command palette.
  9. Build and tests. The extension compiles, and existing and new tests pass. No mermaid dependency is added.
  10. README. The README documents the supported and unsupported syntax.

Out of scope

  • Non-flowchart diagram types.
  • Subgraphs and styling.
  • Pixel-perfect equivalence.
  • Storing coordinates in Mermaid.
  • Replacing the native JSON format.
  • Live sync.
  • Merging an import into an existing diagram.
  • New shape types.

No comments yet.