@redocly/cli 1.0.0 → 1.0.1

package/src/commands/lint.ts

@@ -0,0 +1,151 @@
+import {
+  Config,
+  findConfig,
+  formatProblems,
+  getMergedConfig,
+  getTotals,
+  lint,
+  lintConfig,
+  makeDocumentFromString,
+  stringifyYaml,
+} from '@redocly/openapi-core';
+import {
+  checkIfRulesetExist,
+  exitWithError,
+  getExecutionTime,
+  getFallbackApisOrExit,
+  handleError,
+  pluralize,
+  printConfigLintTotals,
+  printLintTotals,
+  printUnusedWarnings,
+} from '../utils';
+import type { OutputFormat, ProblemSeverity, RawConfig, RuleSeverity } from '@redocly/openapi-core';
+import type { CommandOptions, Skips, Totals } from '../types';
+import { blue, gray } from 'colorette';
+import { performance } from 'perf_hooks';
+
+export type LintOptions = {
+  apis?: string[];
+  'max-problems': number;
+  extends?: string[];
+  config?: string;
+  format: OutputFormat;
+  'generate-ignore-file'?: boolean;
+  'lint-config'?: RuleSeverity;
+} & Omit<Skips, 'skip-decorator'>;
+
+export async function handleLint(argv: LintOptions, config: Config, version: string) {
+  const apis = await getFallbackApisOrExit(argv.apis, config);
+
+  if (!apis.length) {
+    exitWithError('No APIs were provided');
+  }
+
+  if (argv['generate-ignore-file']) {
+    config.styleguide.ignore = {}; // clear ignore
+  }
+  const totals: Totals = { errors: 0, warnings: 0, ignored: 0 };
+  let totalIgnored = 0;
+
+  // TODO: use shared externalRef resolver, blocked by preprocessors now as they can mutate documents
+  for (const { path, alias } of apis) {
+    try {
+      const startedAt = performance.now();
+      const resolvedConfig = getMergedConfig(config, alias);
+      const { styleguide } = resolvedConfig;
+
+      checkIfRulesetExist(styleguide.rules);
+
+      styleguide.skipRules(argv['skip-rule']);
+      styleguide.skipPreprocessors(argv['skip-preprocessor']);
+
+      if (styleguide.recommendedFallback) {
+        process.stderr.write(
+          `No configurations were provided -- using built in ${blue(
+            'recommended'
+          )} configuration by default.\n\n`
+        );
+      }
+      process.stderr.write(gray(`validating ${path.replace(process.cwd(), '')}...\n`));
+      const results = await lint({
+        ref: path,
+        config: resolvedConfig,
+      });
+
+      const fileTotals = getTotals(results);
+      totals.errors += fileTotals.errors;
+      totals.warnings += fileTotals.warnings;
+      totals.ignored += fileTotals.ignored;
+
+      if (argv['generate-ignore-file']) {
+        for (const m of results) {
+          config.styleguide.addIgnore(m);
+          totalIgnored++;
+        }
+      } else {
+        formatProblems(results, {
+          format: argv.format,
+          maxProblems: argv['max-problems'],
+          totals: fileTotals,
+          version,
+        });
+      }
+
+      const elapsed = getExecutionTime(startedAt);
+      process.stderr.write(gray(`${path.replace(process.cwd(), '')}: validated in ${elapsed}\n\n`));
+    } catch (e) {
+      handleError(e, path);
+    }
+  }
+
+  if (argv['generate-ignore-file']) {
+    config.styleguide.saveIgnore();
+    process.stderr.write(
+      `Generated ignore file with ${totalIgnored} ${pluralize('problem', totalIgnored)}.\n\n`
+    );
+  } else {
+    printLintTotals(totals, apis.length);
+  }
+
+  printUnusedWarnings(config.styleguide);
+
+  if (!(totals.errors === 0 || argv['generate-ignore-file'])) {
+    throw new Error('Lint failed.');
+  }
+}
+
+export function lintConfigCallback(
+  argv: CommandOptions & Record<string, undefined>,
+  version: string
+) {
+  if (argv['lint-config'] === 'off') {
+    return;
+  }
+
+  if (argv.format === 'json') {
+    // we can't print config lint results as it will break json output
+    return;
+  }
+
+  return async (config: RawConfig) => {
+    const configPath = findConfig(argv.config) || '';
+    const stringYaml = stringifyYaml(config);
+    const configContent = makeDocumentFromString(stringYaml, configPath);
+    const problems = await lintConfig({
+      document: configContent,
+      severity: argv['lint-config'] as ProblemSeverity,
+    });
+
+    const fileTotals = getTotals(problems);
+
+    formatProblems(problems, {
+      format: argv.format,
+      maxProblems: argv['max-problems'],
+      totals: fileTotals,
+      version,
+    });
+
+    printConfigLintTotals(fileTotals);
+  };
+}

