OpenAPI 3.2: Add regression tests for $self document identity and $ref resolution

[Copilot]

OpenAPI 3.2's $self field declares a document's canonical URI, which acts as the base for resolving relative $ref values. This was untested — adding coverage to confirm @apidevtools/json-schema-ref-parser passes $self through unchanged and that relative $ref resolution is unaffected.

Summary

No production code changes were needed. Three regression tests verify the behavior end-to-end:

• specification.test.ts — Specification.fromFile() on a spec with $self and a relative $ref preserves $self verbatim and resolves the referenced schema correctly
• openapi-middleware.test.ts — The served document retains $self and has external $refs fully inlined by bundle()
• generate.test.ts — Code generation from a $self-declaring spec with relative $refs completes without error and produces route files

Each test creates a two-file spec: a root openapi.yaml with $self: 'https://example.com/openapi.yaml' and a relative $ref to components/pet.yaml.

Original Prompt

OpenAPI 3.2 introduces a top-level $self field that allows an OpenAPI document to declare its own canonical URI. This URI is used as the base when resolving relative $ref values, which is especially important for multi-file specs.

Current state: Counterfact uses @apidevtools/json-schema-ref-parser for bundling, which already handles base-URI resolution. The $self field is likely passed through without issue, but this has not been explicitly verified.

Proposed changes:

• Confirm that the spec loader in src/typescript-generator/specification.ts and src/server/openapi-middleware.ts does not strip or misinterpret $self when bundling
• Add a regression test with a spec that declares $self and uses relative $ref values to verify that references resolve to the correct schemas

Manual acceptance tests

• A spec with $self declared loads without errors via Specification.fromFile()
• $self value is preserved verbatim in the bundled document
• Relative $ref values in a spec with $self resolve to the correct schemas after bundling
• The OpenAPI middleware serves a spec with $self without error, and external $refs are fully inlined
• Code generation from a spec with $self and relative $refs produces valid TypeScript output without errors

Tasks

• Added specification.test.ts: verifies $self preserved + relative $ref resolves to correct schema type via Requirement traversal
• Added openapi-middleware.test.ts: verifies $self in served YAML and schema.$ref is undefined / schema.type is "object" after bundling
• Added generate.test.ts: verifies CodeGenerator succeeds and emits a route file for a $self-declaring spec with external schema ref
• Added changeset (patch)
• Resolved merge conflict in specification.test.ts — preserved both the new $self test and the components/mediaTypes tests merged from main

[pmcelhaney]

@copilot resolve the merge conflicts in this pull request

[Copilot]

@copilot resolve the merge conflicts in this pull request

Done — resolved in 7476cd5. specification.test.ts had a conflict between the $self test I added and the components/mediaTypes tests from main. Kept both sets of tests; all 27 tests pass.