feat(cli): add the recheck engine and the redocly recheck command

.changeset/config.json

@@ -7,7 +7,8 @@
       "@redocly/cli",
       "@redocly/openapi-core",
       "@redocly/respect-core",
-      "@redocly/reunite-integration"
+      "@redocly/reunite-integration",
+      "@redocly/recheck"
     ]
   ],
   "linked": [],

.changeset/recheck-command.md

@@ -0,0 +1,11 @@
+---
+'@redocly/cli': minor
+'@redocly/openapi-core': minor
+'@redocly/recheck': minor
+---
+
+Added the `redocly recheck` command.
+It lints Markdown prose and structure from the `recheck` block in `redocly.yaml`, with presets named in the root `extends` (for example `recheck/markdown`).
+Presets merge with the `recheck` blocks in `extends` order, like other presets.
+The engine's actions return data.
+The CLI prints it.

.changeset/recheck-core-presets.md

@@ -0,0 +1,9 @@
+---
+'@redocly/openapi-core': minor
+---
+
+Added the `plugins` option to `loadConfig` and `createConfig`: ready plugin objects that are added next to the built-in plugin.
+Resolved configs carry the merged `recheck` block in `Config.recheck`.
+A `recheck/*` entry in `extends` resolves like any other preset when a plugin with the id `recheck` is passed, and is skipped otherwise.
+`lint` reads no rules from the block.
+A custom plugin cannot use the id `recheck`.

.changeset/recheck-engine-relocation.md

@@ -0,0 +1,10 @@
+---
+'@redocly/recheck': minor
+---
+
+Added the `@redocly/recheck` engine package to this repository.
+It powers the upcoming `redocly recheck` command.
+`@redocly/recheck/presets` exports the presets as a plugin for `@redocly/openapi-core`.
+
+**Note:** the standalone `recheck` binary and `recheck.yaml` are removed.
+Configuration moves to the `recheck` block of `redocly.yaml`, read by the `redocly recheck` command in a later release.

.oxfmtrc.json

@@ -9,6 +9,8 @@
     "output/",
     "packages/respect-core/src/modules/runtime-expressions/abnf-parser.js",
     "packages/core/src/rules/common/__tests__/fixtures/invalid-yaml.yaml",
+    "packages/recheck/src/config/__tests__/fixtures/",
+    "tests/e2e/recheck/*/docs/",
     "tests/performance/api-definitions/",
     "tests/e2e/generate-client/examples/*/src/api/",
     "tests/e2e/generate-client/examples/*/generators/",

.oxlintrc.json

@@ -91,7 +91,8 @@
         "packages/cli/src/commands/score/**",
         "packages/cli/src/commands/generate-spec/**",
         "packages/cli/src/commands/drift/**",
