fix(core): validate/remove unused securitySchemes and securityDefinitions correctly

[tatomyr]

What/Why/How?

• Updated the no-unused-components rule to validate unused security schemes
• Fixed the remove-unused-components decorator to remove unused security schemes (fixed in Swagger 2.0; added in OAS 3.x)

Reference

Resolves #944

Testing

Internal tests passed: https://github.com/Redocly/redocly/pull/23392

Screenshots (optional)

Check yourself

• This PR follows the contributing guide
• All new/updated code is covered by tests
• 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

Security

• The security impact of the change has been considered
• Code follows company security practices and guidelines

---

Note

Medium Risk
Changes lint warnings and bundle output for security-related components; APIs with defined-but-unreferenced schemes may see new warnings or lose those schemes when bundling with remove-unused-components.

Overview
no-unused-components now treats components.securitySchemes (and Swagger 2 securityDefinitions) as used when they appear by name in any security requirement, not only via $ref. Unused schemes get dedicated diagnostics (e.g. Security scheme: "…" is never used.).

remove-unused-components uses the same notion of “used” so bundling keeps schemes referenced in security (including $ref chains between schemes) and can drop schemes that are only defined or only referenced indirectly through an unused base scheme.

Docs and changesets note that lint may surface extra warnings and bundle --remove-unused-components may strip more entries than before.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: 8b9854a

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

This PR includes changesets to release 3 packages

Name	Type
@redocly/openapi-core	Patch
@redocly/cli	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

[tatomyr]

@cursor review

[github-actions]

CLI Version	Mean Time ± Std Dev (s)	Relative Performance (Lower is Faster)
cli-latest	1.965s ± 0.018s	▓ 1.00x (Fastest)
cli-next	1.986s ± 0.053s	▓ 1.01x

[github-actions]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	81.05% (🎯 80%)	7301 / 9007
🔵	Statements	80.4% (🎯 80%)	7585 / 9433
🔵	Functions	84.08% (🎯 83%)	1463 / 1740
🔵	Branches	72.55% (🎯 72%)	4939 / 6807

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/core/src/decorators/oas2/remove-unused-components.ts	93.61%	90.9%	83.33%	95.23%	31, 96-101
packages/core/src/decorators/oas3/remove-unused-components.ts	96.15%	92.1%	100%	97.91%	28, 172
packages/core/src/rules/oas3/no-unused-components.ts	96.55%	93.33%	100%	100%	44

Generated in workflow #9963 for commit 8b9854a by the Vitest Coverage Report Action

[github-actions]

📦 A new experimental 🧪 version v0.0.0-snapshot.1779373140 of Redocly CLI has been published for testing.

Install with NPM:

npm install @redocly/cli@0.0.0-snapshot.1779373140
# or
npm install @redocly/openapi-core@0.0.0-snapshot.1779373140
# or
npm install @redocly/respect-core@0.0.0-snapshot.1779373140

⚠️ Note: This is a development build and may contain unstable features.

[github-actions]

📦 A new experimental 🧪 version v0.0.0-snapshot.1779448714 of Redocly CLI has been published for testing.

Install with NPM:

npm install @redocly/cli@0.0.0-snapshot.1779448714
# or
npm install @redocly/openapi-core@0.0.0-snapshot.1779448714
# or
npm install @redocly/respect-core@0.0.0-snapshot.1779448714

⚠️ Note: This is a development build and may contain unstable features.

[cursor]

Cursor Bugbot has reviewed your changes 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 25d2099. Configure here.}

[kanoru3101]

I found one issue with the wrong warn/error location

If try with

openapi: 3.1.0
servers:
  - url: https://test.com
info:
  title: PR 2830 repro — $ref chain between securitySchemes
  version: 1.0.0
paths:
  /foo:
    get:
      security:
        - base: []
      summary: Uses 'derived', which is itself a $ref to 'base'
      responses:
        '200':
          description: ok
components:
  securitySchemes:
    base:
      type: apiKey
      name: x-api-key
      in: header
    derived:
      $ref: '#/components/securitySchemes/base'

The warning says "derived" is never used but points to line 18 (base:) instead of line 22 where derived is declared

Run lint command

Run bundle --remove-unused-components command