@kubb/adapter-oas 5.12.8 → 5.13.0

package/dist/index.cjs

@@ -32,11 +32,11 @@ yaml = __toESM(yaml, 1);
 //#region kubb-extension.json
 var compatibility = {
 	"kubb": ">=5.8.3",
-	"node": ">=22.12"
+	"node": ">=22.22"
 };
 //#endregion
 //#region package.json
-var version = "5.12.8";
+var version = "5.13.0";
 //#endregion
 //#region src/constants.ts
 /**
@@ -630,8 +630,34 @@ async function validateDocument(document, { throwOnError = false } = {}) {
 		message: compileErrors(result),
 		help: "Fix each problem listed in the spec, then validate again."
 	});
-	for (const { message } of result.errors) reportInvalidSpec(message.replace(/\n.*/s, ""));
-	if (result.additionalErrors > 0) reportInvalidSpec(`${result.additionalErrors} more validation errors are not listed.`);
+	reportValidationErrors(result);
+}
+function reportValidationErrors({ errors, additionalErrors }) {
+	for (const { message } of errors) reportInvalidSpec(message.replace(/\n.*/s, ""));
+	if (additionalErrors > 0) reportInvalidSpec(`${additionalErrors} more validation errors are not listed.`);
+}
+/**
+* Validates like {@link validateDocument} without `throwOnError`, but in a worker thread, so the
+* build keeps generating while `@readme/openapi-parser` dereferences and checks the spec. Await the
+* returned promise inside the build's diagnostics scope to report its warnings there. Falls back to
+* validating in place where worker threads are missing, as in edge runtimes.
+*/
+async function validateDocumentInWorker(document) {
+	let message;
+	try {
+		const { Worker } = await import("node:worker_threads");
+		const workerFile = require("url").pathToFileURL(__filename).href.endsWith(".ts") ? "./validateWorker.ts" : "./validateWorker.js";
+		const worker = new Worker(new URL(workerFile, require("url").pathToFileURL(__filename).href), { workerData: document });
+		message = await new Promise((resolve, reject) => {
+			worker.once("message", resolve);
+			worker.once("error", reject);
+			worker.once("exit", (code) => reject(/* @__PURE__ */ new Error(`Validation worker exited with code ${code}`)));
+		}).finally(() => worker.terminate());
+	} catch {
+		return validateDocument(document);
+	}
+	if ("thrown" in message) return reportInvalidSpec(message.thrown);
+	if (!message.valid) reportValidationErrors(message);
 }
 //#endregion
 //#region src/oas.ts
