schema-components 1.20.0 → 1.22.0

package/dist/{normalise-CMMEl4cd.mjs → normalise-DVEJQmF7.mjs}

@@ -29,6 +29,8 @@ function normaliseOpenApi30Node(node) {
 		return node;
 	}
 	const nullOption = { type: "null" };
+	if (typeof node.$ref === "string") return { anyOf: [{ $ref: node.$ref }, nullOption] };
+	if (Array.isArray(node.enum) && !node.enum.includes(null)) node.enum = [...node.enum, null];
 	if (Array.isArray(node.anyOf)) {
 		node.anyOf = [...node.anyOf, nullOption];
 		delete node.nullable;
@@ -113,10 +115,270 @@ function normaliseOpenApi30Discriminator(node) {
 	}
 	if ("oneOf" in node) node.oneOf = normalisedComposite;
 	else if ("anyOf" in node) node.anyOf = normalisedComposite;
-	delete node.discriminator;
+	const extensions = {};
+	for (const [key, value] of Object.entries(discriminator)) if (key.startsWith("x-")) extensions[key] = value;
+	if (Object.keys(extensions).length > 0) node.discriminator = {
+		propertyName,
+		...extensions
+	};
+	else delete node.discriminator;
 	return node;
 }
 /**
+* Returns the schema name a `$ref` points at when it targets
+* `#/components/schemas/<Name>`, or `undefined` otherwise.
+*
+* The walker only resolves intra-document refs and other allOf-base
+* patterns; refs into `definitions` (Swagger 2.0) are already rewritten
+* before this stage.
+*/
+function componentSchemaName(ref) {
+	if (typeof ref !== "string") return void 0;
+	if (!ref.startsWith("#/components/schemas/")) return void 0;
+	const name = ref.slice(21);
+	return name.length > 0 ? name : void 0;
+}
+/**
+* Find every immediate `$ref` that an `allOf` array contains pointing
+* back at a `components/schemas/<Name>` entry. Used to discover
+* "Cat extends Pet"-style inheritance — the subtype's `allOf` lists
+* the base by `$ref` alongside its own local fields.
+*/
+function listAllOfBaseRefs(schema) {
+	const allOf = schema.allOf;
+	if (!Array.isArray(allOf)) return [];
+	const result = [];
+	for (const entry of allOf) {
+		if (!isObject(entry)) continue;
+		const name = componentSchemaName(entry.$ref);
+		if (name !== void 0) result.push(name);
+	}
+	return result;
+}
+/**
+* Collect discriminator subtypes for a base schema. Entries come from:
+*
+* 1. The base's `discriminator.mapping` (explicit author intent — the
+*    mapping key supplies the `const` value, the ref names the subtype).
+* 2. Component schemas whose `allOf` lists this base by `$ref` and
+*    were not already named in the mapping. The `const` value defaults
+*    to the subtype's component name.
+*
+* Returned in deterministic order: mapping entries first (preserving
+* authored order), then implicit subtypes alphabetically.
+*/
+function collectDiscriminatorSubtypes(baseName, discriminator, componentSchemas) {
+	const result = [];
+	const seen = /* @__PURE__ */ new Set();
+	const mapping = isObject(discriminator.mapping) ? discriminator.mapping : void 0;
+	if (mapping !== void 0) for (const [constValue, ref] of Object.entries(mapping)) {
+		const name = componentSchemaName(ref);
+		if (name === void 0) continue;
+		if (!isObject(componentSchemas[name])) continue;
+		if (seen.has(name)) continue;
+		seen.add(name);
+		result.push({
+			name,
+			constValue
+		});
+	}
+	const implicitNames = [];
+	for (const [name, schema] of Object.entries(componentSchemas)) {
+		if (!isObject(schema)) continue;
+		if (seen.has(name)) continue;
+		if (!listAllOfBaseRefs(schema).includes(baseName)) continue;
+		implicitNames.push(name);
+	}
+	implicitNames.sort();
+	for (const name of implicitNames) {
+		result.push({
+			name,
+			constValue: name
+		});
+		seen.add(name);
+	}
+	return result;
+}
+/**
+* Inject the discriminator `const` on a subtype schema in-place.
+*
+* When the subtype already declares a matching const we leave it
+* alone. Otherwise the const is added in whichever location the walker
+* will actually observe:
+*
+* - Subtype declares `allOf`: append a new `allOf` entry carrying just
+*   `{ properties: { [propertyName]: { const } } }`. The walker's
+*   `mergeAllOf` merges every entry's `properties` into the resolved
+*   schema, so the const propagates through to the merged result. A
+*   top-level `properties` sibling of `allOf` would be ignored by the
+*   merge.
+* - Subtype does not declare `allOf`: extend the top-level `properties`
+*   block — the walker reads this directly.
+*/
+function injectSubtypeConst(subtype, propertyName, constValue) {
+	if (subtypeAlreadyDeclaresConst(subtype, propertyName)) return;
+	const constEntry = { properties: { [propertyName]: { const: constValue } } };
+	if (Array.isArray(subtype.allOf)) {
+		subtype.allOf = [...subtype.allOf, constEntry];
+		return;
+	}
+	const existingProps = isObject(subtype.properties) ? { ...subtype.properties } : {};
+	const existingDisc = existingProps[propertyName];
+	existingProps[propertyName] = {
+		...isObject(existingDisc) ? existingDisc : {},
+		const: constValue
+	};
+	subtype.properties = existingProps;
+}
+/**
+* Check whether a subtype (or any of its `allOf` entries) already
+* carries a `const` for the discriminator property. Used to avoid
+* overwriting an author-supplied const.
+*/
+function subtypeAlreadyDeclaresConst(subtype, propertyName) {
+	if (hasConstProp(subtype.properties, propertyName)) return true;
+	if (Array.isArray(subtype.allOf)) for (const entry of subtype.allOf) {
+		if (!isObject(entry)) continue;
+		if (hasConstProp(entry.properties, propertyName)) return true;
+	}
+	return false;
+}
+function hasConstProp(properties, propertyName) {
+	if (!isObject(properties)) return false;
+	const prop = properties[propertyName];
+	return isObject(prop) && "const" in prop;
+}
+/**
+* Strip every `$ref` entry in a subtype's `allOf` that targets the
+* discriminator base. The base's own schema content (properties,
+* required, type) is replicated into a synthesised `allOf` entry so
+* the subtype remains structurally complete — without this the base's
+* synthesised `oneOf` would cycle through the subtype's `$ref`s on
+* every walk (Dog → Pet.oneOf → Dog → ...).
+*/
+function rewriteSubtypeAllOf(subtype, baseName, baseInherited) {
+	const allOf = subtype.allOf;
+	if (!Array.isArray(allOf)) return;
+	const baseRefPrefix = `#/components/schemas/${baseName}`;
+	const rewritten = [];
+	let removedBaseRef = false;
+	for (const entry of allOf) {
+		if (isObject(entry) && typeof entry.$ref === "string" && entry.$ref === baseRefPrefix) {
+			removedBaseRef = true;
+			continue;
+		}
+		rewritten.push(entry);
+	}
+	if (!removedBaseRef) return;
+	subtype.allOf = [baseInherited, ...rewritten];
+}
+/**
+* Capture the "inheritable" portion of a base schema before rewriting:
+* `properties`, `required`, `type`, and any other constraint that
+* subtypes used to inherit through `$ref`. The discriminator keyword
+* and the synthesised `oneOf` are intentionally excluded — subtypes
+* never inherited those and including them would re-introduce the
+* Pet → Dog → Pet cycle.
+*/
+function captureBaseInherited(base) {
+	const inherited = {};
+	for (const [key, value] of Object.entries(base)) {
+		if (key === "discriminator") continue;
+		if (key === "oneOf") continue;
+		if (key === "anyOf") continue;
+		inherited[key] = value;
+	}
+	return inherited;
+}
+/**
+* Build an inline `oneOf` option that targets a subtype via `$ref` and
+* carries the discriminator property's `const` at the option's top
+* level. The const sibling is what makes `detectDiscriminated` classify
+* the parent `oneOf` as a discriminated union — it inspects each
+* option's literal `properties`, not the resolved schema.
+*/
+function buildDiscriminatorOption(subtype, propertyName) {
+	return {
+		$ref: `#/components/schemas/${subtype.name}`,
+		properties: { [propertyName]: { const: subtype.constValue } }
+	};
+}
+/**
+* Document-level pre-pass for OpenAPI discriminators that are declared
+* on a base schema and inherited by subtypes via `allOf`.
+*
+* The per-node {@link normaliseOpenApi30Discriminator} only handles
+* discriminators that already sit alongside `oneOf`/`anyOf`. For the
+* canonical "Cat extends Pet" pattern — where `Pet` carries the
+* discriminator and `Cat`/`Dog` reference `Pet` via `allOf` — the
+* discriminator is silently lost. This pre-pass:
+*
+* 1. Injects the discriminator `const` on each subtype's local
+*    `properties` (so a direct render of the subtype validates the
+*    discriminator value correctly).
+* 2. Synthesises a `oneOf` on the base whenever it lacks one, listing
+*    each subtype as `{ $ref, properties: { propertyName: { const } } }`.
+*    The per-node discriminator transform then sees `oneOf` and clears
+*    the `discriminator` keyword, and the walker's
+*    `detectDiscriminated` finds the per-option `const`s.
+*
+* Mutates a shallow clone of `components/schemas` — the input document
+* is never modified.
+*/
+function applyDiscriminatorAllOfPrepass(doc) {
+	const components = doc.components;
+	if (!isObject(components)) return doc;
+	const schemas = components.schemas;
+	if (!isObject(schemas)) return doc;
+	const plans = [];
+	for (const [baseName, base] of Object.entries(schemas)) {
+		if (!isObject(base)) continue;
+		const discriminator = base.discriminator;
+		if (!isObject(discriminator)) continue;
+		const propertyName = discriminator.propertyName;
+		if (typeof propertyName !== "string") continue;
+		const subtypes = collectDiscriminatorSubtypes(baseName, discriminator, schemas);
+		if (subtypes.length === 0) continue;
+		plans.push({
+			baseName,
+			propertyName,
+			subtypes,
+			baseHasOneOfOrAnyOf: Array.isArray(base.oneOf) || Array.isArray(base.anyOf),
+			baseInherited: captureBaseInherited(base)
+		});
+	}
+	if (plans.length === 0) return doc;
+	const newSchemas = { ...schemas };
+	const cloneSchema = (name) => {
+		const existing = newSchemas[name];
+		if (!isObject(existing)) throw new Error(`applyDiscriminatorAllOfPrepass: schema "${name}" disappeared between planning and rewrite`);
+		const clone = { ...existing };
+		newSchemas[name] = clone;
+		return clone;
+	};
+	for (const plan of plans) {
+		for (const subtype of plan.subtypes) {
+			const clone = cloneSchema(subtype.name);
+			rewriteSubtypeAllOf(clone, plan.baseName, plan.baseInherited);
+			injectSubtypeConst(clone, plan.propertyName, subtype.constValue);
+		}
+		if (!plan.baseHasOneOfOrAnyOf) {
+			const baseClone = cloneSchema(plan.baseName);
+			baseClone.oneOf = plan.subtypes.map((subtype) => buildDiscriminatorOption(subtype, plan.propertyName));
+			delete baseClone.properties;
+			delete baseClone.required;
+			delete baseClone.type;
+		}
+	}
+	return {
+		...doc,
+		components: {
+			...components,
+			schemas: newSchemas
+		}
+	};
+}
+/**
 * Combined OpenAPI 3.0.x node transform: Draft 04 + nullable + discriminator.
 * Applied to every schema node in an OpenAPI 3.0 document.
 *
@@ -226,7 +488,7 @@ function normaliseParameter(param, normaliseSchema) {
 	const content = param.content;
 	if (isObject(content)) result.content = normaliseContentMap(content, normaliseSchema);
 	if ("example" in result && !("examples" in result)) {
-		result.examples = [result.example];
+		result.examples = { default: { value: result.example } };
 		delete result.example;
 	} else if ("example" in result) delete result.example;
 	return result;
@@ -252,7 +514,7 @@ function normaliseHeader(header, normaliseSchema) {
 	const content = header.content;
 	if (isObject(content)) result.content = normaliseContentMap(content, normaliseSchema);
 	if ("example" in result && !("examples" in result)) {
-		result.examples = [result.example];
+		result.examples = { default: { value: result.example } };
 		delete result.example;
 	} else if ("example" in result) delete result.example;
 	return result;
@@ -325,9 +587,19 @@ function normaliseSwagger2Document(doc, deepNormalise, normaliseDraft04Node, dia
 			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 : "/";
+	if (typeof doc.host !== "string") {
+		if (Array.isArray(doc.schemes) || typeof doc.basePath === "string") emitDiagnostic(diagnostics, {
+			code: "swagger-missing-host",
+			message: "Swagger 2.0 document declares schemes or basePath without host; skipping server URL synthesis",
+			pointer: "",
+			detail: {
+				hasSchemes: Array.isArray(doc.schemes),
+				hasBasePath: typeof doc.basePath === "string"
+			}
+		});
+	} else {
+		const host = doc.host;
+		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}` }];
 	}
@@ -343,31 +615,62 @@ function normaliseSwagger2Document(doc, deepNormalise, normaliseDraft04Node, dia
 	const parameters = doc.parameters;
 	const requestBodies = {};
 	if (isObject(parameters)) {
-		const globalConsumes = Array.isArray(doc.consumes) ? doc.consumes : ["application/json"];
+		const consumesResolution = resolveSwaggerContentTypes(void 0, doc.consumes);
+		const globalConsumes = consumesResolution.types;
 		const convertedParameters = {};
 		for (const [name, param] of Object.entries(parameters)) {
 			if (!isObject(param)) {
 				convertedParameters[name] = param;
 				continue;
 			}
-			const resolved = resolveSwaggerParameter(param, doc);
+			const resolution = resolveSwaggerParameter(param, doc);
+			if (resolution.kind === "cycle") {
+				emitDiagnostic(diagnostics, {
+					code: "swagger-cyclic-parameter-ref",
+					message: `Cyclic Swagger 2.0 parameter $ref "${resolution.ref}"; skipping entry`,
+					pointer: appendPointer(appendPointer("", "parameters"), name),
+					detail: {
+						ref: resolution.ref,
+						name
+					}
+				});
+				continue;
+			}
+			const resolved = resolution.param;
 			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 (location === "body") {
+				if (consumesResolution.source === "synthesised") emitDiagnostic(diagnostics, {
+					code: "swagger-missing-consumes",
+					message: "Global body parameter declared but document-level `consumes` is absent; defaulting to application/json",
+					pointer: appendPointer(appendPointer("", "parameters"), name),
+					detail: {
+						level: "document",
+						name
+					}
+				});
+				requestBodies[name] = buildRequestBody(resolved, globalConsumes);
+			} else if (location === "formData") requestBodies[name] = buildRequestBody(buildFormDataBody(resolved, [resolved]), formDataContentTypes(globalConsumes));
+			else {
+				const normalised = normaliseSwaggerParameter(resolved, doc, diagnostics, appendPointer(appendPointer("", "parameters"), name));
+				if (normalised !== void 0) convertedParameters[name] = normalised;
+			}
 		}
 		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 producesResolution = resolveSwaggerContentTypes(void 0, doc.produces);
 		const convertedResponses = {};
-		for (const [name, response] of Object.entries(responses)) convertedResponses[name] = isObject(response) ? normaliseSwaggerSingleResponse(response, doc, globalProduces) : response;
+		for (const [name, response] of Object.entries(responses)) convertedResponses[name] = isObject(response) ? normaliseSwaggerSingleResponse(response, doc, producesResolution.types, producesResolution.source, diagnostics, void 0, void 0, name) : response;
 		components.responses = convertedResponses;
 	}
 	if (Object.keys(requestBodies).length > 0) components.requestBodies = requestBodies;
 	const securityDefinitions = doc.securityDefinitions;
-	if (isObject(securityDefinitions)) components.securitySchemes = { ...securityDefinitions };
+	if (isObject(securityDefinitions)) {
+		const translated = {};
+		for (const [name, scheme] of Object.entries(securityDefinitions)) translated[name] = isObject(scheme) ? translateSwaggerSecurityScheme(scheme) : scheme;
+		components.securitySchemes = translated;
+	}
 	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;
@@ -404,17 +707,29 @@ function normaliseSwaggerPaths(paths, doc, diagnostics) {
 			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);
+		if (Array.isArray(pathParams)) {
+			const paramsPointer = appendPointer(appendPointer(appendPointer("", "paths"), path), "parameters");
+			const out = [];
+			for (const [index, p] of pathParams.entries()) {
+				if (!isObject(p)) {
+					out.push(p);
+					continue;
+				}
+				const normalised = normaliseSwaggerParameter(p, doc, diagnostics, appendPointer(paramsPointer, String(index)));
+				if (normalised !== void 0) out.push(normalised);
+			}
+			normalisedPath.parameters = out;
+		}
 		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;
+	const consumesResolution = resolveSwaggerContentTypes(operation.consumes, doc.consumes);
+	const producesResolution = resolveSwaggerContentTypes(operation.produces, doc.produces);
+	const produces = producesResolution.types;
+	const consumes = consumesResolution.types;
 	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)) {
@@ -427,7 +742,17 @@ function normaliseSwaggerOperation(operation, doc, path, method, diagnostics) {
 				nonBodyParams.push(param);
 				continue;
 			}
-			const resolvedParam = resolveSwaggerParameter(param, doc);
+			const paramResolution = resolveSwaggerParameter(param, doc);
+			if (paramResolution.kind === "cycle") {
+				emitDiagnostic(diagnostics, {
+					code: "swagger-cyclic-parameter-ref",
+					message: `Cyclic Swagger 2.0 parameter $ref "${paramResolution.ref}"; skipping entry`,
+					pointer: appendPointer(appendPointer(appendPointer(appendPointer(appendPointer("", "paths"), path), method), "parameters"), String(index)),
+					detail: { ref: paramResolution.ref }
+				});
+				continue;
+			}
+			const resolvedParam = paramResolution.param;
 			const location = resolvedParam.in;
 			if (location === "body") {
 				if (bodyParam !== void 0) {
@@ -451,16 +776,51 @@ function normaliseSwaggerOperation(operation, doc, path, method, diagnostics) {
 					bodyParam = buildFormDataBody(resolvedParam, params);
 					usesFormData = true;
 				}
-			} else nonBodyParams.push(normaliseSwaggerParameter(resolvedParam, doc));
+			} else {
+				const normalised = normaliseSwaggerParameter(resolvedParam, doc, diagnostics, appendPointer(appendPointer(appendPointer(appendPointer(appendPointer("", "paths"), path), method), "parameters"), String(index)));
+				if (normalised !== void 0) nonBodyParams.push(normalised);
+			}
 		}
 		if (nonBodyParams.length > 0) result.parameters = nonBodyParams;
-		if (bodyParam !== void 0) result.requestBody = buildRequestBody(bodyParam, usesFormData ? formDataContentTypes(consumes) : consumes);
+		if (bodyParam !== void 0) {
+			const bodyContentTypes = usesFormData ? formDataContentTypes(consumes) : consumes;
+			if (!usesFormData && consumesResolution.source === "synthesised") emitDiagnostic(diagnostics, {
+				code: "swagger-missing-consumes",
+				message: "Operation declares a body parameter but neither operation-level nor document-level `consumes` is set; defaulting to application/json",
+				pointer: appendPointer(appendPointer(appendPointer("", "paths"), path), method),
+				detail: {
+					level: "operation",
+					method
+				}
+			});
+			result.requestBody = buildRequestBody(bodyParam, bodyContentTypes);
+		}
 	}
 	const responses = operation.responses;
-	if (isObject(responses)) result.responses = normaliseSwaggerResponses(responses, doc, produces);
+	if (isObject(responses)) result.responses = normaliseSwaggerResponses(responses, doc, produces, producesResolution.source, diagnostics, path, method);
 	return result;
 }
 /**
+* Resolve a Swagger 2.0 `consumes` or `produces` array, recording
+* where the value came from so callers can decide whether to emit a
+* "missing content type" diagnostic. Per the Swagger 2.0 spec, absence
+* at BOTH levels means no body — not an implicit `application/json`.
+*/
+function resolveSwaggerContentTypes(operationLevel, documentLevel) {
+	if (Array.isArray(operationLevel)) return {
+		types: operationLevel,
+		source: "operation"
+	};
+	if (Array.isArray(documentLevel)) return {
+		types: documentLevel,
+		source: "document"
+	};
+	return {
+		types: ["application/json"],
+		source: "synthesised"
+	};
+}
+/**
 * 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
@@ -475,12 +835,77 @@ function formDataContentTypes(consumes) {
 	return ["multipart/form-data"];
 }
 /**
-* Resolve a Swagger parameter that may be a `$ref`.
+* Every JSON-Schema-compatible constraint keyword Swagger 2.0 allows on
+* a Parameter Object or Header Object alongside `type`/`format`. These
+* lift into the synthesised `schema` so consumers see the original
+* validation semantics under OAS 3.x's parameter shape.
+*
+* `allowEmptyValue` is included even though it is a Swagger 2.0
+* parameter-level keyword in the source (not a schema keyword) — OAS
+* 3.x defines it at the Parameter Object root, so the calling function
+* keeps it at the parameter root rather than copying it into `schema`.
+*/
+const SWAGGER_PARAM_SCHEMA_KEYWORDS = [
+	"enum",
+	"default",
+	"minimum",
+	"maximum",
+	"exclusiveMinimum",
+	"exclusiveMaximum",
+	"multipleOf",
+	"minLength",
+	"maxLength",
+	"pattern",
+	"minItems",
+	"maxItems",
+	"uniqueItems"
+];
+/**
+* Set of every Swagger 2.0 parameter-root keyword that must be lifted
+* into the synthesised `schema` rather than copied onto the OAS 3.x
+* parameter root. Includes `type`, `format`, `items` (Swagger 2.0
+* parameter-shaped array element descriptor), `collectionFormat`
+* (handled separately by the caller as `style`/`explode`), and every
+* entry from {@link SWAGGER_PARAM_SCHEMA_KEYWORDS}.
+*/
+const PARAM_KEYWORDS_LIFTED_INTO_SCHEMA = new Set([
+	"type",
+	"format",
+	"items",
+	"collectionFormat",
+	...SWAGGER_PARAM_SCHEMA_KEYWORDS
+]);
+/**
+* Synthesise an OpenAPI 3.x `schema` object from a Swagger 2.0
+* parameter-shaped node (parameter or header). Copies `type`,
+* `format`, and every JSON-Schema-compatible constraint that Swagger
+* 2.0 places at the parameter root. Nested `items` is recursively
+* synthesised the same way so array element constraints survive.
+*/
+function buildSchemaFromSwaggerParameterShape(node) {
+	const schema = { type: node.type };
+	if (typeof node.format === "string") schema.format = node.format;
+	for (const keyword of SWAGGER_PARAM_SCHEMA_KEYWORDS) if (node[keyword] !== void 0) schema[keyword] = node[keyword];
+	if (isObject(node.items)) schema.items = buildSchemaFromSwaggerParameterShape(node.items);
+	return schema;
+}
+/**
+* Resolve a Swagger parameter that may be a `$ref`. Returns the
+* resolved parameter object, or a cycle marker so the caller can
+* decide how to surface the failure. Non-ref parameters resolve to
+* themselves; ref targets that don't exist also resolve to the input
+* (the caller treats unknown refs the same as bare parameters).
 */
 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;
