diff --git a/.changeset/gold-cougars-relax.md b/.changeset/gold-cougars-relax.md new file mode 100644 index 0000000000..d5bd0f89d8 --- /dev/null +++ b/.changeset/gold-cougars-relax.md @@ -0,0 +1,6 @@ +--- +"@redocly/cli": patch +--- + +Deprecated lint-related options in the `bundle` command. The options are going to be removed in the subsequent releases. +Use the [lint command](https://redocly.com/docs/cli/commands/lint/) separately to lint your APIs before bundling. diff --git a/__tests__/bundle/bundle-lint-format/checkstyle-format-snapshot.js b/__tests__/bundle/bundle-lint-format/checkstyle-format-snapshot.js index a568419ec4..a0cf2f97df 100644 --- a/__tests__/bundle/bundle-lint-format/checkstyle-format-snapshot.js +++ b/__tests__/bundle/bundle-lint-format/checkstyle-format-snapshot.js @@ -8,6 +8,12 @@ exports[`E2E bundle lint format bundle lint: should be formatted by format: chec +[WARNING] "lint" option is deprecated and will be removed in a future release. + +[WARNING] "format" option is deprecated and will be removed in a future release. + +[WARNING] "max-problems" option is deprecated and will be removed in a future release. + ❌ Validation failed with 1 error. run \`redocly lint --generate-ignore-file\` to add all problems to the ignore file. diff --git a/__tests__/bundle/bundle-lint-format/codeframe-format-snapshot.js b/__tests__/bundle/bundle-lint-format/codeframe-format-snapshot.js index 59659afdd3..62223964c9 100644 --- a/__tests__/bundle/bundle-lint-format/codeframe-format-snapshot.js +++ b/__tests__/bundle/bundle-lint-format/codeframe-format-snapshot.js @@ -2,6 +2,12 @@ exports[`E2E bundle lint format bundle lint: should be formatted by format: codeframe 1`] = ` +[WARNING] "lint" option is deprecated and will be removed in a future release. + +[WARNING] "format" option is deprecated and will be removed in a future release. + +[WARNING] "max-problems" option is deprecated and will be removed in a future release. + [1] openapi.yaml:20:11 at #/paths/~1my_post/post/requestBody/content/application~1json Expected type \`MediaType\` (object) but got \`null\` diff --git a/__tests__/bundle/bundle-lint-format/emptyFormatValue-snapshot.js b/__tests__/bundle/bundle-lint-format/emptyFormatValue-snapshot.js index 68d6f492bc..104e94f411 100644 --- a/__tests__/bundle/bundle-lint-format/emptyFormatValue-snapshot.js +++ b/__tests__/bundle/bundle-lint-format/emptyFormatValue-snapshot.js @@ -2,23 +2,33 @@ exports[`E2E bundle lint format bundle lint: no format parameter or empty value should be formatted as codeframe 1`] = ` -[1] openapi.yaml:20:11 at #/paths/~1my_post/post/requestBody/content/application~1json - -Expected type \`MediaType\` (object) but got \`null\` - -18 | requestBody: -19 | content: -20 | application/json: - | ^^^^^^^^^^^^^^^^^ -21 | - -Error was generated by the spec rule. - - -❌ Validation failed with 1 error. -run \`redocly lint --generate-ignore-file\` to add all problems to the ignore file. - -bundling ./openapi.yaml... -📦 Created a bundle for ./openapi.yaml at /tmp/null.yaml ms. +index.ts bundle [apis...] + +Bundle definition. + +Positionals: + apis [array] [default: []] + +Options: + --version Show version number. [boolean] + --help Show help. [boolean] + -o, --output [string] + --ext Bundle file extension. + [choices: "json", "yaml", "yml"] + --skip-preprocessor Ignore certain preprocessors. [array] + --skip-decorator Ignore certain decorators. [array] + -d, --dereferenced Produce a fully dereferenced bundle. [boolean] + -f, --force Produce bundle output even when errors occur. + [boolean] + --config Path to the config file. [string] + --metafile Produce metadata about the bundle [string] + --remove-unused-components Remove unused components. + [boolean] [default: false] + -k, --keep-url-references Keep absolute url references. [boolean] + --lint-config Severity level for config file linting. + [choices: "warn", "error", "off"] [default: "warn"] + +Invalid values: + Argument: format, Given: true, Choices: "stylish", "codeframe", "json", "checkstyle" `; diff --git a/__tests__/bundle/bundle-lint-format/json-format-snapshot.js b/__tests__/bundle/bundle-lint-format/json-format-snapshot.js index 06aefccdec..7400a51fc5 100644 --- a/__tests__/bundle/bundle-lint-format/json-format-snapshot.js +++ b/__tests__/bundle/bundle-lint-format/json-format-snapshot.js @@ -34,6 +34,12 @@ exports[`E2E bundle lint format bundle lint: should be formatted by format: json "version": "", "problems": [] } +[WARNING] "lint" option is deprecated and will be removed in a future release. + +[WARNING] "format" option is deprecated and will be removed in a future release. + +[WARNING] "max-problems" option is deprecated and will be removed in a future release. + ❌ Validation failed with 1 error. run \`redocly lint --generate-ignore-file\` to add all problems to the ignore file. diff --git a/__tests__/bundle/bundle-lint-format/noFormatParameter-snapshot.js b/__tests__/bundle/bundle-lint-format/noFormatParameter-snapshot.js index 68d6f492bc..608e899808 100644 --- a/__tests__/bundle/bundle-lint-format/noFormatParameter-snapshot.js +++ b/__tests__/bundle/bundle-lint-format/noFormatParameter-snapshot.js @@ -2,6 +2,10 @@ exports[`E2E bundle lint format bundle lint: no format parameter or empty value should be formatted as codeframe 1`] = ` +[WARNING] "lint" option is deprecated and will be removed in a future release. + +[WARNING] "max-problems" option is deprecated and will be removed in a future release. + [1] openapi.yaml:20:11 at #/paths/~1my_post/post/requestBody/content/application~1json Expected type \`MediaType\` (object) but got \`null\` diff --git a/__tests__/bundle/bundle-lint-format/stylish-format-snapshot.js b/__tests__/bundle/bundle-lint-format/stylish-format-snapshot.js index 695b209570..31c559b6c9 100644 --- a/__tests__/bundle/bundle-lint-format/stylish-format-snapshot.js +++ b/__tests__/bundle/bundle-lint-format/stylish-format-snapshot.js @@ -2,6 +2,12 @@ exports[`E2E bundle lint format bundle lint: should be formatted by format: stylish 1`] = ` +[WARNING] "lint" option is deprecated and will be removed in a future release. + +[WARNING] "format" option is deprecated and will be removed in a future release. + +[WARNING] "max-problems" option is deprecated and will be removed in a future release. + openapi.yaml: 20:11 error spec Expected type \`MediaType\` (object) but got \`null\` diff --git a/__tests__/bundle/info-description-override-error/snapshot.js b/__tests__/bundle/info-description-override-error/snapshot.js index 8d5e3e9d4c..cf94eacfda 100644 --- a/__tests__/bundle/info-description-override-error/snapshot.js +++ b/__tests__/bundle/info-description-override-error/snapshot.js @@ -3,10 +3,21 @@ exports[`E2E bundle info-description-override-error 1`] = ` bundling ./main.yaml... -main.yaml: - 8:16 error info-description-override Failed to read markdown override file for "info.description". +[1] main.yaml:8:16 at #/info/description + +Failed to read markdown override file for "info.description". ENOENT: no such file or directory, open './test.md' + 6 | title: Example OpenAPI 3 definition. + 7 | version: 1.0.0 + 8 | description: some description + | ^^^^^^^^^^^^^^^^ + 9 | license: +10 | name: Apache 2.0 + +Error was generated by the info-description-override rule. + + ❌ Errors encountered while bundling ./main.yaml: bundle not created (use --force to ignore errors). `; diff --git a/__tests__/bundle/max-problems-argument/snapshot.js b/__tests__/bundle/max-problems-argument/snapshot.js index 63639c20c3..b1b75d279b 100644 --- a/__tests__/bundle/max-problems-argument/snapshot.js +++ b/__tests__/bundle/max-problems-argument/snapshot.js @@ -238,6 +238,12 @@ components: items: $ref: '#/components/schemas/Pet' +[WARNING] "lint" option is deprecated and will be removed in a future release. + +[WARNING] "format" option is deprecated and will be removed in a future release. + +[WARNING] "max-problems" option is deprecated and will be removed in a future release. + foo.yaml: 30:11 error spec Property \`header\` is not expected here. diff --git a/__tests__/bundle/operation-description-override-error/snapshot.js b/__tests__/bundle/operation-description-override-error/snapshot.js index 9a52cc0379..a055c1c039 100644 --- a/__tests__/bundle/operation-description-override-error/snapshot.js +++ b/__tests__/bundle/operation-description-override-error/snapshot.js @@ -3,10 +3,21 @@ exports[`E2E bundle operation-description-override-error 1`] = ` bundling ./openapi.yaml... -openapi.yaml: - 23:7 error operation-description-override Failed to read markdown override file for operation "updatePet". +[1] openapi.yaml:23:7 at #/paths/~1pet/put/operationId + +Failed to read markdown override file for operation "updatePet". ENOENT: no such file or directory, open './update-pet-operation-description.md' +21 | summary: Update an existing pet +22 | description: '' +23 | operationId: updatePet + | ^^^^^^^^^^^ +24 | responses: +25 | '200': + +Error was generated by the operation-description-override rule. + + ❌ Errors encountered while bundling ./openapi.yaml: bundle not created (use --force to ignore errors). `; diff --git a/__tests__/bundle/tag-description-override-error/snapshot.js b/__tests__/bundle/tag-description-override-error/snapshot.js index 8d197842f0..b9f31c2c65 100644 --- a/__tests__/bundle/tag-description-override-error/snapshot.js +++ b/__tests__/bundle/tag-description-override-error/snapshot.js @@ -3,10 +3,23 @@ exports[`E2E bundle tag-description-override-error 1`] = ` bundling ./main.yaml... -main.yaml: - 17:5 error tag-description-override Failed to read markdown override file for tag "pet". +[1] main.yaml:17:5 at #/tags/0 + +Failed to read markdown override file for tag "pet". ENOENT: no such file or directory, open './pet-tag-description.md' +15 | email: email@redoc.ly +16 | tags: +17 | - name: pet + | ^^^^^^^^^ +18 | description: Everything about your Pets + | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ +19 | - name: store +20 | description: Access to Petstore orders + +Error was generated by the tag-description-override rule. + + ❌ Errors encountered while bundling ./main.yaml: bundle not created (use --force to ignore errors). `; diff --git a/__tests__/commands.test.ts b/__tests__/commands.test.ts index fb67228840..61e96d0b89 100644 --- a/__tests__/commands.test.ts +++ b/__tests__/commands.test.ts @@ -287,10 +287,7 @@ describe('E2E', () => { const entryPoints = getEntrypoints(testPath); - const args = getParams('../../../packages/cli/src/index.ts', 'bundle', [ - '--format=stylish', - ...entryPoints, - ]); + const args = getParams('../../../packages/cli/src/index.ts', 'bundle', [...entryPoints]); it(file, () => { const result = getCommandOutput(args, testPath); diff --git a/__tests__/miscellaneous/resolve-refs-in-preprocessors/snapshot.js b/__tests__/miscellaneous/resolve-refs-in-preprocessors/snapshot.js index 7cde290f38..bfac771727 100644 --- a/__tests__/miscellaneous/resolve-refs-in-preprocessors/snapshot.js +++ b/__tests__/miscellaneous/resolve-refs-in-preprocessors/snapshot.js @@ -52,6 +52,8 @@ components: error_code: type: number +[WARNING] "lint" option is deprecated and will be removed in a future release. + [1] openapi.yaml:4:1 at #/info Info object should contain \`license\` field. diff --git a/__tests__/webpack-bundle/bundle-workflows/result-snapshot.js b/__tests__/webpack-bundle/bundle-workflows/result-snapshot.js index ade6a84b26..f924c58a1a 100644 --- a/__tests__/webpack-bundle/bundle-workflows/result-snapshot.js +++ b/__tests__/webpack-bundle/bundle-workflows/result-snapshot.js @@ -2,6 +2,8 @@ exports[`webpack-bundle test bundle-workflows 1`] = ` +[WARNING] "extends" option is deprecated and will be removed in a future release. + bundling ./openapi.yaml... 📦 Created a bundle for ./openapi.yaml at bundle.yaml ms. diff --git a/__tests__/webpack-bundle/bundle/snapshot.js b/__tests__/webpack-bundle/bundle/snapshot.js index 4a2f0e0875..9f5dbe4e79 100644 --- a/__tests__/webpack-bundle/bundle/snapshot.js +++ b/__tests__/webpack-bundle/bundle/snapshot.js @@ -2,6 +2,10 @@ exports[`webpack-bundle test bundle check 1`] = ` +[WARNING] "lint" option is deprecated and will be removed in a future release. + +[WARNING] "max-problems" option is deprecated and will be removed in a future release. + Woohoo! Your API descriptions are valid. 🎉 bundling ./openapi.yaml... diff --git a/docs/commands/bundle.md b/docs/commands/bundle.md index ae5b81bd30..6643e4e824 100644 --- a/docs/commands/bundle.md +++ b/docs/commands/bundle.md @@ -12,35 +12,40 @@ The `bundle` command first executes preprocessors, then rules, then decorators. ```bash redocly bundle ... -redocly bundle [--max-problems=] -redocly bundle [--lint] [--config=] +redocly bundle [--remove-unused-components] +redocly bundle [--config=] redocly bundle ... -o --ext redocly bundle --version ``` ## Options -| Option | Type | Description | -| -------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| apis | [string] | List of API description root filenames or names assigned in the `apis` section of your Redocly configuration file. Default values are all names defined in the `apis` section within your configuration file. | -| --config | string | Specify path to the [config file](#custom-configuration-file). | -| --dereferenced, -d | boolean | Generate fully dereferenced bundle. | -| --ext | string | Specify bundled file extension. Possible values are `json`, `yaml`, or `yml`. Default value is `yaml`. | -| --extends | [string] | Can be used in combination with `--lint` to [extend a specific configuration](./lint.md#extend-configuration). Default values are taken from the Redocly configuration file. | -| --force, -f | boolean | Generate bundle output even when errors occur. | -| --format | string | Format for the output. Possible values are `codeframe`, `stylish`, `json`, or `checkstyle`. Default value is `codeframe`. | -| --help | boolean | Show help. | -| --keep-url-references, -k | boolean | Keep absolute url references. | -| --lint | boolean | Lint API description files. Default value is `false`. | -| --lint-config | string | Specify the severity level for the configuration file.
**Possible values:** `warn`, `error`, `off`. Default value is `warn`. | -| --max-problems | integer | Truncate output to display the specified maximum number of problems. Default value is `100`. | -| --metafile | string | Path for the bundle metadata file. | -| --output, -o | string | Name or folder for the bundle file. If you don't specify the file extension, `.yaml` is used by default. If the specified folder doesn't exist, it's created automatically. **If the file specified as the bundler's output already exists, it's overwritten.** | -| --remove-unused-components | boolean | Remove unused components from the `bundle` output. | -| --skip-decorator | [string] | Ignore certain decorators. See the [Skip preprocessor, rule, or decorator section](#skip-preprocessor-rule-or-decorator). | -| --skip-preprocessor | [string] | Ignore certain preprocessors. See the [Skip preprocessor, rule, or decorator section](#skip-preprocessor-rule-or-decorator). | -| --skip-rule | [string] | Ignore certain rules. See the [Skip preprocessor, rule, or decorator section](#skip-preprocessor-rule-or-decorator). | -| --version | boolean | Show version number. | +{% admonition type="warning" name="Important" %} +The `--lint` switch and all related options (`--extends`, `--max-problems`, `--skip-rule`, `--format`) are deprecated and are marked for removal in future releases. +Use the [lint command](./lint.md) separately to lint your APIs before bundling. +{% /admonition %} + +| Option | Type | Description | +| ------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| apis | [string] | List of API description root filenames or names assigned in the `apis` section of your Redocly configuration file. Default values are all names defined in the `apis` section within your configuration file. | +| --config | string | Specify path to the [config file](#custom-configuration-file). | +| --dereferenced, -d | boolean | Generate fully dereferenced bundle. | +| --ext | string | Specify bundled file extension. Possible values are `json`, `yaml`, or `yml`. Default value is `yaml`. | +| --extends (**Deprecated**) | [string] | Can be used in combination with `--lint` to [extend a specific configuration](./lint.md#extend-configuration). Default values are taken from the Redocly configuration file. | +| --force, -f | boolean | Generate bundle output even when errors occur. | +| --format (**Deprecated**) | string | Format for the output. Possible values are `codeframe`, `stylish`, `json`, or `checkstyle`. Default value is `codeframe`. | +| --help | boolean | Show help. | +| --keep-url-references, -k | boolean | Keep absolute url references. | +| --lint (**Deprecated**) | boolean | Lint API description files. Default value is `false`. | +| --lint-config | string | Specify the severity level for the configuration file.
**Possible values:** `warn`, `error`, `off`. Default value is `warn`. | +| --max-problems (**Deprecated**) | integer | Truncate output to display the specified maximum number of problems. Default value is `100`. | +| --metafile | string | Path for the bundle metadata file. | +| --output, -o | string | Name or folder for the bundle file. If you don't specify the file extension, `.yaml` is used by default. If the specified folder doesn't exist, it's created automatically. **If the file specified as the bundler's output already exists, it's overwritten.** | +| --remove-unused-components | boolean | Remove unused components from the `bundle` output. | +| --skip-decorator | [string] | Ignore certain decorators. See the [Skip preprocessor, rule, or decorator section](#skip-preprocessor-rule-or-decorator). | +| --skip-preprocessor | [string] | Ignore certain preprocessors. See the [Skip preprocessor, rule, or decorator section](#skip-preprocessor-rule-or-decorator). | +| --skip-rule (**Deprecated**) | [string] | Ignore certain rules. See the [Skip preprocessor, rule, or decorator section](#skip-preprocessor-rule-or-decorator). | +| --version | boolean | Show version number. | ## Examples diff --git a/packages/cli/src/commands/bundle.ts b/packages/cli/src/commands/bundle.ts index 9451edc204..060f5f4886 100644 --- a/packages/cli/src/commands/bundle.ts +++ b/packages/cli/src/commands/bundle.ts @@ -26,10 +26,10 @@ import { writeFileSync } from 'fs'; export type BundleOptions = { apis?: string[]; - 'max-problems': number; + 'max-problems'?: number; extends?: string[]; config?: string; - format: OutputFormat; + format?: OutputFormat; output?: string; ext: OutputExtensions; dereferenced?: boolean; @@ -48,6 +48,8 @@ export async function handleBundle(argv: BundleOptions, config: Config, version: const totals: Totals = { errors: 0, warnings: 0, ignored: 0 }; const maxProblems = argv['max-problems']; + checkForDeprecatedOptions(argv); + for (const { path, alias } of apis) { try { const startedAt = performance.now(); @@ -81,7 +83,7 @@ export async function handleBundle(argv: BundleOptions, config: Config, version: format: argv.format || 'codeframe', totals: fileLintTotals, version, - maxProblems, + maxProblems: maxProblems, }); printLintTotals(fileLintTotals, 2); } @@ -122,8 +124,8 @@ export async function handleBundle(argv: BundleOptions, config: Config, version: totals.ignored += fileTotals.ignored; formatProblems(problems, { - format: argv.format, - maxProblems, + format: argv.format || 'codeframe', + maxProblems: maxProblems, totals: fileTotals, version, }); @@ -175,3 +177,23 @@ export async function handleBundle(argv: BundleOptions, config: Config, version: throw new Error('Bundle failed.'); } } + +function checkForDeprecatedOptions(argv: BundleOptions) { + const deprecatedOptions: Array = [ + 'lint', + 'format', + 'skip-rule', + 'extends', + 'max-problems', + ]; + + for (const option of deprecatedOptions) { + if (argv[option]) { + process.stderr.write( + yellow( + `[WARNING] "${option}" option is deprecated and will be removed in a future release. \n\n` + ) + ); + } + } +} diff --git a/packages/cli/src/index.ts b/packages/cli/src/index.ts index 37369c549a..a8daeae33a 100644 --- a/packages/cli/src/index.ts +++ b/packages/cli/src/index.ts @@ -294,13 +294,13 @@ yargs format: { description: 'Use a specific output format.', choices: ['stylish', 'codeframe', 'json', 'checkstyle'] as ReadonlyArray, - default: 'codeframe' as OutputFormat, + hidden: true, }, 'max-problems': { requiresArg: true, description: 'Reduce output to a maximum of N problems.', type: 'number', - default: 100, + hidden: true, }, ext: { description: 'Bundle file extension.', @@ -311,6 +311,7 @@ yargs description: 'Ignore certain rules.', array: true, type: 'string', + hidden: true, }, 'skip-preprocessor': { description: 'Ignore certain preprocessors.', @@ -340,6 +341,7 @@ yargs description: 'Lint API descriptions', type: 'boolean', default: false, + hidden: true, }, metafile: { description: 'Produce metadata about the bundle', @@ -350,6 +352,7 @@ yargs requiresArg: true, array: true, type: 'string', + hidden: true, }, 'remove-unused-components': { description: 'Remove unused components.',