fix(cli): fix join dropping non-string x-* path extension properties by nonchan7720 · Pull Request #2949 · Redocly/redocly-cli

nonchan7720 · 2026-07-13T16:41:20Z

What/Why/How?

Fixes join silently dropping non-string x-* extension properties defined directly under a path item (e.g.
paths./pets/{petId}.x-foo: true).

collectPaths only merged path-level extensions when their value was a string, via collectPathStringFields. Non-string values
(booleans, objects, arrays, numbers) were never copied into the joined document.

collectPathExtension now handles every non-string x-* field on a path item: it copies the value into the joined path the first
time it's seen, and logs a warning instead of silently overwriting when two source documents provide different values for the same
field.

Reference

Fixes #1574

Testing

Added a path extensions test group to join.test.ts with fixtures in documents.ts covering:

merging a non-string x-* path extension when both source documents agree on the value
logging a warning when the values conflict

Verified against the pre-fix implementation that both new tests fail without this change.

Screenshots (optional)

N/A — CLI behavior change only.

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) — N/A, packages/cli only
New package installed? - Tested in different environments (browser/node) — N/A
Documentation update has been considered — no doc change needed, this restores documented merge behavior
Changeset added — still missing, run npx changeset before merging (@redocly/cli, patch)

Security

The security impact of the change has been considered — object merge over already-parsed/trusted document data, no new external
input surface
Code follows company security practices and guidelines

Note

Low Risk
Scoped CLI join merge logic with tests; no auth, security, or new external input surfaces.

Overview
Fixes join silently omitting path-item x-* extensions when values are not strings (objects, booleans, arrays, etc.).

collect-paths now routes every x-* field on a path item through the same merge path as string fields (e.g. summary), instead of only copying fields whose value is a string. Conflicts between APIs are detected with dequal instead of !==, so object extensions warn when values differ and are kept when they match.

Adds path extensions tests and fixtures for matching x-metadata, conflicting values, and differing object shapes, plus a patch changeset for @redocly/cli.

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

changeset-bot · 2026-07-13T16:41:26Z

🦋 Changeset detected

Latest commit: b593d94

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

This PR includes changesets to release 3 packages

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

Clarified the fix for join extension property to specify that it addresses non-string x-* path extension properties.

github-actions · 2026-07-14T16:18:06Z

Performance Benchmark (Lower is Faster)

CLI Version	Bundle	Lint	Check Config
cli-latest	▓ 1.01x ± 0.02	▓ 1.00x ± 0	▓ 1.00x (Fastest)
cli-next	▓ 1.00x (Fastest)	▓ 1.00x (Fastest)	▓ 1.01x ± 0.01

adamaltman · 2026-07-16T17:00:14Z