+	if (typeof ref !== "string" || !ref.startsWith("#/parameters/")) return {
+		kind: "ok",
+		param
+	};
+	if (visited.has(ref)) return {
+		kind: "cycle",
+		ref
+	};
 	const nextVisited = new Set(visited);
 	nextVisited.add(ref);
 	const name = ref.slice(13);
@@ -489,33 +914,55 @@ function resolveSwaggerParameter(param, doc, visited = /* @__PURE__ */ new Set()
 		const resolved = globalParams[name];
 		if (isObject(resolved)) {
 			if (typeof resolved.$ref === "string") return resolveSwaggerParameter(resolved, doc, nextVisited);
-			return resolved;
+			return {
+				kind: "ok",
+				param: resolved
+			};
 		}
 	}
-	return param;
+	return {
+		kind: "ok",
+		param
+	};
 }
 /**
 * Normalise a single Swagger parameter to OpenAPI 3.x form.
 */
-function normaliseSwaggerParameter(param, doc) {
+function normaliseSwaggerParameter(param, doc, diagnostics, pointer = "") {
 	if (typeof param.$ref === "string") {
-		const resolved = resolveSwaggerParameter(param, doc);
-		if (resolved !== param) return normaliseSwaggerParameter(resolved, doc);
+		const resolution = resolveSwaggerParameter(param, doc);
+		if (resolution.kind === "cycle") {
+			emitDiagnostic(diagnostics, {
+				code: "swagger-cyclic-parameter-ref",
+				message: `Cyclic Swagger 2.0 parameter $ref "${resolution.ref}"; skipping entry`,
+				pointer,
+				detail: { ref: resolution.ref }
+			});
+			return;
+		}
+		const resolved = resolution.param;
+		if (resolved !== param) return normaliseSwaggerParameter(resolved, doc, diagnostics, pointer);
 	}
 	const result = {};
 	for (const [key, value] of Object.entries(param)) {
-		if (key === "type" || key === "format" || key === "collectionFormat") continue;
+		if (PARAM_KEYWORDS_LIFTED_INTO_SCHEMA.has(key)) 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;
-	}
+	if (typeof param.type === "string") if (param.type === "file" && param.in !== "formData") {
+		emitDiagnostic(diagnostics, {
+			code: "swagger-invalid-file-parameter",
+			message: `Swagger 2.0 type: "file" is only valid under in: formData; converting to { type: "string", format: "binary" }`,
+			pointer,
+			detail: {
+				name: param.name,
+				in: param.in
+			}
+		});
+		result.schema = {
+			type: "string",
+			format: "binary"
+		};
+	} else result.schema = buildSchemaFromSwaggerParameterShape(param);
 	const cf = param.collectionFormat;
 	if (typeof cf === "string") switch (cf) {
 		case "csv":
@@ -606,14 +1053,14 @@ function resolveSwaggerResponse(response, doc, visited = /* @__PURE__ */ new Set
 	}
 	return response;
 }
-function normaliseSwaggerResponses(responses, doc, produces) {
+function normaliseSwaggerResponses(responses, doc, produces, producesSource, diagnostics, path, method) {
 	const result = {};
 	for (const [code, response] of Object.entries(responses)) {
 		if (!isObject(response)) {
 			result[code] = response;
 			continue;
 		}
-		result[code] = normaliseSwaggerSingleResponse(response, doc, produces);
+		result[code] = normaliseSwaggerSingleResponse(response, doc, produces, producesSource, diagnostics, path, method, code);
 	}
 	return result;
 }
@@ -626,7 +1073,7 @@ function normaliseSwaggerResponses(responses, doc, produces) {
 * operation’s `responses` map or under document-level `responses`
 * (now `components.responses`).
 */
-function normaliseSwaggerSingleResponse(response, doc, produces) {
+function normaliseSwaggerSingleResponse(response, doc, produces, producesSource = "synthesised", diagnostics, path, method, statusCode) {
 	const resolved = resolveSwaggerResponse(response, doc);
 	const normalised = {};
 	for (const [key, value] of Object.entries(resolved)) if (key !== "schema" && key !== "headers") normalised[key] = value;
@@ -636,6 +1083,15 @@ function normaliseSwaggerSingleResponse(response, doc, produces) {
 		const contentTypes = produces.length > 0 ? produces : ["application/json"];
 		for (const ct of contentTypes) if (typeof ct === "string") content[ct] = { schema };
 		normalised.content = content;
+		if (producesSource === "synthesised") emitDiagnostic(diagnostics, {
+			code: "swagger-missing-consumes",
+			message: "Response declares a schema but neither operation-level nor document-level `produces` is set; defaulting to application/json",
+			pointer: path !== void 0 && method !== void 0 && statusCode !== void 0 ? appendPointer(appendPointer(appendPointer(appendPointer(appendPointer("", "paths"), path), method), "responses"), statusCode) : "",
+			detail: {
+				level: "response",
+				statusCode
+			}
+		});
 	}
 	const headers = resolved.headers;
 	if (isObject(headers)) {
@@ -661,18 +1117,10 @@ function normaliseSwaggerSingleResponse(response, doc, produces) {
 function normaliseSwaggerHeader(header) {
 	const result = {};
 	for (const [key, value] of Object.entries(header)) {
-		if (key === "type" || key === "format" || key === "collectionFormat") continue;
+		if (PARAM_KEYWORDS_LIFTED_INTO_SCHEMA.has(key)) 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;
-	}
+	if (typeof header.type === "string") result.schema = buildSchemaFromSwaggerParameterShape(header);
 	const cf = header.collectionFormat;
 	if (typeof cf === "string") switch (cf) {
 		case "csv":
@@ -722,6 +1170,64 @@ function rewriteSwaggerRefs(node) {
 	else if (Array.isArray(value)) for (const item of value) rewriteSwaggerRefs(item);
 }
 /**
+* Map from Swagger 2.0 `oauth2.flow` (singular) to the OAS 3.x flow key
+* under `flows.<key>`. `application` and `accessCode` were renamed in
+* OAS 3.x to align with RFC 6749 grant-type names.
+*/
+const SWAGGER_OAUTH_FLOW_RENAME = {
+	implicit: "implicit",
+	password: "password",
+	application: "clientCredentials",
+	accessCode: "authorizationCode"
+};
+/**
+* Translate a Swagger 2.0 Security Scheme Object into an OpenAPI 3.x
+* Security Scheme Object. The Swagger 2.0 spec defines three types:
+*
+* - `basic` — has no other fields; OAS 3.x represents this as
+*   `{ type: "http", scheme: "basic" }`.
+* - `apiKey` — carries `name`/`in`; OAS 3.x uses the same shape.
+* - `oauth2` — carries `flow`/`authorizationUrl`/`tokenUrl`/`scopes` at
+*   the root. OAS 3.x nests these under `flows.<name>` where the flow
+*   name maps via {@link SWAGGER_OAUTH_FLOW_RENAME}.
+*
+* Unknown `type` values pass through verbatim — downstream validation
+* (`unknown-security-scheme-type` diagnostic in the parser) handles
+* those cases.
+*/
+function translateSwaggerSecurityScheme(scheme) {
+	const type = scheme.type;
+	if (type === "basic") {
+		const result = {
+			type: "http",
+			scheme: "basic"
+		};
+		if (typeof scheme.description === "string") result.description = scheme.description;
+		return result;
+	}
+	if (type === "oauth2") {
+		const flowName = scheme.flow;
+		if (typeof flowName !== "string") return {
+			...scheme,
+			type: "oauth2"
+		};
+		const renamedFlow = SWAGGER_OAUTH_FLOW_RENAME[flowName] ?? flowName;
+		const flowBody = {};
+		if (typeof scheme.authorizationUrl === "string") flowBody.authorizationUrl = scheme.authorizationUrl;
+		if (typeof scheme.tokenUrl === "string") flowBody.tokenUrl = scheme.tokenUrl;
+		if (typeof scheme.refreshUrl === "string") flowBody.refreshUrl = scheme.refreshUrl;
+		const scopes = scheme.scopes;
+		flowBody.scopes = isObject(scopes) ? { ...scopes } : {};
+		const result = {
+			type: "oauth2",
+			flows: { [renamedFlow]: flowBody }
+		};
+		if (typeof scheme.description === "string") result.description = scheme.description;
+		return result;
+	}
+	return { ...scheme };
+}
+/**
 * 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
@@ -779,58 +1285,76 @@ const SINGLE_SUBSCHEMA_KEYS = new Set([
 * Normalise each element of an unknown array by applying deepNormalise
 * to object elements and passing others through unchanged.
 */
-function normaliseArray(items, transform) {
+function normaliseArray(items, transform, visited) {
 	const result = [];
-	for (const item of items) result.push(isObject(item) ? deepNormalise(item, transform) : item);
+	for (const item of items) result.push(isObject(item) ? deepNormalise(item, transform, visited) : item);
 	return result;
 }
 /**
 * Normalise each value of a sub-schema map (e.g. properties, $defs).
 */
-function normaliseSubSchemaMap(map, transform) {
+function normaliseSubSchemaMap(map, transform, visited) {
 	const result = {};
-	for (const [k, v] of Object.entries(map)) result[k] = isObject(v) ? deepNormalise(v, transform) : v;
+	for (const [k, v] of Object.entries(map)) result[k] = isObject(v) ? deepNormalise(v, transform, visited) : v;
 	return result;
 }
 /**
 * Deep-normalise a JSON Schema object by applying a per-node transform
 * and recursing into every sub-schema location.
+*
+* The optional `visited` set guards against shared object references and
+* cycles introduced upstream (e.g. by the OpenAPI bundler's
+* `structuredClone`-based inlining of external refs). The walk skips
+* already-seen nodes by returning the original reference rather than
+* recursing forever.
 */
-function deepNormalise(schema, transform) {
+function deepNormalise(schema, transform, visited = /* @__PURE__ */ new WeakSet()) {
+	if (visited.has(schema)) return schema;
+	visited.add(schema);
 	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);
+	for (const [key, value] of Object.entries(node)) if (isObject(value) && OBJECT_SUBSCHEMA_KEYS.has(key)) result[key] = normaliseSubSchemaMap(value, transform, visited);
+	else if (Array.isArray(value) && ARRAY_SUBSCHEMA_KEYS.has(key)) result[key] = normaliseArray(value, transform, visited);
+	else if (isObject(value) && SINGLE_SUBSCHEMA_KEYS.has(key)) result[key] = deepNormalise(value, transform, visited);
+	else if (key === "items") if (Array.isArray(value)) result[key] = normaliseArray(value, transform, visited);
+	else if (isObject(value)) result[key] = deepNormalise(value, transform, visited);
 	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);
+		for (const [dk, dv] of Object.entries(value)) if (isObject(dv)) normalised[dk] = deepNormalise(dv, transform, visited);
 		else normalised[dk] = dv;
 		result[key] = normalised;
 	} else result[key] = value;
 	return result;
 }
+/**
+* Construct a child {@link NodeContext} that descends to `segment`,
+* preserving document-level flags (`documentHasDynamicAnchor`,
+* `documentHasRecursiveAnchor`, `declaredDraft`). Centralising the copy
+* keeps the recursion in `deepNormaliseWithContext` from drifting from
+* the {@link NodeContext} shape.
+*/
+function childContext(ctx, segment) {
+	return {
+		diagnostics: ctx.diagnostics,
+		pointer: appendPointer(ctx.pointer, segment),
+		documentHasDynamicAnchor: ctx.documentHasDynamicAnchor,
+		documentHasRecursiveAnchor: ctx.documentHasRecursiveAnchor,
+		declaredDraft: ctx.declaredDraft
+	};
+}
 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))
-		}));
+		if (isObject(item)) result.push(deepNormaliseWithContext(item, transform, childContext(ctx, 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)
-	});
+	for (const [k, v] of Object.entries(map)) if (isObject(v)) result[k] = deepNormaliseWithContext(v, transform, childContext(ctx, k));
 	else result[k] = v;
 	return result;
 }
@@ -846,34 +1370,16 @@ function normaliseSubSchemaMapWithContext(map, transform, ctx) {
 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)
-	});
+	for (const [key, value] of Object.entries(node)) if (isObject(value) && OBJECT_SUBSCHEMA_KEYS.has(key)) result[key] = normaliseSubSchemaMapWithContext(value, transform, childContext(ctx, key));
+	else if (Array.isArray(value) && ARRAY_SUBSCHEMA_KEYS.has(key)) result[key] = normaliseArrayWithContext(value, transform, childContext(ctx, key));
+	else if (isObject(value) && SINGLE_SUBSCHEMA_KEYS.has(key)) result[key] = deepNormaliseWithContext(value, transform, childContext(ctx, key));
+	else if (key === "items") if (Array.isArray(value)) result[key] = normaliseArrayWithContext(value, transform, childContext(ctx, key));
+	else if (isObject(value)) result[key] = deepNormaliseWithContext(value, transform, childContext(ctx, 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)
-		});
+		const depsContext = childContext(ctx, key);
+		for (const [dk, dv] of Object.entries(value)) if (isObject(dv)) normalised[dk] = deepNormaliseWithContext(dv, transform, childContext(depsContext, dk));
 		else normalised[dk] = dv;
 		result[key] = normalised;
 	} else result[key] = value;
