[dinwwwh]

🤖 Generated with Claude Code

https://claude.ai/code/session_01VVaw7RYWCsn8myBE4Rncuq

Problem

A pair of null and a $ref becomes the bare $ref when the target admits null. #356 and #363 kept the pair around a loop by walking the input. In 3.1 such a loop admits only null. The walk missed some loops, and those still became a $ref to themselves in 3.0, which matches nothing (Ajv and the Python validators overflow the stack on it). A fuzzer that builds small sets of nested pairs found about 600 such docs in every 20k. The missed spellings:

• null written as { const: null } or { enum: [null] }
• a duplicate $ref, as anyOf: [$ref, $ref, null]
• pairs nested in a oneOf, or nested more than one level deep

A:
  anyOf:
    - anyOf: [{ $ref: '#/components/schemas/A' }, { const: null }]
    - type: 'null'
# before: A: { $ref: '#/components/schemas/A' }
# after:  A: { anyOf: [{ $ref: '#/components/schemas/A' }, null branch] }

Fix

Each pair whose target admits null now becomes the bare $ref. After the post-pass, any of those that leads back to itself through bare $refs in the 3.0 output gets its pair back. The check runs on the output, so it catches every spelling. The input walk is removed (refAdmitsNull, nonNullBranches).

A pair that leads into such a loop without being on it now becomes the bare $ref, because its target keeps its pair and admits null. A pair whose target keeps a description beside its pair also becomes the bare $ref, since the description breaks the loop. The test expectations for those cases are updated.

Checks

• Tests pass with 100% branch coverage.
• The loop fuzzer finds 0 bare loops over 6 seeds × 20k docs (it found 586 on main).
• jsonschema-rs finds no lost values on the regenerated fuzz dumps.
• On the fuzz dumps, outputs differ from main only on docs with such loops.

---

Generated by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[codspeed]

Merging this PR will not alter performance

✅ 29 untouched benchmarks
⏩ 2 skipped benchmarks¹

---

_{Comparing claude/project-thread-rixcs1 (956f651) with main (2dd01ed)}

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

[pullfrog]

ℹ️ No critical issues — one documentation note below.

Reviewed changes

• Collapse now output-checked — mergeNullable collapses a null/$ref pair to the bare $ref when the target admits null, recording the pair in the new collapsedPairs list; the input-walk helpers refAdmitsNull and nonNullBranches are removed.
• Loop restore post-pass — after the deferred union pass, leadsBack walks the converted output from each collapsed $ref and restores the pair for any that reaches itself through bare $refs, so a $ref-only cycle that matches nothing no longer survives.
• Tests — expectations updated for pairs that now lead into a loop (or whose target keeps a description), plus new cases for nested pairs, duplicate $refs, and const: null.

ℹ️ README not updated for the loop exception

The 3.1→3.0 table row for the nullable $ref pair still says the pair becomes "the $ref alone, when nothing else sits beside the anyOf". After this change that holds only when the $ref does not lead back to the schema; a loop keeps the pair. Since the README is the converter's spec, that row should note the exception.

Technical details

# README: document the loop exception for the nullable `$ref` pair

## Affected sites
- `packages/downgrader/README.md:192` — the row for `anyOf` + null whose other branch is a `$ref` to a null-admitting target; its "In 3.0" cell states the bare `$ref` unconditionally.

## Required outcome
- Note that the pair stays when the `$ref` would lead back to the schema through bare `$ref`s, since the bare `$ref` would then match nothing.

## Suggested approach (optional)
- Extend the "In 3.0" cell of that row, mirroring the wording of the `leadsBack` comment (`packages/downgrader/src/v3.1-to-v3.0.ts:1739`).

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

[dinwwwh]

On the README note: I'm leaving the row as it is. The loop exception isn't new. Since #356, main has kept the pair around a loop without a note in that row, and this PR only changes how the loop is detected. The exception also only applies to a schema that in 3.1 admits nothing but null through itself. No tool writes that: 0 of the 1,052 real docs we checked contain one. A note in the table cell would make every row wider, since oxfmt pads every row of the table, and it would help no one reading it. The comment on leadsBack documents the case in the code.

---

Generated by Claude Code