From 4d2d790cc8de03adde3fb5b820e1da7f4fd29bae Mon Sep 17 00:00:00 2001
From: Alois Klink <alois@aloisklink.com>
Date: Wed, 19 Jul 2023 23:36:13 +0100
Subject: [PATCH] build(docs): handle YAML edgecases in markdown

Our current method of adding a entry using `+=` is not safe in YAML,
since it's valid to make a YAML object entirely in JSON,
see https://github.com/mermaid-js/mermaid/pull/4640#discussion_r1265133463

We're already using `js-yaml` elsewhere in this file, so we may as well
use it for parsing/stringifying.

Reported-by: Remco Haszing <remcohaszing@gmail.com>
---
 packages/mermaid/src/docs.mts     | 29 +++++++++++++++--------------
 packages/mermaid/src/docs.spec.ts |  4 +++-
 2 files changed, 18 insertions(+), 15 deletions(-)

diff --git a/packages/mermaid/src/docs.mts b/packages/mermaid/src/docs.mts
index 227449a0a..f62c44f07 100644
--- a/packages/mermaid/src/docs.mts
+++ b/packages/mermaid/src/docs.mts
@@ -30,10 +30,19 @@
  * @todo Write a test file for this. (Will need to be able to deal .mts file. Jest has trouble with
  *   it.)
  */
+// @ts-ignore: we're importing internal jsonschema2md functions
+import { default as schemaLoader } from '@adobe/jsonschema2md/lib/schemaProxy.js';
+// @ts-ignore: we're importing internal jsonschema2md functions
+import { default as traverseSchemas } from '@adobe/jsonschema2md/lib/traverseSchema.js';
+// @ts-ignore: we're importing internal jsonschema2md functions
+import { default as buildMarkdownFromSchema } from '@adobe/jsonschema2md/lib/markdownBuilder.js';
+// @ts-ignore: we're importing internal jsonschema2md functions
+import { default as jsonSchemaReadmeBuilder } from '@adobe/jsonschema2md/lib/readmeBuilder.js';
 import { readFileSync, writeFileSync, mkdirSync, existsSync, rmSync, rmdirSync } from 'fs';
 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 { posix, dirname, relative, join } from 'path';
 import prettier from 'prettier';
@@ -286,10 +295,12 @@ export function transformMarkdownAst({
         astWithTransformedBlocks.children.unshift(yamlFrontMatter);
       }
       const filePathFromRoot = posix.join('packages/mermaid', originalFilename);
-      // TODO, should we replace this with proper YAML parsing?
-      yamlFrontMatter.value += `\neditLink: ${JSON.stringify(
-        `https://github.com/mermaid-js/mermaid/edit/develop/${filePathFromRoot}`
-      )}`;
+      yamlFrontMatter.value = dump({
+        ...(load(yamlFrontMatter.value, { schema: JSON_SCHEMA }) as
+          | Record<string, unknown>
+          | undefined),
+        editLink: `https://github.com/mermaid-js/mermaid/edit/develop/${filePathFromRoot}`,
+      });
     }
 
     if (removeYAML) {
@@ -346,16 +357,6 @@ const transformMarkdown = (file: string) => {
   copyTransformedContents(file, !verifyOnly, formatted);
 };
 
-import { load, JSON_SCHEMA } from 'js-yaml';
-// @ts-ignore: we're importing internal jsonschema2md functions
-import { default as schemaLoader } from '@adobe/jsonschema2md/lib/schemaProxy.js';
-// @ts-ignore: we're importing internal jsonschema2md functions
-import { default as traverseSchemas } from '@adobe/jsonschema2md/lib/traverseSchema.js';
-// @ts-ignore: we're importing internal jsonschema2md functions
-import { default as buildMarkdownFromSchema } from '@adobe/jsonschema2md/lib/markdownBuilder.js';
-// @ts-ignore: we're importing internal jsonschema2md functions
-import { default as jsonSchemaReadmeBuilder } from '@adobe/jsonschema2md/lib/readmeBuilder.js';
-
 /**
  * Transforms the given JSON Schema into Markdown documentation
  */
diff --git a/packages/mermaid/src/docs.spec.ts b/packages/mermaid/src/docs.spec.ts
index bea833fd9..c84bc1bac 100644
--- a/packages/mermaid/src/docs.spec.ts
+++ b/packages/mermaid/src/docs.spec.ts
@@ -119,7 +119,9 @@ This Markdown should be kept.
     ).toString();
     expect(withYaml).toEqual(`---
 title: Flowcharts Syntax
-editLink: "https://github.com/mermaid-js/mermaid/edit/develop/packages/mermaid/example-input-filename.md"
+editLink: >-
+  https://github.com/mermaid-js/mermaid/edit/develop/packages/mermaid/example-input-filename.md
+
 ---
 
 This Markdown should be kept.