Route path generation: use string concatenation instead of template literals to eliminate $-escaping heuristics

[coderabbitai]

Summary

During review of #3692 (security fix for unescaped OpenAPI strings in generated template literals), a related edge case was identified in packages/core/src/getters/route.ts's getRoutePath function: a literal $ immediately preceding a {param} in an OpenAPI path (e.g. /foo${petId}) is dropped in the generated template literal, producing /foo${petId} instead of /foo$${petId}.

Rationale (root cause, not just this instance)

The underlying problem is not this single edge case — it's the approach. Orval currently builds generated route/URL strings as raw JS template literals, and relies on ad-hoc heuristics (inspecting preceding characters such as \ vs $) to disambiguate a literal $ in the OpenAPI spec from the ${...} interpolation syntax it emits for path parameters. As more jsesc-based escaping of static segments is layered on top, these heuristics keep multiplying and are fragile by construction — every new escaping rule risks colliding with legitimate spec content in a new way.

Patching the heuristic for this one case (literal $ before {param}) does not address the underlying issue: any future OpenAPI path containing characters adjacent to ${/} sequences from jsesc escaping is a candidate for a similar bug.

Proposed fix

Move getRoutePath, getRoute, and getRouteAsArray (and any other generators building route/URL strings from spec content) away from constructing raw template-literal source text via character-adjacency heuristics. Instead, build the generated string using explicit string concatenation of separately-escaped literal segments and parameter placeholders (or an equivalent AST/token-based builder). This removes the need to guess intent from adjacent characters, since literal text and parameter interpolation are never emitted as raw overlapping template-literal syntax that has to be disambiguated after the fact.

Affected areas

• packages/core/src/getters/route.ts (getRoutePath, getRoute, getRouteAsArray)
• Possibly other generators that build template-literal strings from OpenAPI spec content

Acceptance criteria

• Generated route/URL strings are built via string concatenation (or equivalent non-heuristic construction) instead of raw template-literal text with character-adjacency escaping heuristics.
• Literal $ (and other characters that could collide with template-literal syntax) immediately preceding a {param} in an OpenAPI path is preserved correctly regardless of adjacency (e.g. /foo${petId} emits the correct literal $ before the parameter).
• No regression in generated output for existing test fixtures.
• Scoped for the v9 release per the maintainer's guidance.

References

• PR: fix: escape spec-controlled strings in generated template literals and object keys #3692
• Discussion: fix: escape spec-controlled strings in generated template literals and object keys #3692 (comment)
• Requested by: @aqeelat

[aqeelat]

@coderabbitai the idea is to avoid this entire class of errors by using string concatenation instead of template literals. This issue misses the point. Rewrite it.

[coderabbitai]

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
gh issue view 3703 --repo orval-labs/orval --comments

Length of output: 442

---

🏁 Script executed:

#!/bin/bash
gh issue view 3703 --repo orval-labs/orval --json title,body,comments --jq '{title, body, comments: [.comments[] | {author: .author.login, body}]}'

Length of output: 2689

---

🏁 Script executed:

#!/bin/bash
gh issue edit 3703 --repo orval-labs/orval \
  --title "Route path generation: use string concatenation instead of template literals to eliminate \$-escaping heuristics" \
  --body "## Summary

During review of `#3692` (security fix for unescaped OpenAPI strings in generated template literals), a related edge case was identified in \`packages/core/src/getters/route.ts\`'s \`getRoutePath\` function: a literal \`\$\` immediately preceding a \`{param}\` in an OpenAPI path (e.g. \`/foo\${petId}\`) is dropped in the generated template literal, producing \`/foo\${petId}\` instead of \`/foo\$\${petId}\`.

## Rationale (root cause, not just this instance)

The underlying problem is not this single edge case — it's the approach. Orval currently builds generated route/URL strings as raw JS **template literals**, and relies on ad-hoc heuristics (inspecting preceding characters such as \`\\\` vs \`\$\`) to disambiguate a literal \`\$\` in the OpenAPI spec from the \`\${...}\` interpolation syntax it emits for path parameters. As more jsesc-based escaping of static segments is layered on top, these heuristics keep multiplying and are fragile by construction — every new escaping rule risks colliding with legitimate spec content in a new way.

Patching the heuristic for this one case (literal \`\$\` before \`{param}\`) does not address the underlying issue: any future OpenAPI path containing characters adjacent to \`\${\`/\`}\` sequences from jsesc escaping is a candidate for a similar bug.

## Proposed fix

Move \`getRoutePath\`, \`getRoute\`, and \`getRouteAsArray\` (and any other generators building route/URL strings from spec content) away from constructing raw template-literal source text via character-adjacency heuristics. Instead, build the generated string using explicit **string concatenation** of separately-escaped literal segments and parameter placeholders (or an equivalent AST/token-based builder). This removes the need to guess intent from adjacent characters, since literal text and parameter interpolation are never emitted as raw overlapping template-literal syntax that has to be disambiguated after the fact.

## Affected areas

- \`packages/core/src/getters/route.ts\` (\`getRoutePath\`, \`getRoute\`, \`getRouteAsArray\`)
- Possibly other generators that build template-literal strings from OpenAPI spec content

## Acceptance criteria

- Generated route/URL strings are built via string concatenation (or equivalent non-heuristic construction) instead of raw template-literal text with character-adjacency escaping heuristics.
- Literal \`\$\` (and other characters that could collide with template-literal syntax) immediately preceding a \`{param}\` in an OpenAPI path is preserved correctly regardless of adjacency (e.g. \`/foo\${petId}\` emits the correct literal \$ before the parameter).
- No regression in generated output for existing test fixtures.
- Scoped for the v9 release per the maintainer's guidance.

## References

- PR: https://github.com/orval-labs/orval/pull/3692
- Discussion: https://github.com/orval-labs/orval/pull/3692#discussion_r3561486367
- Requested by: `@aqeelat`"

Length of output: 3330

---

@aqeelat done — I've rewritten issue #3703 to center on the actual ask: replacing the template-literal + character-adjacency-heuristic construction in getRoutePath/getRoute/getRouteAsArray with string concatenation, so this whole class of $/{} collision bugs goes away instead of patching one heuristic at a time. The rationale, proposed fix, and acceptance criteria now reflect that.

---

✏️ Learnings added

Learnt from: aqeelat
URL: https://github.com/orval-labs/orval/issues/3703

Timestamp: 2026-07-10T21:41:37.176Z
Learning: For the orval-labs/orval repository, when fixing issues related to unsafe generated route/URL strings in `packages/core/src/getters/route.ts` (e.g. `getRoutePath`, `getRoute`, `getRouteAsArray`), the maintainer (aqeelat) prefers replacing template-literal construction with character-adjacency escaping heuristics (e.g. distinguishing literal `$` from `${...}` interpolation) with explicit string concatenation, rather than patching individual heuristic edge cases. The goal is to eliminate the entire class of `$`/`{}` collision bugs, not fix them one at a time.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.