[dinwwwh]

Requested by dinwwwh · project thread

Summary

find() percent-decodes a $ref, but isInlined checks for /$defs/, /definitions/, the removed parts, and items/additionalProperties on the ref as written. So a $ref such as #/components/schemas/Pair/%69tems (items) was kept as a $ref, and then read the schema the conversion writes at that spot. Where that schema is looser and sits under a not, the 3.0 output rejects values the 3.1 input accepts.

The fix is one more condition: any $ref containing % is replaced by its target, which find already resolves correctly. That also covers percent-encoded #/webhooks/ and #/components/pathItems/ prefixes, so the README limitation about them is removed.

Tradeoffs

• A percent-encoded $ref to an ordinary component, such as #/components/schemas/My%20Pet, is now inlined instead of kept. The output is larger and code generators lose that named type there, but percent-encoded refs are rare in generated documents (oRPC never writes them), and the inlined schema accepts exactly what the target does.

Test plan

• New test: replaces a percent-encoded $ref with its target.
• vitest run packages/downgrader (299 passed) and pnpm check pass locally.

---

Generated by Claude Code

[codspeed]

Merging this PR will not alter performance

1 warning

⚠️ 1 benchmark is dominated by system calls

System calls cannot be simulated consistently and are left out of the measure. The reported value understates the real cost. Switch to the Walltime instrument to measure them.

Learn more about system calls

See affected benchmarks

✅ 29 untouched benchmarks
⏩ 2 skipped benchmarks¹

---

_{Comparing claude/project-thread-h3q238 (c607746) with main (6aeeb95)}

Footnotes

1. 2 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[pullfrog]

ℹ️ No critical issues — one minor docs suggestion below.

Reviewed changes

• Percent-encoded $refs are inlined. isInlined (packages/downgrader/src/v3.1-to-v3.0.ts:285) now returns true for any $ref containing % that resolvePointer resolves, so a ref whose /$defs/, /definitions/, removed-part, or items/additionalProperties segment is percent-encoded is replaced by its target instead of kept as written.
• README limitation removed. The bullet stating removed-part $refs are recognized only by their literal #/webhooks/ / #/components/pathItems/ prefix is dropped.
• New test. replaces a percent-encoded $ref with its target covers a percent-encoded pathItems ref, $defs, an items ref under a not, and an encoded property name.

ℹ️ Schema README no longer matches how $defs $refs are recognized

packages/downgrader/README.md:256 still tells readers that a $ref "into $defs is recognized by its /$defs/ segment", but this PR makes a percent-encoded ref such as #/components/schemas/Box/%24defs/Id resolve and inline too, so the statement is now incomplete in the same way the bullet this PR removed from the Paths section was. Worth updating alongside the change, together with a note that any percent-encoded $ref — including one to an ordinary component — is now inlined (larger output, the named type is lost at that site).

Technical details

# README `$defs`-recognition clause is now stale

## Affected sites
- `packages/downgrader/README.md:256` — "Every `$ref` is read as a JSON Pointer from the document root, and one into `$defs` is recognized by its `/$defs/` segment." With the new `%` condition, `isInlined` (`packages/downgrader/src/v3.1-to-v3.0.ts:285`) also recognizes a percent-encoded `$defs` segment (as it does `definitions`, a removed part, or `items`/`additionalProperties`).

## Required outcome
- The schema Limitations section should no longer imply a literal `/$defs/` segment is the only recognition path, and should reflect that a percent-encoded `$ref` is inlined — including one to an ordinary component, which is the tradeoff this PR makes.

## Context
- This PR already removed the parallel paths bullet: "`$ref`s into removed parts are recognized by their `#/webhooks/` or `#/components/pathItems/` prefix as written, not percent-encoded." The `$defs` clause at `README.md:256` is the schema-section analogue left behind.

  ^{｜ Fix it ➔ ｜ View workflow run ｜ Using deepseek-v4.1-flash (free via Pullfrog for OSS) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes

Re-reviewed the delta since the prior pullfrog review: a docs-only follow-up to the inline-$ref change.

• README limitation updated. The schema Limitations bullet now notes that a $ref which percent-encodes a character, such as #/%24defs/Pet, is replaced by its target, closing the gap flagged in the prior review. The text matches isInlined (packages/downgrader/src/v3.1-to-v3.0.ts:285), where any %-bearing $ref that resolvePointer resolves is inlined.

  ^{｜ View workflow run ｜ Using deepseek-v4.1-flash (free via Pullfrog for OSS) ｜ 𝕏}