DOP-3414: Add back button support for OAS Page Builder (#725)

Author: rayangler

modules/oas-page-builder/index.ts

@@ -12,24 +12,26 @@ program
   .requiredOption('-b, --bundle <path>', 'path to parsed bundle zip')
   .requiredOption('-o, --output <path>', 'path to the directory to output generated files')
   .requiredOption('--redoc <path>', 'path to the Redoc CLI program to run. Must be a JS file')
-  .requiredOption('--repo <path>', 'path to repo being built');
+  .requiredOption('--repo <path>', 'path to repo being built')
+  .requiredOption('--site-url <url>, url to landing page of specific docs site');
 
 program.parse();
 const options = program.opts<ModuleOptions>();
 
 const app = async (options: ModuleOptions) => {
   const { bundle: bundlePath } = options;
-  const oasMetadata = getOASMetadata(bundlePath);
-  if (!oasMetadata) {
+  const metadata = getOASMetadata(bundlePath);
+  if (!metadata) {
     console.log('No OpenAPI content pages found.');
     return;
   }
 
-  const oasMetadataEntries = Object.entries(oasMetadata);
+  const { siteTitle, openapiPages } = metadata;
+  const oasMetadataEntries = Object.entries(openapiPages);
   const numOASPages = oasMetadataEntries.length;
   console.log(`OpenAPI content pages found: ${numOASPages}.`);
 
-  await buildOpenAPIPages(oasMetadataEntries, options);
+  await buildOpenAPIPages(oasMetadataEntries, { ...options, siteTitle });
 };
 
 app(options)

modules/oas-page-builder/src/services/buildMetadata.ts

@@ -1,16 +1,22 @@
 import AdmZip from 'adm-zip';
 import { deserialize } from 'bson';
-import { OASPagesMetadata } from './types';
+import { BuildMetadata, OASPagesMetadata } from './types';
 
-export const getOASMetadata = (bundlePath: string): OASPagesMetadata | null => {
+export const getOASMetadata = (bundlePath: string): BuildMetadata | null => {
   const zip = new AdmZip(bundlePath);
   const zipEntries = zip.getEntries();
 
   for (const entry of zipEntries) {
     if (entry.entryName === 'site.bson') {
       const buildMetadata = deserialize(entry.getData());
-      const oasMetadata: OASPagesMetadata = buildMetadata['openapi_pages'];
-      if (!!oasMetadata) return oasMetadata;
+      const siteTitle: string = buildMetadata['title'];
+      const oasMetadata: OASPagesMetadata | undefined = buildMetadata['openapi_pages'];
+      if (!!oasMetadata && siteTitle) {
+        return {
+          siteTitle,
+          openapiPages: oasMetadata,
+        };
+      }
     }
   }
 

modules/oas-page-builder/src/services/commandExecutor.ts

@@ -1,9 +1,8 @@
 import fetch from 'node-fetch';
-import { ModuleOptions } from '../types';
 import { normalizePath } from '../utils/normalizePath';
-import { execRedoc } from './commandExecutor';
+import { RedocExecutor } from './redocExecutor';
 import { findLastSavedGitHash } from './database';
-import { OASPageMetadata } from './types';
+import { OASPageMetadata, PageBuilderOptions } from './types';
 
 const OAS_FILE_SERVER = 'https://mongodb-mms-prod-build-server.s3.amazonaws.com/openapi/';
 
@@ -53,8 +52,10 @@ const getAtlasSpecUrl = async (apiKeyword: string) => {
 
 export const buildOpenAPIPages = async (
   entries: [string, OASPageMetadata][],
-  { output, redoc: redocPath, repo: repoPath }: ModuleOptions
+  { output, redoc: redocPath, repo: repoPath, siteUrl, siteTitle }: PageBuilderOptions
 ) => {
+  const redocExecutor = new RedocExecutor(redocPath, siteUrl, siteTitle);
+
   for (const [pageSlug, data] of entries) {
     const { source_type: sourceType, source } = data;
 
@@ -73,7 +74,7 @@ export const buildOpenAPIPages = async (
       }
 
       const finalFilename = normalizePath(`${output}/${pageSlug}/index.html`);
-      await execRedoc(spec, finalFilename, redocPath);
+      await redocExecutor.execute(spec, finalFilename);
     } catch (e) {
       console.error(e);
       // Continue to try to build other pages since it's possible that mut will

modules/oas-page-builder/src/services/pageBuilder.ts

@@ -0,0 +1,38 @@
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execCommand = promisify(exec);
+
+export class RedocExecutor {
+  redocPath: string;
+  // Stringified options object for Redoc command. Redoc also accepts individual options or a JSON file
+  private _optionsString: string;
+
+  constructor(redocPath: string, siteUrl: string, siteTitle: string) {
+    this.redocPath = redocPath;
+
+    // Custom options DOP defines in the Redoc fork
+    const customOptions = {
+      backNavigationPath: siteUrl,
+      siteTitle,
+    };
+
+    // May contain both native Redoc options and custom DOP options in the future
+    this._optionsString = JSON.stringify({ customOptions });
+  }
+
+  // Calls Redoc CLI to build spec at given output path
+  async execute(specSource: string, outputPath: string) {
+    const outputArg = `--output ${outputPath}`;
+    const optionsArg = `--options '${this._optionsString}'`;
+    const command = `node ${this.redocPath} build ${specSource} ${outputArg} ${optionsArg}`;
+
+    const { stdout, stderr } = await execCommand(command);
+    console.log(stdout);
+
+    if (stderr) {
+      console.error(`Error trying to build page ${outputPath} with Redoc.`);
+      throw stderr;
+    }
+  }
+}

modules/oas-page-builder/src/services/redocExecutor.ts

@@ -1,6 +1,17 @@
+import { ModuleOptions } from '../types';
+
 export interface OASPageMetadata {
   source_type: string;
   source: string;
 }
 
 export type OASPagesMetadata = Record<string, OASPageMetadata>;
+
+export interface BuildMetadata {
+  siteTitle: string;
+  openapiPages: OASPagesMetadata;
+}
+
+export interface PageBuilderOptions extends Omit<ModuleOptions, 'bundle'> {
+  siteTitle: string;
+}

modules/oas-page-builder/src/services/types.ts

@@ -3,4 +3,5 @@ export interface ModuleOptions {
   output: string;
   redoc: string;
   repo: string;
+  siteUrl: string;
 }

modules/oas-page-builder/src/types.ts

@@ -1,16 +1,19 @@
 import fetch from 'node-fetch';
-import { execRedoc } from '../../../src/services/commandExecutor';
+import { RedocExecutor } from '../../../src/services/redocExecutor';
 import { findLastSavedGitHash } from '../../../src/services/database';
 import { buildOpenAPIPages } from '../../../src/services/pageBuilder';
-import { OASPageMetadata } from '../../../src/services/types';
+import { OASPageMetadata, PageBuilderOptions } from '../../../src/services/types';
 import { ModuleOptions } from '../../../src/types';
 
 const MOCKED_GIT_HASH = '1234';
 const LAST_SAVED_GIT_HASH = '4321';
 
+const mockExecute = jest.fn();
 // Mock execRedoc since we only want to ensure pageBuilder properly calls the function
-jest.mock('../../../src/services/commandExecutor', () => ({
-  execRedoc: jest.fn(),
+jest.mock('../../../src/services/redocExecutor', () => ({
+  RedocExecutor: jest.fn().mockImplementation(() => ({
+    execute: mockExecute,
+  })),
 }));
 
 // Mock database since implementation relies on database instance. Returned values
@@ -33,17 +36,17 @@ const mockFetchImplementation = (ok: boolean) => {
 };
 
 describe('pageBuilder', () => {
-  const testOptions: ModuleOptions = {
-    bundle: '/path/to/bundle.zip',
+  const testOptions: PageBuilderOptions = {
     output: '/path/to/destination',
     redoc: '/path/to/redoc/cli/index.js',
     repo: '/path/to/repo',
+    siteUrl: 'https://mongodb.com/docs',
+    siteTitle: 'Test Docs',
   };
 
   beforeEach(() => {
     // Reset mock to reset call count
-    // @ts-ignore
-    execRedoc.mockReset();
+    mockExecute.mockReset();
   });
 
   it('builds OpenAPI pages', async () => {
@@ -62,24 +65,23 @@ describe('pageBuilder', () => {
     ];
 
     await buildOpenAPIPages(testEntries, testOptions);
-    expect(execRedoc).toBeCalledTimes(testEntries.length);
+    // const mockSoundPlayerInstance = SoundPlayer.mock.instances[0];
+    // const mockRedocExecutorInstance = RedocExecutor.mock.instances[0];
+    expect(mockExecute).toBeCalledTimes(testEntries.length);
     // Local
-    expect(execRedoc).toBeCalledWith(
+    expect(mockExecute).toBeCalledWith(
       `${testOptions.repo}/source${testEntries[0][1].source}`,
-      `${testOptions.output}/${testEntries[0][0]}/index.html`,
-      testOptions.redoc
+      `${testOptions.output}/${testEntries[0][0]}/index.html`
     );
     // Url
-    expect(execRedoc).toBeCalledWith(
+    expect(mockExecute).toBeCalledWith(
       `${testEntries[1][1].source}`,
-      getExpectedOutputPath(testOptions.output, testEntries[1][0]),
-      testOptions.redoc
+      getExpectedOutputPath(testOptions.output, testEntries[1][0])
     );
     // Atlas
-    expect(execRedoc).toBeCalledWith(
+    expect(mockExecute).toBeCalledWith(
       `https://mongodb-mms-prod-build-server.s3.amazonaws.com/openapi/${MOCKED_GIT_HASH}.json`,
-      getExpectedOutputPath(testOptions.output, testEntries[2][0]),
-      testOptions.redoc
+      getExpectedOutputPath(testOptions.output, testEntries[2][0])
     );
   });
 
@@ -91,10 +93,9 @@ describe('pageBuilder', () => {
     const testEntries: [string, OASPageMetadata][] = [['path/to/page/1', { source_type: 'atlas', source: 'cloud' }]];
 
     await buildOpenAPIPages(testEntries, testOptions);
-    expect(execRedoc).toBeCalledWith(
+    expect(mockExecute).toBeCalledWith(
       `https://mongodb-mms-prod-build-server.s3.amazonaws.com/openapi/${LAST_SAVED_GIT_HASH}.json`,
-      getExpectedOutputPath(testOptions.output, testEntries[0][0]),
-      testOptions.redoc
+      getExpectedOutputPath(testOptions.output, testEntries[0][0])
     );
   });
 
@@ -106,6 +107,6 @@ describe('pageBuilder', () => {
     const testEntries: [string, OASPageMetadata][] = [['path/to/page/1', { source_type: 'atlas', source: 'cloud' }]];
 
     await buildOpenAPIPages(testEntries, testOptions);
-    expect(execRedoc).toBeCalledTimes(0);
+    expect(mockExecute).toBeCalledTimes(0);
   });
 });

modules/oas-page-builder/tests/unit/services/pageBuilder.test.ts

@@ -0,0 +1,32 @@
+import { RedocExecutor } from '../../../src/services/redocExecutor';
+import cp from 'child_process';
+
+jest.mock('child_process');
+// @ts-ignore
+cp.exec.mockImplementation((command: string, callback: any) => {
+  callback(null, command);
+});
+
+describe('RedocExecutor', () => {
+  it('calls the Redoc build command with expected parameters', async () => {
+    const testRedocPath = '/path/to/redoc/cli/index.js';
+    const testSiteUrl = 'https://mongodb.com/docs';
+    const testSiteTitle = 'Test Docs';
+    const redocExecutor = new RedocExecutor(testRedocPath, testSiteUrl, testSiteTitle);
+
+    const testSpecSource = '/path/to/spec.json';
+    const testOutputPath = '/path/to/output/index.html';
+    await redocExecutor.execute(testSpecSource, testOutputPath);
+
+    const expectedOptions = {
+      customOptions: {
+        backNavigationPath: testSiteUrl,
+        siteTitle: testSiteTitle,
+      },
+    };
+    const expectedCommand = `node ${testRedocPath} build ${testSpecSource} --output ${testOutputPath} --options '${JSON.stringify(
+      expectedOptions
+    )}'`;
+    expect(cp.exec).toBeCalledWith(expectedCommand, expect.anything());
+  });
+});