@redocly/cli 1.18.0 → 1.19.0

package/src/commands/lint.ts

@@ -1,5 +1,6 @@
+import { blue, gray } from 'colorette';
+import { performance } from 'perf_hooks';
 import {
-  Config,
   formatProblems,
   getMergedConfig,
   getTotals,
@@ -13,19 +14,19 @@ import {
   getExecutionTime,
   getFallbackApisOrExit,
   handleError,
+  notifyAboutIncompatibleConfigOptions,
   pluralize,
   printConfigLintTotals,
   printLintTotals,
   printUnusedWarnings,
 } from '../utils/miscellaneous';
-import { blue, gray } from 'colorette';
-import { performance } from 'perf_hooks';
+import { getCommandNameFromArgs } from '../utils/getCommandNameFromArgs';
 
+import type { Arguments } from 'yargs';
 import type { OutputFormat, ProblemSeverity, RuleSeverity } from '@redocly/openapi-core';
 import type { RawConfigProcessor } from '@redocly/openapi-core/lib/config';
 import type { CommandOptions, Skips, Totals } from '../types';
-import { getCommandNameFromArgs } from '../utils/getCommandNameFromArgs';
-import { Arguments } from 'yargs';
+import type { CommandArgs } from '../wrapper';
 
 export type LintOptions = {
   apis?: string[];
@@ -37,7 +38,12 @@ export type LintOptions = {
   'lint-config'?: RuleSeverity;
 } & Omit<Skips, 'skip-decorator'>;
 
-export async function handleLint(argv: LintOptions, config: Config, version: string) {
+export async function handleLint({
+  argv,
+  config,
+  version,
+  collectSpecData,
+}: CommandArgs<LintOptions>) {
   const apis = await getFallbackApisOrExit(argv.apis, config);
 
   if (!apis.length) {
@@ -73,6 +79,7 @@ export async function handleLint(argv: LintOptions, config: Config, version: str
       const results = await lint({
         ref: path,
         config: resolvedConfig,
+        collectSpecData,
       });
 
       const fileTotals = getTotals(results);
@@ -130,7 +137,13 @@ export function lintConfigCallback(
     return;
   }
 
-  return async ({ document, resolvedRefMap, config }) => {
+  return async ({ document, resolvedRefMap, config, parsed: { theme = {} } }) => {
+    const command = argv ? getCommandNameFromArgs(argv as Arguments) : undefined;
+
+    if (command === 'check-config') {
+      notifyAboutIncompatibleConfigOptions(theme.openapi);
+    }
+
     const problems = await lintConfig({
       document,
       resolvedRefMap,
@@ -147,8 +160,6 @@ export function lintConfigCallback(
       version,
     });
 
-    const command = argv ? getCommandNameFromArgs(argv as unknown as Arguments) : undefined;
-
     printConfigLintTotals(fileTotals, command);
 
     if (fileTotals.errors > 0) {

package/src/commands/login.ts

@@ -1,7 +1,9 @@
-import { Region, RedoclyClient, Config } from '@redocly/openapi-core';
+import { Region, RedoclyClient } from '@redocly/openapi-core';
 import { blue, green, gray } from 'colorette';
 import { promptUser } from '../utils/miscellaneous';
 
+import type { CommandArgs } from '../wrapper';
+
 export function promptClientToken(domain: string) {
   return promptUser(
     green(
@@ -17,7 +19,7 @@ export type LoginOptions = {
   config?: string;
 };
 
-export async function handleLogin(argv: LoginOptions, config: Config) {
+export async function handleLogin({ argv, config }: CommandArgs<LoginOptions>) {
   const region = argv.region || config.region;
   const client = new RedoclyClient(region);
   const clientToken = await promptClientToken(client.domain);

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

@@ -7,7 +7,9 @@ import {
   loadConfigAndHandleErrors,
 } from '../../utils/miscellaneous';
 import startPreviewServer from './preview-server/preview-server';
+
 import type { Skips } from '../../types';
+import type { CommandArgs } from '../../wrapper';
 
 export type PreviewDocsOptions = {
   port: number;
@@ -18,7 +20,10 @@ export type PreviewDocsOptions = {
   force?: boolean;
 } & Omit<Skips, 'skip-rule'>;
 
-export async function previewDocs(argv: PreviewDocsOptions, configFromFile: Config) {
+export async function previewDocs({
+  argv,
+  config: configFromFile,
+}: CommandArgs<PreviewDocsOptions>) {
   let isAuthorizedWithRedocly = false;
   let redocOptions: any = {};
   let config = await reloadConfig(configFromFile);

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

@@ -4,12 +4,13 @@ import { spawn } from 'child_process';
 import { PRODUCT_NAMES, PRODUCT_PACKAGES } from './constants';
 
 import type { PreviewProjectOptions, Product } from './types';
+import type { CommandArgs } from '../../wrapper';
 
-export const previewProject = async (args: PreviewProjectOptions) => {
-  const { plan, port } = args;
-  const projectDir = args['source-dir'];
+export const previewProject = async ({ argv }: CommandArgs<PreviewProjectOptions>) => {
+  const { plan, port } = argv;
+  const projectDir = argv['source-dir'];
 
-  const product = args.product || tryGetProductFromPackageJson(projectDir);
+  const product = argv.product || tryGetProductFromPackageJson(projectDir);
 
   if (!isValidProduct(product)) {
     process.stderr.write(`Invalid product ${product}`);

package/src/commands/push.ts

@@ -20,12 +20,14 @@ import {
   exitWithError,
   printExecutionTime,
   getFallbackApisOrExit,
-  pluralize,
   dumpBundle,
+  pluralize,
 } from '../utils/miscellaneous';
 import { promptClientToken } from './login';
 import { handlePush as handleCMSPush } from '../cms/commands/push';
 
+import type { CommandArgs } from '../wrapper';
+
 const DEFAULT_VERSION = 'latest';
 
 export const DESTINATION_REGEX =
@@ -59,7 +61,7 @@ export function commonPushHandler({
   return transformPush(handlePush);
 }
 
-export async function handlePush(argv: PushOptions, config: Config): Promise<void> {
+export async function handlePush({ argv, config }: CommandArgs<PushOptions>): Promise<void> {
   const client = new RedoclyClient(config.region);
   const isAuthorized = await client.isAuthorizedWithRedoclyByRegion();
   if (!isAuthorized) {
@@ -366,16 +368,11 @@ type BarePushArgs = Omit<PushOptions, 'destination' | 'branchName'> & {
 
 export const transformPush =
   (callback: typeof handlePush) =>
-  (
-    {
-      apis,
-      branch,
-      'batch-id': batchId,
-      'job-id': jobId,
-      ...rest
-    }: BarePushArgs & { 'batch-id'?: string },
-    config: Config
-  ) => {
+  ({
+    argv: { apis, branch, 'batch-id': batchId, 'job-id': jobId, ...rest },
+    config,
+    version,
+  }: CommandArgs<BarePushArgs & { 'batch-id'?: string }>) => {
     const [maybeApiOrDestination, maybeDestination, maybeBranchName] = apis || [];
 
     if (batchId) {
@@ -414,16 +411,17 @@ export const transformPush =
       apiFile = maybeApiOrDestination;
     }
 
-    return callback(
-      {
+    return callback({
+      argv: {
         ...rest,
         destination: rest.destination ?? destination,
         api: apiFile,
         branchName: branch ?? maybeBranchName,
         'job-id': jobId || batchId,
       },
-      config
-    );
+      config,
+      version,
+    });
   };
 
 export function getApiRoot({

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

@@ -3,6 +3,9 @@ import * as path from 'path';
 import * as openapiCore from '@redocly/openapi-core';
 import { ComponentsFiles } from '../types';
 import { blue, green } from 'colorette';
+import { loadConfigAndHandleErrors } from '../../../utils/__mocks__/miscellaneous';
+
+import type { Config } from '@redocly/openapi-core';
 
 const utils = require('../../../utils/miscellaneous');
 
@@ -25,9 +28,13 @@ describe('#split', () => {
     jest.spyOn(process.stderr, 'write').mockImplementation(() => true);
 
     await handleSplit({
-      api: filePath,
-      outDir: openapiDir,
-      separator: '_',
+      argv: {
+        api: filePath,
+        outDir: openapiDir,
+        separator: '_',
+      },
+      config: loadConfigAndHandleErrors() as any as Config,
+      version: 'cli-version',
     });
 
     expect(process.stderr.write).toBeCalledTimes(2);
@@ -46,9 +53,13 @@ describe('#split', () => {
     jest.spyOn(utils, 'pathToFilename').mockImplementation(() => 'newFilePath');
 
     await handleSplit({
-      api: filePath,
-      outDir: openapiDir,
-      separator: '_',
+      argv: {
+        api: filePath,
+        outDir: openapiDir,
+        separator: '_',
+      },
+      config: loadConfigAndHandleErrors() as any as Config,
+      version: 'cli-version',
     });
 
     expect(utils.pathToFilename).toBeCalledWith(expect.anything(), '_');

package/src/commands/split/index.ts

@@ -1,9 +1,9 @@
 import { red, blue, yellow, green } from 'colorette';
 import * as fs from 'fs';
 import { parseYaml, slash, isRef, isTruthy } from '@redocly/openapi-core';
+import { dequal } from '@redocly/openapi-core/lib/utils';
 import * as path from 'path';
 import { performance } from 'perf_hooks';
-const isEqual = require('lodash.isequal');
 import {
   printExecutionTime,
   pathToFilename,
@@ -36,6 +36,7 @@ import type {
   Oas3PathItem,
   Referenced,
 } from './types';
+import type { CommandArgs } from '../../wrapper';
 
 export type SplitOptions = {
   api: string;
@@ -44,12 +45,13 @@ export type SplitOptions = {
   config?: string;
 };
 
-export async function handleSplit(argv: SplitOptions) {
+export async function handleSplit({ argv, collectSpecData }: CommandArgs<SplitOptions>) {
   const startedAt = performance.now();
   const { api, outDir, separator } = argv;
   validateDefinitionFileName(api!);
   const ext = getAndValidateFileExtension(api);
   const openapi = readYaml(api!) as Oas3Definition | Oas3_1Definition;
+  collectSpecData?.(openapi);
   splitDefinition(openapi, outDir, separator, ext);
   process.stderr.write(
     `🪓 Document: ${blue(api!)} ${green('is successfully split')}
@@ -232,7 +234,7 @@ function findComponentTypes(components: any) {
 }
 
 function doesFileDiffer(filename: string, componentData: any) {
-  return fs.existsSync(filename) && !isEqual(readYaml(filename), componentData);
+  return fs.existsSync(filename) && !dequal(readYaml(filename), componentData);
 }
 
 function removeEmptyComponents(
@@ -292,7 +294,7 @@ function iteratePathItems(
 
   for (const pathName of Object.keys(pathItems)) {
     const pathFile = `${path.join(outDir, pathToFilename(pathName, pathSeparator))}.${ext}`;
-    const pathData = pathItems[pathName] as Oas3PathItem;
+    const pathData = pathItems[pathName];
 
     if (isRef(pathData)) continue;
 

package/src/commands/stats.ts

@@ -1,7 +1,6 @@
 import { performance } from 'perf_hooks';
 import * as colors from 'colorette';
 import {
-  Config,
   StyleguideConfig,
   normalizeTypes,
   BaseResolver,
@@ -15,7 +14,9 @@ import {
 } from '@redocly/openapi-core';
 import { getFallbackApisOrExit } from '../utils/miscellaneous';
 import { printExecutionTime } from '../utils/miscellaneous';
+
 import type { StatsAccumulator, StatsName, WalkContext, OutputFormat } from '@redocly/openapi-core';
+import type { CommandArgs } from '../wrapper';
 
 const statsAccumulator: StatsAccumulator = {
   refs: { metric: '🚗 References', total: 0, color: 'red', items: new Set() },
@@ -86,10 +87,11 @@ export type StatsOptions = {
   config?: string;
 };
 
-export async function handleStats(argv: StatsOptions, config: Config) {
+export async function handleStats({ argv, config, collectSpecData }: CommandArgs<StatsOptions>) {
   const [{ path }] = await getFallbackApisOrExit(argv.api ? [argv.api] : [], config);
   const externalRefResolver = new BaseResolver(config.resolve);
   const { bundle: document } = await bundle({ config, ref: path });
+  collectSpecData?.(document.parsed);
   const lintConfig: StyleguideConfig = config.styleguide;
   const specVersion = detectSpec(document.parsed);
   const types = normalizeTypes(

package/src/utils/miscellaneous.ts

@@ -1,4 +1,4 @@
-import fetch from './fetch-with-timeout';
+import * as pluralizeOne from 'pluralize';
 import { basename, dirname, extname, join, resolve, relative, isAbsolute } from 'path';
 import { blue, gray, green, red, yellow } from 'colorette';
 import { performance } from 'perf_hooks';
@@ -9,36 +9,34 @@ import { Writable } from 'stream';
 import { execSync } from 'child_process';
 import { promisify } from 'util';
 import {
-  BundleOutputFormat,
-  StyleguideConfig,
   ResolveError,
   YamlParseError,
-  ResolvedApi,
   parseYaml,
   stringifyYaml,
   isAbsoluteUrl,
   loadConfig,
-  Region,
-  Config,
-  Oas3Definition,
-  Oas2Definition,
   RedoclyClient,
 } from '@redocly/openapi-core';
-import {
-  Totals,
-  outputExtensions,
-  Entrypoint,
-  ConfigApis,
-  CommandOptions,
-  OutputExtensions,
-} from '../types';
-import { isEmptyObject } from '@redocly/openapi-core/lib/utils';
-import { Arguments } from 'yargs';
+import { isEmptyObject, isPlainObject } from '@redocly/openapi-core/lib/utils';
+import { ConfigValidationError } from '@redocly/openapi-core/lib/config';
+import { deprecatedRefDocsSchema } from '@redocly/config/lib/reference-docs-config-schema';
+import { outputExtensions } from '../types';
 import { version } from './update-version-notifier';
 import { DESTINATION_REGEX } from '../commands/push';
-import { ConfigValidationError } from '@redocly/openapi-core/lib/config';
+import fetch from './fetch-with-timeout';
 
+import type { Arguments } from 'yargs';
+import type {
+  BundleOutputFormat,
+  StyleguideConfig,
+  ResolvedApi,
+  Region,
+  Config,
+  Oas3Definition,
+  Oas2Definition,
+} from '@redocly/openapi-core';
 import type { RawConfigProcessor } from '@redocly/openapi-core/lib/config';
+import type { Totals, Entrypoint, ConfigApis, CommandOptions, OutputExtensions } from '../types';
 
 export async function getFallbackApisOrExit(
   argsApis: string[] | undefined,
@@ -279,12 +277,11 @@ export function getAndValidateFileExtension(fileName: string): NonNullable<Outpu
   return 'yaml';
 }
 
-export function pluralize(label: string, num: number) {
-  if (label.endsWith('is')) {
-    [label] = label.split(' ');
-    return num === 1 ? `${label} is` : `${label}s are`;
-  }
-  return num === 1 ? `${label}` : `${label}s`;
+export function pluralize(sentence: string, count?: number, inclusive?: boolean) {
+  return sentence
+    .split(' ')
+    .map((word) => pluralizeOne(word, count, inclusive))
+    .join(' ');
 }
 
 export function handleError(e: Error, ref: string) {
@@ -525,6 +522,7 @@ export function checkIfRulesetExist(rules: typeof StyleguideConfig.prototype.rul
     ...rules.oas3_0,
     ...rules.oas3_1,
     ...rules.async2,
+    ...rules.async3,
     ...rules.arazzo,
   };
 
@@ -543,7 +541,10 @@ export function cleanColors(input: string): string {
 export async function sendTelemetry(
   argv: Arguments | undefined,
   exit_code: ExitCode,
-  has_config: boolean | undefined
+  has_config: boolean | undefined,
+  spec_version: string | undefined,
+  spec_keyword: string | undefined,
+  spec_full_version: string | undefined
 ): Promise<void> {
   try {
     if (!argv) {
@@ -571,6 +572,9 @@ export async function sendTelemetry(
       environment_ci: process.env.CI,
       raw_input: cleanRawInput(process.argv.slice(2)),
       has_config,
+      spec_version,
+      spec_keyword,
+      spec_full_version,
     };
     await fetch(`https://api.redocly.com/registry/telemetry/cli`, {
       method: 'POST',
@@ -600,6 +604,9 @@ export type Analytics = {
   environment_ci?: string;
   raw_input: string;
   has_config?: boolean;
+  spec_version?: string;
+  spec_keyword?: string;
+  spec_full_version?: string;
 };
 
 function isFile(value: string) {
@@ -664,3 +671,25 @@ export function checkForDeprecatedOptions<T>(argv: T, deprecatedOptions: Array<k
     }
   }
 }
+
+export function notifyAboutIncompatibleConfigOptions(
+  themeOpenapiOptions: Record<string, unknown> | undefined
+) {
+  if (isPlainObject(themeOpenapiOptions)) {
+    const propertiesSet = Object.keys(themeOpenapiOptions);
+    const deprecatedSet = Object.keys(deprecatedRefDocsSchema.properties);
+    const intersection = propertiesSet.filter((prop) => deprecatedSet.includes(prop));
+    if (intersection.length > 0) {
+      process.stderr.write(
+        yellow(
+          `\n${pluralize('Property', intersection.length)} ${gray(
+            intersection.map((prop) => `'${prop}'`).join(', ')
+          )} ${pluralize(
+            'is',
+            intersection.length
+          )} only used in API Reference Docs and Redoc version 2.x or earlier.\n\n`
+        )
+      );
+    }
+  }
+}

package/src/wrapper.ts

@@ -1,22 +1,48 @@
-import { Config, Region, doesYamlFileExist } from '@redocly/openapi-core';
-import type { Arguments } from 'yargs';
+import { detectSpec, doesYamlFileExist } from '@redocly/openapi-core';
+import { isPlainObject } from '@redocly/openapi-core/lib/utils';
 import { version } from './utils/update-version-notifier';
-import {
-  ExitCode,
-  exitWithError,
-  loadConfigAndHandleErrors,
-  sendTelemetry,
-} from './utils/miscellaneous';
+import { exitWithError, loadConfigAndHandleErrors, sendTelemetry } from './utils/miscellaneous';
 import { lintConfigCallback } from './commands/lint';
+
+import type { Arguments } from 'yargs';
+import type { Config, Region } from '@redocly/openapi-core';
+import type { CollectFn } from '@redocly/openapi-core/lib/utils';
+import type { ExitCode } from './utils/miscellaneous';
 import type { CommandOptions } from './types';
 
+export type CommandArgs<T extends CommandOptions> = {
+  argv: T;
+  config: Config;
+  version: string;
+  collectSpecData?: CollectFn;
+};
+
 export function commandWrapper<T extends CommandOptions>(
-  commandHandler?: (argv: T, config: Config, version: string) => Promise<unknown>
+  commandHandler?: (wrapperArgs: CommandArgs<T>) => Promise<unknown>
 ) {
   return async (argv: Arguments<T>) => {
     let code: ExitCode = 2;
     let hasConfig;
     let telemetry;
+    let specVersion: string | undefined;
+    let specKeyword: string | undefined;
+    let specFullVersion: string | undefined;
+    const collectSpecData: CollectFn = (document) => {
+      specVersion = detectSpec(document);
+      if (!isPlainObject(document)) return;
+      specKeyword = document?.openapi
+        ? 'openapi'
+        : document?.swagger
+        ? 'swagger'
+        : document?.asyncapi
+        ? 'asyncapi'
+        : document?.arazzo
+        ? 'arazzo'
+        : undefined;
+      if (specKeyword) {
+        specFullVersion = document[specKeyword] as string;
+      }
+    };
     try {
       if (argv.config && !doesYamlFileExist(argv.config)) {
         exitWithError('Please provide a valid path to the configuration file.');
@@ -32,14 +58,14 @@ export function commandWrapper<T extends CommandOptions>(
       hasConfig = !config.styleguide.recommendedFallback;
       code = 1;
       if (typeof commandHandler === 'function') {
-        await commandHandler(argv, config, version);
+        await commandHandler({ argv, config, version, collectSpecData });
       }
       code = 0;
     } catch (err) {
       // Do nothing
     } finally {
       if (process.env.REDOCLY_TELEMETRY !== 'off' && telemetry !== 'off') {
-        await sendTelemetry(argv, code, hasConfig);
+        await sendTelemetry(argv, code, hasConfig, specVersion, specKeyword, specFullVersion);
       }
       process.once('beforeExit', () => {
         process.exit(code);