refactor(cli): split up push/pull/link` funcs

aloisklink · aloisklink · commit 8b4e88967a2b · 2024-03-06T16:00:08.000Z
Move the implementation of `push`/`pull`/`link` into their own
functions, so that we can reuse them to add the feature for sync Mermaid
diagrams from within markdown files.
diff --git a/packages/cli/src/commander.test.ts b/packages/cli/src/commander.test.ts
@@ -230,7 +230,7 @@ describe('pull', () => {
       program.parseAsync(['--config', CONFIG_AUTHED, 'pull', 'test/fixtures/unsynced.mmd'], {
         from: 'user',
       }),
-    ).rejects.toThrowError('Diagram has no id');
+    ).rejects.toThrowError('Diagram at test/fixtures/unsynced.mmd has no id');
   });
 
   it('should fail if MermaidChart document has no code', async () => {
@@ -240,7 +240,7 @@ describe('pull', () => {
 
     await expect(
       program.parseAsync(['--config', CONFIG_AUTHED, 'pull', diagram], { from: 'user' }),
-    ).rejects.toThrowError('Diagram has no code');
+    ).rejects.toThrowError(`Diagram at ${diagram} has no code`);
   });
 
   it('should pull document and add a `id:` field to frontmatter', async () => {
@@ -280,7 +280,7 @@ describe('push', () => {
       program.parseAsync(['--config', CONFIG_AUTHED, 'push', 'test/fixtures/unsynced.mmd'], {
         from: 'user',
       }),
-    ).rejects.toThrowError('Diagram has no id');
+    ).rejects.toThrowError('Diagram at test/fixtures/unsynced.mmd has no id');
   });
 
   it('should push document and remove the `id:` field front frontmatter', async () => {
diff --git a/packages/cli/src/commander.ts b/packages/cli/src/commander.ts
@@ -5,12 +5,12 @@ import {
   InvalidArgumentError,
 } from '@commander-js/extra-typings';
 import { readFile, writeFile } from 'fs/promises';
-import { extractFrontMatter, removeFrontMatterKeys, injectFrontMatter } from './frontmatter.js';
 import { MermaidChart } from '@mermaidchart/sdk';
 
 import input from '@inquirer/input';
 import select, { Separator } from '@inquirer/select';
 import { type Config, defaultConfigPath, readConfig, writeConfig } from './config.js';
+import { link, pull, push } from './methods.js';
 
 /**
  * Global configuration option for the root Commander Command.
@@ -156,58 +156,45 @@ function logout() {
     });
 }
 
-function link() {
+function linkCmd() {
   return createCommand('link')
     .description('Link the given Mermaid diagram to Mermaid Chart')
     .addArgument(new Argument('<path>', 'The path of the file to link.'))
     .action(async (path, _options, command) => {
       const optsWithGlobals = command.optsWithGlobals<CommonOptions>();
       const client = await createClient(optsWithGlobals);
+      const linkCache = {};
+
       const existingFile = await readFile(path, { encoding: 'utf8' });
-      const frontmatter = extractFrontMatter(existingFile);
-
-      if (frontmatter.metadata.id) {
-        throw new CommanderError(
-          /*exitCode=*/ 1,
-          'EALREADY_LINKED',
-          'This document already has an `id` field',
-        );
-      }
 
-      const projects = await client.getProjects();
-
-      const projectId = await select({
-        message: 'Select a project to upload your document to',
-        choices: [
-          ...projects.map((project) => {
-            return {
-              name: project.title,
-              value: project.id,
-            };
-          }),
-          new Separator(
-            `Or go to ${new URL('/app/projects', client.baseURL)} to create a new project`,
-          ),
-        ],
+      const linkedDiagram = await link(existingFile, client, {
+        cache: linkCache,
+        title: path,
+        async getProjectId(cache) {
+          cache.projects = cache.projects ?? client.getProjects();
+          const projectId = await select({
+            message: `Select a project to upload ${path} to`,
+            choices: [
+              ...(await cache.projects).map((project) => {
+                return {
+                  name: project.title,
+                  value: project.id,
+                };
+              }),
+              new Separator(
+                `Or go to ${new URL('/app/projects', client.baseURL)} to create a new project`,
+              ),
+            ],
+          });
+          return projectId;
+        },
       });
 
-      const createdDocument = await client.createDocument(projectId);
-
-      const code = injectFrontMatter(existingFile, { id: createdDocument.documentID });
-
-      await Promise.all([
-        writeFile(path, code, { encoding: 'utf8' }),
-        client.setDocument({
-          projectID: createdDocument.projectID,
-          documentID: createdDocument.documentID,
-          title: path,
-          code: existingFile,
-        }),
-      ]);
+      await writeFile(path, linkedDiagram, { encoding: 'utf8' });
     });
 }
 
-function pull() {
+function pullCmd() {
   return createCommand('pull')
     .description('Pulls a document from from Mermaid Chart')
     .addArgument(new Argument('<path>', 'The path of the file to pull.'))
@@ -216,21 +203,8 @@ function pull() {
       const optsWithGlobals = command.optsWithGlobals<CommonOptions>();
       const client = await createClient(optsWithGlobals);
       const text = await readFile(path, { encoding: 'utf8' });
-      const frontmatter = extractFrontMatter(text);
 
-      if (frontmatter.metadata.id === undefined) {
-        throw new Error('Diagram has no id, have you run `link` yet?');
-      }
-
-      const uploadedFile = await client.getDocument({
-        documentID: frontmatter.metadata.id,
-      });
-
-      if (uploadedFile.code === undefined) {
-        throw new Error('Diagram has no code, please use push first');
-      }
-
-      const newFile = injectFrontMatter(uploadedFile.code, { id: frontmatter.metadata.id });
+      const newFile = await pull(text, client, { title: path });
 
       if (text === newFile) {
         console.log(`✅ - ${path} is up to date`);
@@ -246,38 +220,16 @@ function pull() {
     });
 }
 
-function push() {
+function pushCmd() {
   return createCommand('push')
     .description('Push a local diagram to Mermaid Chart')
     .addArgument(new Argument('<path>', 'The path of the file to push.'))
     .action(async (path, _options, command) => {
       const optsWithGlobals = command.optsWithGlobals<CommonOptions>();
       const client = await createClient(optsWithGlobals);
       const text = await readFile(path, { encoding: 'utf8' });
-      const frontmatter = extractFrontMatter(text);
-
-      if (frontmatter.metadata.id === undefined) {
-        throw new Error('Diagram has no id, have you run `link` yet?');
-      }
-
-      // TODO: check if file has changed since last push and print a warning
-      const existingDiagram = await client.getDocument({
-        documentID: frontmatter.metadata.id,
-      });
 
-      // due to MC-1056, try to remove YAML frontmatter if we can
-      const diagramToUpload = removeFrontMatterKeys(text, new Set(['id']));
-
-      if (existingDiagram.code === diagramToUpload) {
-        console.log(`✅ - ${path} is up to date`);
-      } else {
-        await client.setDocument({
-          projectID: existingDiagram.projectID,
-          documentID: existingDiagram.documentID,
-          code: diagramToUpload,
-        });
-        console.log(`✅ - ${path} was pushed`);
-      }
+      await push(text, client, { title: path });
     });
 }
 
@@ -297,7 +249,7 @@ export function createCommanderCommand() {
     .addCommand(whoami())
     .addCommand(login())
     .addCommand(logout())
-    .addCommand(link())
-    .addCommand(pull())
-    .addCommand(push());
+    .addCommand(linkCmd())
+    .addCommand(pullCmd())
+    .addCommand(pushCmd());
 }
diff --git a/packages/cli/src/methods.ts b/packages/cli/src/methods.ts
@@ -0,0 +1,126 @@
+import type { MermaidChart } from '@mermaidchart/sdk';
+
+import { CommanderError } from '@commander-js/extra-typings';
+import { extractFrontMatter, injectFrontMatter, removeFrontMatterKeys } from './frontmatter.js';
+
+/**
+ * Cached data to use when pulling/pushing/linking multiple files at once.
+ */
+interface Cache {
+  /**
+   * If set, the user has said to use the projectId to create all documents
+   * in.
+   */
+  selectedProjectId?: string;
+  /**
+   * Cached response from {@link MermaidChart.getProjects}.
+   */
+  projects?: ReturnType<MermaidChart['getProjects']>;
+}
+
+interface CommonOptions {
+  /** Description of diagram to use when sending messages to the user */
+  title: string;
+}
+
+interface LinkOptions extends CommonOptions {
+  /** Function that asks the user which project id they want to upload a diagram to */
+  getProjectId: (cache: LinkOptions['cache']) => Promise<string>;
+  // cache to be shared between link calls
+  cache: Cache;
+}
+
+/**
+ * Creates a new diagram on MermaidChart.com for the given local diagram.
+ *
+ * @returns The diagram with an added `id: xxxx` field.
+ */
+export async function link(diagram: string, client: MermaidChart, options: LinkOptions) {
+  const frontmatter = extractFrontMatter(diagram);
+
+  if (frontmatter.metadata.id) {
+    throw new CommanderError(
+      /*exitCode=*/ 1,
+      'EALREADY_LINKED',
+      'This document already has an `id` field',
+    );
+  }
+
+  const { title, getProjectId, cache } = options;
+
+  const projectId = cache.selectedProjectId ?? (await getProjectId(cache));
+
+  const createdDocument = await client.createDocument(projectId);
+
+  await client.setDocument({
+    projectID: createdDocument.projectID,
+    documentID: createdDocument.documentID,
+    title,
+    code: diagram,
+  });
+
+  const diagramWithId = injectFrontMatter(diagram, { id: createdDocument.documentID });
+
+  return diagramWithId;
+}
+
+interface PullOptions extends CommonOptions {}
+
+/**
+ * Pulls down a diagram from MermaidChart.com
+ *
+ * @param diagram - The local diagram. This should have an `id: ` field in the YAML frontmatter.
+ *
+ * @returns The updated diagram. This may equal `diagram` if there were no changes.
+ */
+export async function pull(diagram: string, client: MermaidChart, { title }: PullOptions) {
+  const frontmatter = extractFrontMatter(diagram);
+
+  if (frontmatter.metadata.id === undefined) {
+    throw new Error(`Diagram at ${title} has no id, have you run \`link\` yet?`);
+  }
+
+  const uploadedFile = await client.getDocument({
+    documentID: frontmatter.metadata.id,
+  });
+
+  if (uploadedFile.code === undefined) {
+    throw new Error(`Diagram at ${title} has no code, please use \`push\` first.`);
+  }
+
+  const newFile = injectFrontMatter(uploadedFile.code, { id: frontmatter.metadata.id });
+
+  return newFile;
+}
+
+interface PushOptions extends CommonOptions {}
+
+/**
+ * Push the given diagram to MermaidChart.com
+ */
+export async function push(diagram: string, client: MermaidChart, { title }: PushOptions) {
+  const frontmatter = extractFrontMatter(diagram);
+
+  if (frontmatter.metadata.id === undefined) {
+    throw new Error(`Diagram at ${title} has no id, have you run \`link\` yet?`);
+  }
+
+  // TODO: check if file has changed since last push and print a warning
+  const existingDiagram = await client.getDocument({
+    documentID: frontmatter.metadata.id,
+  });
+
+  // due to MC-1056, try to remove YAML frontmatter if we can
+  const diagramToUpload = removeFrontMatterKeys(diagram, new Set(['id']));
+
+  if (existingDiagram.code === diagramToUpload) {
+    console.log(`✅ - ${title} is up to date`);
+  } else {
+    await client.setDocument({
+      projectID: existingDiagram.projectID,
+      documentID: existingDiagram.documentID,
+      code: diagramToUpload,
+    });
+    console.log(`✅ - ${title} was pushed`);
+  }
+}
