test(downgrader): rewrite checks as end-to-end tests

[dinwwwh]

Rewrites the @openapi-spec/downgrader tests as end-to-end tests under packages/downgrader/tests/. Every test goes through the public package (@openapi-spec/downgrader) instead of the internals in src/shared.ts, and the suite alone keeps coverage at 100%. src/ is unchanged, and the snapshots of the official examples are byte-identical to the old ones.

Layout

• tests/v3.2-to-v3.1/ and tests/v3.1-to-v3.0/, one folder per downgrader, each split into:
  • schema/ for downgradeSchema*, one file per topic, such as type, numeric-bounds, loosening, or keywords
  • spec/ for downgradeSpec*, one file per topic, such as parameters, form-bodies, removed-parts, or corpus
• tests/chained.test.ts for the 3.2 → 3.1 → 3.0 chain the README describes. It sits at the root because it belongs to neither downgrader alone.
• Shared modules:
  • tests/corpus.ts lists the official documents once.
  • tests/validate.ts holds the official-schema checks, including expectValidDowngrade.
  • tests/helpers.ts holds dig and expectAcyclic.
  • Each folder has a schema/helpers.ts or spec/helpers.ts with its conversion helpers.

Changes

• Removes src/shared.test.ts, src/v3.1-to-v3.0.test.ts, src/v3.2-to-v3.1.test.ts, tests/e2e.test.ts, and tests/corpus.test.ts.
• Rewrites the engine behaviors the unit tests covered as tests on real documents and schemas: cloning, cycles and sharing, __proto__ keys, key order, long alias chains, and pointer decoding.
• Explains the tricky cases in comments with links to the OpenAPI 3.0.4, 3.1.2, and 3.2.0 specs, JSON Schema 2020-12, the official 3.0 schema, and the learn.openapis.org upgrade guides. Examples include the multipart application/octet-stream default, why not and oneOf are removed or relaxed after keywords are dropped, and why only the first inlined copy keeps its $id.
• Adds tests for cases nothing covered before:
  • input objects with a null prototype
  • an OAuth scheme whose only flow was the device flow
  • recursion reached through a percent-encoded pointer
  • a Path Item hop that its own $ref chain re-enters

Performance

The suite runs in about 5s instead of about 15s. The old helper built a new validator per check, which recompiled the official OpenAPI schema every time. One shared validator now serves the whole file.

Testing

• 540 tests in 40 files pass with 100% statement, branch, function, and line coverage of packages/downgrader/src, from these tests alone.
• Lint and type-check pass. With CI=true, no snapshots are written or left obsolete.
• The official corpus still has to downgrade to documents the official schemas accept, with no new dangling references and no change to the input.

Notes

• The hand-written "kitchen sink" 3.2 document now checks its 3.1 output with an exact toEqual instead of a snapshot. Its chained 3.0 snapshot was dropped; the official corpus, including the mega documents, still goes through the whole chain.
• Tests for behavior common to both converters, such as not changing the input and handling cycles, are repeated in each downgrader's folder, so each public function proves them on its own.
• spec.openapis.org could not be reached from the environment, so the section anchors in the comments were checked against the spec sources on GitHub.

🤖 Generated with Claude Code

https://claude.ai/code/session_018z4VMNTUoJPMp24y74NBMo

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[pullfrog]

✅ No new issues found.

Reviewed changes — a test-only reorganization of the downgrader suite; no src/ changes. I ran the suite (vitest run: 40 files / 540 tests pass), type:check, and eslint — all green.

• Five monoliths removed — src/shared.test.ts, src/v3.1-to-v3.0.test.ts, src/v3.2-to-v3.1.test.ts, tests/e2e.test.ts, and the old tests/corpus.test.ts, together with the old e2e/corpus snapshots.
• New per-concern suites added — tests/{v3.1-to-v3.0,v3.2-to-v3.1}/{spec,schema}/ split by version pair and spec-vs-schema, plus tests/chained.test.ts for the 3.2→3.1→3.0 chain.
• Shared test infrastructure — tests/corpus.ts now holds corpus data only; tests/validate.ts adds expectValidDowngrade, expectNoNewDanglingRefs, and a shared Validator; tests/helpers.ts keeps dig and adds expectAcyclic.
• Snapshots regenerated — keyed to the new test paths; committed snapshots are complete (no files written during the run, tree stays clean).

The new tests are a strict improvement in organization and generally in coverage: the old tests are re-expressed end-to-end with clearer intent, and edge cases such as pointer-token ownership (length, 00, -, __proto__), percent/tilde decoding, and cycle/fixpoint behavior are now pinned explicitly.

ℹ️ The src/shared.test.ts unit suite has no direct replacement

The 754-line unit suite for the engine primitives was deleted, and no test now imports shared.ts. Most of its behavior is re-covered through the public converters, but a few engine-level invariants (e.g. convertObject remembering a DROP result, releasing the cycle guard when a converter throws, and the clone/map/list/child/resolve/getRef/allOfItems/removedPrefixes contracts) are only exercised indirectly, if at all. Worth confirming the black-box approach is intended rather than an accidental loss.

Technical details

# Deleted `src/shared.test.ts` has no direct replacement

## Affected sites
- `packages/downgrader/src/shared.test.ts` — deleted in full; no new test imports `../src/shared` or `@openapi-spec/downgrader` internals.
- `packages/downgrader/tests/` — the new suite drives behavior only through `downgradeSpecV31ToV30` / `downgradeSpecV32ToV31` / `downgradeSchemaV*`.

## Required outcome
- Confirm that dropping direct unit coverage of `shared.ts` is intentional.
- If not, port the engine-invariant cases (error-path guard release, DROP memoization, `child` canonical-index rules) into a small `tests/shared.test.ts`; the `clone`/`map`/`list`/`resolve` edge cases that already have end-to-end equivalents can stay end-to-end.

## Open questions for the human
- Is the deliberate move to black-box-only testing of the engine, or should the primitive-level cases be retained?

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

[dinwwwh]

Re the Pullfrog note on src/shared.test.ts: dropping it is intentional. This PR's goal is to test only through the public package, and those tests alone cover 100% of statements and branches in shared.ts. The cases the note lists:

• DROP memoization and the child index rules are exercised through the converters. The index rules (length, 00, -, __proto__, inherited keys) are pinned in v3.1-to-v3.0/spec/removed-parts.test.ts.
• Releasing the cycle guard when a converter throws can't happen through the public API. The converters never throw, even on malformed input (they clone it through), and every call starts with a fresh context. So the old test only checked a scenario no caller can reach.

---

Generated by Claude Code