schema-components 1.21.0 → 1.23.0

package/dist/{normalise-DaSrnr8g.mjs → normalise-DCYp06Sr.mjs}

@@ -1,6 +1,9 @@
 import { isObject } from "./core/guards.mjs";
 import { appendPointer, emitDiagnostic } from "./core/diagnostics.mjs";
-import { isOpenApi30, isOpenApi31, isSwagger2, readJsonSchemaDialect } from "./core/version.mjs";
+import { RECURSIVE_ANCHOR_SENTINEL } from "./core/ref.mjs";
+import { isOpenApi30, isOpenApi31, isSwagger2, matchJsonSchemaDraftUri, readJsonSchemaDialect } from "./core/version.mjs";
+import { SWAGGER_2_METHODS, rewriteSwaggerRefPrefix } from "./core/openapiConstants.mjs";
+import { resolveRefChain } from "./core/refChain.mjs";
 //#region src/core/openapi30.ts
 /**
 * OpenAPI 3.0.x schema normalisation.
@@ -10,6 +13,29 @@ import { isOpenApi30, isOpenApi31, isSwagger2, readJsonSchemaDialect } from "./c
 * responses, headers, callbacks, links, examples) to apply normalisation.
 */
 /**
+* Lift OpenAPI 3.x singular `example` onto the plural `examples` key.
+*
+* Two output shapes are spec-correct depending on the parent object type:
+*   - `"array"` — Schema Object: `examples: [example]` (Draft 2020-12 plural).
+*   - `"map"`   — Parameter / Header / Media Type Object: an Examples Map
+*                 keyed by name. The single value is wrapped under the
+*                 synthetic key `default` to produce a valid one-entry map
+*                 of one Example Object.
+*
+* When both `example` and `examples` coexist the spec declares them mutually
+* exclusive — `example` is dropped and `examples` wins.
+*/
+function liftExampleToExamples(node, shape) {
+	if (!("example" in node)) return;
+	if ("examples" in node) {
+		delete node.example;
+		return;
+	}
+	if (shape === "array") node.examples = [node.example];
+	else node.examples = { default: { value: node.example } };
+	delete node.example;
+}
+/**
 * Normalise OpenAPI 3.0.x `nullable` keyword to `anyOf [T, null]`.
 *
 * OpenAPI 3.0 uses `nullable: true` instead of the JSON Schema standard
@@ -20,22 +46,32 @@ import { isOpenApi30, isOpenApi31, isSwagger2, readJsonSchemaDialect } from "./c
 * 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;
+	liftExampleToExamples(node, "array");
 	if (node.nullable !== true) {
 		if ("nullable" in node) delete node.nullable;
 		return node;
 	}
 	const nullOption = { type: "null" };
+	if (typeof node.$ref === "string") {
+		const wrapper = { anyOf: [{ $ref: node.$ref }, nullOption] };
+		for (const key of REF_DOC_SIBLINGS) if (key in node) wrapper[key] = node[key];
+		return wrapper;
+	}
+	if (Array.isArray(node.enum)) {
+		if (node.enum.includes(null)) {
+			delete node.nullable;
+			return node;
+		}
+	}
 	if (Array.isArray(node.anyOf)) {
-		node.anyOf = [...node.anyOf, nullOption];
+		const existing = node.anyOf;
+		node.anyOf = compositeAlreadyAllowsNull(existing) ? existing : [...existing, nullOption];
 		delete node.nullable;
 		return node;
 	}
 	if (Array.isArray(node.oneOf)) {
-		node.anyOf = [...node.oneOf, nullOption];
+		const existing = node.oneOf;
+		node.anyOf = compositeAlreadyAllowsNull(existing) ? existing : [...existing, nullOption];
 		delete node.oneOf;
 		delete node.nullable;
 		return node;
@@ -51,6 +87,39 @@ function normaliseOpenApi30Node(node) {
 	return { anyOf: [wrapper, nullOption] };
 }
 /**
+* Documentary keys that may legitimately sit alongside a `$ref` in an
+* OpenAPI 3.0 Schema Object. They carry author-facing metadata, not
+* validation semantics, so lifting them onto the `anyOf` wrapper
+* preserves authorial intent without violating the spec rule that a
+* Reference Object itself only carry `$ref`.
+*/
+const REF_DOC_SIBLINGS = [
+	"description",
+	"summary",
+	"title",
+	"deprecated",
+	"readOnly",
+	"writeOnly",
+	"example",
+	"examples",
+	"default"
+];
+/**
+* Returns `true` when at least one option in a composite (`anyOf` /
+* `oneOf`) already permits `null` — either a literal `{ type: "null" }`
+* branch or an `enum` containing `null`. Used to dedup the synthetic
+* null option appended when normalising `nullable: true`.
+*/
+function compositeAlreadyAllowsNull(options) {
+	for (const option of options) {
+		if (!isObject(option)) continue;
+		if (option.type === "null") return true;
+		if (Array.isArray(option.type) && option.type.includes("null")) return true;
+		if (Array.isArray(option.enum) && option.enum.includes(null)) return true;
+	}
+	return false;
+}
+/**
 * Normalise OpenAPI 3.0.x `discriminator` keyword by injecting `const`
 * values into each `oneOf`/`anyOf` option's discriminator property.
 *
@@ -78,7 +147,7 @@ function normaliseOpenApi30Discriminator(node) {
 			normalisedComposite.push(option);
 			continue;
 		}
-		const props = isObject(option.properties) ? { ...option.properties } : void 0;
+		const props = isObject(option.properties) ? option.properties : void 0;
 		const discProp = props?.[propertyName];
 		if (isObject(discProp) && "const" in discProp) {
 			normalisedComposite.push(option);
@@ -100,7 +169,7 @@ function normaliseOpenApi30Discriminator(node) {
 			if (entry !== void 0) constValue = entry[0];
 		}
 		if (constValue !== void 0) {
-			const normalisedProps = props ?? {};
+			const normalisedProps = { ...props };
 			normalisedProps[propertyName] = {
 				...isObject(discProp) ? discProp : {},
 				const: constValue
@@ -113,7 +182,13 @@ 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;
 }
 /**
@@ -479,10 +554,7 @@ function normaliseParameter(param, normaliseSchema) {
 	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;
+	liftExampleToExamples(result, "map");
 	return result;
 }
 function normaliseRequestBody(requestBody, normaliseSchema) {
@@ -505,10 +577,7 @@ function normaliseHeader(header, normaliseSchema) {
 	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;
+	liftExampleToExamples(result, "map");
 	return result;
 }
 /**
@@ -531,10 +600,7 @@ function normaliseContentMap(content, normaliseSchema) {
 		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;
+		liftExampleToExamples(normalised, "map");
 		result[mediaType] = normalised;
 	}
 	return result;
@@ -579,9 +645,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}` }];
 	}
@@ -597,37 +673,90 @@ 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") {
+				const paramPointer = appendPointer(appendPointer("", "parameters"), name);
+				let bodyContentTypes;
+				if (consumesResolution.source === "synthesised") {
+					bodyContentTypes = globalConsumes;
+					emitDiagnostic(diagnostics, {
+						code: "swagger-missing-consumes",
+						message: "Global body parameter declared but document-level `consumes` is absent; defaulting to application/json",
+						pointer: paramPointer,
+						detail: {
+							level: "document",
+							name
+						}
+					});
+				} else if (globalConsumes.length === 0) {
+					bodyContentTypes = [];
+					emitDiagnostic(diagnostics, {
+						code: "swagger-missing-consumes",
+						message: "Global body parameter declared but document-level `consumes` is an explicit empty array; preserving an empty content map",
+						pointer: paramPointer,
+						detail: {
+							level: "document",
+							name,
+							reason: "explicitly-cleared",
+							source: consumesResolution.source
+						}
+					});
+				} else bodyContentTypes = globalConsumes;
+				requestBodies[name] = buildRequestBody(resolved, bodyContentTypes);
+			} 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 = {};
+		const securityDefinitionsPointer = appendPointer("", "securityDefinitions");
+		for (const [name, scheme] of Object.entries(securityDefinitions)) {
+			const schemePointer = appendPointer(securityDefinitionsPointer, name);
+			translated[name] = isObject(scheme) ? translateSwaggerSecurityScheme(scheme, diagnostics, schemePointer, name) : 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;
 	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, {
+	if (documentContainsKeyword(doc.definitions, "xml") || documentContainsKeyword(doc.paths, "xml") || documentContainsKeyword(doc.parameters, "xml") || documentContainsKeyword(doc.responses, "xml")) emitDiagnostic(diagnostics, {
 		code: "dropped-swagger-feature",
 		message: "Swagger 2.0 xml markup is not supported and will be dropped",
 		pointer: "",
@@ -637,38 +766,41 @@ function normaliseSwagger2Document(doc, deepNormalise, normaliseDraft04Node, dia
 }
 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) {
+		for (const method of SWAGGER_2_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);
+		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)) {
@@ -681,7 +813,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) {
@@ -705,16 +847,69 @@ 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 operationPointer = appendPointer(appendPointer(appendPointer("", "paths"), path), method);
+			let bodyContentTypes;
+			if (usesFormData) bodyContentTypes = formDataContentTypes(consumes);
+			else if (consumesResolution.source === "synthesised") {
+				bodyContentTypes = consumes;
+				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: operationPointer,
+					detail: {
+						level: "operation",
+						method
+					}
+				});
+			} else if (consumes.length === 0) {
+				bodyContentTypes = [];
+				emitDiagnostic(diagnostics, {
+					code: "swagger-missing-consumes",
+					message: "Operation declares a body parameter but `consumes` is an explicit empty array; preserving an empty content map",
+					pointer: operationPointer,
+					detail: {
+						level: "operation",
+						method,
+						reason: "explicitly-cleared",
+						source: consumesResolution.source
+					}
+				});
+			} else bodyContentTypes = consumes;
+			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
@@ -729,51 +924,141 @@ function formDataContentTypes(consumes) {
 	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;
+* 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).
+*
+* Uses the shared {@link resolveRefChain} helper so cycle detection
+* and hop accounting stay consistent with the other OpenAPI $ref
+* walkers.
+*/
+function resolveSwaggerParameter(param, doc) {
+	let cyclicRef;
+	const finalNode = resolveRefChain(param, {
+		extractRef: (node) => {
+			const ref = node.$ref;
+			if (typeof ref !== "string") return void 0;
+			return ref.startsWith("#/parameters/") ? ref : void 0;
+		},
+		lookup: (ref) => {
+			const name = ref.slice(13);
+			const globalParams = doc.parameters;
+			if (!isObject(globalParams)) return void 0;
+			const resolved = globalParams[name];
+			return isObject(resolved) ? resolved : void 0;
+		},
+		onCycle: (ref) => {
+			cyclicRef = ref;
 		}
-	}
-	return param;
+	});
+	if (cyclicRef !== void 0) return {
+		kind: "cycle",
+		ref: cyclicRef
+	};
+	return {
+		kind: "ok",
+		param: finalNode ?? 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":
-			result.style = "form";
+			result.style = param.in === "path" || param.in === "header" ? "simple" : "form";
 			result.explode = false;
 			break;
 		case "ssv":
@@ -781,8 +1066,15 @@ function normaliseSwaggerParameter(param, doc) {
 			result.explode = false;
 			break;
 		case "tsv":
-			result.style = "tabDelimited";
-			result.explode = false;
+			emitDiagnostic(diagnostics, {
+				code: "swagger-collection-format-dropped",
+				message: "Swagger 2.0 collectionFormat: \"tsv\" has no OpenAPI 3.x equivalent; dropping the keyword",
+				pointer,
+				detail: {
+					feature: "collectionFormat:tsv",
+					location: "parameter"
+				}
+			});
 			break;
 		case "pipes":
 			result.style = "pipeDelimited";
@@ -829,12 +1121,18 @@ function buildFormDataBody(param, allParams) {
 }
 /**
 * Build an OpenAPI 3.x request body from a Swagger 2.0 body parameter.
+*
+* `consumes` is taken at face value — the caller is responsible for
+* deciding whether an absent value should fall back to a default
+* (and emitting `swagger-missing-consumes`) or be preserved as an
+* empty content map (an explicit clear). Inventing a default here
+* would mask the difference and silently override the upstream
+* resolution.
 */
 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 } : {};
+	for (const ct of consumes) 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;
@@ -842,32 +1140,37 @@ function buildRequestBody(bodyParam, consumes) {
 }
 /**
 * Resolve a Swagger 2.0 response `$ref` (e.g. `#/responses/NotFound`).
+*
+* Uses the shared {@link resolveRefChain} helper so cycle detection
+* and hop accounting stay consistent with the other OpenAPI $ref
+* walkers. On cycle the original wrapper is returned (legacy
+* behaviour), preserving the existing response-resolution contract.
 */
-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) {
+function resolveSwaggerResponse(response, doc) {
+	return resolveRefChain(response, {
+		extractRef: (node) => {
+			const ref = node.$ref;
+			if (typeof ref !== "string") return void 0;
+			return ref.startsWith("#/responses/") ? ref : void 0;
+		},
+		lookup: (ref) => {
+			const name = ref.slice(12);
+			const globalResponses = doc.responses;
+			if (!isObject(globalResponses)) return void 0;
+			const resolved = globalResponses[name];
+			return isObject(resolved) ? resolved : void 0;
+		},
+		onCycle: () => response
+	}) ?? response;
+}
+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;
 }
