perf(frontmatter): replace the quadratic front matter regex on hot paths

[MFA-G]

Description

Closes #8200 — frontMatterRegex backtracks polynomially (CodeQL js/polynomial-redos).

The opening \s*[\n\r] is ambiguous: \s* can also consume line breaks, so every failed search for a closing fence backtracks into it, and each of the O(n) split points then rescans the lazy body. Measured on '---\n' + ' \n'.repeat(n), which fits inside the default 50k maxTextSize:

n	frontMatterRegex	matchFrontMatter
4 000	34.6 ms	1.33 ms
8 000	144.9 ms	1.99 ms
16 000	581.7 ms	2.78 ms
24 000	1269.0 ms	1.54 ms

It is reachable from detectType() on raw user input.

Approach

Same shape as the stripAnyComments fix in #7906: a linear scanner replaces the regex on the hot paths, and the regex stays as the test oracle.

As the issue notes, a linear rewrite is not automatically behaviour-preserving — de-ambiguating the opening changes which fence closes the block. So matchFrontMatter reproduces the backtracking result rather than a tidier reading of it. The engine tries the longest opening first and shortens it one line break at a time, which is equivalent to:

1. the opening ends at the last line break of the run after --- that still leaves a closing fence after it;
2. the body ends at the first closing fence after that, since the body is lazy.

That is why the divergence example from the issue, '---\n\n---\n\nMORE\n---\n', is still stripped whole: the opening swallows both leading line breaks, the second --- lands inside the body, and only the third can close. No document changes how it is stripped.

Two forward passes, each visiting a character a bounded number of times — the trailing whitespace runs of two closing fences cannot overlap, since --- separates them.

frontMatterRegex remains exported and byte-for-byte unchanged; it is published surface, and removing it would be a separate breaking decision. A comment now points internal callers at the scanner.

Changes

