schema-components 1.18.0 → 1.19.0

package/dist/{normalise-tL9FckAk.mjs → normalise-C0ofw3W6.mjs}

@@ -1,5 +1,5 @@
 import { isObject } from "./core/guards.mjs";
-import { emitDiagnostic } from "./core/diagnostics.mjs";
+import { appendPointer, emitDiagnostic } from "./core/diagnostics.mjs";
 import { isOpenApi30, isSwagger2 } from "./core/version.mjs";
 //#region src/core/openapi30.ts
 /**
@@ -7,7 +7,7 @@ import { isOpenApi30, isSwagger2 } from "./core/version.mjs";
 *
 * Transforms `nullable`, `discriminator`, `example` keywords, and walks
 * all schema locations (components, paths, parameters, request bodies,
-* responses) to apply normalisation.
+* responses, headers, callbacks, links, examples) to apply normalisation.
 */
 /**
 * Normalise OpenAPI 3.0.x `nullable` keyword to `anyOf [T, null]`.
@@ -127,86 +127,145 @@ function normaliseOpenApi30Combined(node) {
 	return normaliseOpenApi30Discriminator(normaliseOpenApi30Node(normaliseDraft04Node(node)));
 }
 /**
-* Deep-normalise all schemas in an OpenAPI 3.0.x document.
-* Walks components/schemas, path operations, parameters, request bodies,
-* and responses — applying `nullable` normalisation to each schema.
+* Deep-clone the parent first, then patch back any keys whose values were
+* rewritten by the visitor. This preserves immutability of the original
+* document while keeping the visitor straightforward to write.
 */