@@ -720,7 +746,7 @@ function isJsonMimeType(mimeType) {
 //#endregion
 //#region src/model/components.ts
 /**
-* Extracts the inline schema from a media-type `content` map.
+* Extracts the inline schema from a media-type `content` map, with the media type it sits under.
 *
 * 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`.
@@ -728,15 +754,19 @@ function isJsonMimeType(mimeType) {
 * @example
 * ```ts
 * extractSchemaFromContent(operation.content, 'application/json')
-* // SchemaObject | null
+* // { schema: SchemaObject, contentType: 'application/json' } | null
 * ```
 */
 function extractSchemaFromContent(content, preferredContentType) {
 	if (!content) return null;
 	const firstContentType = Object.keys(content)[0] ?? "application/json";
-	const schema = content[preferredContentType ?? firstContentType]?.schema;
-	if (isReference(schema)) return null;
-	return schema ?? null;
+	const targetContentType = preferredContentType ?? firstContentType;
+	const schema = content[targetContentType]?.schema;
+	if (!schema || isReference(schema)) return null;
+	return {
+		schema,
+		contentType: targetContentType
+	};
 }
 /**
 * Walks a schema tree and collects the names of all `#/components/schemas/<name>` `$ref`s.
@@ -788,7 +818,7 @@ function* collectNestedDefinitions(schema, pointer, name) {
 			const nestedName = `${name}_${key}`;
 			yield {
 				schema: definition,
-				pointer: definitionPointer,
+				ref: definitionPointer,
 				originalName: nestedName
 			};
 			yield* collectNestedDefinitions(definition, definitionPointer, nestedName);
@@ -866,25 +896,28 @@ function getSchemas(document, { contentType }, refs) {
 		return resolved && !isReference(resolved) ? resolved : schema;
 	}
 	const candidates = [...Object.entries(components?.schemas ?? {}).flatMap(([name, schema]) => {
-		const pointer = `#/components/schemas/${escapePointerToken(name)}`;
+		const ref = `#/components/schemas/${escapePointerToken(name)}`;
 		return [{
 			schema: resolveSchemaRef(schema),
 			source: "schemas",
 			originalName: name,
-			pointer
-		}, ...[...collectNestedDefinitions(schema, pointer, name)].map((nested) => ({
+			ref
+		}, ...[...collectNestedDefinitions(schema, ref, name)].map((nested) => ({
 			...nested,
 			source: "schemas",
 			nested: true
 		}))];
 	}), ...["responses", "requestBodies"].flatMap((source) => Object.entries(components?.[source] ?? {}).flatMap(([name, item]) => {
-		const schema = extractSchemaFromContent(item.content, contentType);
-		return schema ? [{
-			schema: resolveSchemaRef(schema),
+		const extracted = extractSchemaFromContent(item.content, contentType);
+		if (!extracted) return [];
+		const ref = `#/components/${source}/${escapePointerToken(name)}`;
+		return [{
+			schema: resolveSchemaRef(extracted.schema),
 			source,
 			originalName: name,
-			pointer: `#/components/${source}/${escapePointerToken(name)}`
-		}] : [];
+			ref,
+			pointer: `${ref}/content/${escapePointerToken(extracted.contentType)}/schema`
+		}];
 	}))];
 	const normalizedNames = /* @__PURE__ */ new Map();
 	for (const item of candidates) {
@@ -895,6 +928,7 @@ function getSchemas(document, { contentType }, refs) {
 	}
 	const schemas = {};
 	const renames = /* @__PURE__ */ new Map();
+	const pointers = /* @__PURE__ */ new Map();
 	for (const [, items] of normalizedNames) {
 		const isSingle = items.length === 1;
 		const hasMultipleSources = !isSingle && new Set(items.map((item) => item.source)).size > 1;
@@ -902,12 +936,14 @@ function getSchemas(document, { contentType }, refs) {
 			const suffix = isSingle ? "" : hasMultipleSources ? semanticSuffixes[item.source] : index ? String(index + 1) : "";
 			const uniqueName = item.originalName + suffix;
 			schemas[uniqueName] = item.schema;
-			if (suffix || item.nested) renames.set(item.pointer, uniqueName);
+			pointers.set(uniqueName, item.pointer ?? item.ref);
+			if (suffix || item.nested) renames.set(item.ref, uniqueName);
 		});
 	}
 	return {
 		schemas: sortSchemas(schemas, renames),
-		renames
+		renames,
+		pointers
 	};
 }
 //#endregion
@@ -964,6 +1000,115 @@ function resolveServerUrl(server, overrides) {
 	return url;
 }
 //#endregion
