schema-components 1.18.1 → 1.20.0

package/dist/normalise-CMMEl4cd.mjs

@@ -0,0 +1,1306 @@
+import { isObject } from "./core/guards.mjs";
+import { appendPointer, emitDiagnostic } from "./core/diagnostics.mjs";
+import { isOpenApi30, isOpenApi31, isSwagger2, readJsonSchemaDialect } from "./core/version.mjs";
+//#region src/core/openapi30.ts
+/**
+* OpenAPI 3.0.x schema normalisation.
+*
+* Transforms `nullable`, `discriminator`, `example` keywords, and walks
+* all schema locations (components, paths, parameters, request bodies,
+* responses, headers, callbacks, links, examples) to apply normalisation.
+*/
+/**
+* Normalise OpenAPI 3.0.x `nullable` keyword to `anyOf [T, null]`.
+*
+* OpenAPI 3.0 uses `nullable: true` instead of the JSON Schema standard
+* `anyOf: [T, { type: "null" }]`. The walker understands the latter form
+* natively, so this normaliser converts `nullable` to `anyOf`.
+*
+* Only applied when `nullable` is explicitly `true`. `nullable: false` or
+* absent is the default and requires no transformation.
+*/
+function normaliseOpenApi30Node(node) {
+	if ("example" in node && !("examples" in node)) {
+		node.examples = [node.example];
+		delete node.example;
+	} else if ("example" in node) delete node.example;
+	if (node.nullable !== true) {
+		if ("nullable" in node) delete node.nullable;
+		return node;
+	}
+	const nullOption = { type: "null" };
+	if (Array.isArray(node.anyOf)) {
+		node.anyOf = [...node.anyOf, nullOption];
+		delete node.nullable;
+		return node;
+	}
+	if (Array.isArray(node.oneOf)) {
+		node.anyOf = [...node.oneOf, nullOption];
+		delete node.oneOf;
+		delete node.nullable;
+		return node;
+	}
+	if (Array.isArray(node.allOf)) {
+		node.anyOf = [{ allOf: node.allOf }, nullOption];
+		delete node.allOf;
+		delete node.nullable;
+		return node;
+	}
+	const wrapper = {};
+	for (const [key, value] of Object.entries(node)) if (key !== "nullable") wrapper[key] = value;
+	return { anyOf: [wrapper, nullOption] };
+}
+/**
+* Normalise OpenAPI 3.0.x `discriminator` keyword by injecting `const`
+* values into each `oneOf`/`anyOf` option's discriminator property.
+*
+* In OpenAPI 3.0, `discriminator` is a sibling of `oneOf`/`anyOf`:
+*   discriminator: { propertyName: "type" }
+* The walker detects discriminated unions from `oneOf` + `const` on a
+* property, so this normaliser injects the `const` values from the
+* `mapping` or infers them from `$ref` fragment names.
+*/
+function normaliseOpenApi30Discriminator(node) {
+	const discriminator = node.discriminator;
+	if (!isObject(discriminator)) return node;
+	const propertyName = discriminator.propertyName;
+	if (typeof propertyName !== "string") return node;
+	const mapping = isObject(discriminator.mapping) ? discriminator.mapping : void 0;
+	const composite = node.oneOf ?? node.anyOf;
+	if (!Array.isArray(composite)) return node;
+	const refToValue = /* @__PURE__ */ new Map();
+	if (mapping !== void 0) {
+		for (const [value, ref] of Object.entries(mapping)) if (typeof ref === "string") refToValue.set(ref, value);
+	}
+	const normalisedComposite = [];
+	for (const option of composite) {
+		if (!isObject(option)) {
+			normalisedComposite.push(option);
+			continue;
+		}
+		const props = isObject(option.properties) ? { ...option.properties } : void 0;
+		const discProp = props?.[propertyName];
+		if (isObject(discProp) && "const" in discProp) {
+			normalisedComposite.push(option);
+			continue;
+		}
+		let constValue;
+		if (isObject(discProp) && typeof discProp.$ref === "string") constValue = refToValue.get(discProp.$ref);
+		if (constValue === void 0 && typeof option.$ref === "string") {
+			constValue = refToValue.get(option.$ref);
+			if (constValue === void 0) {
+				const fragment = option.$ref.split("/").pop();
+				if (fragment !== void 0) constValue = fragment;
+			}
+		}
+		if (constValue === void 0 && mapping !== void 0) {
+			const optionIndex = composite.indexOf(option);
+			const mappingEntries = Object.entries(mapping);
+			const entry = optionIndex >= 0 && optionIndex < mappingEntries.length ? mappingEntries[optionIndex] : void 0;
+			if (entry !== void 0) constValue = entry[0];
+		}
+		if (constValue !== void 0) {
+			const normalisedProps = props ?? {};
+			normalisedProps[propertyName] = {
+				...isObject(discProp) ? discProp : {},
+				const: constValue
+			};
+			normalisedComposite.push({
+				...option,
+				properties: normalisedProps
+			});
+		} else normalisedComposite.push(option);
+	}
+	if ("oneOf" in node) node.oneOf = normalisedComposite;
+	else if ("anyOf" in node) node.anyOf = normalisedComposite;
+	delete node.discriminator;
+	return node;
+}
+/**
+* Combined OpenAPI 3.0.x node transform: Draft 04 + nullable + discriminator.
+* Applied to every schema node in an OpenAPI 3.0 document.
+*
+* Draft 04 normalisation is included because OpenAPI 3.0 inherits
+* Draft 04/05 schema semantics including `exclusiveMinimum: boolean`.
+*/
+function normaliseOpenApi30Combined(node) {
+	return normaliseOpenApi30Discriminator(normaliseOpenApi30Node(normaliseDraft04Node(node)));
+}
+/**
+* Deep-clone the parent first, then patch back any keys whose values were
+* rewritten by the visitor. This preserves immutability of the original
+* document while keeping the visitor straightforward to write.
+*/
+/**
+* Deep-normalise every Schema Object in an OpenAPI document.
+*
+* Walks: `paths.*` (operations + path-level parameters), `webhooks.*`
+* (3.1), `components.schemas`, `components.parameters`,
+* `components.responses`, `components.requestBodies`,
+* `components.headers`, `components.callbacks`, `components.pathItems`
+* (3.1). For each Schema-bearing location, applies the supplied
+* `normaliseSchema` function.
+*
+* The walker is structural (it understands OAS document shapes) and
+* delegates the per-schema transformation. For OAS 3.0 the caller
+* passes a full Draft 04 + nullable + discriminator + example
+* normaliser; for OAS 3.1 the caller passes a discriminator-only
+* normaliser so the walker's discriminated-union detection sees the
+* injected `const`s regardless of OAS minor version.
+*/
+function deepNormaliseOpenApiDoc(doc, normaliseSchema) {
+	const result = { ...doc };
+	const components = doc.components;
+	if (isObject(components)) result.components = normaliseComponents(components, normaliseSchema);
+	const paths = doc.paths;
+	if (isObject(paths)) result.paths = normalisePathMap(paths, normaliseSchema);
+	const webhooks = doc.webhooks;
+	if (isObject(webhooks)) result.webhooks = normalisePathMap(webhooks, normaliseSchema);
+	return result;
+}
+/**
+* Backwards-compatible wrapper retaining the historic `deepNormalise`
+* signature used by callers in `normalise.ts`. Always applies the full
+* 3.0 combined transform via `deepNormalise(schema, normaliseOpenApi30Combined)`.
+*/
+function deepNormaliseOpenApi30Doc(doc, deepNormalise) {
+	return deepNormaliseOpenApiDoc(doc, (schema) => deepNormalise(schema, normaliseOpenApi30Combined));
+}
+function normaliseComponents(components, normaliseSchema) {
+	const result = { ...components };
+	const schemas = components.schemas;
+	if (isObject(schemas)) result.schemas = mapObjectValues(schemas, (schema) => isObject(schema) ? normaliseSchema(schema) : schema);
+	const parameters = components.parameters;
+	if (isObject(parameters)) result.parameters = mapObjectValues(parameters, (param) => isObject(param) ? normaliseParameter(param, normaliseSchema) : param);
+	const responses = components.responses;
+	if (isObject(responses)) result.responses = mapObjectValues(responses, (response) => isObject(response) ? normaliseResponse(response, normaliseSchema) : response);
+	const requestBodies = components.requestBodies;
+	if (isObject(requestBodies)) result.requestBodies = mapObjectValues(requestBodies, (body) => isObject(body) ? normaliseRequestBody(body, normaliseSchema) : body);
+	const headers = components.headers;
+	if (isObject(headers)) result.headers = mapObjectValues(headers, (header) => isObject(header) ? normaliseHeader(header, normaliseSchema) : header);
+	const callbacks = components.callbacks;
+	if (isObject(callbacks)) result.callbacks = mapObjectValues(callbacks, (callback) => isObject(callback) ? normaliseCallback(callback, normaliseSchema) : callback);
+	const pathItems = components.pathItems;
+	if (isObject(pathItems)) result.pathItems = mapObjectValues(pathItems, (pathItem) => isObject(pathItem) ? normalisePathItem(pathItem, normaliseSchema) : pathItem);
+	return result;
+}
+function normalisePathMap(paths, normaliseSchema) {
+	return mapObjectValues(paths, (pathItem) => isObject(pathItem) ? normalisePathItem(pathItem, normaliseSchema) : pathItem);
+}
+const HTTP_METHODS = [
+	"get",
+	"put",
+	"post",
+	"delete",
+	"options",
+	"head",
+	"patch",
+	"trace"
+];
+function normalisePathItem(pathItem, normaliseSchema) {
+	const result = { ...pathItem };
+	for (const method of HTTP_METHODS) {
+		const operation = pathItem[method];
+		if (isObject(operation)) result[method] = normaliseOperation(operation, normaliseSchema);
+	}
+	const parameters = pathItem.parameters;
+	if (Array.isArray(parameters)) result.parameters = parameters.map((param) => isObject(param) ? normaliseParameter(param, normaliseSchema) : param);
+	return result;
+}
+function normaliseOperation(operation, normaliseSchema) {
+	const result = { ...operation };
+	const parameters = operation.parameters;
+	if (Array.isArray(parameters)) result.parameters = parameters.map((param) => isObject(param) ? normaliseParameter(param, normaliseSchema) : param);
+	const requestBody = operation.requestBody;
+	if (isObject(requestBody)) result.requestBody = normaliseRequestBody(requestBody, normaliseSchema);
+	const responses = operation.responses;
+	if (isObject(responses)) result.responses = mapObjectValues(responses, (response) => isObject(response) ? normaliseResponse(response, normaliseSchema) : response);
+	const callbacks = operation.callbacks;
+	if (isObject(callbacks)) result.callbacks = mapObjectValues(callbacks, (callback) => isObject(callback) ? normaliseCallback(callback, normaliseSchema) : callback);
+	return result;
+}
+function normaliseParameter(param, normaliseSchema) {
+	const result = { ...param };
+	const schema = param.schema;
+	if (isObject(schema)) result.schema = normaliseSchema(schema);
+	const content = param.content;
+	if (isObject(content)) result.content = normaliseContentMap(content, normaliseSchema);
+	if ("example" in result && !("examples" in result)) {
+		result.examples = [result.example];
+		delete result.example;
+	} else if ("example" in result) delete result.example;
+	return result;
+}
+function normaliseRequestBody(requestBody, normaliseSchema) {
+	const result = { ...requestBody };
+	const content = requestBody.content;
+	if (isObject(content)) result.content = normaliseContentMap(content, normaliseSchema);
+	return result;
+}
+function normaliseResponse(response, normaliseSchema) {
+	const result = { ...response };
+	const content = response.content;
+	if (isObject(content)) result.content = normaliseContentMap(content, normaliseSchema);
+	const headers = response.headers;
+	if (isObject(headers)) result.headers = mapObjectValues(headers, (header) => isObject(header) ? normaliseHeader(header, normaliseSchema) : header);
+	return result;
+}
+function normaliseHeader(header, normaliseSchema) {
+	const result = { ...header };
+	const schema = header.schema;
+	if (isObject(schema)) result.schema = normaliseSchema(schema);
+	const content = header.content;
+	if (isObject(content)) result.content = normaliseContentMap(content, normaliseSchema);
+	if ("example" in result && !("examples" in result)) {
+		result.examples = [result.example];
+		delete result.example;
+	} else if ("example" in result) delete result.example;
+	return result;
+}
+/**
+* A Callback Object is a map of runtime-expression keys → Path Item
+* Objects. Each Path Item carries operations whose responses, request
+* bodies, parameters, and headers may all contain Schema Objects.
+*/
+function normaliseCallback(callback, normaliseSchema) {
+	return mapObjectValues(callback, (pathItem) => isObject(pathItem) ? normalisePathItem(pathItem, normaliseSchema) : pathItem);
+}
+function normaliseContentMap(content, normaliseSchema) {
+	const result = {};
+	for (const [mediaType, mediaObj] of Object.entries(content)) {
+		if (!isObject(mediaObj)) {
+			result[mediaType] = mediaObj;
+			continue;
+		}
+		const normalised = { ...mediaObj };
+		const schema = mediaObj.schema;
+		if (isObject(schema)) normalised.schema = normaliseSchema(schema);
+		const encoding = mediaObj.encoding;
+		if (isObject(encoding)) normalised.encoding = mapObjectValues(encoding, (enc) => isObject(enc) ? normaliseEncoding(enc, normaliseSchema) : enc);
+		if ("example" in normalised && !("examples" in normalised)) {
+			normalised.examples = { default: { value: normalised.example } };
+			delete normalised.example;
+		} else if ("example" in normalised) delete normalised.example;
+		result[mediaType] = normalised;
+	}
+	return result;
+}
+function normaliseEncoding(encoding, normaliseSchema) {
+	const result = { ...encoding };
+	const headers = encoding.headers;
+	if (isObject(headers)) result.headers = mapObjectValues(headers, (header) => isObject(header) ? normaliseHeader(header, normaliseSchema) : header);
+	return result;
+}
+/**
+* Apply `transform` to each value of a `Record<string, unknown>` and
+* return a new record. Non-object values pass through transform unchanged
+* — callers add their own `isObject` guard inside `transform`.
+*/
+function mapObjectValues(source, transform) {
+	const result = {};
+	for (const [key, value] of Object.entries(source)) result[key] = transform(value);
+	return result;
+}
+//#endregion
+//#region src/core/swagger2.ts
+/**
+* Swagger 2.0 → OpenAPI 3.1 document normalisation.
+*
+* Transforms a Swagger 2.0 document into an OpenAPI 3.1-compatible
+* structure: host/basePath/schemes → servers, definitions → components,
+* body/formData params → requestBody, response schemas → content.
+*
+* Individual schemas within the document are also normalised for
+* Draft 04 semantics (exclusiveMinimum/exclusiveMaximum booleans).
+*/
+/**
+* Transform a Swagger 2.0 document into an OpenAPI 3.1-compatible
+* structure.
+*/
+function normaliseSwagger2Document(doc, deepNormalise, normaliseDraft04Node, diagnostics) {
+	const result = {
+		openapi: "3.1.0",
+		info: isObject(doc.info) ? { ...doc.info } : {
+			title: "API",
+			version: "0.0.0"
+		}
+	};
+	if (typeof doc.host === "string" || typeof doc.basePath === "string" || Array.isArray(doc.schemes)) {
+		const host = typeof doc.host === "string" ? doc.host : "localhost";
+		const basePath = typeof doc.basePath === "string" ? doc.basePath : "/";
+		const schemes = Array.isArray(doc.schemes) ? doc.schemes : ["https"];
+		result.servers = [{ url: `${typeof schemes[0] === "string" ? schemes[0] : "https"}://${host}${basePath}` }];
+	}
+	const paths = doc.paths;
+	if (isObject(paths)) result.paths = normaliseSwaggerPaths(paths, doc, diagnostics);
+	const components = {};
+	const definitions = doc.definitions;
+	if (isObject(definitions)) {
+		const schemas = {};
+		for (const [name, schema] of Object.entries(definitions)) schemas[name] = isObject(schema) ? deepNormalise(schema, (node) => normaliseOpenApi30Combined(normaliseDraft04Node(node))) : schema;
+		components.schemas = schemas;
+	}
+	const parameters = doc.parameters;
+	const requestBodies = {};
+	if (isObject(parameters)) {
+		const globalConsumes = Array.isArray(doc.consumes) ? doc.consumes : ["application/json"];
+		const convertedParameters = {};
+		for (const [name, param] of Object.entries(parameters)) {
+			if (!isObject(param)) {
+				convertedParameters[name] = param;
+				continue;
+			}
+			const resolved = resolveSwaggerParameter(param, doc);
+			const location = resolved.in;
+			if (location === "body") requestBodies[name] = buildRequestBody(resolved, globalConsumes);
+			else if (location === "formData") requestBodies[name] = buildRequestBody(buildFormDataBody(resolved, [resolved]), formDataContentTypes(globalConsumes));
+			else convertedParameters[name] = normaliseSwaggerParameter(resolved, doc);
+		}
+		if (Object.keys(convertedParameters).length > 0) components.parameters = convertedParameters;
+	}
+	const responses = doc.responses;
+	if (isObject(responses)) {
+		const globalProduces = Array.isArray(doc.produces) ? doc.produces : ["application/json"];
+		const convertedResponses = {};
+		for (const [name, response] of Object.entries(responses)) convertedResponses[name] = isObject(response) ? normaliseSwaggerSingleResponse(response, doc, globalProduces) : response;
+		components.responses = convertedResponses;
+	}
+	if (Object.keys(requestBodies).length > 0) components.requestBodies = requestBodies;
+	const securityDefinitions = doc.securityDefinitions;
+	if (isObject(securityDefinitions)) components.securitySchemes = { ...securityDefinitions };
+	if (Object.keys(components).length > 0) result.components = components;
+	if (Array.isArray(doc.tags)) result.tags = doc.tags;
+	if (isObject(doc.externalDocs)) result.externalDocs = doc.externalDocs;
+	if (Array.isArray(doc.security)) result.security = doc.security;
+	rewriteSwaggerRefs(result);
+	if (hasXmlAnywhere(doc.definitions) || hasXmlAnywhere(doc.paths) || hasXmlAnywhere(doc.parameters) || hasXmlAnywhere(doc.responses)) emitDiagnostic(diagnostics, {
+		code: "dropped-swagger-feature",
+		message: "Swagger 2.0 xml markup is not supported and will be dropped",
+		pointer: "",
+		detail: { feature: "xml" }
+	});
+	return result;
+}
+function normaliseSwaggerPaths(paths, doc, diagnostics) {
+	const result = {};
+	const METHODS = [
+		"get",
+		"post",
+		"put",
+		"patch",
+		"delete",
+		"head",
+		"options"
+	];
+	for (const [path, pathItem] of Object.entries(paths)) {
+		if (!isObject(pathItem)) {
+			result[path] = pathItem;
+			continue;
+		}
+		const normalisedPath = {};
+		for (const method of METHODS) {
+			const operation = pathItem[method];
+			if (!isObject(operation)) continue;
+			normalisedPath[method] = normaliseSwaggerOperation(operation, doc, path, method, diagnostics);
+		}
+		const pathParams = pathItem.parameters;
+		if (Array.isArray(pathParams)) normalisedPath.parameters = pathParams.map((p) => isObject(p) ? normaliseSwaggerParameter(p, doc) : p);
+		result[path] = normalisedPath;
+	}
+	return result;
+}
+function normaliseSwaggerOperation(operation, doc, path, method, diagnostics) {
+	const result = {};
+	const globalProduces = Array.isArray(doc.produces) ? doc.produces : ["application/json"];
+	const globalConsumes = Array.isArray(doc.consumes) ? doc.consumes : ["application/json"];
+	const produces = Array.isArray(operation.produces) ? operation.produces : globalProduces;
+	const consumes = Array.isArray(operation.consumes) ? operation.consumes : globalConsumes;
+	for (const [key, value] of Object.entries(operation)) if (key !== "parameters" && key !== "responses" && key !== "produces" && key !== "consumes") result[key] = value;
+	const params = operation.parameters;
+	if (Array.isArray(params)) {
+		const nonBodyParams = [];
+		let bodyParam;
+		let firstBodyName;
+		let usesFormData = false;
+		for (const [index, param] of params.entries()) {
+			if (!isObject(param)) {
+				nonBodyParams.push(param);
+				continue;
+			}
+			const resolvedParam = resolveSwaggerParameter(param, doc);
+			const location = resolvedParam.in;
+			if (location === "body") {
+				if (bodyParam !== void 0) {
+					const duplicateName = typeof resolvedParam.name === "string" ? resolvedParam.name : `parameters[${String(index)}]`;
+					emitDiagnostic(diagnostics, {
+						code: "duplicate-body-parameter",
+						message: `Operation defines more than one "in: body" parameter; keeping the first ("${firstBodyName ?? "(unnamed)"}") and discarding "${duplicateName}"`,
+						pointer: appendPointer(appendPointer(appendPointer(appendPointer("", "paths"), path), method), "parameters"),
+						detail: {
+							kept: firstBodyName,
+							discarded: duplicateName,
+							location: "operation"
+						}
+					});
+					continue;
+				}
+				bodyParam = resolvedParam;
+				firstBodyName = typeof resolvedParam.name === "string" ? resolvedParam.name : void 0;
+			} else if (location === "formData") {
+				if (!usesFormData) {
+					bodyParam = buildFormDataBody(resolvedParam, params);
+					usesFormData = true;
+				}
+			} else nonBodyParams.push(normaliseSwaggerParameter(resolvedParam, doc));
+		}
+		if (nonBodyParams.length > 0) result.parameters = nonBodyParams;
+		if (bodyParam !== void 0) result.requestBody = buildRequestBody(bodyParam, usesFormData ? formDataContentTypes(consumes) : consumes);
+	}
+	const responses = operation.responses;
+	if (isObject(responses)) result.responses = normaliseSwaggerResponses(responses, doc, produces);
+	return result;
+}
+/**
+* Determine the request body media type for a Swagger 2.0 formData operation.
+*
+* Per the OAS 3 conversion rules, `application/x-www-form-urlencoded` is
+* preferred when the operation- or document-level `consumes` includes it;
+* otherwise `multipart/form-data` is the default. File uploads (Swagger 2.0
+* `type: file`) still require `multipart/form-data`, but the formData body
+* schema-builder normalises them to `string` + `format: binary` either way
+* and the choice of media type is left to the source document.
+*/
+function formDataContentTypes(consumes) {
+	if (consumes.includes("application/x-www-form-urlencoded")) return ["application/x-www-form-urlencoded"];
+	return ["multipart/form-data"];
+}
+/**
+* Resolve a Swagger parameter that may be a `$ref`.
+*/
+function resolveSwaggerParameter(param, doc, visited = /* @__PURE__ */ new Set()) {
+	const ref = param.$ref;
+	if (typeof ref !== "string" || !ref.startsWith("#/parameters/")) return param;
+	if (visited.has(ref)) return param;
+	const nextVisited = new Set(visited);
+	nextVisited.add(ref);
+	const name = ref.slice(13);
+	const globalParams = doc.parameters;
+	if (isObject(globalParams)) {
+		const resolved = globalParams[name];
+		if (isObject(resolved)) {
+			if (typeof resolved.$ref === "string") return resolveSwaggerParameter(resolved, doc, nextVisited);
+			return resolved;
+		}
+	}
+	return param;
+}
+/**
+* Normalise a single Swagger parameter to OpenAPI 3.x form.
+*/
+function normaliseSwaggerParameter(param, doc) {
+	if (typeof param.$ref === "string") {
+		const resolved = resolveSwaggerParameter(param, doc);
+		if (resolved !== param) return normaliseSwaggerParameter(resolved, doc);
+	}
+	const result = {};
+	for (const [key, value] of Object.entries(param)) {
+		if (key === "type" || key === "format" || key === "collectionFormat") continue;
+		result[key] = value;
+	}
+	if (typeof param.type === "string") {
+		const schema = { type: param.type };
+		if (typeof param.format === "string") schema.format = param.format;
+		if (param.enum !== void 0) schema.enum = param.enum;
+		if (param.default !== void 0) schema.default = param.default;
+		if (param.minimum !== void 0) schema.minimum = param.minimum;
+		if (param.maximum !== void 0) schema.maximum = param.maximum;
+		result.schema = schema;
+	}
+	const cf = param.collectionFormat;
+	if (typeof cf === "string") switch (cf) {
+		case "csv":
+			result.style = "form";
+			result.explode = false;
+			break;
+		case "ssv":
+			result.style = "spaceDelimited";
+			result.explode = false;
+			break;
+		case "tsv":
+			result.style = "tabDelimited";
+			result.explode = false;
+			break;
+		case "pipes":
+			result.style = "pipeDelimited";
+			result.explode = false;
+			break;
+		case "multi":
+			result.style = "form";
+			result.explode = true;
+			break;
+	}
+	return result;
+}
+/**
+* Build a request body from a `formData` parameter.
+*/
+function buildFormDataBody(param, allParams) {
+	const properties = {};
+	const required = [];
+	for (const p of allParams) {
+		if (!isObject(p) || p.in !== "formData") continue;
+		const name = p.name;
+		if (typeof name !== "string") continue;
+		const schema = {};
+		if (p.type === "file") {
+			schema.type = "string";
+			schema.format = "binary";
+		} else {
+			if (typeof p.type === "string") schema.type = p.type;
+			if (typeof p.format === "string") schema.format = p.format;
+			if (p.enum !== void 0) schema.enum = p.enum;
+		}
+		properties[name] = schema;
+		if (p.required === true) required.push(name);
+	}
+	return {
+		name: param.name,
+		in: "body",
+		schema: {
+			type: "object",
+			properties,
+			...required.length > 0 ? { required } : {}
+		}
+	};
+}
+/**
+* Build an OpenAPI 3.x request body from a Swagger 2.0 body parameter.
+*/
+function buildRequestBody(bodyParam, consumes) {
+	const schema = bodyParam.schema;
+	const content = {};
+	const contentTypes = consumes.length > 0 ? consumes : ["application/json"];
+	for (const ct of contentTypes) if (typeof ct === "string") content[ct] = isObject(schema) ? { schema } : {};
+	const result = { content };
+	if (bodyParam.required === true) result.required = true;
+	if (typeof bodyParam.description === "string") result.description = bodyParam.description;
+	return result;
+}
+/**
+* Resolve a Swagger 2.0 response `$ref` (e.g. `#/responses/NotFound`).
+*/
+function resolveSwaggerResponse(response, doc, visited = /* @__PURE__ */ new Set()) {
+	const ref = response.$ref;
+	if (typeof ref !== "string" || !ref.startsWith("#/responses/")) return response;
+	if (visited.has(ref)) return response;
+	const nextVisited = new Set(visited);
+	nextVisited.add(ref);
+	const name = ref.slice(12);
+	const globalResponses = doc.responses;
+	if (isObject(globalResponses)) {
+		const resolved = globalResponses[name];
+		if (isObject(resolved)) {
+			if (typeof resolved.$ref === "string") return resolveSwaggerResponse(resolved, doc, nextVisited);
+			return resolved;
+		}
+	}
+	return response;
+}
+function normaliseSwaggerResponses(responses, doc, produces) {
+	const result = {};
+	for (const [code, response] of Object.entries(responses)) {
+		if (!isObject(response)) {
+			result[code] = response;
+			continue;
+		}
+		result[code] = normaliseSwaggerSingleResponse(response, doc, produces);
+	}
+	return result;
+}
+/**
+* Normalise a single Swagger 2.0 response object — resolves any `$ref` to
+* `#/responses/<Name>` and wraps a top-level `schema` in an OpenAPI 3.x
+* `content` map keyed by the supplied media types.
+*
+* Extracted so the same logic applies whether the response sits inside an
+* operation’s `responses` map or under document-level `responses`
+* (now `components.responses`).
+*/
+function normaliseSwaggerSingleResponse(response, doc, produces) {
+	const resolved = resolveSwaggerResponse(response, doc);
+	const normalised = {};
+	for (const [key, value] of Object.entries(resolved)) if (key !== "schema" && key !== "headers") normalised[key] = value;
+	const schema = resolved.schema;
+	if (isObject(schema)) {
+		const content = {};
+		const contentTypes = produces.length > 0 ? produces : ["application/json"];
+		for (const ct of contentTypes) if (typeof ct === "string") content[ct] = { schema };
+		normalised.content = content;
+	}
+	const headers = resolved.headers;
+	if (isObject(headers)) {
+		const convertedHeaders = {};
+		for (const [name, header] of Object.entries(headers)) convertedHeaders[name] = isObject(header) ? normaliseSwaggerHeader(header) : header;
+		normalised.headers = convertedHeaders;
+	}
+	return normalised;
+}
+/**
+* Normalise a single Swagger 2.0 response header to OpenAPI 3.x form.
+*
+* Swagger 2.0 headers mirror parameter shape: `type`/`format`/
+* `collectionFormat` live at the root. OpenAPI 3.x requires the type
+* descriptor under `schema`, with collection serialisation expressed via
+* `style`/`explode`. Headers do not carry `name` or `in` — those are not
+* part of either spec at this level — so this is a thin sibling to
+* `normaliseSwaggerParameter` rather than a full reuse. The OpenAPI 3.x
+* default header style is `simple`, so CSV-encoded headers map to
+* `simple`/`explode: false` rather than the `form` style used for query
+* parameters.
+*/
+function normaliseSwaggerHeader(header) {
+	const result = {};
+	for (const [key, value] of Object.entries(header)) {
+		if (key === "type" || key === "format" || key === "collectionFormat") continue;
+		result[key] = value;
+	}
+	if (typeof header.type === "string") {
+		const schema = { type: header.type };
+		if (typeof header.format === "string") schema.format = header.format;
+		if (header.enum !== void 0) schema.enum = header.enum;
+		if (header.default !== void 0) schema.default = header.default;
+		if (header.minimum !== void 0) schema.minimum = header.minimum;
+		if (header.maximum !== void 0) schema.maximum = header.maximum;
+		result.schema = schema;
+	}
+	const cf = header.collectionFormat;
+	if (typeof cf === "string") switch (cf) {
+		case "csv":
+			result.style = "simple";
+			result.explode = false;
+			break;
+		case "ssv":
+			result.style = "spaceDelimited";
+			result.explode = false;
+			break;
+		case "tsv":
+			result.style = "tabDelimited";
+			result.explode = false;
+			break;
+		case "pipes":
+			result.style = "pipeDelimited";
+			result.explode = false;
+			break;
+	}
+	return result;
+}
+/**
+* Mapping of Swagger 2.0 $ref prefixes to OpenAPI 3.x equivalents.
+* Applied after document restructuring so all $ref strings point
+* to the correct locations in the normalised document.
+*/
+const REF_REWRITES = [
+	["#/definitions/", "#/components/schemas/"],
+	["#/parameters/", "#/components/parameters/"],
+	["#/responses/", "#/components/responses/"]
+];
+/**
+* Deep-rewrite $ref strings in a normalised Swagger 2.0 document
+* from Swagger 2.0 locations to OpenAPI 3.x locations.
+* Mutates the object in place \u2014 called only on the fresh clone
+* produced by normaliseSwagger2Document.
+*/
+function rewriteSwaggerRefs(node) {
+	if (!isObject(node)) return;
+	if (typeof node.$ref === "string") {
+		for (const [from, to] of REF_REWRITES) if (node.$ref.startsWith(from)) {
+			node.$ref = to + node.$ref.slice(from.length);
+			break;
+		}
+	}
+	for (const value of Object.values(node)) if (isObject(value)) rewriteSwaggerRefs(value);
+	else if (Array.isArray(value)) for (const item of value) rewriteSwaggerRefs(item);
+}
+/**
+* Recursively check whether any node in the supplied subtree carries an
+* `xml` annotation. Walks both objects and arrays so the check works for
+* schemas (definitions, parameter schemas, response schemas, request body
+* schemas) as well as operations and parameters that may carry `xml`
+* metadata at any depth.
+*/
+function hasXmlAnywhere(node) {
+	if (!isObject(node)) {
+		if (Array.isArray(node)) {
+			for (const item of node) if (hasXmlAnywhere(item)) return true;
+		}
+		return false;
+	}
+	if ("xml" in node) return true;
+	for (const value of Object.values(node)) if (hasXmlAnywhere(value)) return true;
+	return false;
+}
+//#endregion
+//#region src/core/normalise.ts
+/**
+* Keys whose values are `Record<string, SubSchema>` — objects where each
+* property is a sub-schema.
+*/
+const OBJECT_SUBSCHEMA_KEYS = new Set([
+	"properties",
+	"patternProperties",
+	"$defs",
+	"definitions",
+	"dependentSchemas"
+]);
+/**
+* Keys whose values are `SubSchema[]` — arrays of sub-schemas.
+*/
+const ARRAY_SUBSCHEMA_KEYS = new Set([
+	"allOf",
+	"anyOf",
+	"oneOf",
+	"prefixItems"
+]);
+/**
+* Keys whose values are a single sub-schema object.
+*/
+const SINGLE_SUBSCHEMA_KEYS = new Set([
+	"additionalProperties",
+	"not",
+	"contains",
+	"propertyNames",
+	"if",
+	"then",
+	"else",
+	"unevaluatedProperties",
+	"unevaluatedItems"
+]);
+/**
+* Normalise each element of an unknown array by applying deepNormalise
+* to object elements and passing others through unchanged.
+*/
+function normaliseArray(items, transform) {
+	const result = [];
+	for (const item of items) result.push(isObject(item) ? deepNormalise(item, transform) : item);
+	return result;
+}
+/**
+* Normalise each value of a sub-schema map (e.g. properties, $defs).
+*/
+function normaliseSubSchemaMap(map, transform) {
+	const result = {};
+	for (const [k, v] of Object.entries(map)) result[k] = isObject(v) ? deepNormalise(v, transform) : v;
+	return result;
+}
+/**
+* Deep-normalise a JSON Schema object by applying a per-node transform
+* and recursing into every sub-schema location.
+*/
+function deepNormalise(schema, transform) {
+	const node = transform({ ...schema });
+	const result = {};
+	for (const [key, value] of Object.entries(node)) if (isObject(value) && OBJECT_SUBSCHEMA_KEYS.has(key)) result[key] = normaliseSubSchemaMap(value, transform);
+	else if (Array.isArray(value) && ARRAY_SUBSCHEMA_KEYS.has(key)) result[key] = normaliseArray(value, transform);
+	else if (isObject(value) && SINGLE_SUBSCHEMA_KEYS.has(key)) result[key] = deepNormalise(value, transform);
+	else if (key === "items") if (Array.isArray(value)) result[key] = normaliseArray(value, transform);
+	else if (isObject(value)) result[key] = deepNormalise(value, transform);
+	else result[key] = value;
+	else if (key === "dependencies" && isObject(value)) {
+		const normalised = {};
+		for (const [dk, dv] of Object.entries(value)) if (isObject(dv)) normalised[dk] = deepNormalise(dv, transform);
+		else normalised[dk] = dv;
+		result[key] = normalised;
+	} else result[key] = value;
+	return result;
+}
+function normaliseArrayWithContext(items, transform, ctx) {
+	const result = [];
+	for (let i = 0; i < items.length; i++) {
+		const item = items[i];
+		if (isObject(item)) result.push(deepNormaliseWithContext(item, transform, {
+			diagnostics: ctx.diagnostics,
+			pointer: appendPointer(ctx.pointer, String(i))
+		}));
+		else result.push(item);
+	}
+	return result;
+}
+function normaliseSubSchemaMapWithContext(map, transform, ctx) {
+	const result = {};
+	for (const [k, v] of Object.entries(map)) if (isObject(v)) result[k] = deepNormaliseWithContext(v, transform, {
+		diagnostics: ctx.diagnostics,
+		pointer: appendPointer(ctx.pointer, k)
+	});
+	else result[k] = v;
+	return result;
+}
+/**
+* Deep-normalise a JSON Schema object, threading a context (diagnostics
+* sink + JSON Pointer) through each recursive call. Used by the JSON
+* Schema normalisation path so per-node transforms can emit diagnostics
+* with accurate pointers.
+*
+* Mirrors `deepNormalise` structurally — keep the two in sync when
+* adding new sub-schema locations.
+*/
+function deepNormaliseWithContext(schema, transform, ctx) {
+	const node = transform({ ...schema }, ctx);
+	const result = {};
+	for (const [key, value] of Object.entries(node)) if (isObject(value) && OBJECT_SUBSCHEMA_KEYS.has(key)) result[key] = normaliseSubSchemaMapWithContext(value, transform, {
+		diagnostics: ctx.diagnostics,
+		pointer: appendPointer(ctx.pointer, key)
+	});
+	else if (Array.isArray(value) && ARRAY_SUBSCHEMA_KEYS.has(key)) result[key] = normaliseArrayWithContext(value, transform, {
+		diagnostics: ctx.diagnostics,
+		pointer: appendPointer(ctx.pointer, key)
+	});
+	else if (isObject(value) && SINGLE_SUBSCHEMA_KEYS.has(key)) result[key] = deepNormaliseWithContext(value, transform, {
+		diagnostics: ctx.diagnostics,
+		pointer: appendPointer(ctx.pointer, key)
+	});
+	else if (key === "items") if (Array.isArray(value)) result[key] = normaliseArrayWithContext(value, transform, {
+		diagnostics: ctx.diagnostics,
+		pointer: appendPointer(ctx.pointer, key)
+	});
+	else if (isObject(value)) result[key] = deepNormaliseWithContext(value, transform, {
+		diagnostics: ctx.diagnostics,
+		pointer: appendPointer(ctx.pointer, key)
+	});
+	else result[key] = value;
+	else if (key === "dependencies" && isObject(value)) {
+		const normalised = {};
+		const depsPointer = appendPointer(ctx.pointer, key);
+		for (const [dk, dv] of Object.entries(value)) if (isObject(dv)) normalised[dk] = deepNormaliseWithContext(dv, transform, {
+			diagnostics: ctx.diagnostics,
+			pointer: appendPointer(depsPointer, dk)
+		});
+		else normalised[dk] = dv;
+		result[key] = normalised;
+	} else result[key] = value;
+	return result;
+}
+/**
+* Walk an array of supposed required-property names. Each non-string
+* element triggers a `dependent-required-invalid` diagnostic against
+* the supplied context. Returns the collected string entries when
+* every element validates, or `undefined` when at least one entry
+* was invalid (signalling the caller should drop the property
+* entirely rather than emit a partial rewrite).
+*
+* `keyword` distinguishes diagnostics that originate from the legacy
+* `dependencies` keyword versus the modern `dependentRequired`.
+*/
+function collectDependencyStrings(items, property, keyword, ctx) {
+	const strings = [];
+	let sawInvalid = false;
+	for (let i = 0; i < items.length; i++) {
+		const item = items[i];
+		if (typeof item === "string") {
+			strings.push(item);
+			continue;
+		}
+		sawInvalid = true;
+		if (ctx === void 0) continue;
+		emitDiagnostic(ctx.diagnostics, {
+			code: "dependent-required-invalid",
+			message: `\`${keyword}.${property}[${String(i)}]\` is not a string; only string property names are valid in a required-dependency array`,
+			pointer: appendPointer(appendPointer(appendPointer(ctx.pointer, keyword), property), String(i)),
+			detail: {
+				property,
+				index: i,
+				value: item
+			}
+		});
+	}
+	return sawInvalid ? void 0 : strings;
+}
+/**
+* Split the legacy `dependencies` keyword into `dependentRequired` and
+* `dependentSchemas` per the Draft 2019-09+ replacement.
+*
+* Each key in `dependencies` maps to either:
+* - `string[]` → `dependentRequired`
+* - A schema object → `dependentSchemas`
+*
+* Both forms can coexist within the same `dependencies` object.
+* After splitting, `dependencies` is removed from the node.
+*
+* When `ctx` is supplied, diagnostics are emitted for:
+* - `legacy-dependencies-split` once per node that contained the
+*   deprecated keyword (callers pass this only on draft paths where
+*   the keyword is unexpected, e.g. 2020-12).
+* - `dependent-required-invalid` for each array entry whose element is
+*   not a string.
+*/
+function splitDependencies(node, ctx, emitLegacyDiagnostic) {
+	const deps = node.dependencies;
+	if (!isObject(deps)) return;
+	if (emitLegacyDiagnostic && ctx !== void 0) emitDiagnostic(ctx.diagnostics, {
+		code: "legacy-dependencies-split",
+		message: "Legacy `dependencies` keyword was split into `dependentRequired`/`dependentSchemas`; `dependencies` was deprecated in Draft 2019-09",
+		pointer: appendPointer(ctx.pointer, "dependencies"),
+		detail: { keys: Object.keys(deps) }
+	});
+	const requiredEntries = {};
+	const schemaEntries = {};
+	for (const [key, value] of Object.entries(deps)) if (Array.isArray(value)) {
+		const accepted = collectDependencyStrings(value, key, "dependencies", ctx);
+		if (accepted !== void 0) requiredEntries[key] = accepted;
+	} else if (isObject(value)) schemaEntries[key] = value;
+	if (Object.keys(requiredEntries).length > 0) {
+		const existing = node.dependentRequired;
+		if (isObject(existing)) for (const [k, v] of Object.entries(requiredEntries)) existing[k] = v;
+		else node.dependentRequired = requiredEntries;
+	}
+	if (Object.keys(schemaEntries).length > 0) {
+		const existing = node.dependentSchemas;
+		if (isObject(existing)) for (const [k, v] of Object.entries(schemaEntries)) existing[k] = v;
+		else node.dependentSchemas = schemaEntries;
+	}
+	delete node.dependencies;
+}
+/**
+* Emit diagnostics for any non-string entries inside a pre-existing
+* `dependentRequired` keyword. Used on draft paths where the author may
+* have already migrated to the Draft 2019-09 form but still produced
+* invalid array entries. The keyword value is not rewritten — the
+* walker is responsible for honouring (or rejecting) the constraint.
+*/
+function validateDependentRequired(node, ctx) {
+	if (ctx === void 0) return;
+	const dr = node.dependentRequired;
+	if (!isObject(dr)) return;
+	for (const [key, value] of Object.entries(dr)) {
+		if (!Array.isArray(value)) continue;
+		collectDependencyStrings(value, key, "dependentRequired", ctx);
+	}
+}
+/**
+* Apply the version-agnostic Draft 04 keyword translations to a single
+* node: boolean exclusive-min/max → number form, bare `id` → `$id`, and
+* tuple-form `items` → `prefixItems`.
+*
+* `divisibleBy` is also translated to `multipleOf` (a Draft 03 carryover
+* that legitimately appears in legacy Draft 04 schemas). When `ctx` is
+* supplied and both keywords are present with conflicting values, a
+* `divisible-by-conflict` diagnostic is emitted.
+*
+* `dependencies` is split into `dependentRequired`/`dependentSchemas`
+* via {@link splitDependencies}; passing `ctx` enables per-entry
+* diagnostics for non-string array members.
+*/
+function applyDraft04Translations(node, ctx) {
+	if (node.exclusiveMinimum === true && typeof node.minimum === "number") {
+		node.exclusiveMinimum = node.minimum;
+		delete node.minimum;
+	} else if (node.exclusiveMinimum === false) delete node.exclusiveMinimum;
+	else if (node.exclusiveMinimum === true) {
+		if (ctx !== void 0) emitDiagnostic(ctx.diagnostics, {
+			code: "bare-exclusive-bound",
+			message: "`exclusiveMinimum: true` requires a sibling numeric `minimum` in Draft 04; dropping the keyword",
+			pointer: appendPointer(ctx.pointer, "exclusiveMinimum"),
+			detail: { keyword: "exclusiveMinimum" }
+		});
+		delete node.exclusiveMinimum;
+	}
+	if (node.exclusiveMaximum === true && typeof node.maximum === "number") {
+		node.exclusiveMaximum = node.maximum;
+		delete node.maximum;
+	} else if (node.exclusiveMaximum === false) delete node.exclusiveMaximum;
+	else if (node.exclusiveMaximum === true) {
+		if (ctx !== void 0) emitDiagnostic(ctx.diagnostics, {
+			code: "bare-exclusive-bound",
+			message: "`exclusiveMaximum: true` requires a sibling numeric `maximum` in Draft 04; dropping the keyword",
+			pointer: appendPointer(ctx.pointer, "exclusiveMaximum"),
+			detail: { keyword: "exclusiveMaximum" }
+		});
+		delete node.exclusiveMaximum;
+	}
+	const divisibleBy = node.divisibleBy;
+	if (typeof divisibleBy === "number") {
+		const multipleOf = node.multipleOf;
+		if (typeof multipleOf === "number") {
+			if (ctx !== void 0 && divisibleBy !== multipleOf) emitDiagnostic(ctx.diagnostics, {
+				code: "divisible-by-conflict",
+				message: `Legacy \`divisibleBy\` (${String(divisibleBy)}) conflicts with \`multipleOf\` (${String(multipleOf)}); keeping \`multipleOf\``,
+				pointer: ctx.pointer,
+				detail: {
+					divisibleBy,
+					multipleOf
+				}
+			});
+		} else node.multipleOf = divisibleBy;
+		delete node.divisibleBy;
+	}
+	if (typeof node.id === "string" && !("$id" in node)) {
+		node.$id = node.id;
+		delete node.id;
+	}
+	if (Array.isArray(node.items) && !("prefixItems" in node)) {
+		node.prefixItems = node.items;
+		delete node.items;
+		if ("additionalItems" in node) {
+			node.items = node.additionalItems;
+			delete node.additionalItems;
+		}
+	}
+	splitDependencies(node, ctx, false);
+	validateDependentRequired(node, ctx);
+}
+/**
+* Normalise Draft 04 `exclusiveMinimum`/`exclusiveMaximum` from boolean
+* to number form, plus the other Draft 04 translations applied to a
+* single node.
+*
+* In Draft 04:
+* - `exclusiveMinimum: true` + `minimum: 5` → value must be > 5
+* - `exclusiveMinimum: false` (or absent) + `minimum: 5` → value must be >= 5
+*
+* In Draft 06+:
+* - `exclusiveMinimum: 5` → value must be > 5 (no separate `minimum`)
+* - `minimum: 5` → value must be >= 5
+*
+* The transform converts boolean form to number form so the walker can
+* treat `exclusiveMinimum`/`exclusiveMaximum` uniformly as numbers.
+*
+* This function preserves the no-context signature for the OpenAPI 3.0
+* and Swagger 2.0 normalisers that compose it directly. The JSON Schema
+* normalisation path uses {@link normaliseDraft04NodeWithContext} via
+* {@link deepNormaliseWithContext} to thread diagnostics.
+*/
+function normaliseDraft04Node(node) {
+	applyDraft04Translations(node, void 0);
+	return node;
+}
+/**
+* Context-aware Draft 04 per-node transform. Identical to
+* {@link normaliseDraft04Node} but threads a {@link NodeContext} so
+* `divisibleBy`/`multipleOf` conflicts and invalid dependency entries
+* can be surfaced as diagnostics with accurate pointers.
+*/
+function normaliseDraft04NodeWithContext(node, ctx) {
+	applyDraft04Translations(node, ctx);
+	return node;
+}
+/**
+* Normalise Draft 06/07 nodes.
+*
+* These drafts introduced `exclusiveMinimum`/`exclusiveMaximum` as numbers
+* (already in final form) and `const`/`examples`, but still use the
+* legacy `dependencies` keyword. Split it into `dependentRequired` /
+* `dependentSchemas` so the walker can process them uniformly.
+*/
+function normaliseDraft06Or07NodeWithContext(node, ctx) {
+	splitDependencies(node, ctx, false);
+	validateDependentRequired(node, ctx);
+	return node;
+}
+/**
+* Normalise Draft 2019-09 `$recursiveRef` to `$ref`.
+*
+* `$recursiveRef` resolves to the nearest `$recursiveAnchor` in the
+* dynamic scope. For rendering, the common pattern is a root
+* `$recursiveAnchor: true` — the normaliser converts
+* `$recursiveRef: "#"` to `$ref: "#"` pointing to the root.
+*
+* The original `$recursiveRef` value is preserved (rather than
+* collapsed to `"#"`) so that anchored variants such as
+* `$recursiveRef: "#meta"` resolve correctly against the
+* corresponding `$recursiveAnchor` name. String-valued
+* `$recursiveAnchor` names are likewise preserved as `$anchor`.
+*/
+function normaliseDraft201909NodeWithContext(node, ctx) {
+	if (typeof node.$recursiveRef === "string") {
+		node.$ref = node.$recursiveRef;
+		delete node.$recursiveRef;
+	}
+	if (node.$recursiveAnchor === true) {
+		if (typeof node.$anchor !== "string") node.$anchor = "__recursive__";
+		delete node.$recursiveAnchor;
+	} else if (typeof node.$recursiveAnchor === "string") {
+		if (typeof node.$anchor !== "string") node.$anchor = node.$recursiveAnchor;
+		delete node.$recursiveAnchor;
+	}
+	validateDependentRequired(node, ctx);
+	return node;
+}
+function normaliseDynamicRefNodeWithContext(node, ctx) {
+	if (typeof node.$dynamicRef === "string") {
+		node.$ref = node.$dynamicRef;
+		delete node.$dynamicRef;
+	}
+	if (typeof node.$dynamicAnchor === "string") {
+		if (typeof node.$anchor !== "string") node.$anchor = node.$dynamicAnchor;
+		delete node.$dynamicAnchor;
+	}
+	splitDependencies(node, ctx, true);
+	validateDependentRequired(node, ctx);
+	return node;
+}
+/**
+* Normalise a JSON Schema to canonical Draft 2020-12 form.
+* Deep-clones the input — the original is never mutated.
+*
+* When `diagnostics` is supplied, per-node transforms emit diagnostics
+* for legacy-keyword rewrites and invalid constructs (e.g. `divisibleBy`
+* conflicts, non-string entries in a `dependentRequired` array, legacy
+* `dependencies` reaching the 2020-12 path).
+*/
+function normaliseJsonSchema(schema, draft, diagnostics) {
+	const ctx = {
+		diagnostics,
+		pointer: ""
+	};
+	let normalised;
+	switch (draft) {
+		case "draft-04":
+			normalised = deepNormaliseWithContext(schema, normaliseDraft04NodeWithContext, ctx);
+			break;
+		case "draft-2019-09":
+			normalised = deepNormaliseWithContext(schema, normaliseDraft201909NodeWithContext, ctx);
+			break;
+		case "draft-2020-12":
+			normalised = deepNormaliseWithContext(schema, normaliseDynamicRefNodeWithContext, ctx);
+			break;
+		case "draft-06":
+		case "draft-07":
+			normalised = deepNormaliseWithContext(schema, normaliseDraft06Or07NodeWithContext, ctx);
+			break;
+	}
+	return resolveRelativeRefs(normalised, diagnostics);
+}
+/**
+* Parse a string as an absolute URI, returning `undefined` when it has
+* no scheme. Used to detect whether an `$id` value defines a base URI.
+*/
+function parseAbsoluteUri(value) {
+	if (typeof value !== "string" || value.length === 0) return void 0;
+	try {
+		const url = new URL(value);
+		if (url.protocol.length === 0) return void 0;
+		return url;
+	} catch {
+		return;
+	}
+}
+/**
+* Resolve a relative reference against a base URI. Returns `undefined`
+* when the reference cannot be resolved (e.g. malformed input).
+*/
+function resolveAgainst(ref, base) {
+	try {
+		return new URL(ref, base);
+	} catch {
+		return;
+	}
+}
+/**
+* Strip the fragment portion from a URL, returning the canonical
+* `scheme://authority/path?query` form. Used to compare a resolved
+* `$ref` URI against the document's `$id` base.
+*/
+function stripFragment(url) {
+	const clone = new URL(url.toString());
+	clone.hash = "";
+	return clone.toString();
+}
+/**
+* Recursively rewrite relative `$ref`s in a schema so they resolve
+* correctly under the JSON Schema base-URI rules (RFC 3986 + JSON
+* Schema §8.2). Refs that resolve to the document's own `$id` are
+* rewritten to fragment-only form so the existing dereferencer can
+* handle them; refs that resolve outside the document are left as
+* absolute URIs (handled by the external resolver path).
+*
+* Returns the input unchanged when the document has no base URI or
+* no relative refs.
+*/
+function resolveRelativeRefs(schema, diagnostics) {
+	const docBaseUrl = parseAbsoluteUri(schema.$id);
+	if (docBaseUrl === void 0) return schema;
+	const docBase = stripFragment(docBaseUrl);
+	return rewriteRelativeRefsNode(schema, docBase, docBase, "", diagnostics);
+}
+function rewriteRelativeRefsNode(node, currentBase, docBase, pointer, diagnostics) {
+	let nextBase = currentBase;
+	const nodeId = node.$id;
+	if (typeof nodeId === "string" && nodeId.length > 0) {
+		const resolved = resolveAgainst(nodeId, currentBase);
+		if (resolved !== void 0) nextBase = stripFragment(resolved);
+	}
+	const result = {};
+	for (const [key, value] of Object.entries(node)) {
+		if (key === "$ref" && typeof value === "string") {
+			result[key] = rewriteRef(value, nextBase, docBase, appendPointer(pointer, key), diagnostics);
+			continue;
+		}
+		result[key] = rewriteRelativeRefsValue(value, key, nextBase, docBase, appendPointer(pointer, key), diagnostics);
+	}
+	return result;
+}
+function rewriteRelativeRefsValue(value, parentKey, currentBase, docBase, pointer, diagnostics) {
+	if (Array.isArray(value)) return value.map((item, i) => rewriteRelativeRefsValue(item, parentKey, currentBase, docBase, appendPointer(pointer, String(i)), diagnostics));
+	if (isObject(value)) return rewriteRelativeRefsNode(value, currentBase, docBase, pointer, diagnostics);
+	return value;
+}
+/**
+* Rewrite a single `$ref` string. Fragment-only refs and refs that
+* already include a scheme are returned unchanged. Relative refs are
+* resolved against `currentBase`; if the result lives in the same
+* document as `docBase`, the ref is rewritten to fragment form.
+*/
+function rewriteRef(ref, currentBase, docBase, pointer, diagnostics) {
+	if (ref.startsWith("#")) return ref;
+	if (/^[a-z][a-z0-9+\-.]*:/i.test(ref)) return ref;
+	const resolved = resolveAgainst(ref, currentBase);
+	if (resolved === void 0) return ref;
+	if (stripFragment(resolved) === docBase) {
+		const fragment = resolved.hash === "" ? "#" : resolved.hash;
+		emitDiagnostic(diagnostics, {
+			code: "relative-ref-resolved",
+			message: `Relative $ref "${ref}" resolved to "${fragment}" against base "${currentBase}"`,
+			pointer,
+			detail: {
+				ref,
+				base: currentBase,
+				resolved: fragment
+			}
+		});
+		return fragment;
+	}
+	const absolute = resolved.toString();
+	emitDiagnostic(diagnostics, {
+		code: "relative-ref-resolved",
+		message: `Relative $ref "${ref}" resolved to "${absolute}" against base "${currentBase}"`,
+		pointer,
+		detail: {
+			ref,
+			base: currentBase,
+			resolved: absolute
+		}
+	});
+	return absolute;
+}
+/**
+* Normalise an OpenAPI document's schemas for walker consumption.
+* Handles version-specific keyword transformations.
+*
+* Returns the same object reference if no normalisation is needed
+* (OpenAPI 3.1.x), or a deep-cloned normalised copy otherwise.
+*/
+function normaliseOpenApiSchemas(doc, version, diagnostics) {
+	if (isSwagger2(version)) return normaliseSwagger2Document(doc, deepNormalise, normaliseDraft04Node, diagnostics);
+	if (isOpenApi30(version)) return deepNormaliseOpenApi30Doc(doc, deepNormalise);
+	if (isOpenApi31(version)) {
+		const dialect = readJsonSchemaDialect(doc);
+		if (dialect.kind === "unknown") emitDiagnostic(diagnostics, {
+			code: "unknown-json-schema-dialect",
+			message: `OpenAPI 3.1 \`jsonSchemaDialect\` URI "${dialect.uri}" does not match a supported JSON Schema draft; falling back to Draft 2020-12`,
+			pointer: "/jsonSchemaDialect",
+			detail: { uri: dialect.uri }
+		});
+	}
+	return deepNormaliseOpenApiDoc(doc, (schema) => deepNormalise(schema, normaliseOpenApi30Discriminator));
+}
+//#endregion
+export { normaliseOpenApiSchemas as a, deepNormaliseOpenApiDoc as c, normaliseOpenApi30Node as d, normaliseJsonSchema as i, normaliseOpenApi30Combined as l, deepNormaliseWithContext as n, normaliseSwagger2Document as o, normaliseDraft04Node as r, deepNormaliseOpenApi30Doc as s, deepNormalise as t, normaliseOpenApi30Discriminator as u };