-        "packages/client-generator/**"
+        "packages/client-generator/**",
+        "packages/recheck/**"
       ],
       "rules": {
         "sonarjs/cognitive-complexity": ["error", 82]

CONTRIBUTING.md

@@ -139,6 +139,25 @@ To make changes to documentation:
 1. Add the link to the rule page to the [built-in rules list](docs/@v2/rules/built-in-rules.md) and the [sidebar](docs/@v2/v2.sidebars.yaml).
 1. Update the rulesets pages and [ruleset templates](docs/@v2/rules/ruleset-templates.md).
 
+### Recheck engine
+
+Recheck is the markdown and prose linting engine in `packages/recheck`.
+To add or change a lint rule, see [`packages/recheck/src/rules/CONTRIBUTING.md`](packages/recheck/src/rules/CONTRIBUTING.md).
+
+The example configs in `packages/recheck/examples/*.yaml` are generated from the presets.
+When you change a preset, the generator, or an appendix in `examples/appendices/`, regenerate them and commit the result:
+
+```bash
+npm run compile
+node packages/recheck/scripts/generate-examples.mjs
+```
+
+The generator reads the built `lib/`, so compile first.
+If you skip this step, `examples-drift.test.ts` fails.
+
+`packages/recheck/src/data/markdoc-realm-schema.ts` is generated from the Realm theme source in the Redocly monorepo.
+Regenerate it there with `scripts/generate-markdoc-schema.mjs` pointed at this checkout, and copy the result over.
+
 ### Update Redoc
 
 When updating Redoc, recompute the subresource integrity [SRI](https://developer.mozilla.org/en-US/docs/Web/Security/Subresource_Integrity) (`redocStandaloneSri` in [package.ts](./packages/cli/src/utils/package.ts)):
@@ -415,7 +434,7 @@ To add an entry:
 
 - **`docs`**: contains the documentation source files. When changes to the documentation are merged, they automatically get published on the [Redocly docs website](https://redocly.com/docs/cli/).
 
-- **`packages`**: contains the source code. It consists of five packages - CLI, core, respect-core, reunite-integration, and client-generator. The codebase is written in Typescript.
+- **`packages`**: contains the source code. It consists of six packages - CLI, core, respect-core, reunite-integration, client-generator, and recheck. The codebase is written in Typescript.
   - **`packages/cli`**: contains Redocly CLI commands and utils. More details [in the README](./README.md) file.
     - **`packages/cli/src`**: contains CLI package source code.
       - **`packages/cli/src/commands`**: contains CLI commands functions.
@@ -436,6 +455,8 @@ To add an entry:
 
   - **`packages/client-generator`**: contains the client and SDK generators.
 
+  - **`packages/recheck`**: contains the Recheck markdown and prose linting engine.
+
 - **`resources`**: contains some example API descriptions and configuration files that might be useful for testing.
 
 - **`cookbook`**: contains the community cookbook — shared rulesets, configuration, custom plugins, and other Redocly CLI additions. It is not part of the build or test suite.

docs/@v2/commands/index.md

@@ -17,6 +17,10 @@ Docs rendering commands:
 - [`translate`](translate.md) Generate translation keys for a Redocly Realm, Reef, or Revel project.
 - [`eject`](eject.md) Eject and modify components from the core theme in a Redocly Realm, Reef, or Revel project.
 
+Docs linting commands:
+
+- [`recheck`](recheck.md) Lint Markdown prose and structure from the `recheck` block.
+
 CI and delivery commands:
 
 - [`bundle`](bundle.md) Bundle an API description.

docs/@v2/commands/recheck.md

@@ -0,0 +1,126 @@
+# `recheck`
+
+## Introduction
+
+The `recheck` command lints Markdown files for prose and structure problems.
+It checks headings, sentences, links, images, and Markdoc tags against a set of rules.
+
+Rules come from presets, such as `recheck/markdown`, that you add to the root `extends` in `redocly.yaml`.
+The [`recheck` block](../configuration/reference/recheck.md) adjusts those rules.
+With no `redocly.yaml`, the command uses `recheck/markdown`.
+With a `redocly.yaml` that has neither, the command checks nothing and says so.
+The command reads the root `recheck` config; settings under `apis.<name>` are not used.
+
+## Usage
+
+```bash
+redocly recheck
+redocly recheck <paths>...
+redocly recheck [--fix]
+redocly recheck [--readability]
+redocly recheck [--generate-baseline]
+redocly recheck [--generate-markdoc-schema] [--from=<path>...] [--output=<path>] [--check]
+redocly recheck --help
+```
+
+{% admonition type="info" name="One action per run" %}
+`--readability`, `--generate-baseline`, and `--generate-markdoc-schema` each replace the default lint action.
+Use at most one of them in a run.
+`--fix` works with the default lint action only.
+{% /admonition %}
+
+## Options
+
+| Option                    | Type     | Description                                                                                                                       |
+| ------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| paths                     | [string] | Files or directories to lint. Default value is the current directory.                                                             |
+| --check                   | boolean  | Fail when the generated schema differs from the file in `--output`. Use with `--generate-markdoc-schema`.                         |
+| --config                  | string   | Path to the [configuration file](../configuration/index.md).                                                                      |
+| --fix                     | boolean  | Apply fixes to the Markdown files. Alias: `-f`.                                                                                   |
+| --format                  | string   | Format for the report.<br />**Possible values:** `table`, `json`, `sarif`, `github-actions`. Default value is `table`.            |
+| --from                    | [string] | Module paths to read Markdoc tags from. Use with `--generate-markdoc-schema`.                                                     |
+| --generate-baseline       | boolean  | Write a baseline file from the current errors.                                                                                    |
+| --generate-markdoc-schema | boolean  | Generate a Markdoc tag schema from theme modules. Needs `--from` and `--output`.                                                  |
+| --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            | number   | Maximum number of problems in the report; applies to every format.                                                                |
+| --output                  | string   | Output file for the generated schema.                                                                                             |
+| --readability             | boolean  | Report readability scores instead of lint findings.                                                                               |
+| --rule                    | [string] | Run only these rules. Alias: `-r`.                                                                                                |
+| --skip-rule               | [string] | Skip these rules.                                                                                                                 |
+| --stats                   | boolean  | Print statistics per rule. Alias: `-s`.                                                                                           |
+| --summary                 | string   | Print a summary of the run.<br />**Possible values:** `json`, `text`.                                                             |
+| --summary-path            | string   | Write the summary to this file.                                                                                                   |
+| --tags                    | [string] | Run only rules with these tags.                                                                                                   |
+| --version                 | boolean  | Show version number.                                                                                                              |
+
+## Examples
+
+### Lint a folder
+
+Add a preset to the root `extends`:
+
+```yaml
+extends:
+  - recheck/markdown
+```
+
+Then run the command on a folder:
+
+```bash
+redocly recheck docs
+```
+
+The command lints every Markdown file under `docs` with the rules from `recheck/markdown`.
+The report goes to stdout and progress messages go to stderr.
+
+### Turn off a rule
+
+Set the rule to `off` in the `recheck` block:
+
+```yaml
+extends:
+  - recheck/markdown
+recheck:
+  rules:
+    recheck/line-length: off
+```
+
+The run applies every rule from `recheck/markdown` except `recheck/line-length`.
+
+### Annotate a pull request
+
+```bash
+redocly recheck docs --format=github-actions
+```
+
+In a GitHub Actions workflow, this format adds each finding as an annotation on the changed line.
+An error becomes `::error`, a warning `::warning`, and an info finding `::notice`.
+Each finding is one line of output:
+
+```text
+::error title=recheck/single-h1,file=docs/index.md,line=2,endLine=2,col=1,endColumn=1::Multiple top-level headings in the same document
+```
+
+### Use a baseline
+
+A baseline records the current errors.
+Later runs report only errors that the baseline does not list.
+
+```bash
+redocly recheck docs --generate-baseline
+```
+
+The command writes `.redocly.recheck-baseline.yaml` next to `redocly.yaml`.
+Commit the file.
+Later runs pick it up automatically.
+
+After you fix errors, generate the baseline again and commit the smaller file.
+
+### Check readability
+
+```bash
+redocly recheck docs --readability
+```
+
+The command prints readability scores for each Markdown file instead of lint findings.

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

@@ -9,6 +9,16 @@ Multiple values are supported, and can include:
 - configuration defined in a [custom plugin](../../custom-plugins/index.md)
 - a path or URL to another `redocly.yaml` file
 
+Entries that start with `recheck/`, such as `recheck/markdown`, are Recheck presets for [`redocly recheck`](../../commands/recheck.md).
+They merge like any other entry, in the order listed: a later entry overrides an earlier one.
+Other commands skip them.
+A custom plugin cannot use the id `recheck`.
+
+The [`recheck` block](recheck.md) of the file that lists the presets merges on top of them.
+The `recheck` command reads the presets in the root `extends` and in the files that the root `extends` lists.
+It does not read them from an API's `extends`.
+The `lint` command reads no rules from them.
+
 Extends is useful if you use a common ruleset across multiple projects.
 Define a ruleset in one location, and each project can `extend` it, with or without modification.