Skip to content

fix: error can't resolve $ref when components.parameters has a ref to the components.schemas #2407

Open
AlbinaBlazhko17 wants to merge 29 commits intomainfrom
fix/cant-resolve-error-in-remove-unused-components
Open

fix: error can't resolve $ref when components.parameters has a ref to the components.schemas #2407
AlbinaBlazhko17 wants to merge 29 commits intomainfrom
fix/cant-resolve-error-in-remove-unused-components

Conversation

@AlbinaBlazhko17
Copy link
Copy Markdown
Contributor

@AlbinaBlazhko17 AlbinaBlazhko17 commented Nov 4, 2025

What/Why/How?

The issue happens when parameter has a reference to schemas and remove-unused-components decorator provided in redocly.yaml.
This PR contains the global fix, nothing changes inside remove-unused-components decorator, because the issue happens in all decorators/rules, which are using Parameters visitor.

Reference

Resolves #2350

Testing

Ran tests and created new for this specific case.

Screenshots (optional)

Check yourself

  • Code changed? - Tested with Redoc/Realm/Reunite (internal)
  • All new/updated code is covered by tests
  • New package installed? - Tested in different environments (browser/node)
  • Documentation update considered

Security

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

Note

Medium Risk
Touches core bundling $ref tracking (resolvedRefMap) which can affect how decorators/rules resolve references across bundled outputs; regression risk is limited by small, targeted logic plus new E2E coverage.

Overview
Fixes a bundling edge case where decorators (notably remove-unused-components) could fail with can't resolve $ref when a bundled components.parameters entry referenced components.schemas.

bundle-visitor now records resolved bundled component refs in resolvedRefMap for both the original source context and the root bundled document, and remove-unused-components registers named components using rawLocation to align with the bundled document pointers. Adds E2E fixtures covering parameter -> schema refs and removal of an unused schema $ref alias, plus a small bundle docs clarification and a patch changeset.

Reviewed by Cursor Bugbot for commit 01f0066. Bugbot is set up for automated code reviews on this repo. Configure here.

@changeset-bot
Copy link
Copy Markdown

changeset-bot bot commented Nov 4, 2025

🦋 Changeset detected

Latest commit: 01f0066

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

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Nov 4, 2025

Command Mean [s] Min [s] Max [s] Relative
redocly lint resources/rebilly.yaml 1.446 ± 0.017 1.417 1.476 1.01 ± 0.02
redocly-next lint resources/rebilly.yaml 1.425 ± 0.019 1.395 1.457 1.00

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Nov 4, 2025

Coverage Report

Status Category Percentage Covered / Total
🔵 Lines 79.92% (🎯 79%) 6686 / 8365
🔵 Statements 79.35% (🎯 79%) 6917 / 8716
🔵 Functions 83.12% (🎯 82%) 1355 / 1630
🔵 Branches 71.61% (🎯 71%) 4546 / 6348
File Coverage
File Stmts Branches Functions Lines Uncovered Lines
Changed Files
packages/core/src/bundle/bundle-visitor.ts 68.85% 63.84% 100% 68.85% 29, 33-41, 48-56, 63, 72, 80, 85-106, 171-183, 200-201, 214-215, 255
packages/core/src/decorators/oas3/remove-unused-components.ts 97.61% 92.59% 100% 100% 89
Generated in workflow #9326 for commit 01f0066 by the Vitest Coverage Report Action

@AlbinaBlazhko17 AlbinaBlazhko17 force-pushed the fix/cant-resolve-error-in-remove-unused-components branch from 4631f22 to ec8a31c Compare November 4, 2025 15:10
@AlbinaBlazhko17 AlbinaBlazhko17 marked this pull request as ready for review November 4, 2025 15:48
@AlbinaBlazhko17 AlbinaBlazhko17 requested review from a team as code owners November 4, 2025 15:48
@AlbinaBlazhko17 AlbinaBlazhko17 self-assigned this Nov 5, 2025
Copy link
Copy Markdown
Collaborator

@tatomyr tatomyr left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please also test this change in Realm/Redoc before merging as it affects the bundler.
image

@AlbinaBlazhko17
Copy link
Copy Markdown
Contributor Author

AlbinaBlazhko17 commented Nov 5, 2025

Please also test this change in Realm/Redoc before merging as it affects the bundler. image

Tested changes in Realm/Redoc.

Screenshot 2025-11-05 at 18 40 02 Screenshot 2025-11-05 at 18 40 19

@AlbinaBlazhko17 AlbinaBlazhko17 force-pushed the fix/cant-resolve-error-in-remove-unused-components branch from 7c12980 to 06df369 Compare November 5, 2025 16:42
@jeremyfiel
Copy link
Copy Markdown
Contributor

did you check if this works for other components? headers, pathItems in 3.1.x, examples, requestBodies, responses

@AlbinaBlazhko17
Copy link
Copy Markdown
Contributor Author

@jeremyfiel Yeah, you are right, need to test with all cases, i will test it tomorrow. At the first glance, everything looks good and all users, that reported this bug faced it in parameters. I thought, that we covered a lot of cases in test and if all tests passes the fixes work correctly.

@AlbinaBlazhko17
Copy link
Copy Markdown
Contributor Author

@jeremyfiel Great point, i implemented new fix for this case and tested for all type of components, provided in remove-unused-components decorator.

Co-authored-by: Andrew Tatomyr <andrew.tatomyr@redocly.com>
resolveBundledComponent(node, resolved, ctx.location.source.absoluteRef);
// Also register from root document location if this is an external ref
// This ensures refs inside bundled components can be resolved when visited later
if (ctx.location.source !== rootDocument.source) {
Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Could you add a test to demonstrate how would such cases look like?

@github-actions
Copy link
Copy Markdown
Contributor

github-actions bot commented Apr 7, 2026

CLI Version Mean Time ± Std Dev (s) Relative Performance (Lower is Faster)
cli-latest 3.522s ± 0.028s ▓ 1.01x
cli-next 3.490s ± 0.021s ▓ 1.00x (Fastest)

Copy link
Copy Markdown

@cursor cursor bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

Fix All in Cursor

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

Reviewed by Cursor Bugbot for commit ec11e38. Configure here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

remove-unused-components removes parameters that are in use

4 participants