schema-components 1.13.0 → 1.15.0

package/dist/core/openapi30.mjs

@@ -1,223 +1,2 @@
-import { isObject } from "./guards.mjs";
-//#region src/core/openapi30.ts
-/**
-* OpenAPI 3.0.x schema normalisation.
-*
-* Transforms `nullable`, `discriminator`, `example` keywords, and walks
-* all schema locations (components, paths, parameters, request bodies,
-* responses) to apply normalisation.
-*/
-/**
-* Normalise OpenAPI 3.0.x `nullable` keyword to `anyOf [T, null]`.
-*
-* OpenAPI 3.0 uses `nullable: true` instead of the JSON Schema standard
-* `anyOf: [T, { type: "null" }]`. The walker understands the latter form
-* natively, so this normaliser converts `nullable` to `anyOf`.
-*
-* Only applied when `nullable` is explicitly `true`. `nullable: false` or
-* absent is the default and requires no transformation.
-*/
-function normaliseOpenApi30Node(node) {
-	if ("example" in node && !("examples" in node)) {
-		node.examples = [node.example];
-		delete node.example;
-	} else if ("example" in node) delete node.example;
-	if (node.nullable !== true) {
-		if ("nullable" in node) delete node.nullable;
-		return node;
-	}
-	const nullOption = { type: "null" };
-	if (Array.isArray(node.anyOf)) {
-		node.anyOf = [...node.anyOf, nullOption];
-		delete node.nullable;
-		return node;
-	}
-	if (Array.isArray(node.oneOf)) {
-		node.anyOf = [...node.oneOf, nullOption];
-		delete node.oneOf;
-		delete node.nullable;
-		return node;
-	}
-	if (Array.isArray(node.allOf)) {
-		node.anyOf = [{ allOf: node.allOf }, nullOption];
-		delete node.allOf;
-		delete node.nullable;
-		return node;
-	}
-	const wrapper = {};
-	for (const [key, value] of Object.entries(node)) if (key !== "nullable") wrapper[key] = value;
-	return { anyOf: [wrapper, nullOption] };
-}
-/**
-* Normalise OpenAPI 3.0.x `discriminator` keyword by injecting `const`
-* values into each `oneOf`/`anyOf` option's discriminator property.
-*
-* In OpenAPI 3.0, `discriminator` is a sibling of `oneOf`/`anyOf`:
-*   discriminator: { propertyName: "type" }
-* The walker detects discriminated unions from `oneOf` + `const` on a
-* property, so this normaliser injects the `const` values from the
-* `mapping` or infers them from `$ref` fragment names.
-*/
-function normaliseOpenApi30Discriminator(node) {
-	const discriminator = node.discriminator;
-	if (!isObject(discriminator)) return node;
-	const propertyName = discriminator.propertyName;
-	if (typeof propertyName !== "string") return node;
-	const mapping = isObject(discriminator.mapping) ? discriminator.mapping : void 0;
-	const composite = node.oneOf ?? node.anyOf;
-	if (!Array.isArray(composite)) return node;
-	const refToValue = /* @__PURE__ */ new Map();
-	if (mapping !== void 0) {
-		for (const [value, ref] of Object.entries(mapping)) if (typeof ref === "string") refToValue.set(ref, value);
-	}
-	const normalisedComposite = [];
-	for (const option of composite) {
-		if (!isObject(option)) {
-			normalisedComposite.push(option);
-			continue;
-		}
-		const props = isObject(option.properties) ? { ...option.properties } : void 0;
-		const discProp = props?.[propertyName];
-		if (isObject(discProp) && "const" in discProp) {
-			normalisedComposite.push(option);
-			continue;
-		}
-		let constValue;
-		if (isObject(discProp) && typeof discProp.$ref === "string") constValue = refToValue.get(discProp.$ref);
-		if (constValue === void 0 && typeof option.$ref === "string") {
-			constValue = refToValue.get(option.$ref);
-			if (constValue === void 0) {
-				const fragment = option.$ref.split("/").pop();
-				if (fragment !== void 0) constValue = fragment;
-			}
-		}
-		if (constValue === void 0 && mapping !== void 0) {
-			const optionIndex = composite.indexOf(option);
-			const mappingEntries = Object.entries(mapping);
-			const entry = optionIndex >= 0 && optionIndex < mappingEntries.length ? mappingEntries[optionIndex] : void 0;
-			if (entry !== void 0) constValue = entry[0];
-		}
-		if (constValue !== void 0) {
-			const normalisedProps = props ?? {};
-			normalisedProps[propertyName] = {
-				...isObject(discProp) ? discProp : {},
-				const: constValue
-			};
-			normalisedComposite.push({
-				...option,
-				properties: normalisedProps
-			});
-		} else normalisedComposite.push(option);
-	}
-	if ("oneOf" in node) node.oneOf = normalisedComposite;
-	else if ("anyOf" in node) node.anyOf = normalisedComposite;
-	delete node.discriminator;
-	return node;
-}
-/**
-* Combined OpenAPI 3.0.x node transform: nullable + discriminator.
-* Applied to every schema node in an OpenAPI 3.0 document.
-*/
-function normaliseOpenApi30Combined(node) {
-	return normaliseOpenApi30Discriminator(normaliseOpenApi30Node(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.
-*/
-function deepNormaliseOpenApi30Doc(doc, deepNormalise) {
-	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
-			};
-		}
-	}
-	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;
-	}
-	return result;
-}
-function normalisePathItem(pathItem, deepNormalise) {
-	const result = { ...pathItem };
-	for (const method of [
-		"get",
-		"post",
-		"put",
-		"patch",
-		"delete"
-	]) {
-		const operation = pathItem[method];
-		if (!isObject(operation)) continue;
-		result[method] = normaliseOperation(operation, deepNormalise);
-	}
-	const parameters = pathItem.parameters;
-	if (Array.isArray(parameters)) result.parameters = parameters.map((param) => isObject(param) ? normaliseParameter(param, deepNormalise) : param);
-	return result;
-}
-function normaliseOperation(operation, deepNormalise) {
-	const result = { ...operation };
-	const parameters = operation.parameters;
-	if (Array.isArray(parameters)) result.parameters = parameters.map((param) => isObject(param) ? normaliseParameter(param, deepNormalise) : param);
-	const requestBody = operation.requestBody;
-	if (isObject(requestBody)) result.requestBody = normaliseRequestBody(requestBody, deepNormalise);
-	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;
-	}
-	return result;
-}
-function normaliseParameter(param, deepNormalise) {
-	const result = { ...param };
-	const schema = param.schema;
-	if (isObject(schema)) result.schema = deepNormalise(schema, normaliseOpenApi30Combined);
-	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) {
-	const result = { ...requestBody };
-	const content = requestBody.content;
-	if (isObject(content)) result.content = normaliseContentMap(content, deepNormalise);
-	return result;
-}
-function normaliseResponse(response, deepNormalise) {
-	const result = { ...response };
-	const content = response.content;
-	if (isObject(content)) result.content = normaliseContentMap(content, deepNormalise);
-	return result;
-}
-function normaliseContentMap(content, deepNormalise) {
-	const result = {};
-	for (const [mediaType, mediaObj] of Object.entries(content)) {
-		if (!isObject(mediaObj)) {
-			result[mediaType] = mediaObj;
-			continue;
-		}
-		const normalised = { ...mediaObj };
-		const schema = mediaObj.schema;
-		if (isObject(schema)) normalised.schema = deepNormalise(schema, normaliseOpenApi30Combined);
-		if ("example" in normalised && !("examples" in normalised)) {
-			normalised.examples = { value: normalised.example };
-			delete normalised.example;
-		} else if ("example" in normalised) delete normalised.example;
-		result[mediaType] = normalised;
-	}
-	return result;
-}
-//#endregion
+import { c as normaliseOpenApi30Discriminator, l as normaliseOpenApi30Node, o as deepNormaliseOpenApi30Doc, s as normaliseOpenApi30Combined } from "../normalise-tL9FckAk.mjs";
 export { deepNormaliseOpenApi30Doc, normaliseOpenApi30Combined, normaliseOpenApi30Discriminator, normaliseOpenApi30Node };

