Fix macOS onboarding issues

[thedustin]

📑 Summary

Hey folks, I would like to contribute to mermaid, so I started by going through the "Mermaid Contributing Guide", and made my dev environment ready.

While setting up my dev environment via docker (on macOS, so using colima) I encountered some issues, which I would like to solve with this pull request.

My setup: macOS (14.3); Colima: stable 0.6.7 (HEAD-a18cb38); Lima: 0.20.0

Sadly, I was not able to make the cypress tests work via docker and xquartz (macOS X11 server).

📏 Design Decisions

Explanation of the different issues I faced, and how I fixed them.

./run Executable Had "ugly" Output

Started the setup by using the ./run executable, but the output produced was not colorful/bold for me. A look into the file showed me, that there was a shebang present that pointed to a fixed bash executable.

A simple fix was to replace the shebang line #!/bin/bash with #!/usr/bin/env bash to use env to start the proper bash executable.

./run Without Any Arguments (or Unsupported Argument) Fails

Running ./run without any arguments fails ugly like this:

$ ./run
./run: line 102: run: command not found

1. $name is not callable, this would expect the ./run executable to be in $PATH. I replaced it with $0, the name/path of the file, to make it callable.
2. I added the case "" (empty command) to the help command, to fallback to the help command when there is no command given.
3. Given an unsupported command will now print a message to stderr, call the help block, and exits the script with the code 1.

Pnpm via ./run Failed with ERR_PNPM_LINKING_FAILED Errors

Just running this script failed for me. It slowly progressed further with each execution, but was not even close to finish after 3 executions.

Output of `./run pnpm install`

/Volumes/Projects/ext/mermaid-thedustin develop*
❯ ./run pnpm install

[+] Creating 4/0
 ✔ Network mermaid-thedustin_default      Created                                                                                                                                 0.0s 
 ✔ Volume "mermaid-thedustin_root_npm"    Created                                                                                                                                 0.0s 
 ✔ Volume "mermaid-thedustin_root_cache"  Created                                                                                                                                 0.0s 
 ✔ Volume "mermaid-thedustin_root_local"  Created                                                                                                                                 0.0s 
[+] Building 19.1s (7/7) 
[*snip* docker build output]

Scope: all 6 workspace projects
Lockfile is up to date, resolution step is skipped
Packages: +2025
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Downloading registry.npmjs.org/typescript/5.0.4: 7.05 MB/7.05 MB, done
 ERR_PNPM_LINKING_FAILED  Error: ENOENT: no such file or directory, copyfile '/mermaid/.pnpm-store/v3/files/cf/83e1357eefb8bdf1542850d66d8007d620e4050b5715dc83f4a921d36ce9ce47d0d13c5d85f2b0ff8318d2877eec2f63b931bd47417a81a538327af927da3e' -> '/mermaid/node_modules/.pnpm/resolve@1.22.4/node_modules/resolve_tmp_1/test/shadowed_core/node_modules/util/index.js'
Progress: resolved 2025, reused 0, downloaded 173, added 164

/Volumes/Projects/ext/mermaid-thedustin develop 36s
❯ ./run pnpm install
Scope: all 6 workspace projects
Lockfile is up to date, resolution step is skipped
Packages: +2025
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
Downloading registry.npmjs.org/typescript/5.1.6: 7.15 MB/7.15 MB, done
 ERR_PNPM_LINKING_FAILED  Error: ENOENT: no such file or directory, copyfile '/mermaid/.pnpm-store/v3/files/4e/e1c88f8c3f4e4cd34cb6c00339bf9d6d036ff4ade3af49e871cc8966b84c729d8b75492acc6413c9a664ac00a57958223ac13c4229da8c62ebe6a53e4f783f' -> '/mermaid/node_modules/.pnpm/@vue+devtools-api@6.5.1/node_modules/@vue/devtools-api_tmp_1/lib/esm/api/context.js'
Progress: resolved 2025, reused 174, downloaded 98, added 95

/Volumes/Projects/ext/mermaid-thedustin develop 9s
❯ ./run pnpm install
Scope: all 6 workspace projects
Lockfile is up to date, resolution step is skipped
Packages: +2025
+++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 ERR_PNPM_LINKING_FAILED  Error: ENOENT: no such file or directory, copyfile '/mermaid/.pnpm-store/v3/files/1d/0688424f69c0e7322aeb720e4e28d9af3b5a7a2dc18b8b198156e377a61a6e05bc824528fca0f8e61ac39b137a028029ff82e5229ad400a3cc22e2bdb687ad-exec' -> '/mermaid/node_modules/.pnpm/@types+d3-interpolate@3.0.1/node_modules/@types/d3-interpolate_tmp_1/LICENSE'
Progress: resolved 2025, reused 273, downloaded 115, added 122

