fix(stateDiagram): enforce strict comment syntax

[RodrigojndSantos]

📑 Summary

Previously, the parser did not enforce strict rules for comment detection. As a result, it could incorrectly interpret inline %% sequences as comments and treat lines starting with a single % as comments. This PR restricts comments to be on their own line starting with %%, ensuring inline content is parsed normally.

Resolves #7090

📏 Design Decisions

To fix this, comment parsing is restricted to only match %% when it appears at the beginning of a new line.

This behavior now follows the documentation:

[...] Comments need to be on their own line, and must be prefaced with %% (double percent signs).

Note that the current documentation includes an example such as Moving --> Still %% another comment, which suggests inline comments are supported. This is inconsistent with the stated rule above. This change enforces the documented behavior rather than the example.

Additionally, this aligns state diagrams with the behavior of other diagram types, where inline comments are not supported and are instead parsed as normal elements.

This ensures:

• Proper separation between comments and valid diagram syntax;
• Consistent behavior across all lexer states.

Before:

After:

📋 Tasks

Make sure you

• 📖 have read the contribution guidelines
• 💻 have added necessary unit/e2e tests.
• 📓 have added documentation. Make sure MERMAID_RELEASE_VERSION is used for all new features.
• 🦋 If your PR makes a change that should be noted in one or more packages' changelogs, generate a changeset by running pnpm changeset and following the prompts. Changesets that add features should be minor and those that fix bugs should be patch. Please prefix changeset messages with feat:, fix:, or chore:.

[changeset-bot]

🦋 Changeset detected

Latest commit: 326eb2b

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
mermaid	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[netlify]

✅ Deploy Preview for mermaid-js ready!

Name	Link
🔨 Latest commit	326eb2b
🔍 Latest deploy log	https://app.netlify.com/projects/mermaid-js/deploys/69e5547c154a8a00081ed78a
😎 Deploy Preview	https://deploy-preview-7520--mermaid-js.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[pkg-pr-new]

Open in StackBlitz

@mermaid-js/examples

npm i https://pkg.pr.new/@mermaid-js/examples@7520

mermaid

npm i https://pkg.pr.new/mermaid@7520

@mermaid-js/layout-elk

npm i https://pkg.pr.new/@mermaid-js/layout-elk@7520

@mermaid-js/layout-tidy-tree

npm i https://pkg.pr.new/@mermaid-js/layout-tidy-tree@7520

@mermaid-js/mermaid-zenuml

npm i https://pkg.pr.new/@mermaid-js/mermaid-zenuml@7520

@mermaid-js/parser

npm i https://pkg.pr.new/@mermaid-js/parser@7520

@mermaid-js/tiny

npm i https://pkg.pr.new/@mermaid-js/tiny@7520

commit: 326eb2b

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 3.33%. Comparing base (bad4325) to head (326eb2b).
⚠️ Report is 90 commits behind head on develop.

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #7520      +/-   ##
==========================================
- Coverage     3.33%   3.33%   -0.01%     
==========================================
  Files          536     537       +1     
  Lines        56240   56355     +115     
  Branches       820     822       +2     
==========================================
+ Hits          1877    1878       +1     
- Misses       54363   54477     +114     

Flag	Coverage Δ
unit	3.33% <ø> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.
see 16 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[knsv]

[sisyphus-bot]

Thanks for tackling this, @RodrigojndSantos — issue #7090 has been open since October 2025, and it's great to see someone bringing state diagram comment parsing in line with the documented behavior. The PR description is thorough, and the before/after screenshots make the intent crystal clear. Let's get this across the finish line!

---

What's working well

🎉 [praise] The refactoring approach is clean — replacing four separate (and partially overlapping) comment rules with a single rule that enforces the documented invariant ("comments must be on their own line, prefaced with %%") is a solid simplification.

🎉 [praise] Good test design — the tests verify both the positive case (own-line %% comments are skipped) and the negative cases (single % is not a comment, inline %% is not a comment). Testing inside struct blocks too is a nice touch.

🎉 [praise] Changeset is correct — patch bump with fix: prefix, well-described.

---

Things to address

1. 🔴 [blocking] — Comments after blank lines are not recognized

