Found a broken mermaid diagram, fixed it, but also added a lint step to hopefully catch future issues

Author: Duncanma

.github/workflows/mermaid-ci.yml

@@ -0,0 +1,33 @@
+name: Mermaid CI
+
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - "scripts/lint-mermaid.mjs"
+      - "package.json"
+      - "yarn.lock"
+      - ".github/workflows/mermaid-ci.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  mermaid:
+    name: Validate Mermaid syntax
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout Repository
+        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
+
+      - name: Setup Node.js Environment
+        uses: actions/setup-node@48b55a011bda9f5d6aeb4c2d9c7362e8dae4041e # v6.4.0
+        with:
+          node-version: "24"
+          cache: "yarn"
+
+      - name: Install Dependencies
+        run: yarn install --frozen-lockfile
+
+      - name: Lint Mermaid Diagrams
+        run: yarn lint:mermaid

.github/workflows/vale-ci.yml

@@ -22,4 +22,4 @@ jobs:
           level: info
           filter_mode: diff_context
           fail_on_error: false
-          vale_flags: "--config=.vale-ci.ini"
+          vale_flags: "--config=.vale-ci.ini docs"

docs/design-patterns/early-return-local-activities.mdx

@@ -44,7 +44,7 @@ sequenceDiagram
         W->>S: Complete ActivityTask
     end
 
-    Note over C,W: Client has its response; Phase 2 continues in the background
+    Note over C,W: Client has its response and Phase 2 continues in the background
 ```
 
 **Numbered walkthrough:**

package.json

@@ -23,6 +23,7 @@
     "lint:py": "vale docs/develop/python/*.mdx",
     "lint:ruby": "vale docs/develop/ruby/*.mdx",
     "lint:ts": "vale docs/develop/typescript/*.mdx",
+    "lint:mermaid": "node ./scripts/lint-mermaid.mjs",
     "fix-vale": "node vale/auto-fix-vale.js vale-output.json",
     "serve": "docusaurus serve",
     "snipsync": "snipsync",

scripts/lint-mermaid.mjs

@@ -0,0 +1,148 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import DOMPurify from 'dompurify';
+import mermaidModule from 'mermaid';
+
+const mermaid = mermaidModule.default ?? mermaidModule;
+const DOCS_ROOT = path.resolve('docs');
+const MARKDOWN_EXTENSIONS = new Set(['.md', '.mdx']);
+
+function isMarkdownFile(filePath) {
+  return MARKDOWN_EXTENSIONS.has(path.extname(filePath));
+}
+
+async function walk(dir) {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+  const results = [];
+  for (const entry of entries) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...(await walk(fullPath)));
+    } else if (entry.isFile() && isMarkdownFile(fullPath)) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+function extractMermaidBlocks(content) {
+  const lines = content.split(/\r?\n/);
+  const blocks = [];
+  let inBlock = false;
+  let blockStartLine = 0;
+  let blockLines = [];
+
+  for (let i = 0; i < lines.length; i += 1) {
+    const line = lines[i];
+    if (!inBlock) {
+      if (/^\s*```mermaid\s*$/.test(line)) {
+        inBlock = true;
+        blockStartLine = i + 2; // first content line, 1-indexed
+        blockLines = [];
+      }
+      continue;
+    }
+
+    if (/^\s*```\s*$/.test(line)) {
+      blocks.push({
+        startLine: blockStartLine,
+        content: blockLines.join('\n'),
+      });
+      inBlock = false;
+      blockLines = [];
+      continue;
+    }
+
+    blockLines.push(line);
+  }
+
+  if (inBlock) {
+    blocks.push({
+      startLine: blockStartLine,
+      content: blockLines.join('\n'),
+      unterminated: true,
+    });
+  }
+
+  return blocks;
+}
+
+function extractRelativeLineFromError(errorMessage) {
+  const match = errorMessage.match(/line\s+(\d+)/i);
+  return match ? Number(match[1]) : null;
+}
+
+async function lintFile(filePath) {
+  const content = await fs.readFile(filePath, 'utf8');
+  const blocks = extractMermaidBlocks(content);
+  const errors = [];
+
+  for (const block of blocks) {
+    if (block.unterminated) {
+      errors.push({
+        filePath,
+        line: block.startLine,
+        message: 'Unterminated mermaid code fence.',
+      });
+      continue;
+    }
+
+    if (!block.content.trim()) {
+      continue;
+    }
+
+    try {
+      await mermaid.parse(block.content);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const relativeLine = extractRelativeLineFromError(message);
+      const absoluteLine = relativeLine ? block.startLine + relativeLine - 1 : block.startLine;
+      errors.push({
+        filePath,
+        line: absoluteLine,
+        message,
+      });
+    }
+  }
+
+  return errors;
+}
+
+async function main() {
+  // Mermaid's parser may call DOMPurify hooks for some diagram syntaxes.
+  // In Node (without a browser window), dompurify can resolve to a minimal
+  // implementation that lacks hook APIs; provide no-op hooks so syntax-only
+  // parsing still works in CI.
+  if (typeof DOMPurify.addHook !== 'function') {
+    DOMPurify.addHook = () => {};
+  }
+  if (typeof DOMPurify.removeHook !== 'function') {
+    DOMPurify.removeHook = () => {};
+  }
+  if (typeof DOMPurify.sanitize !== 'function') {
+    DOMPurify.sanitize = (value) => value;
+  }
+
+  mermaid.initialize({ startOnLoad: false });
+
+  const markdownFiles = await walk(DOCS_ROOT);
+  const allErrors = [];
+
+  for (const filePath of markdownFiles) {
+    const fileErrors = await lintFile(filePath);
+    allErrors.push(...fileErrors);
+  }
+
+  if (allErrors.length > 0) {
+    console.error(`Mermaid lint failed with ${allErrors.length} error(s):`);
+    for (const err of allErrors) {
+      const relPath = path.relative(process.cwd(), err.filePath);
+      console.error(`- ${relPath}:${err.line} ${err.message}`);
+    }
+    process.exit(1);
+  }
+
+  console.log(`Mermaid lint passed. Checked ${markdownFiles.length} markdown files.`);
+}
+
+await main();