-function deepNormaliseOpenApi30Doc(doc, deepNormalise) {
+/**
+* Deep-normalise every Schema Object in an OpenAPI document.
+*
+* Walks: `paths.*` (operations + path-level parameters), `webhooks.*`
+* (3.1), `components.schemas`, `components.parameters`,
+* `components.responses`, `components.requestBodies`,
+* `components.headers`, `components.callbacks`, `components.pathItems`
+* (3.1). For each Schema-bearing location, applies the supplied
+* `normaliseSchema` function.
+*
+* The walker is structural (it understands OAS document shapes) and
+* delegates the per-schema transformation. For OAS 3.0 the caller
+* passes a full Draft 04 + nullable + discriminator + example
+* normaliser; for OAS 3.1 the caller passes a discriminator-only
+* normaliser so the walker's discriminated-union detection sees the
+* injected `const`s regardless of OAS minor version.
+*/
+function deepNormaliseOpenApiDoc(doc, normaliseSchema) {
 	const result = { ...doc };
 	const components = doc.components;
-	if (isObject(components)) {
-		const schemas = components.schemas;
-		if (isObject(schemas)) {
-			const normalisedSchemas = {};
-			for (const [name, schema] of Object.entries(schemas)) normalisedSchemas[name] = isObject(schema) ? deepNormalise(schema, normaliseOpenApi30Combined) : schema;
-			result.components = {
-				...components,
-				schemas: normalisedSchemas
-			};
-		}
-	}
+	if (isObject(components)) result.components = normaliseComponents(components, normaliseSchema);
 	const paths = doc.paths;
-	if (isObject(paths)) {
-		const normalisedPaths = {};
-		for (const [path, pathItem] of Object.entries(paths)) normalisedPaths[path] = isObject(pathItem) ? normalisePathItem(pathItem, deepNormalise) : pathItem;
-		result.paths = normalisedPaths;
-	}
+	if (isObject(paths)) result.paths = normalisePathMap(paths, normaliseSchema);
+	const webhooks = doc.webhooks;
+	if (isObject(webhooks)) result.webhooks = normalisePathMap(webhooks, normaliseSchema);
 	return result;
 }
-function normalisePathItem(pathItem, deepNormalise) {
+/**
+* Backwards-compatible wrapper retaining the historic `deepNormalise`
+* signature used by callers in `normalise.ts`. Always applies the full
+* 3.0 combined transform via `deepNormalise(schema, normaliseOpenApi30Combined)`.
+*/
+function deepNormaliseOpenApi30Doc(doc, deepNormalise) {
+	return deepNormaliseOpenApiDoc(doc, (schema) => deepNormalise(schema, normaliseOpenApi30Combined));
+}
+function normaliseComponents(components, normaliseSchema) {
+	const result = { ...components };
+	const schemas = components.schemas;
+	if (isObject(schemas)) result.schemas = mapObjectValues(schemas, (schema) => isObject(schema) ? normaliseSchema(schema) : schema);
+	const parameters = components.parameters;
+	if (isObject(parameters)) result.parameters = mapObjectValues(parameters, (param) => isObject(param) ? normaliseParameter(param, normaliseSchema) : param);
+	const responses = components.responses;
+	if (isObject(responses)) result.responses = mapObjectValues(responses, (response) => isObject(response) ? normaliseResponse(response, normaliseSchema) : response);
+	const requestBodies = components.requestBodies;
+	if (isObject(requestBodies)) result.requestBodies = mapObjectValues(requestBodies, (body) => isObject(body) ? normaliseRequestBody(body, normaliseSchema) : body);
+	const headers = components.headers;
+	if (isObject(headers)) result.headers = mapObjectValues(headers, (header) => isObject(header) ? normaliseHeader(header, normaliseSchema) : header);
+	const callbacks = components.callbacks;
+	if (isObject(callbacks)) result.callbacks = mapObjectValues(callbacks, (callback) => isObject(callback) ? normaliseCallback(callback, normaliseSchema) : callback);
+	const pathItems = components.pathItems;
+	if (isObject(pathItems)) result.pathItems = mapObjectValues(pathItems, (pathItem) => isObject(pathItem) ? normalisePathItem(pathItem, normaliseSchema) : pathItem);
+	return result;
+}
+function normalisePathMap(paths, normaliseSchema) {
+	return mapObjectValues(paths, (pathItem) => isObject(pathItem) ? normalisePathItem(pathItem, normaliseSchema) : pathItem);
+}
+const HTTP_METHODS = [
+	"get",
+	"put",
+	"post",
+	"delete",
+	"options",
+	"head",
+	"patch",
+	"trace"
+];
+function normalisePathItem(pathItem, normaliseSchema) {
 	const result = { ...pathItem };
-	for (const method of [
-		"get",
-		"post",
-		"put",
-		"patch",
-		"delete"
-	]) {
+	for (const method of HTTP_METHODS) {
 		const operation = pathItem[method];
-		if (!isObject(operation)) continue;
-		result[method] = normaliseOperation(operation, deepNormalise);
+		if (isObject(operation)) result[method] = normaliseOperation(operation, normaliseSchema);
 	}
 	const parameters = pathItem.parameters;
-	if (Array.isArray(parameters)) result.parameters = parameters.map((param) => isObject(param) ? normaliseParameter(param, deepNormalise) : param);
+	if (Array.isArray(parameters)) result.parameters = parameters.map((param) => isObject(param) ? normaliseParameter(param, normaliseSchema) : param);
 	return result;
 }
-function normaliseOperation(operation, deepNormalise) {
+function normaliseOperation(operation, normaliseSchema) {
 	const result = { ...operation };
 	const parameters = operation.parameters;
-	if (Array.isArray(parameters)) result.parameters = parameters.map((param) => isObject(param) ? normaliseParameter(param, deepNormalise) : param);
+	if (Array.isArray(parameters)) result.parameters = parameters.map((param) => isObject(param) ? normaliseParameter(param, normaliseSchema) : param);
 	const requestBody = operation.requestBody;
-	if (isObject(requestBody)) result.requestBody = normaliseRequestBody(requestBody, deepNormalise);
+	if (isObject(requestBody)) result.requestBody = normaliseRequestBody(requestBody, normaliseSchema);
 	const responses = operation.responses;
-	if (isObject(responses)) {
-		const normalisedResponses = {};
-		for (const [code, response] of Object.entries(responses)) normalisedResponses[code] = isObject(response) ? normaliseResponse(response, deepNormalise) : response;
-		result.responses = normalisedResponses;
-	}
+	if (isObject(responses)) result.responses = mapObjectValues(responses, (response) => isObject(response) ? normaliseResponse(response, normaliseSchema) : response);
+	const callbacks = operation.callbacks;
+	if (isObject(callbacks)) result.callbacks = mapObjectValues(callbacks, (callback) => isObject(callback) ? normaliseCallback(callback, normaliseSchema) : callback);
 	return result;
 }
-function normaliseParameter(param, deepNormalise) {
+function normaliseParameter(param, normaliseSchema) {
 	const result = { ...param };
 	const schema = param.schema;
-	if (isObject(schema)) result.schema = deepNormalise(schema, normaliseOpenApi30Combined);
+	if (isObject(schema)) result.schema = normaliseSchema(schema);
+	const content = param.content;
+	if (isObject(content)) result.content = normaliseContentMap(content, normaliseSchema);
 	if ("example" in result && !("examples" in result)) {
 		result.examples = [result.example];
 		delete result.example;
 	} else if ("example" in result) delete result.example;
 	return result;
 }
-function normaliseRequestBody(requestBody, deepNormalise) {
+function normaliseRequestBody(requestBody, normaliseSchema) {
 	const result = { ...requestBody };
 	const content = requestBody.content;
-	if (isObject(content)) result.content = normaliseContentMap(content, deepNormalise);
+	if (isObject(content)) result.content = normaliseContentMap(content, normaliseSchema);
 	return result;
 }
-function normaliseResponse(response, deepNormalise) {
+function normaliseResponse(response, normaliseSchema) {
 	const result = { ...response };
 	const content = response.content;
-	if (isObject(content)) result.content = normaliseContentMap(content, deepNormalise);
+	if (isObject(content)) result.content = normaliseContentMap(content, normaliseSchema);
+	const headers = response.headers;
+	if (isObject(headers)) result.headers = mapObjectValues(headers, (header) => isObject(header) ? normaliseHeader(header, normaliseSchema) : header);
+	return result;
+}
+function normaliseHeader(header, normaliseSchema) {
+	const result = { ...header };
+	const schema = header.schema;
+	if (isObject(schema)) result.schema = normaliseSchema(schema);
+	const content = header.content;
+	if (isObject(content)) result.content = normaliseContentMap(content, normaliseSchema);
+	if ("example" in result && !("examples" in result)) {
+		result.examples = [result.example];
+		delete result.example;
+	} else if ("example" in result) delete result.example;
 	return result;
 }
-function normaliseContentMap(content, deepNormalise) {
+/**
+* A Callback Object is a map of runtime-expression keys → Path Item
+* Objects. Each Path Item carries operations whose responses, request
+* bodies, parameters, and headers may all contain Schema Objects.
+*/
+function normaliseCallback(callback, normaliseSchema) {
+	return mapObjectValues(callback, (pathItem) => isObject(pathItem) ? normalisePathItem(pathItem, normaliseSchema) : pathItem);
+}
+function normaliseContentMap(content, normaliseSchema) {
 	const result = {};
 	for (const [mediaType, mediaObj] of Object.entries(content)) {
 		if (!isObject(mediaObj)) {
@@ -215,7 +274,9 @@ function normaliseContentMap(content, deepNormalise) {
 		}
 		const normalised = { ...mediaObj };
 		const schema = mediaObj.schema;
-		if (isObject(schema)) normalised.schema = deepNormalise(schema, normaliseOpenApi30Combined);
+		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 = { value: normalised.example };
 			delete normalised.example;
@@ -224,6 +285,22 @@ function normaliseContentMap(content, deepNormalise) {
 	}
 	return result;
 }
+function normaliseEncoding(encoding, normaliseSchema) {
+	const result = { ...encoding };
+	const headers = encoding.headers;
+	if (isObject(headers)) result.headers = mapObjectValues(headers, (header) => isObject(header) ? normaliseHeader(header, normaliseSchema) : header);
+	return result;
+}
+/**
+* Apply `transform` to each value of a `Record<string, unknown>` and
+* return a new record. Non-object values pass through transform unchanged
+* — callers add their own `isObject` guard inside `transform`.
+*/
+function mapObjectValues(source, transform) {
+	const result = {};
+	for (const [key, value] of Object.entries(source)) result[key] = transform(value);
+	return result;
+}
 //#endregion
 //#region src/core/swagger2.ts
 /**
@@ -264,16 +341,39 @@ function normaliseSwagger2Document(doc, deepNormalise, normaliseDraft04Node, dia
 		components.schemas = schemas;
 	}
 	const parameters = doc.parameters;
-	if (isObject(parameters)) components.parameters = { ...parameters };
+	const requestBodies = {};
+	if (isObject(parameters)) {
+		const globalConsumes = Array.isArray(doc.consumes) ? doc.consumes : ["application/json"];
+		const convertedParameters = {};
+		for (const [name, param] of Object.entries(parameters)) {
+			if (!isObject(param)) {
+				convertedParameters[name] = param;
+				continue;
+			}
+			const resolved = resolveSwaggerParameter(param, doc);
+			const location = resolved.in;
+			if (location === "body") requestBodies[name] = buildRequestBody(resolved, globalConsumes);
+			else if (location === "formData") requestBodies[name] = buildRequestBody(buildFormDataBody(resolved, [resolved]), ["multipart/form-data"]);
+			else convertedParameters[name] = normaliseSwaggerParameter(resolved, doc);
+		}
+		if (Object.keys(convertedParameters).length > 0) components.parameters = convertedParameters;
+	}
 	const responses = doc.responses;
-	if (isObject(responses)) components.responses = { ...responses };
+	if (isObject(responses)) {
+		const globalProduces = Array.isArray(doc.produces) ? doc.produces : ["application/json"];
+		const convertedResponses = {};
+		for (const [name, response] of Object.entries(responses)) convertedResponses[name] = isObject(response) ? normaliseSwaggerSingleResponse(response, doc, globalProduces) : response;
+		components.responses = convertedResponses;
+	}
+	if (Object.keys(requestBodies).length > 0) components.requestBodies = requestBodies;
 	const securityDefinitions = doc.securityDefinitions;
 	if (isObject(securityDefinitions)) components.securitySchemes = { ...securityDefinitions };
 	if (Object.keys(components).length > 0) result.components = components;
 	if (Array.isArray(doc.tags)) result.tags = doc.tags;
 	if (isObject(doc.externalDocs)) result.externalDocs = doc.externalDocs;
+	if (Array.isArray(doc.security)) result.security = doc.security;
 	rewriteSwaggerRefs(result);
-	if (isObject(doc.xml) || isObject(doc.definitions) && hasXmlInSchemas(doc.definitions)) emitDiagnostic(diagnostics, {
+	if (hasXmlAnywhere(doc.definitions) || hasXmlAnywhere(doc.paths) || hasXmlAnywhere(doc.parameters) || hasXmlAnywhere(doc.responses)) emitDiagnostic(diagnostics, {
 		code: "dropped-swagger-feature",
 		message: "Swagger 2.0 xml markup is not supported and will be dropped",
 		pointer: "",
@@ -480,21 +580,33 @@ function normaliseSwaggerResponses(responses, doc, produces) {
 			result[code] = response;
 			continue;
 		}
-		const resolved = resolveSwaggerResponse(response, doc);
-		const normalised = {};
-		for (const [key, value] of Object.entries(resolved)) if (key !== "schema") normalised[key] = value;
-		const schema = resolved.schema;
-		if (isObject(schema)) {
-			const content = {};
-			const contentTypes = produces.length > 0 ? produces : ["application/json"];
-			for (const ct of contentTypes) if (typeof ct === "string") content[ct] = { schema };
-			normalised.content = content;
-		}
-		result[code] = normalised;
+		result[code] = normaliseSwaggerSingleResponse(response, doc, produces);
 	}
 	return result;
 }
 /**
+* Normalise a single Swagger 2.0 response object — resolves any `$ref` to
+* `#/responses/<Name>` and wraps a top-level `schema` in an OpenAPI 3.x
+* `content` map keyed by the supplied media types.
+*
+* Extracted so the same logic applies whether the response sits inside an
+* operation’s `responses` map or under document-level `responses`
+* (now `components.responses`).
+*/
+function normaliseSwaggerSingleResponse(response, doc, produces) {
+	const resolved = resolveSwaggerResponse(response, doc);
+	const normalised = {};
+	for (const [key, value] of Object.entries(resolved)) if (key !== "schema") normalised[key] = value;
+	const schema = resolved.schema;
+	if (isObject(schema)) {
+		const content = {};
+		const contentTypes = produces.length > 0 ? produces : ["application/json"];
+		for (const ct of contentTypes) if (typeof ct === "string") content[ct] = { schema };
+		normalised.content = content;
+	}
+	return normalised;
+}
+/**
 * 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.
@@ -522,10 +634,21 @@ function rewriteSwaggerRefs(node) {
 	else if (Array.isArray(value)) for (const item of value) rewriteSwaggerRefs(item);
 }
 /**
-* Check if any schema in a definitions block contains an `xml` property.
+* Recursively check whether any node in the supplied subtree carries an
+* `xml` annotation. Walks both objects and arrays so the check works for
+* schemas (definitions, parameter schemas, response schemas, request body
+* schemas) as well as operations and parameters that may carry `xml`
+* metadata at any depth.
 */
-function hasXmlInSchemas(definitions) {
-	for (const schema of Object.values(definitions)) if (isObject(schema) && "xml" in schema) return true;
+function hasXmlAnywhere(node) {
+	if (!isObject(node)) {
+		if (Array.isArray(node)) {
+			for (const item of node) if (hasXmlAnywhere(item)) return true;
+		}
+		return false;
+	}
+	if ("xml" in node) return true;
+	for (const value of Object.values(node)) if (hasXmlAnywhere(value)) return true;
 	return false;
 }
 //#endregion
@@ -602,6 +725,107 @@ function deepNormalise(schema, transform) {
 	} else result[key] = value;
 	return result;
 }
+function normaliseArrayWithContext(items, transform, ctx) {
+	const result = [];
+	for (let i = 0; i < items.length; i++) {
+		const item = items[i];
+		if (isObject(item)) result.push(deepNormaliseWithContext(item, transform, {
+			diagnostics: ctx.diagnostics,
+			pointer: appendPointer(ctx.pointer, String(i))
+		}));
+		else result.push(item);
+	}
+	return result;
+}
+function normaliseSubSchemaMapWithContext(map, transform, ctx) {
+	const result = {};
+	for (const [k, v] of Object.entries(map)) if (isObject(v)) result[k] = deepNormaliseWithContext(v, transform, {
+		diagnostics: ctx.diagnostics,
+		pointer: appendPointer(ctx.pointer, k)
+	});
+	else result[k] = v;
+	return result;
+}
+/**
+* Deep-normalise a JSON Schema object, threading a context (diagnostics
+* sink + JSON Pointer) through each recursive call. Used by the JSON
+* Schema normalisation path so per-node transforms can emit diagnostics
+* with accurate pointers.
+*
+* Mirrors `deepNormalise` structurally — keep the two in sync when
+* adding new sub-schema locations.
+*/
+function deepNormaliseWithContext(schema, transform, ctx) {
+	const node = transform({ ...schema }, ctx);
+	const result = {};
+	for (const [key, value] of Object.entries(node)) if (isObject(value) && OBJECT_SUBSCHEMA_KEYS.has(key)) result[key] = normaliseSubSchemaMapWithContext(value, transform, {
+		diagnostics: ctx.diagnostics,
+		pointer: appendPointer(ctx.pointer, key)
+	});
+	else if (Array.isArray(value) && ARRAY_SUBSCHEMA_KEYS.has(key)) result[key] = normaliseArrayWithContext(value, transform, {
+		diagnostics: ctx.diagnostics,
+		pointer: appendPointer(ctx.pointer, key)
+	});
+	else if (isObject(value) && SINGLE_SUBSCHEMA_KEYS.has(key)) result[key] = deepNormaliseWithContext(value, transform, {
+		diagnostics: ctx.diagnostics,
+		pointer: appendPointer(ctx.pointer, key)
+	});
+	else if (key === "items") if (Array.isArray(value)) result[key] = normaliseArrayWithContext(value, transform, {
+		diagnostics: ctx.diagnostics,
+		pointer: appendPointer(ctx.pointer, key)
+	});
+	else if (isObject(value)) result[key] = deepNormaliseWithContext(value, transform, {
+		diagnostics: ctx.diagnostics,
+		pointer: appendPointer(ctx.pointer, key)
+	});
+	else result[key] = value;
+	else if (key === "dependencies" && isObject(value)) {
+		const normalised = {};
+		const depsPointer = appendPointer(ctx.pointer, key);
+		for (const [dk, dv] of Object.entries(value)) if (isObject(dv)) normalised[dk] = deepNormaliseWithContext(dv, transform, {
+			diagnostics: ctx.diagnostics,
+			pointer: appendPointer(depsPointer, dk)
+		});
+		else normalised[dk] = dv;
+		result[key] = normalised;
+	} else result[key] = value;
+	return result;
+}
+/**
+* Walk an array of supposed required-property names. Each non-string
+* element triggers a `dependent-required-invalid` diagnostic against
+* the supplied context. Returns the collected string entries when
+* every element validates, or `undefined` when at least one entry
+* was invalid (signalling the caller should drop the property
+* entirely rather than emit a partial rewrite).
+*
+* `keyword` distinguishes diagnostics that originate from the legacy
+* `dependencies` keyword versus the modern `dependentRequired`.
+*/
+function collectDependencyStrings(items, property, keyword, ctx) {
+	const strings = [];
+	let sawInvalid = false;
+	for (let i = 0; i < items.length; i++) {
+		const item = items[i];
+		if (typeof item === "string") {
+			strings.push(item);
+			continue;
+		}
+		sawInvalid = true;
+		if (ctx === void 0) continue;
+		emitDiagnostic(ctx.diagnostics, {
+			code: "dependent-required-invalid",
+			message: `\`${keyword}.${property}[${String(i)}]\` is not a string; only string property names are valid in a required-dependency array`,
+			pointer: appendPointer(appendPointer(appendPointer(ctx.pointer, keyword), property), String(i)),
+			detail: {
+				property,
+				index: i,
+				value: item
+			}
+		});
+	}
+	return sawInvalid ? void 0 : strings;
+}
 /**
 * Split the legacy `dependencies` keyword into `dependentRequired` and
 * `dependentSchemas` per the Draft 2019-09+ replacement.
@@ -612,15 +836,28 @@ function deepNormalise(schema, transform) {
 *
 * Both forms can coexist within the same `dependencies` object.
 * After splitting, `dependencies` is removed from the node.
+*
+* When `ctx` is supplied, diagnostics are emitted for:
+* - `legacy-dependencies-split` once per node that contained the
+*   deprecated keyword (callers pass this only on draft paths where
+*   the keyword is unexpected, e.g. 2020-12).
+* - `dependent-required-invalid` for each array entry whose element is
+*   not a string.
 */
-function splitDependencies(node) {
+function splitDependencies(node, ctx, emitLegacyDiagnostic) {
 	const deps = node.dependencies;
 	if (!isObject(deps)) return;
+	if (emitLegacyDiagnostic && ctx !== void 0) emitDiagnostic(ctx.diagnostics, {
+		code: "legacy-dependencies-split",
+		message: "Legacy `dependencies` keyword was split into `dependentRequired`/`dependentSchemas`; `dependencies` was deprecated in Draft 2019-09",
+		pointer: appendPointer(ctx.pointer, "dependencies"),
+		detail: { keys: Object.keys(deps) }
+	});
 	const requiredEntries = {};
 	const schemaEntries = {};
 	for (const [key, value] of Object.entries(deps)) if (Array.isArray(value)) {
-		const strings = value.filter((v) => typeof v === "string");
-		if (strings.length === value.length) requiredEntries[key] = strings;
+		const accepted = collectDependencyStrings(value, key, "dependencies", ctx);
+		if (accepted !== void 0) requiredEntries[key] = accepted;
 	} else if (isObject(value)) schemaEntries[key] = value;
 	if (Object.keys(requiredEntries).length > 0) {
 		const existing = node.dependentRequired;
@@ -635,21 +872,36 @@ function splitDependencies(node) {
 	delete node.dependencies;
 }
 /**
-* Normalise Draft 04 `exclusiveMinimum`/`exclusiveMaximum` from boolean
-* to number form.
+* Emit diagnostics for any non-string entries inside a pre-existing
+* `dependentRequired` keyword. Used on draft paths where the author may
+* have already migrated to the Draft 2019-09 form but still produced
+* invalid array entries. The keyword value is not rewritten — the
+* walker is responsible for honouring (or rejecting) the constraint.
+*/
+function validateDependentRequired(node, ctx) {
+	if (ctx === void 0) return;
+	const dr = node.dependentRequired;
+	if (!isObject(dr)) return;
+	for (const [key, value] of Object.entries(dr)) {
+		if (!Array.isArray(value)) continue;
+		collectDependencyStrings(value, key, "dependentRequired", ctx);
+	}
+}
+/**
+* Apply the version-agnostic Draft 04 keyword translations to a single
+* node: boolean exclusive-min/max → number form, bare `id` → `$id`, and
+* tuple-form `items` → `prefixItems`.
 *
-* In Draft 04:
-* - `exclusiveMinimum: true` + `minimum: 5` → value must be > 5
-* - `exclusiveMinimum: false` (or absent) + `minimum: 5` → value must be >= 5
+* `divisibleBy` is also translated to `multipleOf` (a Draft 03 carryover
+* that legitimately appears in legacy Draft 04 schemas). When `ctx` is
+* supplied and both keywords are present with conflicting values, a
+* `divisible-by-conflict` diagnostic is emitted.
 *
-* In Draft 06+:
-* - `exclusiveMinimum: 5` → value must be > 5 (no separate `minimum`)
-* - `minimum: 5` → value must be >= 5
-*
-* The transform converts boolean form to number form so the walker can
-* treat `exclusiveMinimum`/`exclusiveMaximum` uniformly as numbers.
+* `dependencies` is split into `dependentRequired`/`dependentSchemas`
+* via {@link splitDependencies}; passing `ctx` enables per-entry
+* diagnostics for non-string array members.
 */
-function normaliseDraft04Node(node) {
+function applyDraft04Translations(node, ctx) {
 	if (node.exclusiveMinimum === true && typeof node.minimum === "number") {
 		node.exclusiveMinimum = node.minimum;
 		delete node.minimum;
@@ -658,6 +910,22 @@ function normaliseDraft04Node(node) {
 		node.exclusiveMaximum = node.maximum;
 		delete node.maximum;
 	} else if (node.exclusiveMaximum === false) delete node.exclusiveMaximum;
+	const divisibleBy = node.divisibleBy;
+	if (typeof divisibleBy === "number") {
+		const multipleOf = node.multipleOf;
+		if (typeof multipleOf === "number") {
+			if (ctx !== void 0 && divisibleBy !== multipleOf) emitDiagnostic(ctx.diagnostics, {
+				code: "divisible-by-conflict",
+				message: `Legacy \`divisibleBy\` (${String(divisibleBy)}) conflicts with \`multipleOf\` (${String(multipleOf)}); keeping \`multipleOf\``,
+				pointer: ctx.pointer,
+				detail: {
+					divisibleBy,
+					multipleOf
+				}
+			});
+		} else node.multipleOf = divisibleBy;
+		delete node.divisibleBy;
+	}
 	if (typeof node.id === "string" && !("$id" in node)) {
 		node.$id = node.id;
 		delete node.id;
@@ -670,7 +938,42 @@ function normaliseDraft04Node(node) {
 			delete node.additionalItems;
 		}
 	}
-	splitDependencies(node);
+	splitDependencies(node, ctx, false);
+	validateDependentRequired(node, ctx);
+}
+/**
+* Normalise Draft 04 `exclusiveMinimum`/`exclusiveMaximum` from boolean
+* to number form, plus the other Draft 04 translations applied to a
+* single node.
+*
+* In Draft 04:
+* - `exclusiveMinimum: true` + `minimum: 5` → value must be > 5
+* - `exclusiveMinimum: false` (or absent) + `minimum: 5` → value must be >= 5
+*
+* In Draft 06+:
+* - `exclusiveMinimum: 5` → value must be > 5 (no separate `minimum`)
+* - `minimum: 5` → value must be >= 5
+*
+* The transform converts boolean form to number form so the walker can
+* treat `exclusiveMinimum`/`exclusiveMaximum` uniformly as numbers.
+*
+* This function preserves the no-context signature for the OpenAPI 3.0
+* and Swagger 2.0 normalisers that compose it directly. The JSON Schema
+* normalisation path uses {@link normaliseDraft04NodeWithContext} via
+* {@link deepNormaliseWithContext} to thread diagnostics.
+*/
+function normaliseDraft04Node(node) {
+	applyDraft04Translations(node, void 0);
+	return node;
+}
+/**
+* Context-aware Draft 04 per-node transform. Identical to
+* {@link normaliseDraft04Node} but threads a {@link NodeContext} so
+* `divisibleBy`/`multipleOf` conflicts and invalid dependency entries
+* can be surfaced as diagnostics with accurate pointers.
+*/
+function normaliseDraft04NodeWithContext(node, ctx) {
+	applyDraft04Translations(node, ctx);
 	return node;
 }
 /**
@@ -681,8 +984,9 @@ function normaliseDraft04Node(node) {
 * legacy `dependencies` keyword. Split it into `dependentRequired` /
 * `dependentSchemas` so the walker can process them uniformly.
 */
-function normaliseDraft06Or07Node(node) {
-	splitDependencies(node);
+function normaliseDraft06Or07NodeWithContext(node, ctx) {
+	splitDependencies(node, ctx, false);
+	validateDependentRequired(node, ctx);
 	return node;
 }
 /**
@@ -693,22 +997,28 @@ function normaliseDraft06Or07Node(node) {
 * `$recursiveAnchor: true` — the normaliser converts
 * `$recursiveRef: "#"` to `$ref: "#"` pointing to the root.
 *
-* If a `$recursiveAnchor` name is given (non-empty string), the ref
-* is converted to `$ref: "#<anchor>"` so the existing $anchor
-* resolution in ref.ts can find it.
+* The original `$recursiveRef` value is preserved (rather than
+* collapsed to `"#"`) so that anchored variants such as
+* `$recursiveRef: "#meta"` resolve correctly against the
+* corresponding `$recursiveAnchor` name. String-valued
+* `$recursiveAnchor` names are likewise preserved as `$anchor`.
 */
-function normaliseDraft201909Node(node) {
+function normaliseDraft201909NodeWithContext(node, ctx) {
 	if (typeof node.$recursiveRef === "string") {
-		node.$ref = "#";
+		node.$ref = node.$recursiveRef;
 		delete node.$recursiveRef;
 	}
 	if (node.$recursiveAnchor === true) {
 		if (typeof node.$anchor !== "string") node.$anchor = "__recursive__";
 		delete node.$recursiveAnchor;
+	} else if (typeof node.$recursiveAnchor === "string") {
+		if (typeof node.$anchor !== "string") node.$anchor = node.$recursiveAnchor;
+		delete node.$recursiveAnchor;
 	}
+	validateDependentRequired(node, ctx);
 	return node;
 }
-function normaliseDynamicRefNode(node) {
+function normaliseDynamicRefNodeWithContext(node, ctx) {
 	if (typeof node.$dynamicRef === "string") {
 		node.$ref = node.$dynamicRef;
 		delete node.$dynamicRef;
@@ -717,19 +1027,30 @@ function normaliseDynamicRefNode(node) {
 		if (typeof node.$anchor !== "string") node.$anchor = node.$dynamicAnchor;
 		delete node.$dynamicAnchor;
 	}
+	splitDependencies(node, ctx, true);
+	validateDependentRequired(node, ctx);
 	return node;
 }
 /**
 * Normalise a JSON Schema to canonical Draft 2020-12 form.
 * Deep-clones the input — the original is never mutated.
+*
+* When `diagnostics` is supplied, per-node transforms emit diagnostics
+* for legacy-keyword rewrites and invalid constructs (e.g. `divisibleBy`
+* conflicts, non-string entries in a `dependentRequired` array, legacy
+* `dependencies` reaching the 2020-12 path).
 */
-function normaliseJsonSchema(schema, draft) {
+function normaliseJsonSchema(schema, draft, diagnostics) {
+	const ctx = {
+		diagnostics,
+		pointer: ""
+	};
 	switch (draft) {
-		case "draft-04": return deepNormalise(schema, normaliseDraft04Node);
-		case "draft-2019-09": return deepNormalise(schema, normaliseDraft201909Node);
-		case "draft-2020-12": return deepNormalise(schema, normaliseDynamicRefNode);
+		case "draft-04": return deepNormaliseWithContext(schema, normaliseDraft04NodeWithContext, ctx);
+		case "draft-2019-09": return deepNormaliseWithContext(schema, normaliseDraft201909NodeWithContext, ctx);
+		case "draft-2020-12": return deepNormaliseWithContext(schema, normaliseDynamicRefNodeWithContext, ctx);
 		case "draft-06":
-		case "draft-07": return deepNormalise(schema, normaliseDraft06Or07Node);
+		case "draft-07": return deepNormaliseWithContext(schema, normaliseDraft06Or07NodeWithContext, ctx);
 	}
 }
 /**
@@ -742,7 +1063,7 @@ function normaliseJsonSchema(schema, draft) {
 function normaliseOpenApiSchemas(doc, version, diagnostics) {
 	if (isSwagger2(version)) return normaliseSwagger2Document(doc, deepNormalise, normaliseDraft04Node, diagnostics);
 	if (isOpenApi30(version)) return deepNormaliseOpenApi30Doc(doc, deepNormalise);
-	return doc;
+	return deepNormaliseOpenApiDoc(doc, (schema) => deepNormalise(schema, normaliseOpenApi30Discriminator));
 }
 //#endregion
-export { normaliseSwagger2Document as a, normaliseOpenApi30Discriminator as c, normaliseOpenApiSchemas as i, normaliseOpenApi30Node as l, normaliseDraft04Node as n, deepNormaliseOpenApi30Doc as o, normaliseJsonSchema as r, normaliseOpenApi30Combined as s, deepNormalise as t };
+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 };