@kubb/adapter-oas 5.0.0-beta.61 → 5.0.0-beta.63

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-beta.61",
+  "version": "5.0.0-beta.63",
   "description": "OpenAPI and Swagger adapter for Kubb. Parses and validates OAS 2.0/3.x specifications into a @kubb/ast RootNode for downstream code generation plugins.",
   "keywords": [
     "adapter",
@@ -46,8 +46,8 @@
     "api-ref-bundler": "0.5.1",
     "swagger2openapi": "^7.0.8",
     "yaml": "^2.9.0",
-    "@kubb/ast": "5.0.0-beta.61",
-    "@kubb/core": "5.0.0-beta.61"
+    "@kubb/ast": "5.0.0-beta.63",
+    "@kubb/core": "5.0.0-beta.63"
   },
   "devDependencies": {
     "@types/json-schema": "^7.0.15",

package/src/adapter.ts

@@ -10,7 +10,7 @@ import { collect, narrowSchema } from '@kubb/ast'
 import { extractRefName } from '@kubb/ast/utils'
 
 /**
- * Canonical adapter name for `@kubb/adapter-oas`. Used for driver lookups.
+ * The `name` of `@kubb/adapter-oas`, used to identify this adapter in a Kubb config.
  */
 export const adapterOasName = 'oas' satisfies AdapterOas['name']
 

package/src/constants.ts

@@ -5,10 +5,9 @@ import { ast } from '@kubb/core'
  *
  * @example
  * ```ts
- * import { DEFAULT_PARSER_OPTIONS } from '@kubb/adapter-oas'
+ * import { DEFAULT_PARSER_OPTIONS, parseOas } from '@kubb/adapter-oas'
  *
- * const parser = createOasParser(oas)
- * const root = parser.parse({ ...DEFAULT_PARSER_OPTIONS, dateType: 'date' })
+ * const { root } = parseOas(document, { ...DEFAULT_PARSER_OPTIONS, dateType: 'date' })
  * ```
  */
 export const DEFAULT_PARSER_OPTIONS = {
@@ -68,13 +67,21 @@ export const MERGE_DEFAULT_VERSION = '1.0.0' as const
  */
 export const structuralKeys = new Set(['properties', 'items', 'additionalProperties', 'oneOf', 'anyOf', 'allOf', 'not'] as const)
 
+/**
+ * Formats `convertFormat` maps to a dedicated type without going through `formatMap`:
+ * `int64` and the date/time family. Keep this in sync with the `convertFormat`
+ * special-cases in `parser.ts`. `isHandledFormat` reads it so the
+ * `KUBB_UNSUPPORTED_FORMAT` diagnostic and the parser agree on what is handled.
+ */
+export const specialCasedFormats: ReadonlySet<string> = new Set(['int64', 'date-time', 'date', 'time'])
+
 /**
  * Static map from OAS `format` strings to Kubb `SchemaType` values.
  *
  * Only formats whose AST type differs from the OAS `type` field appear here.
- * Formats that depend on runtime options (`int64`, `date-time`, `date`, `time`) are handled separately
- * in the parser. `ipv4` and `ipv6` map to their own dedicated schema types. `hostname` and
- * `idn-hostname` map to `'url'` as the closest generic string-format type.
+ * Formats that depend on runtime options (`int64`, `date-time`, `date`, `time`) are handled
+ * separately in the parser. `ipv4` and `ipv6` map to their own dedicated schema types. `hostname`
+ * and `idn-hostname` map to `'url'` as the closest generic string-format type.
  *
  * @example
  * ```ts
@@ -85,14 +92,6 @@ export const structuralKeys = new Set(['properties', 'items', 'additionalPropert
  * formatMap['float']  // 'number'
  * ```
  */
-/**
- * Formats `convertFormat` maps to a dedicated type without going through `formatMap`:
- * `int64` and the date/time family. Keep this in sync with the `convertFormat`
- * special-cases in `parser.ts`. `isHandledFormat` reads it so the
- * `KUBB_UNSUPPORTED_FORMAT` diagnostic and the parser agree on what is handled.
- */
-export const specialCasedFormats: ReadonlySet<string> = new Set(['int64', 'date-time', 'date', 'time'])
-
 export const formatMap = {
   uuid: 'uuid',
   email: 'email',

package/src/dedupe.ts

@@ -0,0 +1,237 @@
+import { containsCircularRef, extractRefName } from '@kubb/ast/utils'
+import { ast } from '@kubb/core'
+import { SCHEMA_REF_PREFIX } from './constants.ts'
+
+/**
+ * The destination a deduplicated shape points at: the shared schema name and the
+ * synthetic `$ref` path stored on the generated `ref` nodes.
+ */
+type Target = {
+  name: string
+  ref: string
+}
+
+/**
+ * The result of {@link plan}: the shared definitions to prepend to the schema list, plus the
+ * rewriting behavior that repoints duplicate shapes at their shared target. The lookup maps stay
+ * private to the closure, so callers interact with one object instead of three collections.
+ */
+export type Plan = {
+  /**
+   * New top-level schema definitions created for inline shapes that had no existing named
+   * component. Nested duplicates inside each definition are already collapsed.
+   */
+  extracted: Array<ast.SchemaNode>
+  /**
+   * Rewrites an operation or nested schema, replacing every duplicate sub-schema with a `ref` to
+   * its shared target. Replacing a node prunes its subtree, so nested duplicates inside a replaced
+   * shape are not visited again. A `ref` to a duplicate top-level schema is repointed at the first
+   * schema with the same content.
+   */
+  apply<T extends ast.Node>(node: T): T
+  /**
+   * Rewrites a top-level schema. A schema whose content duplicates a different shared one becomes a
+   * `ref` alias to it (keeping its own name and docs). Otherwise its nested duplicates collapse
+   * while its own root is preserved.
+   */
+  applyTopLevel(node: ast.SchemaNode): ast.SchemaNode
+  /**
+   * Whether a top-level name duplicates an earlier schema with the same content. Such a schema is
+   * never emitted, since every reference to it is repointed at the first schema with that content.
+   */
+  isAlias(name: string): boolean
+}
+
+/**
+ * Runtime state {@link plan} reads from the current parse: schema names that take part in a
+ * circular chain (never extracted, extracting them would break the cycle) and the names already in
+ * use (so extracted definitions resolve collisions).
+ */
+export type DedupeContext = {
+  circularSchemas: ReadonlySet<string>
+  usedNames: Set<string>
+}
+
+/**
+ * Minimum occurrences before a shape is deduplicated.
+ */
+const MIN_OCCURRENCES = 2
+
+/**
+ * Builds the shared `ref` replacement for a duplicate occurrence, carrying the
+ * usage-slot and documentation fields that are not part of the shared type.
+ */
+function createRefNode(node: ast.SchemaNode, target: Target): ast.SchemaNode {
+  return ast.factory.createSchema({
+    type: 'ref',
+    name: target.name,
+    ref: target.ref,
+    optional: node.optional,
+    nullish: node.nullish,
+    readOnly: node.readOnly,
+    writeOnly: node.writeOnly,
+    deprecated: node.deprecated,
+    description: node.description,
+    default: node.default,
+    example: node.example,
+  })
+}
+
+/**
+ * Strips usage-slot flags from an extracted definition and applies its name.
+ * A standalone definition is never optional, so `optional`/`nullish` are cleared.
+ */
+function cleanDefinition(node: ast.SchemaNode, name: string): ast.SchemaNode {
+  return { ...node, name, optional: undefined, nullish: undefined }
+}
+
+/**
+ * Returns `true` when a node is eligible for deduplication. Only enums and objects qualify, and
+ * object shapes that take part in a circular chain are rejected so recursive structures are not
+ * extracted (which would break the cycle).
+ */
+function isCandidate(node: ast.SchemaNode, circularSchemas: ReadonlySet<string>): boolean {
+  if (node.type === 'enum') return true
+  if (node.type !== 'object') return false
+  if (node.name && circularSchemas.has(node.name)) return false
+  return !containsCircularRef(node, { circularSchemas })
+}
+
+/**
+ * Produces the name for an inline shape with no existing named component, resolving
+ * collisions against `usedNames`. Returns `null` for an unnamed shape, which stays inline.
+ */
+function nameFor(node: ast.SchemaNode, usedNames: Set<string>): string | null {
+  const base = node.name
+  if (!base) return null
+
+  let name = base
+  let counter = 2
+  while (usedNames.has(name)) {
+    name = `${base}${counter++}`
+  }
+  usedNames.add(name)
+  return name
+}
+
+/**
+ * Scans a forest of schema and operation nodes and produces a {@link Plan}.
+ *
+ * A shape that occurs at least {@link MIN_OCCURRENCES} times is deduplicated: if any occurrence is
+ * a named top-level schema, the first one becomes the target (so other top-level duplicates and
+ * inline copies turn into references to it). Other top-level names with the same content are
+ * recorded as aliases. Otherwise a new definition is extracted using {@link nameFor}. The returned
+ * plan rewrites nodes against those decisions.
+ *
+ * @example
+ * ```ts
+ * const dedupePlan = plan([...schemaNodes, ...operationNodes], { circularSchemas, usedNames })
+ * ```
+ */
+export function plan(roots: ReadonlyArray<ast.Node>, context: DedupeContext): Plan {
+  const { circularSchemas, usedNames } = context
+
+  const topLevelNodes = new Set<ast.SchemaNode>()
+
+  type Group = {
+    count: number
+    representative: ast.SchemaNode
+    topLevelNames: Array<string>
+  }
+  const groups = new Map<string, Group>()
+
+  for (const root of roots) {
+    if (root.kind === 'Schema') topLevelNodes.add(root)
+    for (const schemaNode of ast.collect<ast.SchemaNode>(root, { schema: (node) => node })) {
+      if (!isCandidate(schemaNode, circularSchemas)) continue
+
+      const signature = ast.signatureOf(schemaNode)
+      const isTopLevel = topLevelNodes.has(schemaNode) && !!schemaNode.name
+      const group = groups.get(signature)
+      if (group) {
+        group.count++
+        if (isTopLevel) group.topLevelNames.push(schemaNode.name!)
+      } else {
+        groups.set(signature, { count: 1, representative: schemaNode, topLevelNames: isTopLevel ? [schemaNode.name!] : [] })
+      }
+    }
+  }
+
+  const bySignature = new Map<string, Target>()
+  const byName = new Map<string, Target>()
+  const pendingExtractions: Array<{ name: string; representative: ast.SchemaNode }> = []
+
+  for (const [signature, group] of groups) {
+    if (group.count < MIN_OCCURRENCES) continue
+
+    const [firstName, ...duplicateNames] = group.topLevelNames
+    if (firstName) {
+      const target: Target = { name: firstName, ref: `${SCHEMA_REF_PREFIX}${firstName}` }
+      bySignature.set(signature, target)
+      for (const duplicate of duplicateNames) {
+        byName.set(duplicate, target)
+      }
+      continue
+    }
+
+    const name = nameFor(group.representative, usedNames)
+    if (!name) continue
+
+    bySignature.set(signature, { name, ref: `${SCHEMA_REF_PREFIX}${name}` })
+    pendingExtractions.push({ name, representative: group.representative })
+  }
+
+  // Rewrites a node against the resolved targets. `skipRootMatch` keeps a definition's own root from
+  // turning into a reference to itself. Nested duplicates are still collapsed.
+  function rewrite<T extends ast.Node>(node: T, skipRootMatch: boolean): T {
+    if (bySignature.size === 0 && byName.size === 0) return node
+
+    const root = node
+
+    return ast.transform(node, {
+      schema(schemaNode) {
+        if (schemaNode.type === 'ref') {
+          const refName = schemaNode.ref ? extractRefName(schemaNode.ref) : schemaNode.name
+          const target = refName ? byName.get(refName) : undefined
+
+          return target ? { ...schemaNode, name: target.name, ref: target.ref } : undefined
+        }
+
+        if (skipRootMatch && schemaNode === root) return undefined
+
+        const target = bySignature.get(ast.signatureOf(schemaNode))
+        if (!target) return undefined
+
+        return createRefNode(schemaNode, target)
+      },
+    }) as T
+  }
+
+  // Build extracted definitions only after every target name is known, so nested
+  // duplicates inside a definition also resolve to refs.
+  const extracted = pendingExtractions.map(({ name, representative }) => cleanDefinition(rewrite(representative, true), name))
+
+  return {
+    extracted,
+    apply<T extends ast.Node>(node: T): T {
+      return rewrite(node, false)
+    },
+    applyTopLevel(node: ast.SchemaNode): ast.SchemaNode {
+      const target = bySignature.get(ast.signatureOf(node))
+      if (target && target.name !== node.name) {
+        return ast.factory.createSchema({
+          type: 'ref',
+          name: node.name ?? null,
+          ref: target.ref,
+          description: node.description,
+          deprecated: node.deprecated,
+        })
+      }
+
+      return rewrite(node, true)
+    },
+    isAlias(name: string): boolean {
+      return byName.has(name)
+    },
+  }
+}

package/src/dialect.ts

@@ -1,4 +1,5 @@
 import { ast } from '@kubb/core'
+import { plan } from './dedupe.ts'
 import { isDiscriminator, isNullable, isReference } from './guards.ts'
 import { resolveRef } from './refs.ts'
 import type { SchemaObject } from './types.ts'
@@ -22,13 +23,16 @@ import type { SchemaObject } from './types.ts'
  * const parser = createSchemaParser(context, oasDialect) // explicit
  * ```
  */
-export const oasDialect = ast.defineSchemaDialect({
+export const oasDialect = ast.defineDialect({
   name: 'oas',
-  isNullable,
-  isReference,
-  isDiscriminator,
-  isBinary: (schema: SchemaObject) => schema.type === 'string' && schema.contentMediaType === 'application/octet-stream',
-  resolveRef,
+  schema: {
+    isNullable,
+    isReference,
+    isDiscriminator,
+    isBinary: (schema: SchemaObject) => schema.type === 'string' && schema.contentMediaType === 'application/octet-stream',
+    resolveRef,
+  },
+  dedupe: { plan },
 })
 
 /**

package/src/discriminator.ts

@@ -7,7 +7,7 @@ export type DiscriminatorTarget = {
 }
 
 /**
- * Builds a map of child schema names → discriminator patch data by scanning the given
+ * Maps each child schema name to its discriminator patch data by scanning the given
  * top-level AST schema nodes for union schemas that carry a `discriminatorPropertyName`.
  *
  * The streaming path calls this on a small pre-parsed subset of schemas (only the

package/src/factory.ts

@@ -18,7 +18,7 @@ export type ValidateDocumentOptions = {
 }
 
 /**
- * Loads and dereferences an OpenAPI document, returning the raw `Document`.
+ * Loads and bundles an OpenAPI document, returning the raw `Document`.
  *
  * Accepts a file path string or an already-parsed document object. File paths and URLs are
  * bundled via `api-ref-bundler`, hoisting external file schemas into named `components.schemas`

package/src/mime.ts

@@ -1,9 +1,8 @@
 /**
  * MIME type fragments that mark a media type as JSON-like.
  *
- * Matches the substrings used by the `oas` library's `matchesMimeType.json`, so a content type is
- * JSON when it contains any of these. The `+json` entry catches structured-syntax suffixes such as
- * `application/vnd.api+json`.
+ * A content type is JSON when it contains any of these substrings. The `+json` entry catches
+ * structured-syntax suffixes such as `application/vnd.api+json`.
  */
 const jsonMimeFragments = ['application/json', 'application/x-json', 'text/json', 'text/x-json', '+json'] as const
 

package/src/operation.ts

@@ -125,8 +125,8 @@ export function getRequestContent({
 }
 
 /**
- * Returns the primary request content type. Prefers a JSON-like media type (the last one wins,
- * matching the previous behavior), then the first declared one, defaulting to `'application/json'`.
+ * Returns the primary request content type. Prefers a JSON-like media type (the last one wins
+ * when several are declared), then the first declared one, defaulting to `'application/json'`.
  */
 export function getRequestContentType({ document, operation }: OperationContext): string {
   const content = getRequestBodyContent({ document, operation })

package/src/parser.ts

@@ -20,6 +20,7 @@ import {
   getSchemaType,
 } from './resolvers.ts'
 import type { ContentType, Document, Operation, ReferenceObject, SchemaObject } from './types.ts'
+import type { StatusCode } from '@kubb/ast'
 
 /**
  * Parser context holding the raw OpenAPI document and optional content-type override.
@@ -101,6 +102,22 @@ function normalizeArrayEnum(schema: SchemaObject): SchemaObject {
   return { ...schemaWithoutEnum, items: normalizedItems } as SchemaObject
 }
 
+/**
+ * Builds a `null` scalar node carrying the schema's documentation. Shared by the `const: null`
+ * and the drf-spectacular `NullEnum` (`{ enum: [null] }`) branches, which render identically.
+ */
+function createNullSchema(schema: SchemaObject, name: string | null | undefined): ast.SchemaNode {
+  return ast.factory.createSchema({
+    type: 'null',
+    primitive: 'null',
+    name,
+    title: schema.title,
+    description: schema.description,
+    deprecated: schema.deprecated,
+    format: schema.format,
+  })
+}
+
 /**
  * Names the inline enums on a property's schema, and on each item when the property is a tuple, from
  * the parent and property name. Wraps `macroEnumName` at the property construction site.
@@ -162,7 +179,7 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
     if (refPath && !resolvingRefs.has(refPath)) {
       if (!resolvedRefCache.has(refPath)) {
         try {
-          const referenced = dialect.resolveRef<SchemaObject>(document, refPath)
+          const referenced = dialect.schema.resolveRef<SchemaObject>(document, refPath)
           if (referenced) {
             resolvingRefs.add(refPath)
             resolvedSchema = parseSchema({ schema: referenced }, rawOptions)
@@ -223,13 +240,13 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
     }> = []
     const allOfMembers: Array<ast.SchemaNode> = (schema.allOf as Array<SchemaObject | ReferenceObject>)
       .filter((item) => {
-        if (!dialect.isReference(item) || !name) return true
-        const deref = dialect.resolveRef<SchemaObject>(document, item.$ref)
-        if (!deref || !dialect.isDiscriminator(deref)) return true
+        if (!dialect.schema.isReference(item) || !name) return true
+        const deref = dialect.schema.resolveRef<SchemaObject>(document, item.$ref)
+        if (!deref || !dialect.schema.isDiscriminator(deref)) return true
         const parentUnion = deref.oneOf ?? deref.anyOf
         if (!parentUnion) return true
         const childRef = `${SCHEMA_REF_PREFIX}${name}`
-        const inOneOf = parentUnion.some((oneOfItem) => dialect.isReference(oneOfItem) && oneOfItem.$ref === childRef)
+        const inOneOf = parentUnion.some((oneOfItem) => dialect.schema.isReference(oneOfItem) && oneOfItem.$ref === childRef)
         const inMapping = Object.values(deref.discriminator.mapping ?? {}).some((v) => v === childRef)
         if (inOneOf || inMapping) {
           const discriminatorValue = findDiscriminator(deref.discriminator.mapping, childRef)
@@ -253,9 +270,9 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
 
       if (missingRequired.length) {
         const resolvedMembers = (schema.allOf as Array<SchemaObject | ReferenceObject>).flatMap((item) => {
-          if (!dialect.isReference(item)) return [item as SchemaObject]
-          const deref = dialect.resolveRef<SchemaObject>(document, item.$ref)
-          return deref && !dialect.isReference(deref) ? [deref] : []
+          if (!dialect.schema.isReference(item)) return [item as SchemaObject]
+          const deref = dialect.schema.resolveRef<SchemaObject>(document, item.$ref)
+          return deref && !dialect.schema.isReference(deref) ? [deref] : []
         })
 
         for (const key of missingRequired) {
@@ -322,10 +339,10 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
     const strategy: 'one' | 'any' = schema.oneOf ? 'one' : 'any'
     const unionBase = {
       ...buildSchemaNode(schema, name, nullable, defaultValue),
-      discriminatorPropertyName: dialect.isDiscriminator(schema) ? schema.discriminator.propertyName : undefined,
+      discriminatorPropertyName: dialect.schema.isDiscriminator(schema) ? schema.discriminator.propertyName : undefined,
       strategy,
     }
-    const discriminator = dialect.isDiscriminator(schema) ? schema.discriminator : undefined
+    const discriminator = dialect.schema.isDiscriminator(schema) ? schema.discriminator : undefined
     const sharedPropertiesNode = schema.properties
       ? (() => {
           const { oneOf: _oneOf, anyOf: _anyOf, ...schemaWithoutUnion } = schema
@@ -338,7 +355,7 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
 
     if (sharedPropertiesNode || discriminator?.mapping) {
       const members = unionMembers.map((s) => {
-        const ref = dialect.isReference(s) ? s.$ref : undefined
+        const ref = dialect.schema.isReference(s) ? s.$ref : undefined
         const discriminatorValue = findDiscriminator(discriminator?.mapping, ref)
         const memberNode = parseSchema({ schema: s as SchemaObject, name }, rawOptions)
 
@@ -401,15 +418,7 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
     const constValue = schema.const
 
     if (constValue === null) {
-      return ast.factory.createSchema({
-        type: 'null',
-        primitive: 'null',
-        name,
-        title: schema.title,
-        description: schema.description,
-        deprecated: schema.deprecated,
-        format: schema.format,
-      })
+      return createNullSchema(schema, name)
     }
 
     const constPrimitive = getPrimitiveType(typeof constValue === 'number' ? 'number' : typeof constValue === 'boolean' ? 'boolean' : 'string')
@@ -528,15 +537,7 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
     // render as `never` (plugin-ts) / invalid `z.enum([])` (plugin-zod). Mirror the `const: null`
     // branch so it renders as a clean `null` (not `z.null().nullable()`).
     if (nullInEnum && filteredValues.length === 0) {
-      return ast.factory.createSchema({
-        type: 'null',
-        primitive: 'null',
-        name,
-        title: schema.title,
-        description: schema.description,
-        deprecated: schema.deprecated,
-        format: schema.format,
-      })
+      return createNullSchema(schema, name)
     }
 
     const enumNullable = nullable || nullInEnum || undefined
@@ -599,7 +600,7 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
       ? Object.entries(schema.properties).map(([propName, propSchema]) => {
           const required = Array.isArray(schema.required) ? schema.required.includes(propName) : !!schema.required
           const resolvedPropSchema = propSchema as SchemaObject
-          const propNullable = dialect.isNullable(resolvedPropSchema)
+          const propNullable = dialect.schema.isNullable(resolvedPropSchema)
 
           const resolvedChildName = childName(name, propName)
           const propNode = parseSchema({ schema: resolvedPropSchema, name: resolvedChildName }, rawOptions)
@@ -653,7 +654,7 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
       ...buildSchemaNode(schema, name, nullable, defaultValue),
     })
 
-    if (dialect.isDiscriminator(schema) && schema.discriminator.mapping) {
+    if (dialect.schema.isDiscriminator(schema) && schema.discriminator.mapping) {
       const discPropName = schema.discriminator.propertyName
       const values = Object.keys(schema.discriminator.mapping)
       const enumName = name ? enumPropName(name, discPropName, options.enumSuffix) : undefined
@@ -795,14 +796,14 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
    * match/convert/fall-through contract.
    */
   const schemaRules: Array<SchemaRule> = [
-    { name: 'ref', match: ({ schema }) => dialect.isReference(schema), convert: convertRef },
+    { name: 'ref', match: ({ schema }) => dialect.schema.isReference(schema), convert: convertRef },
     { name: 'allOf', match: ({ schema }) => !!schema.allOf?.length, convert: convertAllOf },
     { name: 'union', match: ({ schema }) => !!(schema.oneOf?.length || schema.anyOf?.length), convert: convertUnion },
     { name: 'const', match: ({ schema }) => 'const' in schema && schema.const !== undefined, convert: convertConst },
     { name: 'format', match: ({ schema }) => !!schema.format, convert: convertFormat },
     {
       name: 'blob',
-      match: ({ schema }) => dialect.isBinary(schema),
+      match: ({ schema }) => dialect.schema.isBinary(schema),
       convert: convertBlob,
     },
     { name: 'multi-type', match: ({ schema }) => Array.isArray(schema.type) && schema.type.length > 1, convert: convertMultiType },
@@ -848,7 +849,7 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
       return parseSchema({ schema: flattenedSchema, name }, rawOptions)
     }
 
-    const nullable = dialect.isNullable(schema) || undefined
+    const nullable = dialect.schema.isNullable(schema) || undefined
     const defaultValue = schema.default === null && nullable ? undefined : schema.default
     const type = Array.isArray(schema.type) ? schema.type[0] : schema.type
 
@@ -946,7 +947,7 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
     const keys: Array<string> = []
     for (const key in schema.properties) {
       const prop = schema.properties[key]
-      if (prop && !dialect.isReference(prop) && (prop as Record<string, unknown>)[flag]) {
+      if (prop && !dialect.schema.isReference(prop) && (prop as Record<string, unknown>)[flag]) {
         keys.push(key)
       }
     }
@@ -975,11 +976,11 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
       const schema = getRequestSchema(document, operation, { contentType: ct })
       if (!schema) return []
       return [
-        {
+        ast.factory.createContent({
           contentType: ct,
-          schema: ast.syncOptionality(parseSchema({ schema, name: requestBodyName }, options), requestBodyMeta.required),
+          schema: ast.optionality(parseSchema({ schema, name: requestBodyName }, options), requestBodyMeta.required),
           keysToOmit: collectPropertyKeysByFlag(schema, 'readOnly'),
-        },
+        }),
       ]
     })
 
@@ -1013,23 +1014,28 @@ export function createSchemaParser(ctx: OasParserContext, dialect: OasDialect =
       // Build one entry per declared response content type so plugins can union the variants.
       // When a global contentType is configured, restrict to that single type (mirrors requestBody).
       const responseContentTypes = ctx.contentType ? [ctx.contentType] : getResponseBodyContentTypes(document, operation, statusCode)
-      const content = responseContentTypes.map((contentType) => ({ contentType, ...parseEntrySchema(contentType) }))
+      const content = responseContentTypes.map((contentType) => ast.factory.createContent({ contentType, ...parseEntrySchema(contentType) }))
 
       // Body-less responses keep a single fallback entry so the response still resolves to a
       // (void/any) schema, matching how `requestBody` only carries schemas inside `content`.
       if (content.length === 0) {
-        content.push({ contentType: getRequestContentType({ document, operation }) || 'application/json', ...parseEntrySchema(ctx.contentType) })
+        content.push(
+          ast.factory.createContent({
+            contentType: getRequestContentType({ document, operation }) || 'application/json',
+            ...parseEntrySchema(ctx.contentType),
+          }),
+        )
       }
 
       return ast.factory.createResponse({
-        statusCode: statusCode as ast.StatusCode,
+        statusCode: statusCode as StatusCode,
         description,
         content,
       })
     })
 
     const pathItem = document.paths?.[operation.path]
-    const pathItemDoc = pathItem && !dialect.isReference(pathItem) ? (pathItem as { summary?: unknown; description?: unknown }) : undefined
+    const pathItemDoc = pathItem && !dialect.schema.isReference(pathItem) ? (pathItem as { summary?: unknown; description?: unknown }) : undefined
     const pickDoc = (key: 'summary' | 'description'): string | undefined => {
       const own = operation.schema[key]
       if (typeof own === 'string') return own

package/src/refs.ts

@@ -7,12 +7,13 @@ const _refCache = new WeakMap<Document, Map<string, unknown>>()
 /**
  * Resolves a local JSON pointer reference from a document.
  *
- * Accepts `#/...` refs. Returns `null` for empty or non-local refs.
- * Throws when the pointer cannot be resolved.
+ * Accepts `#/...` refs. Returns `null` for an empty or non-local ref. When the pointer cannot be
+ * resolved, reports a `refNotFound` diagnostic into the active build and returns `null`. Outside a
+ * build there is no sink to collect it, so it throws instead.
  *
  * @example
  * ```ts
- * resolveRef<SchemaObject>(document, '#/components/schemas/Pet') // SchemaObject | null
+ * resolveRef<SchemaObject>(document, '#/components/schemas/Pet')
  * ```
  */
 export function resolveRef<T = unknown>(document: Document, $ref: string): T | null {