schema-components 1.12.11 → 1.14.0

package/dist/core/walker.mjs

@@ -1,196 +1,63 @@
 import { isObject } from "./guards.mjs";
-import { resolveEditability } from "./types.mjs";
+import { appendPointer, emitDiagnostic } from "./diagnostics.mjs";
+import { countDistinctRefs, resolveRef } from "./ref.mjs";
+import { extractArrayConstraints, extractObjectConstraints, stripInapplicableConstraints } from "./constraints.mjs";
+import { ANNOTATION_SIBLINGS, detectDiscriminated, mergeAllOf, mergeRefSiblings, normaliseAnyOf } from "./merge.mjs";
+import { buildBase, buildBooleanField, buildFileField, buildNullField, buildNumberField, buildStringField, buildUnknownField, extractChildOverride, extractSchemaMetaFields, getArray, getObject, getString, isPrimitive, walkDependentRequiredMap, walkSubSchemaMap, withoutKeys } from "./walkBuilders.mjs";
 //#region src/core/walker.ts
-function getString(obj, key) {
-	const value = obj[key];
-	return typeof value === "string" ? value : void 0;
-}
-function getNumber(obj, key) {
-	const value = obj[key];
-	return typeof value === "number" ? value : void 0;
-}
-function getArray(obj, key) {
-	const value = obj[key];
-	return Array.isArray(value) ? value : void 0;
-}
-function getObject(obj, key) {
-	const value = obj[key];
-	return isObject(value) ? value : void 0;
-}
-const MAX_REF_DEPTH = 10;
-function resolveRef(schema, rootDocument, visited) {
-	const ref = getString(schema, "$ref");
-	if (ref === void 0) return schema;
-	if (visited.has(ref)) return { type: "unknown" };
-	if (visited.size >= MAX_REF_DEPTH) return { type: "unknown" };
-	const resolved = dereference(ref, rootDocument);
-	if (resolved === void 0) return { type: "unknown" };
-	const nextVisited = new Set(visited);
-	nextVisited.add(ref);
-	return resolveRef(resolved, rootDocument, nextVisited);
-}
-function dereference(ref, root) {
-	if (ref === "#") return root;
-	if (!ref.startsWith("#/")) return void 0;
-	const parts = ref.slice(2).split("/");
-	if (parts.length === 1 && parts[0] === "") return root;
-	let current = root;
-	for (const part of parts) {
-		if (!isObject(current)) return void 0;
-		const decoded = part.replace(/~1/g, "/").replace(/~0/g, "~");
-		current = current[decoded];
-	}
-	return isObject(current) ? current : void 0;
-}
-/**
-* Merge multiple JSON Schema objects from allOf into one.
-* Merges: properties, required, meta fields, and constraints.
-*/
-function mergeAllOf(schemas) {
-	const merged = {};
-	const properties = {};
-	const required = [];
-	for (const entry of schemas) {
-		if (!isObject(entry)) continue;
-		const props = getObject(entry, "properties");
-		if (props !== void 0) for (const [key, value] of Object.entries(props)) properties[key] = value;
-		const req = getArray(entry, "required");
-		if (req !== void 0) {
-			for (const r of req) if (typeof r === "string" && !required.includes(r)) required.push(r);
-		}
-		for (const [key, value] of Object.entries(entry)) {
-			if (key === "properties" || key === "required" || key === "allOf" || key === "type") continue;
-			if (!(key in merged)) merged[key] = value;
-		}
-		if (!("type" in merged)) {
-			const type = getString(entry, "type");
-			if (type !== void 0) merged.type = type;
-		}
-	}
-	if (Object.keys(properties).length > 0) merged.properties = properties;
-	if (required.length > 0) merged.required = required;
-	return merged;
-}
 /**
-* Detect `anyOf: [T, { type: "null" }]` → nullable T.
-* Returns the non-null schema and a nullable flag.
+* Handle JSON Schema boolean values (Draft 06+).
+* - `true` → permissive (unknown, editable)
+* - `false` → never (cannot hold any value)
 */
