@kubb/adapter-oas 5.0.0-beta.37 → 5.0.0-beta.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/adapter-oas",
-  "version": "5.0.0-beta.37",
+  "version": "5.0.0-beta.39",
   "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",
@@ -47,7 +47,7 @@
     "oas": "^32.1.18",
     "oas-normalize": "^16.0.4",
     "swagger2openapi": "^7.0.8",
-    "@kubb/core": "5.0.0-beta.37"
+    "@kubb/core": "5.0.0-beta.39"
   },
   "devDependencies": {
     "@types/swagger2openapi": "^7.0.4",

package/src/adapter.ts

@@ -1,4 +1,3 @@
-import { once } from '@internals/utils'
 import { ast, createAdapter } from '@kubb/core'
 import type { AdapterSource } from '@kubb/core'
 import BaseOas from 'oas'
@@ -68,39 +67,83 @@ export const adapterOas = createAdapter<AdapterOas>((options) => {
   let nameMapping = new Map<string, string>()
   let parsedDocument: Document | null = null
 
-  // `once` collapses concurrent callers (e.g. a build's `stream()` racing with `openInStudio()`'s `parse()`) onto one in-flight promise.
-  const ensureDocument = once(async (source: AdapterSource): Promise<Document> => {
-    const fresh = await parseFromConfig(source)
-    if (validate) await validateDocument(fresh)
-    parsedDocument = fresh
-    return fresh
-  })
-
-  const ensureSchemas = once(async (document: Document) => {
-    const result = getSchemas(document, { contentType })
-    nameMapping = result.nameMapping
-    return result.schemas
-  })
-
-  const ensureBaseOas = once((document: Document) => new BaseOas(document))
-
-  const ensureSchemaParser = once((document: Document) => createSchemaParser({ document, contentType }))
-
-  const ensurePreScan = once(
-    (
-      schemas: Awaited<ReturnType<typeof ensureSchemas>>,
-      parseSchema: ReturnType<typeof ensureSchemaParser>['parseSchema'],
-      parseOperation: ReturnType<typeof ensureSchemaParser>['parseOperation'],
-      baseOas: ReturnType<typeof ensureBaseOas>,
-    ) => preScan({ schemas, parseSchema, parseOperation, baseOas, parserOptions, discriminator, dedupe }),
-  )
+  // Cache per source and per document so one adapter instance reused across a `defineConfig` array
+  // parses each config's spec instead of replaying the first one. Keying the document by its source
+  // object still collapses a config's concurrent `stream()` (build) and `parse()` (studio) calls,
+  // which share one source object, onto a single parse. The document-derived caches key off the
+  // resulting document, so distinct configs (distinct documents) stay isolated.
+  const documentCache = new WeakMap<AdapterSource, Promise<Document>>()
+  const schemasCache = new WeakMap<Document, Promise<ReturnType<typeof getSchemas>['schemas']>>()
+  const baseOasCache = new WeakMap<Document, BaseOas>()
+  const schemaParserCache = new WeakMap<Document, ReturnType<typeof createSchemaParser>>()
+  const preScanCache = new WeakMap<Document, ReturnType<typeof preScan>>()
+
+  function ensureDocument(source: AdapterSource): Promise<Document> {
+    const cached = documentCache.get(source)
+    if (cached) return cached
+
+    const promise = (async () => {
+      const fresh = await parseFromConfig(source)
+      if (validate) await validateDocument(fresh)
+      parsedDocument = fresh
+      return fresh
+    })()
+    documentCache.set(source, promise)
+    return promise
+  }
+
+  function ensureSchemas(document: Document): Promise<ReturnType<typeof getSchemas>['schemas']> {
+    const cached = schemasCache.get(document)
+    if (cached) return cached
+
+    const promise = Promise.resolve().then(() => {
+      const result = getSchemas(document, { contentType })
+      nameMapping = result.nameMapping
+      return result.schemas
+    })
+    schemasCache.set(document, promise)
+    return promise
+  }
+
+  function ensureBaseOas(document: Document): BaseOas {
+    const cached = baseOasCache.get(document)
+    if (cached) return cached
+
+    const baseOas = new BaseOas(document)
+    baseOasCache.set(document, baseOas)
+    return baseOas
+  }
+
+  function ensureSchemaParser(document: Document): ReturnType<typeof createSchemaParser> {
+    const cached = schemaParserCache.get(document)
+    if (cached) return cached
+
+    const parser = createSchemaParser({ document, contentType })
+    schemaParserCache.set(document, parser)
+    return parser
+  }
+
+  function ensurePreScan(
+    document: Document,
+    schemas: ReturnType<typeof getSchemas>['schemas'],
+    parseSchema: ReturnType<typeof ensureSchemaParser>['parseSchema'],
+    parseOperation: ReturnType<typeof ensureSchemaParser>['parseOperation'],
+    baseOas: BaseOas,
+  ): ReturnType<typeof preScan> {
+    const cached = preScanCache.get(document)
+    if (cached) return cached
+
+    const result = preScan({ schemas, parseSchema, parseOperation, baseOas, parserOptions, discriminator, dedupe })
+    preScanCache.set(document, result)
+    return result
+  }
 
   async function createStream(source: AdapterSource): Promise<ast.InputStreamNode> {
     const document = await ensureDocument(source)
     const schemas = await ensureSchemas(document)
     const { parseSchema, parseOperation } = ensureSchemaParser(document)
     const baseOas = ensureBaseOas(document)
-    const { refAliasMap, enumNames, circularNames, discriminatorChildMap, dedupePlan } = ensurePreScan(schemas, parseSchema, parseOperation, baseOas)
+    const { refAliasMap, enumNames, circularNames, discriminatorChildMap, dedupePlan } = ensurePreScan(document, schemas, parseSchema, parseOperation, baseOas)
 
     return createInputStream({
       schemas,

package/src/factory.ts

@@ -1,6 +1,6 @@
 import path from 'node:path'
 import { exists, mergeDeep, URLPath } from '@internals/utils'
-import { diagnosticCode, DiagnosticError } from '@kubb/core'
+import { Diagnostics } from '@kubb/core'
 import type { AdapterSource } from '@kubb/core'
 import { bundle, loadConfig } from '@redocly/openapi-core'
 import OASNormalize from 'oas-normalize'
@@ -78,8 +78,8 @@ export async function mergeDocuments(pathOrApi: Array<string | Document>): Promi
   const documents = await Promise.all(pathOrApi.map((p) => parseDocument(p, { enablePaths: false, canBundle: false })))
 
   if (documents.length === 0) {
-    throw new DiagnosticError({
-      code: diagnosticCode.inputRequired,
+    throw new Diagnostics.Error({
+      code: Diagnostics.code.inputRequired,
       severity: 'error',
       message: 'No OAS documents were provided for merging.',
       help: 'Pass at least one path or document to `input.path`.',
@@ -149,8 +149,8 @@ export async function assertInputExists(input: string): Promise<void> {
     return
   }
   if (!(await exists(input))) {
-    throw new DiagnosticError({
-      code: diagnosticCode.inputNotFound,
+    throw new Diagnostics.Error({
+      code: Diagnostics.code.inputNotFound,
       severity: 'error',
       message: `Cannot read the file set in \`input.path\` (or via \`kubb generate PATH\`): ${input}`,
       help: 'Check that the path exists and is readable, then set it in `input.path` or pass it as `kubb generate PATH`.',

package/src/refs.ts

@@ -1,4 +1,4 @@
-import { type Diagnostic, diagnosticCode, Diagnostics } from '@kubb/core'
+import { type Diagnostic, Diagnostics } from '@kubb/core'
 import { isReference } from './guards.ts'
 import type { Document } from './types.ts'
 
@@ -41,15 +41,18 @@ export function resolveRef<T = unknown>(document: Document, $ref: string): T | n
 
   if (!current) {
     const diagnostic: Diagnostic = {
-      code: diagnosticCode.refNotFound,
+      code: Diagnostics.code.refNotFound,
       severity: 'error',
       message: `Could not find a definition for ${origRef}.`,
       help: 'Add the schema under `components.schemas`, or fix the `$ref`. Run `kubb validate` to check the spec.',
       location: { kind: 'schema', pointer: origRef, ref: origRef },
     }
     // Report the unresolved ref into the active build and resolve to null, like any
-    // other unresolvable ref. The build collects it and keeps going.
-    Diagnostics.report(diagnostic)
+    // other unresolvable ref. The build collects it and keeps going. Outside a build there is no
+    // sink, so throw rather than silently returning null.
+    if (!Diagnostics.report(diagnostic)) {
+      throw new Diagnostics.Error(diagnostic)
+    }
     return null
   }
 

package/src/resolvers.ts

@@ -1,5 +1,5 @@
 import { pascalCase } from '@internals/utils'
-import { diagnosticCode, DiagnosticError } from '@kubb/core'
+import { Diagnostics } from '@kubb/core'
 import type { ast } from '@kubb/core'
 import type { ParameterObject, ServerObject } from 'oas/types'
 import { isRef } from 'oas/types'
@@ -36,8 +36,8 @@ export function resolveServerUrl(server: ServerObject, overrides?: Record<string
     }
 
     if (variable.enum?.length && !variable.enum.some((e) => String(e) === value)) {
-      throw new DiagnosticError({
-        code: diagnosticCode.invalidServerVariable,
+      throw new Diagnostics.Error({
+        code: Diagnostics.code.invalidServerVariable,
         severity: 'error',
         message: `Invalid server variable value '${value}' for '${key}' when resolving ${server.url}. Valid values are: ${variable.enum.join(', ')}.`,
         help: `Use one of the allowed enum values, or drop the enum on the '${key}' server variable.`,

package/src/schemaDiagnostics.ts

@@ -1,4 +1,4 @@
-import { diagnosticCode, Diagnostics } from '@kubb/core'
+import { Diagnostics } from '@kubb/core'
 import type { ast } from '@kubb/core'
 import { isHandledFormat } from './resolvers.ts'
 
@@ -11,13 +11,21 @@ import { isHandledFormat } from './resolvers.ts'
  * no-op outside one, and repeats are deduped by the build.
  */
 export function reportSchemaDiagnostics({ node, name }: { node: ast.SchemaNode; name: string }): void {
-  visit(node, `#/components/schemas/${name}`)
+  visit(node, `#/components/schemas/${escapePointerToken(name)}`)
+}
+
+/**
+ * Escapes a single JSON pointer reference token per RFC 6901 (`~` → `~0`, `/` → `~1`), so a
+ * property name with those characters maps to a distinct pointer instead of colliding in the dedupe.
+ */
+function escapePointerToken(token: string): string {
+  return token.replace(/~/g, '~0').replace(/\//g, '~1')
 }
 
 function visit(node: ast.SchemaNode, pointer: string): void {
   if (node.deprecated) {
     Diagnostics.report({
-      code: diagnosticCode.deprecated,
+      code: Diagnostics.code.deprecated,
       severity: 'info',
       message: 'This schema is marked as deprecated.',
       location: { kind: 'schema', pointer },
@@ -26,7 +34,7 @@ function visit(node: ast.SchemaNode, pointer: string): void {
 
   if (typeof node.format === 'string' && !isHandledFormat(node.format)) {
     Diagnostics.report({
-      code: diagnosticCode.unsupportedFormat,
+      code: Diagnostics.code.unsupportedFormat,
       severity: 'warning',
       message: `Kubb does not map the format "${node.format}" to a specific type, so it falls back to the base type.`,
       help: `Use a format Kubb supports, or handle "${node.format}" with a custom parser or plugin.`,
@@ -36,7 +44,7 @@ function visit(node: ast.SchemaNode, pointer: string): void {
 
   if (node.type === 'object') {
     for (const property of node.properties) {
-      visit(property.schema, `${pointer}/properties/${property.name}`)
+      visit(property.schema, `${pointer}/properties/${escapePointerToken(property.name)}`)
     }
     if (node.additionalProperties && typeof node.additionalProperties === 'object') {
       visit(node.additionalProperties, `${pointer}/additionalProperties`)
@@ -44,16 +52,25 @@ function visit(node: ast.SchemaNode, pointer: string): void {
     return
   }
 
-  if (node.type === 'array' || node.type === 'tuple') {
+  if (node.type === 'array') {
     for (const item of node.items ?? []) {
       visit(item, `${pointer}/items`)
     }
     return
   }
 
+  if (node.type === 'tuple') {
+    // Each tuple position has its own pointer, so index them. A shared `/items` would collapse
+    // distinct diagnostics in the dedupe.
+    for (const [index, item] of (node.items ?? []).entries()) {
+      visit(item, `${pointer}/items/${index}`)
+    }
+    return
+  }
+
   if (node.type === 'union' || node.type === 'intersection') {
-    for (const member of node.members ?? []) {
-      visit(member, pointer)
+    for (const [index, member] of (node.members ?? []).entries()) {
+      visit(member, `${pointer}/members/${index}`)
     }
   }
 }