fix(gantt): warn when an after/until reference or a duration cannot be resolved

[galshir]

📑 Summary

Refs #4121 (this PR makes the two silent failures behind that report visible; the scheduling fallback itself is unchanged, so the issue should stay open)

A gantt milestone written without a duration (M1, :milestone, 2023-01-01, m1) is parsed as a two-field task, so m1 is consumed as the "duration" and the milestone never gets that id. A later after m1 then finds nothing and silently falls back to today's date. Both failures are silent, which is what made the original report hard to diagnose.

This PR keeps the existing fallback behaviour - there are tests that rely on it - and only makes the failures visible:

• after and until now warn about task ids they could not resolve.
• An end value that is neither a valid date nor a valid duration now warns instead of being dropped silently.

Both warnings point at the correct milestone syntax (Milestone :milestone, m1, 2023-01-01, 0d).

📏 Design Decisions

Warnings rather than errors, so no existing diagram changes the way it renders. The unit tests use vi.spyOn(log, 'warn'), following the existing pattern in flow-style.spec.js and gitGraph.spec.ts. No documentation change is needed: the docs already state that invalid duration tokens are ignored and that the task defaults to zero duration.

📋 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: 351d7d2

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	351d7d2
🔍 Latest deploy log	https://app.netlify.com/projects/mermaid-js/deploys/6aa4668bf24f7a00081e41b7
😎 Deploy Preview	https://deploy-preview-8254--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: a8212c87-8018-47b9-add6-abe4323c67b0

📥 Commits

Reviewing files that changed from the base of the PR and between 94ea01f and 351d7d2.

📒 Files selected for processing (3)

• .changeset/gantt-warn-unresolved-task-references.md
• packages/mermaid/src/diagrams/gantt/ganttDb.js
• packages/mermaid/src/diagrams/gantt/ganttDb.spec.ts

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

---

📝 Walkthrough

Walkthrough

Gantt parsing now warns about unknown after and until task IDs. It also warns when an end value is not a valid date or duration. Tests cover warning and non-warning cases, milestone end times, and the patch changeset.

Changes

Gantt validation warnings

Layer / File(s)	Summary
Unresolved task reference warnings packages/mermaid/src/diagrams/gantt/ganttDb.js, packages/mermaid/src/diagrams/gantt/ganttDb.spec.ts	The database filters empty references, evaluates valid tasks, and warns about unknown after or until IDs. Tests cover both warning and valid-reference cases.
Invalid end-value handling packages/mermaid/src/diagrams/gantt/ganttDb.js, packages/mermaid/src/diagrams/gantt/ganttDb.spec.ts, .changeset/gantt-warn-unresolved-task-references.md	Invalid duration or date values now produce warnings before the zero-duration fallback. Tests verify milestone end times, and the changeset declares a patch release.

Priority: ➖ Normal

Estimated code review effort: 2 (Simple) | ~12 minutes

Change: Bug fix · Severity of issue fixed: Medium

Merge Risk: ⚪ Minimal · up to 351d7

The warning behavior is covered without changing the established Gantt scheduling fallbacks, so no merge-blocking risk remains.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Linked Issues check	⚠️ Warning	The change does not implement the behavior required by issue #4121. It adds warnings for unresolved after and until IDs, but getStartDate and getEndDate still use the existing fallback when no…	Implement the milestone/task ID parsing or resolution required by the issue so multiple milestone references resolve to their tasks. Add a regression test that verifies the start dates for tasks using both after m1 and after m2.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Out of Scope Changes check	✅ Passed	The warning logic, Gantt database tests, and changeset support issue #4121. The changes do not introduce an unrelated feature or unrelated code change.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check. Docstring coverage is scoped to functions touched by this diff. Analyzed 0 functions across 2…
Title check	✅ Passed	The title clearly and concisely describes the main change: warnings for unresolved Gantt references and invalid durations.
Description check	✅ Passed	The description is complete and relevant. It explains the issue, implementation decisions, tests, documentation decision, and changeset status. The task checklist is filled out, and the intentional us…

Full details: Linked Issues check

Explanation

