Redocly · DmitryAnansky · Apr 4, 2024 · Mar 26, 2024 · Mar 26, 2024 · Mar 27, 2024
@@ -0,0 +1,5 @@
+---
+"@redocly/cli": minor
+---
+
+Removed additional operations from the `join` command; use `lint` and/or `bundle` for operations such as `lint` and `decorate`.
@@ -291,7 +291,6 @@ describe('E2E', () => {
         { name: 'prefix-tags-with-filename', value: true },
         { name: 'without-x-tag-groups', value: true },
         { name: 'prefix-components-with-info-prop', value: 'title' },
-        { name: 'decorate', value: true },
       ];
 
       test.each(options)('test with option: %s', (option) => {

@@ -18,12 +18,16 @@ The `join` command accepts both YAML and JSON files, which you can mix in the re
 
 Apart from providing individual API description files as the input, you can also specify the path to a folder that contains multiple API description files and match them with a wildcard (for example, `myproject/openapi/*.(yaml/json)`). The `join` command collects all matching files and combines them into one file.
 
+{% admonition type="info" name="Use join with other commands" %}
+We recommend running [`lint`](./lint.md) before joining API descriptions to ensure that they are valid and meet the expected standards.
+You may also want to use [decorators](./../decorators.md) to add any filtering or transformation needed for your API descriptions, either before or after bundling.
+{% /admonition %}
+
 ### Usage
 
 ```bash
 redocly join <api> <api>...
 redocly join <api> <api>... -o <outputName>
-redocly join <path-to-folder>/<wildcard-pattern> [--lint]
 redocly join [--help] [--prefix-components-with-info-prop] [--prefix-tags-with-info-prop] [--prefix-tags-with-filename]
 
 redocly join first-api.yaml second-api.yaml
@@ -35,24 +39,16 @@ redocly join --version
 
 ## Options
 
-{% admonition type="warning" name="Important" %}
-The `--lint` option is deprecated and is marked for removal in future releases.
-Use the [lint command](./lint.md) separately to lint your APIs before joining.
-{% /admonition %}
-
 | Option                             | Type     | Description                                                                                                                                                                                                |
 | ---------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | apis                               | [string] | **REQUIRED.** 1. Array of paths to API description files that you want to join. At least two input files are required.<br />2. A wildcard pattern to match API description files within a specific folder. |
 | --config                           | string   | Specify path to the [config file](../configuration/index.md).                                                                                                                                              |
-| --decorate                         | boolean  | Run decorators.                                                                                                                                                                                            |
 | --help                             | boolean  | Show help.                                                                                                                                                                                                 |
-| --lint (**Deprecated**)            | boolean  | Lint API description files.                                                                                                                                                                                |
 | --lint-config                      | string   | Specify the severity level for the configuration file. <br/> **Possible values:** `warn`, `error`, `off`. Default value is `warn`.                                                                         |
 | --output, -o                       | string   | Name for the joined output file. Defaults to `openapi.yaml` or `openapi.json` (Depends on the extension of the first input file). **If the file already exists, it's overwritten.**                        |
 | --prefix-components-with-info-prop | string   | Prefix components with property value from info object. See the [prefix-components-with-info-prop section](#prefix-components-with-info-prop) below.                                                       |
 | --prefix-tags-with-filename        | string   | Prefix tags with property value from file name. See the [prefix-tags-with-filename section](#prefix-tags-with-filename) below.                                                                             |
 | --prefix-tags-with-info-prop       | boolean  | Prefix tags with property value from info object. See the [prefix-tags-with-info-prop](#prefix-tags-with-info-prop) section.                                                                               |
-| --preprocess                       | boolean  | Run preprocessors.                                                                                                                                                                                         |
 | --version                          | boolean  | Show version number.                                                                                                                                                                                       |
 | --without-x-tag-groups             | boolean  | Skip automated `x-tagGroups` creation. See the [without-x-tag-groups](#without-x-tag-groups) section.                                                                                                      |
 

@@ -165,23 +165,6 @@ describe('handleJoin', () => {
     expect(config.styleguide.skipPreprocessors).toHaveBeenCalled();
   });
 
-  it('should not call skipDecorators and skipPreprocessors', async () => {
-    (detectSpec as jest.Mock).mockReturnValue('oas3_0');
-    await handleJoin(
-      {
-        apis: ['first.yaml', 'second.yaml'],
-        decorate: true,
-        preprocess: true,
-      },
-      ConfigFixture as any,
-      'cli-version'
-    );
-
-    const config = loadConfig();
-    expect(config.styleguide.skipDecorators).not.toHaveBeenCalled();
-    expect(config.styleguide.skipPreprocessors).not.toHaveBeenCalled();
-  });
-
   it('should handle join with prefix-components-with-info-prop and null values', async () => {
     (detectSpec as jest.Mock).mockReturnValue('oas3_0');
 

@@ -6,24 +6,19 @@
   Config,
   SpecVersion,
   BaseResolver,
-  StyleguideConfig,
   formatProblems,
   getTotals,
-  lintDocument,
   detectSpec,
   bundleDocument,
   isRef,
 } from '@redocly/openapi-core';
 import {
   getFallbackApisOrExit,
   printExecutionTime,
-  handleError,
-  printLintTotals,
   exitWithError,
   sortTopLevelKeysForOas,
   getAndValidateFileExtension,
   writeToFileByExtension,
-  checkForDeprecatedOptions,
 } from '../utils/miscellaneous';
 import { isObject, isString, keysOf } from '../utils/js-utils';
 import { COMPONENTS, OPENAPI3_METHOD } from './split/types';
@@ -53,16 +48,13 @@
  apiFilename: string;
  apiTitle?: string;
  tags: Oas3Tag[];
  potentialConflicts: any;
  tagsPrefix: string;
  componentsPrefix: string | undefined;
 };
 
 export type JoinOptions = {
   apis: string[];
-  lint?: boolean;
-  decorate?: boolean;
-  preprocess?: boolean;
   'prefix-tags-with-info-prop'?: string;
   'prefix-tags-with-filename'?: boolean;
   'prefix-components-with-info-prop'?: string;
@@ -79,8 +71,6 @@
     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 {
@@ -111,23 +101,19 @@
     )
   );
 
-  if (!argv.decorate) {
-    const decorators = new Set([
-      ...Object.keys(config.styleguide.decorators.oas3_0),
-      ...Object.keys(config.styleguide.decorators.oas3_1),
-      ...Object.keys(config.styleguide.decorators.oas2),
-    ]);
-    config.styleguide.skipDecorators(Array.from(decorators));
-  }
+  const decorators = new Set([
+    ...Object.keys(config.styleguide.decorators.oas3_0),
+    ...Object.keys(config.styleguide.decorators.oas3_1),
+    ...Object.keys(config.styleguide.decorators.oas2),
+  ]);
+  config.styleguide.skipDecorators(Array.from(decorators));
 
-  if (!argv.preprocess) {
-    const preprocessors = new Set([
-      ...Object.keys(config.styleguide.preprocessors.oas3_0),
-      ...Object.keys(config.styleguide.preprocessors.oas3_1),
-      ...Object.keys(config.styleguide.preprocessors.oas2),
-    ]);
-    config.styleguide.skipPreprocessors(Array.from(preprocessors));
-  }
+  const preprocessors = new Set([
+    ...Object.keys(config.styleguide.preprocessors.oas3_0),
+    ...Object.keys(config.styleguide.preprocessors.oas3_1),
+    ...Object.keys(config.styleguide.preprocessors.oas2),
+  ]);
+  config.styleguide.skipPreprocessors(Array.from(preprocessors));
 
   const bundleResults = await Promise.all(
     documents.map((document) =>
@@ -146,7 +132,7 @@
     if (fileTotals.errors) {
       formatProblems(problems, {
         totals: fileTotals,
-        version: document.parsed.version,
+        version: packageVersion,
       });
       exitWithError(
         `❌ Errors encountered while bundling ${blue(
@@ -179,13 +165,7 @@
     }
   }
 
-  if (argv.lint) {
-    for (const document of documents) {
-      await validateApi(document, config.styleguide, externalRefResolver, packageVersion);
-    }
-  }
-
   const joinedDef: any = {};
   const potentialConflicts = {
     tags: {},
    paths: {},
@@ -308,7 +288,7 @@
  }

  function getIndexGroup(name: string): number {
    return joinedDef[xTagGroups].findIndex((item: any) => item.name === name);
  }

  function createXTagGroups(name: string) {
@@ -316,7 +296,7 @@
      joinedDef[xTagGroups] = [];
    }

    if (!joinedDef[xTagGroups].some((g: any) => g.name === name)) {
      joinedDef[xTagGroups].push({ name, tags: [] });
    }

@@ -342,7 +322,7 @@
        joinedDef['servers'] = [];
      }
      for (const server of servers) {
        if (!joinedDef.servers.some((s: any) => s.url === server.url)) {
          joinedDef.servers.push(server);
        }
      }
@@ -641,7 +621,7 @@
  }

  function addInfoSectionAndSpecVersion(
    documents: any,
    prefixComponentsWithInfoProp: string | undefined
  ) {
    const firstApi = documents[0];
@@ -787,22 +767,6 @@
   return info[prefixArg].replaceAll(/\s/g, '_');
 }
 
-async function validateApi(
-  document: Document,
-  config: StyleguideConfig,
-  externalRefResolver: BaseResolver,
-  packageVersion: string
-) {
-  try {
-    const results = await lintDocument({ document, config, externalRefResolver });
-    const fileTotals = getTotals(results);
-    formatProblems(results, { format: 'stylish', totals: fileTotals, version: packageVersion });
-    printLintTotals(fileTotals, 2);
-  } catch (err) {
-    handleError(err, document.parsed);
-  }
-}
-
 function replace$Refs(obj: unknown, componentsPrefix: string) {
   crawl(obj, (node: Record<string, unknown>) => {
     if (node.$ref && typeof node.$ref === 'string' && startsWithComponents(node.$ref)) {

@@ -105,9 +105,6 @@ yargs
           demandOption: true,
         })
         .option({
-          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': {
             description: 'Prefix tags with property value from info object.',
             requiresArg: true,
@@ -142,8 +139,47 @@ yargs
             choices: ['warn', 'error', 'off'] as ReadonlyArray<RuleSeverity>,
             default: 'warn' as RuleSeverity,
           },
+          lint: {
+            hidden: true,
+            deprecated: true,
+          },
+          decorate: {
+            hidden: true,
+            deprecated: true,
+          },
+          preprocess: {
+            hidden: true,
+            deprecated: true,
+          },
         }),
     (argv) => {
+      const DEPRECATED_OPTIONS = ['lint', 'preprocess', 'decorate'];
+      const DECORATORS_DOCUMENTATION_LINK = 'https://redocly.com/docs/cli/decorators/#decorators';
+      const JOIN_COMMAND_DOCUMENTATION_LINK = 'https://redocly.com/docs/cli/commands/join/#join';
+
+      DEPRECATED_OPTIONS.forEach((option) => {
+        if (argv[option]) {
+          process.stdout.write(
+            `${colors.red(
+              `Option --${option} is no longer supported. Please review join command documentation ${JOIN_COMMAND_DOCUMENTATION_LINK}.`
+            )}`
+          );
+          process.stdout.write('\n\n');
+
+          if (['preprocess', 'decorate'].includes(option)) {
+            process.stdout.write(
+              `${colors.red(
+                `If you are looking for decorators, please review the decorators documentation ${DECORATORS_DOCUMENTATION_LINK}.`
+              )}`
+            );
+            process.stdout.write('\n\n');
+          }
+
+          yargs.showHelp();
+          process.exit(1);
+        }
+      });
+
       process.env.REDOCLY_CLI_COMMAND = 'join';
       commandWrapper(handleJoin)(argv);
     }