+//#region src/emit/schemaShape.ts
+/**
+* Whether `format` maps to a dedicated type; `false` is what `KUBB_UNSUPPORTED_FORMAT` flags.
+*/
+function isHandledFormat(format) {
+	return formatMap[format] !== void 0 || specialCasedFormats.has(format);
+}
+/**
+* Resolves the `dateType` option down to the value for one format. The scalar form of
+* `dateType` applies to every format; the object form picks `dateTime`/`date`/`time`
+* individually and defaults an omitted key to `'string'`.
+*/
+function resolveDateTypeValue(dateType, format) {
+	if (typeof dateType !== "object" || dateType === null) return dateType;
+	return dateType[format === "date-time" ? "dateTime" : format] ?? "string";
+}
+/**
+* Reads schema examples as an array. OAS 3.1 uses an `examples` array, but specs (including ones
+* labeled 3.1) still use the singular OAS 3.0 `example`, which the upgrader only converts on the
+* 3.0 -> 3.1 hop. Normalize both into one array so the AST node exposes only `examples`.
+*/
+function extractExamples(schema) {
+	if (Array.isArray(schema.examples)) return schema.examples;
+	return schema.example !== void 0 ? [schema.example] : void 0;
+}
+function hasStructuralKeywords(fragment) {
+	return Object.keys(fragment).some((key) => structuralKeys.has(key));
+}
+/**
+* Flattens a keyword-only `allOf` into its parent schema.
+*
+* 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 the
+* original schema unchanged when flattening is unsafe.
+*
+* @example
+* ```ts
+* flattenSchema({ allOf: [{ description: 'A pet' }], type: 'object', properties: {} })
+* // { type: 'object', properties: {}, description: 'A pet' }
+* flattenSchema({ allOf: [{ $ref: '#/components/schemas/Pet' }] })
+* // returned unchanged, contains a $ref
+* ```
+*/
+function flattenSchema(schema) {
+	if (!schema.allOf?.length) return schema;
+	const allOfFragments = schema.allOf;
+	if (allOfFragments.some((item) => isReference(item))) return schema;
+	if (allOfFragments.some(hasStructuralKeywords)) return schema;
+	const { allOf: _allOf, ...rest } = schema;
+	const merged = rest;
+	for (const fragment of allOfFragments) for (const [key, value] of Object.entries(fragment)) merged[key] ??= value;
+	return merged;
+}
+//#endregion
+//#region src/schemaDiagnostics.ts
+/**
+* Links one freshly converted schema and its nested schemas to their RFC 6901 pointers
+* (`#/components/schemas/Pet/properties/owner/properties/name`), and reports the advisory
+* diagnostics (`KUBB_UNSUPPORTED_FORMAT`, `KUBB_DEPRECATED`) against them.
+* Refs are not followed, so the resolved schema is handled 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 scanSchema(node, pointer = node.pointer) {
+	if (pointer) visit(node, pointer);
+}
+function visit(node, pointer) {
+	node.pointer ??= pointer;
+	if (node.deprecated) _kubb_kit.Diagnostics.report({
+		code: _kubb_kit.Diagnostics.code.deprecated,
+		severity: "info",
+		message: "This schema is marked as deprecated.",
+		location: {
+			kind: "schema",
+			pointer
+		}
+	});
+	if (typeof node.format === "string" && !isHandledFormat(node.format)) _kubb_kit.Diagnostics.report({
+		code: _kubb_kit.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.`,
+		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 === "not") {
+		for (const member of node.members ?? []) visit(member, `${pointer}/not`);
+		return;
+	}
+	if (node.type === "union" || node.type === "intersection") {
+		const keyword = node.type === "intersection" ? "allOf" : node.strategy === "any" ? "anyOf" : "oneOf";
+		for (const [index, member] of (node.members ?? []).entries()) visit(member, `${pointer}/${keyword}/${index}`);
+	}
+}
+//#endregion
 //#region src/operation.ts
 function slugify(value) {
 	return value.replace(/[^a-zA-Z0-9]/g, "-").replace(/-{2,}/g, "-").replace(/^-|-$/g, "");
@@ -1013,11 +1158,18 @@ function getRequestContentType({ operation, refs }) {
 }
 /** Merges path-level and operation-level parameters; operation-level wins per `in:name`. */
 function getParameters({ operation, refs }) {
-	const resolveParams = (params) => params.map((p) => refs.derefKeepingRef(p)).filter((p) => !!p && typeof p === "object" && "in" in p && "name" in p);
-	const operationParams = resolveParams(operation.schema?.parameters || []);
-	const pathLevelParams = resolveParams(operation.pathItem.parameters ?? []);
+	const resolveParams = (params, pointer) => params.flatMap((entry, index) => {
+		const param = refs.derefKeepingRef(entry);
+		return param && typeof param === "object" && "in" in param && "name" in param ? [{
+			param,
+			pointer: `${pointer}/parameters/${index}`
+		}] : [];
+	});
+	const pathPointer = `#/paths/${escapePointerToken(operation.path)}`;
+	const operationParams = resolveParams(operation.schema?.parameters || [], `${pathPointer}/${operation.method.toLowerCase()}`);
+	const pathLevelParams = resolveParams(operation.pathItem.parameters ?? [], pathPointer);
 	const paramMap = /* @__PURE__ */ new Map();
-	for (const p of [...pathLevelParams, ...operationParams]) if (p.name && p.in) paramMap.set(`${p.in}:${p.name}`, p);
+	for (const entry of [...pathLevelParams, ...operationParams]) if (entry.param.name && entry.param.in) paramMap.set(`${entry.param.in}:${entry.param.name}`, entry);
 	return Array.from(paramMap.values());
 }
 /** Schema for one media type of a `content` map, with the binary fallback for an emptied non-JSON entry. */