The change does not implement the behavior required by issue #4121. It adds warnings for unresolved after and until IDs, but getStartDate and getEndDate still use the existing fallback when no reference resolves. The new tests verify warning messages only. They do not verify that after m1 and after m2 schedule tasks after the correct milestones.

• Fix all pre-merge checks with AI

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

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@8254

mermaid

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

@mermaid-js/layout-elk

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

@mermaid-js/layout-tidy-tree

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

@mermaid-js/mermaid-zenuml

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

@mermaid-js/parser

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

@mermaid-js/tiny

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

commit: 351d7d2

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 78.49%. Comparing base (94ea01f) to head (351d7d2).

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #8254      +/-   ##
===========================================
- Coverage    80.71%   78.49%   -2.23%     
===========================================
  Files          619      619              
  Lines        84920    84956      +36     
  Branches     16074    18512    +2438     
===========================================
- Hits         68547    66687    -1860     
- Misses       15354    17377    +2023     
+ Partials      1019      892     -127     

Flag	Coverage Δ
e2e	64.22% <70.83%> (-9.42%)	⬇️
unit	78.79% <100.00%> (+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/diagrams/gantt/ganttDb.js	85.94% <100.00%> (+1.05%)	⬆️

... and 120 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.

[argos-ci]

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

Build	Status	Details	Updated (UTC)
default (Inspect)	✅ No changes detected	-	Sep 11, 2026, 9:10 PM

[knsv-bot]

[sisyphus-bot]

Thanks for picking this one up, @galshir! Issue #4121 has been sitting open for a long time, and the write-up in the PR description is the clearest diagnosis of it so far. The decision to keep the fallback behaviour and only make the failures visible is exactly the right call for a diagram type that is rendered on millions of existing pages.

I checked out the branch, ran the gantt unit tests (52 pass, 1 pre-existing skip), ESLint and Prettier on the changed files (clean), and ran a few extra probes against the docs' milestone examples, timestamp date formats (x/X), and the exact diagram from the issue. No false-positive warnings on valid input, and the issue's diagram now produces a warning for each root cause.

What's working well

• 🎉 [praise] The duration warning fires on the actual root cause of #4121 (m1 being parsed as a duration), not just on the downstream after m1 symptom. That is the message a user needs to see, and pointing both messages at the correct milestone syntax is a nice touch.
• 🎉 [praise] Filtering empty ids out of ids.split(' ') is a small, correct hardening of the after/until parsing (after a b no longer looks up an empty id). Rendering output and control flow are otherwise unchanged, so there is no visual regression risk.
• 🎉 [praise] Tests cover the positive case, the negative case, and the "no warning when everything resolves" case, and follow the existing vi.spyOn(log, 'warn') pattern. The changeset is a correctly scoped patch with a fix: prefix.

Security

Reviewed for XSS/injection. The warning strings interpolate user-controlled diagram text, but they only reach log.warn (a console.warn.bind(...) with the user text as a trailing argument, so %c/%s are not interpreted), never a DOM sink. No DOMPurify or SVG changes. No issues identified.

Things to consider

• 💡 [suggestion] (pre-existing, optional in this PR) taskDb at ganttDb.js:595 is a module-level const that is never reset in clear(). On a page with more than one gantt chart, an id from an earlier diagram still resolves in a later one, so findTaskById returns whatever task happens to sit at that index in the new rawTasks array and the new "unknown task id" warning stays silent. It also makes the new tests order-dependent within the spec file (they rely on no earlier test having registered m1). Switching it to let taskDb = {} and resetting it in clear() would be a two-line change that makes the warning trustworthy. Happy to see this as a follow-up PR instead if you would rather keep this one focused.
• 🟢 [nit] getTasks() re-runs compileTasks() up to ten times when a task's start cannot be resolved on the first pass, and each pass re-emits every warning. In practice the renderer calls getTasks() once and most diagrams resolve in a single pass, so this is cosmetic. If you want to dedupe, collecting warnings into a Set and flushing them once at the end of getTasks() would do it.

Verdict: approving. Let's get this across the finish line.

[mermaid-bot]

@galshir, 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.