chore: add rules docs

Author: DmitryAnansky

.changeset/new-falcons-unite.md

@@ -0,0 +1,5 @@
+---
+"@redocly/openapi-core": patch
+---
+
+Removed the `no-actions-type-end` Spot rule.

docs/guides/lint-arazzo.md

@@ -71,22 +71,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.
-The rules available for linting Arazzo are:
-
-- `parameters-not-in-body`: the `in` section inside `parameters` must not contain a `body`.
-- `sourceDescription-type`: the `type` property of the `sourceDescription` object must be either `openapi` or `arazzo`.
-- `version-enum`: the `version` property must be one of the supported values.
-- `workflowId-unique`: the `workflowId` property must be unique across all workflows.
-- `stepId-unique`: the `stepId` must be unique amongst all steps described in the workflow.
-- `sourceDescription-name-unique`: the `name` property of the `sourceDescription` object must be unique across all source descriptions.
-- `workflow-dependsOn`: the items in the `workflow` `dependsOn` property must exist and be unique.
-- `parameters-unique`: the `parameters` list must not include duplicate parameters.
-- `step-onSuccess-unique`: the `onSuccess` actions of the `step` object must be unique.
-- `step-onFailure-unique`: the `onFailure` actions of the `step` object must be unique.
-- `requestBody-replacements-unique`: the `replacements` of the `requestBody` object must be unique.
-- `no-criteria-xpath`: the `xpath` type criteria is not supported by Spot.
-- `no-actions-type-end`: the `end` type action is not supported by Spot.
-- `criteria-unique`: the criteria list must not contain duplicated assertions.
+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`.
 The following example shows configuration for the minimal ruleset with some additional rules configuration:

docs/guides/lint-asyncapi.md

@@ -53,8 +53,8 @@ some of the built-in rules. The currently-supported rules are:
 
 - `info-contact`: the `Info` section must contain a valid `Contact` field.
 - `operation-operationId`: every operation must have a valid `operationId`.
-- `channels-kebab-case`: channel names should be `kebab-case` (lowercase with hyphens).
-- `no-channel-trailing-slash`: channel names must not have trailing slashes in their names.
+- `channels-kebab-case`: channel address should be `kebab-case` (lowercase with hyphens).
+- `no-channel-trailing-slash`: channel names must not have trailing slashes in their address.
 - `tag-description`: all tags require a description.
 - `tags-alphabetical`: tags should be listed in the AsyncAPI file in alphabetical order.
 

docs/rules/arazzo/criteria-unique.md

@@ -1,7 +1,3 @@
----
-slug: /docs/cli/rules/arazzo/criteria-unique
----
-
 # criteria-unique
 
 The criteria list must not contain duplicated assertions.
@@ -10,9 +6,9 @@ The criteria list must not contain duplicated assertions.
 | ------ | ------------- |
 | 1.0.0  | ✅            |
 
-## API design principles
+## Design principles
 
-The criteria list must not contain duplicated assertions.
+To avoid redundancy and confusion, the assertions in the criteria list must not be duplicated.
 
 ## Configuration
 
@@ -23,7 +19,7 @@ The criteria list must not contain duplicated assertions.
 An example configuration:
 
 ```yaml
-arazzoRules:
+rules:
   criteria-unique: error
 ```
 
@@ -32,7 +28,7 @@ arazzoRules:
 Given the following configuration:
 
 ```yaml
