feat(mermaid): spar-mermaid foundation with flowchart emitter (v0.10.x)

[avrabe]

Motivation

The current SVG rendering path (via etch) has known quality pain documented in docs/plans/2026-03-17-rendering-quality-design.md. Mermaid addresses both rendering quality and machine-parseability: rivet renders Mermaid in-place in requirement/test descriptions, and the text output is diff-able and round-trip-testable.

Scope — emit only, library only

This PR is the M1 foundation. It adds one new crate with no CLI surface and no renderer dependency.

In this PR:

• New crate spar-mermaid (version 0.9.3, workspace edition)
• emit_flowchart(instance: &SystemInstance, opts: &MermaidOptions) -> String — walks the component arena and emits flowchart TD
• MermaidOptions with categories filter, max_depth filter, include_connections flag
• 6 unit tests covering the full option surface
• REQ-MERMAID-001 + TEST-MERMAID-FLOWCHART in artifact tracker

Follow-on PRs (out of scope here):

• CLI subcommand
• classDiagram, requirementDiagram, block-beta
• SysML2 → Mermaid bridge
• Round-trip topology-preservation tests (need mermaid parser)
• stateDiagram per SOM (v0.11.0)
• Trace-topology overlay (v0.11.0)

MWE — sample emitted Mermaid

From the canonical test instance (root system + 3 threads + 1 processor + 2 connections):

flowchart TD
    cpu["processor: cpu"]
    root["system: root"]
    t1["thread: t1"]
    t2["thread: t2"]
    t3["thread: t3"]
    t1 --> t2
    t2 --> t3

Loading

Paste into https://mermaid.live to verify visually.

Design notes

• ConnectionEnd holds subcomponent: Option<Name> + feature: Name (not a direct ComponentInstanceIdx). Endpoint resolution uses case-insensitive name lookup against the owner's children — consistent with AADL §3.1 case-insensitive identifiers.
• SemanticConnection (which does carry direct idx pairs) is deliberately not used here: those entries are computed post-instantiation from a GlobalScope and aren't available in manually-constructed test instances. The ConnectionInstance path is sufficient for foundation emission.
• Cycle safety: SystemInstance::instantiate already detects circular containment; the emitter trusts that guarantee and documents the assumption. max_depth provides a natural bound for manually-constructed instances with depth limits set.

Checklist

• cargo build -p spar-mermaid — clean
• cargo test -p spar-mermaid — 6/6 pass
• cargo clippy -p spar-mermaid -- -D warnings — clean
• rivet validate — REQ-MERMAID-001 + TEST-MERMAID-FLOWCHART present and linked (pre-existing unrelated YAML issue at line 1615 of verification.yaml is not introduced by this PR)

🤖 Generated with Claude Code

[codecov]

Codecov Report

❌ Patch coverage is 98.80478% with 3 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
crates/spar-mermaid/src/lib.rs	98.80%	3 Missing ⚠️

📢 Thoughts on this report? Let us know!