fix(drift): match path segments that mix literal text with parameters

[ariesclark]

What/Why/How?

Note

This was heavily assisted by Anthropic's Opus 5. I've reviewed the code to the best of my ability, but if there's any obvious issues I didn't catch, let me know.

A path template whose segment mixes literal text with parameters never matched a request. compileOpenApiPath tested each segment with /^\{([^}]+)\}$/, which recognizes only a segment that is entirely one parameter. Anything else, such as two parameters or a parameter beside literal text, fell through to escapeRegex and became a literal. So /instances/{worldId}:{instanceId} matched only a URL containing that raw text, which no request carries. drift reported those requests as undocumented and coverage left them out of its figures.

The compiler now scans each segment for \{([^}]+)\}, escapes the literal runs between matches, and emits ([^/]+?) per parameter. Non-greedy is deliberate: with two parameters around a separator, the first must stop at the first occurrence rather than swallow to the last.

Specificity scoring gains a middle tier. A pure literal still scores +2 and a bare parameter 0, with +1 for a segment holding both. The counter reads a per-segment paramsBefore snapshot, because params accumulates across the whole template.

Reference

None.

Testing

compile-openapi-path.test.ts covers single-parameter segments, the / boundary, two parameters in one segment, a multi-parameter segment with a following suffix, the first-separator split when the trailing value holds another separator, score ordering, and pure literals.

Against a 140-exchange capture, drift's false "undocumented endpoint" reports went from 3 to 0 and coverage rose from 87 to 90 operations. drift now validates the three newly matched responses.

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

The change only widens which documented paths a recorded request can match, and adds no new input handling.

---

Note

Low Risk
Localized regex compilation fix with broad test coverage; it only expands which documented paths match traffic and does not add new input surfaces.

Overview
compileOpenApiPath no longer treats only whole-segment {param} templates as parameters. Segments like /instances/{worldId}:{instanceId} are compiled by scanning each {name}, escaping literal runs, and emitting non-greedy ([^/]+?) captures so the first parameter stops at the first separator.

drift and coverage can therefore match recorded traffic to those documented routes instead of flagging them undocumented or omitting them from coverage. Specificity scoring adds +1 for mixed literal/parameter segments (between pure literals +2 and bare parameters 0).

New unit tests in compile-openapi-path.test.ts cover multi-parameter segments, separator boundaries, suffix paths, and score ordering. Changeset documents the patch for @redocly/cli.

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

[changeset-bot]

🦋 Changeset detected

Latest commit: 78d0b0b

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

This PR includes changesets to release 4 packages

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