@redocly/cli 1.0.0 → 1.0.1

package/src/commands/build-docs/types.ts

@@ -0,0 +1,24 @@
+export type BuildDocsOptions = {
+  watch?: boolean;
+  output?: string;
+  title?: string;
+  disableGoogleFont?: boolean;
+  port?: number;
+  templateFileName?: string;
+  templateOptions?: any;
+  redocOptions?: any;
+  redocCurrentVersion: string;
+};
+
+export type BuildDocsArgv = {
+  api: string;
+  o: string;
+  title?: string;
+  disableGoogleFont?: boolean;
+  template?: string;
+  templateOptions: Record<string, any>;
+  theme: {
+    openapi: string | Record<string, unknown>;
+  };
+  config?: string;
+};

package/src/commands/build-docs/utils.ts

@@ -0,0 +1,110 @@
+import { createElement } from 'react';
+import { createStore, Redoc } from 'redoc';
+import { Config, isAbsoluteUrl } from '@redocly/openapi-core';
+
+import { renderToString } from 'react-dom/server';
+import { ServerStyleSheet } from 'styled-components';
+import { compile } from 'handlebars';
+import { dirname, join, resolve } from 'path';
+import { existsSync, lstatSync, readFileSync } from 'fs';
+
+import type { BuildDocsOptions } from './types';
+import { red } from 'colorette';
+import { exitWithError } from '../../utils';
+
+export function getObjectOrJSON(
+  openapiOptions: string | Record<string, unknown>,
+  config: Config
+): JSON | Record<string, unknown> | Config {
+  switch (typeof openapiOptions) {
+    case 'object':
+      return openapiOptions;
+    case 'string':
+      try {
+        if (existsSync(openapiOptions) && lstatSync(openapiOptions).isFile()) {
+          return JSON.parse(readFileSync(openapiOptions, 'utf-8'));
+        } else {
+          return JSON.parse(openapiOptions);
+        }
+      } catch (e) {
+        process.stderr.write(
+          red(
+            `Encountered error:\n\n${openapiOptions}\n\nis neither a file with a valid JSON object neither a stringified JSON object.`
+          )
+        );
+        exitWithError(e);
+      }
+      break;
+    default: {
+      if (config) {
+        process.stderr.write(`Found ${config.configFile} and using theme.openapi options\n`);
+
+        return config.theme.openapi ? config.theme.openapi : {};
+      }
+      return {};
+    }
+  }
+  return {};
+}
+
+export async function getPageHTML(
+  api: any,
+  pathToApi: string,
+  {
+    title,
+    disableGoogleFont,
+    templateFileName,
+    templateOptions,
+    redocOptions = {},
+    redocCurrentVersion,
+  }: BuildDocsOptions,
+  configPath?: string
+) {
+  process.stderr.write('Prerendering docs\n');
+
+  const apiUrl = redocOptions.specUrl || (isAbsoluteUrl(pathToApi) ? pathToApi : undefined);
+  const store = await createStore(api, apiUrl, redocOptions);
+  const sheet = new ServerStyleSheet();
+
+  const html = renderToString(sheet.collectStyles(createElement(Redoc, { store })));
+  const state = await store.toJS();
+  const css = sheet.getStyleTags();
+
+  templateFileName = templateFileName
+    ? templateFileName
+    : redocOptions?.htmlTemplate
+    ? resolve(configPath ? dirname(configPath) : '', redocOptions.htmlTemplate)
+    : join(__dirname, './template.hbs');
+  const template = compile(readFileSync(templateFileName).toString());
+  return template({
+    redocHTML: `
+      <div id="redoc">${html || ''}</div>
+      <script>
+      ${`const __redoc_state = ${sanitizeJSONString(JSON.stringify(state))};` || ''}
+
+      var container = document.getElementById('redoc');
+      Redoc.${'hydrate(__redoc_state, container)'};
+
+      </script>`,
+    redocHead:
+      `<script src="https://cdn.redoc.ly/redoc/v${redocCurrentVersion}/bundles/redoc.standalone.js"></script>` +
+      css,
+    title: title || api.info.title || 'ReDoc documentation',
+    disableGoogleFont,
+    templateOptions,
+  });
+}
+
+export function sanitizeJSONString(str: string): string {
+  return escapeClosingScriptTag(escapeUnicode(str));
+}
+
+// see http://www.thespanner.co.uk/2011/07/25/the-json-specification-is-now-wrong/
+export function escapeClosingScriptTag(str: string): string {
+  return str.replace(/<\/script>/g, '<\\/script>');
+}
+
+// see http://www.thespanner.co.uk/2011/07/25/the-json-specification-is-now-wrong/
+export function escapeUnicode(str: string): string {
+  return str.replace(/\u2028|\u2029/g, (m) => '\\u202' + (m === '\u2028' ? '8' : '9'));
+}

package/src/commands/bundle.ts

