feat: improve the spec ruleset (#2163)

Author: tatomyr

.changeset/long-ducks-deliver.md

@@ -0,0 +1,7 @@
+---
+"@redocly/openapi-core": minor
+"@redocly/cli": minor
+---
+
+Configured the `spec` ruleset for OpenAPI, AsyncAPI, Arazzo, and Overlay specifications.
+This ruleset is designed to strictly follow the specifications.

.prettierignore

@@ -1,7 +1,7 @@
 coverage/
 lib/
 output/
-packages/core/src/rules/__tests__/fixtures/invalid-yaml.yaml
+packages/core/src/rules/common/__tests__/fixtures/invalid-yaml.yaml
 packages/respect-core/src/modules/runtime-expressions/abnf-parser.cjs
 benchmark/api-definitions/
 LICENSE.md

CONTRIBUTING.md

@@ -160,7 +160,7 @@ It only checks links within the local docs (it can't check links to other docs s
 
 ## Built-in rules changes
 
-After adding a new rule, make sure it is added to the `minimal`, `recommended`, `recommended-strict` (the same as the previous but with warnings turned into error) and `all` rulesets with appropriate severity levels.
+After adding a new rule, make sure it is added to the `minimal`, `recommended`, `recommended-strict` (the same as the previous but with warnings turned into error), `spec`, and `all` rulesets with appropriate severity levels.
 The defaults are `off` for `minimal` and `recommended` and `error` for `all`.
 Also add the rule to the built-in rules list in [the config types tree](./packages/core/src/types/redocly-yaml.ts).
 

docs/@v2/commands/lint.md

@@ -24,19 +24,19 @@ redocly lint --version
 
 ## Options
 
-| Option                 | Type     | Description                                                                                                                                                                                         |
-| ---------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| apis                   | [string] | Array of API or Arazzo description filenames that need to be linted. See [the API section](#specify-api) for more options.                                                                          |
-| --config               | string   | Specify path to the [configuration file](#use-custom-configuration-file).                                                                                                                           |
-| --extends              | [string] | [Extend a specific configuration](#extend-configuration) (defaults or config file settings). Build-in rulesets are: `minimal`, `recommended`, `recommended-strict`. Default value is `recommended`. |
-| --format               | string   | Format for the output.<br />**Possible values:** `codeframe`, `stylish`, `json`, `checkstyle`, `codeclimate`, `github-actions`, `markdown`, `summary`. Default value is `codeframe`.                |
-| --generate-ignore-file | boolean  | [Generate ignore file](#generate-ignore-file).                                                                                                                                                      |
-| --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`.                                                                  |
-| --max-problems         | integer  | Truncate output to display the specified [maximum number of problems](#limit-the-displayed-problems-count). Default value is 100.                                                                   |
-| --skip-preprocessor    | [string] | Ignore certain preprocessors. See the [Skip preprocessor or rule section](#skip-preprocessor-or-rule) below.                                                                                        |
-| --skip-rule            | [string] | Ignore certain rules. See the [Skip preprocessor or rule section](#skip-preprocessor-or-rule) below.                                                                                                |
-| --version              | boolean  | Show version number.                                                                                                                                                                                |
+| Option                 | Type     | Description                                                                                                                                                                                                 |
+| ---------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| apis                   | [string] | Array of API or Arazzo description filenames that need to be linted. See [the API section](#specify-api) for more options.                                                                                  |
+| --config               | string   | Specify path to the [configuration file](#use-custom-configuration-file).                                                                                                                                   |
+| --extends              | [string] | [Extend a specific configuration](#extend-configuration) (defaults or config file settings). Build-in rulesets are: `spec`, `minimal`, `recommended`, `recommended-strict`. Default value is `recommended`. |
+| --format               | string   | Format for the output.<br />**Possible values:** `codeframe`, `stylish`, `json`, `checkstyle`, `codeclimate`, `github-actions`, `markdown`, `summary`. Default value is `codeframe`.                        |
+| --generate-ignore-file | boolean  | [Generate ignore file](#generate-ignore-file).                                                                                                                                                              |
+| --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`.                                                                          |
+| --max-problems         | integer  | Truncate output to display the specified [maximum number of problems](#limit-the-displayed-problems-count). Default value is 100.                                                                           |
+| --skip-preprocessor    | [string] | Ignore certain preprocessors. See the [Skip preprocessor or rule section](#skip-preprocessor-or-rule) below.                                                                                                |
+| --skip-rule            | [string] | Ignore certain rules. See the [Skip preprocessor or rule section](#skip-preprocessor-or-rule) below.                                                                                                        |
+| --version              | boolean  | Show version number.                                                                                                                                                                                        |
 
 ## Examples
 
@@ -113,7 +113,7 @@ redocly lint --config=./another/directory/config.yaml
 ### Extend configuration
 
 The `--extends` option allows you to extend the existing configuration.
-This option accepts one of the following values: `minimal`, `recommended`, or `recommended-strict`.
+This option accepts one of the following values: `minimal`, `recommended`, `recommended-strict`, or `spec`.
 Each of the values is a base set of rules that the `lint` command uses.
 You can further modify this set in cases when you want to have your own set of rules based on the existing one, including particular rules that cover your specific needs.
 For more details, see [rulesets](../rules.md).
@@ -304,8 +304,8 @@ Running the `lint` command with `--format=markdown` produces output like the fol
 
 | Severity | Location | Problem | Message |
 |---|---|---|---|
-| error | line 42:11 | [struct](https://redocly.com/docs/cli/rules/oas/struct) | Must contain at least one of the following fields: schema, content. |
-| error | line 44:11 | [struct](https://redocly.com/docs/cli/rules/oas/struct) | Property `type` is not expected here. |
+| error | line 42:11 | [struct](https://redocly.com/docs/cli/rules/common/struct) | Must contain at least one of the following fields: schema, content. |
+| error | line 44:11 | [struct](https://redocly.com/docs/cli/rules/common/struct) | Property `type` is not expected here. |
 
 Validation failed
 Errors: 2
@@ -369,7 +369,7 @@ Example of an ignore file:
 
 ```yaml .redocly.lint-ignore.yaml file
 # This file instructs Redocly's linter to ignore the rules contained for specific parts of your API.
-# See https://redoc.ly/docs/cli/ for more information.
+# See https://redocly.com/docs/cli/ for more information.
 museum-with-errors.yaml:
   struct:
     - '#/paths/~1museum-hours/get/operationIds'

docs/@v2/guides/configure-rules.md

@@ -10,6 +10,7 @@ In this guide, learn how to choose and adapt the rules built into Redocly for yo
 
 To get started, try one of the existing rulesets and see if it meets your needs.
 
+- The [`spec`](../rules/spec-ruleset.md) ruleset follows the OpenAPI specification.
 - The [`recommended`](../rules/recommended.md) ruleset has a good basic set of rules for a consistent, user-friendly API.
 - The [recommended-strict](../rules/recommended.md#recommended-strict-ruleset) ruleset is identical to the `recommended`, except it elevates all warnings to errors so that you don't miss the warnings, i.e. in a CI pipeline.
 - Or try the [`minimal`](../rules/minimal.md) ruleset which shows some warnings, but far fewer errors that would cause the lint to fail.

docs/@v2/guides/lint-arazzo.md

@@ -70,7 +70,7 @@ run `redocly lint --generate-ignore-file` to add all problems to the ignore file
 
 ## Configure the linting rules
 
-Choose from the ready-made rulesets (`minimal`, `recommended` or `recommended-strict`), or go one better and configure the rules that suit your use case.
+Choose from the ready-made rulesets (`spec`, `minimal`, `recommended` or `recommended-strict`), or go one better and configure the rules that suit your use case.
 There's a full [list of built-in rules for Arazzo](../rules/built-in-rules.md#arazzo-rules) to refer to.
 
 Add the rules to `redocly.yaml`, but for Arazzo specifications, the rules go in their own configuration section called `arazzoRules`.

docs/@v2/quickstart.md

@@ -63,17 +63,17 @@ You have 1 warning.
 
 The output shows any aspects where the OpenAPI doesn't meet the standard. If you get too much output, try adding the `--format summary` parameter to the command.
 
-Feeling brave and highly API compliant? Try the `recommended` standard instead and see how yours measures up.
+Feeling brave and highly API compliant? Try the `recommended` or `spec` ruleset instead and see how yours measures up.
 
 ## Craft a custom ruleset
 
 Redocly CLI has some [great built-in rules](./rules/built-in-rules.md), and you can use these to build up a ruleset that works for you.
 
-For example, let's build a lightweight ruleset using the [minimal ruleset](./rules/minimal.md) and adding some built-in rules to create a custom ruleset. You can see an example in the following snippet:
+For example, let's build a lightweight ruleset using the [spec ruleset](./rules/spec-ruleset.md) and adding some built-in rules to create a custom ruleset. You can see an example in the following snippet:
 
 ```yaml
 extends:
- - minimal
+ - spec
 
 rules:
   path-parameters-defined: error

docs/@v2/rules.md

@@ -16,7 +16,8 @@ Redocly uses rules to describe all the different aspects of API behavior that we
 
 Rulesets are groups of rules that are applied together, and APIs can be checked against as many rulesets as needed during linting. To get you started, there are some built-in rulesets:
 
-- Our [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.
+- Our [spec](./rules/spec-ruleset.md) ruleset follows the OpenAPI specification as closely as possible and is a good starting point to build your own standards on top of it.
+- 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.
 

docs/@v2/rules/arazzo/struct.md

@@ -29,10 +29,10 @@ The rules list is split into sections.
 
 ### Special rules
 
-- [no-unresolved-refs](./oas/no-unresolved-refs.md): Every `$ref` must exist
+- [no-unresolved-refs](./common/no-unresolved-refs.md): Every `$ref` must exist
 - [no-unused-components](./oas/no-unused-components.md): All components must be used
 - [security-defined](./oas/security-defined.md): Security rules must be defined, either globally or per-operation
-- [struct](./oas/struct.md): Conform to the declared OpenAPI specification version
+- [struct](./common/struct.md): Conform to the declared OpenAPI specification version
 - [spec-components-invalid-map-name](./oas/spec-components-invalid-map-name.md): Use only alphanumeric and basic punctuation as key names in the components section
 - [spec-strict-refs](./oas/spec-strict-refs.md) Restricts the usage of the `$ref` keyword.