package/dist/core/ref.d.mts

@@ -1,25 +1,2 @@
-//#region src/core/ref.d.ts
-/**
- * $ref resolution for JSON Schema.
- *
- * Handles JSON Pointer dereference, $anchor lookup, cycle detection,
- * and maximum depth limiting.
- */
-/**
- * Resolve a `$ref` in a schema against a root document.
- * Returns the original schema if no `$ref` is present.
- * Returns an unknown-schema placeholder on cycle or depth exceeded.
- */
-declare function resolveRef(schema: Record<string, unknown>, rootDocument: Record<string, unknown>, visited: Set<string>): Record<string, unknown>;
-/**
- * Dereference a JSON Pointer fragment (`#/path/to/schema`) or an
- * `$anchor` (`#SomeName`) against a root document.
- */
-declare function dereference(ref: string, root: Record<string, unknown>): Record<string, unknown> | undefined;
-/**
- * Recursively scan a schema document for a `$anchor` matching the given name.
- * Returns the schema object containing the anchor, or undefined.
- */
-declare function findAnchor(node: unknown, anchorName: string): Record<string, unknown> | undefined;
-//#endregion
-export { dereference, findAnchor, resolveRef };
+import { a as findAnchor, i as dereference, n as RefOptions, o as resolveRef, r as countDistinctRefs, t as ExternalResolver } from "../ref-DvWoULcy.mjs";
+export { ExternalResolver, RefOptions, countDistinctRefs, dereference, findAnchor, resolveRef };

