@redocly/cli 1.3.0 → 1.4.0

package/src/__tests__/commands/join.test.ts

@@ -1,11 +1,12 @@
 import { handleJoin } from '../../commands/join';
-import { exitWithError, writeYaml } from '../../utils';
+import { exitWithError, writeToFileByExtension, writeYaml } from '../../utils';
 import { yellow } from 'colorette';
 import { detectSpec } from '@redocly/openapi-core';
 import { loadConfig } from '../../__mocks__/@redocly/openapi-core';
 import { ConfigFixture } from '../fixtures/config';
 
 jest.mock('../../utils');
+
 jest.mock('colorette');
 
 describe('handleJoin fails', () => {
@@ -80,7 +81,7 @@ describe('handleJoin fails', () => {
     );
   });
 
-  it('should call writeYaml function', async () => {
+  it('should call writeToFileByExtension function', async () => {
     (detectSpec as jest.Mock).mockReturnValue('oas3_0');
     await handleJoin(
       {
@@ -90,10 +91,14 @@ describe('handleJoin fails', () => {
       'cli-version'
     );
 
-    expect(writeYaml).toHaveBeenCalledWith(expect.any(Object), 'openapi.yaml', expect.any(Boolean));
+    expect(writeToFileByExtension).toHaveBeenCalledWith(
+      expect.any(Object),
+      'openapi.yaml',
+      expect.any(Boolean)
+    );
   });
 
-  it('should call writeYaml function for OpenAPI 3.1', async () => {
+  it('should call writeToFileByExtension function for OpenAPI 3.1', async () => {
     (detectSpec as jest.Mock).mockReturnValue('oas3_1');
     await handleJoin(
       {
@@ -103,10 +108,14 @@ describe('handleJoin fails', () => {
       'cli-version'
     );
 
-    expect(writeYaml).toHaveBeenCalledWith(expect.any(Object), 'openapi.yaml', expect.any(Boolean));
+    expect(writeToFileByExtension).toHaveBeenCalledWith(
+      expect.any(Object),
+      'openapi.yaml',
+      expect.any(Boolean)
+    );
   });
 
-  it('should call writeYaml function with custom output file', async () => {
+  it('should call writeToFileByExtension function with custom output file', async () => {
     (detectSpec as jest.Mock).mockReturnValue('oas3_0');
     await handleJoin(
       {
@@ -117,7 +126,28 @@ describe('handleJoin fails', () => {
       'cli-version'
     );
 
-    expect(writeYaml).toHaveBeenCalledWith(expect.any(Object), 'output.yml', expect.any(Boolean));
+    expect(writeToFileByExtension).toHaveBeenCalledWith(
+      expect.any(Object),
+      'output.yml',
+      expect.any(Boolean)
+    );
+  });
+
+  it('should call writeToFileByExtension function with json file extension', async () => {
+    (detectSpec as jest.Mock).mockReturnValue('oas3_0');
+    await handleJoin(
+      {
+        apis: ['first.json', 'second.yaml'],
+      },
+      ConfigFixture as any,
+      'cli-version'
+    );
+
+    expect(writeToFileByExtension).toHaveBeenCalledWith(
+      expect.any(Object),
+      'openapi.json',
+      expect.any(Boolean)
+    );
   });
 
   it('should call skipDecorators and skipPreprocessors', async () => {

package/src/__tests__/utils.test.ts

@@ -12,6 +12,10 @@ import {
   HandledError,
   cleanArgs,
   cleanRawInput,
+  getAndValidateFileExtension,
+  writeYaml,
+  writeJson,
+  writeToFileByExtension,
 } from '../utils';
 import {
   ResolvedApi,
@@ -19,11 +23,13 @@ import {
   isAbsoluteUrl,
   ResolveError,
   YamlParseError,
+  stringifyYaml,
 } from '@redocly/openapi-core';
 import { blue, red, yellow } from 'colorette';
-import { existsSync, statSync } from 'fs';
+import { existsSync, statSync, writeFileSync } from 'fs';
 import * as path from 'path';
 import * as process from 'process';
+import * as utils from '../utils';
 
 jest.mock('os');
 jest.mock('colorette');
@@ -554,4 +560,42 @@ describe('cleanRawInput', () => {
       'redocly lint file-json --format stylish --extends=minimal --skip-rule operation-4xx-response'
     );
   });
+
+  describe('validateFileExtension', () => {
+    it('should return current file extension', () => {
+      expect(getAndValidateFileExtension('test.json')).toEqual('json');
+    });
+
+    it('should return yaml and print warning if file extension does not supported', () => {
+      const stderrMock = jest.spyOn(process.stderr, 'write').mockImplementation(() => true);
+      (yellow as jest.Mock<any, any>).mockImplementation((text: string) => text);
+
+      expect(getAndValidateFileExtension('test.xml')).toEqual('yaml');
+      expect(stderrMock).toHaveBeenCalledWith(`Unsupported file extension: xml. Using yaml.\n`);
+    });
+  });
+
+  describe('writeToFileByExtension', () => {
+    beforeEach(() => {
+      jest.spyOn(process.stderr, 'write').mockImplementation(jest.fn());
+      (yellow as jest.Mock<any, any>).mockImplementation((text: string) => text);
+    });
+
+    afterEach(() => {
+      jest.restoreAllMocks();
+    });
+
+    it('should call stringifyYaml function', () => {
+      writeToFileByExtension('test data', 'test.yaml');
+      expect(stringifyYaml).toHaveBeenCalledWith('test data', { noRefs: false });
+      expect(process.stderr.write).toHaveBeenCalledWith(`test data`);
+    });
+
+    it('should call JSON.stringify function', () => {
+      const stringifySpy = jest.spyOn(JSON, 'stringify').mockImplementation((data) => data);
+      writeToFileByExtension('test data', 'test.json');
+      expect(stringifySpy).toHaveBeenCalledWith('test data', null, 2);
+      expect(process.stderr.write).toHaveBeenCalledWith(`test data`);
+    });
+  });
 });

package/src/commands/join.ts

@@ -25,9 +25,10 @@ import {
   printExecutionTime,
   handleError,
   printLintTotals,
-  writeYaml,
   exitWithError,
   sortTopLevelKeysForOas,
+  getAndValidateFileExtension,
+  writeToFileByExtension,
 } from '../utils';
 import { isObject, isString, keysOf } from '../js-utils';
 import {
@@ -70,16 +71,19 @@ export type JoinOptions = {
 
 export async function handleJoin(argv: JoinOptions, config: Config, packageVersion: string) {
   const startedAt = performance.now();
+
   if (argv.apis.length < 2) {
     return exitWithError(`At least 2 apis should be provided. \n\n`);
   }
 
+  const fileExtension = getAndValidateFileExtension(argv.output || argv.apis[0]);
+
   const {
     'prefix-components-with-info-prop': prefixComponentsWithInfoProp,
     'prefix-tags-with-filename': prefixTagsWithFilename,
     'prefix-tags-with-info-prop': prefixTagsWithInfoProp,
     'without-x-tag-groups': withoutXTagGroups,
-    output: specFilename = 'openapi.yaml',
+    output: specFilename = `openapi.${fileExtension}`,
   } = argv;
 
   const usedTagsOptions = [
@@ -229,7 +233,8 @@ export async function handleJoin(argv: JoinOptions, config: Config, packageVersi
     return exitWithError(`Please fix conflicts before running ${yellow('join')}.`);
   }
 
-  writeYaml(sortTopLevelKeysForOas(joinedDef), specFilename, noRefs);
+  writeToFileByExtension(sortTopLevelKeysForOas(joinedDef), specFilename, noRefs);
+
   printExecutionTime('join', startedAt, specFilename);
 
   function populateTags({

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

@@ -127,7 +127,6 @@ yargs
             describe: 'Output file',
             alias: 'o',
             type: 'string',
-            default: 'openapi.yaml',
           },
           config: {
             description: 'Path to the config file.',

package/src/utils.ts

@@ -25,7 +25,14 @@ import {
   RedoclyClient,
 } from '@redocly/openapi-core';
 import { ConfigValidationError } from '@redocly/openapi-core/lib/config';
-import { Totals, outputExtensions, Entrypoint, ConfigApis, CommandOptions } from './types';
+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';
@@ -209,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 });
 
@@ -220,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(' ');