The new comment rule [\n][ \t]*\%\%(?!\{).* starts with [\n] (a single newline). However, the [\n]+ rule (which returns the NL token) appears earlier in the grammar and will greedily consume all consecutive newlines. This means when a blank line precedes a %% comment, the newlines are already consumed before the comment rule gets a chance to match.

Reproduction scenario:

stateDiagram-v2
A --> B

%% this comment after a blank line becomes a state ID!
C --> D

What happens step by step:

1. After A --> B, the lexer sees \n\n%%...
2. The [\n]+ rule matches \n\n (2 chars) — longer than the comment rule's [\n] (which can only start a 1-char newline match before [ \t]* fails on the second \n)
3. [\n]+ wins, returns NL token
4. The lexer is now at %% this comment... with no preceding newline
5. The comment rule requires [\n] prefix — doesn't match
6. %% falls through to the ID rule [^:\n\s\-\{]+ on line 141, creating a state named %%this

This is a regression — the old rules matched %% comments regardless of preceding blank lines.

Suggested fix: Change [\n] to [\n]+ in the comment rule:

<INITIAL,ID,STATE,struct,LINE>[\n]+[ \t]*\%\%(?!\{).*     /* skip comments */

This way the comment rule can consume multiple newlines (including blank lines) before the %%, and its longer match will beat the [\n]+ NL rule.

(stateDiagram.jison, new rule at line ~65 in the PR)

---

2. 🟡 [important] — Test coverage gap for blank-line and edge-case scenarios

The current tests don't cover several realistic scenarios that would have caught issue #1 above. It would be great to add tests for:

• Comment after a blank line — A --> B\n\n%% comment\nC --> D (the regression scenario)
• Multiple consecutive comment lines — verify they're all skipped
• Comment as the last line of input — A --> B\n%% trailing comment
• Comment between transitions — A --> B\n%% comment\nB --> C (verify both transitions are parsed)

(state-style.spec.js)

---

3. 💡 [suggestion] — Document expected behavior for inline %%

The test asserts that %%not_inline_comment in [*] --> Moving %%not_inline_comment becomes a state. While this is correct per the documented rule, it's a behavior change that might surprise users who were relying on inline comments. Worth adding a brief code comment in the test explaining why this is expected — it serves as documentation for future contributors.

---

Security

No XSS or injection issues identified. This is a parser-only change that makes comment matching stricter, which is security-positive.

---

Self-check

• At least one 🎉 [praise] item exists
• No duplicate comments
• Severity tally: 1 🔴 blocking / 1 🟡 important / 0 🟢 nit / 1 💡 suggestion / 3 🎉 praise
• Verdict matches criteria: REQUEST_CHANGES (🔴 present)
• Not a draft PR — REQUEST_CHANGES is appropriate
• Tone check: collaborative and constructive

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	👍 Changes approved	1 changed	Apr 19, 2026, 10:30 PM

[RodrigojndSantos]

Hi @knsv , thanks for the detailed guidance! I've pushed the changes and addressed all the points you mentioned. Ready for review.

[knsv]

Great @RodrigojndSantos

Thanks for the extra effort. We will do a re-review!

[knsv]

Hey Santos, there are still some lingering issues to address. This wouldn't be as sensitive if it were a new diagram type, but since state diagrams already exist in the wild, changes that affect existing rendering behavior are something we take seriously.

%% comments silently become state names

This is a behavior change I want to flag. Users whose diagrams contain something like Moving --> Still %% comment: this worked before this PR (even if undocumented). After this PR, a phantom state named %%comment appears in the rendered output. That's arguably a worse failure mode than the original bug, because it's silent and visually confusing rather than loud.
These two links illustrate the difference in behavior:
Before (current):

https://mermaid.live/edit#pako:eNpdkT9vgzAQxb-KdVKWChAh_KuHLmnGTNladzjFDiCBjYwdJUV89zqm0Co33f2e7z1ZN8JZcQEUBoNGvDdYaezCa8IkcfX58kXC8I2cTNO2M_Kth058Rkd1bWRFNhuCPc7iL3py-Uf3God6pr5dvCGASjccqNFWBNAJ3eFjhPHxmIGpRScYUNdycUHbGgZMTm6tR_mhVLdsamWrGugF28FNtud_H12pFpILvVdWGqBp5j2AjnADmmdFVJbbMsuTvNy6KYA70CKOXl3luzRJ412eTgF8-8w4KotsiTnwxii9pqA16nSX5xUIrx_nC_hDTD8hcnqf

After (this PR):

https://deploy-preview-7520--mermaid-js.netlify.app/edit#pako:eNpdjz9PxDAMxb9KZOkW1FahTf9lYDlWJjYIg0VCW9EkVZqegKrfnVzKAbo3Pf9sP8srvFqpgMPs0av7ATuHOj3lwpCg55sXkqZ35NEP47ijaCMMzWv0YE-D6cjhQHDCvfmDrlL-0aPDud9ptJdsSKBzgwTu3aIS0MppPJewnocF-F5pJYAHK9G9CxBmCzsTmidr9WXN2aXrgb_hOIdqmeTfl78jikjljnYxHnh-GyOAr_ABnFU0ow2ty6KtyrZpWAKfwGuatUFVwXJGi4ptCXzFkzRr6nL7BsjBZMU

Also: please verify that %%{init:...}%% directives still work correctly with the new parser changes.

[RodrigojndSantos]

Thank you for the feedback.

In my current implementation, lines starting with %% are only recognized as comments if they are on their own line. Consequently, inline %% comments or lines starting with a single % are no longer treated as comments and are instead parsed as normal states or transitions.

I understand that turning these inline sequences into 'phantom states' is a confusing regression for users who rely on those comments (even if undocumented). That said, I’m unsure about the best path forward and would appreciate your guidance:

1. Change the parser logic to still disallow inline comments but handle them differently? In this case, do you have any suggestions on what that behavior should be?

2. Keep the current behavior (allow inline comments)? In this case, the fix for #7090 would simply ensure that comments must start with %% (whether on their own line or inline with transitions), preventing a single % from being ignored.

What do you think is the best path forward to resolve this?

Note: I have verified that %%{init:...}%% directives are still working correctly with the new parser changes.

[knsv-bot]

[sisyphus-bot]

Hi @RodrigojndSantos — thanks for laying the options out so clearly, and for the careful thought about the regression. Let's go with option 2.

The deciding factor for me is backwards compatibility. Here's how the two paths compare against the universe of existing state diagrams already in the wild (rendered on GitHub, GitLab, Obsidian, docs sites, etc.):

Existing pattern	Option 1 (reject inline %%)	Option 2 (allow inline %%)
%% full-line comment	works	works
Moving --> Still %% inline comment	parse error (breaks)	works (preserved)
State label containing a single % (the #7090 bug)	fixed	fixed
%%{init: {...}}%% directive	works	works (you've already verified)
Silent phantom %%comment state from current PR	avoided (loudly)	avoided (silently-correct)

Option 1's failure mode is a hard parse error on diagrams that used to render. Even though it's "loud" rather than "silent," from a backwards-compat standpoint that's still a breaking change — anyone whose historical docs contain Moving --> Still %% comment would suddenly see a red error box where they used to see a diagram, and we can't fix their already-published content.

Option 2's only behavior change vs. pre-PR is the #7090 fix itself: a single % stops being treated as a comment start. That's exactly the bug we want to fix, and anyone relying on that was already in broken/undocumented territory.

Concretely, what I'd like to see in the PR

1. Lexer recognizes %% as a comment start both at the beginning of a line and inline (anywhere on a line, outside of the %%{...}%% directive syntax).
2. A single % is parsed as normal text / part of an identifier (the state diagram: comments are not on their own line #7090 fix).
3. Docs update in stateDiagram.md: reconcile the prose with the example. Something like "Comments start with %% and run to the end of the line. They can be on their own line or at the end of a statement."
4. Unit tests covering:
   • %% full-line comment
   • Moving --> Still %% inline comment → parses as a transition, comment stripped
   • Line containing a single % → parsed as normal syntax, not a comment
   • %%{init: {...}}%% directive still parses (regression test to lock it in)

Thanks again for the care on this one — flagging the phantom-state behavior yourself was exactly the right instinct. Ping me when it's ready and I'll re-review. 🙏

[RodrigojndSantos]

Hi @knsv,
I’ve updated the lexer to improve comment handling:

• %% is now consistently recognized as a comment start (both full-line and inline);

• A single % is treated as normal text (not a comment);

• Documentation in stateDiagram.md has been aligned with this behavior;

• Added unit tests covering full-line comments and inline comments scenarios.

⚠️ Note: while testing the %%{init: ...}%% directive, I noticed an issue with how it is tokenized. Previously, it was being consumed by the generic \%%[^\n]* comment rule! After the changes, it now falls through to the <INITIAL,STATE>\{ rule and, even if it doesn’t match there, it eventually ends up in the INVALID state. This behavior appears to have already existed prior to my changes. It may indicate an issue with %%{ handling, though I’m unsure what the intended behavior should be. However, the directive still works as expected in my local environment.

Thanks for your guidance so far!

[pbrolin47]

Hello @RodrigojndSantos
Me, @knsv and @ashishjain0512 share the work sometimes for re-reviewing, triaging issues etc.
I see that you have addressed the comments from the discussion with @knsv, so I'll approve this PR

[pbrolin47]

This PR has gone through some iterations and I think the final comments have now been addressed.

[mermaid-bot]

@RodrigojndSantos, Thank you for the contribution!
You are now eligible for a year of Premium account on MermaidChart.
Sign up with your GitHub account to activate.