@redocly/cli 1.0.2 → 1.2.0

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

@@ -1,7 +1,7 @@
 import { handleJoin } from '../../commands/join';
 import { exitWithError, writeYaml } from '../../utils';
 import { yellow } from 'colorette';
-import { detectOpenAPI } from '@redocly/openapi-core';
+import { detectSpec } from '@redocly/openapi-core';
 import { loadConfig } from '../../__mocks__/@redocly/openapi-core';
 import { ConfigFixture } from '../fixtures/config';
 
@@ -50,7 +50,7 @@ describe('handleJoin fails', () => {
     );
   });
 
-  it('should call exitWithError because Only OpenAPI 3 is supported', async () => {
+  it('should call exitWithError because Only OpenAPI 3.0 and OpenAPI 3.1 are supported', async () => {
     await handleJoin(
       {
         apis: ['first.yaml', 'second.yaml'],
@@ -58,11 +58,43 @@ describe('handleJoin fails', () => {
       ConfigFixture as any,
       'cli-version'
     );
-    expect(exitWithError).toHaveBeenCalledWith('Only OpenAPI 3 is supported: undefined \n\n');
+    expect(exitWithError).toHaveBeenCalledWith(
+      'Only OpenAPI 3.0 and OpenAPI 3.1 are supported: undefined \n\n'
+    );
+  });
+
+  it('should call exitWithError if mixing OpenAPI 3.0 and 3.1', async () => {
+    (detectSpec as jest.Mock)
+      .mockImplementationOnce(() => 'oas3_0')
+      .mockImplementationOnce(() => 'oas3_1');
+    await handleJoin(
+      {
+        apis: ['first.yaml', 'second.yaml'],
+      },
+      ConfigFixture as any,
+      'cli-version'
+    );
+
+    expect(exitWithError).toHaveBeenCalledWith(
+      'All APIs must use the same OpenAPI version: undefined \n\n'
+    );
   });
 
   it('should call writeYaml function', async () => {
-    (detectOpenAPI as jest.Mock).mockReturnValue('oas3_0');
+    (detectSpec as jest.Mock).mockReturnValue('oas3_0');
+    await handleJoin(
+      {
+        apis: ['first.yaml', 'second.yaml'],
+      },
+      ConfigFixture as any,
+      'cli-version'
+    );
+
+    expect(writeYaml).toHaveBeenCalledWith(expect.any(Object), 'openapi.yaml', expect.any(Boolean));
+  });
+
+  it('should call writeYaml function for OpenAPI 3.1', async () => {
+    (detectSpec as jest.Mock).mockReturnValue('oas3_1');
     await handleJoin(
       {
         apis: ['first.yaml', 'second.yaml'],
@@ -75,7 +107,7 @@ describe('handleJoin fails', () => {
   });
 
   it('should call writeYaml function with custom output file', async () => {
-    (detectOpenAPI as jest.Mock).mockReturnValue('oas3_0');
+    (detectSpec as jest.Mock).mockReturnValue('oas3_0');
     await handleJoin(
       {
         apis: ['first.yaml', 'second.yaml'],
@@ -89,7 +121,7 @@ describe('handleJoin fails', () => {
   });
 
   it('should call skipDecorators and skipPreprocessors', async () => {
-    (detectOpenAPI as jest.Mock).mockReturnValue('oas3_0');
+    (detectSpec as jest.Mock).mockReturnValue('oas3_0');
     await handleJoin(
       {
         apis: ['first.yaml', 'second.yaml'],
@@ -104,7 +136,7 @@ describe('handleJoin fails', () => {
   });
 
   it('should not call skipDecorators and skipPreprocessors', async () => {
-    (detectOpenAPI as jest.Mock).mockReturnValue('oas3_0');
+    (detectSpec as jest.Mock).mockReturnValue('oas3_0');
     await handleJoin(
       {
         apis: ['first.yaml', 'second.yaml'],

package/src/__tests__/utils.test.ts

@@ -406,7 +406,7 @@ describe('handleErrors', () => {
     expect(() => handleError(resolveError, ref)).toThrowError(HandledError);
     expect(redColoretteMocks).toHaveBeenCalledTimes(1);
     expect(process.stderr.write).toHaveBeenCalledWith(
-      `Failed to resolve api definition at openapi/test.yaml:\n\n  - File not found.\n\n`
+      `Failed to resolve API description at openapi/test.yaml:\n\n  - File not found.\n\n`
     );
   });
 
@@ -415,7 +415,7 @@ describe('handleErrors', () => {
     expect(() => handleError(yamlParseError, ref)).toThrowError(HandledError);
     expect(redColoretteMocks).toHaveBeenCalledTimes(1);
     expect(process.stderr.write).toHaveBeenCalledWith(
-      `Failed to parse api definition at openapi/test.yaml:\n\n  - Invalid yaml.\n\n`
+      `Failed to parse API description at openapi/test.yaml:\n\n  - Invalid yaml.\n\n`
     );
   });
 
@@ -460,6 +460,7 @@ describe('checkIfRulesetExist', () => {
       oas2: {},
       oas3_0: {},
       oas3_1: {},
+      async2: {},
     };
     expect(() => checkIfRulesetExist(rules)).toThrowError(
       '⚠️ No rules were configured. Learn how to configure rules: https://redocly.com/docs/cli/rules/'

package/src/assert-node-version.ts

@@ -1,8 +1,19 @@
+import * as semver from 'semver';
 import * as path from 'path';
-import { exitWithError } from './utils';
+import * as process from 'process';
+import { yellow } from 'colorette';
 
 try {
-  require('assert-node-version')(path.join(__dirname, '../'));
-} catch (err) {
-  exitWithError(err.message);
+  const { engines } = require(path.join(__dirname, '../package.json'));
+  const version = engines.node;
+
+  if (!semver.satisfies(process.version, version)) {
+    process.stderr.write(
+      yellow(
+        `\n⚠️ Warning: failed to satisfy expected node version. Expected: "${version}", Current "${process.version}"\n\n`
+      )
+    );
+  }
+} catch (e) {
+  // Do nothing
 }

package/src/commands/join.ts

@@ -5,7 +5,7 @@ const isEqual = require('lodash.isequal');
 import {
   Config,
   Oas3Definition,
-  OasVersion,
+  SpecVersion,
   BaseResolver,
   Document,
   StyleguideConfig,
@@ -13,7 +13,7 @@ import {
   formatProblems,
   getTotals,
   lintDocument,
-  detectOpenAPI,
+  detectSpec,
   bundleDocument,
   Referenced,
   isRef,
@@ -29,7 +29,12 @@ import {
   sortTopLevelKeysForOas,
 } from '../utils';
 import { isObject, isString, keysOf } from '../js-utils';
-import { Oas3Parameter, Oas3PathItem, Oas3Server } from '@redocly/openapi-core/lib/typings/openapi';
+import {
+  Oas3Parameter,
+  Oas3PathItem,
+  Oas3Server,
+  Oas3_1Definition,
+} from '@redocly/openapi-core/lib/typings/openapi';
 import { OPENAPI3_METHOD } from './split/types';
 import { BundleResult } from '@redocly/openapi-core/lib/bundle';
 
@@ -141,12 +146,22 @@ export async function handleJoin(argv: JoinOptions, config: Config, packageVersi
     }
   }
 
+  let oasVersion: SpecVersion | null = null;
   for (const document of documents) {
     try {
-      const version = detectOpenAPI(document.parsed);
-      if (version !== OasVersion.Version3_0) {
+      const version = detectSpec(document.parsed);
+      if (version !== SpecVersion.OAS3_0 && version !== SpecVersion.OAS3_1) {
+        return exitWithError(
+          `Only OpenAPI 3.0 and OpenAPI 3.1 are supported: ${blue(
+            document.source.absoluteRef
+          )} \n\n`
+        );
+      }
+
+      oasVersion = oasVersion ?? version;
+      if (oasVersion !== version) {
         return exitWithError(
-          `Only OpenAPI 3 is supported: ${blue(document.source.absoluteRef)} \n\n`
+          `All APIs must use the same OpenAPI version: ${blue(document.source.absoluteRef)} \n\n`
         );
       }
     } catch (e) {
@@ -165,7 +180,7 @@ export async function handleJoin(argv: JoinOptions, config: Config, packageVersi
     tags: {},
     paths: {},
     components: {},
-    xWebhooks: {},
+    webhooks: {},
   };
 
   addInfoSectionAndSpecVersion(documents, prefixComponentsWithInfoProp);
@@ -200,7 +215,7 @@ export async function handleJoin(argv: JoinOptions, config: Config, packageVersi
     collectExternalDocs(openapi, context);
     collectPaths(openapi, context);
     collectComponents(openapi, context);
-    collectXWebhooks(openapi, context);
+    collectWebhooks(oasVersion!, openapi, context);
     if (componentsPrefix) {
       replace$Refs(openapi, componentsPrefix);
     }
@@ -573,32 +588,33 @@ export async function handleJoin(argv: JoinOptions, config: Config, packageVersi
     }
   }
 
-  function collectXWebhooks(
-    openapi: Oas3Definition,
+  function collectWebhooks(
+    oasVersion: SpecVersion,
+    openapi: Oas3_1Definition,
     { apiFilename, api, potentialConflicts, tagsPrefix, componentsPrefix }: JoinDocumentContext
   ) {
-    const xWebhooks = 'x-webhooks';
-    const openapiXWebhooks = openapi[xWebhooks];
-    if (openapiXWebhooks) {
-      if (!joinedDef.hasOwnProperty(xWebhooks)) {
-        joinedDef[xWebhooks] = {};
+    const webhooks = oasVersion === SpecVersion.OAS3_1 ? 'webhooks' : 'x-webhooks';
+    const openapiWebhooks = openapi[webhooks];
+    if (openapiWebhooks) {
+      if (!joinedDef.hasOwnProperty(webhooks)) {
+        joinedDef[webhooks] = {};
       }
-      for (const webhook of Object.keys(openapiXWebhooks)) {
-        joinedDef[xWebhooks][webhook] = openapiXWebhooks[webhook];
+      for (const webhook of Object.keys(openapiWebhooks)) {
+        joinedDef[webhooks][webhook] = openapiWebhooks[webhook];
 
-        if (!potentialConflicts.xWebhooks.hasOwnProperty(webhook)) {
-          potentialConflicts.xWebhooks[webhook] = {};
+        if (!potentialConflicts.webhooks.hasOwnProperty(webhook)) {
+          potentialConflicts.webhooks[webhook] = {};
         }
-        for (const operation of Object.keys(openapiXWebhooks[webhook])) {
-          potentialConflicts.xWebhooks[webhook][operation] = [
-            ...(potentialConflicts.xWebhooks[webhook][operation] || []),
+        for (const operation of Object.keys(openapiWebhooks[webhook])) {
+          potentialConflicts.webhooks[webhook][operation] = [
+            ...(potentialConflicts.webhooks[webhook][operation] || []),
             api,
           ];
         }
-        for (const operationKey of Object.keys(joinedDef[xWebhooks][webhook])) {
-          const { tags } = joinedDef[xWebhooks][webhook][operationKey];
+        for (const operationKey of Object.keys(joinedDef[webhooks][webhook])) {
+          const { tags } = joinedDef[webhooks][webhook][operationKey];
           if (tags) {
-            joinedDef[xWebhooks][webhook][operationKey].tags = tags.map((tag: string) =>
+            joinedDef[webhooks][webhook][operationKey].tags = tags.map((tag: string) =>
               addPrefix(tag, tagsPrefix)
             );
             populateTags({

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

@@ -1,15 +1,7 @@
 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 { bundle, RedoclyClient, getTotals, getMergedConfig, Config } from '@redocly/openapi-core';
+import { getFallbackApisOrExit, handleError, loadConfigAndHandleErrors } from '../../utils';
 import startPreviewServer from './preview-server/preview-server';
 import type { Skips } from '../../types';
 
@@ -178,13 +170,3 @@ export function debounce(func: Function, wait: number, immediate?: boolean) {
     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/preview-server.ts

@@ -1,6 +1,6 @@
 import { compile } from 'handlebars';
 import * as colorette from 'colorette';
-import * as portfinder from 'portfinder';
+import { getPort } from 'get-port-please';
 import { readFileSync, promises as fsPromises } from 'fs';
 import * as path from 'path';
 
@@ -143,7 +143,7 @@ export default async function startPreviewServer(
     console.timeEnd(colorette.dim(`GET ${request.url}`));
   };
 
-  const wsPort = await portfinder.getPortPromise({ port: 32201 });
+  const wsPort = await getPort({ portRange: [32201, 32301] });
 
   const server = startHttpServer(port, host, handler);
   server.on('listening', () => {

package/src/commands/stats.ts

@@ -4,13 +4,10 @@ import {
   Config,
   StyleguideConfig,
   normalizeTypes,
-  Oas3Types,
-  Oas2Types,
   BaseResolver,
   resolveDocument,
-  detectOpenAPI,
-  OasMajorVersion,
-  openAPIMajor,
+  detectSpec,
+  getTypes,
   normalizeVisitors,
   walkDocument,
   Stats,
@@ -72,20 +69,16 @@ export async function handleStats(argv: StatsOptions, config: Config) {
   const externalRefResolver = new BaseResolver(config.resolve);
   const { bundle: document } = await bundle({ config, ref: path });
   const lintConfig: StyleguideConfig = config.styleguide;
-  const oasVersion = detectOpenAPI(document.parsed);
-  const oasMajorVersion = openAPIMajor(oasVersion);
+  const specVersion = detectSpec(document.parsed);
   const types = normalizeTypes(
-    lintConfig.extendTypes(
-      oasMajorVersion === OasMajorVersion.Version3 ? Oas3Types : Oas2Types,
-      oasVersion
-    ),
+    lintConfig.extendTypes(getTypes(specVersion), specVersion),
     lintConfig
   );
 
   const startedAt = performance.now();
   const ctx: WalkContext = {
     problems: [],
-    oasVersion: oasVersion,
+    oasVersion: specVersion,
     visitorsData: {},
   };
 

package/src/index.ts

@@ -20,6 +20,10 @@ import type { Arguments } from 'yargs';
 import type { OutputFormat, RuleSeverity } from '@redocly/openapi-core';
 import type { BuildDocsArgv } from './commands/build-docs/types';
 
+if (!('replaceAll' in String.prototype)) {
+  require('core-js/actual/string/replace-all');
+}
+
 cacheLatestVersion();
 
 yargs
@@ -45,11 +49,11 @@ yargs
   )
   .command(
     'split [api]',
-    'Split an API definition into a multi-file structure.',
+    'Split an API description into a multi-file structure.',
     (yargs) =>
       yargs
         .positional('api', {
-          description: 'API definition file that you want to split',
+          description: 'API description file that you want to split',
           type: 'string',
         })
         .option({
@@ -129,7 +133,7 @@ yargs
 
   .command(
     'push [api] [maybeDestination] [maybeBranchName]',
-    'Push an API definition to the Redocly API registry.',
+    'Push an API description to the Redocly API registry.',
     (yargs) =>
       yargs
         .usage('push [api]')
@@ -184,7 +188,7 @@ yargs
             type: 'string',
           },
           public: {
-            description: 'Make the API definition available to the public',
+            description: 'Make the API description available to the public',
             type: 'boolean',
           },
           files: {
@@ -314,7 +318,7 @@ yargs
           type: 'string',
         },
         lint: {
-          description: 'Lint API definitions',
+          description: 'Lint API descriptions',
           type: 'boolean',
           default: false,
         },

package/src/utils.ts

@@ -2,7 +2,7 @@ import fetch from './fetch-with-timeout';
 import { basename, dirname, extname, join, resolve, relative, isAbsolute } from 'path';
 import { blue, gray, green, red, yellow } from 'colorette';
 import { performance } from 'perf_hooks';
-import * as glob from 'glob-promise';
+import * as glob from 'glob';
 import * as fs from 'fs';
 import * as readline from 'readline';
 import { Writable } from 'stream';
@@ -96,7 +96,7 @@ async function expandGlobsInEntrypoints(args: string[], config: ConfigApis) {
     await Promise.all(
       (args as string[]).map(async (aliasOrPath) => {
         return glob.hasMagic(aliasOrPath) && !isAbsoluteUrl(aliasOrPath)
-          ? (await glob(aliasOrPath)).map((g: string) => getAliasOrPath(config, g))
+          ? (await glob.__promisify__(aliasOrPath)).map((g: string) => getAliasOrPath(config, g))
           : getAliasOrPath(config, aliasOrPath);
       })
     )
@@ -232,10 +232,9 @@ export function handleError(e: Error, ref: string) {
       throw e;
     }
     case ResolveError:
-      return exitWithError(`Failed to resolve api definition at ${ref}:\n\n  - ${e.message}.`);
+      return exitWithError(`Failed to resolve API description at ${ref}:\n\n  - ${e.message}.`);
     case YamlParseError:
-      return exitWithError(`Failed to parse api definition at ${ref}:\n\n  - ${e.message}.`);
-    // TODO: codeframe
+      return exitWithError(`Failed to parse API description at ${ref}:\n\n  - ${e.message}.`);
     case CircularJSONNotSupportedError: {
       return exitWithError(
         `Detected circular reference which can't be converted to JSON.\n` +
@@ -269,7 +268,7 @@ export function printLintTotals(totals: Totals, definitionsCount: number) {
     );
   } else if (totals.warnings > 0) {
     process.stderr.write(
-      green(`Woohoo! Your OpenAPI ${pluralize('definition is', definitionsCount)} valid. 🎉\n`)
+      green(`Woohoo! Your API ${pluralize('description is', definitionsCount)} valid. 🎉\n`)
     );
     process.stderr.write(
       yellow(`You have ${totals.warnings} ${pluralize('warning', totals.warnings)}.\n${ignored}`)
@@ -277,7 +276,7 @@ export function printLintTotals(totals: Totals, definitionsCount: number) {
   } else {
     process.stderr.write(
       green(
-        `Woohoo! Your OpenAPI ${pluralize('definition is', definitionsCount)} valid. 🎉\n${ignored}`
+        `Woohoo! Your API ${pluralize('description is', definitionsCount)} valid. 🎉\n${ignored}`
       )
     );
   }