feat(downgrader): add @oasty/downgrader with 3.2-to-3.1 and 3.1-to-3.0 converters

[dinwwwh]

Adds the @oasty/downgrader package: it downgrades OpenAPI documents one minor version at a time (3.2 → 3.1 and 3.1 → 3.0), for whole documents or standalone Schema Objects. There is intentionally no direct 3.2 → 3.0 converter — the two steps compose. Converters never throw and never mutate their input: malformed parts pass through unchanged, existing x- extensions and unknown keys always survive, and unsupported constructs are converted where a real equivalent exists and removed otherwise — no invented x- keys.

Conversion behavior

• 3.2 → 3.1: components.mediaTypes references are inlined (entries with external/unknown/cyclic targets are removed — 3.1 content maps cannot hold references), streaming itemSchema becomes an array schema, response summary and example dataValue/serializedValue promote into their 3.1 slots when free; $self, server names, tag metadata, QUERY/additional operations, and querystring parameters (including references to them) are removed. Schema Objects pass through as-is — 3.2 keeps the 3.1 dialect and JSON Schema tolerates extra keywords.
• 3.1 → 3.0: type arrays become nullable, const becomes a single-value enum, numeric exclusive bounds become bound + flag with the tighter bound winning, boolean schemas and $ref-with-siblings get their 3.0 forms, and 3.0-required fields (paths, operation responses, array items) are synthesized so output validates.
• The README documents every rule and the known lossy limitations.

Testing

• 318 tests, 100% coverage (statements, branches, functions, lines); the corpus suites validate every input document and every converted hop against the official OpenAPI JSON Schemas, so valid-in -> valid-out is an asserted property.
• E2E and corpus suites validate every converted document against the official OpenAPI JSON Schemas via @seriousme/openapi-schema-validator: ~74 real fixture documents (OAI examples and schema-test corpus) are converted through each hop and must come out valid; petstore passes through 3.1 → 3.0 byte-identical apart from the version stamp.
• A multi-agent adversarial review ran against the final code; all confirmed findings are fixed (unresolvable content references now removed with exact cycle detection, no prototype-chain lookups, dangling querystring parameter references removed, synthesized array variants carry items) or documented.

Notes for review

• The corpus surfaced one upstream gap already landed separately: the 3.2 Media Type Object description field (fix(types): add description field to 3.2 MediaTypeObject #3).
• Published tarball now contains only unbuild output; tsc -b typecheck artifacts go to a separate gitignored directory.

[codecov]

Welcome to Codecov 🎉

Once you merge this PR into your default branch, you're all set! Codecov will compare coverage reports and display results in all future pull requests.

ℹ️ You can also turn on project coverage checks and project coverage reporting on Pull Request comment

Thanks for integrating Codecov - We've got you covered ☂️

[Copilot]

Pull request overview

Adds @oasty/downgrader for staged OpenAPI 3.2 → 3.1 → 3.0 conversion.

Changes:

• Implements defensive document and schema converters.
• Adds comprehensive unit, corpus, validation, and snapshot tests.
• Configures package publishing, type-checking, and dependencies.

Reviewed changes

Copilot reviewed 14 out of 15 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
package.json	Adds the schema validator dependency.
pnpm-lock.yaml	Locks new package and validator dependencies.
packages/downgrader/package.json	Defines package metadata, exports, and scripts.
packages/downgrader/tsconfig.json	Configures package type-check output.
packages/downgrader/README.md	Documents conversion rules and limitations.
packages/downgrader/src/index.ts	Exports the public converter APIs.
packages/downgrader/src/shared.ts	Adds defensive cloning and traversal utilities.
packages/downgrader/src/shared.test.ts	Tests shared utilities and cycle handling.
packages/downgrader/src/v3.1-to-v3.0.ts	Implements 3.1-to-3.0 conversion.
packages/downgrader/src/v3.1-to-v3.0.test.ts	Tests 3.1-to-3.0 behavior.
packages/downgrader/src/v3.2-to-v3.1.ts	Implements 3.2-to-3.1 conversion.
packages/downgrader/src/v3.2-to-v3.1.test.ts	Tests 3.2-to-3.1 behavior.
packages/downgrader/tests/corpus.test.ts	Validates fixture corpus conversions.
packages/downgrader/tests/e2e.test.ts	Tests complete chained conversions.
packages/downgrader/tests/__snapshots__/e2e.test.ts.snap	Records expected converted documents.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

Suppressed comments (1)

packages/downgrader/src/v3.1-to-v3.0.ts:207

• const and enum are conjunctive JSON Schema constraints, so replacing an existing enum changes valid schemas. For example, { const: 5, enum: [1, 2] } accepts nothing, but this emits { enum: [5] }, which accepts 5. Preserve the intersection: if the const is absent from the existing enum, emit the existing match-nothing 3.0 representation; otherwise narrowing to the const is safe.

  // `const` is a single-value `enum`.
  out.enum = [deepClone(schema.const)];
  if (schema.const === null) {
    out.nullable = true;
  }

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.