feat(openapi): modularize generator and hoist error schemas into components (#1721)

Resolves: #1355

## Summary

Rewrites the OpenAPI generator into small focused modules, hoists typed
error schemas into `components.schemas`, and brings every generator
module to 100% test coverage. The generator stays schema-library
agnostic: tests cover zod, arktype, and plain JSON schemas through
custom converters.

Error responses now reference named components derived from the error
code:

```yaml
"400":
  content:
    application/json:
      schema:
        oneOf:
          - $ref: '#/components/schemas/BadRequest'
          - $ref: '#/components/schemas/BadRequest2'
          - $ref: '#/components/schemas/UndefinedError'
```

## Changes

- Defined errors are hoisted into `#/components/schemas`, named after
their code (`BAD_REQUEST` -> `BadRequest`), with numbered postfixes on
conflicts and reuse of equal schemas across procedures.
- Fixed dangling `$defs` refs when local defs are referenced through
keywords like `patternProperties` or `contains`.
- Fixed component reuse when regenerating with a previously generated
document passed as `base`.
- Split the generator into `openapi-generator`,
`openapi-generator-operation`, and `openapi-generator-components`.
- Added `visitJsonSchemaRefs` to `@orpc/json-schema`, sharing traversal
rules with `mapJsonSchemaRefs` so ref discovery and rewriting cannot
drift.

## Tests

- One unit test file per module in `src/`, reaching 100% statement,
branch, function, and line coverage of all three generator modules from
unit tests alone.
- E2E tests in `packages/openapi/tests/openapi-generator/` organized
around end-user use cases: CRUD API, webhook with full HTTP control,
file upload and download, SSE streaming, typed errors, reusable
components, composed schemas, and schema library agnosticism (zod,
arktype, plain JSON schemas).

Author: dinwwwh

packages/json-schema/src/ref-utils.test.ts

@@ -1,5 +1,66 @@
 import type { JsonSchema } from './types'
-import { decodeJsonPointerSegment, encodeJsonPointerSegment, hoistRecursiveRefToDef, mapJsonSchemaRefs, resolveJsonSchemaRootLocalRef } from './ref-utils'
+import { decodeJsonPointerSegment, encodeJsonPointerSegment, hoistRecursiveRefToDef, mapJsonSchemaRefs, resolveJsonSchemaRootLocalRef, visitJsonSchemaRefs } from './ref-utils'
+
+describe('visitJsonSchemaRefs', () => {
+  it('visits refs under the same keywords mapJsonSchemaRefs rewrites, and skips non-schema keywords', () => {
+    const schema: JsonSchema = {
+      type: 'object',
+      properties: { child: { $ref: '#/$defs/A' } },
+      patternProperties: { '^x-': { $ref: '#/$defs/B' } },
+      propertyNames: { $ref: '#/$defs/C' },
+      dependentSchemas: { other: { $ref: '#/$defs/D' } },
+      contains: { $ref: '#/$defs/E' },
+      prefixItems: [{ $ref: '#/$defs/F' }],
+      not: { $ref: '#/$defs/G' },
+      if: { $ref: '#/$defs/H' },
+      then: { $ref: '#/$defs/I' },
+      else: { $ref: '#/$defs/J' },
+      items: { $ref: '#/$defs/K' },
+      additionalProperties: { $ref: '#/$defs/L' },
+      anyOf: [{ $ref: '#/$defs/M' }],
+      $defs: { Nested: { $ref: '#/$defs/N' } },
+      examples: [{ $ref: '#/$defs/Ignored' }],
+    }
+
+    const mapped: string[] = []
+    mapJsonSchemaRefs(schema, (ref) => {
+      mapped.push(ref)
+      return ref
+    })
+
+    const visited: string[] = []
+    visitJsonSchemaRefs(schema, ref => visited.push(ref))
+
+    expect(visited.sort()).toEqual(mapped.sort())
+    expect(visited).not.toContain('#/$defs/Ignored')
+    expect(visited.length).toBe(14)
+  })
+
+  it('visits shared and cyclic object instances once', () => {
+    const shared: JsonSchema = { $ref: '#/$defs/Shared' }
+    const cyclic: Record<string, unknown> = { type: 'object' }
+    cyclic.items = cyclic
+
+    const visited: string[] = []
+    visitJsonSchemaRefs({
+      type: 'object',
+      properties: {
+        a: shared,
+        b: shared,
+        c: cyclic as JsonSchema,
+      },
+    }, ref => visited.push(ref))
+
+    expect(visited).toEqual(['#/$defs/Shared'])
+  })
+
+  it('ignores non-object schemas', () => {
+    const visited: string[] = []
+    visitJsonSchemaRefs(true, ref => visited.push(ref))
+    visitJsonSchemaRefs(false, ref => visited.push(ref))
+    expect(visited).toEqual([])
+  })
+})
 
 describe('json pointer utils', () => {
   it('encodes and decodes JSON pointer segments', () => {

packages/json-schema/src/ref-utils.ts

@@ -25,6 +25,42 @@ export function decodeJsonPointerSegment(segment: string): string {
   return segment.replaceAll('~1', '/').replaceAll('~0', '~')
 }
 
+/**
+ * Visits every `$ref` in a schema, traversing the same keywords as {@link mapJsonSchemaRefs}.
+ * Shared or cyclic object instances are visited once.
+ */
+export function visitJsonSchemaRefs(
+  value: JsonSchema,
+  visit: (ref: string) => void,
+  schemaLevel = true,
+  seen = new Set<object>(),
+): void {
+  if (!value || typeof value !== 'object' || seen.has(value)) {
+    return
+  }
+
+  seen.add(value)
+
+  if (Array.isArray(value)) {
+    for (const item of value) {
+      visitJsonSchemaRefs(item, visit, schemaLevel, seen)
+    }
+    return
+  }
+
+  for (const [key, val] of Object.entries(value)) {
+    if (key === '$ref' && typeof val === 'string') {
+      visit(val)
+    }
+    else if (!schemaLevel) {
+      visitJsonSchemaRefs(val as JsonSchema, visit, true, seen)
+    }
+    else if (JSON_SCHEMA_LOGIC_KEYWORDS.has(key) || JSON_SCHEMA_RECORD_KEYWORDS.has(key)) {
+      visitJsonSchemaRefs(val as JsonSchema, visit, !JSON_SCHEMA_RECORD_KEYWORDS.has(key), seen)
+    }
+  }
+}
+
 export function mapJsonSchemaRefs(
   value: JsonSchema,
   map: (ref: string, path: Array<string | number>) => string,

packages/openapi/src/adapters/standard/openapi-handler-codec.test.ts

@@ -87,6 +87,29 @@ describe('openAPIHandlerCodec', () => {
         expect(resolveBody).not.toHaveBeenCalled()
       })
 
+      it('treats HEAD like GET, merging path params and query without reading the body', async () => {
+        const procedure = os
+          .meta(openapi({ method: 'HEAD', path: '/{id}' }))
+          .handler(vi.fn())
+        const codec = new OpenAPIHandlerCodec(procedure)
+        const resolveBody = vi.fn()
+
+        const result = await codec.resolveProcedure(createRequest({
+          method: 'HEAD',
+          url: '/42?verbose=true',
+          resolveBody,
+        }), options as any)
+
+        expect(result).toBeDefined()
+
+        await expect(result!.decodeInput()).resolves.toEqual({
+          id: '42',
+          verbose: 'true',
+        })
+
+        expect(resolveBody).not.toHaveBeenCalled()
+      })
+
       it('returns query directly when there are no path params', async () => {
         const procedure = os
           .meta(openapi({ method: 'GET', path: '/status' }))

packages/openapi/src/adapters/standard/openapi-handler-codec.ts

@@ -15,6 +15,7 @@ import {
 } from '../../constants'
 import { getOpenAPIMeta } from '../../meta'
 import { OpenAPISerializer } from '../../openapi-serializer'
+import { isBodylessMethod } from '../../utils'
 import { OpenAPIMatcher } from './openapi-matcher'
 
 export interface OpenAPIHandlerCodecCoreOptions<_T extends Context> {
@@ -27,7 +28,7 @@ export interface OpenAPIHandlerCodecCoreOptions<_T extends Context> {
    * Mapping ORPCError Code -> HTTP Status Code
    * The status code should be in the `4xx` or `5xx` range (must be greater than or equal to `400`).
    *
-   * @default COMMON_ERROR_STATUS_MAP, DEFAULT_ERROR_STATUS
+   * @default COMMON_ERROR_STATUS_MAP
    */
   errorStatusMap?: Record<string, number> | undefined
 
@@ -66,7 +67,7 @@ export class OpenAPIHandlerCodecCore<T extends Context> {
     const query = this.deserializeQuery(search, meta?.queryStyles)
 
     if (inputStructure === 'compact') {
-      const data = request.method === 'GET'
+      const data = isBodylessMethod(request.method)
         ? query
         : this.serializer.deserialize(await request.resolveBody(meta?.requestBodyHint))
 

packages/openapi/src/adapters/standard/openapi-link-codec.test.ts

@@ -50,6 +50,24 @@ describe('openAPILinkCodec', () => {
         })
       })
 
+      it('builds a HEAD request with query parameters and no body', async () => {
+        const codec = new OpenAPILinkCodec({
+          check: oc.meta(openapi({ method: 'HEAD', path: '/items/{id}' })),
+        }, {
+          url: '/api',
+          serializer,
+        })
+
+        const request = await codec.encodeInput({ id: '42', verbose: true }, ['check'], { context: {} })
+
+        expect(request.method).toBe('HEAD')
+        expect(request.body).toBeUndefined()
+
+        const url = new URL(request.url, 'http://localhost')
+        expect(url.pathname).toBe('/api/items/42')
+        expect(url.searchParams.get('verbose')).toBe('true')
+      })
+
       it('builds a GET request with a prefixed path and mixed query styles', async () => {
         const codec = new OpenAPILinkCodec({
           item: oc.meta(openapi({

packages/openapi/src/adapters/standard/openapi-link-codec.ts

@@ -17,7 +17,7 @@ import {
 } from '../../constants'
 import { getOpenAPIMeta } from '../../meta'
 import { OpenAPISerializer } from '../../openapi-serializer'
-import { getDynamicPathParams } from '../../utils'
+import { getDynamicPathParams, isBodylessMethod } from '../../utils'
 
 export class OpenAPILinkCodecError extends TypeError {}
 
@@ -112,7 +112,7 @@ export class OpenAPILinkCodec<T extends ClientContext> implements StandardLinkCo
 
       pathname = `${basePathname.replace(END_SLASH_REGEX, '')}${pathname}` as `/${string}`
 
-      if (method === 'GET') {
+      if (isBodylessMethod(method)) {
         const queryString = this.serializeQueryString(data, meta?.queryStyles)
         const search = combineSearch(baseSearch, queryString)
         const url = `${pathname}${search ?? ''}${baseHash ?? ''}` as StandardUrl
@@ -175,7 +175,7 @@ export class OpenAPILinkCodec<T extends ClientContext> implements StandardLinkCo
     const search = combineSearch(baseSearch, queryString)
     const url = `${pathname}${search ?? ''}${baseHash ?? ''}` as StandardUrl
 
-    if (method === 'GET') {
+    if (isBodylessMethod(method)) {
       return {
         body: undefined,
         method,