schema-components 1.22.0 → 1.24.0

package/dist/core/ref.d.mts

@@ -1,2 +1,2 @@
-import { a as findAnchor, i as dereference, n as RefOptions, o as resolveRef, r as countDistinctRefs, t as ExternalResolver } from "../ref-D-_JBZkF.mjs";
-export { ExternalResolver, RefOptions, countDistinctRefs, dereference, findAnchor, resolveRef };
+import { a as dereference, i as countDistinctRefs, n as RECURSIVE_ANCHOR_SENTINEL, o as findAnchor, r as RefOptions, s as resolveRef, t as ExternalResolver } from "../ref-DCDuswPe.mjs";
+export { ExternalResolver, RECURSIVE_ANCHOR_SENTINEL, RefOptions, countDistinctRefs, dereference, findAnchor, resolveRef };

package/dist/core/ref.mjs

@@ -9,6 +9,30 @@ import { isPrototypePollutingKey } from "./uri.mjs";
 * Handles JSON Pointer dereference, $anchor lookup, cycle detection,
 * and depth limiting derived from the document's own $ref count.
 */
+/**
+* The canonical recursive `$anchor` name synthesised by the Draft
+* 2019-09 `$recursiveAnchor: true` rewrite. Re-exported here so the
+* collision check in {@link findAnchor} stays aligned with the
+* rewriter in `core/normalise.ts`.
+*/
+const RECURSIVE_ANCHOR_SENTINEL = "__recursive__";
+/**
+* Translate a boolean sub-schema (Draft 06+) into a `Record<string,unknown>`
+* the walker can interpret with no semantic loss:
+*
+*   `true`  → `{}`               (always-valid schema)
+*   `false` → `{ not: {} }`      (never-valid schema)
+*
+* Used by {@link resolveRef} so callers that expect an object schema
+* can continue without per-call-site boolean handling. The walker's
+* sub-schema dispatch (`walkSubSchema`) handles booleans natively at
+* non-root positions; this translation covers the degenerate case
+* where a top-level `$ref` resolves to a boolean schema.
+*/
+function booleanSchemaToObject(value) {
+	if (value) return {};
+	return { not: {} };
+}
 function getString(obj, key) {
 	const value = obj[key];
 	return typeof value === "string" ? value : void 0;
@@ -97,6 +121,7 @@ function resolveRef(schema, rootDocument, visited, diagnostics, maxDepth, extern
 			if (target !== void 0) {
 				const nextVisited = new Set(visited);
 				nextVisited.add(ref);
+				if (typeof target === "boolean") return booleanSchemaToObject(target);
 				return resolveRef(target, externalDoc, nextVisited, diagnostics, maxDepth, externalResolver);
 			}
 		}
@@ -131,6 +156,7 @@ function resolveRef(schema, rootDocument, visited, diagnostics, maxDepth, extern
 			constraints: {}
 		};
 	}
+	if (typeof resolved === "boolean") return booleanSchemaToObject(resolved);
 	const nextVisited = new Set(visited);
 	nextVisited.add(ref);
 	return resolveRef(resolved, rootDocument, nextVisited, diagnostics, maxDepth, externalResolver);