package/src/commands/login.ts

@@ -0,0 +1,27 @@
+import { Region, RedoclyClient, Config } from '@redocly/openapi-core';
+import { blue, green, gray } from 'colorette';
+import { promptUser } from '../utils';
+
+export function promptClientToken(domain: string) {
+  return promptUser(
+    green(
+      `\n  🔑 Copy your API key from ${blue(`https://app.${domain}/profile`)} and paste it below`
+    ),
+    true
+  );
+}
+
+export type LoginOptions = {
+  verbose?: boolean;
+  region?: Region;
+  config?: string;
+};
+
+export async function handleLogin(argv: LoginOptions, config: Config) {
+  const region = argv.region || config.region;
+  const client = new RedoclyClient(region);
+  const clientToken = await promptClientToken(client.domain);
+  process.stdout.write(gray('\n  Logging in...\n'));
+  await client.login(clientToken, argv.verbose);
+  process.stdout.write(green('  Authorization confirmed. ✅\n\n'));
+}

package/src/commands/preview-docs/index.ts

@@ -0,0 +1,190 @@
+import * as colorette from 'colorette';
+import * as chockidar from 'chokidar';
+import {
+  bundle,
+  ResolveError,
+  YamlParseError,
+  RedoclyClient,
+  getTotals,
+  getMergedConfig,
+  Config,
+} from '@redocly/openapi-core';
+import { getFallbackApisOrExit, loadConfigAndHandleErrors } from '../../utils';
+import startPreviewServer from './preview-server/preview-server';
+import type { Skips } from '../../types';
+
+export type PreviewDocsOptions = {
+  port: number;
+  host: string;
+  'use-community-edition'?: boolean;
+  config?: string;
+  api?: string;
+  force?: boolean;
+} & Omit<Skips, 'skip-rule'>;
+
+export async function previewDocs(argv: PreviewDocsOptions, configFromFile: Config) {
+  let isAuthorizedWithRedocly = false;
+  let redocOptions: any = {};
+  let config = await reloadConfig(configFromFile);
+
+  const apis = await getFallbackApisOrExit(argv.api ? [argv.api] : [], config);
+  const api = apis[0];
+
+  let cachedBundle: any;
+  const deps = new Set<string>();
+
+  async function getBundle() {
+    return cachedBundle;
+  }
+
+  async function updateBundle() {
+    process.stdout.write('\nBundling...\n\n');
+    try {
+      const {
+        bundle: openapiBundle,
+        problems,
+        fileDependencies,
+      } = await bundle({
+        ref: api.path,
+        config,
+      });
+      const removed = [...deps].filter((x) => !fileDependencies.has(x));
+      watcher.unwatch(removed);
+      watcher.add([...fileDependencies]);
+      deps.clear();
+      fileDependencies.forEach(deps.add, deps);
+
+      const fileTotals = getTotals(problems);
+
+      if (fileTotals.errors === 0) {
+        process.stdout.write(
+          fileTotals.errors === 0
+            ? `Created a bundle for ${api.alias || api.path} ${
+                fileTotals.warnings > 0 ? 'with warnings' : 'successfully'
+              }\n`
+            : colorette.yellow(
+                `Created a bundle for ${
+                  api.alias || api.path
+                } with errors. Docs may be broken or not accurate\n`
+              )
+        );
+      }
+
+      return openapiBundle.parsed;
+    } catch (e) {
+      handleError(e, api.path);
+    }
+  }
+
+  setImmediate(() => {
+    cachedBundle = updateBundle();
+  }); // initial cache
+
+  const isAuthorized = isAuthorizedWithRedocly || redocOptions.licenseKey;
+  if (!isAuthorized) {
+    process.stderr.write(
+      `Using Redoc community edition.\nLogin with redocly ${colorette.blue(
+        'login'
+      )} or use an enterprise license key to preview with the premium docs.\n\n`
+    );
+  }
+
+  const hotClients = await startPreviewServer(argv.port, argv.host, {
+    getBundle,
+    getOptions: () => redocOptions,
+    useRedocPro: isAuthorized && !redocOptions.useCommunityEdition,
+  });
+
+  const watchPaths = [api.path, config.configFile!].filter((e) => !!e);
+  const watcher = chockidar.watch(watchPaths, {
+    disableGlobbing: true,
+    ignoreInitial: true,
+  });
+
+  const debouncedUpdatedBundle = debounce(async () => {
+    cachedBundle = updateBundle();
+    await cachedBundle;
+    hotClients.broadcast('{"type": "reload", "bundle": true}');
+  }, 2000);
+
+  const changeHandler = async (type: string, file: string) => {
+    process.stdout.write(`${colorette.green('watch')} ${type} ${colorette.blue(file)}\n`);
+    if (file === config.configFile) {
+      config = await reloadConfig();
+      hotClients.broadcast(JSON.stringify({ type: 'reload' }));
+      return;
+    }
+
+    debouncedUpdatedBundle();
+  };
+
+  watcher.on('change', changeHandler.bind(undefined, 'changed'));
+  watcher.on('add', changeHandler.bind(undefined, 'added'));
+  watcher.on('unlink', changeHandler.bind(undefined, 'removed'));
+
+  watcher.on('ready', () => {
+    process.stdout.write(
+      `\n  👀  Watching ${colorette.blue(api.path)} and all related resources for changes\n\n`
+    );
+  });
+
+  async function reloadConfig(config?: Config) {
+    if (!config) {
+      try {
+        config = (await loadConfigAndHandleErrors({ configPath: argv.config })) as Config;
+      } catch (err) {
+        config = new Config({ apis: {}, styleguide: {} });
+      }
+    }
+    const redoclyClient = new RedoclyClient();
+    isAuthorizedWithRedocly = await redoclyClient.isAuthorizedWithRedocly();
+    const resolvedConfig = getMergedConfig(config, argv.api);
+    const { styleguide } = resolvedConfig;
+
+    styleguide.skipPreprocessors(argv['skip-preprocessor']);
+    styleguide.skipDecorators(argv['skip-decorator']);
+
+    const referenceDocs = resolvedConfig.theme?.openapi;
+    redocOptions = {
+      ...referenceDocs,
+      useCommunityEdition: argv['use-community-edition'] || referenceDocs?.useCommunityEdition,
+      licenseKey: process.env.REDOCLY_LICENSE_KEY || referenceDocs?.licenseKey,
+      whiteLabel: true,
+    };
+    return resolvedConfig;
+  }
+}
+
+export function debounce(func: Function, wait: number, immediate?: boolean) {
+  let timeout: NodeJS.Timeout | null;
+
+  return function executedFunction(...args: any[]) {
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
+    // eslint-disable-next-line @typescript-eslint/no-this-alias
+    const context = this;
+
+    const later = () => {
+      timeout = null;
+      if (!immediate) func.apply(context, args);
+    };
+
+    const callNow = immediate && !timeout;
+
+    if (timeout) clearTimeout(timeout);
+
+    timeout = setTimeout(later, wait);
+
+    if (callNow) func.apply(context, args);
+  };
+}
+
+function handleError(e: Error, ref: string) {
+  if (e instanceof ResolveError) {
+    process.stderr.write(`Failed to resolve api definition at ${ref}:\n\n  - ${e.message}.\n\n`);
+  } else if (e instanceof YamlParseError) {
+    process.stderr.write(`Failed to parse api definition at ${ref}:\n\n  - ${e.message}.\n\n`);
+  } else {
+    process.stderr.write(`Something went wrong when processing ${ref}:\n\n  - ${e.message}.\n\n`);
+  }
+}