@@ -0,0 +1,177 @@
+import {
+  formatProblems,
+  getTotals,
+  getMergedConfig,
+  lint,
+  bundle,
+  Config,
+  OutputFormat,
+} from '@redocly/openapi-core';
+import {
+  dumpBundle,
+  getExecutionTime,
+  getFallbackApisOrExit,
+  getOutputFileName,
+  handleError,
+  printUnusedWarnings,
+  saveBundle,
+  printLintTotals,
+  checkIfRulesetExist,
+  sortTopLevelKeysForOas,
+} from '../utils';
+import type { OutputExtensions, Skips, Totals } from '../types';
+import { performance } from 'perf_hooks';
+import { blue, gray, green, yellow } from 'colorette';
+import { writeFileSync } from 'fs';
+
+export type BundleOptions = {
+  apis?: string[];
+  'max-problems': number;
+  extends?: string[];
+  config?: string;
+  format: OutputFormat;
+  output?: string;
+  ext: OutputExtensions;
+  dereferenced?: boolean;
+  force?: boolean;
+  lint?: boolean;
+  metafile?: string;
+  'remove-unused-components'?: boolean;
+  'keep-url-references'?: boolean;
+} & Skips;
+
+export async function handleBundle(argv: BundleOptions, config: Config, version: string) {
+  const removeUnusedComponents =
+    argv['remove-unused-components'] ||
+    config.rawConfig?.styleguide?.decorators?.hasOwnProperty('remove-unused-components');
+  const apis = await getFallbackApisOrExit(argv.apis, config);
+  const totals: Totals = { errors: 0, warnings: 0, ignored: 0 };
+  const maxProblems = argv['max-problems'];
+
+  for (const { path, alias } of apis) {
+    try {
+      const startedAt = performance.now();
+      const resolvedConfig = getMergedConfig(config, alias);
+      const { styleguide } = resolvedConfig;
+
+      styleguide.skipRules(argv['skip-rule']);
+      styleguide.skipPreprocessors(argv['skip-preprocessor']);
+      styleguide.skipDecorators(argv['skip-decorator']);
+
+      if (argv.lint) {
+        checkIfRulesetExist(styleguide.rules);
+        if (config.styleguide.recommendedFallback) {
+          process.stderr.write(
+            `No configurations were provided -- using built in ${blue(
+              'recommended'
+            )} configuration by default.\n\n`
+          );
+        }
+        const results = await lint({
+          ref: path,
+          config: resolvedConfig,
+        });
+        const fileLintTotals = getTotals(results);
+
+        totals.errors += fileLintTotals.errors;
+        totals.warnings += fileLintTotals.warnings;
+        totals.ignored += fileLintTotals.ignored;
+
+        formatProblems(results, {
+          format: argv.format || 'codeframe',
+          totals: fileLintTotals,
+          version,
+          maxProblems,
+        });
+        printLintTotals(fileLintTotals, 2);
+      }
+
+      process.stderr.write(gray(`bundling ${path}...\n`));
+
+      const {
+        bundle: result,
+        problems,
+        ...meta
+      } = await bundle({
+        config: resolvedConfig,
+        ref: path,
+        dereference: argv.dereferenced,
+        removeUnusedComponents,
+        keepUrlRefs: argv['keep-url-references'],
+      });
+
+      const fileTotals = getTotals(problems);
+      const { outputFile, ext } = getOutputFileName(path, apis.length, argv.output, argv.ext);
+
+      if (fileTotals.errors === 0 || argv.force) {
+        if (!argv.output) {
+          const output = dumpBundle(
+            sortTopLevelKeysForOas(result.parsed),
+            argv.ext || 'yaml',
+            argv.dereferenced
+          );
+          process.stdout.write(output);
+        } else {
+          const output = dumpBundle(sortTopLevelKeysForOas(result.parsed), ext, argv.dereferenced);
+          saveBundle(outputFile, output);
+        }
+      }
+
+      totals.errors += fileTotals.errors;
+      totals.warnings += fileTotals.warnings;
+      totals.ignored += fileTotals.ignored;
+
+      formatProblems(problems, {
+        format: argv.format,
+        maxProblems,
+        totals: fileTotals,
+        version,
+      });
+
+      if (argv.metafile) {
+        if (apis.length > 1) {
+          process.stderr.write(
+            yellow(`[WARNING] "--metafile" cannot be used with multiple apis. Skipping...`)
+          );
+        }
+        {
+          writeFileSync(argv.metafile, JSON.stringify(meta), 'utf-8');
+        }
+      }
+
+      const elapsed = getExecutionTime(startedAt);
+      if (fileTotals.errors > 0) {
+        if (argv.force) {
+          process.stderr.write(
+            `❓ Created a bundle for ${blue(path)} at ${blue(outputFile)} with errors ${green(
+              elapsed
+            )}.\n${yellow('Errors ignored because of --force')}.\n`
+          );
+        } else {
+          process.stderr.write(
+            `❌ Errors encountered while bundling ${blue(
+              path
+            )}: bundle not created (use --force to ignore errors).\n`
+          );
+        }
+      } else {
+        process.stderr.write(
+          `📦 Created a bundle for ${blue(path)} at ${blue(outputFile)} ${green(elapsed)}.\n`
+        );
+      }
+
+      const removedCount = meta.visitorsData?.['remove-unused-components']?.removedCount;
+      if (removedCount) {
+        process.stderr.write(gray(`🧹 Removed ${removedCount} unused components.\n`));
+      }
+    } catch (e) {
+      handleError(e, path);
+    }
+  }
+
+  printUnusedWarnings(config.styleguide);
+
+  if (!(totals.errors === 0 || argv.force)) {
+    throw new Error('Bundle failed.');
+  }
+}