I have no experience with pnpm, so I searched, and found an issue discussing it: pnpm/pnpm#7024. Answers in the issue recommended to use package-import-method=clone-or-copy, which solved at least for me the issue, and should be fine to use in a docker environment.

./run test Failed on linting step

Running the tests failed for me:

Output of `./run pnpm test`

/Volumes/Projects/ext/mermaid-thedustin develop*
❯ ./run pnpm test
[*snip* the other steps were fine]

> mermaid-monorepo@10.2.4 lint:jison /mermaid
> tsx ./scripts/jison/lint.mts

Linting ./packages/mermaid-example-diagram/src/parser/exampleDiagram.jison
Linting ./packages/mermaid/src/diagrams/block/parser/block.jison
Linting ./packages/mermaid/src/diagrams/c4/parser/c4Diagram.jison
Linting ./packages/mermaid/src/diagrams/er/parser/erDiagram.jison
Linting ./packages/mermaid/src/diagrams/class/parser/classDiagram.jison
Linting ./packages/mermaid/src/diagrams/flowchart/parser/flow.jison
Linting ./packages/mermaid/src/diagrams/gantt/parser/gantt.jison
Linting ./packages/mermaid/src/diagrams/info/parser/info.jison
Linting ./packages/mermaid/src/diagrams/git/parser/gitGraph.jison
Linting ./packages/mermaid/src/diagrams/mindmap/parser/mindmap.jison
Linting ./packages/mermaid/src/diagrams/quadrant-chart/parser/quadrant.jison
Linting ./packages/mermaid/src/diagrams/pie/parser/pie.jison
Linting ./packages/mermaid/src/diagrams/sankey/parser/sankey.jison
Linting ./packages/mermaid/src/diagrams/sequence/parser/sequenceDiagram.jison
Linting ./packages/mermaid/src/diagrams/requirement/parser/requirementDiagram.jison
Linting ./packages/mermaid/src/diagrams/state/parser/stateDiagram.jison
Linting ./packages/mermaid/src/diagrams/user-journey/parser/journey.jison
Linting ./packages/mermaid/src/diagrams/timeline/parser/timeline.jison
Linting ./packages/mermaid/src/diagrams/xychart/parser/xychart.jison
Checking formatting...
[warn] .pnpm-store/v3/files/00/0dd3563fb40368ae2284245842bfb6a16306ada3fba3cee98d3325cbf32c016110520edc72f4be5b3d8562e77196c001b2b499aafba19e15d3bf48fea3ccc6-index.json
[*snip* more than 2000 lines like this]
[warn] .pnpm-store/v3/files/ff/ff3c985592271f25c42cf07400014c92f6332581d76f9e218ecc0cbd92a8b98091e294f6ac51bd6b92c938e6dc5526a4110cb857dc90022a11a546503c5beb-index.json
[warn] Code style issues found in 2021 files. Forgot to run Prettier?
 ELIFECYCLE  Command failed with exit code 1.
 ELIFECYCLE  Test failed. See above for more details.

As you can see, the linting command failed, as it tried to lint the files in .pnpm-store/.

After digging in the pnpm script, I noticed that this is not thrown by the "jison" linting as I first thought, but by the prettifier linting (see the "Checking formatting" message).

Adding the .pnpm-store file to the respecting ignore file fixed the issue for me.

📋 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.
• 🔖 targeted develop branch

[netlify]

✅ Deploy Preview for mermaid-js ready!

Name	Link
🔨 Latest commit	337f07b
🔍 Latest deploy log	https://app.netlify.com/sites/mermaid-js/deploys/65bfd244ca8c1b00084f73b0
😎 Deploy Preview	https://deploy-preview-5262--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 site configuration.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (b043d79) 73.73% compared to head (337f07b) 79.51%.

Additional details and impacted files

@@             Coverage Diff             @@
##           develop    #5262      +/-   ##
===========================================
+ Coverage    73.73%   79.51%   +5.78%     
===========================================
  Files          164      175      +11     
  Lines        13864    14396     +532     
  Branches       741      855     +114     
===========================================
+ Hits         10222    11447    +1225     
+ Misses        3467     2755     -712     
- Partials       175      194      +19     

Flag	Coverage Δ
e2e	85.09% <ø> (+6.93%)	⬆️
unit	43.22% <ø> (ø)

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

see 43 files with indirect coverage changes

[mermaid-bot]

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