fix: resolve $ref siblings during bundling

[vadyvas]

What/Why/How?

Fixed bundling for $ref siblings so sibling properties are resolved reliably, including nested external refs and non-Schema sibling contexts.

• Updated traversal logic in walk to process sibling properties next to $ref correctly.

---

Important

Bundling now resolves all sibling properties next to $ref, regardless of whether the node is interpreted as a Reference Object or a Schema Object.

This is important because OpenAPI 3.1 distinguishes these cases in the spec:

“This object cannot be extended with additional properties and any properties added SHALL be ignored.
Note that this restriction on additional properties is a difference between Reference Objects and Schema Objects that contain a $ref keyword.”

Reference

OpenAPI 3.1 — Reference Object

• Bundle does not resolve references in $ref siblings #2768
• Properties from merged references are ignored when using bundle #1329

Testing

• added tests

Screenshots (optional)

paths:
  /sample:
    get:
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Base'
                properties: # <-- should be processed as sibling content during bundle
                  second:
                    $ref: ./reference.yaml#/Second # <-- should be resolved
                additionalProperties:
                  $ref: ./reference.yaml#/Meta # <-- should be resolved
      requestBody:
        $ref: '#/components/requestBodies/SampleBody'
        description:
          $ref: ./reference.yaml#/title # <-- should be resolved (non-Schema sibling context)

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
Touches core AST traversal in walk.ts, which can subtly affect how refs and scalar fields are processed across bundling/dereferencing. Added unit and e2e fixtures reduce regression risk but behavior may change for edge-case specs relying on previous resolution order.

Overview
Bundling now resolves sibling fields next to $ref more reliably, including cases where sibling content contains nested external $refs and where $ref is used as a schema wrapper with additional keywords.

The traversal in walk.ts was adjusted to ensure sibling properties on the original node are walked appropriately rather than being skipped/treated as scalars, and new unit + e2e tests/fixtures were added to lock in the expected bundled and --dereferenced outputs. A changeset bumps @redocly/openapi-core and @redocly/cli with a patch fix note.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: 81fe95d

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]

Coverage Report

Status	Category	Percentage	Covered / Total
🔵	Lines	80.04% (🎯 80%)	7099 / 8869
🔵	Statements	79.45% (🎯 79%)	7378 / 9286
🔵	Functions	83.45% (🎯 83%)	1428 / 1711
🔵	Branches	71.5% (🎯 71%)	4798 / 6710

File Coverage

File	Stmts	Branches	Functions	Lines	Uncovered Lines
Changed Files
packages/core/src/walk.ts	98.14%	97.18%	84.21%	98.66%	184, 199, 415

Generated in workflow #9619 for commit 81fe95d by the Vitest Coverage Report Action

[github-actions]

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

[vadyvas]

@cursor review

[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 ecbaf4e. Configure here.}

[github-actions]

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

Install with NPM:

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

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