Merge pull request #5924 from mermaid-js/sidv/autoGenerateShapeDocs

Auto generate shape docs
mermaid-js · Oct 9, 2024 · 2b86750 · 2b86750
2 parents 2506c29 + b452247
commit 2b86750
Show file tree

Hide file tree

Showing 9 changed files with 223 additions and 107 deletions.
diff --git a/.build/common.ts b/.build/common.ts
@@ -1,3 +1,9 @@
+export interface PackageOptions {
+  name: string;
+  packageName: string;
+  file: string;
+}
+
 /**
  * Shared common options for both ESBuild and Vite
  */
@@ -27,4 +33,4 @@ export const packageOptions = {
     packageName: 'mermaid-layout-elk',
     file: 'layouts.ts',
   },
-} as const;
+} as const satisfies Record<string, PackageOptions>;
diff --git a/.esbuild/build.ts b/.esbuild/build.ts
@@ -8,7 +8,10 @@ import { defaultOptions, getBuildConfig } from './util.js';
 const shouldVisualize = process.argv.includes('--visualize');
 
 const buildPackage = async (entryName: keyof typeof packageOptions) => {
-  const commonOptions: MermaidBuildOptions = { ...defaultOptions, entryName } as const;
+  const commonOptions: MermaidBuildOptions = {
+    ...defaultOptions,
+    options: packageOptions[entryName],
+  } as const;
   const buildConfigs: MermaidBuildOptions[] = [
     // package.mjs
     { ...commonOptions },
@@ -40,7 +43,7 @@ const buildPackage = async (entryName: keyof typeof packageOptions) => {
         continue;
       }
       const fileName = Object.keys(metafile.outputs)
-        .find((file) => !file.includes('chunks') && file.endsWith('js'))
+        .find((file) => !file.includes('chunks') && file.endsWith('js'))!
         .replace('dist/', '');
       // Upload metafile into https://esbuild.github.io/analyze/
       await writeFile(`stats/${fileName}.meta.json`, JSON.stringify(metafile));

diff --git a/.esbuild/util.ts b/.esbuild/util.ts
@@ -3,7 +3,7 @@ import { fileURLToPath } from 'url';
 import type { BuildOptions } from 'esbuild';
 import { readFileSync } from 'fs';
 import jsonSchemaPlugin from './jsonSchemaPlugin.js';
-import { packageOptions } from '../.build/common.js';
+import type { PackageOptions } from '../.build/common.js';
 import { jisonPlugin } from './jisonPlugin.js';
 
 const __dirname = fileURLToPath(new URL('.', import.meta.url));
@@ -13,10 +13,10 @@ export interface MermaidBuildOptions extends BuildOptions {
   core: boolean;
   metafile: boolean;
   format: 'esm' | 'iife';
-  entryName: keyof typeof packageOptions;
+  options: PackageOptions;
 }
 
-export const defaultOptions: Omit<MermaidBuildOptions, 'entryName'> = {
+export const defaultOptions: Omit<MermaidBuildOptions, 'entryName' | 'options'> = {
   minify: false,
   metafile: false,
   core: false,
@@ -52,9 +52,14 @@ const getFileName = (fileName: string, { core, format, minify }: MermaidBuildOpt
 };
 
 export const getBuildConfig = (options: MermaidBuildOptions): BuildOptions => {
-  const { core, entryName, metafile, format, minify } = options;
+  const {
+    core,
+    metafile,
+    format,
+    minify,
+    options: { name, file, packageName },
+  } = options;
   const external: string[] = ['require', 'fs', 'path'];
-  const { name, file, packageName } = packageOptions[entryName];
   const outFileName = getFileName(name, options);
   const output: BuildOptions = buildOptions({
     absWorkingDir: resolve(__dirname, `../packages/${packageName}`),

diff --git a/docs/syntax/flowchart.md b/docs/syntax/flowchart.md
diff --git a/packages/mermaid/package.json b/packages/mermaid/package.json
@@ -35,8 +35,8 @@
     "clean": "rimraf dist",
     "dev": "pnpm -w dev",
     "docs:code": "typedoc src/defaultConfig.ts src/config.ts src/mermaid.ts && prettier --write ./src/docs/config/setup",
-    "docs:build": "rimraf ../../docs && pnpm docs:spellcheck && pnpm docs:code && tsx scripts/docs.cli.mts",
-    "docs:verify": "pnpm docs:spellcheck && pnpm docs:code && tsx scripts/docs.cli.mts --verify",
+    "docs:build": "rimraf ../../docs && pnpm docs:code && pnpm docs:spellcheck && tsx scripts/docs.cli.mts",
+    "docs:verify": "pnpm docs:code && pnpm docs:spellcheck && tsx scripts/docs.cli.mts --verify",
     "docs:pre:vitepress": "pnpm --filter ./src/docs prefetch && rimraf src/vitepress && pnpm docs:code && tsx scripts/docs.cli.mts --vitepress && pnpm --filter ./src/vitepress install --no-frozen-lockfile --ignore-scripts",
     "docs:build:vitepress": "pnpm docs:pre:vitepress && (cd src/vitepress && pnpm run build) && cpy --flat src/docs/landing/ ./src/vitepress/.vitepress/dist/landing",
     "docs:dev": "pnpm docs:pre:vitepress && concurrently \"pnpm --filter ./src/vitepress dev\" \"tsx scripts/docs.cli.mts --watch --vitepress\"",

diff --git a/packages/mermaid/scripts/docs.mts b/packages/mermaid/scripts/docs.mts
@@ -41,7 +41,8 @@ import { exec } from 'child_process';
 import { globby } from 'globby';
 import { JSDOM } from 'jsdom';
 import { dump, load, JSON_SCHEMA } from 'js-yaml';
-import type { Code, ListItem, Root, Text, YAML } from 'mdast';
+import type { Code, ListItem, PhrasingContent, Root, Text, YAML } from 'mdast';
+import { register } from 'node:module';
 import { posix, dirname, relative, join } from 'path';
 import prettier from 'prettier';
 import { remark } from 'remark';
@@ -53,6 +54,10 @@ import mm from 'micromatch';
 import flatmap from 'unist-util-flatmap';
 import { visit } from 'unist-util-visit';
 
+// short-circuit `.schema.yaml` imports, so that we can safely import `shapes.js`
+register('./loadHook.mjs', import.meta.url);
+const { shapesDefs } = await import('../src/rendering-util/rendering-elements/shapes.js');
+
 export const MERMAID_RELEASE_VERSION = JSON.parse(readFileSync('../mermaid/package.json', 'utf8'))
   .version as string;
 const MERMAID_MAJOR_VERSION = MERMAID_RELEASE_VERSION.split('.')[0];
@@ -103,6 +108,60 @@ const generateHeader = (file: string): string => {
 > ## Please edit the corresponding file in [${filePathFromRoot}](${sourcePathRelativeToGenerated}).`;
 };
 
+/**
+ * Builds a markdown list of shapes supported in flowcharts.
+ */
+export function buildShapeDoc() {
+  const data = shapesDefs
+    .sort((a, b) => a.semanticName.localeCompare(b.semanticName))
+    .map((shape): PhrasingContent[][] => {
+      const { name, semanticName, description, shortName, aliases = [] } = shape;
+      return [
+        [{ type: 'text', value: semanticName }],
+        [{ type: 'text', value: name }],
+        [{ type: 'inlineCode', value: shortName }],
+        [{ type: 'text', value: description }],
+        aliases.sort().flatMap((alias, index) => [
+          ...(index !== 0 ? ([{ type: 'text', value: ', ' }] as const) : []),
+          {
+            type: 'inlineCode',
+            value: alias,
+          },
+        ]),
+      ];
+    });
+
+  // don't prettify this table, since we'd do it later
+  return remark()
+    .use(remarkGfm)
+    .stringify({
+      type: 'root',
+      children: [
+        {
+          type: 'table',
+          children: [
+            ['Semantic Name', 'Shape Name', 'Short Name', 'Description', 'Alias Supported'].map(
+              (s): PhrasingContent[] => [
+                {
+                  type: 'strong',
+                  children: [{ type: 'text', value: s }],
+                },
+              ]
+            ),
+            ...data,
+          ].map((row) => ({
+            type: 'tableRow',
+            children: row.map((cell) => ({
+              type: 'tableCell',
+              children: cell,
+            })),
+          })),
+        },
+      ],
+    })
+    .toString();
+}
+
 /**
  * Given a source file name and path, return the documentation destination full path and file name
  * Create the destination path if it does not already exist.
@@ -192,10 +251,22 @@ export const transformToBlockQuote = (
 const injectPlaceholders = (text: string): string =>
   text.replace(/<MERMAID_VERSION>/g, MERMAID_MAJOR_VERSION).replace(/<CDN_URL>/g, CDN_URL);
 
+const virtualGenerators: Record<string, () => string> = {
+  shapesTable: buildShapeDoc,
+};
+
 const transformIncludeStatements = (file: string, text: string): string => {
   // resolve includes - src https://github.com/vuejs/vitepress/blob/428eec3750d6b5648a77ac52d88128df0554d4d1/src/node/markdownToVue.ts#L65-L76
-  return text.replace(includesRE, (m, m1) => {
+  return text.replace(includesRE, (m, m1: string) => {
     try {
+      if (m1.startsWith('virtual:')) {
+        const key = m1.replace('virtual:', '');
+        const generator = virtualGenerators[key];
+        if (!generator) {
+          throw new Error(`Unknown virtual generator: ${key} in "${file}"`);
+        }
+        return generator();
+      }
       const includePath = join(dirname(file), m1).replaceAll('\\', '/');
       const content = readSyncedUTF8file(includePath);
       includedFiles.add(changeToFinalDocDir(includePath));

diff --git a/packages/mermaid/scripts/docs.spec.ts b/packages/mermaid/scripts/docs.spec.ts
@@ -1,4 +1,4 @@
-import { transformMarkdownAst, transformToBlockQuote } from './docs.mjs';
+import { buildShapeDoc, transformMarkdownAst, transformToBlockQuote } from './docs.mjs';
 
 import { remark } from 'remark'; // import it this way so we can mock it
 import remarkFrontmatter from 'remark-frontmatter';
@@ -165,4 +165,59 @@ This Markdown should be kept.
       });
     });
   });
+
+  describe('buildShapeDoc', () => {
+    it('should build shapesTable based on the shapeDefs', () => {
+      expect(buildShapeDoc()).toMatchInlineSnapshot(`
+        "| **Semantic Name**                 | **Shape Name**         | **Short Name** | **Description**                | **Alias Supported**                                              |
+        | --------------------------------- | ---------------------- | -------------- | ------------------------------ | ---------------------------------------------------------------- |
+        | Card                              | Notched Rectangle      | \`notch-rect\`   | Represents a card              | \`card\`, \`notched-rectangle\`                                      |
+        | Collate                           | Hourglass              | \`hourglass\`    | Represents a collate operation | \`collate\`, \`hourglass\`                                           |
+        | Com Link                          | Lightning Bolt         | \`bolt\`         | Communication link             | \`com-link\`, \`lightning-bolt\`                                     |
+        | Comment                           | Curly Brace            | \`brace\`        | Adds a comment                 | \`brace-l\`, \`comment\`                                             |
+        | Comment Right                     | Curly Brace            | \`brace-r\`      | Adds a comment                 |                                                                  |
+        | Comment with braces on both sides | Curly Braces           | \`braces\`       | Adds a comment                 |                                                                  |
+        | Data Input/Output                 | Lean Right             | \`lean-r\`       | Represents input or output     | \`in-out\`, \`lean-right\`                                           |
+        | Data Input/Output                 | Lean Left              | \`lean-l\`       | Represents output or input     | \`lean-left\`, \`out-in\`                                            |
+        | Database                          | Cylinder               | \`cyl\`          | Database storage               | \`cylinder\`, \`database\`, \`db\`                                     |
+        | Decision                          | Diamond                | \`diam\`         | Decision-making step           | \`decision\`, \`diamond\`, \`question\`                                |
+        | Delay                             | Half-Rounded Rectangle | \`delay\`        | Represents a delay             | \`half-rounded-rectangle\`                                         |
+        | Direct Access Storage             | Horizontal Cylinder    | \`h-cyl\`        | Direct access storage          | \`das\`, \`horizontal-cylinder\`                                     |
+        | Disk Storage                      | Lined Cylinder         | \`lin-cyl\`      | Disk storage                   | \`disk\`, \`lined-cylinder\`                                         |
+        | Display                           | Curved Trapezoid       | \`curv-trap\`    | Represents a display           | \`curved-trapezoid\`, \`display\`                                    |
+        | Divided Process                   | Divided Rectangle      | \`div-rect\`     | Divided process shape          | \`div-proc\`, \`divided-process\`, \`divided-rectangle\`               |
+        | Document                          | Document               | \`doc\`          | Represents a document          | \`doc\`, \`document\`                                                |
+        | Event                             | Rounded Rectangle      | \`rounded\`      | Represents an event            | \`event\`                                                          |
+        | Extract                           | Triangle               | \`tri\`          | Extraction process             | \`extract\`, \`triangle\`                                            |
+        | Fork/Join                         | Filled Rectangle       | \`fork\`         | Fork or join in process flow   | \`join\`                                                           |
+        | Internal Storage                  | Window Pane            | \`win-pane\`     | Internal storage               | \`internal-storage\`, \`window-pane\`                                |
+        | Junction                          | Filled Circle          | \`f-circ\`       | Junction point                 | \`filled-circle\`, \`junction\`                                      |
+        | Lined Document                    | Lined Document         | \`lin-doc\`      | Lined document                 | \`lined-document\`                                                 |
+        | Lined/Shaded Process              | Lined Rectangle        | \`lin-rect\`     | Lined process shape            | \`lin-proc\`, \`lined-process\`, \`lined-rectangle\`, \`shaded-process\` |
+        | Loop Limit                        | Trapezoidal Pentagon   | \`notch-pent\`   | Loop limit step                | \`loop-limit\`, \`notched-pentagon\`                                 |
+        | Manual File                       | Flipped Triangle       | \`flip-tri\`     | Manual file operation          | \`flipped-triangle\`, \`manual-file\`                                |
+        | Manual Input                      | Sloped Rectangle       | \`sl-rect\`      | Manual input step              | \`manual-input\`, \`sloped-rectangle\`                               |
+        | Manual Operation                  | Trapezoid Base Top     | \`trap-t\`       | Represents a manual task       | \`inv-trapezoid\`, \`manual\`, \`trapezoid-top\`                       |
+        | Multi-Document                    | Stacked Document       | \`docs\`         | Multiple documents             | \`documents\`, \`st-doc\`, \`stacked-document\`                        |
+        | Multi-Process                     | Stacked Rectangle      | \`st-rect\`      | Multiple processes             | \`processes\`, \`procs\`, \`stacked-rectangle\`                        |
+        | Odd                               | Odd                    | \`odd\`          | Odd shape                      |                                                                  |
+        | Paper Tape                        | Flag                   | \`flag\`         | Paper tape                     | \`paper-tape\`                                                     |
+        | Prepare Conditional               | Hexagon                | \`hex\`          | Preparation or condition step  | \`hexagon\`, \`prepare\`                                             |
+        | Priority Action                   | Trapezoid Base Bottom  | \`trap-b\`       | Priority action                | \`priority\`, \`trapezoid\`, \`trapezoid-bottom\`                      |
+        | Process                           | Rectangle              | \`rect\`         | Standard process shape         | \`proc\`, \`process\`, \`rectangle\`                                   |
+        | Start                             | Circle                 | \`circle\`       | Starting point                 | \`circ\`                                                           |
+        | Start                             | Small Circle           | \`sm-circ\`      | Small starting point           | \`small-circle\`, \`start\`                                          |
+        | Stop                              | Double Circle          | \`dbl-circ\`     | Represents a stop point        | \`double-circle\`                                                  |
+        | Stop                              | Framed Circle          | \`fr-circ\`      | Stop point                     | \`framed-circle\`, \`stop\`                                          |
+        | Stored Data                       | Bow Tie Rectangle      | \`bow-rect\`     | Stored data                    | \`bow-tie-rectangle\`, \`stored-data\`                               |
+        | Subprocess                        | Framed Rectangle       | \`fr-rect\`      | Subprocess                     | \`framed-rectangle\`, \`subproc\`, \`subprocess\`, \`subroutine\`        |
+        | Summary                           | Crossed Circle         | \`cross-circ\`   | Summary                        | \`crossed-circle\`, \`summary\`                                      |
+        | Tagged Document                   | Tagged Document        | \`tag-doc\`      | Tagged document                | \`tag-doc\`, \`tagged-document\`                                     |
+        | Tagged Process                    | Tagged Rectangle       | \`tag-rect\`     | Tagged process                 | \`tag-proc\`, \`tagged-process\`, \`tagged-rectangle\`                 |
+        | Terminal Point                    | Stadium                | \`stadium\`      | Terminal point                 | \`pill\`, \`terminal\`                                               |
+        | Text Block                        | Text Block             | \`text\`         | Text block                     |                                                                  |
+        "
+      `);
+    });
+  });
 });
diff --git a/packages/mermaid/scripts/loadHook.mjs b/packages/mermaid/scripts/loadHook.mjs
@@ -0,0 +1,22 @@
+import { fileURLToPath } from 'node:url';
+/** @import import { LoadHook } from "node:module"; */
+/**
+ * @type {LoadHook}
+ *
+ * Load hook that short circuits the loading of `.schema.yaml` files with `export default {}`.
+ * These would normally be loaded using ESBuild, but that doesn't work for these local scripts.
+ *
+ * @see https://nodejs.org/api/module.html#loadurl-context-nextload
+ */
+export const load = async (url, context, nextLoad) => {
+  const filePath = url.startsWith('file://') ? fileURLToPath(url) : url;
+  if (filePath.endsWith('.schema.yaml')) {
+    return {
+      format: 'module',
+      shortCircuit: true,
+      source: `export default {}`,
+    };
+  } else {
+    return await nextLoad(url, context);
+  }
+};