@kubb/adapter-oas 5.0.0-beta.36 → 5.0.0-beta.38

package/dist/index.js

@@ -1,12 +1,145 @@
 import "./chunk-C0LytTxp.js";
-import path from "node:path";
-import { ast, createAdapter } from "@kubb/core";
+import { DiagnosticError, Diagnostics, ast, createAdapter, diagnosticCode } from "@kubb/core";
 import BaseOas from "oas";
+import path from "node:path";
+import { access } from "node:fs/promises";
 import { bundle, loadConfig } from "@redocly/openapi-core";
 import OASNormalize from "oas-normalize";
 import swagger2openapi from "swagger2openapi";
 import { isRef } from "oas/types";
 import { matchesMimeType } from "oas/utils";
+//#region src/constants.ts
+/**
+* Default parser options applied when no explicit options are provided.
+*
+* @example
+* ```ts
+* import { DEFAULT_PARSER_OPTIONS } from '@kubb/adapter-oas'
+*
+* const parser = createOasParser(oas)
+* const root = parser.parse({ ...DEFAULT_PARSER_OPTIONS, dateType: 'date' })
+* ```
+*/
+const DEFAULT_PARSER_OPTIONS = {
+	dateType: "string",
+	integerType: "bigint",
+	unknownType: "any",
+	emptySchemaType: "any",
+	enumSuffix: "enum"
+};
+/**
+* JSON-Pointer prefix for schemas declared under `components.schemas` in an OpenAPI document.
+*
+* Used when building or parsing `$ref` strings.
+*
+* @example
+* ```ts
+* `${SCHEMA_REF_PREFIX}Pet` // '#/components/schemas/Pet'
+* ```
+*/
+const SCHEMA_REF_PREFIX = "#/components/schemas/";
+/**
+* OpenAPI version string written into the stub document created during multi-spec merges.
+*/
+const MERGE_OPENAPI_VERSION = "3.0.0";
+/**
+* Fallback `info.title` placed in the stub document when merging multiple API files.
+*/
+const MERGE_DEFAULT_TITLE = "Merged API";
+/**
+* Fallback `info.version` placed in the stub document when merging multiple API files.
+*/
+const MERGE_DEFAULT_VERSION = "1.0.0";
+/**
+* Set of JSON Schema keywords that prevent a schema fragment from being inlined during `allOf` flattening.
+*
+* A fragment that contains any of these keys carries structural meaning of its own and must stay as a separate
+* intersection member rather than being merged into the parent.
+*
+* @example
+* ```ts
+* import { structuralKeys } from '@kubb/adapter-oas'
+*
+* const isStructural = Object.keys(fragment).some((key) => structuralKeys.has(key))
+* // true when fragment has e.g. 'properties' or 'oneOf'
+* ```
+*/
+const structuralKeys = new Set([
+	"properties",
+	"items",
+	"additionalProperties",
+	"oneOf",
+	"anyOf",
+	"allOf",
+	"not"
+]);
+/**
+* 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.
+*
+* @example
+* ```ts
+* import { formatMap } from '@kubb/adapter-oas'
+*
+* formatMap['uuid']   // 'uuid'
+* formatMap['binary'] // 'blob'
+* 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.
+*/
+const specialCasedFormats = new Set([
+	"int64",
+	"date-time",
+	"date",
+	"time"
+]);
+const formatMap = {
+	uuid: "uuid",
+	email: "email",
+	"idn-email": "email",
+	uri: "url",
+	"uri-reference": "url",
+	url: "url",
+	ipv4: "ipv4",
+	ipv6: "ipv6",
+	hostname: "url",
+	"idn-hostname": "url",
+	binary: "blob",
+	byte: "blob",
+	int32: "integer",
+	float: "number",
+	double: "number"
+};
+/**
+* Vendor extension keys that attach human-readable labels to enum values, checked in priority order.
+*
+* @example
+* ```ts
+* import { enumExtensionKeys } from '@kubb/adapter-oas'
+*
+* const key = enumExtensionKeys.find((k) => k in schema) // 'x-enumNames' | 'x-enum-varnames' | undefined
+* ```
+*/
+const enumExtensionKeys = ["x-enumNames", "x-enum-varnames"];
+/**
+* Maps `'any' | 'unknown' | 'void'` option strings to their `ScalarSchemaType` constant.
+* Replaces a plain object lookup with a `Map` for explicit key membership testing via `.has()`.
+*/
+const typeOptionMap = new Map([
+	["any", ast.schemaTypes.any],
+	["unknown", ast.schemaTypes.unknown],
+	["void", ast.schemaTypes.void]
+]);
+//#endregion
 //#region ../../internals/utils/src/casing.ts
 /**
 * Shared implementation for camelCase and PascalCase conversion.
@@ -71,6 +204,23 @@ function pascalCase(text, { isFile, prefix = "", suffix = "" } = {}) {
 	return toCamelOrPascal(`${prefix} ${text} ${suffix}`, true);
 }
 //#endregion
+//#region ../../internals/utils/src/fs.ts
+/**
+* Resolves to `true` when the file or directory at `path` exists.
+* Uses `Bun.file().exists()` when running under Bun, `fs.access` otherwise.
+*
+* @example
+* ```ts
+* if (await exists('./kubb.config.ts')) {
+*   const content = await read('./kubb.config.ts')
+* }
+* ```
+*/
+async function exists(path) {
+	if (typeof Bun !== "undefined") return Bun.file(path).exists();
+	return access(path).then(() => true, () => false);
+}
+//#endregion
 //#region ../../internals/utils/src/object.ts
 /**
 * Returns `true` when `value` is a plain (non-null, non-array) object.
@@ -105,30 +255,6 @@ function mergeDeep(target, source) {
 	return result;
 }
 //#endregion
-//#region ../../internals/utils/src/promise.ts
-/**
-* Returns a wrapper that caches the result of the first invocation and replays
-* it for every subsequent call, ignoring later arguments.
-*
-* Works for sync and async factories — for async, the cached value is the
-* promise itself, so concurrent callers share one in-flight execution and
-* cannot race each other.
-*
-* @example
-* ```ts
-* const loadDocument = once(async (path: string) => parse(await readFile(path)))
-* const a = loadDocument('./a.yaml') // parses
-* const b = loadDocument('./b.yaml') // returns the cached promise from the first call
-* ```
-*/
-function once(factory) {
-	let cache;
-	return (...args) => {
-		if (!cache) cache = { value: factory(...args) };
-		return cache.value;
-	};
-}
-//#endregion
 //#region ../../internals/utils/src/reserved.ts
 /**
 * JavaScript and Java reserved words.
@@ -379,126 +505,6 @@ var URLPath = class {
 	}
 };
 //#endregion
-//#region src/constants.ts
-/**
-* Default parser options applied when no explicit options are provided.
-*
-* @example
-* ```ts
-* import { DEFAULT_PARSER_OPTIONS } from '@kubb/adapter-oas'
-*
-* const parser = createOasParser(oas)
-* const root = parser.parse({ ...DEFAULT_PARSER_OPTIONS, dateType: 'date' })
-* ```
-*/
-const DEFAULT_PARSER_OPTIONS = {
-	dateType: "string",
-	integerType: "bigint",
-	unknownType: "any",
-	emptySchemaType: "any",
-	enumSuffix: "enum"
-};
-/**
-* JSON-Pointer prefix for schemas declared under `components.schemas` in an OpenAPI document.
-*
-* Used when building or parsing `$ref` strings.
-*
-* @example
-* ```ts
-* `${SCHEMA_REF_PREFIX}Pet` // '#/components/schemas/Pet'
-* ```
-*/
-const SCHEMA_REF_PREFIX = "#/components/schemas/";
-/**
-* OpenAPI version string written into the stub document created during multi-spec merges.
-*/
-const MERGE_OPENAPI_VERSION = "3.0.0";
-/**
-* Fallback `info.title` placed in the stub document when merging multiple API files.
-*/
-const MERGE_DEFAULT_TITLE = "Merged API";
-/**
-* Fallback `info.version` placed in the stub document when merging multiple API files.
-*/
-const MERGE_DEFAULT_VERSION = "1.0.0";
-/**
-* Set of JSON Schema keywords that prevent a schema fragment from being inlined during `allOf` flattening.
-*
-* A fragment that contains any of these keys carries structural meaning of its own and must stay as a separate
-* intersection member rather than being merged into the parent.
-*
-* @example
-* ```ts
-* import { structuralKeys } from '@kubb/adapter-oas'
-*
-* const isStructural = Object.keys(fragment).some((key) => structuralKeys.has(key))
-* // true when fragment has e.g. 'properties' or 'oneOf'
-* ```
-*/
-const structuralKeys = new Set([
-	"properties",
-	"items",
-	"additionalProperties",
-	"oneOf",
-	"anyOf",
-	"allOf",
-	"not"
-]);
-/**
-* 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.
-*
-* @example
-* ```ts
-* import { formatMap } from '@kubb/adapter-oas'
-*
-* formatMap['uuid']   // 'uuid'
-* formatMap['binary'] // 'blob'
-* formatMap['float']  // 'number'
-* ```
-*/
-const formatMap = {
-	uuid: "uuid",
-	email: "email",
-	"idn-email": "email",
-	uri: "url",
-	"uri-reference": "url",
-	url: "url",
-	ipv4: "ipv4",
-	ipv6: "ipv6",
-	hostname: "url",
-	"idn-hostname": "url",
-	binary: "blob",
-	byte: "blob",
-	int32: "integer",
-	float: "number",
-	double: "number"
-};
-/**
-* Vendor extension keys that attach human-readable labels to enum values, checked in priority order.
-*
-* @example
-* ```ts
-* import { enumExtensionKeys } from '@kubb/adapter-oas'
-*
-* const key = enumExtensionKeys.find((k) => k in schema) // 'x-enumNames' | 'x-enum-varnames' | undefined
-* ```
-*/
-const enumExtensionKeys = ["x-enumNames", "x-enum-varnames"];
-/**
-* Maps `'any' | 'unknown' | 'void'` option strings to their `ScalarSchemaType` constant.
-* Replaces a plain object lookup with a `Map` for explicit key membership testing via `.has()`.
-*/
-const typeOptionMap = new Map([
-	["any", ast.schemaTypes.any],
-	["unknown", ast.schemaTypes.unknown],
-	["void", ast.schemaTypes.void]
-]);
-//#endregion
 //#region src/guards.ts
 /**
 * Returns `true` when `doc` is a Swagger 2.0 document (no `openapi` key).
@@ -608,7 +614,13 @@ async function mergeDocuments(pathOrApi) {
 		enablePaths: false,
 		canBundle: false
 	})));
-	if (documents.length === 0) throw new Error("No OAS documents provided for merging.");
+	if (documents.length === 0) throw new DiagnosticError({
+		code: diagnosticCode.inputRequired,
+		severity: "error",
+		message: "No OAS documents were provided for merging.",
+		help: "Pass at least one path or document to `input.path`.",
+		location: { kind: "config" }
+	});
 	const seed = {
 		openapi: MERGE_OPENAPI_VERSION,
 		info: {
@@ -624,9 +636,9 @@ async function mergeDocuments(pathOrApi) {
 * Creates a `Document` from an `AdapterSource`.
 *
 * Handles all three source types:
-* - `{ type: 'path' }` — resolves and bundles a local file path or remote URL.
-* - `{ type: 'paths' }` — merges multiple file paths into a single document.
-* - `{ type: 'data' }` — parses an inline string (YAML/JSON) or raw object.
+* - `{ type: 'path' }` resolves and bundles a local file path or remote URL.
+* - `{ type: 'paths' }` merges multiple file paths into a single document.
+* - `{ type: 'data' }` parses an inline string (YAML/JSON) or raw object.
 *
 * @example
 * ```ts
@@ -634,14 +646,31 @@ async function mergeDocuments(pathOrApi) {
 * const document = await parseFromConfig({ type: 'data', data: '{"openapi":"3.0.0",...}' })
 * ```
 */
