@redocly/cli 1.2.1 → 1.4.0

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

@@ -1,13 +1,29 @@
 (function run() {
   const Socket = window.SimpleWebsocket;
   const port = window.__OPENAPI_CLI_WS_PORT;
+  const host = window.__OPENAPI_CLI_WS_HOST;
 
   let socket;
 
   reconnect();
 
+  function getFormattedHost() {
+    // Use localhost when bound to all interfaces
+    if (host === '::' || host === '0.0.0.0') {
+      return 'localhost';
+    }
+
+    // Other IPv6 addresses must be wrapped in brackets
+    if (host.includes('::')) {
+      return `[${host}]`;
+    }
+
+    // Otherwise return as-is
+    return host;
+  }
+
   function reconnect() {
-    socket = new Socket(`ws://127.0.0.1:${port}`);
+    socket = new Socket(`ws://${getFormattedHost()}:${port}`);
     socket.on('connect', () => {
       socket.send('{"type": "ping"}');
     });
@@ -29,13 +45,14 @@
 
     socket.on('close', () => {
       socket.destroy();
-      console.log('Connection lost, trying to reconnect in 4s');
+      console.log('[hot] Connection lost, trying to reconnect in 4s');
       setTimeout(() => {
         reconnect();
       }, 4000);
     });
 
     socket.on('error', () => {
+      console.log('[hot] Error connecting to hot reloading server');
       socket.destroy();
     });
   }

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

@@ -12,7 +12,8 @@ function getPageHTML(
   htmlTemplate: string,
   redocOptions: object = {},
   useRedocPro: boolean,
-  wsPort: number
+  wsPort: number,
+  host: string
 ) {
   let templateSrc = readFileSync(htmlTemplate, 'utf-8');
 
@@ -28,6 +29,7 @@ function getPageHTML(
   <script>
     window.__REDOC_EXPORT = '${useRedocPro ? 'RedoclyReferenceDocs' : 'Redoc'}';
     window.__OPENAPI_CLI_WS_PORT = ${wsPort};
+    window.__OPENAPI_CLI_WS_HOST = "${host}";
   </script>
   <script src="/simplewebsocket.min.js"></script>
   <script src="/hot.js"></script>
@@ -67,7 +69,7 @@ export default async function startPreviewServer(
 
     if (request.url?.endsWith('/') || path.extname(request.url!) === '') {
       respondWithGzip(
-        getPageHTML(htmlTemplate || defaultTemplate, getOptions(), useRedocPro, wsPort),
+        getPageHTML(htmlTemplate || defaultTemplate, getOptions(), useRedocPro, wsPort, host),
         request,
         response,
         {
@@ -143,7 +145,7 @@ export default async function startPreviewServer(
     console.timeEnd(colorette.dim(`GET ${request.url}`));
   };
 
-  const wsPort = await getPort({ portRange: [32201, 32301] });
+  const wsPort = await getPort({ port: 32201, portRange: [32201, 32301], host });
 
   const server = startHttpServer(port, host, handler);
   server.on('listening', () => {
@@ -152,5 +154,5 @@ export default async function startPreviewServer(
     );
   });
 
-  return startWsServer(wsPort);
+  return startWsServer(wsPort, host);
 }

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

@@ -62,8 +62,8 @@ export function startHttpServer(port: number, host: string, handler: http.Reques
   return http.createServer(handler).listen(port, host);
 }
 
-export function startWsServer(port: number) {
-  const socketServer = new SocketServer({ port, clientTracking: true });
+export function startWsServer(port: number, host: string) {
+  const socketServer = new SocketServer({ port, host, clientTracking: true });
 
   socketServer.on('connection', (socket: any) => {
     socket.on('data', (data: string) => {

package/src/commands/split/__tests__/index.test.ts

@@ -3,12 +3,13 @@ import * as path from 'path';
 import * as openapiCore from '@redocly/openapi-core';
 import { ComponentsFiles } from '../types';
 import { blue, green } from 'colorette';
+import { writeToFileByExtension } from '../../../utils';
 
 const utils = require('../../../utils');
 
 jest.mock('../../../utils', () => ({
   ...jest.requireActual('../../../utils'),
-  writeYaml: jest.fn(),
+  writeToFileByExtension: jest.fn(),
 }));
 
 jest.mock('@redocly/openapi-core', () => ({
@@ -65,7 +66,9 @@ describe('#split', () => {
       openapiDir,
       path.join(openapiDir, 'paths'),
       componentsFiles,
-      '_'
+      '_',
+      undefined,
+      'yaml'
     );
 
     expect(openapiCore.slash).toHaveBeenCalledWith('paths/test.yaml');
@@ -82,7 +85,9 @@ describe('#split', () => {
       openapiDir,
       path.join(openapiDir, 'webhooks'),
       componentsFiles,
-      'webhook_'
+      'webhook_',
+      undefined,
+      'yaml'
     );
 
     expect(openapiCore.slash).toHaveBeenCalledWith('webhooks/test.yaml');
@@ -99,7 +104,9 @@ describe('#split', () => {
       openapiDir,
       path.join(openapiDir, 'webhooks'),
       componentsFiles,
-      'webhook_'
+      'webhook_',
+      undefined,
+      'yaml'
     );
 
     expect(openapiCore.slash).toHaveBeenCalledWith('webhooks/test.yaml');
@@ -118,7 +125,9 @@ describe('#split', () => {
       openapiDir,
       path.join(openapiDir, 'paths'),
       componentsFiles,
-      '_'
+      '_',
+      undefined,
+      'yaml'
     );
 
     expect(utils.escapeLanguageName).nthCalledWith(1, 'C#');

package/src/commands/split/index.ts

@@ -10,10 +10,11 @@ import {
   printExecutionTime,
   pathToFilename,
   readYaml,
-  writeYaml,
   exitWithError,
   escapeLanguageName,
   langToExt,
+  writeToFileByExtension,
+  getAndValidateFileExtension,
 } from '../../utils';
 import { isString, isObject, isEmptyObject } from '../../js-utils';
 import {
@@ -46,8 +47,9 @@ export async function handleSplit(argv: SplitOptions) {
   const startedAt = performance.now();
   const { api, outDir, separator } = argv;
   validateDefinitionFileName(api!);
+  const ext = getAndValidateFileExtension(api);
   const openapi = readYaml(api!) as Oas3Definition | Oas3_1Definition;
-  splitDefinition(openapi, outDir, separator);
+  splitDefinition(openapi, outDir, separator, ext);
   process.stderr.write(
     `🪓 Document: ${blue(api!)} ${green('is successfully split')}
     and all related files are saved to the directory: ${blue(outDir)} \n`
@@ -58,18 +60,21 @@ export async function handleSplit(argv: SplitOptions) {
 function splitDefinition(
   openapi: Oas3Definition | Oas3_1Definition,
   openapiDir: string,
-  pathSeparator: string
+  pathSeparator: string,
+  ext: string
 ) {
   fs.mkdirSync(openapiDir, { recursive: true });
 
   const componentsFiles: ComponentsFiles = {};
-  iterateComponents(openapi, openapiDir, componentsFiles);
+  iterateComponents(openapi, openapiDir, componentsFiles, ext);
   iteratePathItems(
     openapi.paths,
     openapiDir,
     path.join(openapiDir, 'paths'),
     componentsFiles,
-    pathSeparator
+    pathSeparator,
+    undefined,
+    ext
   );
   const webhooks =
     (openapi as Oas3_1Definition).webhooks || (openapi as Oas3Definition)['x-webhooks'];
@@ -80,11 +85,12 @@ function splitDefinition(
     path.join(openapiDir, 'webhooks'),
     componentsFiles,
     pathSeparator,
-    'webhook_'
+    'webhook_',
+    ext
   );
 
   replace$Refs(openapi, openapiDir, componentsFiles);
-  writeYaml(openapi, path.join(openapiDir, 'openapi.yaml'));
+  writeToFileByExtension(openapi, path.join(openapiDir, `openapi.${ext}`));
 }
 
 function isStartsWithComponents(node: string) {
@@ -135,7 +141,7 @@ function traverseDirectoryDeepCallback(
   if (isNotYaml(filename)) return;
   const pathData = readYaml(filename);
   replace$Refs(pathData, directory, componentsFiles);
-  writeYaml(pathData, filename);
+  writeToFileByExtension(pathData, filename);
 }
 
 function crawl(object: any, visitor: any) {
@@ -251,8 +257,8 @@ function extractFileNameFromPath(filename: string) {
   return path.basename(filename, path.extname(filename));
 }
 
-function getFileNamePath(componentDirPath: string, componentName: string) {
-  return path.join(componentDirPath, componentName) + '.yaml';
+function getFileNamePath(componentDirPath: string, componentName: string, ext: string) {
+  return path.join(componentDirPath, componentName) + `.${ext}`;
 }
 
 function gatherComponentsFiles(
@@ -278,13 +284,14 @@ function iteratePathItems(
   outDir: string,
   componentsFiles: object,
   pathSeparator: string,
-  codeSamplesPathPrefix: string = ''
+  codeSamplesPathPrefix: string = '',
+  ext: string
 ) {
   if (!pathItems) return;
   fs.mkdirSync(outDir, { recursive: true });
 
   for (const pathName of Object.keys(pathItems)) {
-    const pathFile = `${path.join(outDir, pathToFilename(pathName, pathSeparator))}.yaml`;
+    const pathFile = `${path.join(outDir, pathToFilename(pathName, pathSeparator))}.${ext}`;
     const pathData = pathItems[pathName] as Oas3PathItem;
 
     if (isRef(pathData)) continue;
@@ -314,7 +321,7 @@ function iteratePathItems(
         };
       }
     }
-    writeYaml(pathData, pathFile);
+    writeToFileByExtension(pathData, pathFile);
     pathItems[pathName] = {
       $ref: slash(path.relative(openapiDir, pathFile)),
     };
@@ -326,7 +333,8 @@ function iteratePathItems(
 function iterateComponents(
   openapi: Oas3Definition | Oas3_1Definition,
   openapiDir: string,
-  componentsFiles: ComponentsFiles
+  componentsFiles: ComponentsFiles,
+  ext: string
 ) {
   const { components } = openapi;
   if (components) {
@@ -340,7 +348,7 @@ function iterateComponents(
     function iterateAndGatherComponentsFiles(componentType: Oas3ComponentName) {
       const componentDirPath = path.join(componentsDir, componentType);
       for (const componentName of Object.keys(components?.[componentType] || {})) {
-        const filename = getFileNamePath(componentDirPath, componentName);
+        const filename = getFileNamePath(componentDirPath, componentName, ext);
         gatherComponentsFiles(components!, componentsFiles, componentType, componentName, filename);
       }
     }
@@ -350,7 +358,7 @@ function iterateComponents(
       const componentDirPath = path.join(componentsDir, componentType);
       createComponentDir(componentDirPath, componentType);
       for (const componentName of Object.keys(components?.[componentType] || {})) {
-        const filename = getFileNamePath(componentDirPath, componentName);
+        const filename = getFileNamePath(componentDirPath, componentName, ext);
         const componentData = components?.[componentType]?.[componentName];
         replace$Refs(componentData, path.dirname(filename), componentsFiles);
         implicitlyReferenceDiscriminator(
@@ -369,7 +377,7 @@ function iterateComponents(
             )
           );
         } else {
-          writeYaml(componentData, filename);
+          writeToFileByExtension(componentData, filename);
         }
 
         if (isNotSecurityComponentType(componentType)) {

package/src/fetch-with-timeout.ts

@@ -12,6 +12,9 @@ export default async (url: string, options = {}) => {
       controller.abort();
     }, TIMEOUT);
 
+    // FIXME: fix this (possibly along with this issue: https://github.com/Redocly/redocly-cli/issues/1260)
+    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
+    // @ts-ignore
     const res = await nodeFetch(url, { signal: controller.signal, ...options });
     clearTimeout(timeout);
     return res;

package/src/index.ts

@@ -36,6 +36,11 @@ yargs
     (yargs) =>
       yargs.positional('api', { type: 'string' }).option({
         config: { description: 'Path to the config file.', type: 'string' },
+        'lint-config': {
+          description: 'Severity level for config file linting.',
+          choices: ['warn', 'error', 'off'] as ReadonlyArray<RuleSeverity>,
+          default: 'warn' as RuleSeverity,
+        },
         format: {
           description: 'Use a specific output format.',
           choices: ['stylish', 'json'] as ReadonlyArray<OutputFormat>,
@@ -73,6 +78,11 @@ yargs
             requiresArg: true,
             type: 'string',
           },
+          'lint-config': {
+            description: 'Severity level for config file linting.',
+            choices: ['warn', 'error', 'off'] as ReadonlyArray<RuleSeverity>,
+            default: 'warn' as RuleSeverity,
+          },
         })
         .demandOption('api'),
     (argv) => {
@@ -117,13 +127,17 @@ yargs
             describe: 'Output file',
             alias: 'o',
             type: 'string',
-            default: 'openapi.yaml',
           },
           config: {
             description: 'Path to the config file.',
             requiresArg: true,
             type: 'string',
           },
+          'lint-config': {
+            description: 'Severity level for config file linting.',
+            choices: ['warn', 'error', 'off'] as ReadonlyArray<RuleSeverity>,
+            default: 'warn' as RuleSeverity,
+          },
         }),
     (argv) => {
       process.env.REDOCLY_CLI_COMMAND = 'join';
@@ -196,6 +210,11 @@ yargs
             array: true,
             type: 'string',
           },
+          'lint-config': {
+            description: 'Severity level for config file linting.',
+            choices: ['warn', 'error', 'off'] as ReadonlyArray<RuleSeverity>,
+            default: 'warn' as RuleSeverity,
+          },
         })
         .deprecateOption('batch-id', 'use --job-id')
         .deprecateOption('maybeDestination')
@@ -342,6 +361,11 @@ yargs
           type: 'boolean',
           alias: 'k',
         },
+        'lint-config': {
+          description: 'Severity level for config file linting.',
+          choices: ['warn', 'error', 'off'] as ReadonlyArray<RuleSeverity>,
+          default: 'warn' as RuleSeverity,
+        },
       }),
     (argv) => {
       process.env.REDOCLY_CLI_COMMAND = 'bundle';
@@ -426,6 +450,11 @@ yargs
           description: 'Path to the config file.',
           type: 'string',
         },
+        'lint-config': {
+          description: 'Severity level for config file linting.',
+          choices: ['warn', 'error', 'off'] as ReadonlyArray<RuleSeverity>,
+          default: 'warn' as RuleSeverity,
+        },
       }),
     (argv) => {
       process.env.REDOCLY_CLI_COMMAND = 'preview-docs';
@@ -471,6 +500,11 @@ yargs
             describe: 'Path to the config file.',
             type: 'string',
           },
+          'lint-config': {
+            description: 'Severity level for config file linting.',
+            choices: ['warn', 'error', 'off'] as ReadonlyArray<RuleSeverity>,
+            default: 'warn' as RuleSeverity,
+          },
         })
         .check((argv: any) => {
           if (argv.theme && !argv.theme?.openapi)

package/src/utils.ts

@@ -24,7 +24,15 @@ import {
   Oas2Definition,
   RedoclyClient,
 } from '@redocly/openapi-core';
-import { Totals, outputExtensions, Entrypoint, ConfigApis, CommandOptions } from './types';
+import { ConfigValidationError } from '@redocly/openapi-core/lib/config';
+import {
+  Totals,
+  outputExtensions,
+  Entrypoint,
+  ConfigApis,
+  CommandOptions,
+  OutputExtensions,
+} from './types';
 import { isEmptyObject } from '@redocly/openapi-core/lib/utils';
 import { Arguments } from 'yargs';
 import { version } from './update-version-notifier';
@@ -208,6 +216,17 @@ export function readYaml(filename: string) {
   return parseYaml(fs.readFileSync(filename, 'utf-8'), { filename });
 }
 
+export function writeToFileByExtension(data: unknown, filePath: string, noRefs?: boolean) {
+  const ext = getAndValidateFileExtension(filePath);
+
+  if (ext === 'json') {
+    writeJson(data, filePath);
+    return;
+  }
+
+  writeYaml(data, filePath, noRefs);
+}
+
 export function writeYaml(data: any, filename: string, noRefs = false) {
   const content = stringifyYaml(data, { noRefs });
 
@@ -219,6 +238,27 @@ export function writeYaml(data: any, filename: string, noRefs = false) {
   fs.writeFileSync(filename, content);
 }
 
+export function writeJson(data: unknown, filename: string) {
+  const content = JSON.stringify(data, null, 2);
+
+  if (process.env.NODE_ENV === 'test') {
+    process.stderr.write(content);
+    return;
+  }
+  fs.mkdirSync(dirname(filename), { recursive: true });
+  fs.writeFileSync(filename, content);
+}
+
+export function getAndValidateFileExtension(fileName: string): NonNullable<OutputExtensions> {
+  const ext = fileName.split('.').pop();
+
+  if (['yaml', 'yml', 'json'].includes(ext!)) {
+    return ext as NonNullable<OutputExtensions>;
+  }
+  process.stderr.write(yellow(`Unsupported file extension: ${ext}. Using yaml.\n`));
+  return 'yaml';
+}
+
 export function pluralize(label: string, num: number) {
   if (label.endsWith('is')) {
     [label] = label.split(' ');
@@ -244,6 +284,8 @@ export function handleError(e: Error, ref: string) {
     }
     case SyntaxError:
       return exitWithError(`Syntax error: ${e.message} ${e.stack?.split('\n\n')?.[0]}`);
+    case ConfigValidationError:
+      return exitWithError(e.message);
     default: {
       exitWithError(`Something went wrong when processing ${ref}:\n\n  - ${e.message}.`);
     }
@@ -294,17 +336,11 @@ export function printLintTotals(totals: Totals, definitionsCount: number) {
 export function printConfigLintTotals(totals: Totals): void {
   if (totals.errors > 0) {
     process.stderr.write(
-      red(
-        `❌ Your config has ${totals.errors} ${pluralize('error', totals.errors)}${
-          totals.warnings > 0
-            ? ` and ${totals.warnings} ${pluralize('warning', totals.warnings)}`
-            : ''
-        }.\n`
-      )
+      red(`❌ Your config has ${totals.errors} ${pluralize('error', totals.errors)}.`)
     );
   } else if (totals.warnings > 0) {
     process.stderr.write(
-      yellow(`You have ${totals.warnings} ${pluralize('warning', totals.warnings)}.\n`)
+      yellow(`⚠️ Your config has ${totals.warnings} ${pluralize('warning', totals.warnings)}.\n`)
     );
   }
 }