[dinwwwh]

Requested by dinwwwh · project thread

What

isInlined replaces a $ref into items, additionalProperties, $defs or definitions with its target, because the conversion can replace what sits there. It tested the whole pointer, though, so a $ref to a component named one of those words also matched, for example #/components/schemas/items.

Such a component was then inlined at every use. When it is recursive, the inlined copy is cut to {} one level down, so the output loses every constraint below that level and the named type is gone.

Now only the part after #/components/<type>/<name> is checked, since that segment is a name and not a keyword:

• A keyword after the name still counts, so #/components/schemas/items/properties/rows/items is still replaced.
• The % check and the removed-part prefixes still look at the whole $ref.

Found in real docs

Celigo's npm specs (Tools, Imports, Exports, APIs, AI Agents, Async Helpers) name their recursive mapping row items. Before this change, Mappings.items.properties.mappings.items became the inlined row, with its nested mappings.items set to {}.

A new symbolic oracle found it: json-schema-diff, with recursive schemas unrolled 3 levels. It flagged those components, and after this change it flags none.

Repro:

downgradeSpecV31ToV30({ openapi: '3.1.0', info, paths: {}, components: { schemas: {
  items: { type: 'object', properties: { kids: { type: 'array', items: { $ref: '#/components/schemas/items' } } } },
} } })
// before: items.properties.kids.items = { type: 'object', properties: { kids: { type: 'array', items: {} } } }
// after:  items.properties.kids.items = { $ref: '#/components/schemas/items' }

Tests

• New test: components named items, additionalProperties, $defs and definitions, plus a response named items, all keep their $ref. A $ref with a keyword after the name is still replaced. The test fails on main.
• Suite: all 309 downgrader tests pass, and branch coverage of src stays at 100%.
• Checks: pnpm run check passes.

---

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-ttohne (8ed8ba0) with main (f5c6835)}

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 new issues found.

Reviewed changes

• isInlined strips the component prefix — packages/downgrader/src/v3.1-to-v3.0.ts:298 now removes #/components/<type>/<name> before testing for /$defs/, /definitions/, and INTO_REPLACED, so a $ref to a component named items or additionalProperties is no longer mistaken for a $ref into a keyword. The % check and the #/webhooks/ / #/components/pathItems/ prefixes still read the whole ref, as documented.
• Regression test — packages/downgrader/tests/v3.1-to-v3.0.test.ts:2935 pins component names items, additionalProperties, $defs, definitions, a response named items, and that a keyword after the name (items/properties/rows/items) is still inlined.

I verified locally: all 309 downgrader tests pass, v3.1-to-v3.0.ts branch coverage is unaffected for the new code (the only uncovered branch, line 1718, is in convertSecurity and pre-existing), and pnpm run check (sherif, oxlint, oxfmt, tsc) passes.

The only behavior narrowed is a $ref pointing directly at a $defs/definitions map under a component whose name is itself $defs/definitions — not a valid schema reference, and refs into removed keywords dangling is already a documented limitation.

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