package/dist/core/ref.mjs

@@ -1,46 +1,125 @@
 import { isObject } from "./guards.mjs";
+import { emitDiagnostic } from "./diagnostics.mjs";
 //#region src/core/ref.ts
 /**
 * $ref resolution for JSON Schema.
 *
 * Handles JSON Pointer dereference, $anchor lookup, cycle detection,
-* and maximum depth limiting.
+* and depth limiting derived from the document's own $ref count.
 */
 function getString(obj, key) {
 	const value = obj[key];
 	return typeof value === "string" ? value : void 0;
 }
-const MAX_REF_DEPTH = 10;
+/**
+* Count all distinct `$ref` strings reachable from a root document.
+* A chain longer than the number of distinct refs is necessarily cyclic.
+* Returns at least 1 so that single-ref schemas have a usable bound.
+*/
+function countDistinctRefs(root) {
+	const refs = /* @__PURE__ */ new Set();
+	collectRefs(root, refs);
+	return Math.max(refs.size, 1);
+}
+function collectRefs(node, refs) {
+	if (!isObject(node)) return;
+	const ref = node.$ref;
+	if (typeof ref === "string") refs.add(ref);
+	for (const value of Object.values(node)) if (isObject(value)) collectRefs(value, refs);
+	else if (Array.isArray(value)) for (const item of value) collectRefs(item, refs);
+}
 /**
 * Resolve a `$ref` in a schema against a root document.
 * Returns the original schema if no `$ref` is present.
 * Returns an unknown-schema placeholder on cycle or depth exceeded.
+*
+* The depth bound is derived from the number of distinct `$ref` strings
+* in the root document — a chain longer than that count is necessarily
+* cyclic. When `maxDepth` is not provided, a reasonable default is used.
 */
