fix(mermaid): escape the punctuation a sequence diagram reads as syntax

[nao1215]

Refs #146 — one subpackage per pull request. This is sequence, and it has the widest spread of the set because a sequence diagram takes no quoted text anywhere.

Two escape sets, measured one character at a time

Message, note, block description — # ;

char	what happens today
;	ends the statement, whole diagram refused
#	opens a comment — deploy #2 of 3 reaches the drawing as deploy, silently

Participant name — ; : , < > - %% ( )

char	what happens today
;	ends the statement
:	separates the name from the message after it
,	separates one name from the next
< >	open the arrow syntax
-	starts every arrow — web-server could be declared but never sent a message
%%	opens a comment on the message line and drops the message
( )	safe alone, fatal as a pair

A name is escaped identically where it is declared and where a message refers to it, so the two still match. There is a test for exactly that, since getting it wrong would silently create a second participant.

Deliberately left alone

• A # in a participant name — safe there, unlike in message text.
• A lone % anywhere — only a run opens a comment, so 50% traffic is untouched.
• The comma between two participants a note spans. NoteOver("Alice,Bob", …) is documented mermaid syntax for a note across both, and this package cannot tell it apart from one name holding a comma. Tested, and called out in the code.

On the parentheses: a single unmatched ( renders today, so escaping it does change working output. An unmatched parenthesis is not a name anybody writes, and the matched pair — Deploy (prod) — is broken today. The drawn text is identical either way.

Verification

• go test ./... passes with no golden file changed; golangci-lint run ./... reports 0 issues.
• mermaid/sequence coverage 98.7%.
• The sequence entry in doc/edgecase/main.go goes from "'#[]+emoji+Japanese+*-| to the full probe set, and the document is regenerated. Every committed diagram renders: 64 blocks, 0 failed.

Summary by CodeRabbit

• Bug Fixes
  • Improved Mermaid sequence diagrams by safely escaping special characters in participant names, messages, notes, and control-block descriptions.
  • Added support for punctuation, brackets, braces, symbols, emoji, Japanese text, and encoded content without breaking diagram syntax.
  • Preserved valid formatting for colons, percent pairs, hashes, and participant separators.
  • Maintained support for inline <br/> breaks while excluding unsupported line breaks.
• Tests
  • Expanded coverage for escaping across messages, notes, blocks, participants, and actors.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 33e63cb1-e6fa-4860-8b23-1b940a358f7b

📥 Commits

Reviewing files that changed from the base of the PR and between 11e990d and f3d2194.

📒 Files selected for processing (1)

• doc/edgecase/main.go

🚧 Files skipped from review as they are similar to previous changes (1)

• doc/edgecase/main.go

---

📝 Walkthrough

Walkthrough

Sequence diagram generation now escapes syntax-sensitive participant names, messages, notes, and control-block descriptions. Tests and edge-case fixtures cover punctuation, entity-like sequences, preserved percent and hash forms, emoji, and Japanese text.

Changes

Sequence diagram escaping

Layer / File(s)	Summary
Escaping utilities mermaid/sequence/escape.go	Added escaping rules for text, participant names, note targets, and participant lists. Entity-like hashes and percent pairs receive special handling.
Sequence output integration mermaid/sequence/*.go	Participant directives, activation methods, messages, notes, and control-block descriptions now use escaped values.
Escaping validation and edge cases mermaid/sequence/sequence_test.go, doc/edgecase/*	Tests and fixtures cover syntax-sensitive punctuation, preserved valid forms, Unicode content, emoji, and Japanese text.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related issues

• bug: thirteen mermaid subpackages write labels the renderer cannot read #146 — The PR implements escaping for sequence participants, messages, notes, and control-block text described by the issue.

Possibly related PRs

• nao1215/markdown#147 — Both PRs update sequence edge-case fixtures, while this PR also adds sequence-content escaping.
• nao1215/markdown#156 — Both PRs modify Mermaid escaping behavior and edge-case coverage.
• nao1215/markdown#159 — Both PRs add Mermaid escaping utilities and apply entity handling to diagram text.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and concisely describes the main change: escaping punctuation that Mermaid interprets as sequence-diagram syntax.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/sequence-statement-punctuation

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[github-actions]

Code Metrics Report

	main (d06f2bb)	#169 (528a9e4)	+/-
Coverage	96.4%	96.4%	-0.1%
Test Execution Time	10s	9s	-1s

Details

  |                     | main (d06f2bb) | #169 (528a9e4) |  +/-  |
  |---------------------|----------------|----------------|-------|
- | Coverage            |          96.4% |          96.4% | -0.1% |
  |   Files             |             77 |             78 |    +1 |
  |   Lines             |           3263 |           3285 |   +22 |
+ |   Covered           |           3148 |           3169 |   +21 |
+ | Test Execution Time |            10s |             9s |   -1s |

Code coverage of files in pull request scope (99.0% → 98.4%)

Files	Coverage	+/-	Status
mermaid/sequence/activation.go	100.0%	0.0%	modified
mermaid/sequence/directive.go	100.0%	0.0%	modified
mermaid/sequence/escape.go	95.4%	+95.4%	added
mermaid/sequence/note.go	100.0%	0.0%	modified
mermaid/sequence/sequence.go	97.1%	0.0%	modified
mermaid/sequence/statement.go	100.0%	0.0%	modified

---

Reported by octocov