-function parseFromConfig(source) {
+async function parseFromConfig(source) {
 	if (source.type === "data") {
 		if (typeof source.data === "object") return parseDocument(structuredClone(source.data));
 		return parseDocument(source.data, { canBundle: false });
 	}
 	if (source.type === "paths") return mergeDocuments(source.paths);
 	if (new URLPath(source.path).isURL) return parseDocument(source.path);
-	return parseDocument(path.resolve(path.dirname(source.path), source.path));
+	const resolved = path.resolve(path.dirname(source.path), source.path);
+	await assertInputExists(resolved);
+	return parseDocument(resolved);
+}
+/**
+* Throws a coded `KUBB_INPUT_NOT_FOUND` diagnostic when a local input path does not exist.
+* URLs are skipped, and a malformed but readable file is left for `parseDocument` to surface
+* its parse error instead.
+*/
+async function assertInputExists(input) {
+	if (new URLPath(input).isURL) return;
+	if (!await exists(input)) throw new DiagnosticError({
+		code: diagnosticCode.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`.",
+		location: { kind: "config" }
+	});
 }
 /**
 * Validates an OpenAPI document using `oas-normalize` with colorized error output.
@@ -688,7 +717,21 @@ function resolveRef(document, $ref) {
 	}
 	if (docCache.has($ref)) return docCache.get($ref);
 	const current = $ref.split("/").filter(Boolean).reduce((obj, key) => obj?.[key], document);
-	if (!current) throw new Error(`Could not find a definition for ${origRef}.`);
+	if (!current) {
+		const diagnostic = {
+			code: diagnosticCode.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
+			}
+		};
+		if (!Diagnostics.report(diagnostic)) throw new DiagnosticError(diagnostic);
+		return null;
+	}
 	docCache.set($ref, current);
 	return current;
 }
@@ -715,13 +758,13 @@ function dereferenceWithRef(document, schema) {
 //#endregion
 //#region src/dialect.ts
 /**
-* The OpenAPI / Swagger dialect — the default used by `@kubb/adapter-oas`.
+* The OpenAPI / Swagger dialect, the default used by `@kubb/adapter-oas`.
 *
 * Implements the spec-agnostic {@link ast.SchemaDialect} contract: it isolates the
 * decisions that differ between specs (nullability, `$ref`, discriminator, binary,
 * ref resolution) so the converter pipeline and dispatch rules stay shared. A
-* future adapter (e.g. AsyncAPI) ships its own dialect — `type: ['null', …]`
-* nullability, no discriminator object, binary via `contentEncoding` — and reuses
+* future adapter (e.g. AsyncAPI) ships its own dialect, `type: ['null', …]`
+* nullability, no discriminator object, binary via `contentEncoding` and reuses
 * the rest unchanged.
 *
 * Formats (`uuid`, `email`, dates, …) are intentionally NOT here: they are shared
@@ -763,7 +806,16 @@ function resolveServerUrl(server, overrides) {
 	for (const [key, variable] of Object.entries(server.variables)) {
 		const value = overrides?.[key] ?? (variable.default != null ? String(variable.default) : void 0);
 		if (value === void 0) continue;
-		if (variable.enum?.length && !variable.enum.some((e) => String(e) === value)) throw new Error(`Invalid server variable value '${value}' for '${key}' when resolving ${server.url}. Valid values are: ${variable.enum.join(", ")}.`);
+		if (variable.enum?.length && !variable.enum.some((e) => String(e) === value)) throw new DiagnosticError({
+			code: diagnosticCode.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.`,
+			location: {
+				kind: "document",
+				pointer: "#/servers"
+			}
+		});
 		url = url.replaceAll(`{${key}}`, value);
 	}
 	return url;
@@ -776,6 +828,15 @@ function getSchemaType(format) {
 	return formatMap[format] ?? null;
 }
 /**
+* Whether the parser maps `format` to a dedicated type. True for any `formatMap` entry and the
+* `specialCasedFormats` `convertFormat` handles directly. False means the format falls back to the
+* base type, which is what `KUBB_UNSUPPORTED_FORMAT` flags. Reading both sources keeps the
+* diagnostic in step with the parser as `formatMap` grows.
+*/
+function isHandledFormat(format) {
+	return getSchemaType(format) !== null || specialCasedFormats.has(format);
+}
+/**
 * Converts an OAS primitive type string to its `PrimitiveSchemaType` equivalent.
 * Numeric types (`number`, `integer`, `bigint`) pass through unchanged. `boolean` maps to `'boolean'`. Everything else becomes `'string'`.
 */
@@ -872,7 +933,7 @@ function getRequestSchema(document, operation, options = {}) {
 /**
 * Flattens a keyword-only `allOf` into its parent schema.
 *
-* Only flattens when every member is a plain fragment — no `$ref` and no structural keywords
+* Only flattens when every member is a plain fragment, with no `$ref` and no structural keywords
 * (see `structuralKeys`). Outer schema values take precedence over fragment values.
 * Returns `null` for a `null` input, and the original schema unchanged when flattening is unsafe.
 *
@@ -882,7 +943,7 @@ function getRequestSchema(document, operation, options = {}) {
 * // { type: 'object', properties: {}, description: 'A pet' }
 *
 * flattenSchema({ allOf: [{ $ref: '#/components/schemas/Pet' }] })
-* // returned unchanged — contains a $ref
+* // returned unchanged, contains a $ref
 * ```
 */
 /**
@@ -908,7 +969,7 @@ function flattenSchema(schema) {
 /**
 * Extracts the inline schema from a media-type `content` map.
 *
-* Prefers `preferredContentType` when given; otherwise uses the first key in the map.
+* Prefers `preferredContentType` when given, otherwise uses the first key in the map.
 * Returns `null` when `content` is absent, the schema is missing, or the schema is a `$ref`.
 *
 * @example
@@ -1100,9 +1161,9 @@ function buildSchemaNode(schema, name, nullable, defaultValue) {
 /**
 * Returns all request body content type keys for an operation.
 *
-* The requestBody is dereferenced **in-place** when it is a `$ref` — the same mutation
-* that `getRequestSchema` already performs — so that the returned list accurately reflects
-* the available content types even for referenced bodies.
+* The requestBody is dereferenced in place when it is a `$ref` (the same mutation that
+* `getRequestSchema` already performs), so the returned list accurately reflects the
+* available content types even for referenced bodies.
 *
 * @example
 * ```ts
@@ -1119,7 +1180,7 @@ function getRequestBodyContentTypes(document, operation) {
 /**
 * Returns all response content type keys for an operation at a given status code.
 *
-* Response `$ref`s are resolved in-place first — the same mutation `getResponseSchema` performs —
+* Response `$ref`s are resolved in place first (the same mutation `getResponseSchema` performs),
 * so the returned list reflects the available content types even for referenced responses.
 *
 * @example
@@ -1179,16 +1240,12 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 	*/
 	const resolvingRefs = /* @__PURE__ */ new Set();
 	/**
-	* Cache of already-resolved `$ref` schemas within this parser instance.
+	* Cache of `$ref` schemas already resolved in this parser instance, keyed by ref path.
 	*
-	* Without this, the same referenced schema (e.g. `customer`) is fully re-expanded
-	* every time it appears as a `$ref` in a different parent schema. In heavily
-	* cross-referenced specs like Stripe (~1 400 schemas), this causes exponential
-	* blowup — `customer` alone may be referenced from dozens of top-level schemas,
-	* each triggering a fresh recursive expansion of its entire sub-tree.
-	*
-	* Memoizing by `$ref` path reduces the overall work from O(2^depth) to O(N)
-	* where N is the number of unique schema names.
+	* Without it, a shared schema (e.g. `customer`) is re-expanded for every `$ref` that points at
+	* it. In cross-referenced specs like Stripe (~1400 schemas) that becomes exponential blowup,
+	* since one schema can be referenced from dozens of parents, each re-walking its whole subtree.
+	* Memoizing by ref path drops the work from O(2^depth) to O(N) unique schema names.
 	*/
 	const resolvedRefCache = /* @__PURE__ */ new Map();
 	/**
@@ -1726,7 +1783,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 	/**
 	* Ordered schema-dispatch table. Order is significant: composition keywords (`$ref`, `allOf`,
 	* `oneOf`/`anyOf`) take precedence over `const`/`format`, which take precedence over the plain
-	* `type`. The first matching rule that produces a node wins; see {@link SchemaRule} for the
+	* `type`. The first matching rule that produces a node wins. See {@link SchemaRule} for the
 	* match/convert/fall-through contract.
 	*/
 	const schemaRules = [
@@ -2071,6 +2128,61 @@ function patchDiscriminatorNode(node, entry) {
 	};
 }
 //#endregion
+//#region src/schemaDiagnostics.ts
+/**
+* Reports the advisory diagnostics (`KUBB_UNSUPPORTED_FORMAT`, `KUBB_DEPRECATED`) for one
+* top-level schema. Walks the node the parser produced during `preScan`, threading the RFC 6901
+* pointer as it descends so a nested field reports against its full path
+* (`#/components/schemas/Pet/properties/owner/properties/name`). Refs are not followed, so the
+* resolved schema is reported under its own walk. Reports land in the active build run, are a
+* no-op outside one, and repeats are deduped by the build.
+*/
+function reportSchemaDiagnostics({ node, 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) {
+	return token.replace(/~/g, "~0").replace(/\//g, "~1");
+}
+function visit(node, pointer) {
+	if (node.deprecated) Diagnostics.report({
+		code: diagnosticCode.deprecated,
+		severity: "info",
+		message: "This schema is marked as deprecated.",
+		location: {
+			kind: "schema",
+			pointer
+		}
+	});
+	if (typeof node.format === "string" && !isHandledFormat(node.format)) Diagnostics.report({
+		code: diagnosticCode.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.`,
+		location: {
+			kind: "schema",
+			pointer
+		}
+	});
+	if (node.type === "object") {
+		for (const property of node.properties) visit(property.schema, `${pointer}/properties/${escapePointerToken(property.name)}`);
+		if (node.additionalProperties && typeof node.additionalProperties === "object") visit(node.additionalProperties, `${pointer}/additionalProperties`);
+		return;
+	}
+	if (node.type === "array") {
+		for (const item of node.items ?? []) visit(item, `${pointer}/items`);
+		return;
+	}
+	if (node.type === "tuple") {
+		for (const [index, item] of (node.items ?? []).entries()) visit(item, `${pointer}/items/${index}`);
+		return;
+	}
+	if (node.type === "union" || node.type === "intersection") for (const [index, member] of (node.members ?? []).entries()) visit(member, `${pointer}/members/${index}`);
+}
+//#endregion
 //#region src/stream.ts
 /**
 * Builds the deduplication plan from the already-parsed top-level schema nodes plus a
@@ -2130,7 +2242,7 @@ function resolveBaseUrl({ document, serverIndex, serverVariables }) {
 * After this call, only `refAliasMap` and `discriminatorChildMap` stay alive in the adapter closure.
 * Both are proportional to the number of aliases or discriminator parents, not total schema count.
 *
-* Each schema is parsed again during the streaming pass — this is intentional.
+* Each schema is parsed again during the streaming pass. This is intentional.
 * Holding the parsed nodes in memory here would defeat the streaming memory benefit.
 *
 * @example
@@ -2154,6 +2266,10 @@ function preScan({ schemas, parseSchema, parseOperation, baseOas, parserOptions,
 			name
 		}, parserOptions);
 		allNodes.push(node);
+		reportSchemaDiagnostics({
+			node,
+			name
+		});
 		if (node.type === "ref" && node.name && node.name !== name) refAliasMap.set(name, node);
 		if (ast.narrowSchema(node, ast.schemaTypes.enum) && node.name) enumNames.push(node.name);
 		if (discriminator === "inherit" && (schema.oneOf ?? schema.anyOf) && schema.discriminator?.propertyName) discriminatorParentNodes.push(node);
@@ -2294,37 +2410,72 @@ const adapterOas = createAdapter((options) => {
 	};
 	let nameMapping = /* @__PURE__ */ new Map();
 	let parsedDocument = null;
-	const ensureDocument = once(async (source) => {
-		const fresh = await parseFromConfig(source);
-		if (validate) await validateDocument(fresh);
-		parsedDocument = fresh;
-		return fresh;
-	});
-	const ensureSchemas = once(async (document) => {
-		const result = getSchemas(document, { contentType });
-		nameMapping = result.nameMapping;
-		return result.schemas;
-	});
-	const ensureBaseOas = once((document) => new BaseOas(document));
-	const ensureSchemaParser = once((document) => createSchemaParser({
-		document,
-		contentType
-	}));
-	const ensurePreScan = once((schemas, parseSchema, parseOperation, baseOas) => preScan({
-		schemas,
-		parseSchema,
-		parseOperation,
-		baseOas,
-		parserOptions,
-		discriminator,
-		dedupe
-	}));
+	const documentCache = /* @__PURE__ */ new WeakMap();
+	const schemasCache = /* @__PURE__ */ new WeakMap();
+	const baseOasCache = /* @__PURE__ */ new WeakMap();
+	const schemaParserCache = /* @__PURE__ */ new WeakMap();
+	const preScanCache = /* @__PURE__ */ new WeakMap();
+	function ensureDocument(source) {
+		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) {
+		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) {
+		const cached = baseOasCache.get(document);
+		if (cached) return cached;
+		const baseOas = new BaseOas(document);
+		baseOasCache.set(document, baseOas);
+		return baseOas;
+	}
+	function ensureSchemaParser(document) {
+		const cached = schemaParserCache.get(document);
+		if (cached) return cached;
+		const parser = createSchemaParser({
+			document,
+			contentType
+		});
+		schemaParserCache.set(document, parser);
+		return parser;
+	}
+	function ensurePreScan(document, schemas, parseSchema, parseOperation, baseOas) {
+		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) {
 		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,
 			parseSchema,
@@ -2370,6 +2521,7 @@ const adapterOas = createAdapter((options) => {
 			return parsedDocument;
 		},
 		async validate(input, options) {
+			await assertInputExists(input);
 			await validateDocument(await parseDocument(input), options);
 		},
 		getImports(node, resolve) {