refactor(downgrader): simplify converters, tests, and fixtures

[dinwwwh]

Cleanup pass over the downgrader package, prompted by checking that the OpenAPI 3.2 query operation is covered (it is, in the types, the converter, and the tests). The converters lose comments that restated the code, the tests lose duplicated helpers and blanket casts, and the shared fixtures become typed exports that tests consume without casts. Conversion behaviour is unchanged.

Source

• UnknownRecord alias removed in favour of the inline type.
• HTTP_METHODS is now HTTP_METHODS_UP_TO_V31, making explicit that 3.2 adds query on top of the list.
• Comments that restated adjacent code are gone; spec rationale and cast justifications stay. Module headers point at the README for the mapping tables instead of duplicating them.
• convertSchema sits below its field table, so the no-use-before-define suppression is gone; the remaining arrow-function consts are function declarations.

Tests

• dig and expectValidAs live in one tests/helpers.ts instead of three copies.
• Fixture exports are export const doc: OpenAPIObject rather than satisfies, so they keep the real type and pass into the converters directly. This also fixes the tictactoe fixture, whose security union TypeScript widened into a shape the index signature rejected.
• as any remains only on deliberately malformed inputs: junk values, missing required fields, and wrong-version documents.

Testing

• pnpm lint, pnpm type:check, and pnpm test pass (327 tests).

[pullfrog]

✅ No new issues found.

Reviewed changes

• Converter source cleanup — UnknownRecord inlined to Record<string, unknown> throughout shared.ts and both converters; HTTP_METHODS renamed HTTP_METHODS_UP_TO_V31; convertSchema moved below the SCHEMA_FIELDS table so the no-use-before-define suppression is gone; convertSubschemas/convertContent/convertResponses arrow-consts became function declarations; convertParameterList inlined at its two call sites. I diffed the converter sources base→head directly: the changes are mechanical (moves, renames, comment deletions), no behavioral drift.
• Doc comment trim — the removed comments restated code or duplicated the README; I checked that the README's mapping tables cover every construct the trimmed module headers now defer to.
• Test helper consolidation — the three duplicated copies of dig/expectValidAs/validate merged into tests/helpers.ts; as any survives only on deliberately malformed inputs (non-objects, missing-required-field docs, 3.2-only fields fed to the 3.1→3.0 hop), matching the PR's claim.
• Fixture typing — 82 fixtures flip from satisfies OpenAPIObject to : OpenAPIObject, letting the corpus/e2e tests pass them straight into the converters. The tictactoe fix is real and I reproduced it: with satisfies, security: [{ defaultApiKey: [] }, { app2AppOauth: ['board:read'] }] infers a union whose members get ?: undefined normalized twins, which the [name: string]: string[] index signature rejects — the annotation contextually types the literal and avoids that union. Excess-property checking still applies to the annotated literals, so the fixtures keep rejecting disallowed properties.

Verified locally: pnpm type:check, pnpm lint, and pnpm test (327 tests, including the snapshot-pinned converter outputs and the 72 corpus round-trips) all pass; the corpus fixture lists are unchanged (36 + 36 entries).

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

[pullfrog]

✅ No new issues found.

Reviewed changes (delta since the prior pullfrog review of 1141c4c)

• Merge of origin/main into the branch (e984453) — no downgrader or types content changed; the merge brings main in cleanly.
• Workflow whitespace trim (f2dcfb5) — .github/workflows/pullfrog.yml drops trailing spaces from two blank lines. Whitespace only, no behavioral surface.
• The other 92 files carry the same diff hashes as the previously reviewed commit; the full refactor stands as reviewed and passes pnpm type:check, pnpm lint, and all 327 tests.

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