@redocly/cli 2.65.1 → 2.66.0

package/lib/skills/recheck-config/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: recheck-config
+description: Use when you create or tune the recheck block and recheck/* presets in redocly.yaml for a project — choose presets, set severities from measured counts, add exceptions, adopt a baseline, and validate the result.
+---
+
+# Configure recheck in redocly.yaml
+
+Configure `redocly recheck` for a project the way its maintainers would: measure first, decide per rule, and record intent.
+The documentation is at [redocly.com/docs/cli/recheck](https://redocly.com/docs/cli/recheck); favor it over memory for rule names and options.
+
+## How the configuration is shaped
+
+Presets go in the root `extends`.
+Adjustments go in the `recheck` block, with rules nested under `rules`.
+The `lint` command ignores both, so they live next to the API ruleset:
+
+```yaml
+extends:
+  - recommended
+  - recheck/markdown
+  - recheck/prose
+recheck:
+  excludes:
+    - CHANGELOG.md
+  rules:
+    recheck/line-length: off
+    recheck/no-duplicate-heading:
+      severity: warn
+      assertions:
+        no-duplicate-heading:
+          siblingsOnly: true
+```
+
+Rules of the shape:
+
+- A rule key is `<namespace>/<name>`: `recheck/line-length`, `google/no-via`, or your own, such as `acme/product-names`.
+- A severity string (`off`, `info`, `warn`, `error`) adjusts a rule that a preset defines.
+  For a key no preset defines, it is a configuration error, because the rule has no assertions.
+- A rule object merges over the preset's rule, but its `assertions` merge by assertion id: one option you set on a `swap` or `pattern` assertion replaces the preset's whole word list.
+  To reject one term from a preset's list, turn the rule off, restate the full list, or use an inline directive.
+- A new prose rule needs `severity`, `message`, and `assertions`.
+  A new Markdown rule, such as `recheck/list-length`, needs only `severity` and `assertions`.
+- The block does not accept `extends` or `baseline`; both are configuration errors.
+- The command reads the root block only.
+  A `recheck` block under `apis.<name>` does nothing and prints a warning.
+
+## Start a new config
+
+1. Begin with the structural preset, and run recheck to validate it:
+
+   ```yaml
+   extends:
+     - recheck/markdown
+   ```
+
+   ```bash
+   npx @redocly/cli recheck docs
+   npx @redocly/cli check-config
+   ```
+
+   The `recheck` command reports configuration errors before it lints anything, and `check-config` validates the block's shape.
+
+2. Add prose presets deliberately, not wholesale.
+   `recheck/prose` is a small starter at `warn`.
+   `recheck/google` and `recheck/microsoft` are large style guides, detection-only, that need tuning before they help.
+   `recheck/plain-language`, `recheck/inclusive-language`, and `recheck/technical-english` compose onto either.
+
+3. If the project writes Markdoc tags, add `recheck/markdoc` to `extends` and `markdoc: true` to the block.
+   Without the flag, the Markdoc rules never report.
+
+## Tune severities from measurements, not taste
+
+1. Run the whole document set and count findings per rule:
+
+   ```bash
+   npx @redocly/cli recheck docs --summary=json --summary-path=recheck-summary.json
+   ```
+
+   The summary's `breakdown` has the count per rule and severity.
+   For examples of each rule's findings, run `--rule=<name>` and read a few.
+
+2. Decide per rule from the counts:
+   - `error` — enforce now; the document set is clean or you fix it in the same change.
+   - `warn` — a worklist; visible, not blocking.
+   - `off` — decided against; keep a YAML comment that says why, or the decision is lost.
+
+3. Prefer fixing content over configuring around it.
+   Run `--fix` first; most structural findings repair themselves.
+   Review the fix list before you commit: fixes that re-indent lines can move content out of an indented Markdoc tag body.
+
+## Exceptions, in order of preference
+
+1. Fix the content.
+2. The top-level `excludes` list, or a rule's `excludes` or `appliesTo`, for generated or frozen content such as archives and vendored docs — with a comment naming the reason.
+3. `exceptions.lines` for a recurring true positive that must stay as written.
+4. An inline `<!-- recheck-disable-next-line rule-name -->` for a single line.
+
+## Adopt strictness on a large document set with a baseline
+
+When the document set has too many errors to fix at once, record them and gate only new ones:
+
+```bash
+npx @redocly/cli recheck docs --generate-baseline
+```
+
+Commit `.redocly.recheck-baseline.yaml`.
+The command writes it next to `redocly.yaml`, and later runs pick it up by presence; there is no configuration key.
+It records errors only, as one count per file per rule.
+
+Counts only step down: when findings get fixed, the run reports stale entries, so regenerate the baseline and commit the diff.
+
+## Finish
+
+- `npx @redocly/cli recheck docs` and `npx @redocly/cli check-config` report no configuration errors.
+- Every `off` and every exception carries a comment with its reason.
+- The project's contributing docs say how contributors run recheck locally, and CI runs it with `--format=github-actions`.

package/lib/skills/recheck-lint/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: recheck-lint
+description: Use when you write or edit Markdown in a project whose redocly.yaml has a recheck block or a recheck/* preset in extends — run redocly recheck on the touched files before you commit them or hand them over, and fix what it finds.
+---
+
+# Lint Markdown with recheck before you commit it
+
+This project lints Markdown structure and prose with `redocly recheck`.
+Your Markdown must pass it, the same as code must pass its tests.
+
+## When this applies
+
+Look for a `redocly.yaml` in the project root or above the files you touched.
+This skill applies when that file has a `recheck` block, or a `recheck/*` preset in its root `extends`, for example:
+
+```yaml
+extends:
+  - recommended
+  - recheck/markdown
+recheck:
+  rules:
+    recheck/line-length: off
+```
+
+If neither exists, skip this skill.
+The command checks nothing in that case and says so.
+
+## What to do
+
+1. After you write or edit Markdown files, run recheck on them:
+
+   ```bash
+   npx @redocly/cli recheck <file-or-directory>
+   ```
+
+   Pass the files you touched, not the whole repository, so the report is yours to act on.
+
+2. If it reports errors, run the auto-fix first — most structural findings repair themselves:
+
+   ```bash
+   npx @redocly/cli recheck <file-or-directory> --fix
+   ```
+
+   The command lists every edit it made.
+   Read the list: a fix inside a Markdoc tag body or a code sample deserves a look.
+
+3. Fix the remaining errors by hand.
+   Read each message; the rule name links the finding to its intent.
+   To see one rule at a time, add `--rule=<name>` with the name the report prints.
+
+4. Re-run until it reports no errors, and only then commit or output the content.
+   The command exits with code 1 while errors remain.
+
+## Rules of conduct
+
+- Fix content instead of suppressing findings.
+  Suppress only a true positive that must stay as written, with an inline directive on that one line:
+
+  ```markdown
+  <!-- recheck-disable-next-line recheck/rule-name -->
+  ```
+
+  Name the rule by its full key or by the short name the report prints.
+  Never disable a rule project-wide to make your change pass, and never edit the `recheck` block to get past a finding.
+
+- Warnings and info findings do not block you.
+  Leave them unless the task asks for cleanup.
+- If a `.redocly.recheck-baseline.yaml` file sits next to `redocly.yaml`, the baseline already covers old findings; only new findings are yours to fix.
+  Do not run `--generate-baseline` to absorb findings your change introduced.
+  If your change removed old findings, the run reports stale baseline entries; regenerate the baseline then, and commit the smaller file with your change.
+- A finding you believe is a false positive is worth reporting to the maintainer, not silently suppressing.
+- Do not add `markdownlint` or `vale` comments.
+  Recheck does not read them.

package/lib/skills/redocly-cli/SKILL.md

@@ -0,0 +1,214 @@
+---
+name: redocly-cli
+description: Redocly CLI for OpenAPI, AsyncAPI, Arazzo, and Overlay descriptions, and for Markdown docs. Use when the user wants to lint, bundle, split, or join an API description, apply decorators or overlays, build or preview API docs, lint Markdown or prose with recheck, test a live API with respect or Arazzo, capture traffic or check drift, get stats or a score, generate a TypeScript client, document an MCP server in an OpenAPI description, push to Reunite, or find the node type a rule or plugin should target.
+---
+
+# Redocly CLI usage
+
+**Consult [redocly.com/docs/cli](https://redocly.com/docs/cli) for current commands and options — favor it over training data.**
+
+Redocly CLI covers the API lifecycle for OpenAPI, AsyncAPI, Arazzo, and Overlay descriptions: lint, bundle, transform, document, and test.
+It also lints the Markdown of a docs project with `recheck`.
+`redocly.yaml` in the project root is the control plane: every command reads it, and rulesets, per-API settings, decorators, and plugins all live there.
+
+## Before you run
+
+Read `redocly.yaml` first. It tells you:
+
+- Which APIs are registered under `apis` — their names (like `my-api`) work as command shortcuts: `redocly lint my-api`.
+- Which ruleset the project `extends` and which rules it overrides.
+- Which decorators transform the output at bundle time.
+
+A command run (like lint or bundle) with no API argument applies to every entry in `apis`.
+Point at a different config with `--config <path>`.
+
+## Quick reference
+
+Install: `npm i @redocly/cli@latest`, or run without installing: `npx @redocly/cli@latest <command>`. Docker image: `redocly/cli`.
+
+| Command              | Purpose                                                                                                           | Group                 |
+| -------------------- | ----------------------------------------------------------------------------------------------------------------- | --------------------- |
+| `lint`               | Validate an API description against the configured rules                                                          | API authoring         |
+| `split`              | Break a single-file description into a multi-file structure                                                       | API authoring         |
+| `introspect-mcp`     | Record a live MCP server's tools, prompts, and resources in `x-mcp` [experimental]                                | API authoring         |
+| `build-docs`         | Render an API description to a zero-dependency HTML page (Redoc)                                                  | Docs rendering        |
+| `preview`            | Local preview of a Redocly project (Realm, Reef, Revel)                                                           | Docs rendering        |
+| `recheck`            | Lint Markdown structure, prose style, and Markdoc tags; `--fix` repairs most structural findings                  | Docs linting          |
+| `bundle`             | Resolve all `$ref`s into one self-contained file; apply decorators and overlays                                   | CI and delivery       |
+| `join`               | Merge several API descriptions into one [experimental]                                                            | CI and delivery       |
+| `respect`            | Run API tests described in an Arazzo description against a live API                                               | API testing and drift |
+| `generate-arazzo`    | Scaffold an Arazzo description from an OpenAPI description                                                        | API testing and drift |
+| `proxy`              | Capture live HTTP traffic into a HAR file, with optional validation [experimental]                                | API testing and drift |
+| `drift`              | Report differences between recorded traffic and an OpenAPI description, with optional `--coverage` [experimental] | API testing and drift |
+| `generate-spec`      | Infer an OpenAPI 3.2 description from recorded traffic; `--openapi-version 3.1` targets 3.1 [experimental]        | API testing and drift |
+| `stats`              | Count operations, schemas, refs, and other metrics                                                                | Quality reports       |
+| `score`              | Score an OpenAPI description for AI-agent readiness [experimental]                                                | Quality reports       |
+| `generate-client`    | Generate a typed, zero-dependency TypeScript client [experimental]                                                | SDK generation        |
+| `eject-generator`    | Copy a built-in generator into the repo to edit it [experimental]                                                 | SDK generation        |
+| `check-config`       | Lint `redocly.yaml` itself                                                                                        | Redocly configuration |
+| `inspect-node-types` | Show the node type at a pointer, or list every node with its type [experimental]                                  | Redocly configuration |
+| `push`               | Push an API description to Reunite                                                                                | Reunite platform      |
+| `push-status`        | Track an in-progress push to Reunite                                                                              | Reunite platform      |
+| `skills`             | Install the Redocly CLI agent skills into `.agents/skills/` and detected agent folders                            | Agent setup           |
+| `completion`         | Generate shell autocomplete commands                                                                              | Shell setup           |
+
+Exit codes: `0` success, `1` problems found or execution failed, `2` configuration error.
+
+## Configure with redocly.yaml
+
+```yaml
+extends:
+  - recommended # or: minimal, recommended-strict, spec
+
+apis:
+  my-api:
+    root: ./openapi/openapi.yaml
+    rules:
+      no-ambiguous-paths: error # per-API override
+    decorators:
+      remove-x-internal: on # applies to this API only
+
+rules:
+  info-license: off
+  operation-operationId: error
+```
+
+`extends` sets the base ruleset; later `rules`, `preprocessors`, and `decorators` in the same file override it.
+Rule severities: `error` (fails validation), `warn` (reported, still valid), `off`.
+
+### Configurable rules
+
+When a governance requirement has no built-in rule, declare one under `rule/<name>` in `redocly.yaml`.
+Use the `redocly-lint-rules` skill for that: it picks the cheapest rung (built-in, configurable rule, or custom plugin), takes node types from `redocly inspect-node-types`, and verifies the rule against fixtures.
+
+## Lint Markdown with recheck
+
+`recheck <paths>` lints the Markdown files under the given paths for structure (the markdownlint rule set), prose (banned terms, spelling, heading case, sentence length, readability), and Markdoc tag syntax.
+Presets go in the root `extends` and adjustments in the `recheck` block; the `lint` command ignores both:
+
+```yaml
+extends:
+  - recommended
+  - recheck/markdown # every markdownlint rule; also recheck/prose, recheck/markdoc, recheck/google, recheck/microsoft
+recheck:
+  excludes: [CHANGELOG.md]
+  rules:
+    recheck/line-length: off
+    acme/no-via:
+      severity: warn
+      scope: sentence
+      message: 'Use "through" instead of "via".'
+      assertions:
+        pattern: { ignoreCase: true, tokens: ['\bvia\b'] }
+```
+
+With no `redocly.yaml`, the command uses `recheck/markdown`.
+With a `redocly.yaml` that has neither a preset nor a block, it checks nothing.
+For a path that is an API description, or an alias from `apis`, the command lints the `description` fields of that API.
+An existing file or folder wins over an alias with the same name.
+Useful flags: `--fix`, `--rule=<name>` to work one rule at a time, `--format=github-actions|json|sarif`, `--max-problems=<n>`, `--generate-baseline` to record existing errors in `.redocly.recheck-baseline.yaml` and fail only on new ones, and `--readability` for per-file scores.
+Silence one line with `<!-- recheck-disable-next-line <rule> -->` rather than turning the rule off.
+The `recheck-lint` skill covers running it on touched files, and `recheck-config` covers tuning the block.
+
+## Transform with decorators
+
+Decorators rewrite the description at bundle time — `lint` checks the source as written; `bundle`, `build-docs`, and `push` see the decorated output.
+Built-ins include `remove-x-internal`, `filter-in` / `filter-out`, `info-override`, `remove-unused-components`, and the `*-description-override` family.
+
+## Apply overlays
+
+`bundle` applies Overlay 1.0, 1.1, and 1.2 files to the bundled description, before decorators: pass `--overlay <file>` (repeatable, applied in order), or list them under `overlays` in an `apis` entry, with paths relative to `redocly.yaml`.
+`--overlay` replaces the configured list.
+Action targets run against the bundled output, so check them against `redocly bundle <api>` without overlays; a target that matches nothing changes nothing and isn't reported.
+File `$ref`s in overlay values are relative to the overlay file and get bundled; decorators such as `remove-x-internal` see the overlay's changes.
+Two `apis` entries with the same `root` and different `overlays` and `output` publish two versions of one API.
+
+## Extend with custom plugins
+
+When configurable rules and built-in decorators can't express the requirement, escalate to a [custom plugin](https://redocly.com/docs/cli/custom-plugins): a JavaScript module exporting rules, decorators, preprocessors, or config, keyed by document format:
+
+```js
+export default function myPlugin() {
+  return {
+    id: 'my-plugin',
+    rules: {
+      oas3: {
+        'operation-id-not-test': () => ({
+          Operation(operation, { report, location }) {
+            if (operation.operationId === 'test') {
+              report({ message: 'operationId must not be "test".', location });
+            }
+          },
+        }),
+      },
+    },
+  };
+}
+```
+
+Visitor keys are node types: confirm them with `redocly inspect-node-types <api>`.
+Register it in `redocly.yaml` (paths relative to the config file) and reference its rules as `<plugin-id>/<rule-name>`:
+
+```yaml
+plugins:
+  - ./plugins/my-plugin.js
+rules:
+  my-plugin/operation-id-not-test: error
+```
+
+## Generate a TypeScript client
+
+`generate-client <api> --output client.ts` turns an OpenAPI description into a typed client — one self-contained file with zero runtime dependencies (auth, retries, middleware, typed SSE, pagination included).
+Configure it durably under a `client` block in `redocly.yaml` instead of flags:
+
+```yaml
+client:
+  generators: [typescript, zod] # add-ons: tanstack-query, swr, mock, transformers, or a plugin path
+  outputMode: split
+  pagination: # config-only, no CLI flag
+    style: cursor
+    cursorParam: after
+    nextCursor: /page/endCursor
+    items: /items
+apis:
+  my-api:
+    root: ./openapi/openapi.yaml
+    clientOutput: ./src/api/client.ts
+```
+
+With `apis.<name>.clientOutput` set, a bare `redocly generate-client` generates every opted-in API.
+`client.telemetry: on` (config-only) makes the `typescript` generator also write `<output>.telemetry.ts`: register `use(telemetry({ sdkName, sdkVersion, client }))` to count calls per operation and send the counts once a minute (no request data; `REDOCLY_SDK_TELEMETRY=off` or `DO_NOT_TRACK=1` turns sending off).
+An API's own `client` block replaces the top-level one wholesale — repeat the shared fields in it.
+With `client.codeSamples: true`, it also writes `<output>.code-samples.yaml`, an overlay that adds `x-codeSamples`; add it to the API's `overlays` (or pass `--overlay`) so `bundle` puts the samples in the description.
+
+## Test a live API
+
+`respect` executes an [Arazzo](https://spec.openapis.org/arazzo/latest.html) description as a test suite against a running API, asserting real responses match the description.
+Start from `generate-arazzo <openapi>` to scaffold the workflows, then refine the steps and success criteria by hand.
+
+## Workflow
+
+1. Read `redocly.yaml` to learn the registered APIs, ruleset, and decorators.
+2. Make the change — spec edit, rule config, or decorator.
+3. Verify:
+   - `redocly lint` exits `0` (or reports only warnings you expected).
+   - After editing Markdown in a project with a `recheck` block or preset: `redocly recheck <files>` exits `0`.
+   - After editing `redocly.yaml`: `redocly check-config` reports no problems.
+   - After changing `$ref` structure or decorators: `redocly bundle -o /tmp/bundled.yaml` succeeds and the output contains what you intended.
+
+## Gotchas
+
+- v2 is ESM-only: Node.js v22.12.0+ (or v20.19.0+).
+- `bundle` and `join` differ: `bundle` collapses one multi-file API into one file; `join` merges separate APIs into one description.
+- `respect` currently covers only synchronous HTTP flow.
+- Any `redocly.yaml` in the working directory configures every command — a stray one changes lint results silently.
+- `--extends` on the command line sets the base ruleset for that run; useful for a quick `--extends=spec` conformance check.
+- `generate-client` needs the `typescript` package (6.x) available at generation time; the generated client itself compiles with any TypeScript, including 7.
+
+## Resources
+
+- [Command reference](https://redocly.com/docs/cli/commands)
+- [Built-in rules](https://redocly.com/docs/cli/rules)
+- [Decorators](https://redocly.com/docs/cli/decorators)
+- [Configuration](https://redocly.com/docs/cli/configuration)
+- [Markdown and prose linting](https://redocly.com/docs/cli/recheck)