docs: Optimise document generation

Co-authored-by: Alois Klink <alois@aloisklink.com>

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));