@redocly/cli 1.5.0 → 1.7.0

package/src/commands/join.ts

@@ -29,6 +29,7 @@ import {
   sortTopLevelKeysForOas,
   getAndValidateFileExtension,
   writeToFileByExtension,
+  checkForDeprecatedOptions,
 } from '../utils';
 import { isObject, isString, keysOf } from '../js-utils';
 import {
@@ -65,7 +66,6 @@ export type JoinOptions = {
   'without-x-tag-groups'?: boolean;
   output?: string;
   config?: string;
-  extends?: undefined;
   'lint-config'?: RuleSeverity;
 };
 
@@ -76,6 +76,8 @@ export async function handleJoin(argv: JoinOptions, config: Config, packageVersi
     return exitWithError(`At least 2 apis should be provided. \n\n`);
   }
 
+  checkForDeprecatedOptions(argv, ['lint'] as Array<keyof JoinOptions>);
+
   const fileExtension = getAndValidateFileExtension(argv.output || argv.apis[0]);
 
   const {

package/src/commands/lint.ts

@@ -1,13 +1,10 @@
 import {
   Config,
-  findConfig,
   formatProblems,
   getMergedConfig,
   getTotals,
   lint,
   lintConfig,
-  makeDocumentFromString,
-  stringifyYaml,
 } from '@redocly/openapi-core';
 import { ConfigValidationError } from '@redocly/openapi-core/lib/config';
 import {
@@ -21,11 +18,13 @@ import {
   printLintTotals,
   printUnusedWarnings,
 } from '../utils';
-import type { OutputFormat, ProblemSeverity, RawConfig, RuleSeverity } from '@redocly/openapi-core';
-import type { CommandOptions, Skips, Totals } from '../types';
 import { blue, gray } from 'colorette';
 import { performance } from 'perf_hooks';
 
+import type { OutputFormat, ProblemSeverity, Document, RuleSeverity } from '@redocly/openapi-core';
+import type { ResolvedRefMap } from '@redocly/openapi-core/lib/resolve';
+import type { CommandOptions, Skips, Totals } from '../types';
+
 export type LintOptions = {
   apis?: string[];
   'max-problems': number;
@@ -129,12 +128,10 @@ export function lintConfigCallback(
     return;
   }
 
-  return async (config: RawConfig) => {
-    const configPath = findConfig(argv.config) || '';
-    const stringYaml = stringifyYaml(config);
-    const configContent = makeDocumentFromString(stringYaml, configPath);
+  return async (document: Document, resolvedRefMap: ResolvedRefMap) => {
     const problems = await lintConfig({
-      document: configContent,
+      document,
+      resolvedRefMap,
       severity: (argv['lint-config'] || 'warn') as ProblemSeverity,
     });
 

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

@@ -0,0 +1,23 @@
+import { Product } from './types';
+
+export const PRODUCT_PACKAGES = {
+  realm: '@redocly/realm',
+  'redoc-revel': '@redocly/redoc-revel',
+  'revel-reef': '@redocly/revel-reef',
+  'redoc-reef': '@redocly/redoc-reef',
+  redoc: '@redocly/redoc',
+  revel: '@redocly/revel',
+  reef: '@redocly/reef',
+};
+
+export const PRODUCT_NAMES: { [key in Product]: string } = {
+  redoc: 'Redoc',
+  revel: 'Revel',
+  reef: 'Reef',
+  realm: 'Realm',
+  'redoc-revel': 'Redoc + Revel',
+  'redoc-reef': 'Redoc + Reef',
+  'revel-reef': 'Revel + Reef',
+};
+
+export const PRODUCT_PLANS = ['pro', 'enterprise'] as const;

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

@@ -0,0 +1,58 @@
+import path = require('path');
+import { existsSync, readFileSync } from 'fs';
+import { spawn } from 'child_process';
+import { PRODUCT_NAMES, PRODUCT_PACKAGES } from './constants';
+
+import type { PreviewProjectOptions, Product } from './types';
+
+export const previewProject = async (args: PreviewProjectOptions) => {
+  const { plan, port } = args;
+  const projectDir = args['source-dir'];
+
+  const product = args.product || tryGetProductFromPackageJson(projectDir);
+
+  if (!isValidProduct(product)) {
+    process.stderr.write(`Invalid product ${product}`);
+    throw new Error(`Project preview launch failed`);
+  }
+
+  const productName = PRODUCT_NAMES[product];
+  const packageName = PRODUCT_PACKAGES[product];
+
+  process.stdout.write(`\nLaunching preview of ${productName} ${plan} using NPX\n\n`);
+
+  spawn('npx', ['-y', packageName, 'develop', `--plan=${plan}`, `--port=${port || 4000}`], {
+    stdio: 'inherit',
+    cwd: projectDir,
+  });
+};
+
+const isValidProduct = (product: string | undefined): product is Product => {
+  if (!product) {
+    return false;
+  }
+
+  return !!PRODUCT_NAMES[product as Product];
+};
+
+const tryGetProductFromPackageJson = (projectDir: string): Product => {
+  const packageJsonPath = path.join(process.cwd(), projectDir, 'package.json');
+
+  if (existsSync(packageJsonPath)) {
+    try {
+      const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf-8'));
+      const packageJsonDeps = packageJson.dependencies || {};
+
+      for (const [product, packageName] of Object.entries(PRODUCT_PACKAGES)) {
+        if (packageJsonDeps[packageName]) {
+          process.stdout.write(`\n${packageName} detected in project's 'package.json'`);
+          return product as Product;
+        }
+      }
+    } catch (error) {
+      process.stdout.write(`Invalid 'package.json': ${packageJsonPath}. Using Realm.`);
+    }
+  }
+
+  return 'realm';
+};

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

@@ -0,0 +1,12 @@
+import { PRODUCT_PACKAGES, PRODUCT_PLANS } from './constants';
+
+export type Product = keyof typeof PRODUCT_PACKAGES;
+export type ProductPlan = typeof PRODUCT_PLANS[number];
+
+export type PreviewProjectOptions = {
+  product?: Product | string;
+  plan: ProductPlan | string;
+  port?: number;
+  'source-dir': string;
+  config: string | undefined;
+};

package/src/commands/split/index.ts

@@ -97,8 +97,8 @@ function isStartsWithComponents(node: string) {
   return node.startsWith(componentsPath);
 }
 
-function isNotYaml(filename: string) {
-  return !(filename.endsWith('.yaml') || filename.endsWith('.yml'));
+function isSupportedExtension(filename: string) {
+  return filename.endsWith('.yaml') || filename.endsWith('.yml') || filename.endsWith('.json');
 }
 
 function loadFile(fileName: string) {
@@ -138,7 +138,7 @@ function traverseDirectoryDeepCallback(
   directory: string,
   componentsFiles: object
 ) {
-  if (isNotYaml(filename)) return;
+  if (!isSupportedExtension(filename)) return;
   const pathData = readYaml(filename);
   replace$Refs(pathData, directory, componentsFiles);
   writeToFileByExtension(pathData, filename);

package/src/index.ts

@@ -19,6 +19,8 @@ import { version } from './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';
 
 if (!('replaceAll' in String.prototype)) {
   require('core-js/actual/string/replace-all');
@@ -92,7 +94,7 @@ yargs
   )
   .command(
     'join [apis...]',
-    'Join definitions [experimental].',
+    'Join multiple API descriptions into one [experimental].',
     (yargs) =>
       yargs
         .positional('apis', {
@@ -101,7 +103,7 @@ yargs
           demandOption: true,
         })
         .option({
-          lint: { description: 'Lint definitions', type: 'boolean', default: false },
+          lint: { description: 'Lint descriptions', type: 'boolean', default: false, hidden: true },
           decorate: { description: 'Run decorators', type: 'boolean', default: false },
           preprocess: { description: 'Run preprocessors', type: 'boolean', default: false },
           'prefix-tags-with-info-prop': {
@@ -124,7 +126,7 @@ yargs
             type: 'boolean',
           },
           output: {
-            describe: 'Output file',
+            description: 'Output file.',
             alias: 'o',
             type: 'string',
           },
@@ -228,7 +230,7 @@ yargs
   )
   .command(
     'lint [apis...]',
-    'Lint definition.',
+    'Lint an API description.',
     (yargs) =>
       yargs.positional('apis', { array: true, type: 'string', demandOption: true }).option({
         format: {
@@ -287,10 +289,14 @@ yargs
   )
   .command(
     'bundle [apis...]',
-    'Bundle definition.',
+    'Bundle a multi-file API description to a single file.',
     (yargs) =>
       yargs.positional('apis', { array: true, type: 'string', demandOption: true }).options({
-        output: { type: 'string', alias: 'o' },
+        output: {
+          type: 'string',
+          description: 'Output file.',
+          alias: 'o',
+        },
         format: {
           description: 'Use a specific output format.',
           choices: ['stylish', 'codeframe', 'json', 'checkstyle'] as ReadonlyArray<OutputFormat>,
@@ -413,9 +419,41 @@ yargs
       })(argv);
     }
   )
+  .command(
+    'preview',
+    'Preview Redocly project using one of the product NPM packages.',
+    (yargs) =>
+      yargs.options({
+        product: {
+          type: 'string',
+          choices: ['redoc', 'revel', 'reef', 'realm', 'redoc-revel', 'redoc-reef', 'revel-reef'],
+          description:
+            "Product used to launch preview. Default is inferred from project's package.json or 'realm' is used.",
+        },
+        plan: {
+          type: 'string',
+          choices: PRODUCT_PLANS,
+          default: 'enterprise',
+        },
+        port: {
+          type: 'number',
+          description: 'Preview port.',
+          default: 4000,
+        },
+        'source-dir': {
+          alias: 'd',
+          type: 'string',
+          description: 'Project directory.',
+          default: '.',
+        },
+      }),
+    (argv) => {
+      commandWrapper(previewProject)(argv);
+    }
+  )
   .command(
     'preview-docs [api]',
-    'Preview API reference docs for the specified definition.',
+    'Preview API reference docs for an API description.',
     (yargs) =>
       yargs.positional('api', { type: 'string' }).options({
         port: {
@@ -519,7 +557,7 @@ yargs
       commandWrapper(handlerBuildCommand)(argv as Arguments<BuildDocsArgv>);
     }
   )
-  .completion('completion', 'Generate completion script.')
+  .completion('completion', 'Generate autocomplete script for `redocly` command.')
   .demandCommand(1)
   .middleware([notifyUpdateCliVersion])
   .strict().argv;

package/src/types.ts

@@ -8,6 +8,7 @@ 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 { PreviewProjectOptions } from './commands/preview-project/types';
 
 export type Totals = {
   errors: number;
@@ -30,7 +31,9 @@ export type CommandOptions =
   | BundleOptions
   | LoginOptions
   | PreviewDocsOptions
-  | BuildDocsArgv;
+  | BuildDocsArgv
+  | PreviewProjectOptions;
+
 export type Skips = {
   'skip-rule'?: string[];
   'skip-decorator'?: string[];

package/src/utils.ts

@@ -17,14 +17,12 @@ import {
   stringifyYaml,
   isAbsoluteUrl,
   loadConfig,
-  RawConfig,
   Region,
   Config,
   Oas3Definition,
   Oas2Definition,
   RedoclyClient,
 } from '@redocly/openapi-core';
-import { ConfigValidationError } from '@redocly/openapi-core/lib/config';
 import {
   Totals,
   outputExtensions,
@@ -37,6 +35,9 @@ import { isEmptyObject } from '@redocly/openapi-core/lib/utils';
 import { Arguments } from 'yargs';
 import { version } from './update-version-notifier';
 import { DESTINATION_REGEX } from './commands/push';
+import { ConfigValidationError } from '@redocly/openapi-core/lib/config';
+
+import type { RawConfigProcessor } from '@redocly/openapi-core/lib/config';
 
 export async function getFallbackApisOrExit(
   argsApis: string[] | undefined,
@@ -145,6 +146,24 @@ export function langToExt(lang: string) {
     javascript: '.js',
     js: '.js',
     python: '.py',
+    c: '.c',
+    'c++': '.cpp',
+    coffeescript: '.litcoffee',
+    dart: '.dart',
+    elixir: '.ex',
+    go: '.go',
+    groovy: '.groovy',
+    java: '.java',
+    kotlin: '.kt',
+    'objective-c': '.m',
+    perl: '.pl',
+    powershell: '.ps1',
+    ruby: '.rb',
+    rust: '.rs',
+    scala: '.sc',
+    swift: '.swift',
+    typescript: '.ts',
+    tsx: '.tsx',
   };
   return langObj[lang.toLowerCase()];
 }
@@ -425,7 +444,7 @@ export async function loadConfigAndHandleErrors(
   options: {
     configPath?: string;
     customExtends?: string[];
-    processRawConfig?: (rawConfig: RawConfig) => void | Promise<void>;
+    processRawConfig?: RawConfigProcessor;
     files?: string[];
     region?: Region;
   } = {}
@@ -626,3 +645,17 @@ export function cleanArgs(args: CommandOptions) {
 export function cleanRawInput(argv: string[]) {
   return argv.map((entry) => entry.split('=').map(cleanString).join('=')).join(' ');
 }
+
+export function checkForDeprecatedOptions<T>(argv: T, deprecatedOptions: Array<keyof T>) {
+  for (const option of deprecatedOptions) {
+    if (argv[option]) {
+      process.stderr.write(
+        yellow(
+          `[WARNING] "${String(
+            option
+          )}" option is deprecated and will be removed in a future release. \n\n`
+        )
+      );
+    }
+  }
+}