package/src/commands/preview-docs/preview-server/default.hbs

@@ -0,0 +1,24 @@
+
+<!DOCTYPE html>
+<html>
+
+<head>
+  <meta charset="utf8" />
+  <title>{{title}}</title>
+  <!-- needed for adaptive design -->
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <style>
+    body {
+      padding: 0;
+      margin: 0;
+    }
+  </style>
+  {{{redocHead}}}
+  <link href="https://fonts.googleapis.com/css?family=Montserrat:300,400,700|Roboto:300,400,700" rel="stylesheet">
+</head>
+
+<body>
+  {{{redocHTML}}}
+</body>
+
+</html>

package/src/commands/preview-docs/preview-server/hot.js

@@ -0,0 +1,42 @@
+(function run() {
+  const Socket = window.SimpleWebsocket;
+  const port = window.__OPENAPI_CLI_WS_PORT;
+
+  let socket;
+
+  reconnect();
+
+  function reconnect() {
+    socket = new Socket(`ws://127.0.0.1:${port}`);
+    socket.on('connect', () => {
+      socket.send('{"type": "ping"}');
+    });
+
+    socket.on('data', (data) => {
+      const message = JSON.parse(data);
+      switch (message.type) {
+        case 'pong':
+          console.log('[hot] hot reloading connected');
+          break;
+        case 'reload':
+          console.log('[hot] full page reload');
+          window.location.reload();
+          break;
+        default:
+          console.log(`[hot] ${message.type} received`);
+      }
+    });
+
+    socket.on('close', () => {
+      socket.destroy();
+      console.log('Connection lost, trying to reconnect in 4s');
+      setTimeout(() => {
+        reconnect();
+      }, 4000);
+    });
+
+    socket.on('error', () => {
+      socket.destroy();
+    });
+  }
+})();

