feat: configurable operation-4xx-response (excludeMethods); add tests…

[jeremyfiel]

What/Why/How?

What:

• Run the operation-4xx-response validation at the Operation level so the HTTP method is available.
• Add an excludeMethods rule option (case-insensitive array) to skip 4XX validation for specified HTTP methods.
• Default excludeMethods to ["get", "head", "options"].
• Mirror the same behavior for webhooks (honor existing validateWebhooks flag).
• Add unit tests, documentation, and a changeset.

Why:

• Safe/read-only methods commonly do not validate request bodies and often don't need a documented 4XX response. Requiring a 4XX response for every operation is noisy for many APIs. Making the excluded methods configurable lets projects relax the rule where appropriate without removing it globally.

How:

• Move the 4XX check from the Responses visitor to Operation.leave so the HTTP verb (ctx.key) can be inspected.
• If the operation method is in excludeMethods, skip validation.
• Preserve reporting location to point at the operation.responses map (keeps tests/docs stable).
• Provide a config example in docs to override excludeMethods.

Files changed (high level)

• packages/core/src/rules/common/operation-4xx-response.ts — implementation and option parsing
• packages/core/src/rules/common/tests/operation-4xx-response.exclude.test.ts — new unit tests for excluded/non-excluded methods
• docs/@v2/rules/oas/operation-4xx-response.md — documented excludeMethods option and examples
• .changeset/skip-4xx-safe-methods.md — changeset entry

Reference

• Rule docs updated: docs/@v2/rules/oas/operation-4xx-response.md
• Implementation: packages/core/src/rules/common/operation-4xx-response.ts
• Branch: jeremyfiel/fix/operation-4xx-skip-safe-methods

Testing

Local verification steps (repo root):

1. npm install
2. npm run compile
3. npm run unit
   • or to run only the new tests:
     npm run unit -- packages/core/src/rules/common/tests/operation-4xx-response.exclude.test.ts
4. npm run lint

CI:

• The PR will run the repository GitHub Actions (compile, unit tests, lint). The PR includes a changeset.

Screenshots (optional)

n/a

Check yourself

• This PR follows the contributing guide: https://github.com/Redocly/redocly-cli/blob/main/CONTRIBUTING.md#pull-request-guidelines
• All new/updated code is covered by tests (unit tests added)
• Core code changed? - Tested with other Redocly products (internal contributions only)
• New package installed? - Tested in different environments (browser/node)
• Documentation update has been considered and included (docs/@v2 updated)
• Changeset included (.changeset/skip-4xx-safe-methods.md)

Security

• The security impact of the change has been considered. This is a linter/rules change and does not execute untrusted code or change runtime behavior of published packages.
• Code follows company security practices and guidelines (no new dependencies added).

---

Note

Medium Risk
Default lint behavior changes for a common rule: GET/HEAD/OPTIONS no longer require documented 4XX responses unless users override excludeMethods, which may surprise teams on strict presets.

Overview
The operation-4xx-response rule now skips 4XX checks for configurable HTTP methods, with get, head, and options excluded by default. Validation runs at the Operation level (instead of on the responses map alone) so the verb is available; webhook operations follow the same rules when validateWebhooks is enabled. Lint locations still point at operation.responses.

Projects can extend exclusions via excludeMethods (documented with an example) or restore strict checks for every method by overriding that list (e.g. an empty array). Unit tests cover default exclusion for GET and enforcement for POST.

^{Reviewed by Cursor Bugbot for commit 17c84be. Bugbot is set up for automated code reviews on this repo. Configure here.}

[changeset-bot]

🦋 Changeset detected

Latest commit: 17c84be

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@redocly/openapi-core	Patch
@redocly/cli	Patch
@redocly/client-generator	Patch
@redocly/respect-core	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit e4533ab. Configure here.}

[github-actions]

Performance Benchmark (Lower is Faster)

CLI Version	Bundle	Lint	Check Config
cli-latest	▓▓ 1.07x ± 0.01	▓▓ 1.04x ± 0.01	▓▓▓▓▓▓ 1.20x ± 0.01
cli-next	▓ 1.00x (Fastest)	▓ 1.00x (Fastest)	▓ 1.00x (Fastest)

[adamaltman]

I'm not sure if this should be the default. GET requests can still have 4xx responses like 401, 403, 429 which could be documented and the documentation could help consumers and code gen.

[jeremyfiel]

good call.
i wonder if it makes more sense to target the operations and codes directly. the way it stands, it's fairly noisy but to your point, there are definitely use cases where it's helpful for those other non validation responses

how do you feel about this?

rules:
  operation-4xx-response:
  severity: warn
  exclusions:
    get: 
    - 400
    head:
    - 400

[adamaltman]

I'm not sure I follow what does the exclusion get 400 mean?

I would read it to mean that if the get request has a 400 response, then exclude that 400 response from being evaluated here but it doesn't make sense because it would pass this rule then if it has a 400 response. Or am I interpreting it wrong?

I think excludeMethods makes more sense, but just that the default no methods are excluded (for BC).

[adamaltman]

Suggested change

	const defaultExcluded = ['get', 'head', 'options'];
	const defaultExcluded = ['options'];

I think I would start with this possibly.

Also, even this is a breaking change.