Merge branch 'sidv/esbuild' into sidv/vitest

* sidv/esbuild: (115 commits)
  cleanup
  Fix docs
  Fix coverage
  Fix for issues in errorhandling and class diagrams after refactoring
  Replace GoogleAnalytics with Plausible
  chore(deps): bump dompurify from 2.3.10 to 2.4.0 (#3444)
  chore(deps): bump stylis from 4.1.1 to 4.1.2 (#3439)
  chore(deps-dev): bump webpack-dev-server from 4.10.1 to 4.11.0 (#3450)
  fix(git): support single character branch names
  Cleanup unused variables and some commented out code
  Cleanup fixing som lingering issues
  Remove extension
  Apply suggestions from code review
  chore(deps-dev): bump eslint-plugin-jest from 27.0.1 to 27.0.4 (#3458)
  chore(deps-dev): bump @typescript-eslint/eslint-plugin (#3457)
  chore(deps-dev): bump concurrently from 7.3.0 to 7.4.0 (#3445)
  chore(deps-dev): bump @babel/preset-env from 7.18.10 to 7.19.0 (#3442)
  chore(deps-dev): bump @typescript-eslint/parser from 5.36.1 to 5.37.0 (#3451)
  chore(deps-dev): bump @babel/core from 7.18.13 to 7.19.0 (#3447)
  chore(deps-dev): bump jest-environment-jsdom from 29.0.2 to 29.0.3 (#3441)
  ...

.esbuild/esbuild.cjs

@@ -1,4 +1,4 @@
-const { esmBuild, umdBuild } = require('./util.cjs');
+const { esmBuild, esmCoreBuild, iifeBuild } = require('./util.cjs');
 const { build } = require('esbuild');
 
 const handler = (e) => {
@@ -7,8 +7,14 @@ const handler = (e) => {
 };
 const watch = process.argv.includes('--watch');
 
-build(umdBuild({ minify: false, watch })).catch(handler);
+// mermaid.js
+build(iifeBuild({ minify: false, watch })).catch(handler);
+// mermaid.esm.mjs
 build(esmBuild({ minify: false, watch })).catch(handler);
 
+// mermaid.min.js
 build(esmBuild()).catch(handler);
-build(umdBuild()).catch(handler);
+// mermaid.esm.min.mjs
+build(iifeBuild()).catch(handler);
+// mermaid.core.mjs (node_modules unbundled)
+build(esmCoreBuild()).catch(handler);

.esbuild/serve.cjs

@@ -1,15 +1,15 @@
 const esbuild = require('esbuild');
 const http = require('http');
 const path = require('path');
-const { umdBuild } = require('./util.cjs');
+const { iifeBuild } = require('./util.cjs');
 
 // Start esbuild's server on a random local port
 esbuild
   .serve(
     {
       servedir: path.join(__dirname, '..'),
     },
-    umdBuild({ minify: false })
+    iifeBuild({ minify: false })
   )
   .then((result) => {
     // The result tells us where esbuild's local server is

.esbuild/util.cjs

@@ -1,5 +1,6 @@
 const { Generator } = require('jison');
 const fs = require('fs');
+const { dependencies } = require('../package.json');
 
 /** @typedef {import('esbuild').BuildOptions} Options */
 
@@ -18,33 +19,68 @@ const buildOptions = (override = {}) => {
     tsconfig: 'tsconfig.json',
     resolveExtensions: ['.ts', '.js', '.json', '.jison'],
     external: ['require', 'fs', 'path'],
-    entryPoints: ['src/mermaid.ts'],
-    outfile: 'dist/mermaid.min.js',
+    outdir: 'dist',
     plugins: [jisonPlugin],
     sourcemap: 'external',
     ...override,
   };
 };
 
+const getOutFiles = (extension) => {
+  return {
+    [`mermaid${extension}`]: 'src/mermaid.ts',
+    [`diagramAPI${extension}`]: 'src/diagram-api/diagramAPI.ts',
+  };
+};
 /**
- * @param {Options} override
- * @returns {Options}
+ * Build options for mermaid.esm.* build.
+ *
+ * For ESM browser use.
+ *
+ * @param {Options} override - Override options.
+ * @returns {Options} ESBuild build options.
  */
 exports.esmBuild = (override = { minify: true }) => {
   return buildOptions({
     format: 'esm',
-    outfile: `dist/mermaid.esm${override.minify ? '.min' : ''}.mjs`,
+    entryPoints: getOutFiles(`.esm${override.minify ? '.min' : ''}`),
+    outExtension: { '.js': '.mjs' },
     ...override,
   });
 };
 
 /**
- * @param {Options} override
- * @returns {Options}
+ * Build options for mermaid.core.* build.
+ *
+ * This build does not bundle `./node_modules/`, as it is designed to be used with
+ * Webpack/ESBuild/Vite to use mermaid inside an app/website.
+ *
+ * @param {Options} override - Override options.
+ * @returns {Options} ESBuild build options.
+ */
+exports.esmCoreBuild = (override) => {
+  return buildOptions({
+    format: 'esm',
+    entryPoints: getOutFiles(`.core`),
+    outExtension: { '.js': '.mjs' },
+    external: ['require', 'fs', 'path', ...Object.keys(dependencies)],
+    platform: 'neutral',
+    ...override,
+  });
+};
+
+/**
+ * Build options for mermaid.js build.
+ *
+ * For IIFE browser use (where ESM is not yet supported).
+ *
+ * @param {Options} override - Override options.
+ * @returns {Options} ESBuild build options.
  */
-exports.umdBuild = (override = { minify: true }) => {
+exports.iifeBuild = (override = { minify: true }) => {
   return buildOptions({
-    outfile: `dist/mermaid${override.minify ? '.min' : ''}.js`,
+    entryPoints: getOutFiles(override.minify ? '.min' : ''),
+    format: 'iife',
     ...override,
   });
 };
@@ -55,7 +91,9 @@ const jisonPlugin = {
     build.onLoad({ filter: /\.jison$/ }, async (args) => {
       // Load the file from the file system
       const source = await fs.promises.readFile(args.path, 'utf8');
-      const contents = new Generator(source, { 'token-stack': true }).generate();
+      const contents = new Generator(source, { 'token-stack': true }).generate({
+        moduleMain: '() => {}', // disable moduleMain (default one requires Node.JS modules)
+      });
       return { contents, warnings: [] };
     });
   },

.eslintignore

@@ -1,3 +1,5 @@
 dist/**
 .github/**
 docs/Setup.md
+cypress.config.js
+cypress/plugins/index.js

.eslintrc.json

@@ -15,13 +15,15 @@
   },
   "extends": [
     "eslint:recommended",
+    "plugin:@typescript-eslint/recommended",
     "plugin:jsdoc/recommended",
     "plugin:json/recommended",
     "plugin:markdown/recommended",
     "prettier"
   ],
   "plugins": ["@typescript-eslint", "html", "jest", "jsdoc", "json"],
   "rules": {
+    "no-console": "error",
     "no-prototype-builtins": "off",
     "no-unused-vars": "off",
     "jsdoc/check-indentation": "off",
@@ -35,6 +37,16 @@
     "jsdoc/require-returns": "off",
     "jsdoc/require-returns-description": "off",
     "cypress/no-async-tests": "off",
+    "@typescript-eslint/ban-ts-comment": [
+      "error",
+      {
+        "ts-expect-error": "allow-with-description",
+        "ts-ignore": "allow-with-description",
+        "ts-nocheck": "allow-with-description",
+        "ts-check": "allow-with-description",
+        "minimumDescriptionLength": 10
+      }
+    ],
     "json/*": ["error", "allowComments"],
     "no-empty": ["error", { "allowEmptyCatch": true }]
   },
@@ -45,6 +57,19 @@
         "no-undef": "off",
         "jsdoc/require-jsdoc": "off"
       }
+    },
+    {
+      "files": ["./cypress/**", "./demos/**"],
+      "rules": {
+        "no-console": "off"
+      }
+    },
+    {
+      "files": ["./**/*.spec.{ts,js}", "./cypress/**", "./demos/**", "./**/docs/**"],
+      "rules": {
+        "jsdoc/require-jsdoc": "off",
+        "@typescript-eslint/no-unused-vars": "off"
+      }
     }
   ]
 }

.github/workflows/checks.yml

@@ -14,7 +14,7 @@ jobs:
     name: check tests
     if: github.repository_owner == 'mermaid-js'
     steps:
-      - uses: actions/checkout@v2
+      - uses: actions/checkout@v3
         with:
           fetch-depth: 0
       - uses: testomatio/check-tests@stable

.github/workflows/e2e

@@ -36,3 +36,9 @@ jobs:
       run: yarn e2e
       env:
         CYPRESS_CACHE_FOLDER: .cache/Cypress
+
+    - name: Upload Coverage to Coveralls
+        uses: coverallsapp/github-action@master
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          flag-name: e2e

.github/workflows/lint.yml

@@ -40,3 +40,18 @@ jobs:
 
       - name: Verify Docs
         run: yarn docs:verify
+
+      - name: Check no `console.log()` in .jison files
+        # ESLint can't parse .jison files directly
+        # In the future, it might be worth making a `eslint-plugin-jison`, so
+        # that this will be built into the `yarn lint` command.
+        run: |
+          shopt -s globstar
+          mkdir -p tmp/
+          for jison_file in src/**/*.jison; do
+            outfile="tmp/$(basename -- "$jison_file" .jison)-jison.js"
+            echo "Converting $jison_file to $outfile"
+            # default module-type (CJS) always adds a console.log()
+            yarn jison "$jison_file" --outfile "$outfile" --module-type "amd"
+          done
+          yarn eslint --no-eslintrc --rule no-console:error --parser "@babel/eslint-parser" "./tmp/*-jison.js"

.github/workflows/test.yml

@@ -32,3 +32,12 @@ jobs:
       - name: Run Unit Tests
         run: |
           yarn ci --coverage
+
+      - name: Upload Coverage to Coveralls
+        # it feels a bit weird to use @master, but that's what the docs use
+        # (coveralls also doesn't publish a @v1 we can use)
+        # https://github.com/marketplace/actions/coveralls-github-action
+        uses: coverallsapp/github-action@master
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          flag-name: unit

.lintstagedrc.json

@@ -1,4 +1,5 @@
 {
   "src/docs/**": ["yarn docs:build --git"],
-  "*.{ts,js,json,html,md}": ["eslint --fix", "prettier --write"]
+  "src/docs.mts": ["yarn docs:build --git"],
+  "*.{ts,js,json,html,md,mts}": ["eslint --fix", "prettier --write"]
 }

.webpack/webpack.config.babel.js

@@ -3,43 +3,44 @@ import nodeExternals from 'webpack-node-externals';
 import baseConfig from './webpack.config.base';
 
 export default (_env, args) => {
-  switch (args.mode) {
-    case 'development':
-      return [
-        baseConfig,
-        merge(baseConfig, {
-          externals: [nodeExternals()],
-          output: {
-            filename: '[name].core.js',
-          },
-        }),
-      ];
-    case 'production':
-      return [
-        // umd
-        merge(baseConfig, {
-          output: {
-            filename: '[name].min.js',
-          },
-        }),
-        // esm
-        mergeWithCustomize({
-          customizeObject: customizeObject({
-            'output.library': 'replace',
-          }),
-        })(baseConfig, {
-          experiments: {
-            outputModule: true,
-          },
-          output: {
-            library: {
-              type: 'module',
-            },
-            filename: '[name].esm.min.mjs',
-          },
-        }),
-      ];
-    default:
-      throw new Error('No matching configuration was found!');
-  }
+  return [
+    // non-minified
+    merge(baseConfig, {
+      optimization: {
+        minimize: false,
+      },
+    }),
+    // core [To be used by webpack/esbuild/vite etc to bundle mermaid]
+    merge(baseConfig, {
+      externals: [nodeExternals()],
+      output: {
+        filename: '[name].core.js',
+      },
+      optimization: {
+        minimize: false,
+      },
+    }),
+    // umd
+    merge(baseConfig, {
+      output: {
+        filename: '[name].min.js',
+      },
+    }),
+    // esm
+    mergeWithCustomize({
+      customizeObject: customizeObject({
+        'output.library': 'replace',
+      }),
+    })(baseConfig, {
+      experiments: {
+        outputModule: true,
+      },
+      output: {
+        library: {
+          type: 'module',
+        },
+        filename: '[name].esm.min.mjs',
+      },
+    }),
+  ];
 };

CONTRIBUTING.md

@@ -20,8 +20,8 @@ yarn test
 We make all changes via pull requests. As we have many pull requests from developers new to mermaid, the current approach is to have _knsv, Knut Sveidqvist_ as a main reviewer of changes and merging pull requests. More precisely like this:
 
 - Large changes reviewed by knsv or other developer asked to review by knsv
-- Smaller low-risk changes like dependencies, documentation etc can be merged by active collaborators
-- documentation (updates to the docs folder is also allowed via direct commits)
+- Smaller low-risk changes like dependencies, documentation, etc. can be merged by active collaborators
+- Documentation (updates to the `src/docs` folder is also allowed via direct commits)
 
 To commit code, create a branch, let it start with the type like feature or bug followed by the issue number for reference and some describing text.
 
@@ -37,12 +37,28 @@ Another:
 
 Less strict here, it is OK to commit directly in the `develop` branch if you are a collaborator.
 
-The documentation is located in the `docs` directory and published using GitHub Pages.
-The documentation site is powered by [Docsify](https://docsify.js.org), a simple documentation site generator.
+The documentation is written in **Markdown**. For more information about Markdown [see the GitHub Markdown help page](https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax).
 
-The documentation is written in Markdown, for more information about Markdown [see the GitHub Markdown help page](https://help.github.com/en/github/writing-on-github/basic-writing-and-formatting-syntax).
+### Documentation source files are in /src/docs
 
-If you want to preview the documentation site on your machine, you need to install `docsify-cli`:
+The source files for the project documentation are located in the `/src/docs` directory. This is where you should make changes.
+The files under `/src/docs` are processed to generate the published documentation, and the resulting files are put into the `/docs` directory.
+
+```mermaid
+flowchart LR
+  classDef default fill:#fff,color:black,stroke:black
+
+  source["files in /src/docs\n(changes should be done here)"] -- automatic processing\nto generate the final documentation--> published["files in /docs\ndisplayed on the official documentation site"]
+
+```
+
+**_DO NOT CHANGE FILES IN `/docs`_**
+
+### The official documentation site
+
+**[The mermaid documentation site](https://mermaid-js.github.io/mermaid/) is powered by [Docsify](https://docsify.js.org), a simple documentation site generator.**
+
+If you want to preview the whole documentation site on your machine, you need to install `docsify-cli`:
 
 ```sh
 $ npm i docsify-cli -g
@@ -121,9 +137,13 @@ it('should render forks and joins', () => {
 
 Finally, if it is not in the documentation, no one will know about it and then **no one will use it**. Wouldn't that be sad? With all the effort that was put into the feature?
 
-The docs are located in the docs folder and are ofc written in markdown. Just pick the right section and start typing. If you want to add to the structure as in adding a new section and new file you do that via the \_navbar.md.
+The source files for documentation are in `/src/docs` and are written in markdown. Just pick the right section and start typing. See the [Committing Documentation](#committing-documentation) section for more about how the documentation is generated.
+
+#### Adding to or changing the documentation organization
+
+If you want to add a new section or change the organization (structure), then you need to make sure to **change the side navigation** in `src/docs/_sidebar.md`.
 
-The changes in master is reflected in https://mermaid-js.github.io/mermaid/ once released the updates are committed to https://mermaid-js.github.io/#/
+When changes are committed and then released, they become part of the `master` branch and become part of the published documentation on https://mermaid-js.github.io/mermaid/
 
 ## Last words