@redocly/cli 1.18.1 → 1.20.0

package/src/commands/bundle.ts

@@ -1,4 +1,7 @@
-import { formatProblems, getTotals, getMergedConfig, bundle, Config } from '@redocly/openapi-core';
+import { performance } from 'perf_hooks';
+import { blue, gray, green, yellow } from 'colorette';
+import { writeFileSync } from 'fs';
+import { formatProblems, getTotals, getMergedConfig, bundle } from '@redocly/openapi-core';
 import {
   dumpBundle,
   getExecutionTime,
@@ -8,12 +11,11 @@ import {
   printUnusedWarnings,
   saveBundle,
   sortTopLevelKeysForOas,
+  checkForDeprecatedOptions,
 } from '../utils/miscellaneous';
+
 import type { OutputExtensions, Skips, Totals } from '../types';
-import { performance } from 'perf_hooks';
-import { blue, gray, green, yellow } from 'colorette';
-import { writeFileSync } from 'fs';
-import { checkForDeprecatedOptions } from '../utils/miscellaneous';
+import type { CommandArgs } from '../wrapper';
 
 export type BundleOptions = {
   apis?: string[];
@@ -28,7 +30,12 @@ export type BundleOptions = {
   'keep-url-references'?: boolean;
 } & Skips;
 
-export async function handleBundle(argv: BundleOptions, config: Config, version: string) {
+export async function handleBundle({
+  argv,
+  config,
+  version,
+  collectSpecData,
+}: CommandArgs<BundleOptions>) {
   const removeUnusedComponents =
     argv['remove-unused-components'] ||
     config.rawConfig?.styleguide?.decorators?.hasOwnProperty('remove-unused-components');
@@ -59,6 +66,7 @@ export async function handleBundle(argv: BundleOptions, config: Config, version:
         dereference: argv.dereferenced,
         removeUnusedComponents,
         keepUrlRefs: argv['keep-url-references'],
+        collectSpecData,
       });
 
       const fileTotals = getTotals(problems);

package/src/commands/join.ts

@@ -2,7 +2,6 @@ import * as path from 'path';
 import { red, blue, yellow, green } from 'colorette';
 import { performance } from 'perf_hooks';
 import {
-  Config,
   SpecVersion,
   BaseResolver,
   formatProblems,
@@ -38,6 +37,7 @@ import type {
   Oas3Server,
   Oas3_1Definition,
 } from '@redocly/openapi-core/lib/typings/openapi';
+import type { CommandArgs } from '../wrapper';
 
 const Tags = 'tags';
 const xTagGroups = 'x-tagGroups';
@@ -64,7 +64,11 @@ export type JoinOptions = {
   'lint-config'?: RuleSeverity;
 };
 
-export async function handleJoin(argv: JoinOptions, config: Config, packageVersion: string) {
+export async function handleJoin({
+  argv,
+  config,
+  version: packageVersion,
+}: CommandArgs<JoinOptions>) {
   const startedAt = performance.now();
 
   if (argv.apis.length < 2) {

package/src/commands/lint.ts

@@ -1,7 +1,6 @@
 import { blue, gray } from 'colorette';
 import { performance } from 'perf_hooks';
 import {
-  Config,
   formatProblems,
   getMergedConfig,
   getTotals,
@@ -23,10 +22,11 @@ import {
 } from '../utils/miscellaneous';
 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 type { Arguments } from 'yargs';
+import type { CommandArgs } from '../wrapper';
 
 export type LintOptions = {
   apis?: string[];
@@ -38,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) {
@@ -74,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);

package/src/commands/login.ts

@@ -1,7 +1,10 @@
-import { Region, RedoclyClient, Config } from '@redocly/openapi-core';
 import { blue, green, gray } from 'colorette';
+import { RedoclyClient } from '@redocly/openapi-core';
 import { promptUser } from '../utils/miscellaneous';
 
+import type { CommandArgs } from '../wrapper';
+import type { Region } from '@redocly/openapi-core';
+
 export function promptClientToken(domain: string) {
   return promptUser(
     green(
@@ -17,7 +20,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);
@@ -151,6 +156,7 @@ export async function previewDocs(argv: PreviewDocsOptions, configFromFile: Conf
   }
 }
 
+// eslint-disable-next-line @typescript-eslint/ban-types
 export function debounce(func: Function, wait: number, immediate?: boolean) {
   let timeout: NodeJS.Timeout | null;
 

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

@@ -3,11 +3,11 @@ import * as colorette from 'colorette';
 import { getPort } from 'get-port-please';
 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/miscellaneous';
 
+import type { IncomingMessage } from 'http';
+
 function getPageHTML(
   htmlTemplate: string,
   redocOptions: object = {},
@@ -60,7 +60,8 @@ export default async function startPreviewServer(
     getBundle,
     getOptions,
     useRedocPro,
-  }: { getBundle: Function; getOptions: Function; useRedocPro: boolean }
+  }: // eslint-disable-next-line @typescript-eslint/ban-types
+  { getBundle: Function; getOptions: Function; useRedocPro: boolean }
 ) {
   const defaultTemplate = path.join(__dirname, 'default.hbs');
   const handler = async (request: IncomingMessage, response: any) => {

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

@@ -1,6 +1,7 @@
 import * as http from 'http';
 import * as zlib from 'zlib';
-import { ReadStream } from 'fs';
+
+import type { ReadStream } from 'fs';
 
 const SocketServer = require('simple-websocket/server.js');
 

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

@@ -1,4 +1,4 @@
-import { Product } from './types';
+import type { Product } from './types';
 
 export const PRODUCT_PACKAGES = {
   realm: '@redocly/realm',

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/preview-project/types.ts

@@ -1,4 +1,4 @@
-import { PRODUCT_PACKAGES, PRODUCT_PLANS } from './constants';
+import type { PRODUCT_PACKAGES, PRODUCT_PLANS } from './constants';
 
 export type Product = keyof typeof PRODUCT_PACKAGES;
 export type ProductPlan = typeof PRODUCT_PLANS[number];

package/src/commands/push.ts

@@ -6,13 +6,10 @@ import { yellow, green, blue, red } from 'colorette';
 import { createHash } from 'crypto';
 import {
   bundle,
-  Config,
   RedoclyClient,
   IGNORE_FILE,
-  BundleOutputFormat,
   getTotals,
   slash,
-  Region,
   getMergedConfig,
   getProxyAgent,
 } from '@redocly/openapi-core';
@@ -26,9 +23,13 @@ import {
 import { promptClientToken } from './login';
 import { handlePush as handleCMSPush } from '../cms/commands/push';
 
+import type { Config, BundleOutputFormat, Region } from '@redocly/openapi-core';
+import type { CommandArgs } from '../wrapper';
+
 const DEFAULT_VERSION = 'latest';
 
 export const DESTINATION_REGEX =
+  // eslint-disable-next-line no-useless-escape
   /^(@(?<organizationId>[\w\-\s]+)\/)?(?<name>[^@]*)@(?<version>[\w\.\-]+)$/;
 
 export type PushOptions = {
@@ -59,7 +60,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 +367,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 +410,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

@@ -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')}
@@ -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,8 +1,6 @@
 import { performance } from 'perf_hooks';
 import * as colors from 'colorette';
 import {
-  Config,
-  StyleguideConfig,
   normalizeTypes,
   BaseResolver,
   resolveDocument,
@@ -13,9 +11,16 @@ import {
   Stats,
   bundle,
 } 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 { getFallbackApisOrExit, printExecutionTime } from '../utils/miscellaneous';
+
+import type { CommandArgs } from '../wrapper';
+import type {
+  StatsAccumulator,
+  StatsName,
+  WalkContext,
+  OutputFormat,
+  StyleguideConfig,
+} from '@redocly/openapi-core';
 
 const statsAccumulator: StatsAccumulator = {
   refs: { metric: '🚗 References', total: 0, color: 'red', items: new Set() },
@@ -24,6 +29,7 @@ const statsAccumulator: StatsAccumulator = {
   parameters: { metric: '👉 Parameters', total: 0, color: 'yellow', items: new Set() },
   links: { metric: '🔗 Links', total: 0, color: 'cyan', items: new Set() },
   pathItems: { metric: '🔀 Path Items', total: 0, color: 'green' },
+  webhooks: { metric: '🎣 Webhooks', total: 0, color: 'green' },
   operations: { metric: '👷 Operations', total: 0, color: 'yellow' },
   tags: { metric: '🔖 Tags', total: 0, color: 'white', items: new Set() },
 };
@@ -86,10 +92,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/index.ts

@@ -3,27 +3,33 @@
 import './utils/assert-node-version';
 import * as yargs from 'yargs';
 import * as colors from 'colorette';
-import { outputExtensions, PushArguments, regionChoices } from './types';
 import { RedoclyClient } from '@redocly/openapi-core';
+import { outputExtensions, regionChoices } from './types';
 import { previewDocs } from './commands/preview-docs';
 import { handleStats } from './commands/stats';
 import { handleSplit } from './commands/split';
 import { handleJoin } from './commands/join';
-import { handlePushStatus, PushStatusOptions } from './cms/commands/push-status';
+import { handlePushStatus } from './cms/commands/push-status';
 import { handleLint } from './commands/lint';
 import { handleBundle } from './commands/bundle';
 import { handleLogin } from './commands/login';
 import { handlerBuildCommand } from './commands/build-docs';
-import { cacheLatestVersion, notifyUpdateCliVersion } from './utils/update-version-notifier';
+import {
+  cacheLatestVersion,
+  notifyUpdateCliVersion,
+  version,
+} from './utils/update-version-notifier';
 import { commandWrapper } from './wrapper';
-import { version } from './utils/update-version-notifier';
-import type { Arguments } from 'yargs';
-import type { OutputFormat, RuleSeverity } from '@redocly/openapi-core';
-import type { BuildDocsArgv } from './commands/build-docs/types';
 import { previewProject } from './commands/preview-project';
 import { PRODUCT_PLANS } from './commands/preview-project/constants';
 import { commonPushHandler } from './commands/push';
 
+import type { Arguments } from 'yargs';
+import type { OutputFormat, RuleSeverity } from '@redocly/openapi-core';
+import type { BuildDocsArgv } from './commands/build-docs/types';
+import type { PushStatusOptions } from './cms/commands/push-status';
+import type { PushArguments } from './types';
+
 if (!('replaceAll' in String.prototype)) {
   require('core-js/actual/string/replace-all');
 }

package/src/types.ts

@@ -9,9 +9,8 @@ import type { StatsOptions } from './commands/stats';
 import type { SplitOptions } from './commands/split';
 import type { PreviewDocsOptions } from './commands/preview-docs';
 import type { BuildDocsArgv } from './commands/build-docs/types';
-import type { PushOptions as PushBhOptions } from './cms/commands/push';
-import type { PushStatusOptions } from './cms/commands/push-status';
 import type { PushOptions as CMSPushOptions } from './cms/commands/push';
+import type { PushStatusOptions } from './cms/commands/push-status';
 import type { PreviewProjectOptions } from './commands/preview-project/types';
 
 export type Totals = {
@@ -31,7 +30,7 @@ export type CommandOptions =
   | SplitOptions
   | JoinOptions
   | PushOptions
-  | PushBhOptions
+  | CMSPushOptions
   | LintOptions
   | BundleOptions
   | LoginOptions

package/src/utils/getCommandNameFromArgs.ts

@@ -1,4 +1,4 @@
-import { Arguments } from 'yargs';
+import type { Arguments } from 'yargs';
 
 export function getCommandNameFromArgs(argv: Arguments | undefined): string | number {
   return argv?._?.[0] ?? '';

package/src/utils/miscellaneous.ts

@@ -522,6 +522,7 @@ export function checkIfRulesetExist(rules: typeof StyleguideConfig.prototype.rul
     ...rules.oas3_0,
     ...rules.oas3_1,
     ...rules.async2,
+    ...rules.async3,
     ...rules.arazzo,
   };
 
@@ -540,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) {
@@ -568,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',
@@ -597,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) {

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);