package/src/commands/preview-docs/preview-server/oauth2-redirect.html

@@ -0,0 +1,21 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1,shrink-to-fit=no" />
+    <title>Redocly Reference Docs: OAuth2 Redirect</title>
+    <style>
+      .user-info {
+        margin: 150px auto auto;
+        width: 50%;
+        background-color: whitesmoke;
+        padding: 20px;
+        text-align: center;
+      }
+    </style>
+  </head>
+  <body>
+    <script src="https://cdn.redoc.ly/reference-docs/latest/oauth2-redirect.js"></script>
+    <noscript>You need to enable JavaScript to run this app.</noscript>
+  </body>
+</html>

package/src/commands/preview-docs/preview-server/preview-server.ts

@@ -0,0 +1,156 @@
+import { compile } from 'handlebars';
+import * as colorette from 'colorette';
+import * as portfinder from 'portfinder';
+import { readFileSync, promises as fsPromises } from 'fs';
+import * as path from 'path';
+
+import { startHttpServer, startWsServer, respondWithGzip, mimeTypes } from './server';
+import type { IncomingMessage } from 'http';
+import { isSubdir } from '../../../utils';
+
+function getPageHTML(
+  htmlTemplate: string,
+  redocOptions: object = {},
+  useRedocPro: boolean,
+  wsPort: number
+) {
+  let templateSrc = readFileSync(htmlTemplate, 'utf-8');
+
+  // fix template for backward compatibility
+  templateSrc = templateSrc
+    .replace(/{?{{redocHead}}}?/, '{{{redocHead}}}')
+    .replace('{{redocBody}}', '{{{redocHTML}}}');
+
+  const template = compile(templateSrc);
+
+  return template({
+    redocHead: `
+  <script>
+    window.__REDOC_EXPORT = '${useRedocPro ? 'RedoclyReferenceDocs' : 'Redoc'}';
+    window.__OPENAPI_CLI_WS_PORT = ${wsPort};
+  </script>
+  <script src="/simplewebsocket.min.js"></script>
+  <script src="/hot.js"></script>
+  <script src="${
+    useRedocPro
+      ? 'https://cdn.redoc.ly/reference-docs/latest/redocly-reference-docs.min.js'
+      : 'https://cdn.redoc.ly/redoc/latest/bundles/redoc.standalone.js'
+  }"></script>
+`,
+    redocHTML: `
+  <div id="redoc"></div>
+  <script>
+    var container = document.getElementById('redoc');
+    ${
+      useRedocPro
+        ? "window[window.__REDOC_EXPORT].setPublicPath('https://cdn.redoc.ly/reference-docs/latest/');"
+        : ''
+    }
+    window[window.__REDOC_EXPORT].init("/openapi.json", ${JSON.stringify(redocOptions)}, container)
+  </script>`,
+  });
+}
+
+export default async function startPreviewServer(
+  port: number,
+  host: string,
+  {
+    getBundle,
+    getOptions,
+    useRedocPro,
+  }: { getBundle: Function; getOptions: Function; useRedocPro: boolean }
+) {
+  const defaultTemplate = path.join(__dirname, 'default.hbs');
+  const handler = async (request: IncomingMessage, response: any) => {
+    console.time(colorette.dim(`GET ${request.url}`));
+    const { htmlTemplate } = getOptions() || {};
+
+    if (request.url?.endsWith('/') || path.extname(request.url!) === '') {
+      respondWithGzip(
+        getPageHTML(htmlTemplate || defaultTemplate, getOptions(), useRedocPro, wsPort),
+        request,
+        response,
+        {
+          'Content-Type': 'text/html',
+        }
+      );
+    } else if (request.url === '/openapi.json') {
+      const bundle = await getBundle();
+      if (bundle === undefined) {
+        respondWithGzip(
+          JSON.stringify({
+            openapi: '3.0.0',
+            info: {
+              description:
+                '<code> Failed to generate bundle: check out console output for more details </code>',
+            },
+            paths: {},
+          }),
+          request,
+          response,
+          {
+            'Content-Type': 'application/json',
+          }
+        );
+      } else {
+        respondWithGzip(JSON.stringify(bundle), request, response, {
+          'Content-Type': 'application/json',
+        });
+      }
+    } else {
+      let filePath =
+        // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+        // @ts-ignore
+        {
+          '/hot.js': path.join(__dirname, 'hot.js'),
+          '/oauth2-redirect.html': path.join(__dirname, 'oauth2-redirect.html'),
+          '/simplewebsocket.min.js': require.resolve('simple-websocket/simplewebsocket.min.js'),
+        }[request.url || ''];
+
+      if (!filePath) {
+        const basePath = htmlTemplate ? path.dirname(htmlTemplate) : process.cwd();
+
+        filePath = path.resolve(basePath, `.${request.url}`);
+
+        if (!isSubdir(basePath, filePath)) {
+          respondWithGzip('404 Not Found', request, response, { 'Content-Type': 'text/html' }, 404);
+          console.timeEnd(colorette.dim(`GET ${request.url}`));
+          return;
+        }
+      }
+
+      const extname = String(path.extname(filePath)).toLowerCase() as keyof typeof mimeTypes;
+
+      const contentType = mimeTypes[extname] || 'application/octet-stream';
+      try {
+        respondWithGzip(await fsPromises.readFile(filePath), request, response, {
+          'Content-Type': contentType,
+        });
+      } catch (e) {
+        if (e.code === 'ENOENT') {
+          respondWithGzip('404 Not Found', request, response, { 'Content-Type': 'text/html' }, 404);
+        } else {
+          respondWithGzip(
+            `Something went wrong: ${e.code || e.message}...\n`,
+            request,
+            response,
+            {},
+            500
+          );
+        }
+      }
+    }
+    console.timeEnd(colorette.dim(`GET ${request.url}`));
+  };
+
+  const wsPort = await portfinder.getPortPromise({ port: 32201 });
+
+  const server = startHttpServer(port, host, handler);
+  server.on('listening', () => {
+    process.stdout.write(
+      `\n  🔎  Preview server running at ${colorette.blue(`http://${host}:${port}\n`)}`
+    );
+  });
+
+  return startWsServer(wsPort);
+}