@@ -976,6 +1482,26 @@ function validateDependentRequired(node, ctx) {
 	}
 }
 /**
+* Translate the legacy tuple-form `items: [Schema, Schema]` keyword to
+* Draft 2020-12's `prefixItems`. `additionalItems` becomes the rest-element
+* schema and is rewritten to `items`.
+*
+* Applies to Drafts 04, 06, and 07 — all of which used the tuple form
+* before Draft 2020-12 split positional schemas into `prefixItems`.
+*
+* No-op when `items` is already a single sub-schema, or when `prefixItems`
+* is already present (do not overwrite an explicit author choice).
+*/
+function translateTupleItems(node) {
+	if (!Array.isArray(node.items) || "prefixItems" in node) return;
+	node.prefixItems = node.items;
+	delete node.items;
+	if ("additionalItems" in node) {
+		node.items = node.additionalItems;
+		delete node.additionalItems;
+	}
+}
+/**
 * 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`.
@@ -1036,14 +1562,7 @@ function applyDraft04Translations(node, ctx) {
 		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;
-		}
-	}
+	translateTupleItems(node);
 	splitDependencies(node, ctx, false);
 	validateDependentRequired(node, ctx);
 }
@@ -1089,8 +1608,14 @@ function normaliseDraft04NodeWithContext(node, ctx) {
 * (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.
+*
+* Drafts 06 and 07 also use the tuple form
+* `items: [Schema, Schema], additionalItems: Schema` — translate that to
+* Draft 2020-12's `prefixItems` + rest-`items` so the walker produces a
+* `TupleField` rather than silently dropping the positional schemas.
 */
 function normaliseDraft06Or07NodeWithContext(node, ctx) {
+	translateTupleItems(node);
 	splitDependencies(node, ctx, false);
 	validateDependentRequired(node, ctx);
 	return node;
@@ -1110,8 +1635,18 @@ function normaliseDraft06Or07NodeWithContext(node, ctx) {
 * `$recursiveAnchor` names are likewise preserved as `$anchor`.
 */
 function normaliseDraft201909NodeWithContext(node, ctx) {
-	if (typeof node.$recursiveRef === "string") {
-		node.$ref = node.$recursiveRef;
+	const recursiveRef = node.$recursiveRef;
+	if (typeof recursiveRef === "string") {
+		if (!recursiveRef.startsWith("#")) emitDiagnostic(ctx.diagnostics, {
+			code: "dynamic-ref-degraded",
+			message: `Cross-document \`$recursiveRef\` "${recursiveRef}" rewritten to a static \`$ref\`; dynamic-scope resolution is not preserved`,
+			pointer: appendPointer(ctx.pointer, "$recursiveRef"),
+			detail: {
+				keyword: "$recursiveRef",
+				ref: recursiveRef
+			}
+		});
+		node.$ref = recursiveRef;
 		delete node.$recursiveRef;
 	}
 	if (node.$recursiveAnchor === true) {
@@ -1121,12 +1656,24 @@ function normaliseDraft201909NodeWithContext(node, ctx) {
 		if (typeof node.$anchor !== "string") node.$anchor = node.$recursiveAnchor;
 		delete node.$recursiveAnchor;
 	}
+	splitDependencies(node, ctx, false);
 	validateDependentRequired(node, ctx);
 	return node;
 }
 function normaliseDynamicRefNodeWithContext(node, ctx) {
-	if (typeof node.$dynamicRef === "string") {
-		node.$ref = node.$dynamicRef;
+	const dynamicRef = node.$dynamicRef;
+	if (typeof dynamicRef === "string") {
+		const crossDocument = !dynamicRef.startsWith("#");
+		if (crossDocument || ctx.documentHasDynamicAnchor) emitDiagnostic(ctx.diagnostics, {
+			code: "dynamic-ref-degraded",
+			message: crossDocument ? `Cross-document \`$dynamicRef\` "${dynamicRef}" rewritten to a static \`$ref\`; dynamic-scope resolution is not preserved` : `\`$dynamicRef\` "${dynamicRef}" rewritten to a static \`$ref\` in a document declaring \`$dynamicAnchor\`; dynamic-scope resolution is not preserved`,
+			pointer: appendPointer(ctx.pointer, "$dynamicRef"),
+			detail: {
+				keyword: "$dynamicRef",
+				ref: dynamicRef
+			}
+		});
+		node.$ref = dynamicRef;
 		delete node.$dynamicRef;
 	}
 	if (typeof node.$dynamicAnchor === "string") {
@@ -1138,6 +1685,63 @@ function normaliseDynamicRefNodeWithContext(node, ctx) {
 	return node;
 }
 /**
+* Pick the per-node transform that normalises a single Schema Object to
+* canonical Draft 2020-12 form for the supplied draft. Exposed so the
+* OpenAPI 3.1 path can honour a non-default `jsonSchemaDialect`
+* declaration by routing each Schema Object through the matching
+* transform without re-implementing the dispatch.
+*/
+function selectDraftTransform(draft) {
+	switch (draft) {
+		case "draft-04": return normaliseDraft04NodeWithContext;
+		case "draft-06":
+		case "draft-07": return normaliseDraft06Or07NodeWithContext;
+		case "draft-2019-09": return normaliseDraft201909NodeWithContext;
+		case "draft-2020-12": return normaliseDynamicRefNodeWithContext;
+	}
+}
+/**
+* Scan a JSON document body for the presence of a named keyword
+* anywhere in the structure. Walks both arrays and objects without
+* regard to schema-vs-data position — the caller is responsible for
+* passing a keyword whose presence is meaningful at any depth.
+*
+* Cycle-safe: cyclic references introduced by the OpenAPI bundler's
+* `structuredClone` of external refs are short-circuited via the
+* `visited` set so the scan terminates.
+*/
+function documentContainsKeyword(value, keyword, visited = /* @__PURE__ */ new WeakSet()) {
+	if (Array.isArray(value)) {
+		if (visited.has(value)) return false;
+		visited.add(value);
+		for (const item of value) if (documentContainsKeyword(item, keyword, visited)) return true;
+		return false;
+	}
+	if (isObject(value)) {
+		if (visited.has(value)) return false;
+		visited.add(value);
+		if (keyword in value) return true;
+		for (const v of Object.values(value)) if (documentContainsKeyword(v, keyword, visited)) return true;
+		return false;
+	}
+	return false;
+}
+/**
+* Build a root {@link NodeContext} for a document being normalised.
+* Pre-scans for `$dynamicAnchor` and `$recursiveAnchor` so per-node
+* transforms can decide whether a `$dynamicRef`/`$recursiveRef`
+* rewrite needs a `dynamic-ref-degraded` diagnostic.
+*/
+function buildRootContext(schema, diagnostics, declaredDraft) {
+	return {
+		diagnostics,
+		pointer: "",
+		documentHasDynamicAnchor: documentContainsKeyword(schema, "$dynamicAnchor"),
+		documentHasRecursiveAnchor: documentContainsKeyword(schema, "$recursiveAnchor"),
+		declaredDraft
+	};
+}
+/**
 * Normalise a JSON Schema to canonical Draft 2020-12 form.
 * Deep-clones the input — the original is never mutated.
 *
@@ -1147,27 +1751,8 @@ function normaliseDynamicRefNodeWithContext(node, ctx) {
 * `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);
+	const ctx = buildRootContext(schema, diagnostics, draft);
+	return resolveRelativeRefs(deepNormaliseWithContext(schema, selectDraftTransform(draft), ctx), diagnostics);
 }
 /**
 * Parse a string as an absolute URI, returning `undefined` when it has
@@ -1205,6 +1790,29 @@ function stripFragment(url) {
 	return clone.toString();
 }
 /**
+* Emit an `invalid-id-fragment` diagnostic when an `$id` value carries
+* a fragment that will be stripped during base-URI resolution. Per
+* JSON Schema 2020-12 §8.2.1, the URI in `$id` MUST NOT contain a
+* non-empty fragment (an empty `#` fragment is permitted for historical
+* reasons but conveys nothing). Stripping it silently loses authoring
+* intent — the caller almost certainly meant to declare an `$anchor`
+* or sibling identifier instead.
+*/
+function reportFragmentInId(value, url, pointer, diagnostics) {
+	if (diagnostics === void 0) return;
+	if (typeof value !== "string") return;
+	if (url.hash.length === 0) return;
+	emitDiagnostic(diagnostics, {
+		code: "invalid-id-fragment",
+		message: `\`$id\` URI "${value}" includes the fragment "${url.hash}", which is not permitted by JSON Schema §8.2.1; the fragment is stripped before use`,
+		pointer: appendPointer(pointer, "$id"),
+		detail: {
+			id: value,
+			fragment: url.hash
+		}
+	});
+}
+/**
 * 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
@@ -1219,14 +1827,29 @@ 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);
+	return rewriteRelativeRefsNode(schema, docBase, docBase, "", diagnostics, /* @__PURE__ */ new WeakSet());
 }
-function rewriteRelativeRefsNode(node, currentBase, docBase, pointer, diagnostics) {
+/**
+* Rewrite relative `$ref`s in a single node, recursing into sub-schemas.
+*
+* The `visited` set guards against shared object references and cycles
+* introduced upstream (e.g. by the OpenAPI bundler's `structuredClone`
+* inlining of external refs). When a node is re-encountered the rewrite
+* is short-circuited — returning the original reference unchanged is
+* sound because every relative `$ref` in the subtree was already
+* rewritten on the first visit.
+*/
+function rewriteRelativeRefsNode(node, currentBase, docBase, pointer, diagnostics, visited) {
+	if (visited.has(node)) return node;
+	visited.add(node);
 	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);
+		if (resolved !== void 0) {
+			reportFragmentInId(nodeId, resolved, pointer, diagnostics);
+			nextBase = stripFragment(resolved);
+		}
 	}
 	const result = {};
 	for (const [key, value] of Object.entries(node)) {
@@ -1234,13 +1857,17 @@ function rewriteRelativeRefsNode(node, currentBase, docBase, pointer, diagnostic
 			result[key] = rewriteRef(value, nextBase, docBase, appendPointer(pointer, key), diagnostics);
 			continue;
 		}
-		result[key] = rewriteRelativeRefsValue(value, key, nextBase, docBase, appendPointer(pointer, key), diagnostics);
+		result[key] = rewriteRelativeRefsValue(value, nextBase, docBase, appendPointer(pointer, key), diagnostics, visited);
 	}
 	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);
+function rewriteRelativeRefsValue(value, currentBase, docBase, pointer, diagnostics, visited) {
+	if (Array.isArray(value)) {
+		if (visited.has(value)) return value;
+		visited.add(value);
+		return value.map((item, i) => rewriteRelativeRefsValue(item, currentBase, docBase, appendPointer(pointer, String(i)), diagnostics, visited));
+	}
+	if (isObject(value)) return rewriteRelativeRefsNode(value, currentBase, docBase, pointer, diagnostics, visited);
 	return value;
 }
 /**
@@ -1290,7 +1917,25 @@ function rewriteRef(ref, currentBase, docBase, pointer, diagnostics) {
 */
 function normaliseOpenApiSchemas(doc, version, diagnostics) {
 	if (isSwagger2(version)) return normaliseSwagger2Document(doc, deepNormalise, normaliseDraft04Node, diagnostics);
-	if (isOpenApi30(version)) return deepNormaliseOpenApi30Doc(doc, deepNormalise);
+	if (isOpenApi30(version)) return deepNormaliseOpenApi30Doc(applyDiscriminatorAllOfPrepass(doc), deepNormalise);
+	if (!isOpenApi31(version)) {
+		const rawOpenApi = typeof doc.openapi === "string" ? doc.openapi : void 0;
+		const rawSwagger = typeof doc.swagger === "string" ? doc.swagger : void 0;
+		const versionLabel = rawOpenApi ?? rawSwagger ?? `${String(version.major)}.${String(version.minor)}.${String(version.patch)}`;
+		const pointer = rawOpenApi !== void 0 ? "/openapi" : "/swagger";
+		emitDiagnostic(diagnostics, {
+			code: "unknown-openapi-version",
+			message: `Unsupported OpenAPI/Swagger version "${versionLabel}"; falling back to the OpenAPI 3.1 pipeline`,
+			pointer,
+			detail: {
+				version: versionLabel,
+				major: version.major,
+				minor: version.minor,
+				patch: version.patch
+			}
+		});
+	}
+	let dialectDraft;
 	if (isOpenApi31(version)) {
 		const dialect = readJsonSchemaDialect(doc);
 		if (dialect.kind === "unknown") emitDiagnostic(diagnostics, {
@@ -1299,8 +1944,13 @@ function normaliseOpenApiSchemas(doc, version, diagnostics) {
 			pointer: "/jsonSchemaDialect",
 			detail: { uri: dialect.uri }
 		});
+		else if (dialect.kind === "known") dialectDraft = dialect.draft;
 	}
-	return deepNormaliseOpenApiDoc(doc, (schema) => deepNormalise(schema, normaliseOpenApi30Discriminator));
+	return deepNormaliseOpenApiDoc(applyDiscriminatorAllOfPrepass(doc), (schema) => {
+		let intermediate = schema;
+		if (dialectDraft !== void 0 && dialectDraft !== "draft-2020-12") intermediate = deepNormaliseWithContext(intermediate, selectDraftTransform(dialectDraft), buildRootContext(intermediate, diagnostics, dialectDraft));
+		return resolveRelativeRefs(deepNormalise(intermediate, normaliseOpenApi30Discriminator), diagnostics);
+	});
 }
 //#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 };
+export { normaliseOpenApiSchemas as a, applyDiscriminatorAllOfPrepass as c, normaliseOpenApi30Combined as d, normaliseOpenApi30Discriminator as f, normaliseJsonSchema as i, deepNormaliseOpenApi30Doc as l, deepNormaliseWithContext as n, selectDraftTransform as o, normaliseOpenApi30Node as p, normaliseDraft04Node as r, normaliseSwagger2Document as s, deepNormalise as t, deepNormaliseOpenApiDoc as u };