@redocly/cli 1.0.0-beta.105 → 1.0.0-beta.106

package/src/commands/lint.ts

@@ -6,43 +6,35 @@ import {
   lintConfig,
   findConfig,
   getMergedConfig,
-  OutputFormat,
   makeDocumentFromString,
   loadConfig,
   stringifyYaml,
   RawConfig,
   RuleSeverity,
   ProblemSeverity,
-  doesYamlFileExist
+  doesYamlFileExist,
 } from '@redocly/openapi-core';
 import {
   getExecutionTime,
-  getFallbackEntryPointsOrExit,
+  getFallbackApisOrExit,
   handleError,
   pluralize,
   printLintTotals,
   printConfigLintTotals,
   printUnusedWarnings,
-  exitWithError
+  exitWithError,
 } from '../utils';
-import { Totals } from '../types';
+import type { CommonOptions, Skips, Totals } from '../types';
 import { blue, gray, red } from 'colorette';
 import { performance } from 'perf_hooks';
 
-export type LintOptions = {
-  entrypoints: string[];
-  'max-problems'?: number;
-  'generate-ignore-file'?: boolean;
-  'skip-rule'?: string[];
-  'skip-preprocessor'?: string[];
-  'lint-config': RuleSeverity;
-  extends?: string[];
-  config?: string;
-  format: OutputFormat;
-};
+export type LintOptions = CommonOptions &
+  Omit<Skips, 'skip-decorator'> & {
+    'generate-ignore-file'?: boolean;
+    'lint-config': RuleSeverity;
+  };
 
 export async function handleLint(argv: LintOptions, version: string) {
-
   if (argv.config && !doesYamlFileExist(argv.config)) {
     return exitWithError('Please, provide valid path to the configuration file');
   }
@@ -53,29 +45,31 @@ export async function handleLint(argv: LintOptions, version: string) {
     lintConfigCallback(argv, version)
   );
 
-  const entrypoints = await getFallbackEntryPointsOrExit(argv.entrypoints, config);
+  const apis = await getFallbackApisOrExit(argv.apis, config);
 
   if (argv['generate-ignore-file']) {
-    config.lint.ignore = {}; // clear ignore
+    config.styleguide.ignore = {}; // clear ignore
   }
   const totals: Totals = { errors: 0, warnings: 0, ignored: 0 };
   let totalIgnored = 0;
 
   // TODO: use shared externalRef resolver, blocked by preprocessors now as they can mutate documents
-  for (const { path, alias } of entrypoints) {
+  for (const { path, alias } of apis) {
     try {
       const startedAt = performance.now();
       const resolvedConfig = getMergedConfig(config, alias);
-      resolvedConfig.lint.skipRules(argv['skip-rule']);
-      resolvedConfig.lint.skipPreprocessors(argv['skip-preprocessor']);
+      const { styleguide } = resolvedConfig;
+
+      styleguide.skipRules(argv['skip-rule']);
+      styleguide.skipPreprocessors(argv['skip-preprocessor']);
 
-      if (resolvedConfig.lint.recommendedFallback) {
+      if (styleguide.recommendedFallback) {
         process.stderr.write(
           `No configurations were defined in extends -- using built in ${blue(
-            'recommended',
+            'recommended'
           )} configuration by default.\n${red(
-            'Warning! This default behavior is going to be deprecated soon.',
-          )}\n\n`,
+            'Warning! This default behavior is going to be deprecated soon.'
+          )}\n\n`
         );
       }
       process.stderr.write(gray(`validating ${path.replace(process.cwd(), '')}...\n`));
@@ -91,7 +85,7 @@ export async function handleLint(argv: LintOptions, version: string) {
 
       if (argv['generate-ignore-file']) {
         for (let m of results) {
-          config.lint.addIgnore(m);
+          config.styleguide.addIgnore(m);
           totalIgnored++;
         }
       } else {
@@ -106,26 +100,25 @@ export async function handleLint(argv: LintOptions, version: string) {
       const elapsed = getExecutionTime(startedAt);
       process.stderr.write(gray(`${path.replace(process.cwd(), '')}: validated in ${elapsed}\n\n`));
     } catch (e) {
-      totals.errors++;
       handleError(e, path);
     }
   }
 
   if (argv['generate-ignore-file']) {
-    config.lint.saveIgnore();
+    config.styleguide.saveIgnore();
     process.stderr.write(
       `Generated ignore file with ${totalIgnored} ${pluralize('problem', totalIgnored)}.\n\n`
     );
   } else {
-    printLintTotals(totals, entrypoints.length);
+    printLintTotals(totals, apis.length);
   }
 
-  printUnusedWarnings(config.lint);
+  printUnusedWarnings(config.styleguide);
 
   // defer process exit to allow STDOUT pipe to flush
   // see https://github.com/nodejs/node-v0.x-archive/issues/3737#issuecomment-19156072
   process.once('exit', () =>
-    process.exit(totals.errors === 0 || argv['generate-ignore-file'] ? 0 : 1),
+    process.exit(totals.errors === 0 || argv['generate-ignore-file'] ? 0 : 1)
   );
 }
 

package/src/commands/login.ts

@@ -5,9 +5,9 @@ import { promptUser } from '../utils';
 export function promptClientToken(domain: string) {
   return promptUser(
     green(
-      `\n  🔑 Copy your API key from ${blue(`https://app.${domain}/profile`)} and paste it below`,
+      `\n  🔑 Copy your API key from ${blue(`https://app.${domain}/profile`)} and paste it below`
     ),
-    true,
+    true
   );
 }
 

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

@@ -9,29 +9,26 @@ import {
   getTotals,
   getMergedConfig,
 } from '@redocly/openapi-core';
-import { getFallbackEntryPointsOrExit } from '../../utils';
+import { getFallbackApisOrExit } from '../../utils';
 import startPreviewServer from './preview-server/preview-server';
-
-export async function previewDocs(argv: {
-  port: number;
-  host: string;
-  'use-community-edition'?: boolean;
-  config?: string;
-  entrypoint?: string;
-  'skip-rule'?: string[];
-  'skip-decorator'?: string[];
-  'skip-preprocessor'?: string[];
-  force?: boolean;
-}) {
+import type { Skips } from 'cli/src/types';
+
+export async function previewDocs(
+  argv: {
+    port: number;
+    host: string;
+    'use-community-edition'?: boolean;
+    config?: string;
+    api?: string;
+    force?: boolean;
+  } & Omit<Skips, 'skip-rule'>
+) {
   let isAuthorizedWithRedocly: boolean = false;
   let redocOptions: any = {};
   let config = await reloadConfig();
 
-  const entrypoints = await getFallbackEntryPointsOrExit(
-    argv.entrypoint ? [argv.entrypoint] : [],
-    config,
-  );
-  const entrypoint = entrypoints[0];
+  const apis = await getFallbackApisOrExit(argv.api ? [argv.api] : [], config);
+  const api = apis[0];
 
   let cachedBundle: any;
   const deps = new Set<string>();
@@ -48,7 +45,7 @@ export async function previewDocs(argv: {
         problems,
         fileDependencies,
       } = await bundle({
-        ref: entrypoint.path,
+        ref: api.path,
         config,
       });
       const removed = [...deps].filter((x) => !fileDependencies.has(x));
@@ -62,20 +59,20 @@ export async function previewDocs(argv: {
       if (fileTotals.errors === 0) {
         process.stdout.write(
           fileTotals.errors === 0
-            ? `Created a bundle for ${entrypoint.alias || entrypoint.path} ${
+            ? `Created a bundle for ${api.alias || api.path} ${
                 fileTotals.warnings > 0 ? 'with warnings' : 'successfully'
               }\n`
             : colorette.yellow(
                 `Created a bundle for ${
-                  entrypoint.alias || entrypoint.path
-                } with errors. Docs may be broken or not accurate\n`,
-              ),
+                  api.alias || api.path
+                } with errors. Docs may be broken or not accurate\n`
+              )
         );
       }
 
       return openapiBundle.parsed;
     } catch (e) {
-      handleError(e, entrypoint.path);
+      handleError(e, api.path);
     }
   }
 
@@ -87,8 +84,8 @@ export async function previewDocs(argv: {
   if (!isAuthorized) {
     process.stderr.write(
       `Using Redoc community edition.\nLogin with redocly ${colorette.blue(
-        'login',
-      )} or use an enterprise license key to preview with the premium docs.\n\n`,
+        'login'
+      )} or use an enterprise license key to preview with the premium docs.\n\n`
     );
   }
 
@@ -98,7 +95,7 @@ export async function previewDocs(argv: {
     useRedocPro: isAuthorized && !redocOptions.useCommunityEdition,
   });
 
-  const watchPaths = [entrypoint.path, config.configFile!].filter((e) => !!e);
+  const watchPaths = [api.path, config.configFile!].filter((e) => !!e);
   const watcher = chockidar.watch(watchPaths, {
     disableGlobbing: true,
     ignoreInitial: true,
@@ -127,9 +124,7 @@ export async function previewDocs(argv: {
 
   watcher.on('ready', () => {
     process.stdout.write(
-      `\n  👀  Watching ${colorette.blue(
-        entrypoint.path,
-      )} and all related resources for changes\n\n`,
+      `\n  👀  Watching ${colorette.blue(api.path)} and all related resources for changes\n\n`
     );
   });
 
@@ -137,10 +132,12 @@ export async function previewDocs(argv: {
     let config = await loadConfig(argv.config);
     const redoclyClient = new RedoclyClient();
     isAuthorizedWithRedocly = await redoclyClient.isAuthorizedWithRedocly();
-    const resolvedConfig = getMergedConfig(config, argv.entrypoint);
-    resolvedConfig.lint.skipRules(argv['skip-rule']);
-    resolvedConfig.lint.skipPreprocessors(argv['skip-preprocessor']);
-    resolvedConfig.lint.skipDecorators(argv['skip-decorator']);
+    const resolvedConfig = getMergedConfig(config, argv.api);
+    const { styleguide } = resolvedConfig;
+
+    styleguide.skipPreprocessors(argv['skip-preprocessor']);
+    styleguide.skipDecorators(argv['skip-decorator']);
+
     const referenceDocs = resolvedConfig['features.openapi'];
     redocOptions = {
       ...referenceDocs,
@@ -175,13 +172,9 @@ export function debounce(func: Function, wait: number, immediate?: boolean) {
 
 function handleError(e: Error, ref: string) {
   if (e instanceof ResolveError) {
-    process.stderr.write(
-      `Failed to resolve entrypoint definition at ${ref}:\n\n  - ${e.message}.\n\n`,
-    );
+    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 entrypoint definition at ${ref}:\n\n  - ${e.message}.\n\n`,
-    );
+    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

@@ -12,7 +12,7 @@ function getPageHTML(
   htmlTemplate: string,
   redocOptions: object = {},
   useRedocPro: boolean,
-  wsPort: number,
+  wsPort: number
 ) {
   let templateSrc = readFileSync(htmlTemplate, 'utf-8');
 
@@ -58,7 +58,7 @@ export default async function startPreviewServer(
     getBundle,
     getOptions,
     useRedocPro,
-  }: { getBundle: Function; getOptions: Function; useRedocPro: boolean },
+  }: { getBundle: Function; getOptions: Function; useRedocPro: boolean }
 ) {
   const defaultTemplate = path.join(__dirname, 'default.hbs');
   const handler = async (request: IncomingMessage, response: any) => {
@@ -72,7 +72,7 @@ export default async function startPreviewServer(
         response,
         {
           'Content-Type': 'text/html',
-        },
+        }
       );
     } else if (request.url === '/openapi.json') {
       const bundle = await getBundle();
@@ -90,7 +90,7 @@ export default async function startPreviewServer(
           response,
           {
             'Content-Type': 'application/json',
-          },
+          }
         );
       } else {
         respondWithGzip(JSON.stringify(bundle), request, response, {
@@ -134,7 +134,7 @@ export default async function startPreviewServer(
             request,
             response,
             {},
-            500,
+            500
           );
         }
       }
@@ -147,7 +147,7 @@ export default async function startPreviewServer(
   const server = startHttpServer(port, host, handler);
   server.on('listening', () => {
     process.stdout.write(
-      `\n  🔎  Preview server running at ${colorette.blue(`http://${host}:${port}\n`)}`,
+      `\n  🔎  Preview server running at ${colorette.blue(`http://${host}:${port}\n`)}`
     );
   });
 

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

@@ -28,7 +28,7 @@ export function respondWithGzip(
   request: http.IncomingMessage,
   response: http.ServerResponse,
   headers = {},
-  code = 200,
+  code = 200
 ) {
   let compressedStream;
   const acceptEncoding = (request.headers['accept-encoding'] as string) || '';

package/src/commands/push.ts

@@ -19,7 +19,7 @@ import {
 import {
   exitWithError,
   printExecutionTime,
-  getFallbackEntryPointsOrExit,
+  getFallbackApisOrExit,
   pluralize,
   dumpBundle,
 } from '../utils';
@@ -28,7 +28,7 @@ import { promptClientToken } from './login';
 const DEFAULT_VERSION = 'latest';
 
 type PushArgs = {
-  entrypoint?: string;
+  api?: string;
   destination?: string;
   branchName?: string;
   upsert?: boolean;
@@ -36,7 +36,7 @@ type PushArgs = {
   'batch-size'?: number;
   region?: Region;
   'skip-decorator'?: string[];
-  'public'?: boolean;
+  public?: boolean;
 };
 
 export async function handlePush(argv: PushArgs): Promise<void> {
@@ -61,8 +61,8 @@ export async function handlePush(argv: PushArgs): Promise<void> {
   ) {
     exitWithError(
       `Destination argument value is not valid, please use the right format: ${yellow(
-        '<@organization-id/api-name@api-version>',
-      )}`,
+        '<@organization-id/api-name@api-version>'
+      )}`
     );
   }
 
@@ -71,18 +71,17 @@ export async function handlePush(argv: PushArgs): Promise<void> {
   if (!organizationId) {
     return exitWithError(
       `No organization provided, please use the right format: ${yellow(
-        '<@organization-id/api-name@api-version>',
-      )} or specify the 'organization' field in the config file.`,
+        '<@organization-id/api-name@api-version>'
+      )} or specify the 'organization' field in the config file.`
     );
   }
-  const entrypoint =
-    argv.entrypoint || (name && version && getApiEntrypoint({ name, version, config }));
+  const api = argv.api || (name && version && getApiRoot({ name, version, config }));
 
-  if (name && version && !entrypoint) {
+  if (name && version && !api) {
     exitWithError(
-      `No entrypoint found that matches ${blue(
-        `${name}@${version}`,
-      )}. Please make sure you have provided the correct data in the config file.`,
+      `No api found that matches ${blue(
+        `${name}@${version}`
+      )}. Please make sure you have provided the correct data in the config file.`
     );
   }
 
@@ -98,24 +97,24 @@ export async function handlePush(argv: PushArgs): Promise<void> {
     );
   }
 
-  const apis = entrypoint ? { [`${name}@${version}`]: { root: entrypoint } } : config.apis;
+  const apis = api ? { [`${name}@${version}`]: { root: api } } : config.apis;
 
-  for (const [apiNameAndVersion, { root: entrypoint }] of Object.entries(apis)) {
+  for (const [apiNameAndVersion, { root: api }] of Object.entries(apis)) {
     const resolvedConfig = getMergedConfig(config, apiNameAndVersion);
-    resolvedConfig.lint.skipDecorators(argv['skip-decorator']);
+    resolvedConfig.styleguide.skipDecorators(argv['skip-decorator']);
 
     const [name, version = DEFAULT_VERSION] = apiNameAndVersion.split('@');
     try {
       let rootFilePath = '';
       const filePaths: string[] = [];
-      const filesToUpload = await collectFilesToUpload(entrypoint, resolvedConfig);
+      const filesToUpload = await collectFilesToUpload(api, resolvedConfig);
       const filesHash = hashFiles(filesToUpload.files);
 
       process.stdout.write(
         `Uploading ${filesToUpload.files.length} ${pluralize(
           'file',
-          filesToUpload.files.length,
-        )}:\n`,
+          filesToUpload.files.length
+        )}:\n`
       );
 
       let uploaded = 0;
@@ -137,12 +136,12 @@ export async function handlePush(argv: PushArgs): Promise<void> {
         filePaths.push(filePath);
 
         process.stdout.write(
-          `Uploading ${file.contents ? 'bundle for ' : ''}${blue(file.filePath)}...`,
+          `Uploading ${file.contents ? 'bundle for ' : ''}${blue(file.filePath)}...`
         );
 
         const uploadResponse = await uploadFileToS3(
           signedUploadUrl,
-          file.contents || file.filePath,
+          file.contents || file.filePath
         );
 
         const fileCounter = `(${++uploaded}/${filesToUpload.files.length})`;
@@ -175,9 +174,9 @@ export async function handlePush(argv: PushArgs): Promise<void> {
 
       if (error.message === 'API_VERSION_NOT_FOUND') {
         exitWithError(`The definition version ${blue(name)}/${blue(
-          version,
+          version
         )} does not exist in organization ${blue(organizationId)}!\n${yellow(
-          'Suggestion:',
+          'Suggestion:'
         )} please use ${blue('-u')} or ${blue('--upsert')} to create definition.
         `);
       }
@@ -186,10 +185,10 @@ export async function handlePush(argv: PushArgs): Promise<void> {
     }
 
     process.stdout.write(
-      `Definition: ${blue(entrypoint!)} is successfully pushed to Redocly API Registry \n`,
+      `Definition: ${blue(api!)} is successfully pushed to Redocly API Registry \n`
     );
   }
-  printExecutionTime('push', startedAt, entrypoint || `apis in organization ${organizationId}`);
+  printExecutionTime('push', startedAt, api || `apis in organization ${organizationId}`);
 }
 
 function getFilesList(dir: string, files?: any): string[] {
@@ -206,15 +205,15 @@ function getFilesList(dir: string, files?: any): string[] {
   return files;
 }
 
-async function collectFilesToUpload(entrypoint: string, config: Config) {
+async function collectFilesToUpload(api: string, config: Config) {
   let files: { filePath: string; keyOnS3: string; contents?: Buffer }[] = [];
-  const [{ path: entrypointPath }] = await getFallbackEntryPointsOrExit([entrypoint], config);
+  const [{ path: apiPath }] = await getFallbackApisOrExit([api], config);
 
   process.stdout.write('Bundling definition\n');
 
   const { bundle: openapiBundle, problems } = await bundle({
     config,
-    ref: entrypointPath,
+    ref: apiPath,
     skipRedoclyRegistryRefs: true,
   });
 
@@ -222,17 +221,15 @@ async function collectFilesToUpload(entrypoint: string, config: Config) {
 
   if (fileTotals.errors === 0) {
     process.stdout.write(
-      `Created a bundle for ${blue(entrypoint)} ${
-        fileTotals.warnings > 0 ? 'with warnings' : ''
-      }\n`,
+      `Created a bundle for ${blue(api)} ${fileTotals.warnings > 0 ? 'with warnings' : ''}\n`
     );
   } else {
-    exitWithError(`Failed to create a bundle for ${blue(entrypoint)}\n`);
+    exitWithError(`Failed to create a bundle for ${blue(api)}\n`);
   }
 
-  const fileExt = path.extname(entrypointPath).split('.').pop();
+  const fileExt = path.extname(apiPath).split('.').pop();
   files.push(
-    getFileEntry(entrypointPath, dumpBundle(openapiBundle.parsed, fileExt as BundleOutputFormat)),
+    getFileEntry(apiPath, dumpBundle(openapiBundle.parsed, fileExt as BundleOutputFormat))
   );
 
   if (fs.existsSync('package.json')) {
@@ -243,14 +240,14 @@ async function collectFilesToUpload(entrypoint: string, config: Config) {
   }
   if (config.configFile) {
     // All config file paths including the root one
-    files.push(...[...new Set(config.lint.extendPaths)].map((f) => getFileEntry(f)));
+    files.push(...[...new Set(config.styleguide.extendPaths)].map((f) => getFileEntry(f)));
     if (config['features.openapi'].htmlTemplate) {
       const dir = getFolder(config['features.openapi'].htmlTemplate);
       const fileList = getFilesList(dir, []);
       files.push(...fileList.map((f) => getFileEntry(f)));
     }
     let pluginFiles = new Set<string>();
-    for (const plugin of config.lint.pluginPaths) {
+    for (const plugin of config.styleguide.pluginPaths) {
       if (typeof plugin !== 'string') continue;
       const fileList = getFilesList(getFolder(plugin), []);
       fileList.forEach((f) => pluginFiles.add(f));
@@ -259,7 +256,7 @@ async function collectFilesToUpload(entrypoint: string, config: Config) {
   }
   return {
     files,
-    root: path.resolve(entrypointPath),
+    root: path.resolve(apiPath),
   };
 
   function filterPluginFilesByExt(files: string[]) {
@@ -302,7 +299,7 @@ function validateDestinationWithoutOrganization(destination: string) {
 
 export function getDestinationProps(
   destination: string | undefined,
-  organization: string | undefined,
+  organization: string | undefined
 ) {
   return destination && validateDestination(destination)
     ? destination.substring(1).split(/[@\/]/)
@@ -311,8 +308,8 @@ export function getDestinationProps(
     : [organization];
 }
 
-type BarePushArgs = Omit<PushArgs, 'entrypoint' | 'destination' | 'branchName'> & {
-  maybeEntrypointOrAliasOrDestination?: string;
+type BarePushArgs = Omit<PushArgs, 'api' | 'destination' | 'branchName'> & {
+  maybeApiOrDestination?: string;
   maybeDestination?: string;
   maybeBranchName?: string;
   branch?: string;
@@ -320,31 +317,25 @@ type BarePushArgs = Omit<PushArgs, 'entrypoint' | 'destination' | 'branchName'>
 
 export const transformPush =
   (callback: typeof handlePush) =>
-  ({
-    maybeEntrypointOrAliasOrDestination,
-    maybeDestination,
-    maybeBranchName,
-    branch,
-    ...rest
-  }: BarePushArgs) => {
+  ({ maybeApiOrDestination, maybeDestination, maybeBranchName, branch, ...rest }: BarePushArgs) => {
     if (!!maybeBranchName) {
       process.stderr.write(
         yellow(
-          'Deprecation warning: Do not use the third parameter as a branch name. Please use a separate --branch option instead.',
-        ),
+          'Deprecation warning: Do not use the third parameter as a branch name. Please use a separate --branch option instead.'
+        )
       );
     }
-    const entrypoint = maybeDestination ? maybeEntrypointOrAliasOrDestination : undefined;
-    const destination = maybeDestination || maybeEntrypointOrAliasOrDestination;
+    const api = maybeDestination ? maybeApiOrDestination : undefined;
+    const destination = maybeDestination || maybeApiOrDestination;
     return callback({
       ...rest,
       destination,
-      entrypoint,
+      api,
       branchName: branch ?? maybeBranchName,
     });
   };
 
-export function getApiEntrypoint({
+export function getApiRoot({
   name,
   version,
   config: { apis },