schema-components 1.13.0 → 1.15.0

package/dist/core/walker.mjs

@@ -1,19 +1,63 @@
 import { isObject } from "./guards.mjs";
-import { resolveRef } from "./ref.mjs";
+import { appendPointer, emitDiagnostic } from "./diagnostics.mjs";
+import { countDistinctRefs, resolveRef } from "./ref.mjs";
 import { extractArrayConstraints, extractObjectConstraints, stripInapplicableConstraints } from "./constraints.mjs";
-import { detectDiscriminated, mergeAllOf, normaliseAnyOf } from "./merge.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
+/**
+* Handle JSON Schema boolean values (Draft 06+).
+* - `true` → permissive (unknown, editable)
+* - `false` → never (cannot hold any value)
+*/
+function walkBooleanSchema(value) {
+	if (value) return {
+		type: "unknown",
+		editability: "editable",
+		meta: {},
+		constraints: {}
+	};
+	return {
+		type: "never",
+		editability: "presentation",
+		meta: { rejected: true },
+		constraints: {}
+	};
+}
+/**
+* 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 walkSubSchema(value, ctx) {
+	if (isObject(value)) return walkNode(value, ctx);
+	if (typeof value === "boolean") return walkBooleanSchema(value);
+	return {
+		type: "unknown",
+		editability: "editable",
+		meta: {},
+		constraints: {}
+	};
+}
 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,
@@ -21,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) {
@@ -46,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",
@@ -54,12 +103,21 @@ 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",
@@ -78,15 +136,30 @@ function walkNode(schema, ctx) {
 		return conditional;
 	}
 	const notSchema = getObject(schema, "not");
-	if (notSchema !== void 0) return {
-		...buildBase(withoutKeys(schema, ["not"]), ctx),
-		type: "negation",
-		constraints: {},
-		negated: walkNode(notSchema, ctx)
-	};
+	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");
 	const typeArray = getArray(schema, "type");
 	if (type === void 0 && typeArray !== void 0) {
@@ -115,7 +188,14 @@ function walkNode(schema, ctx) {
 		});
 		return walkUnion(options, ctx);
 	}
-	if (type === void 0) return buildUnknownField(schema, 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);
@@ -134,11 +214,20 @@ function walkNode(schema, ctx) {
 		};
 	}
 	if (type === "array") return walkArray(schema, 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 buildFileField(schema, ctx);
-	return buildStringField(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 buildNumberField(schema, ctx);
@@ -173,11 +262,13 @@ function walkObject(schema, properties, ctx) {
 		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",
@@ -191,6 +282,12 @@ function walkObject(schema, properties, ctx) {
 	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;
@@ -200,6 +297,12 @@ function walkObject(schema, properties, ctx) {
 	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;
@@ -271,15 +374,12 @@ function walkArray(schema, ctx) {
 	};
 }
 function walkUnion(options, ctx) {
-	const optionsArray = options.filter(isObject);
+	const walkedOptions = options.map((opt) => walkSubSchema(opt, ctx));
 	return {
 		...buildBase({}, ctx),
 		type: "union",
 		constraints: {},
-		options: optionsArray.map((opt) => walkNode(opt, {
-			...ctx,
-			fieldOverrides: void 0
-		}))
+		options: walkedOptions
 	};
 }
 function walkDiscriminatedUnion(discriminated, ctx) {

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 };

package/dist/html/a11y.d.mts

@@ -1,5 +1,5 @@
-import { j as WalkedField } from "../types-ag2jYLqQ.mjs";
-import { t as AllConstraints } from "../renderer-DseHeliw.mjs";
+import { M as WalkedField } from "../types-D_5ST7SS.mjs";
+import { t as AllConstraints } from "../renderer-BdSqllx5.mjs";
 import { HtmlAttributes, HtmlNode } from "./html.mjs";
 
 //#region src/html/a11y.d.ts

package/dist/html/renderToHtml.d.mts

@@ -1,5 +1,5 @@
-import { w as SchemaMeta } from "../types-ag2jYLqQ.mjs";
-import { o as HtmlResolver } from "../renderer-DseHeliw.mjs";
+import { T as SchemaMeta } from "../types-D_5ST7SS.mjs";
+import { o as HtmlResolver } from "../renderer-BdSqllx5.mjs";
 
 //#region src/html/renderToHtml.d.ts
 interface RenderToHtmlOptions {

package/dist/html/renderToHtmlStream.d.mts

@@ -1,5 +1,5 @@
-import { w as SchemaMeta } from "../types-ag2jYLqQ.mjs";
-import { o as HtmlResolver } from "../renderer-DseHeliw.mjs";
+import { T as SchemaMeta } from "../types-D_5ST7SS.mjs";
+import { o as HtmlResolver } from "../renderer-BdSqllx5.mjs";
 
 //#region src/html/renderToHtmlStream.d.ts
 interface StreamRenderOptions {

package/dist/html/renderers.d.mts

@@ -1,5 +1,5 @@
-import { j as WalkedField } from "../types-ag2jYLqQ.mjs";
-import { o as HtmlResolver } from "../renderer-DseHeliw.mjs";
+import { M as WalkedField } from "../types-D_5ST7SS.mjs";
+import { o as HtmlResolver } from "../renderer-BdSqllx5.mjs";
 
 //#region src/html/renderers.d.ts
 declare function dateInputType(format: string | undefined): string | undefined;

package/dist/html/streamRenderers.d.mts

@@ -1,5 +1,5 @@
-import { j as WalkedField } from "../types-ag2jYLqQ.mjs";
-import { o as HtmlResolver } from "../renderer-DseHeliw.mjs";
+import { M as WalkedField } from "../types-D_5ST7SS.mjs";
+import { o as HtmlResolver } from "../renderer-BdSqllx5.mjs";
 import { HtmlElement } from "./html.mjs";
 
 //#region src/html/streamRenderers.d.ts