-function normaliseAnyOf(options) {
-	if (options.length !== 2) return void 0;
-	let inner;
-	let hasNull = false;
-	for (const opt of options) {
-		if (!isObject(opt)) return void 0;
-		if (opt.type === "null") hasNull = true;
-		else inner = opt;
-	}
-	if (!hasNull || inner === void 0) return void 0;
+function walkBooleanSchema(value) {
+	if (value) return {
+		type: "unknown",
+		editability: "editable",
+		meta: {},
+		constraints: {}
+	};
 	return {
-		inner,
-		isNullable: true
+		type: "never",
+		editability: "presentation",
+		meta: { rejected: true },
+		constraints: {}
 	};
 }
 /**
-* Detect oneOf where every option is an object with a property
-* that has a `const` value → discriminated union.
+* Walk a sub-schema that may be an object, a boolean, or neither.
+* Dispatches to walkNode (object), walkBooleanSchema (boolean),
+* or returns unknown with a diagnostic.
 */
-function detectDiscriminated(options) {
-	if (options.length === 0) return void 0;
-	let discriminator;
-	for (const opt of options) {
-		if (!isObject(opt)) return void 0;
-		const props = getObject(opt, "properties");
-		if (props === void 0) return void 0;
-		let foundKey;
-		for (const [key, value] of Object.entries(props)) if (isObject(value) && "const" in value) {
-			foundKey = key;
-			break;
-		}
-		if (foundKey === void 0) return void 0;
-		if (discriminator === void 0) discriminator = foundKey;
-		else if (discriminator !== foundKey) return;
-	}
-	if (discriminator === void 0) return void 0;
+function walkSubSchema(value, ctx) {
+	if (isObject(value)) return walkNode(value, ctx);
+	if (typeof value === "boolean") return walkBooleanSchema(value);
 	return {
-		options: options.filter(isObject),
-		discriminator
+		type: "unknown",
+		editability: "editable",
+		meta: {},
+		constraints: {}
 	};
 }
-const META_KEYWORDS = new Set([
-	"readOnly",
-	"writeOnly",
-	"description",
-	"title",
-	"deprecated",
-	"default",
-	"component",
-	"example",
-	"examples"
-]);
-function extractMetaFromJson(schema) {
-	const meta = {};
-	for (const [key, value] of Object.entries(schema)) if (META_KEYWORDS.has(key)) meta[key] = value;
-	return meta;
-}
-function extractConstraintsFromJson(schema) {
-	const constraints = {};
-	const minLength = getNumber(schema, "minLength");
-	if (minLength !== void 0) constraints.minLength = minLength;
-	const maxLength = getNumber(schema, "maxLength");
-	if (maxLength !== void 0) constraints.maxLength = maxLength;
-	const minimum = getNumber(schema, "minimum");
-	if (minimum !== void 0) constraints.minimum = minimum;
-	const maximum = getNumber(schema, "maximum");
-	if (maximum !== void 0) constraints.maximum = maximum;
-	const pattern = getString(schema, "pattern");
-	if (pattern !== void 0) constraints.pattern = pattern;
-	const format = getString(schema, "format");
-	if (format !== void 0) constraints.format = format;
-	const minItems = getNumber(schema, "minItems");
-	if (minItems !== void 0) constraints.minItems = minItems;
-	const maxItems = getNumber(schema, "maxItems");
-	if (maxItems !== void 0) constraints.maxItems = maxItems;
-	if (format === "binary") {
-		const contentMediaType = getString(schema, "contentMediaType");
-		if (contentMediaType !== void 0) constraints.mimeTypes = [contentMediaType];
-	}
-	return constraints;
-}
-const OVERRIDE_META_KEYS = new Set([
-	"readOnly",
-	"writeOnly",
-	"description",
-	"title",
-	"deprecated",
-	"component",
-	"visible",
-	"order"
-]);
-function extractSchemaMetaFields(overrides) {
-	if (overrides === void 0) return void 0;
-	const meta = {};
-	for (const key of Object.keys(overrides)) if (OVERRIDE_META_KEYS.has(key)) meta[key] = overrides[key];
-	return Object.keys(meta).length > 0 ? meta : void 0;
-}
-function extractChildOverride(overrides, key) {
-	if (overrides === void 0) return void 0;
-	const child = overrides[key];
-	if (child === void 0 || child === null) return void 0;
-	if (typeof child !== "object" || Array.isArray(child)) return void 0;
-	const result = {};
-	for (const [k, v] of Object.entries(child)) result[k] = v;
-	return Object.keys(result).length > 0 ? result : void 0;
-}
 function walk(schema, options = {}) {
-	const { componentMeta, rootMeta, fieldOverrides, rootDocument } = options;
+	const { componentMeta, rootMeta, fieldOverrides, rootDocument, diagnostics, externalResolver } = options;
+	if (typeof schema === "boolean") return walkBooleanSchema(schema);
 	if (!isObject(schema)) return {
 		type: "unknown",
 		editability: "editable",
 		meta: {},
 		constraints: {}
 	};
+	const topRef = typeof schema.$ref === "string" ? schema.$ref : void 0;
+	if (topRef !== void 0 && !topRef.startsWith("#")) emitDiagnostic(diagnostics, {
+		code: "external-ref",
+		message: `External $ref not supported: ${topRef}`,
+		pointer: "",
+		detail: { ref: topRef }
+	});
 	const doc = rootDocument ?? schema;
-	return walkNode(resolveRef(schema, doc, /* @__PURE__ */ new Set()), {
+	const maxRefDepth = countDistinctRefs(doc);
+	return walkNode(resolveRef(schema, doc, /* @__PURE__ */ new Set(), diagnostics, maxRefDepth, externalResolver), {
 		componentMeta,
 		rootMeta,
 		fieldOverrides,
@@ -198,7 +65,11 @@ function walk(schema, options = {}) {
 		isNullable: false,
 		isOptional: false,
 		defaultValue: void 0,
-		refResults: /* @__PURE__ */ new Map()
+		refResults: /* @__PURE__ */ new Map(),
+		pointer: "",
+		diagnostics,
+		maxRefDepth,
+		externalResolver
 	});
 }
 function walkNode(schema, ctx) {
@@ -223,7 +94,8 @@ function walkNode(schema, ctx) {
 	if (ref !== void 0) {
 		const cached = ctx.refResults.get(ref);
 		if (cached !== void 0) return cached;
-		const resolved = resolveRef(schema, ctx.rootDocument, /* @__PURE__ */ new Set());
+		const hasSiblings = [...ANNOTATION_SIBLINGS].some((k) => k in schema);
+		const resolved = resolveRef(schema, ctx.rootDocument, /* @__PURE__ */ new Set(), ctx.diagnostics, ctx.maxRefDepth, ctx.externalResolver);
 		const placeholder = {
 			type: "unknown",
 			editability: "editable",
@@ -231,68 +103,172 @@ function walkNode(schema, ctx) {
 			constraints: {}
 		};
 		ctx.refResults.set(ref, placeholder);
-		const result = walkNode(resolved, ctx);
+		let result = walkNode(resolved, ctx);
+		if (hasSiblings) result = {
+			...result,
+			meta: mergeRefSiblings(schema, result.meta)
+		};
 		Object.assign(placeholder, result);
 		return placeholder;
 	}
+	const ifSchema = getObject(schema, "if");
+	if (ifSchema !== void 0) {
+		emitDiagnostic(ctx.diagnostics, {
+			code: "conditional-fallback",
+			message: "if/then/else rendered as base schema; conditionals require runtime evaluation",
+			pointer: ctx.pointer
+		});
+		const base = buildBase(withoutKeys(schema, [
+			"if",
+			"then",
+			"else"
+		]), ctx);
+		const thenSchema = getObject(schema, "then");
+		const elseSchema = getObject(schema, "else");
+		const conditional = {
+			...base,
+			type: "conditional",
+			constraints: {},
+			ifClause: walkNode(ifSchema, ctx)
+		};
+		if (thenSchema !== void 0) conditional.thenClause = walkNode(thenSchema, ctx);
+		if (elseSchema !== void 0) conditional.elseClause = walkNode(elseSchema, ctx);
+		return conditional;
+	}
+	const notSchema = getObject(schema, "not");
+	if (notSchema !== void 0) {
+		emitDiagnostic(ctx.diagnostics, {
+			code: "type-negation-fallback",
+			message: "not schema rendered as negation; TypeScript cannot negate types",
+			pointer: ctx.pointer
+		});
+		return {
+			...buildBase(withoutKeys(schema, ["not"]), ctx),
+			type: "negation",
+			constraints: {},
+			negated: walkNode(notSchema, ctx)
+		};
+	}
 	const enumValues = getArray(schema, "enum");
 	if (enumValues !== void 0) return walkEnum(schema, enumValues, ctx);
-	if ("const" in schema) return walkLiteral(schema, ctx);
+	if ("const" in schema) {
+		if (!isPrimitive(schema.const)) emitDiagnostic(ctx.diagnostics, {
+			code: "invalid-const",
+			message: `const value is not a primitive: ${typeof schema.const}`,
+			pointer: ctx.pointer,
+			detail: { constValue: schema.const }
+		});
+		return walkLiteral(schema, ctx);
+	}
 	const type = getString(schema, "type");
-	if (type === void 0) return buildField(schema, "unknown", ctx);
+	const typeArray = getArray(schema, "type");
+	if (type === void 0 && typeArray !== void 0) {
+		const nonNullTypes = typeArray.filter((t) => typeof t === "string" && t !== "null");
+		const hasNull = typeArray.includes("null");
+		if (nonNullTypes.length === 0) return buildNullField(schema, ctx);
+		if (nonNullTypes.length === 1) {
+			const walkCtx = hasNull ? {
+				...ctx,
+				isNullable: true
+			} : ctx;
+			const singleType = nonNullTypes[0];
+			if (singleType === void 0) return buildUnknownField(schema, ctx);
+			return walkNode({
+				...stripInapplicableConstraints(schema, singleType),
+				type: singleType
+			}, walkCtx);
+		}
+		const options = nonNullTypes.map((t) => ({
+			...stripInapplicableConstraints(schema, t),
+			type: t
+		}));
+		if (hasNull) return walkUnion([...options, { type: "null" }], {
+			...ctx,
+			isNullable: true
+		});
+		return walkUnion(options, ctx);
+	}
+	if (type === void 0) {
+		emitDiagnostic(ctx.diagnostics, {
+			code: "unsupported-type",
+			message: "Schema has no type, composition, enum, or const; rendering as unknown",
+			pointer: ctx.pointer
+		});
+		return buildUnknownField(schema, ctx);
+	}
 	if (type === "string") return walkString(schema, ctx);
 	if (type === "number" || type === "integer") return walkNumber(schema, ctx);
 	if (type === "boolean") return walkBoolean(schema, ctx);
-	if (type === "null") return buildField(schema, "null", ctx);
+	if (type === "null") return buildNullField(schema, ctx);
 	if (type === "object") {
 		const properties = getObject(schema, "properties");
 		if (properties !== void 0) return walkObject(schema, properties, ctx);
 		const additionalProps = getObject(schema, "additionalProperties");
 		if (additionalProps !== void 0) return walkRecord(schema, additionalProps, ctx);
-		return buildField(schema, "object", ctx);
+		return {
+			...buildBase(schema, ctx),
+			type: "object",
+			constraints: extractObjectConstraints(schema),
+			fields: {},
+			requiredFields: []
+		};
 	}
 	if (type === "array") return walkArray(schema, ctx);
-	return buildField(schema, "unknown", ctx);
+	emitDiagnostic(ctx.diagnostics, {
+		code: "unsupported-type",
+		message: `Unknown schema type: ${type}`,
+		pointer: ctx.pointer,
+		detail: { type }
+	});
+	return buildUnknownField(schema, ctx);
 }
 function walkString(schema, ctx) {
-	if (getString(schema, "format") === "binary") return buildField(schema, "file", ctx);
-	return buildField(schema, "string", ctx);
+	if (getString(schema, "format") === "binary") return buildFileField(schema, ctx);
+	const field = buildStringField(schema, ctx);
+	const contentSchema = getObject(schema, "contentSchema");
+	if (contentSchema !== void 0) field.meta.decodedSchema = walkNode(contentSchema, ctx);
+	return field;
 }
 function walkNumber(schema, ctx) {
-	return buildField(schema, "number", ctx);
+	return buildNumberField(schema, ctx);
 }
 function walkBoolean(schema, ctx) {
-	return buildField(schema, "boolean", ctx);
+	return buildBooleanField(schema, ctx);
 }
 function walkEnum(schema, enumValues, ctx) {
 	return {
-		...buildField(schema, "enum", ctx),
-		enumValues: enumValues.filter((v) => typeof v === "string")
+		...buildBase(schema, ctx),
+		type: "enum",
+		constraints: {},
+		enumValues: enumValues.filter((v) => typeof v === "string" || typeof v === "number" || typeof v === "boolean" || v === null)
 	};
 }
 function walkLiteral(schema, ctx) {
 	const constValue = schema.const;
 	const values = isPrimitive(constValue) ? [constValue] : [];
 	return {
-		...buildField(schema, "literal", ctx),
+		...buildBase(schema, ctx),
+		type: "literal",
+		constraints: {},
 		literalValues: values
 	};
 }
 function walkObject(schema, properties, ctx) {
-	const base = buildField(schema, "object", ctx);
-	const required = getArray(schema, "required");
+	const requiredFields = getArray(schema, "required")?.filter((r) => typeof r === "string") ?? [];
 	const fields = {};
 	for (const [key, propSchema] of Object.entries(properties)) {
 		const childOverride = extractChildOverride(ctx.fieldOverrides, key);
-		const isRequired = required?.includes(key) === true;
+		const isRequired = requiredFields.includes(key);
 		const childCtx = {
 			...ctx,
 			fieldOverrides: childOverride,
-			isOptional: !isRequired
+			isOptional: !isRequired,
+			pointer: appendPointer(ctx.pointer, key)
 		};
 		const overrideMeta = extractSchemaMetaFields(childOverride);
 		if (overrideMeta !== void 0 && ("readOnly" in overrideMeta || "writeOnly" in overrideMeta)) childCtx.componentMeta = void 0;
 		if (isObject(propSchema)) fields[key] = walkNode(propSchema, childCtx);
+		else if (typeof propSchema === "boolean") fields[key] = walkBooleanSchema(propSchema);
 		else fields[key] = {
 			type: "unknown",
 			editability: "editable",
@@ -300,13 +276,53 @@ function walkObject(schema, properties, ctx) {
 			constraints: {}
 		};
 	}
+	const patternProps = getObject(schema, "patternProperties");
+	const walkedPatternProps = patternProps !== void 0 ? walkSubSchemaMap(patternProps, walkNode, ctx) : void 0;
+	let additionalPropertiesClosed;
+	let additionalPropertiesSchema;
+	const additionalProps = schema.additionalProperties;
+	if (additionalProps === false) additionalPropertiesClosed = true;
+	else if (additionalProps === true) additionalPropertiesSchema = {
+		type: "unknown",
+		editability: "editable",
+		meta: {},
+		constraints: {}
+	};
+	else if (isObject(additionalProps)) additionalPropertiesSchema = walkNode(additionalProps, ctx);
+	const depSchemas = getObject(schema, "dependentSchemas");
+	const walkedDepSchemas = depSchemas !== void 0 ? walkSubSchemaMap(depSchemas, walkNode, ctx) : void 0;
+	const depReq = getObject(schema, "dependentRequired");
+	const walkedDepReq = depReq !== void 0 ? walkDependentRequiredMap(depReq) : void 0;
+	let unevaluatedProperties;
+	let unevaluatedPropertiesClosed;
+	const unevalProps = schema.unevaluatedProperties;
+	if (unevalProps === false) unevaluatedPropertiesClosed = true;
+	else if (unevalProps === true) unevaluatedProperties = {
+		type: "unknown",
+		editability: "editable",
+		meta: {},
+		constraints: {}
+	};
+	else if (isObject(unevalProps)) unevaluatedProperties = walkNode(unevalProps, ctx);
+	const propertyNamesSchema = getObject(schema, "propertyNames");
+	const walkedPropertyNames = propertyNamesSchema !== void 0 ? walkNode(propertyNamesSchema, ctx) : void 0;
 	return {
-		...base,
-		fields
+		...buildBase(schema, ctx),
+		type: "object",
+		constraints: extractObjectConstraints(schema),
+		fields,
+		requiredFields,
+		...walkedPatternProps !== void 0 && Object.keys(walkedPatternProps).length > 0 ? { patternProperties: walkedPatternProps } : {},
+		...additionalPropertiesClosed ? { additionalPropertiesClosed } : {},
+		...additionalPropertiesSchema !== void 0 ? { additionalPropertiesSchema } : {},
+		...walkedDepSchemas !== void 0 && Object.keys(walkedDepSchemas).length > 0 ? { dependentSchemas: walkedDepSchemas } : {},
+		...walkedDepReq !== void 0 && Object.keys(walkedDepReq).length > 0 ? { dependentRequired: walkedDepReq } : {},
+		...unevaluatedProperties !== void 0 ? { unevaluatedProperties } : {},
+		...unevaluatedPropertiesClosed ? { unevaluatedPropertiesClosed } : {},
+		...walkedPropertyNames !== void 0 ? { propertyNames: walkedPropertyNames } : {}
 	};
 }
 function walkRecord(schema, valueSchema, ctx) {
-	const base = buildField(schema, "record", ctx);
 	const propertyNames = getObject(schema, "propertyNames");
 	const keyType = propertyNames !== void 0 ? walkNode(propertyNames, ctx) : {
 		type: "string",
@@ -316,39 +332,61 @@ function walkRecord(schema, valueSchema, ctx) {
 	};
 	const valueType = walkNode(valueSchema, ctx);
 	return {
-		...base,
+		...buildBase(schema, ctx),
+		type: "record",
+		constraints: extractObjectConstraints(schema),
 		keyType,
 		valueType
 	};
 }
 function walkArray(schema, ctx) {
-	const base = buildField(schema, "array", ctx);
+	const prefixItems = getArray(schema, "prefixItems");
+	if (prefixItems !== void 0) {
+		const walkedItems = prefixItems.filter(isObject).map((item) => walkNode(item, ctx));
+		return {
+			...buildBase(schema, ctx),
+			type: "tuple",
+			constraints: extractArrayConstraints(schema),
+			prefixItems: walkedItems
+		};
+	}
+	const unevaluatedItemsSchema = getObject(schema, "unevaluatedItems");
+	const walkedUnevaluatedItems = unevaluatedItemsSchema !== void 0 ? walkNode(unevaluatedItemsSchema, ctx) : void 0;
 	const items = getObject(schema, "items");
 	if (items !== void 0) {
 		const elementOverride = extractChildOverride(ctx.fieldOverrides, "[]");
 		return {
-			...base,
+			...buildBase(schema, ctx),
+			type: "array",
+			constraints: extractArrayConstraints(schema),
 			element: walkNode(items, {
 				...ctx,
 				fieldOverrides: elementOverride
-			})
+			}),
+			...walkedUnevaluatedItems !== void 0 ? { unevaluatedItems: walkedUnevaluatedItems } : {}
 		};
 	}
-	return base;
+	return {
+		...buildBase(schema, ctx),
+		type: "array",
+		constraints: extractArrayConstraints(schema),
+		...walkedUnevaluatedItems !== void 0 ? { unevaluatedItems: walkedUnevaluatedItems } : {}
+	};
 }
 function walkUnion(options, ctx) {
-	const optionsArray = options.filter(isObject);
+	const walkedOptions = options.map((opt) => walkSubSchema(opt, ctx));
 	return {
-		...buildField({}, "union", ctx),
-		options: optionsArray.map((opt) => walkNode(opt, {
-			...ctx,
-			fieldOverrides: void 0
-		}))
+		...buildBase({}, ctx),
+		type: "union",
+		constraints: {},
+		options: walkedOptions
 	};
 }
 function walkDiscriminatedUnion(discriminated, ctx) {
 	return {
-		...buildField({}, "discriminatedUnion", ctx),
+		...buildBase({}, ctx),
+		type: "discriminatedUnion",
+		constraints: {},
 		options: discriminated.options.map((opt) => walkNode(opt, {
 			...ctx,
 			fieldOverrides: void 0
@@ -356,31 +394,5 @@ function walkDiscriminatedUnion(discriminated, ctx) {
 		discriminator: discriminated.discriminator
 	};
 }
-function buildField(schema, type, ctx) {
-	const propertyMeta = extractMetaFromJson(schema);
-	const overrideMeta = extractSchemaMetaFields(ctx.fieldOverrides);
-	const mergedMeta = {
-		...propertyMeta,
-		...overrideMeta
-	};
-	const defaultValue = "default" in schema ? schema.default : void 0;
-	const editability = resolveEditability(mergedMeta, ctx.componentMeta, ctx.rootMeta);
-	if ((overrideMeta !== void 0 && ("readOnly" in overrideMeta || "writeOnly" in overrideMeta) || Boolean(propertyMeta.readOnly) || Boolean(propertyMeta.writeOnly)) && ctx.componentMeta !== void 0) ctx = {
-		...ctx,
-		componentMeta: void 0
-	};
-	return {
-		type,
-		editability,
-		meta: mergedMeta,
-		isOptional: ctx.isOptional,
-		isNullable: ctx.isNullable,
-		defaultValue: defaultValue ?? ctx.defaultValue,
-		constraints: extractConstraintsFromJson(schema)
-	};
-}
-function isPrimitive(value) {
-	return typeof value === "string" || typeof value === "number" || typeof value === "boolean" || value === null;
-}
 //#endregion
 export { walk };

package/dist/diagnostics-DzbZmcLI.d.mts

@@ -0,0 +1,64 @@
+//#region src/core/diagnostics.d.ts
+/**
+ * Diagnostics channel for schema-components.
+ *
+ * Provides a structured way to surface silent fallbacks — unresolved `$ref`,
+ * unknown keywords, unknown `format` values, invalid `const` values,
+ * unsupported `type` entries, dropped Swagger 2.0 features, external
+ * `$ref`, type-negation fallbacks, and conditional fallbacks.
+ *
+ * Consumers pass a `DiagnosticSink` callback to receive diagnostics
+ * as they occur. By default, diagnostics are silently discarded.
+ * Setting `strict: true` converts any diagnostic into a thrown
+ * `SchemaCompatibilityError`.
+ */
+/**
+ * Machine-readable codes identifying each class of diagnostic.
+ * Stable across releases — consumers can pattern-match on these.
+ */
+type DiagnosticCode = "unresolved-ref" | "unknown-keyword" | "unknown-format" | "invalid-const" | "unsupported-type" | "dropped-swagger-feature" | "external-ref" | "type-negation-fallback" | "conditional-fallback" | "assumed-draft" | "depth-exceeded";
+/**
+ * A single diagnostic emitted during schema processing.
+ */
+interface Diagnostic {
+  /** Machine-readable code for programmatic handling. */
+  code: DiagnosticCode;
+  /** Human-readable description of the issue. */
+  message: string;
+  /** JSON Pointer to the schema node that triggered the diagnostic. */
+  pointer: string;
+  /** Additional context specific to the diagnostic code. */
+  detail?: Record<string, unknown>;
+}
+/**
+ * Callback that receives each diagnostic as it is emitted.
+ */
+type DiagnosticSink = (d: Diagnostic) => void;
+/**
+ * Diagnostics configuration threaded through the processing pipeline.
+ */
+interface DiagnosticsOptions {
+  /**
+   * Callback for receiving diagnostics. When omitted, diagnostics
+   * are silently discarded (preserving backward compatibility).
+   */
+  diagnostics?: DiagnosticSink;
+  /**
+   * When `true`, any diagnostic is converted to a thrown
+   * `SchemaCompatibilityError`. Useful in CI or strict mode
+   * to catch schema drift early.
+   */
+  strict?: boolean;
+}
+/**
+ * Emit a diagnostic through the configured sink.
+ * When `strict` is enabled, throws a `SchemaCompatibilityError` instead.
+ */
+declare function emitDiagnostic(opts: DiagnosticsOptions | undefined, diagnostic: Diagnostic): void;
+/**
+ * Append a segment to a JSON Pointer.
+ * Encodes `/` and `~` per RFC 6901.
+ */
+declare function appendPointer(base: string, segment: string): string;
+//#endregion
+export { appendPointer as a, DiagnosticsOptions as i, DiagnosticCode as n, emitDiagnostic as o, DiagnosticSink as r, Diagnostic as t };