@@ -1065,7 +1217,7 @@ function collectPropertyKeysByFlag(schema, flag) {
 	}
 	return keys.length ? keys : null;
 }
-function parseParameter({ param, parentName, options, parseSchema }) {
+function parseParameter({ param, pointer, parentName, options, parseSchema }) {
 	const schemaName = parentName && param.name ? pascalCase(`${parentName} ${param.name}`) : void 0;
 	const contentType = param.schema ? void 0 : Object.keys(param.content ?? {})[0];
 	const rawSchema = param.schema ?? (contentType ? param.content?.[contentType]?.schema : void 0);
@@ -1073,10 +1225,12 @@ function parseParameter({ param, parentName, options, parseSchema }) {
 		schema: rawSchema,
 		name: schemaName
 	}) : _kubb_kit.ast.factory.createSchema({ type: options.unknownType });
+	if (rawSchema) scanSchema(schema, contentType ? `${pointer}/content/${escapePointerToken(contentType)}/schema` : `${pointer}/schema`);
 	const style = param.style;
 	const explode = param.explode;
 	const allowReserved = param.allowReserved;
 	return _kubb_kit.ast.factory.createParameter({
+		pointer,
 		name: param.name,
 		in: param.in,
 		schema: {
@@ -1097,13 +1251,14 @@ function parseOperation({ operation, ...ctx }) {
 	const { refs, contentType, options, parseSchema } = ctx;
 	const operationId = getOperationId(operation);
 	const operationName = operationId ? pascalCase(operationId) : void 0;
+	const pointer = `#/paths/${escapePointerToken(operation.path)}/${operation.method.toLowerCase()}`;
 	const parameters = getParameters({
 		operation,
 		refs
-	}).map((param) => parseParameter({
+	}).map((entry) => parseParameter({
 		options,
 		parseSchema,
-		param,
+		...entry,
 		parentName: operationName
 	}));
 	const body = getRequestBody({
@@ -1119,16 +1274,19 @@ function parseOperation({ operation, ...ctx }) {
 			refs
 		});
 		if (!schema) return [];
+		const node = parseSchema({
+			schema,
+			name: requestBodyName
+		});
+		scanSchema(node, `${pointer}/requestBody/content/${escapePointerToken(ct)}/schema`);
 		return [_kubb_kit.ast.factory.createContent({
 			contentType: ct,
-			schema: _kubb_kit.ast.optionality(parseSchema({
-				schema,
-				name: requestBodyName
-			}), bodyRequired),
+			schema: _kubb_kit.ast.optionality(node, bodyRequired),
 			keysToOmit: collectPropertyKeysByFlag(schema, "readOnly")
 		})];
 	});
 	const requestBody = content.length > 0 || body?.description ? {
+		pointer: `${pointer}/requestBody`,
 		description: body?.description,
 		required: bodyRequired || void 0,
 		content: content.length > 0 ? content : void 0
@@ -1146,11 +1304,13 @@ function parseOperation({ operation, ...ctx }) {
 				contentType: ct,
 				refs
 			});
+			const node = raw && Object.keys(raw).length > 0 ? parseSchema({
+				schema: raw,
+				name: responseName
+			}) : _kubb_kit.ast.factory.createSchema({ type: options.emptySchemaType });
+			if (raw && ct) scanSchema(node, `${pointer}/responses/${statusCode}/content/${escapePointerToken(ct)}/schema`);
 			return {
-				schema: raw && Object.keys(raw).length > 0 ? parseSchema({
-					schema: raw,
-					name: responseName
-				}) : _kubb_kit.ast.factory.createSchema({ type: options.emptySchemaType }),
+				schema: node,
 				keysToOmit: collectPropertyKeysByFlag(raw, "writeOnly")
 			};
 		};
@@ -1166,6 +1326,7 @@ function parseOperation({ operation, ...ctx }) {
 			...parseEntrySchema(contentType)
 		}));
 		return _kubb_kit.ast.factory.createResponse({
+			pointer: `${pointer}/responses/${statusCode}`,
 			statusCode,
 			description: response?.description,
 			content: responseContent
@@ -1178,6 +1339,7 @@ function parseOperation({ operation, ...ctx }) {
 		return typeof fallback === "string" ? fallback : void 0;
 	};
 	return _kubb_kit.ast.factory.createOperation({
+		pointer,
 		operationId,
 		protocol: "http",
 		method: operation.method.toUpperCase(),
@@ -1193,60 +1355,6 @@ function parseOperation({ operation, ...ctx }) {
 	});
 }
 //#endregion
-//#region src/emit/schemaShape.ts
-/**
-* Whether `format` maps to a dedicated type; `false` is what `KUBB_UNSUPPORTED_FORMAT` flags.
-*/
-function isHandledFormat(format) {
-	return formatMap[format] !== void 0 || specialCasedFormats.has(format);
-}
-/**
-* Resolves the `dateType` option down to the value for one format. The scalar form of
-* `dateType` applies to every format; the object form picks `dateTime`/`date`/`time`
-* individually and defaults an omitted key to `'string'`.
-*/
-function resolveDateTypeValue(dateType, format) {
-	if (typeof dateType !== "object" || dateType === null) return dateType;
-	return dateType[format === "date-time" ? "dateTime" : format] ?? "string";
-}
-/**
-* Reads schema examples as an array. OAS 3.1 uses an `examples` array, but specs (including ones
-* labeled 3.1) still use the singular OAS 3.0 `example`, which the upgrader only converts on the
-* 3.0 -> 3.1 hop. Normalize both into one array so the AST node exposes only `examples`.
-*/
-function extractExamples(schema) {
-	if (Array.isArray(schema.examples)) return schema.examples;
-	return schema.example !== void 0 ? [schema.example] : void 0;
-}
-function hasStructuralKeywords(fragment) {
-	return Object.keys(fragment).some((key) => structuralKeys.has(key));
-}
-/**
-* Flattens a keyword-only `allOf` into its parent schema.
-*
-* 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 the
-* original schema unchanged when flattening is unsafe.
-*
-* @example
-* ```ts
-* flattenSchema({ allOf: [{ description: 'A pet' }], type: 'object', properties: {} })
-* // { type: 'object', properties: {}, description: 'A pet' }
-* flattenSchema({ allOf: [{ $ref: '#/components/schemas/Pet' }] })
-* // returned unchanged, contains a $ref
-* ```
-*/
-function flattenSchema(schema) {
-	if (!schema.allOf?.length) return schema;
-	const allOfFragments = schema.allOf;
-	if (allOfFragments.some((item) => isReference(item))) return schema;
-	if (allOfFragments.some(hasStructuralKeywords)) return schema;
-	const { allOf: _allOf, ...rest } = schema;
-	const merged = rest;
-	for (const fragment of allOfFragments) for (const [key, value] of Object.entries(fragment)) merged[key] ??= value;
-	return merged;
-}
-//#endregion
 //#region src/emit/createNode.ts
 /**
 * Builds a schema node from a converter's base context plus its type-specific fields. Every
@@ -2356,55 +2464,6 @@ function createRefs(document) {
 	};
 }
 //#endregion
-//#region src/schemaDiagnostics.ts
-/**
-* Reports the advisory diagnostics (`KUBB_UNSUPPORTED_FORMAT`, `KUBB_DEPRECATED`) for one freshly
-* converted top-level schema.
-*
-* Walks the node the parser produced, 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 scanSchema({ node, name }) {
-	visit(node, `#/components/schemas/${escapePointerToken(name)}`);
-}
-function visit(node, pointer) {
-	if (node.deprecated) _kubb_kit.Diagnostics.report({
-		code: _kubb_kit.Diagnostics.code.deprecated,
-		severity: "info",
-		message: "This schema is marked as deprecated.",
-		location: {
-			kind: "schema",
-			pointer
-		}
-	});
-	if (typeof node.format === "string" && !isHandledFormat(node.format)) _kubb_kit.Diagnostics.report({
-		code: _kubb_kit.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.`,
-		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" || node.type === "not") for (const [index, member] of (node.members ?? []).entries()) visit(member, `${pointer}/members/${index}`);
-}
-//#endregion
 //#region src/sourceLocator.ts
 let cached;
 const toRange = ([start, end]) => ({
@@ -2445,17 +2504,122 @@ function findRefUsage(document, ref) {
 	return found[0];
 }
 /**
-* Maps OpenAPI JSON pointers and unresolved references to ranges in YAML or JSON source.
+* One pass over JSON text, so a located diagnostic in a large JSON spec skips `yaml.parseDocument`.
+* Holds the range of every key and array item by pointer, and the first usage of every `$ref`, as
+* `findPointer` and `findRefUsage` return them. Throws where the text breaks JSON syntax, such as a
+* comment, an unquoted key, or an unquoted `$ref` value. Other bare values, such as `object`, pass.
 */
-const locate = (source, location) => {
-	if (!("pointer" in location)) return void 0;
-	if (cached?.source === source) cached.source = source;
-	else cached = {
+function indexJson(source) {
+	const pointers = /* @__PURE__ */ new Map();
+	const refs = /* @__PURE__ */ new Map();
+	let at = source.indexOf("{");
+	const fail = () => {
+		throw new SyntaxError(`Unexpected character at ${at}`);
+	};
+	const skipSpace = () => {
+		for (let code = source.charCodeAt(at); code === 32 || code === 9 || code === 10 || code === 13; code = source.charCodeAt(++at));
+	};
+	const readString = () => {
+		if (source[at] !== "\"") fail();
+		const start = at;
+		for (at++; source.charCodeAt(at) !== 34; at++) {
+			if (at >= source.length) fail();
+			if (source.charCodeAt(at) === 92) at++;
+		}
+		const raw = source.slice(start + 1, at++);
+		return {
+			text: raw.includes("\\") ? JSON.parse(source.slice(start, at)) : raw,
+			start,
+			end: at
+		};
+	};
+	const expect = (char) => {
+		skipSpace();
+		if (source[at++] !== char) fail();
+		skipSpace();
+	};
+	const walk = (pointer) => {
+		const open = source[at];
+		if (open === "\"") {
+			readString();
+			return;
+		}
+		if (open !== "{" && open !== "[") {
+			const start = at;
+			while (at < source.length && !/[\s,\]}]/.test(source[at])) at++;
+			if (at === start) fail();
+			return;
+		}
+		const close = open === "{" ? "}" : "]";
+		at++;
+		for (let index = 0;; index++) {
+			skipSpace();
+			if (source[at] === close) break;
+			if (index > 0) expect(",");
+			if (open === "[") {
+				const start = at;
+				const next = `${pointer}/${index}`;
+				walk(next);
+				if (!pointers.has(next)) pointers.set(next, {
+					start,
+					end: at
+				});
+				continue;
+			}
+			const key = readString();
+			const next = `${pointer}/${escapePointerToken(key.text)}`;
+			if (!pointers.has(next)) pointers.set(next, {
+				start: key.start,
+				end: key.end
+			});
+			expect(":");
+			if (key.text !== "$ref" || source[at] === "{" || source[at] === "[") {
+				walk(next);
+				continue;
+			}
+			const value = readString();
+			if (!refs.has(value.text)) refs.set(value.text, {
+				start: value.start,
+				end: value.end
+			});
+		}
+		at++;
+	};
+	walk("#");
+	return {
+		pointers,
+		refs
+	};
+}
+/** Indexes plain JSON text; anything else goes to the YAML parser. */
+function parse(source) {
+	if (/^[ \t\n\r]*\{/.test(source)) try {
+		return {
+			source,
+			json: indexJson(source)
+		};
+	} catch {}
+	return {
 		source,
 		document: yaml.parseDocument(source)
 	};
+}
+/**
+* Maps OpenAPI JSON pointers and unresolved references to ranges in YAML or JSON source.
+*/
+const locate = (source, location) => {
+	if (!("pointer" in location)) return void 0;
+	cached = cached?.source === source ? {
+		...cached,
+		source
+	} : parse(source);
+	const ref = "ref" in location ? location.ref : void 0;
+	if ("json" in cached) {
+		const { pointers, refs } = cached.json;
+		return pointers.get(location.pointer) ?? (ref ? refs.get(ref) : void 0);
+	}
 	const { document } = cached;
-	return findPointer(document, location.pointer) ?? ("ref" in location && location.ref ? findRefUsage(document, location.ref) : void 0);
+	return findPointer(document, location.pointer) ?? (ref ? findRefUsage(document, ref) : void 0);
 };
 //#endregion
 //#region src/adapter.ts
@@ -2512,25 +2676,26 @@ const adapterOas = (0, _kubb_core.defineExtension)({
 	}),
 	build({ validate, contentType, server, discriminator, enums, ...parserOptions }) {
 		let parsedDocument = null;
+		const pendingValidations = [];
 		const inputCache = /* @__PURE__ */ new WeakMap();
 		/**
 		* Parses every schema and operation once, resolving ref aliases and discriminator children from that same pass.
 		*/
-		function parseInput({ document, refs, schemas, parseSchema }) {
+		function parseInput({ document, refs, schemas, pointers, parseSchema }) {
 			const parsedByName = /* @__PURE__ */ new Map();
 			const refAliasMap = /* @__PURE__ */ new Map();
 			const enumNames = [];
 			const discriminatorParentNodes = [];
 			for (const [name, schema] of Object.entries(schemas)) {
-				const node = parseSchema({
-					schema,
-					name
-				});
+				const node = {
+					...parseSchema({
+						schema,
+						name
+					}),
+					pointer: pointers.get(name)
+				};
 				parsedByName.set(name, node);
-				scanSchema({
-					node,
-					name
-				});
+				scanSchema(node);
 				if (node.type === "ref" && node.name && node.name !== name) refAliasMap.set(name, node);
 				if (_kubb_kit.ast.narrowSchema(node, "enum") && node.name) enumNames.push(node.name);
 				if (discriminator === "propagate" && (schema.oneOf ?? schema.anyOf) && schema.discriminator?.propertyName) discriminatorParentNodes.push(node);
@@ -2555,7 +2720,8 @@ const adapterOas = (0, _kubb_core.defineExtension)({
 				const base = child ? patchDiscriminatorNode(parsed, child) : parsed;
 				const node = aliased ? {
 					...aliased,
-					name
+					name,
+					pointer: parsed.pointer
 				} : base;
 				schemaNodes.push(promotedEnums ? refPromotedEnums(node, promotedEnums) : node);
 			}
@@ -2621,6 +2787,9 @@ const adapterOas = (0, _kubb_core.defineExtension)({
 				assertDocument(document);
 				await validateDocument(document, options);
 			},
+			async settle() {
+				await Promise.all(pendingValidations.splice(0));
+			},
 			async parse(source, { signal } = {}) {
 				signal?.throwIfAborted();
 				const cached = inputCache.get(source);
@@ -2629,14 +2798,15 @@ const adapterOas = (0, _kubb_core.defineExtension)({
 					const document = await parseFromConfig(source);
 					signal?.throwIfAborted();
 					assertDocument(document);
-					if (validate) await validateDocument(document);
+					if (validate) pendingValidations.push(validateDocumentInWorker(document));
 					parsedDocument = document;
 					const refs = createRefs(document);
-					const { schemas, renames } = getSchemas(document, { contentType }, refs);
+					const { schemas, renames, pointers } = getSchemas(document, { contentType }, refs);
 					return parseInput({
 						document,
 						refs,
 						schemas,
+						pointers,
 						parseSchema: createSchemaParser({
 							document,
 							refs,