sealmap_mermaid/lib.rs
1//! # sealmap-mermaid
2//!
3//! Typed, deterministic writers for the Mermaid diagram kinds that explain
4//! code best: [`SequenceDiagram`] (behaviour), [`ClassDiagram`] (structure),
5//! [`ErDiagram`] (data) and [`Flowchart`] (dependencies and topology, from
6//! module level up to multi-repository maps).
7//!
8//! The writers know nothing about code models; they are a safe Mermaid
9//! emitter you can use on their own, and with `default-features = false` the
10//! crate has **no dependencies**. The default `model` feature adds
11//! `Ident::from_symbol`, the injective map from a `sealmap_model::SymbolId`
12//! to a diagram id that `sealmap-corpus` uses to project a
13//! `sealmap_model::Codebase` into diagrams.
14//!
15//! ## Why typed builders instead of `format!`
16//!
17//! Mermaid's grammar has sharp edges that string concatenation trips over:
18//! `;` ends a statement inside sequence messages, `end` is a keyword in node
19//! ids, `{`/`}` close class bodies, `(` turns a class member into a method,
20//! `<`/`>` collide with generics, and `#` starts an entity code. Escaping
21//! uses Mermaid entity codes (`#lt;`, `#59;`, ...), which render as the
22//! original characters. Every value
23//! that reaches the output here goes through [`Ident`] (for ids) or
24//! [`escape_text`] (for labels), so arbitrary source text cannot break a
25//! diagram.
26//!
27//! ## Determinism and density
28//!
29//! * Rendering is a pure function of the builder: same calls, same bytes.
30//! Builders preserve insertion order for statements (sequence order *is*
31//! meaning) and you control ordering of declarations. Nothing is sorted
32//! behind your back and nothing depends on hash order.
33//! * Output uses two-space indentation, `\n` line endings, a trailing newline
34//! and no trailing whitespace.
35//! * Output is minimal: no styling, no redundant arrows, no init directives
36//! unless you add them. Density is the default; decoration is opt-in.
37//!
38//! ## Example
39//!
40//! ```
41//! use sealmap_mermaid::{Arrow, Ident, SequenceDiagram};
42//!
43//! let api = Ident::new("app__Api");
44//! let db = Ident::new("app__Db");
45//!
46//! let mut seq = SequenceDiagram::new();
47//! seq.participant(api.clone(), "Api");
48//! seq.participant(db.clone(), "Db");
49//! seq.message(&api, &db, Arrow::Sync, "query(sql); fetch");
50//! seq.loop_block("for row in rows", |b| {
51//! b.message(&api, &api, Arrow::Sync, "decode(row)?");
52//! });
53//!
54//! assert_eq!(
55//! seq.render(),
56//! "sequenceDiagram\n\
57//! \x20 participant app__Api as Api\n\
58//! \x20 participant app__Db as Db\n\
59//! \x20 app__Api->>app__Db: query(sql)#59; fetch\n\
60//! \x20 loop for row in rows\n\
61//! \x20 app__Api->>app__Api: decode(row)?\n\
62//! \x20 end\n"
63//! );
64//! ```
65
66#![forbid(unsafe_code)]
67#![deny(missing_docs)]
68
69mod class;
70mod er;
71mod escape;
72mod flowchart;
73mod sequence;
74#[cfg(feature = "model")]
75mod symbol;
76mod writer;
77
78pub use class::{Class, ClassDiagram, ClassRelation, ClassRelationKind, Direction};
79pub use er::{Cardinality, ErDiagram};
80pub use escape::{Ident, escape_text, escape_type};
81pub use flowchart::{EdgeStyle, Flowchart, NodeShape};
82pub use sequence::{Arrow, BlockKind, SeqBuilder, SequenceDiagram};
83pub use writer::CodeWriter;
84
85/// Compiles and runs the README examples as doctests.
86#[cfg(doctest)]
87#[doc = include_str!("../README.md")]
88struct ReadmeDoctests;