package/src/commands/preview-docs/preview-server/server.ts

@@ -0,0 +1,91 @@
+import * as http from 'http';
+import * as zlib from 'zlib';
+import { ReadStream } from 'fs';
+
+const SocketServer = require('simple-websocket/server.js');
+
+export const mimeTypes = {
+  '.html': 'text/html',
+  '.js': 'text/javascript',
+  '.css': 'text/css',
+  '.json': 'application/json',
+  '.png': 'image/png',
+  '.jpg': 'image/jpg',
+  '.gif': 'image/gif',
+  '.svg': 'image/svg+xml',
+  '.wav': 'audio/wav',
+  '.mp4': 'video/mp4',
+  '.woff': 'application/font-woff',
+  '.ttf': 'application/font-ttf',
+  '.eot': 'application/vnd.ms-fontobject',
+  '.otf': 'application/font-otf',
+  '.wasm': 'application/wasm',
+};
+
+// credits: https://stackoverflow.com/a/9238214/1749888
+export function respondWithGzip(
+  contents: string | Buffer | ReadStream,
+  request: http.IncomingMessage,
+  response: http.ServerResponse,
+  headers = {},
+  code = 200
+) {
+  let compressedStream;
+  const acceptEncoding = (request.headers['accept-encoding'] as string) || '';
+  if (acceptEncoding.match(/\bdeflate\b/)) {
+    response.writeHead(code, { ...headers, 'content-encoding': 'deflate' });
+    compressedStream = zlib.createDeflate();
+  } else if (acceptEncoding.match(/\bgzip\b/)) {
+    response.writeHead(code, { ...headers, 'content-encoding': 'gzip' });
+    compressedStream = zlib.createGzip();
+  } else {
+    response.writeHead(code, headers);
+    if (typeof contents === 'string' || Buffer.isBuffer(contents)) {
+      response.write(contents);
+      response.end();
+    } else if (response !== undefined) {
+      contents.pipe(response);
+    }
+    return;
+  }
+
+  if (typeof contents === 'string' || Buffer.isBuffer(contents)) {
+    compressedStream.write(contents);
+    compressedStream.pipe(response);
+    compressedStream.end();
+  } else {
+    contents.pipe(compressedStream).pipe(response);
+  }
+}
+
+export function startHttpServer(port: number, host: string, handler: http.RequestListener) {
+  return http.createServer(handler).listen(port, host);
+}
+
+export function startWsServer(port: number) {
+  const socketServer = new SocketServer({ port, clientTracking: true });
+
+  socketServer.on('connection', (socket: any) => {
+    socket.on('data', (data: string) => {
+      const message = JSON.parse(data);
+      switch (message.type) {
+        case 'ping':
+          socket.send('{"type": "pong"}');
+          break;
+        default:
+        // nope
+      }
+    });
+  });
+
+  socketServer.broadcast = (message: string) => {
+    socketServer._server.clients.forEach((client: any) => {
+      if (client.readyState === 1) {
+        // OPEN
+        client.send(message);
+      }
+    });
+  };
+
+  return socketServer;
+}