@@ -880,7 +1183,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;
@@ -890,11 +1193,24 @@ 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)) {
 		const convertedHeaders = {};
-		for (const [name, header] of Object.entries(headers)) convertedHeaders[name] = isObject(header) ? normaliseSwaggerHeader(header) : header;
+		const headersPointer = appendPointer(path !== void 0 && method !== void 0 && statusCode !== void 0 ? appendPointer(appendPointer(appendPointer(appendPointer(appendPointer("", "paths"), path), method), "responses"), statusCode) : "", "headers");
+		for (const [name, header] of Object.entries(headers)) {
+			const headerPointer = appendPointer(headersPointer, name);
+			convertedHeaders[name] = isObject(header) ? normaliseSwaggerHeader(header, diagnostics, headerPointer) : header;
+		}
 		normalised.headers = convertedHeaders;
 	}
 	return normalised;
@@ -912,21 +1228,13 @@ function normaliseSwaggerSingleResponse(response, doc, produces) {
 * `simple`/`explode: false` rather than the `form` style used for query
 * parameters.
 */
-function normaliseSwaggerHeader(header) {
+function normaliseSwaggerHeader(header, diagnostics, pointer = "") {
 	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":
@@ -938,8 +1246,15 @@ function normaliseSwaggerHeader(header) {
 			result.explode = false;
 			break;
 		case "tsv":
-			result.style = "tabDelimited";
-			result.explode = false;
+			emitDiagnostic(diagnostics, {
+				code: "swagger-collection-format-dropped",
+				message: "Swagger 2.0 collectionFormat: \"tsv\" has no OpenAPI 3.x equivalent; dropping the keyword",
+				pointer,
+				detail: {
+					feature: "collectionFormat:tsv",
+					location: "header"
+				}
+			});
 			break;
 		case "pipes":
 			result.style = "pipeDelimited";
@@ -949,49 +1264,86 @@ function normaliseSwaggerHeader(header) {
 	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.
+* from Swagger 2.0 locations to OpenAPI 3.x locations using the
+* shared {@link rewriteSwaggerRefPrefix} mapping. 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;
-		}
-	}
+	if (typeof node.$ref === "string") node.$ref = rewriteSwaggerRefPrefix(node.$ref);
 	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.
+* 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 hasXmlAnywhere(node) {
-	if (!isObject(node)) {
-		if (Array.isArray(node)) {
-			for (const item of node) if (hasXmlAnywhere(item)) return true;
+function translateSwaggerSecurityScheme(scheme, diagnostics, pointer = "", name) {
+	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") {
+			emitDiagnostic(diagnostics, {
+				code: "swagger-malformed-oauth-flow",
+				message: `Swagger 2.0 oauth2 security scheme${name !== void 0 ? ` "${name}"` : ""} is missing the required \`flow\` field; preserving the original shape verbatim`,
+				pointer,
+				detail: {
+					name,
+					flow: flowName
+				}
+			});
+			return {
+				...scheme,
+				type: "oauth2"
+			};
 		}
-		return false;
+		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;
 	}
-	if ("xml" in node) return true;
-	for (const value of Object.values(node)) if (hasXmlAnywhere(value)) return true;
-	return false;
+	return { ...scheme };
 }
 //#endregion
 //#region src/core/normalise.ts
@@ -1075,24 +1427,34 @@ function deepNormalise(schema, transform, visited = /* @__PURE__ */ new WeakSet(
 	} 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;
 }
@@ -1108,34 +1470,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;
@@ -1188,17 +1532,24 @@ function collectDependencyStrings(items, property, keyword, ctx) {
 * 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).
+* - The supplied `legacyDiagnostic` code (if any) once per node that
+*   contained the deprecated keyword. Callers pass
+*   `legacy-dependencies-split-2019` on the 2019-09 path (the draft
+*   that introduced the split — authors should already have migrated)
+*   and `legacy-dependencies-split` on the defensive 2020-12 path.
 * - `dependent-required-invalid` for each array entry whose element is
 *   not a string.
+* - `dependencies-conflict` when both the legacy `dependencies` keyword
+*   and a pre-existing `dependentRequired`/`dependentSchemas` declare
+*   the same key with different values. The pre-existing modern
+*   keyword wins and the legacy value is discarded — silently
+*   overwriting would mask the author's bug.
 */
-function splitDependencies(node, ctx, emitLegacyDiagnostic) {
+function splitDependencies(node, ctx, legacyDiagnostic) {
 	const deps = node.dependencies;
 	if (!isObject(deps)) return;
-	if (emitLegacyDiagnostic && ctx !== void 0) emitDiagnostic(ctx.diagnostics, {
-		code: "legacy-dependencies-split",
+	if (legacyDiagnostic !== void 0 && ctx !== void 0) emitDiagnostic(ctx.diagnostics, {
+		code: legacyDiagnostic,
 		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) }
@@ -1211,17 +1562,61 @@ function splitDependencies(node, ctx, emitLegacyDiagnostic) {
 	} 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;
+		if (isObject(existing)) for (const [k, v] of Object.entries(requiredEntries)) {
+			if (k in existing) {
+				if (ctx !== void 0 && !arraysEqual(existing[k], v)) emitDiagnostic(ctx.diagnostics, {
+					code: "dependencies-conflict",
+					message: `Legacy \`dependencies.${k}\` conflicts with the pre-existing \`dependentRequired.${k}\`; keeping the modern keyword and discarding the legacy value`,
+					pointer: appendPointer(ctx.pointer, "dependencies"),
+					detail: {
+						key: k,
+						kept: existing[k],
+						discarded: v,
+						keyword: "dependentRequired"
+					}
+				});
+				continue;
+			}
+			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;
+		if (isObject(existing)) for (const [k, v] of Object.entries(schemaEntries)) {
+			if (k in existing) {
+				if (ctx !== void 0) emitDiagnostic(ctx.diagnostics, {
+					code: "dependencies-conflict",
+					message: `Legacy \`dependencies.${k}\` conflicts with the pre-existing \`dependentSchemas.${k}\`; keeping the modern keyword and discarding the legacy value`,
+					pointer: appendPointer(ctx.pointer, "dependencies"),
+					detail: {
+						key: k,
+						kept: existing[k],
+						discarded: v,
+						keyword: "dependentSchemas"
+					}
+				});
+				continue;
+			}
+			existing[k] = v;
+		}
 		else node.dependentSchemas = schemaEntries;
 	}
 	delete node.dependencies;
 }
 /**
+* Compare two values that should both be string arrays. Returns true
+* when both are arrays of equal length holding the same strings in
+* the same order. Used to skip the `dependencies-conflict` diagnostic
+* when the legacy and modern keywords agree.
+*/
+function arraysEqual(a, b) {
+	if (!Array.isArray(a) || !Array.isArray(b)) return false;
+	if (a.length !== b.length) return false;
+	for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return false;
+	return true;
+}
+/**
 * 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
@@ -1319,7 +1714,7 @@ function applyDraft04Translations(node, ctx) {
 		delete node.id;
 	}
 	translateTupleItems(node);
-	splitDependencies(node, ctx, false);
+	splitDependencies(node, ctx, void 0);
 	validateDependentRequired(node, ctx);
 }
 /**
@@ -1372,7 +1767,7 @@ function normaliseDraft04NodeWithContext(node, ctx) {
 */
 function normaliseDraft06Or07NodeWithContext(node, ctx) {
 	translateTupleItems(node);
-	splitDependencies(node, ctx, false);
+	splitDependencies(node, ctx, void 0);
 	validateDependentRequired(node, ctx);
 	return node;
 }
@@ -1391,34 +1786,120 @@ function normaliseDraft06Or07NodeWithContext(node, ctx) {
 * `$recursiveAnchor` names are likewise preserved as `$anchor`.
 */
 function normaliseDraft201909NodeWithContext(node, ctx) {
-	if (typeof node.$recursiveRef === "string") {
-		node.$ref = node.$recursiveRef;
+	if (node.$anchor === "__recursive__" && node.$recursiveAnchor !== true) emitDiagnostic(ctx.diagnostics, {
+		code: "recursive-anchor-collision",
+		message: `User-supplied \`$anchor: "${RECURSIVE_ANCHOR_SENTINEL}"\` collides with the canonical sentinel synthesised by the Draft 2019-09 \`$recursiveAnchor: true\` rewrite; lookups for this anchor may resolve to either declaration`,
+		pointer: appendPointer(ctx.pointer, "$anchor"),
+		detail: { anchor: RECURSIVE_ANCHOR_SENTINEL }
+	});
+	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) {
-		if (typeof node.$anchor !== "string") node.$anchor = "__recursive__";
+		if (typeof node.$anchor !== "string") node.$anchor = RECURSIVE_ANCHOR_SENTINEL;
 		delete node.$recursiveAnchor;
 	} else if (typeof node.$recursiveAnchor === "string") {
 		if (typeof node.$anchor !== "string") node.$anchor = node.$recursiveAnchor;
 		delete node.$recursiveAnchor;
 	}
+	splitDependencies(node, ctx, "legacy-dependencies-split-2019");
 	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") {
 		if (typeof node.$anchor !== "string") node.$anchor = node.$dynamicAnchor;
 		delete node.$dynamicAnchor;
 	}
-	splitDependencies(node, ctx, true);
+	translateTupleItems(node);
+	splitDependencies(node, ctx, "legacy-dependencies-split");
 	validateDependentRequired(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.
 *
@@ -1428,27 +1909,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
@@ -1486,6 +1948,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
@@ -1519,7 +2004,10 @@ function rewriteRelativeRefsNode(node, currentBase, docBase, pointer, diagnostic
 	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)) {
@@ -1588,6 +2076,24 @@ 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(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, {
@@ -1596,8 +2102,45 @@ function normaliseOpenApiSchemas(doc, version, diagnostics) {
 			pointer: "/jsonSchemaDialect",
 			detail: { uri: dialect.uri }
 		});
+		else if (dialect.kind === "known") dialectDraft = dialect.draft;
+	}
+	return deepNormaliseOpenApiDoc(applyDiscriminatorAllOfPrepass(doc), (schema) => {
+		let intermediate = schema;
+		const effectiveDraft = resolveSchemaLocalDialect(intermediate, diagnostics) ?? dialectDraft;
+		if (effectiveDraft !== void 0 && effectiveDraft !== "draft-2020-12") intermediate = deepNormaliseWithContext(intermediate, selectDraftTransform(effectiveDraft), buildRootContext(intermediate, diagnostics, effectiveDraft));
+		return resolveRelativeRefs(deepNormalise(intermediate, normaliseOpenApi30Discriminator), diagnostics);
+	});
+}
+/**
+* Resolve a Schema-Object-level `$schema` declaration to a
+* `JsonSchemaDraft`. Returns `undefined` when the keyword is absent or
+* its value is not a string; emits `unknown-json-schema-dialect` and
+* returns `undefined` when the value is a string that does not match
+* any supported draft URI. The caller falls back to the document-level
+* dialect (or 2020-12) in that case.
+*
+* Per OpenAPI 3.1 §4.7.5, the override applies to the Schema Object
+* and its subschemas. Nested overrides inside individual sub-schemas
+* are not currently honoured — the dispatch happens once at the top
+* of each Schema Object surfaced by `deepNormaliseOpenApiDoc`.
+*/
+function resolveSchemaLocalDialect(schema, diagnostics) {
+	const value = schema.$schema;
+	if (typeof value !== "string") return void 0;
+	const draft = matchJsonSchemaDraftUri(value);
+	if (draft === void 0) {
+		emitDiagnostic(diagnostics, {
+			code: "unknown-json-schema-dialect",
+			message: `Schema Object-level \`$schema\` URI "${value}" does not match a supported JSON Schema draft; falling back to the document dialect`,
+			pointer: "/$schema",
+			detail: {
+				uri: value,
+				level: "schema-object"
+			}
+		});
+		return;
 	}
-	return deepNormaliseOpenApiDoc(applyDiscriminatorAllOfPrepass(doc), (schema) => resolveRelativeRefs(deepNormalise(schema, normaliseOpenApi30Discriminator), diagnostics));
+	return draft;
 }
 //#endregion
-export { normaliseOpenApiSchemas as a, deepNormaliseOpenApi30Doc as c, normaliseOpenApi30Discriminator as d, normaliseOpenApi30Node as f, normaliseJsonSchema as i, deepNormaliseOpenApiDoc as l, deepNormaliseWithContext as n, normaliseSwagger2Document as o, normaliseDraft04Node as r, applyDiscriminatorAllOfPrepass as s, deepNormalise as t, normaliseOpenApi30Combined as u };
+export { normaliseJsonSchema as a, normaliseSwagger2Document as c, deepNormaliseOpenApiDoc as d, liftExampleToExamples as f, normaliseOpenApi30Node as h, normaliseDraft04Node as i, applyDiscriminatorAllOfPrepass as l, normaliseOpenApi30Discriminator as m, deepNormaliseWithContext as n, normaliseOpenApiSchemas as o, normaliseOpenApi30Combined as p, documentContainsKeyword as r, selectDraftTransform as s, deepNormalise as t, deepNormaliseOpenApi30Doc as u };