• regexes.ts — add matchFrontMatter, returning { indent, body, length } (the regex's groups 1, 2 and match length).
• detectType.ts, frontmatter.ts — the two callers that matched the regex on user input.
• regexes.spec.ts — equivalence against frontMatterRegex over a hand-written corpus (CRLF, tab indent, indented --- inside a multi-line scalar per Sankey diagram throws "Syntax error in text" with sankey keyword (missing hyphen) #7613, the frontMatterRegex is polynomial on whitespace-heavy input (ReDoS, CodeQL js/polynomial-redos) #8200 divergence, unterminated blocks, four-dash fences, mismatched indents) plus 3000 random fence-and-whitespace strings from a seeded PRNG, and a scaling assertion.

Also here

The existing stripAnyComments scaling test took the mean of its timed runs, which made it flake under parallel workers (I hit it at 28x on an otherwise-clean tree). Both scaling tests now take the minimum, which reports the run that was not interrupted. This is a test-only change; the ratio bar of 8 is untouched.

Validation

• vitest run packages/mermaid/src/diagram-api/ → 60 passed.
• Full vitest run packages/mermaid/src/ → same failures as develop (unbuilt @mermaid-js/parser workspace dep locally); no new ones. Diffed the failing-file lists against a stashed tree to confirm.
• ESLint and Prettier clean on the touched files.

Summary

• Replaced hot-path use of frontMatterRegex with the linear matchFrontMatter scanner.
• Updated detectType and extractFrontMatter.
• Preserved frontMatterRegex unchanged for compatibility.
• Added equivalence, seeded random-input, and linear-scaling tests.
• Improved timing-test stability with minimum measurements.
• Added a Mermaid package changeset.
• Targeted tests, ESLint, and Prettier checks passed.

[changeset-bot]

🦋 Changeset detected

Latest commit: 139f470

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	139f470
🔍 Latest deploy log	https://app.netlify.com/projects/mermaid-js/deploys/6aade40335928e00081bdf6b
😎 Deploy Preview	https://deploy-preview-8203--mermaid-js.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

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

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Advanced

Run ID: f9526a5c-80dd-4db6-ba88-30072e37be25

📥 Commits

Reviewing files that changed from the base of the PR and between 40ef7b4 and 139f470.

📒 Files selected for processing (1)

• packages/mermaid/src/diagram-api/regexes.spec.ts

Included review availability: Your plan provides up to 10 included reviews per hour; 9 remain after this review.

---

📝 Walkthrough

Walkthrough

The change adds a linear matchFrontMatter scanner, updates front-matter consumers to use its structured result, preserves frontMatterRegex, and adds equivalence, fuzz, and performance tests.

Changes

Front-matter scanner

Layer / File(s)	Summary
Scanner contract and implementation packages/mermaid/src/diagram-api/regexes.ts	Adds FrontMatterMatch, scanner helpers, and matchFrontMatter, while retaining the existing frontMatterRegex.
Parser integration packages/mermaid/src/diagram-api/detectType.ts, packages/mermaid/src/diagram-api/frontmatter.ts	Uses scanner results to remove front matter, dedent the YAML body, and slice the remaining text.
Behavior and performance validation packages/mermaid/src/diagram-api/regexes.spec.ts, .changeset/frontmatter-redos.md	Adds regex-equivalence, deterministic fuzz, and linear-scaling tests, plus a patch changeset.

Priority: ➖ Normal

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

Change: Bug fix · Severity of issue fixed: Medium

Sequence Diagram(s)

sequenceDiagram
  participant InputText
  participant matchFrontMatter
  participant detectType
  participant extractFrontMatter
  InputText->>matchFrontMatter: scan text
  matchFrontMatter-->>detectType: indent, body, length
  matchFrontMatter-->>extractFrontMatter: indent, body, length
  detectType->>detectType: slice front matter and strip comments
  extractFrontMatter->>extractFrontMatter: dedent body and slice remaining text

Loading

Suggested reviewers: knsv

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely describes the main change: replacing quadratic front-matter regex usage on hot paths for performance.
Description check	✅ Passed	The description is detailed and covers the issue, approach, design decisions, affected files, compatibility constraints, tests, validation, and changeset. It does not reproduce the template headings o…
Linked Issues check	✅ Passed	PR #8200 requirements are met. matchFrontMatter replaces regex use in detectType and extractFrontMatter, while frontMatterRegex remains byte-for-byte compatible. The scanner preserves indent a…
Out of Scope Changes check	✅ Passed	The changes stay within #8200. The changeset, scanner comments, caller updates, and timing and equivalence tests directly support the ReDoS fix, compatibility, or release documentation. No unrelated p…
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 1 functions across 4 files.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create a new PR

---

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.}

[pkg-pr-new]

Open in StackBlitz

@mermaid-js/examples

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

mermaid

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

@mermaid-js/layout-elk

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

@mermaid-js/layout-tidy-tree

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

@mermaid-js/mermaid-zenuml

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

@mermaid-js/parser

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

@mermaid-js/tiny

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

commit: 139f470

[codecov]

Codecov Report

❌ Patch coverage is 97.10145% with 2 lines in your changes missing coverage. Please review.
✅ Project coverage is 80.74%. Comparing base (386bbca) to head (139f470).

Files with missing lines	Patch %	Lines
packages/mermaid/src/diagram-api/regexes.ts	96.55%	2 Missing ⚠️

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #8203      +/-   ##
===========================================
+ Coverage    80.73%   80.74%   +0.01%     
===========================================
  Files          619      619              
  Lines        84970    85030      +60     
  Branches     18596    16115    -2481     
===========================================
+ Hits         68601    68659      +58     
- Misses       15350    15352       +2     
  Partials      1019     1019              

Flag	Coverage Δ
e2e	73.64% <84.78%> (+<0.01%)	⬆️
unit	78.81% <97.10%> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
packages/mermaid/src/diagram-api/detectType.ts	100.00% <100.00%> (ø)
packages/mermaid/src/diagram-api/frontmatter.ts	100.00% <100.00%> (ø)
packages/mermaid/src/diagram-api/regexes.ts	97.67% <96.55%> (-2.33%)	⬇️

🚀 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.

[argos-ci]

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

Build	Status	Details	Updated (UTC)
default (Inspect)	✅ No changes detected	1 ignored	Sep 19, 2026, 1:44 AM

[MFA-G]

Rebased onto latest develop — the branch was conflicting.

The only conflict was in regexes.spec.ts, and it was the two sides fixing the same flake in different shapes. develop (45b9c9b, 3c21bbf) inlined a min-over-five-trials loop inside stripAnyComments's measure; this branch had extracted a fastestRun helper because the new matchFrontMatter scaling test needs the same treatment.

Resolution keeps the helper and adopts develop's sampling: minimum over 5 trials of the mean of 5 calls, not the minimum of 5 single calls. The single-call variant is the noisier of the two at ~30µs per call. develop's it.each change — dropping the non-discriminating "deep indents" shape — is taken unmodified.

Verified after the merge: regexes.spec.ts + frontmatter.spec.ts pass (22 tests), and regexes.spec.ts passed 5/5 consecutive runs. prettier --check and eslint clean on all four touched files. git diff upstream/develop...HEAD is still only the five files this PR owns.

[pbrolin47]

Hi @MFA-G,
Thanks for this PR.

[sisyphos-bot]

What's Working Well

🎉 [praise] The seeded PRNG for 3000 random equivalence tests is the right design choice for a scanner that must reproduce a regex byte-for-byte. It's deterministic (a failing seed is self-documenting), cheap to run, and reaches inputs
that the hand-written corpus wouldn't think to include. The 24-case hand-written corpus covers the structured cases you reasoned about; the random sweep covers the ones you didn't.

🎉 [praise] The fastestRun refactor (min-over-mean) is a real improvement over the existing stripAnyComments scaling test, and the motivation is exactly right: a single GC pause inflates an average irreversibly but leaves the minimum
clean. The existing test was already using Math.min over trial groups — this completes that reasoning by removing the average within each group.

🎉 [praise] Keeping frontMatterRegex exported and byte-for-byte unchanged with a comment that redirects internal callers to matchFrontMatter is the correct treatment of published surface. It also doubles as the equivalence oracle in
the test, which is elegant.

🎉 [praise] The long docstring above matchFrontMatter explaining why the scanner reproduces backtracking behavior rather than a cleaner semantics — specifically, the opening-swallows-multiple-line-breaks divergence case — is exactly
the kind of comment that prevents a future reader from "simplifying" the code into a bug. That's the comment that earns its existence.

🎉 [praise] The PR description's measurement table (34.6ms / 144.9ms / 581.7ms / 1269.0ms at n=4k/8k/16k/24k → 1.33ms / 1.99ms / 2.78ms / 1.54ms) makes the perf claim concrete and independently checkable. The proof that "two forward
passes, each visiting a character a bounded number of times" because the trailing whitespace runs of two closing fences can't overlap is correct and concise.

---

Correctness Verification (Key Cases)

I traced the algorithm manually through the behavioral divergence case from issue #8200:

'---\n\n---\n\nMORE\n---\n'

• openingEnds = [3, 4] (both \n chars after the opening ---)
• Valid closing fences at: i=4 (the second \n, which sees --- at pos 5) → closingEnd=9; i=14 (the \n after MORE, which sees --- at pos 15) → closingEnd=18
• lastClosingFence = 14
• Largest openingEnd < 14: both 3 and 4 qualify → openingEnd = 4, bodyStart = 5
• First fence from bodyStart: i=14 → returns { indent:'', body:'---\n\nMORE', length:19 }

The whole string is consumed — matching the regex's backtracking result. ✓

CRLF case ('---\r\ntitle: CRLF\r\n---\r\ngraph TD\n'):

• openingEnds = [3, 4] (\r and \n)
• The closing fence check at i=16 (\n after \r at 15): text.startsWith('---', 17) → yes; trailing run ends at i=21 (\n) → closingEnd=21
• openingEnd=4, bodyStart=5, body='title: CRLF\r' ✓

---

Caller Changes

detectType.ts: The swap from text.replace(frontMatterRegex, '') to text.slice(frontMatter.length) is semantically equivalent — frontMatterRegex is ^-anchored with no /g flag, so it only matches once at the start. The length field
covers exactly what the regex would have matched. ✓

frontmatter.ts: match.indent → matches[1], match.body → matches[2], match.length → matches[0].length. All mappings are correct; the dedent logic is unchanged. ✓

---

Security

(XSS sub-agent result pending — incorporating in final verdict below.)

The matchFrontMatter scanner returns slices of the original string — no new content is introduced. match.body flows to yaml.load() with JSON schema restriction, same as before. match.indent is used only for string prefix checks
(line.startsWith(indent)). match.length feeds into .slice(). None of these are new DOM sinks. The sanitization boundary is unchanged — DOMPurify still runs on the final SVG output in mermaidAPI.ts. The PR closes a DoS surface, not a
direct injection vector, and doesn't weaken any existing sanitization.

No XSS or injection issues identified.

---

Tests

The new tests are thorough:

• 24 hand-curated cases covering YAML edge cases (CRLF, tab indent, indented --- inside multiline scalars, divergence from frontMatterRegex is polynomial on whitespace-heavy input (ReDoS, CodeQL js/polynomial-redos) #8200, unterminated blocks, four-dash fences, mismatched indents, empty input)
• 3000 seeded random strings verifying equivalence
• Scaling assertion: 4x input must not produce > 8x time — this catches quadratic growth (16x expected) while tolerating O(n log n) and normal timing noise

The scaling test correctly uses matchFrontMatter(input) as a warm-up call before fastestRun, avoiding JIT compilation cost in the measurement. ✓

---

Minor Notes (Non-blocking)

💡 [suggestion] openingEnds accumulates all line-break positions in the opening's whitespace run, but only the largest one below lastClosingFence is used. For inputs with a very long all-whitespace run after the opening ---, this is an
O(k) allocation where k is the whitespace run length. Since k ≤ input length and the algorithm is already O(n) overall, this isn't a correctness or complexity issue — just noting it in case a future optimization pass targets it.
Alternatively, tracking only the two most recent positions would suffice: previousEnd and currentEnd.

---

Self-Check

• At least one 🎉 [praise] ✓ (five)
• No duplicate findings ✓
• Severity tally: 0 🔴 / 0 🟡 / 0 🟢 / 1 💡 / 5 🎉
• Verdict: APPROVE (no 🔴/🟡 issues) ✓
• Not a draft ✓
• Tone: appreciative ✓

---

Verdict: APPROVE

[mermaid-bot]

@MFA-G, 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.