+        .mockImplementationOnce(() =>
+          Promise.resolve({
+            source: { absoluteRef: 'ref-b' },
+            parsed: anotherPathWithDifferentObjectExtension,


What if the object had different keys though? Like a.yaml has owner and b.yaml has team?

A warning log is being output.
I think we'll just have to handle this the same way we do other standard items.

If this part overlaps, it means the paths also overlap.

@nonchan7720 Please add a test for this case { owner: 'team-a' } and { team: 'x' }.

kanoru3101

Thanks for the contribution. Checked it out locally — works as expected, non-string x-* path extensions now merge the same way as regular path-level fields (first one wins, warning on conflict).

Left a few comments.

kanoru3101 · 2026-07-17T12:32:42Z

+        .mockImplementationOnce(() =>
+          Promise.resolve({
+            source: { absoluteRef: 'ref-b' },
+            parsed: anotherPathWithDifferentObjectExtension,


@nonchan7720 Please add a test for this case { owner: 'team-a' } and { team: 'x' }.

Co-authored-by: Viktor Sydor <31951646+kanoru3101@users.noreply.github.com>

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.}

Want higher recall? High effort reviews run extra passes and find more bugs. A team admin can switch effort levels in the Cursor dashboard.

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

RomanHotsiy

LGTM, left one simplification comment

RomanHotsiy · 2026-07-18T00:38:37Z

-        if (typeof pathItem[field] === 'string') {
+        if (
+          typeof pathItem[field] === 'string' ||
+          (field.startsWith('x-') && typeof pathItem[field] !== 'string')


Suggested change

(field.startsWith('x-') && typeof pathItem[field] !== 'string')

(field.startsWith('x-'))

fixed.
5b7a1cc

kanoru3101

LGTM

Co-authored-by: Viktor Sydor <31951646+kanoru3101@users.noreply.github.com>

fix: join extension property

8a20526

nonchan7720 added 2 commits July 14, 2026 01:59

fix collectPathExtension

9c2f824

test: cover non-string x-* path extension merging in join

489b31e

nonchan7720 changed the title ~~fix: join extension property~~ fix: Fix join dropping non-string x-* path extension properties. Jul 13, 2026

Clarify fix for join extension property

bc76fd1

Clarified the fix for join extension property to specify that it addresses non-string x-* path extension properties.

nonchan7720 marked this pull request as ready for review July 13, 2026 17:16

nonchan7720 requested review from a team as code owners July 13, 2026 17:16

nonchan7720 changed the title ~~fix: Fix join dropping non-string x-* path extension properties.~~ fix(cli): Fix join dropping non-string x-* path extension properties. Jul 13, 2026

nonchan7720 changed the title ~~fix(cli): Fix join dropping non-string x-* path extension properties.~~ fix(cli): fix join dropping non-string x-* path extension properties. Jul 14, 2026

nonchan7720 changed the title ~~fix(cli): fix join dropping non-string x-* path extension properties.~~ fix(cli): fix join dropping non-string x-* path extension properties Jul 14, 2026

adamaltman reviewed Jul 16, 2026

View reviewed changes

kanoru3101 reviewed Jul 17, 2026

View reviewed changes

Update .changeset/dull-adults-punch.md

310638c

Co-authored-by: Viktor Sydor <31951646+kanoru3101@users.noreply.github.com>

cursor Bot reviewed Jul 17, 2026

View reviewed changes

Comment thread packages/cli/src/commands/join/utils/collect-paths.ts Outdated

nonchan7720 added 2 commits July 18, 2026 00:30

test: cover x-* path extension merge when objects have different keys

229f223

refactor: merge collectPathExtension into collectPathStringFields

c3edfd1

nonchan7720 requested review from adamaltman and kanoru3101 July 17, 2026 15:38

RomanHotsiy approved these changes Jul 18, 2026

View reviewed changes

nonchan7720 and others added 2 commits July 18, 2026 10:50

refactor: simplify x-* field condition in collectPaths

5b7a1cc

Merge branch 'main' into fix_issue_1574

c3fc9fb

kanoru3101 approved these changes Jul 18, 2026

View reviewed changes

Comment thread .changeset/dull-adults-punch.md Outdated

Update .changeset/dull-adults-punch.md

b593d94

Co-authored-by: Viktor Sydor <31951646+kanoru3101@users.noreply.github.com>

nonchan7720 requested review from RomanHotsiy and kanoru3101 July 18, 2026 13:33

kanoru3101 approved these changes Jul 18, 2026

View reviewed changes

	(field.startsWith('x-') && typeof pathItem[field] !== 'string')
	(field.startsWith('x-'))

Uh oh!

Conversation

nonchan7720 commented Jul 13, 2026 • edited by cursor Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What/Why/How?

Reference

Testing

Screenshots (optional)

Check yourself

Security

Uh oh!

changeset-bot Bot commented Jul 13, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

github-actions Bot commented Jul 14, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Performance Benchmark (Lower is Faster)

Uh oh!

adamaltman Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

nonchan7720 Jul 16, 2026

Choose a reason for hiding this comment

Uh oh!

kanoru3101 Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

kanoru3101 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

kanoru3101 Jul 17, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cursor Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

RomanHotsiy left a comment

Choose a reason for hiding this comment

Uh oh!

RomanHotsiy Jul 18, 2026

Choose a reason for hiding this comment

Uh oh!

nonchan7720 Jul 18, 2026

Choose a reason for hiding this comment

Uh oh!

kanoru3101 left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

nonchan7720 commented Jul 13, 2026 •

edited by cursor Bot

Loading

changeset-bot Bot commented Jul 13, 2026 •

edited

Loading

github-actions Bot commented Jul 14, 2026 •

edited

Loading