feat(cli): add an experimental diff command

.changeset/purple-onions-shave.md

@@ -0,0 +1,6 @@
+---
+'@redocly/cli': minor
+'@redocly/openapi-core': minor
+---
+
+Added an experimental `diff` command that compares two API descriptions, reports what was added, removed, and modified, and rates every change by the semver bump it requires (`patch`, `minor`, or `major`). `--fail-on` sets the impact that fails the run and `--check-version` verifies that `info.version` was bumped accordingly.

docs/@v2/commands/diff.md

@@ -0,0 +1,162 @@
+# `diff`
+
+## Introduction
+
+The `diff` command compares two API descriptions and lists the changes between them.
+The command gives each change an impact: the semver part that a release with this change must bump.
+
+- `major`: the change can break a client, for example a removed operation.
+- `minor`: the change adds to the API, for example a new path.
+- `patch`: the change does not break or add anything, for example a new description.
+
+Use the command in CI to stop breaking changes, or to get the next version of your API.
+
+{% admonition type="warning" name="Experimental" %}
+This is an experimental feature.
+Its behavior, options, rule names, and output formats can change in future releases.
+{% /admonition %}
+
+## Usage
+
+```bash
+redocly diff <base> <revision>
+redocly diff <base> <revision> [--fail-on=<impact>] [--check-version]
+redocly diff <base> <revision> [--format=<value>] [--output=<path>]
+redocly diff <base> <revision> [--config=<path>] [--skip-rule=<rule>]...
+```
+
+## Options
+
+| Option          | Type     | Description                                                                                                                                                                                    |
+| --------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| base            | string   | **REQUIRED.** Path, URL, or [alias](../configuration/reference/apis.md) of the older API description.                                                                                          |
+| revision        | string   | **REQUIRED.** Path, URL, or alias of the newer API description.                                                                                                                                |
+| --check-version | boolean  | Fail if `info.version` of the revision is lower than the version that the changes require. See [Check the version](#check-the-version). Default value is `false`.                              |
+| --config        | string   | Specify path to the [configuration file](../configuration/index.md).                                                                                                                           |
+| --fail-on       | string   | Exit with code `1` if a change has this impact or a higher impact. <br /> **Possible values:** `major`, `minor`, `patch`, `none`. Default value is `major`.                                    |
+| --format        | string   | Format for the output. See [Output formats](#output-formats). <br /> **Possible values:** `stylish`, `json`, `markdown`, `html`, `github-actions`, `next-version`. Default value is `stylish`. |
+| --help          | boolean  | Show help.                                                                                                                                                                                     |
+| --lint-config   | string   | Specify the severity level for the configuration file. <br /> **Possible values:** `warn`, `error`, `off`. Default value is `warn`.                                                            |
+| --output, -o    | string   | Write the report to this file. All formats support this option, except `github-actions`.                                                                                                       |
+| --skip-rule     | [string] | Turn off these [diff rules](../rules/diff-rules.md) for this run.                                                                                                                              |
+| --version       | boolean  | Show version number.                                                                                                                                                                           |
+
+## How the command compares descriptions
+
+- The [diff rules](../rules/diff-rules.md) find the changes that can break a client and set their impact.
+  A change that no rule reports is `minor` if you add something, and `patch` in all other cases.
+- A new component is `patch`, because it has no effect until something uses it.
+- The command follows `$ref`s, also into other files.
+  It shows a change in a component at the first place that uses the component, with the line of the change in its file.
+- If you rename an item, such as a path, a property, or a parameter, and the new item is similar to the old item, the command shows one changed item.
+  It does not show a removed item and an added item.
+- A new order of list items, such as parameters or `oneOf` subschemas, is not a change.
+- The command applies the preprocessors from your configuration, but not the [decorators](../decorators.md).
+  To compare the descriptions that you publish, bundle them with your decorators first.
+- The diff rules support OpenAPI 3.x and AsyncAPI 3.
+  For other description types, the command lists the changes, but all changes are `minor` or `patch`.
+- The command cannot compare descriptions of different types, for example OpenAPI 2.0 and OpenAPI 3.1.
+
+## Output formats
+
+The command prints the report to stdout and all other messages to stderr.
+
+| Format           | Output                                                                                                      |
+| ---------------- | ----------------------------------------------------------------------------------------------------------- |
+| `stylish`        | The changes grouped by path, webhook, channel, operation, or server, with rule messages and file locations. |
+| `json`           | All data of each change. Use this format in scripts.                                                        |
+| `markdown`       | A table of the changes for a pull request comment.                                                          |
+| `html`           | A standalone page that you open in a browser.                                                               |
+| `github-actions` | An error annotation for each rule message of a `major` change.                                              |
+| `next-version`   | Only the next version, for example `2.0.0`. See [Get the next version](#get-the-next-version).              |
+
+## Examples
+
+### Stop breaking changes in CI
+
+By default, the command exits with code `1` if it finds a `major` change:
+
+```bash
+redocly diff main/openapi.yaml openapi.yaml
+```
+
+To also fail on new features, use `--fail-on=minor`.
+To never fail, use `--fail-on=none`.
+
+### Check the version
+
+With `--check-version`, the command also fails if `info.version` of the revision is lower than the version that the changes require:
+
+```bash
+redocly diff main/openapi.yaml openapi.yaml --check-version
+```
+
+For example, if the base version is `1.2.0` and a change is `major`, the revision version must be `2.0.0` or higher:
+
+```text
+❌ info.version went 1.2.0 → 1.3.0, but these changes require a major bump (2.0.0).
+```
+
+- Below version `1.0.0`, semver allows a `minor` release to break the API.
+  Thus, a `major` change from `0.4.2` requires `0.5.0` or higher.
+- The command compares only the `major.minor.patch` numbers.
+  It ignores pre-release and build labels.
+- A change to `info.version` does not require a bump.
+- If the changes require a bump and `info.version` is not a semver string, the check fails.
+
+### Get the next version
+
+The `next-version` format prints the base version, bumped as the changes require:
+
+```bash
+NEXT_VERSION=$(redocly diff main/openapi.yaml openapi.yaml --format=next-version --fail-on=none)
+```
+
+If no change requires a bump, the command prints the base version.
+Use `--fail-on=none`, so that a `major` change does not stop your script.
+
+### Comment on a pull request
+
+Write the report to a file, and attach the file to a pull request comment:
+
+```bash
+redocly diff main/openapi.yaml openapi.yaml --format=markdown -o diff.md
+```
+
+To show each breaking change on the changed line, use the `github-actions` format in a GitHub Actions workflow:
+
+```bash
+redocly diff main/openapi.yaml openapi.yaml --format=github-actions
+```
+
+### Compare two APIs by their aliases
+
+If the `apis` section of `redocly.yaml` has both descriptions, use their aliases:
+
+```yaml
+apis:
+  cafe@v1:
+    root: v1/openapi.yaml
+  cafe@v2:
+    root: v2/openapi.yaml
+```
+
+```bash
+redocly diff cafe@v1 cafe@v2
+```
+
+### Change the impact of a rule
+
+To change the impact of a rule, or to turn it off, add a [`diff` section](../configuration/reference/diff.md) to `redocly.yaml`:
+
+```yaml
+extends:
+  - diff-recommended
+diff:
+  enum-values-added: minor
+```
+
+## Resources
+
+- [Diff rules](../rules/diff-rules.md)
+- [`diff` configuration](../configuration/reference/diff.md)

docs/@v2/commands/index.md

@@ -24,6 +24,7 @@ Docs linting commands:
 CI and delivery commands:
 
 - [`bundle`](bundle.md) Bundle an API description.
+- [`diff`](diff.md) Compare two API descriptions and rate each change by the semver bump it requires [experimental feature].
 - [`join`](join.md) Join API descriptions [experimental feature].
 
 API testing and drift commands:

docs/@v2/configuration/index.md

@@ -8,7 +8,7 @@
 
 # Redocly configuration file
 
 You can configure all of your Redocly tools using a single `redocly.yaml` configuration file in the root of your project. Your `redocly.yaml` configurations can be used locally, in CI, or on our hosted platforms to specify the following behaviors:
 
 - The rules to apply to your APIs and how strictly to `lint`.
 - The styles and features to use when rendering your API documentation.
@@ -20,7 +20,7 @@
 
 ## Example Redocly configuration file
 
 An example is worth a thousand words, or so they say. Here's a simple configuration file showing some of the options available and how to use them.
 
 ```yaml
 extends:
@@ -43,7 +43,7 @@
 
 Read on to learn more about the various configuration sections and what you can do with each one.
 
 ## Using configuration with Redocly CLI
 
 Some of the Redocly CLI commands, such as the [lint command](../commands/lint.md), use the API names from the `apis` object as shortcuts for referencing API descriptions.
 You can tell the `lint` command to validate specific API descriptions by using their names from the `apis` object, like in the following example:
@@ -52,7 +52,7 @@
 redocly lint core@v2
 ```
 
 On the other hand, if you run the command without specifying any aliases, it applies to all API descriptions listed in the `apis` object of the configuration file.
 
 ```shell
 redocly lint
@@ -71,7 +71,7 @@
 Use `extends` to adopt an existing [ruleset](../rules.md#rulesets) such as the `recommended` or `minimal` standards.
 You can also define your own rulesets and refer to them here by file path or URL.
 
 While the order of the sections in the configuration file doesn't matter, usually `extends` is first, and any later rules, preprocessors or decorators defined in this file then override the base settings.
 
 Read the [detailed `extends` documentation](./extends.md) to see more information and examples.
 
@@ -80,7 +80,7 @@
 In the `rules` section, configure which rules apply, their severity levels, and any options that they support.
 Configurable rules, and rules from custom plugins are also configured here.
 
 Use this section to adjust the linting rules from the rulesets or other base configuration set in `extends`, and fine-tune it to meet the needs of your API. Here's an example `redocly.yaml`, changing some rule severity, and using some additional configuration for a rule.
 
 ```yaml
 rules:
@@ -112,6 +112,19 @@
 The `lint` command ignores the Recheck presets and the `recheck` block, and the `recheck` command ignores API rulesets.
 For more information, visit the [`recheck` block reference](./reference/recheck.md) and the [Markdown and prose linting](../recheck/index.md) section.
 
+### Configure `diff` rules
+
+In the `diff` section, set the impact that each [diff rule](../rules/diff-rules.md) gives to a change: `major`, `minor`, `patch`, or `off`.
+The [`diff` command](../commands/diff.md) uses these rules to compare two versions of an API.
+See the [`diff` reference](./reference/diff.md) for all options.
+
+```yaml
+extends:
+  - diff-recommended
+diff:
+  enum-values-added: minor
+```
+
 <a id="theme-object"></a>
 
 ### Configure OpenAPI features and documentation styles
@@ -122,7 +135,7 @@
 In case of conflict, API takes priority.
 
 The API registry supports [the mock server feature](https://redocly.com/docs/api-registry/guides/mock-server-quickstart/) and allows project owners to enable it for all branches per API version.
 When the mock server is enabled for an API, you can send test requests to it from any API client.
 
 The `mockServer` object allows additional configuration of the mock server behavior.
 This object is optional.
@@ -139,7 +152,7 @@
 
 The `openapi` object configures features and theming for API documentation generated from OpenAPI descriptions.
 
 If you need to apply different theming and functionality to individual APIs, add the `openapi` property to the appropriate API in the `apis` object, and use the same options as the global `openapi` object.
 
 Find the full list of supported options on the [Reference docs configuration page](https://redocly.com/docs/api-reference-docs/configuration/functionality/).
 
@@ -148,7 +161,7 @@
 ### Configure each of the `apis` independently
 
 For organizations with multiple APIs, versions or environments, having specific configuration for each is a powerful tool.
 All configuration options can be nested within a specific API entry.
 
 #### Example of `apis` configuration
 
@@ -176,7 +189,7 @@
 
 ### Use custom `plugins`
 
 Use this list to import any custom plugins (omit this section if you have no plugins). Custom plugins are used to add any custom decorators or rules that you want to use, that aren't provided by the Redocly [built-in rules](../rules/built-in-rules.md), [configurable rules](../rules/configurable-rules.md), or existing [decorators](../decorators.md).
 
 Add each plugin by path, relative to the configuration file, to have the plugin contents available to configure.
 Importing by URL isn't supported, to reduce the risk of malicious code execution.
@@ -229,12 +242,12 @@
 ```
 
 The first match takes priority when a URL matches multiple patterns.
 Therefore, only the header from the first match is used in the request.
 
 ### Split up the configuration file
 
 As your config file grows, you may want to split it into multiple parts.
 Splitting a config file is possible by using references in a config similar to how they are used in OpenAPI descriptions:
 
 ```yaml
 extends:

docs/@v2/configuration/reference/diff.md

@@ -0,0 +1,69 @@
+# `diff`
+
+## Introduction
+
+The `diff` section sets the impact of each [diff rule](../../rules/diff-rules.md).
+The [`diff` command](../../commands/diff.md) uses these impacts.
+
+Use the `diff` section only at the root of a configuration file.
+[API-specific sections](./apis.md) do not support it.
+
+{% admonition type="warning" name="Experimental" %}
+The `diff` section is an experimental feature.
+It can change in future releases.
+{% /admonition %}
+
+## Options
+
+{% table %}
+
+- Option
+- Type
+- Description
+
+---
+
+- {rule name}
+- string
+- **REQUIRED**. The impact of the changes that the rule reports.
+  Possible values: `major`, `minor`, `patch`, `off`.
+
+{% /table %}
+
+To set an impact for one specification version, use one of these sections.
+They have the same options.
+
+- `oas3_0Diff`
+- `oas3_1Diff`
+- `oas3_2Diff`
+- `async3Diff`
+
+## Examples
+
+This example adds the `diff-recommended` ruleset, sets a lower impact for one rule, and turns off another rule:
+
+```yaml
+extends:
+  - diff-recommended
+diff:
+  enum-values-added: minor
+  schema-constraint-changed: off
+```
+
+This example changes the impact of a rule for OpenAPI 3.1 descriptions only:
+
+```yaml
+extends:
+  - diff-recommended
+oas3_1Diff:
+  schema-type-changed: minor
+```
+
+## Related options
+
+- [extends](./extends.md) adds the `diff-recommended` ruleset.
+
+## Resources
+
+- [Diff rules](../../rules/diff-rules.md)
+- [`diff` command](../../commands/diff.md)

docs/@v2/rules.md

@@ -5,10 +5,10 @@
 
 # Rules to describe API standards
 
 Redocly uses rules to describe all the different aspects of API behavior that we check for during linting. Rules come in different levels of complexity, and can also be grouped for reuse. Here's an overview of what is available:
 
 - **Rulesets** are groups of rules that can be applied to any API. This is a good way to build up a ruleset that you can use locally or with your CI. Multiple rulesets can be used at once, so feel free to make smaller ones and compose the rulesets that fit each API.
 - **Built-in rules:** for the most common use cases, the rules are already made for you, all you need to do is choose if they should cause an `error`, simply `warn` of a problem, or be turned `off`. [See the built-in rules documentation](./rules/built-in-rules.md) for more information and examples.
 - **Configurable rules** allow powerful describing of API standards without needing to write code. Create a configurable rule, choose which parts of the API description it applies to, and what the criteria for success are. The linting tool does the rest. With plenty of examples, the [configurable rules](./rules/configurable-rules.md) helps you to describe your API standards easily and well.
 - **Custom code rules** if none of the above exactly fits your needs, then a [custom code plugin](./custom-plugins/index.md) is an extensible way to bring some custom JavaScript to build on Redocly's existing features.
 
@@ -23,6 +23,7 @@
 - A [recommended](./rules/recommended.md) ruleset is our unabashedly opinionated recommendation of what we think a good API looks like. It's a great place to start, before adapting to your own context.
 - A [recommended-strict](./rules/recommended.md#recommended-strict-ruleset) ruleset is identical to the `recommended`, except it elevates all warnings to errors. It's the ideal option for those who don't want to miss anything.
 - A [minimal](./rules/minimal.md) ruleset is a good starting point for an existing API that doesn't currently conform to any standard. It has fewer rules that cause an error, with others either downgraded to a warning or turned off completely.
+- The [diff-recommended](./rules/diff-rules.md#diff-recommended-ruleset) ruleset holds the rules that the `diff` command uses to find breaking changes between two versions of an API.
 
 Enable a ruleset by adding a block like this to the Redocly configuration file: