Merge pull request #20 from Mermaid-Chart/feat/use-a-url-id-for-frontmatter

feat(cli)!: use a URL id in the frontmatter

Author: aloisklink

packages/cli/README.md

@@ -57,7 +57,7 @@ which points to the diagram on MermaidChart.com:
 ```mermaid
 ---
 title: My diagram
-id: xxxx-xxxxx-xxxxx # this field is created by @mermaidchart/cli
+id: https://www.mermaidchart.com/d/xxxx-xxxxx-xxxxx # this field is created by @mermaidchart/cli
 ---
 flowchart
   x[My Diagram]

packages/cli/src/commander.test.ts

@@ -226,7 +226,7 @@ describe('link', () => {
     );
 
     await expect(readFile(diagram, { encoding: 'utf8' })).resolves.toContain(
-      `id: ${mockedEmptyDiagram.documentID}`,
+      `id: https://test.mermaidchart.invalid/d/${mockedEmptyDiagram.documentID}`,
     );
   });
 
@@ -271,7 +271,7 @@ describe('link', () => {
       await Promise.all(
         [diagram, diagram2, diagram3].map(async (file) => {
           await expect(readFile(file, { encoding: 'utf8' })).resolves.toContain(
-            `id: ${mockedEmptyDiagram.documentID}`,
+            `id: https://test.mermaidchart.invalid/d/${mockedEmptyDiagram.documentID}`,
           );
         }),
       );
@@ -298,8 +298,10 @@ describe('link', () => {
 
     const file = await readFile(unlinkedMarkdownFile, { encoding: 'utf8' });
 
-    expect(file).toMatch(`id: ${mockedEmptyDiagram.documentID}\n`);
-    expect(file).toMatch(`id: second-id\n`);
+    expect(file).toMatch(
+      `id: https://test.mermaidchart.invalid/d/${mockedEmptyDiagram.documentID}\n`,
+    );
+    expect(file).toMatch(`id: https://test.mermaidchart.invalid/d/second-id\n`);
   });
 
   it('should link diagrams in partially linked markdown file', async () => {
@@ -323,7 +325,7 @@ describe('link', () => {
 
     const file = await readFile(partiallyLinkedMarkdownFile, { encoding: 'utf8' });
 
-    expect(file).toMatch(`id: second-id\n`);
+    expect(file).toMatch(`id: https://test.mermaidchart.invalid/d/second-id\n`);
   });
 
   it('should handle unusual markdown formatting', async () => {
@@ -347,7 +349,7 @@ describe('link', () => {
 
     const file = await readFile(unusualMarkdownFile, { encoding: 'utf8' });
 
-    const idLineRegex = /^.*id: my-mocked-diagram-id\n/gm;
+    const idLineRegex = /^.*id: https:\/\/test.mermaidchart.invalid\/d\/my-mocked-diagram-id\n/gm;
 
     expect(file).toMatch(idLineRegex);
     // other than the added `id: xxxx` field, everything else should be identical,
@@ -412,7 +414,9 @@ title: My cool flowchart
     for (const file of [diagram, diagram2]) {
       const diagramContents = await readFile(file, { encoding: 'utf8' });
 
-      expect(diagramContents).toContain(`id: ${mockedDiagram.documentID}`);
+      expect(diagramContents).toContain(
+        `id: https://test.mermaidchart.invalid/d/${mockedDiagram.documentID}`,
+      );
       expect(diagramContents).toContain("flowchart TD\n      A[I've been updated!]");
     }
   });

packages/cli/src/frontmatter.ts

@@ -6,14 +6,37 @@
 import * as yaml from 'js-yaml';
 
 const frontMatterRegex = /^-{3}\s*[\n\r](.*?)[\n\r]-{3}\s*[\n\r]+/s;
+const urlIDRegex = /(?<baseURL>.*)\/d\/(?<documentID>[\w-]+)/;
+
+type UrlID = `${string}/d/${string}`;
+
+export function getDocumentID(urlID: UrlID, expectedbaseURL: string) {
+  const match = urlID.match(urlIDRegex);
+  if (match === null) {
+    throw new Error(
+      `Invalid document ID: ${urlID}. Please report this issue to the @mermaidchart/cli maintainers.`,
+    );
+  }
+  // we know that this regex will always return groups on a match
+  const { baseURL, documentID } = match.groups as { baseURL: string; documentID: string };
+  if (baseURL !== expectedbaseURL) {
+    throw new Error(
+      `Your @mermaidchart/cli is configured to use ${expectedbaseURL}, but your diagram is using ${baseURL}`,
+    );
+  }
+  return documentID;
+}
+export function createUrlID(baseURL: string, documentID: string): UrlID {
+  return `${baseURL}/d/${documentID}`;
+}
 
 interface FrontMatterMetadata {
   title?: string;
   // Allows custom display modes. Currently used for compact mode in gantt charts.
   displayMode?: string;
   config?: Record<string, any>; // eslint-disable-line @typescript-eslint/no-explicit-any
-  /** Unique ID for the diagram on MermaidChart.com */
-  id?: string;
+  /** Unique ID for the diagram, e.g. `https://www.mermaidchart.com/d/xxxxxx-xxxx-xxxxx` */
+  id?: UrlID;
 }
 
 export interface FrontMatterResult {

packages/cli/src/methods.ts

@@ -1,7 +1,13 @@
 import type { MermaidChart } from '@mermaidchart/sdk';
 
 import { CommanderError } from '@commander-js/extra-typings';
-import { extractFrontMatter, injectFrontMatter, removeFrontMatterKeys } from './frontmatter.js';
+import {
+  createUrlID,
+  extractFrontMatter,
+  getDocumentID,
+  injectFrontMatter,
+  removeFrontMatterKeys,
+} from './frontmatter.js';
 
 /**
  * Cached data to use when pulling/pushing/linking multiple files at once.
@@ -81,7 +87,9 @@ export async function link(
     code: diagram,
   });
 
-  const diagramWithId = injectFrontMatter(diagram, { id: createdDocument.documentID });
+  const diagramWithId = injectFrontMatter(diagram, {
+    id: createUrlID(client.baseURL, createdDocument.documentID),
+  });
 
   return diagramWithId;
 }
@@ -103,7 +111,7 @@ export async function pull(diagram: string, client: MermaidChart, { title }: Pul
   }
 
   const uploadedFile = await client.getDocument({
-    documentID: frontmatter.metadata.id,
+    documentID: getDocumentID(frontmatter.metadata.id, client.baseURL),
   });
 
   if (uploadedFile.code === undefined) {
@@ -129,7 +137,7 @@ export async function push(diagram: string, client: MermaidChart, { title }: Pus
 
   // TODO: check if file has changed since last push and print a warning
   const existingDiagram = await client.getDocument({
-    documentID: frontmatter.metadata.id,
+    documentID: getDocumentID(frontmatter.metadata.id, client.baseURL),
   });
 
   // due to MC-1056, try to remove YAML frontmatter if we can

packages/cli/test/fixtures/connected-diagram.mmd

@@ -1,6 +1,6 @@
 ---
 title: My cool flowchart
-id: my-test-document-id
+id: https://test.mermaidchart.invalid/d/my-test-document-id
 ---
 flowchart TD
     A[Needs Update]

packages/cli/test/fixtures/linked-markdown-file.md

@@ -6,7 +6,7 @@ This is a flowchart diagram
 
 ```mermaid
 ---
-id: xxxxxxx-flowchart
+id: https://test.mermaidchart.invalid/d/xxxxxxx-flowchart
 ---
 flowchart
     A[Hello World]
@@ -16,7 +16,7 @@ While this is a pie diagram
 
 ```mermaid
 ---
-id: xxxxxxx-pie
+id: https://test.mermaidchart.invalid/d/xxxxxxx-pie
 ---
 pie
     "Flowchart" : 1

packages/cli/test/fixtures/partially-linked-markdown-file.md

@@ -6,7 +6,7 @@ This is a journey diagram that is already linked.
 
 ```mermaid
 ---
-id: xxxxxxx-journey
+id: https://test.mermaidchart.invalid/d/xxxxxxx-journey
 ---
 journey
     title This is a linked journey diagram.