Eric Traut
44fe510ce3
## What changed - Default `flowchart` and `graph` to top-down layout when no direction is specified. - Support solid and dashed edges with directed, undirected, or bidirectional endpoints: `-->`, `---`, `<-->`, `-.->`, `-.-`, and `<-.->`. - Accept pipe labels on these edges and spaced directed infix labels such as `A -- send --> B` and `A -. retry .-> B`. - Expand `&` groups into all source-to-target edges, including in chains. For example, `A & B --> C & D` creates four edges. Enforce the 24-edge limit after expansion and cap each group at 24 node references. ## Testing Add coverage for equivalent syntax, edge styles and endpoints, malformed input, and expansion limits. Extend rendering snapshots across all four directions and the TUI native-renderer test with the new syntax. GitOrigin-RevId: 6e51653ebf6b8b7e7e1edec0c2e09a5d9c8dec74
codex-mermaid
Standalone, bounded Mermaid text renderer.
It uses the existing unicode-width dependency; no Mermaid runtime or new external
production dependency is needed.
Supported subsets
| Family | Supported syntax |
|---|---|
flowchart, graph |
TD/TB (default), BT, LR, RL; rectangle [label], decision {label}, and stadium ([label]) nodes; solid -->/---/<--> and dashed -.->/-.-/<-.-> edges; pipe labels and spaced directed infix labels (-- text -->, -. text .->); & fan-out/fan-in, chains, branches, merges, loops |
sequenceDiagram |
Implicit participants, participant/actor, aliases, ->, ->>, -->, -->>, -x, --x, self-messages, Note over A[,B], nested loop/alt/opt/critical/break, one labeled else per alt |
stateDiagram-v2, stateDiagram |
Flat states, state "label" as ID, descriptions, directed transitions with optional labels, initial/final [*], direction declarations |
classDiagram |
class ID, multiline member bodies, ID : member, solid/dashed links, association, inheritance, composition, aggregation, dependency, realization, quoted endpoint cardinalities, relationship labels, direction declarations |
erDiagram |
Entities, multiline attribute bodies, type name [PK, FK, UK] ["comment"], all four endpoint cardinalities, identifying/non-identifying relationships, relationship labels, direction declarations |
Identifiers are ASCII letters followed by letters, digits, or underscores. Text
supports ordinary Unicode and CJK. Full-line %% comments and
semicolon-separated statements are supported outside flowchart labels, quoted
tokens, and class bodies. Sequence quotes are literal text; use newlines between
class members, whose semicolons remain text. Member/attribute bodies need a
separate statement for each opening brace, member, and closing brace (for
example class Order { followed by member lines and a final }). Class member
text is retained in one compartment, including visibility, signatures, and
return types. ER attribute types and names use the identifier grammar above.
Flowchart node and edge labels may be enclosed in double quotes. Literal ampersands are supported in labels, as is printable punctuation after parsing. Quotes protect flowchart label delimiters such as brackets, pipes, and semicolons. HTML and entity escapes remain unsupported and return an error before statement splitting.
These are explicit subsets, not complete Mermaid compatibility. Compound states, flowchart subgraphs, other shapes, sequence activation and parallel fragments, styling, front matter, directives, HTML, escapes, combining/zero-width characters, and ligatures with non-additive widths return errors. Callers should retain source on any error; the library never returns a partial diagram.
Layout and notation
Graph nodes appear in declaration/first-reference order, in the requested direction.
Each edge gets its own lane and endpoint positions. Crossings use ╪ and never
join routes. Decisions use ◇ inside a box; stadiums use rounded box corners. Horizontal layouts
reserve a text gutter for every endpoint, which can make connected graphs wide;
the caller receives TooWide if the complete output does not fit.
Class links use arrows into the referenced class, ◁/△ for inheritance/realization,
◆ for composition, and ◇ for aggregation. Endpoint cardinalities appear in
parentheses next to the appropriate class or entity. ER cardinalities are written
as 1, 0..1, 1..many, or 0..many. Solid ER links are identifying; dashed links
are non-identifying. Class members and ER keys/comments appear verbatim as readable
text, rather than renderer metadata.
Sequence messages retain chronological order. ->>/-->> use ▶/◀ arrowheads,
->/--> have no arrowhead, and -x/--x use a cross endpoint. Solid and dashed
strokes remain distinct. Lifelines crossed by a message use ┼; this is not a recipient.
Control fragments have nested frames and explicit branch labels. Notes span their
named participants. States use separate ● initial and ◎ final nodes.
Limits and evaluation
All inputs are limited to 16 KiB. Graphs allow 16 nodes, 24 edges (after expanding
& groups), and 16 members per node. Each & group allows at most 24 node references. Sequences allow 8 participants, 64 events (including fragment boundaries),
and 4 fragment levels. Source labels and identifiers are limited to 40 display
cells/ASCII bytes respectively. Rendered canvases are capped at 65,536 cells,
independent of the caller's maximum width. The library performs no I/O.
From codex-rs, preview a file, optionally specifying the available width:
cargo run -p codex-mermaid --example render -- 180 < diagram.mmd
Run just test -p codex-mermaid --lib. Coverage includes complex snapshots for every
family, relationship endpoints, all ER cardinalities, width/error bounds,
truncated input, and reconstruction of every edge in all 512 directed three-node
graphs in each of the four layout directions.
render_spans returns the same layout as lines of semantic Node, Edge, and
Text spans. Callers apply their own theme; the crate never emits ANSI escapes.