refactor(downgrader): reuse aliasEnd, skip the second pass for path item fields, fix oracle drift

[dinwwwh]

Three small cleanups in packages/downgrader. Converter outputs do not change.

Changes

1. Reuse ctx.aliasEnd in convertContentEntry (src/v3.2-to-v3.1.ts)
A media type $ref used to be followed with skipAliases(ref, ctx, () => true), which re-walks the alias chain. It now calls the memoised ctx.aliasEnd. A chain that loops still comes out as DROP. skipAliases is no longer exported, since only inlineSchema and refOr use it.

2. One pass for references into dropped Path Item fields (src/shared.ts)
removedPrefixes only listed document and components prefixes. So a $ref or operationRef into a path item's query or additionalOperations was only found dangling after a whole pass, and the entire document was converted again.

• removedParts replaces removedPrefixes. It also reports which fields of PATH_ITEM_FIELDS are DROP.

• New isInDroppedPathItemField recognises a Path Item pointer (via isPathItemPointer) followed by one of those fields. It walks the input to skip Path Items the converter copies rather than converts:

  • extensions under paths;
  • anything under a Callback Object that is a Reference Object;
  • anything under a value that isn't an object.

  A plain isPathItemPointer check would wrongly inline references into those.

• The check only seeds dangles in the first pass. ctx.isRemovedPart, which decides which links and discriminator mappings are removed, stays prefix-only. Folding the check in there would start removing links and mappings whose target is missing or can't be inlined, such as an operationRef to a query that doesn't exist.

• Only a reference whose text names one of the dropped fields is parsed and walked. A document with thousands of references therefore pays nothing extra, and neither does 3.1 → 3.0, where no Path Item field is dropped.

3. Test oracle drift (tests/validate.ts)
resolvePointer stays independent of parsePointer/child on purpose: the conversion uses those to decide what dangles, so an oracle built on them would share their bugs. A comment now says so, and its drift is fixed:

• #/a/length no longer resolves on an array;
• a plain-name fragment such as #pet is not a pointer. It used to resolve to root.et.

Tests

• removed-parts.test.ts, "handles references into query and additionalOperations in a single pass": counts reads of another path item. The count is 2 before this change and 1 after.
• removed-parts.test.ts, "leaves references to a query that the conversion keeps as written":
  • covers a paths extension, a Callback Object that is a Reference Object, a component named query and a file named query.yaml;
  • fails if the input walk is reduced to a plain isPathItemPointer check;
  • together with the test above, covers every new line and branch.
• New tests/validate.test.ts covers the oracle's pointer handling.

Verification

• Lint, types, tests: pnpm lint and pnpm type:check are clean; pnpm vitest run packages/downgrader passes (678 tests).
• Same outputs as main, on the test suite: I ran every input the suite passes to the downgrader through both this branch and main. All 829 outputs were identical, including key order.
• Same outputs as main, on generated documents: 3000 fuzzed 3.2 documents gave identical outputs from 3.2 → 3.1 and from 3.1 → 3.0. They are dense in references into query and additionalOperations and into documents that only look like Path Items. The same fuzzer flags 85% of documents when only the plain isPathItemPointer check is used, so it does detect differences.
• Speed: a 2000-path 3.2 document with one link into query goes from 84.0 ms to 36.0 ms. Without such a link it stays at 32.2 ms. On a document with 4000 distinct references the timings are unchanged, within noise.

References into fields that are dropped further down, such as a media type's itemSchema, still cost a second pass. They are out of scope here.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GZa6QbyudtUSAeHt5W2B8A

[pullfrog]

your Pullfrog Router balance is empty, and this repo has no provider key to fall back on, so the agent never ran.

To fix, any one of: add a payment method or top up your Router balance · add a provider API key (GitHub Actions secret or Pullfrog secret) · switch this repo to a free model.

Top up Router → · Model settings → · Setup docs → · Ask in Discord →

  ^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ 𝕏}

[dinwwwh]

The pullfrog check fails for a reason this PR can't fix. Its log says the Pullfrog Router balance is empty and the repo has no provider key, so the review agent never ran. #47 failed the same way at the same time while its other checks passed. I haven't re-run it, because a re-run would hit the same empty balance.

To get a Pullfrog review, a maintainer needs to top up the balance or add a provider key in the Pullfrog console. The check says it gates nothing unless branch protection requires it.

---

Generated by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[pullfrog]

your Pullfrog Router balance is empty, and this repo has no provider key to fall back on, so the agent never ran.

To fix, any one of: add a payment method or top up your Router balance · add a provider API key (GitHub Actions secret or Pullfrog secret) · switch this repo to a free model.

Top up Router → · Model settings → · Setup docs → · Ask in Discord →

  ^{｜ Rerun failed job ➔ ｜ View workflow run ｜ via Pullfrog ｜ 𝕏}

[codspeed]

Merging this PR will not alter performance

✅ 19 untouched benchmarks

---

_{Comparing claude/compassionate-mendel-ovhft1 (b338f98) with main (c4640c6)}