-arazzoRules:
+rules:
   criteria-unique: error
 ```
 

docs/rules/arazzo/parameters-unique.md

@@ -0,0 +1,58 @@
+# parameters-unique
+
+Requires unique values in the `parameters` lists.
+
+| Arazzo | Compatibility |
+| ------ | ------------- |
+| 1.0.0  | ✅            |
+
+## Design principles
+
+A list of `parameters` that are applicable to a step or all the steps described in a workflow must not contain duplicates.
+If duplicates are present, unexpected parameter overrides could cause problems.
+
+This ruled checks parameter lists in the following locations:
+
+- `workflows.[workflow].parameters`
+- `workflows.[workflow[.steps.[step].parameters`
+- `x-parameters`
+
+## Configuration
+
+| Option   | Type   | Description                                             |
+| -------- | ------ | ------------------------------------------------------- |
+| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. |
+
+An example configuration:
+
+```yaml
+rules:
+  parameters-unique: error
+```
+
+## Examples
+
+Given the following configuration:
+
+```yaml
+rules:
+  parameters-unique: error
+```
+
+Example of a **correct** `parameters` list:
+
+```yaml Correct example
+workflows:
+  - workflowId: get-museum-hours
+    parameters:
+      - in: header
+        name: Authorization
+        value: Basic Og==
+      - in: header
+        name: X-Forwarded-For
+        value: 1.2.3.4
+```
+
+## Resources
+
+- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/arazzo/parameters-unique.ts)

docs/rules/arazzo/requestBody-replacements-unique.md

@@ -0,0 +1,56 @@
+# requestBody-replacements-unique
+
+Requires the `replacements` in the `step.requestBody` object to be unique.
+
+| Arazzo | Compatibility |
+| ------ | ------------- |
+| 1.0.0  | ✅            |
+
+## Design principles
+
+The list of locations and values to set within a payload must not have duplicates that might result in content override.
+
+## Configuration
+
+| Option   | Type   | Description                                             |
+| -------- | ------ | ------------------------------------------------------- |
+| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. |
+
+An example configuration:
+
+```yaml
+rules:
+  requestBody-replacements-unique: error
+```
+
+## Examples
+
+Given the following configuration:
+
+```yaml
+rules:
+  requestBody-replacements-unique: error
+```
+
+Example of a **correct** `replacements` list:
+
+```yaml Correct example
+workflows:
+  - workflowId: events-crud
+    steps:
+      - stepId: create-event
+        operationPath: $sourceDescriptions.museum-api#/paths/~1special-events/post
+        requestBody:
+          payload:
+            name: 'Mermaid Treasure Identification and Analysis'
+            description: 'Identify and analyze mermaid treasures'
+          replacements:
+            - target: name
+              value: 'new name'
+            - target: description
+              value: 'another description'
+```
+
+## Resources
+
+- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/arazzo/requestBody-replacements-unique.ts)

docs/rules/arazzo/sourceDescriptions-name-unique.md

@@ -0,0 +1,54 @@
+# sourceDescriptions-name-unique
+
+The `name` property of the Source Description object must be unique across all source descriptions.
+
+| Arazzo | Compatibility |
+| ------ | ------------- |
+| 1.0.0  | ✅            |
+
+## Design principles
+
+To avoid confusion or unexpected outputs, each Source Description object must have a unique `name` property.
+Especially in a longer list of sources, this could be difficult to identify and could have unwanted side effects.
+
+## Configuration
+
+| Option   | Type   | Description                                             |
+| -------- | ------ | ------------------------------------------------------- |
+| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. |
+
+An example configuration:
+
+```yaml
+rules:
+  sourceDescriptions-name-unique: error
+```
+
+## Examples
+
+Given the following configuration:
+
+```yaml
+rules:
+  sourceDescriptions-name-unique: error
+```
+
+Example of a **correct** `sourceDescriptions` list:
+
+```yaml Correct example
+sourceDescriptions:
+  - name: museum-api
+    type: openapi
+    url: ../openapi.yaml
+  - name: pets-api
+    type: openapi
+    url: ../petstore.yaml
+```
+
+## Related rules
+
+- [sourceDescription-type](./sourceDescriptions-type.md)
+
+## Resources
+
+- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/arazzo/sourceDescriptions-name-unique.ts)

docs/rules/arazzo/sourceDescriptions-not-empty.md

@@ -0,0 +1,69 @@
+# sourceDescriptions-not-empty
+
+The Source Description must have at least one entry.
+
+| Arazzo | Compatibility |
+| ------ | ------------- |
+| 1.0.0  | ✅            |
+
+## Design principles
+
+Source descriptions are an important part of an Arazzo description, and at least one entry must exist.
+If the list is empty, this could indicate an omission or another problem; this rule alerts you if that happens.
+
+## Configuration
+
+| Option   | Type   | Description                                             |
+| -------- | ------ | ------------------------------------------------------- |
+| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. |
+
+An example configuration:
+
+```yaml
+rules:
+  sourceDescriptions-not-empty: error
+```
+
+## Examples
+
+Given the following configuration:
+
+```yaml
+rules:
+  sourceDescriptions-not-empty: error
+```
+
+Example of a **correct** usage:
+
+```yaml Correct example
+arazzo: '1.0.0'
+info:
+  title: Cool API
+  version: 1.0.0
+  description: A cool API
+sourceDescriptions:
+  - name: museum-api
+    type: openapi
+    url: openapi.yaml
+  - name: another-api
+    type: openapi
+    url: openapi.yaml
+workflows:
+  - workflowId: get-museum-hours
+    description: This workflow demonstrates how to get the museum opening hours and buy tickets.
+    parameters:
+      - in: header
+        name: Authorization
+        value: Basic Og==
+    steps:
+      - stepId: get-museum-hours
+        description: >-
+          Get museum hours by resolving request details with getMuseumHours operationId from openapi.yaml description.
+        operationId: $sourceDescriptions.museum-api.getMuseumHours
+        successCriteria:
+          - condition: $statusCode == 200
+```
+
+## Resources
+
+- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/arazzo/sourceDescriptions-not-empty.ts)

docs/rules/arazzo/sourceDescriptions-type.md

@@ -0,0 +1,54 @@
+# sourceDescriptions-type
+
+The `type` property of the Source Description object must be either `openapi` or `arazzo`.
+
+| Arazzo | Compatibility |
+| ------ | ------------- |
+| 1.0.0  | ✅            |
+
+## Design principles
+
+Arazzo currently supports either an OpenAPI file or another Arazzo file as the source description.
+This rule makes sure that the type is clearly identified and is one of the supported types.
+
+## Configuration
+
+| Option   | Type   | Description                                             |
+| -------- | ------ | ------------------------------------------------------- |
+| severity | string | Possible values: `off`, `warn`, `error`. Default `off`. |
+
+An example configuration:
+
+```yaml
+rules:
+  sourceDescriptions-type: error
+```
+
+## Examples
+
+Given the following configuration:
+
+```yaml
+rules:
+  sourceDescriptions-type: error
+```
+
+Example of a **correct** `sourceDescriptions` list:
+
+```yaml Correct example
+sourceDescriptions:
+  - name: museum-api
+    type: openapi
+    url: ../openapi.yaml
+  - name: tickets-from-museum-api
+    type: arazzo
+    url: museum-tickets.arazzo.yaml
+```
+
+## Related rules
+
+- [sourceDescription-name-unique](./sourceDescriptions-name-unique.md)
+
+## Resources
+
+- [Rule source](https://github.com/Redocly/redocly-cli/blob/main/packages/core/src/rules/arazzo/sourceDescription-type.ts)