@@ -138,6 +164,15 @@ function resolveRef(schema, rootDocument, visited, diagnostics, maxDepth, extern
 /**
 * Dereference a JSON Pointer fragment (`#/path/to/schema`) or an
 * `$anchor` (`#SomeName`) against a root document.
+*
+* Returns the resolved sub-schema, which may be a JSON object or — per
+* Draft 06+ — a boolean (`true` for the always-valid schema, `false`
+* for the never-valid schema). Returns `undefined` when the pointer or
+* anchor cannot be resolved.
+*
+* JSON Pointer segments are percent-decoded per RFC 6901 §6 before the
+* `~1`/`~0` token expansion; this allows pointers such as
+* `#/paths/~1pets%20store` to resolve a path containing a literal space.
 */
 function dereference(ref, root) {
 	if (ref === "#") return root;
@@ -145,11 +180,21 @@ function dereference(ref, root) {
 		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, "~");
+		for (let i = 0; i < parts.length; i++) {
+			const part = parts[i];
+			if (part === void 0) return void 0;
+			let percentDecoded;
+			try {
+				percentDecoded = decodeURIComponent(part);
+			} catch {
+				return;
+			}
+			const decoded = percentDecoded.replace(/~1/g, "/").replace(/~0/g, "~");
 			if (isPrototypePollutingKey(decoded)) return void 0;
-			current = current[decoded];
+			if (!isObject(current)) return void 0;
+			const next = current[decoded];
+			if (i === parts.length - 1 && typeof next === "boolean") return next;
+			current = next;
 		}
 		return isObject(current) ? current : void 0;
 	}
@@ -162,18 +207,39 @@ function dereference(ref, root) {
 * Recursively scan a schema document for a `$anchor` matching the given name.
 * Returns the schema object containing the anchor, or undefined.
 *
+* Per JSON Schema 2020-12 §8.2, `$anchor` is scoped to the resource
+* defined by the nearest enclosing `$id`. A bare DFS would happily
+* cross resource boundaries and resolve to an anchor declared in an
+* unrelated sub-resource — that violates the spec and produces wrong
+* walker input when two sub-schemas use the same anchor name within
+* their own `$id` scope.
+*
+* The walk skips into any sub-tree that introduces a new `$id` value:
+* such a sub-tree is a separate resource and its `$anchor`s belong to
+* that resource, not the caller's. Anchors declared at the same `$id`
+* scope (or in nested sub-schemas without their own `$id`) remain
+* reachable.
+*
 * The optional `visited` set guards against shared object references and
 * cycles introduced by the OpenAPI bundler's `structuredClone`-based
 * inlining of external refs. Without it a recursive document would stack
 * overflow before reaching the matching anchor.
+*
+* When `crossResourceBoundary` is `true` the walker is currently
+* recursing into a sub-tree that introduced its own `$id`; we still
+* recurse so a nested `$anchor` declared inside that same sub-resource
+* is reachable from the caller that owns that resource, but we skip
+* further nested resources for the same reason as above.
 */
 function findAnchor(node, anchorName, visited = /* @__PURE__ */ new WeakSet()) {
 	if (!isObject(node)) return void 0;
 	if (visited.has(node)) return void 0;
 	visited.add(node);
 	if (node.$anchor === anchorName) return node;
-	for (const value of Object.values(node)) {
+	for (const [key, value] of Object.entries(node)) {
+		if (key === "$id") continue;
 		if (isObject(value)) {
+			if (introducesNewResource(value)) continue;
 			const found = findAnchor(value, anchorName, visited);
 			if (found !== void 0) return found;
 		}
@@ -181,11 +247,22 @@ function findAnchor(node, anchorName, visited = /* @__PURE__ */ new WeakSet()) {
 			if (visited.has(value)) continue;
 			visited.add(value);
 			for (const item of value) {
+				if (isObject(item) && introducesNewResource(item)) continue;
 				const found = findAnchor(item, anchorName, visited);
 				if (found !== void 0) return found;
 			}
 		}
 	}
 }
+/**
+* A sub-tree introduces a new resource when it carries a non-empty
+* string `$id`. JSON Schema 2020-12 treats such a sub-tree as the
+* root of a separate resource — its `$anchor` declarations live in
+* that resource's scope, not the enclosing one.
+*/
+function introducesNewResource(node) {
+	const id = node.$id;
+	return typeof id === "string" && id.length > 0;
+}
 //#endregion
-export { countDistinctRefs, dereference, findAnchor, resolveRef };
+export { RECURSIVE_ANCHOR_SENTINEL, countDistinctRefs, dereference, findAnchor, resolveRef };

package/dist/core/refChain.d.mts

@@ -0,0 +1,70 @@
+//#region src/core/refChain.d.ts
+/**
+ * Generic single-pass `$ref` chain resolver.
+ *
+ * Several OpenAPI / JSON Schema code paths follow `$ref` indirection with
+ * cycle and depth protection — Path Item refs, Parameter / Response refs,
+ * Reference Object → Reference Object chains, etc. Each call site previously
+ * hand-rolled the loop; this helper centralises the discipline so cycle
+ * detection, depth-cap behaviour, and the lookup boundary are consistent.
+ *
+ * The helper is intentionally lookup-shape agnostic: it walks `string` refs
+ * via a user-supplied `lookup`, recording each ref string in a `Set` to
+ * detect cycles, and tracking hop count against `maxHops`. The caller chooses
+ * what to do on cycle or depth-cap via `onCycle` / `onDepthExceeded`.
+ */
+/** Maximum number of `$ref` hops permitted by default. */
+declare const DEFAULT_REF_CHAIN_MAX_HOPS = 8;
+/**
+ * Configuration for a single chain resolution.
+ *
+ * `lookup(ref)` returns the dereferenced node for a given `$ref` string, or
+ * `undefined` when the ref cannot be resolved. The chain follows further
+ * `$ref` indirection on the returned node until either:
+ *
+ *  - The node is not a ref wrapper (final value reached) → returns the node.
+ *  - The same ref string is encountered twice → calls `onCycle(ref)`.
+ *  - The hop count exceeds `maxHops` → calls `onDepthExceeded(ref)`.
+ *  - `lookup` returns `undefined` → returns `undefined`.
+ *
+ * Callers decide whether `onCycle` / `onDepthExceeded` should throw, emit
+ * a diagnostic, or return a fallback value.
+ */
+interface ResolveRefChainOptions<T> {
+  /** Resolve a `$ref` string to its target node, or `undefined`. */
+  readonly lookup: (ref: string) => T | undefined;
+  /**
+   * Extract a `$ref` string from a node, or `undefined` when the node is
+   * not a ref wrapper. The default reads `node.$ref` when `node` is an
+   * object with a string `$ref` property.
+   */
+  readonly extractRef?: (node: T) => string | undefined;
+  /**
+   * Called when a previously-visited `$ref` is encountered. Returns the
+   * value the resolver should return in place of further resolution.
+   */
+  readonly onCycle?: (ref: string) => T | undefined;
+  /**
+   * Called when `maxHops` is exceeded. Returns the value the resolver
+   * should return in place of further resolution.
+   */
+  readonly onDepthExceeded?: (ref: string) => T | undefined;
+  /**
+   * Maximum number of `$ref` hops permitted before `onDepthExceeded` fires.
+   * Defaults to `DEFAULT_REF_CHAIN_MAX_HOPS`.
+   */
+  readonly maxHops?: number;
+  /**
+   * Pre-seeded visited-set. Useful when the caller has already followed
+   * one or more hops outside this helper.
+   */
+  readonly visited?: Set<string>;
+}
+/**
+ * Resolve a `$ref` chain starting from `initial`. See `ResolveRefChainOptions`
+ * for the contract. Returns the final dereferenced node, the cycle/depth
+ * fallback, or `undefined` when a hop cannot be resolved.
+ */
+declare function resolveRefChain<T>(initial: T, options: ResolveRefChainOptions<T>): T | undefined;
+//#endregion
+export { DEFAULT_REF_CHAIN_MAX_HOPS, ResolveRefChainOptions, resolveRefChain };

package/dist/core/refChain.mjs

@@ -0,0 +1,44 @@
+//#region src/core/refChain.ts
+/**
+* Generic single-pass `$ref` chain resolver.
+*
+* Several OpenAPI / JSON Schema code paths follow `$ref` indirection with
+* cycle and depth protection — Path Item refs, Parameter / Response refs,
+* Reference Object → Reference Object chains, etc. Each call site previously
+* hand-rolled the loop; this helper centralises the discipline so cycle
+* detection, depth-cap behaviour, and the lookup boundary are consistent.
+*
+* The helper is intentionally lookup-shape agnostic: it walks `string` refs
+* via a user-supplied `lookup`, recording each ref string in a `Set` to
+* detect cycles, and tracking hop count against `maxHops`. The caller chooses
+* what to do on cycle or depth-cap via `onCycle` / `onDepthExceeded`.
+*/
+/** Maximum number of `$ref` hops permitted by default. */
+const DEFAULT_REF_CHAIN_MAX_HOPS = 8;
+function defaultExtractRef(node) {
+	if (typeof node !== "object" || node === null) return void 0;
+	if (!("$ref" in node)) return void 0;
+	const { $ref } = node;
+	return typeof $ref === "string" ? $ref : void 0;
+}
+/**
+* Resolve a `$ref` chain starting from `initial`. See `ResolveRefChainOptions`
+* for the contract. Returns the final dereferenced node, the cycle/depth
+* fallback, or `undefined` when a hop cannot be resolved.
+*/
+function resolveRefChain(initial, options) {
+	const { lookup, extractRef = defaultExtractRef, onCycle, onDepthExceeded, maxHops = 8, visited = /* @__PURE__ */ new Set() } = options;
+	let current = initial;
+	let hops = 0;
+	while (current !== void 0) {
+		const ref = extractRef(current);
+		if (ref === void 0) return current;
+		if (visited.has(ref)) return onCycle !== void 0 ? onCycle(ref) : void 0;
+		visited.add(ref);
+		if (hops >= maxHops) return onDepthExceeded !== void 0 ? onDepthExceeded(ref) : void 0;
+		hops += 1;
+		current = lookup(ref);
+	}
+}
+//#endregion
+export { DEFAULT_REF_CHAIN_MAX_HOPS, resolveRefChain };

package/dist/core/renderer.d.mts

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

package/dist/core/swagger2.d.mts

@@ -1,4 +1,4 @@
-import { i as DiagnosticsOptions } from "../diagnostics-D0QCYGv0.mjs";
+import { i as DiagnosticsOptions } from "../diagnostics-Cbwak-ZX.mjs";
 import { NodeTransform } from "./normalise.mjs";
 
 //#region src/core/swagger2.d.ts

package/dist/core/swagger2.mjs

@@ -1,2 +1,2 @@
-import { s as normaliseSwagger2Document } from "../normalise-DVEJQmF7.mjs";
+import { c as normaliseSwagger2Document } from "../normalise-DCYp06Sr.mjs";
 export { normaliseSwagger2Document };