-function resolveRef(schema, rootDocument, visited) {
+function resolveRef(schema, rootDocument, visited, diagnostics, maxDepth, externalResolver) {
 	const ref = getString(schema, "$ref");
 	if (ref === void 0) return schema;
-	if (visited.has(ref)) return {
-		type: "unknown",
-		editability: "editable",
-		meta: {},
-		constraints: {}
-	};
-	if (visited.size >= MAX_REF_DEPTH) return {
-		type: "unknown",
-		editability: "editable",
-		meta: {},
-		constraints: {}
-	};
+	if (visited.has(ref)) {
+		emitDiagnostic(diagnostics, {
+			code: "unresolved-ref",
+			message: `Circular $ref detected: ${ref}`,
+			pointer: ref,
+			detail: { ref }
+		});
+		return {
+			type: "unknown",
+			editability: "editable",
+			meta: {},
+			constraints: {}
+		};
+	}
+	const depthLimit = maxDepth ?? 64;
+	if (visited.size >= depthLimit) {
+		emitDiagnostic(diagnostics, {
+			code: "depth-exceeded",
+			message: `$ref depth exceeded derived bound (${String(depthLimit)}): ${ref}`,
+			pointer: ref,
+			detail: {
+				ref,
+				depth: visited.size,
+				bound: depthLimit
+			}
+		});
+		return {
+			type: "unknown",
+			editability: "editable",
+			meta: {},
+			constraints: {}
+		};
+	}
+	if (!ref.startsWith("#") && externalResolver !== void 0) {
+		const hashIndex = ref.indexOf("#");
+		const uri = hashIndex >= 0 ? ref.slice(0, hashIndex) : ref;
+		const fragment = hashIndex >= 0 ? ref.slice(hashIndex) : "#";
+		const externalDoc = externalResolver(uri);
+		if (isObject(externalDoc)) {
+			const target = dereference(fragment, externalDoc);
+			if (target !== void 0) {
+				const nextVisited = new Set(visited);
+				nextVisited.add(ref);
+				return resolveRef(target, externalDoc, nextVisited, diagnostics, maxDepth, externalResolver);
+			}
+		}
+		emitDiagnostic(diagnostics, {
+			code: "external-ref",
+			message: `External resolver returned no document for: ${ref}`,
+			pointer: ref,
+			detail: {
+				ref,
+				uri
+			}
+		});
+		return {
+			type: "unknown",
+			editability: "editable",
+			meta: {},
+			constraints: {}
+		};
+	}
 	const resolved = dereference(ref, rootDocument);
-	if (resolved === void 0) return {
-		type: "unknown",
-		editability: "editable",
-		meta: {},
-		constraints: {}
-	};
+	if (resolved === void 0) {
+		emitDiagnostic(diagnostics, {
+			code: "unresolved-ref",
+			message: `Could not resolve $ref: ${ref}`,
+			pointer: ref,
+			detail: { ref }
+		});
+		return {
+			type: "unknown",
+			editability: "editable",
+			meta: {},
+			constraints: {}
+		};
+	}
 	const nextVisited = new Set(visited);
 	nextVisited.add(ref);
-	return resolveRef(resolved, rootDocument, nextVisited);
+	return resolveRef(resolved, rootDocument, nextVisited, diagnostics, maxDepth, externalResolver);
 }
 /**
 * Dereference a JSON Pointer fragment (`#/path/to/schema`) or an
@@ -83,4 +162,4 @@ function findAnchor(node, anchorName) {
 	}
 }
 //#endregion
-export { dereference, findAnchor, resolveRef };
+export { countDistinctRefs, dereference, findAnchor, resolveRef };

package/dist/core/renderer.d.mts

@@ -1,2 +1,2 @@
-import { a as HtmlRenderProps, c as RenderFunction, d as getRenderFunction, f as mergeHtmlResolvers, i as HtmlRenderFunction, l as RenderProps, m as typeToKey, n as BaseFieldProps, o as HtmlResolver, p as mergeResolvers, r as ComponentResolver, s as RESOLVER_KEYS, t as AllConstraints, u as getHtmlRenderFn } from "../renderer-DseHeliw.mjs";
+import { a as HtmlRenderProps, c as RenderFunction, d as getRenderFunction, f as mergeHtmlResolvers, i as HtmlRenderFunction, l as RenderProps, m as typeToKey, n as BaseFieldProps, o as HtmlResolver, p as mergeResolvers, r as ComponentResolver, s as RESOLVER_KEYS, t as AllConstraints, u as getHtmlRenderFn } from "../renderer-BdSqllx5.mjs";
 export { AllConstraints, BaseFieldProps, ComponentResolver, HtmlRenderFunction, HtmlRenderProps, HtmlResolver, RESOLVER_KEYS, RenderFunction, RenderProps, getHtmlRenderFn, getRenderFunction, mergeHtmlResolvers, mergeResolvers, typeToKey };

package/dist/core/swagger2.d.mts

@@ -1,3 +1,4 @@
+import { i as DiagnosticsOptions } from "../diagnostics-DzbZmcLI.mjs";
 import { NodeTransform } from "./normalise.mjs";
 
 //#region src/core/swagger2.d.ts
@@ -5,6 +6,6 @@ import { NodeTransform } from "./normalise.mjs";
  * Transform a Swagger 2.0 document into an OpenAPI 3.1-compatible
  * structure.
  */
-declare function normaliseSwagger2Document(doc: Record<string, unknown>, deepNormalise: (schema: Record<string, unknown>, transform: NodeTransform) => Record<string, unknown>, normaliseDraft04Node: NodeTransform): Record<string, unknown>;
+declare function normaliseSwagger2Document(doc: Record<string, unknown>, deepNormalise: (schema: Record<string, unknown>, transform: NodeTransform) => Record<string, unknown>, normaliseDraft04Node: NodeTransform, diagnostics?: DiagnosticsOptions): Record<string, unknown>;
 //#endregion
 export { normaliseSwagger2Document };