fix 5747 replace $root with mermaid/dist

[bollwyvl]

📑 Summary

• Replaces references to $root with mermaid/dist
• Adds pnpm test:check:tsc which builds the tarballs and uses them in a minimal TypeScript project
• Adds above to CI

Resolves #5747.
Includes #5798 (this would have also failed tsc, as the rendering-utils/types.d.ts would not be present).

📏 Design Decisions

This relies on using a tsconfig.json#/compilerOptions/paths that exactly matches the structure of the as-distributed files, such that downstream packages won't have to add anything to their configuration (e.g. a special case for $root, skipLibCheck, etc). Note this only checks whether the packages can be imported, as adding much of anything else would likely make these baseline, language-level failures harder to debug.

The added script/tsc-check.ts runs out-of-tree, and uses npm to avoid pollution from the build system, and cleans up after itself on the happy path, but leaves the files in place for interactive inspection in the event of a failure.

The parser and zenuml packages are commented out, as they presently fail in this setup, but as I don't use them, I have left this for someone who does to get them under control.

📋 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]

⚠️ No Changeset found

Latest commit: 6a3f1d1

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

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

[netlify]

✅ Deploy Preview for mermaid-js ready!

Name	Link
🔨 Latest commit	6a3f1d1
🔍 Latest deploy log	https://app.netlify.com/sites/mermaid-js/deploys/66ddd8e077421e00084b180c
😎 Deploy Preview	https://deploy-preview-5805--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

Attention: Patch coverage is 0% with 274 lines in your changes missing coverage. Please review.

Project coverage is 4.99%. Comparing base (e5aebf3) to head (6a3f1d1).
Report is 15 commits behind head on develop.

Files with missing lines	Patch %	Lines
scripts/tsc-check.ts	0.00%	175 Missing ⚠️
...aid/src/rendering-util/rendering-elements/edges.js	0.00%	7 Missing ⚠️
.../src/rendering-util/rendering-elements/clusters.js	0.00%	5 Missing ⚠️
...ng-util/rendering-elements/shapes/rectWithTitle.ts	0.00%	5 Missing ⚠️
packages/mermaid/src/rendering-util/render.ts	0.00%	4 Missing ⚠️
...c/rendering-util/rendering-elements/createLabel.js	0.00%	4 Missing ⚠️
...c/rendering-util/rendering-elements/shapes/util.js	0.00%	4 Missing ⚠️
...kages/mermaid/src/diagrams/architecture/svgDraw.ts	0.00%	3 Missing ⚠️
...rc/rendering-util/rendering-elements/edgeMarker.ts	0.00%	3 Missing ⚠️
...rendering-util/rendering-elements/shapes/choice.ts	0.00%	3 Missing ⚠️
... and 32 more

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #5805      +/-   ##
==========================================
- Coverage     5.01%   4.99%   -0.02%     
==========================================
  Files          336     338       +2     
  Lines        48075   48261     +186     
  Branches       575     551      -24     
==========================================
  Hits          2413    2413              
- Misses       45662   45848     +186     

Flag	Coverage Δ
unit	4.99% <0.00%> (-0.02%)	⬇️

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

Files with missing lines	Coverage Δ
...aid/src/diagrams/architecture/architectureIcons.ts	0.00% <0.00%> (ø)
.../src/diagrams/architecture/architectureRenderer.ts	0.00% <0.00%> (ø)
packages/mermaid/src/mermaid.ts	0.00% <0.00%> (ø)
packages/mermaid/src/rendering-util/icons.ts	0.00% <0.00%> (ø)
...rc/rendering-util/layout-algorithms/dagre/index.js	0.00% <0.00%> (ø)
...g-util/layout-algorithms/dagre/mermaid-graphlib.js	0.00% <0.00%> (ø)
...d/src/rendering-util/rendering-elements/markers.js	0.00% <0.00%> (ø)
...dering-util/rendering-elements/shapes/labelRect.ts	0.00% <0.00%> (ø)
...ring-util/rendering-elements/shapes/roundedRect.ts	0.00% <0.00%> (ø)
...ering-util/rendering-elements/shapes/squareRect.ts	0.00% <0.00%> (ø)
... and 32 more

... and 1 file with indirect coverage changes

[argos-ci]

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

Build	Status	Details	Updated (UTC)
default (Inspect)	✅ No changes detected	-	Sep 8, 2024, 5:16 PM

[pkg-pr-new]

Open in Stackblitz

pnpm add https://pkg.pr.new/mermaid-js/mermaid@5805

pnpm add https://pkg.pr.new/mermaid-js/mermaid/@mermaid-js/layout-elk@5805

pnpm add https://pkg.pr.new/mermaid-js/mermaid/@mermaid-js/mermaid-zenuml@5805

pnpm add https://pkg.pr.new/mermaid-js/mermaid/@mermaid-js/parser@5805

commit: 6a3f1d1

[bollwyvl]

howdy folks! (esp. @knsv @sidharthv96) I've seen a couple releases go out, but still have been unable to kick the tires on any new features/fixes due to #5747.

Please consider a review here (or the somewhat smaller #5798), so that downstreams using typescript can more easily start adopting the 11.x line.

[sidharthv96]

Hi @bollwyvl, the mermaid/dist import approach works, but it doesn't feel right. We're discussing whether we should remove the $root imports completely, and use relative imports as before.

We came across https://github.com/Rich-Harris/dts-buddy while checking for alternatives, but it has a very prominent warning to not use it.

[bollwyvl]

Sure, I personally prefer the relative ones, and can prepare an alternate PR. I presumed there was some reason the paths were desirable (not understanding, or being particularly interested in, what e.g. vitepress, etc. is actually doing)

[bollwyvl]

Please see #5838

[bollwyvl]

prominent warning to not use it.

Yep. I've found pretty much anything "fancy," in a TypeScript build just makes a project harder to maintain over time, and much more complicated for downstreams. TS is still likely never going to land as a first-party citizen in the browser, but the ecosystem is big enough on the developer side to try to do it The Most Widely-Compatible Way whenever possible. Put differently: if fancy tool gains are great enough, they may be worth it for a delivered application built by a single organization... but maddening for downstreams when it happens in a library.

For example, adopting "composite": true is widely supported by tools/compilers, doesn't change the delivered .js or .d.ts, and results in a substantial speedup of re-builds, which start to become relevant at a project with the (contributor, file, dependency) count of mermaid, and could be worth considering.