fix(downgrader): inline $refs into parts removed by 3.2 to 3.1

[dinwwwh]

3.2 → 3.1 no longer leaves $refs pointing at parts it removes. A reference into components.mediaTypes, a query or additionalOperations operation, a removed parameter, or a moved itemSchema is now replaced by its converted target, so the output validates as 3.1. Documents without such references convert exactly as before.

Fixes

• Reference Objects and Schema Object $refs into removed parts are inlined in converted form, following reference chains. #/components/mediaTypes/Pet/schema becomes the Pet schema; beside other schema keywords the target is appended to allOf.
• A ref loop through a removed part is cut by dropping the reference, instead of producing a circular object that JSON.stringify cannot serialize.
• References into a parameter list that lost a querystring entry no longer point at the wrong parameter.
• References that resolve to a removed parameter or header through any pointer are removed, not only aliases inside components.
• Content-map $refs resolve any local media type, including escaped names such as a~1b.
• Shared schemas in dereferenced documents are still converted once (fix(downgrader): convert shared schemas once in dereferenced documents #23), in both passes.

Performance

Document (200 schemas, 100 paths)	main	this PR
No dangling refs	2.57 ms	3.28 ms
One dangling ref	2.58 ms	6.67 ms

Every distinct $ref is checked against the first-pass result, and schemas are walked rather than copied. A second pass runs only when something dangles.

Testing

• 400 tests pass with 100% coverage of packages/downgrader/src; lint and type-check pass.
• An end-to-end 3.2 document with refs into mediaTypes, query, additionalOperations and a shifted parameter index validates as 3.1 and, chained, as 3.0.
• Both routes into the ref-cycle bug have regression tests that fail with the old guard; a depth-40 shared schema diamond converts once with a dangling ref present.

Known limits

• A recursive schema defined only under a removed part keeps one level and its repeat becomes {}, since 3.1 has nowhere to keep it without inventing a component name. Where the cut lands can depend on key order.
• Link operationRef and discriminator mapping values pointing into removed parts pass through unchanged; the README lists them.
• 3.1 → 3.0 has the same class of problem (refs into dropped $defs dangle). That is a separate change.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[pullfrog]

Important

The main contract holds for the paths under test, but the two-pass dangling detection can still emit a dangling $ref when a dangling Reference Object is dropped by the cycle cut from a parameter/header array: the drop shifts indices relative to the draft snapshot that danglesIn was computed against, so a ref to a later index is judged alive and kept. See the inline note.

Reviewed changes

• Schema $ref inlining — finishSchema inlines a dangling schema $ref's converted target, merging into allOf when the schema has siblings and returning the target directly when otherwise empty; createSchemaFields.$ref drops the keyword when it dangles.
• Reference Object inlining — convertRefOr inlines any Reference Object whose target dangles, following reference chains; content-map entries now resolve any local pointer via resolveRefChain.
• Two-pass detection — the first pass records every $ref and produces a draft; danglesIn compares source-vs-draft pointer resolution (with an array-length index-shift sentinel); the second pass inlines only when something dangles.
• Generalized parameter/header removal — resolveRefChain + losesEntireContent replace the precomputed component-ref index, so refs through any pointer are removed, not only aliases inside components.
• New shared.ts helpers — parseLocalRef, getChild, resolveLocalRef, isConverting, with unit tests.
• README — documents $ref inlining and the new known limits.

  ^{｜ Fix all ➔ ｜ Fix 👍s ➔ ｜ View workflow run ｜ Using DeepSeek Flash (default — pick a model for stronger reviews) ｜ 𝕏}

[pullfrog]

✅ No new issues found.

Reviewed changes

The prior review flagged that the second pass could drop a cyclic dangling Reference Object from a parameter/header array while dangles had been computed against the first-pass draft that still contained it, so a ref to a later index was judged alive and left dangling. 665b33e closes that gap.

• Made the cycle cut happen in both passes — convertRefOr now drops a value when resolveRefChain(value, context) === DROP, so the first-pass draft (where dangles is recorded but refs are otherwise kept) already reflects the same array shrinking the second pass produces.
• resolveRefChain now returns DROP on a loop instead of undefined, and resolveMediaType / losesEntireContent were updated to treat that as dropped, so cyclic alias chains are consistently removed everywhere rather than preserved.
• Updated the alias-cycle test (a cycle can never resolve, so { parameters: {} } is now correct) and added a parameter-index regression test.
• I independently verified the new regression test fails without the guard: with 665b33e reverted the output leaves P: { $ref: '#/paths/~1a/get/parameters/1' } dangling, exactly the prior repro. With the fix, 401 tests, lint, and typecheck pass.

  ^{｜ View workflow run ｜ Using DeepSeek Flash (default — pick a model for stronger reviews) ｜ 𝕏}