schema-components 1.21.0 → 1.23.0

package/dist/core/openapiConstants.d.mts

@@ -0,0 +1,67 @@
+//#region src/core/openapiConstants.d.ts
+/**
+ * Shared OpenAPI / Swagger constants and helpers.
+ *
+ * Single source of truth for HTTP method tuples, default content types, and
+ * the Swagger 2.0 → OpenAPI 3.x reference-prefix rewriting table. Consumers
+ * import the named exports rather than hand-maintaining sibling copies that
+ * silently drift when methods or prefixes change.
+ */
+/**
+ * Canonical OpenAPI 3.x HTTP method tuple in path-item iteration order.
+ * Spec: https://spec.openapis.org/oas/v3.1.1#path-item-object
+ */
+declare const HTTP_METHODS: readonly ["get", "put", "post", "delete", "options", "head", "patch", "trace"];
+type HttpMethod = (typeof HTTP_METHODS)[number];
+/**
+ * Swagger 2.0 omits `trace` — the keyword was introduced in OpenAPI 3.0.
+ * Derived from `HTTP_METHODS` so adding a method to the canonical tuple
+ * automatically propagates here (after which the filter may need updating).
+ */
+declare const SWAGGER_2_METHODS: readonly Exclude<HttpMethod, "trace">[];
+/**
+ * Default media type used when an OpenAPI document elides `consumes` /
+ * `produces` or a Schema Object stands alone (no parent Media Type).
+ */
+declare const DEFAULT_OPENAPI_CONTENT_TYPE = "application/json";
+/**
+ * Canonical `$ref` prefix table for the JSON Pointer locations used by
+ * OpenAPI 3.x and Swagger 2.0 documents.
+ */
+declare const REF_PREFIXES: {
+  /** OpenAPI 3.x — most schemas live under `components.schemas`. */readonly components: {
+    readonly schemas: "#/components/schemas/";
+    readonly parameters: "#/components/parameters/";
+    readonly responses: "#/components/responses/";
+    readonly requestBodies: "#/components/requestBodies/";
+    readonly headers: "#/components/headers/";
+    readonly examples: "#/components/examples/";
+    readonly links: "#/components/links/";
+    readonly callbacks: "#/components/callbacks/";
+    readonly securitySchemes: "#/components/securitySchemes/";
+    readonly pathItems: "#/components/pathItems/";
+  }; /** Swagger 2.0 legacy prefixes. */
+  readonly swagger2: {
+    readonly definitions: "#/definitions/";
+    readonly parameters: "#/parameters/";
+    readonly responses: "#/responses/";
+  };
+};
+/**
+ * Swagger 2.0 → OpenAPI 3.x `$ref` prefix mapping. Applied during the
+ * 2.0 → 3.x lift to rewrite legacy pointer prefixes onto their components
+ * counterparts. Order matters: longer prefixes first prevents `#/parameters/`
+ * from shadowing `#/components/parameters/` during a partial migration.
+ */
+declare const REF_REWRITES: readonly {
+  readonly from: string;
+  readonly to: string;
+}[];
+/**
+ * Rewrite a Swagger 2.0 ref prefix onto the equivalent OpenAPI 3.x location.
+ * Returns the ref unchanged when no prefix matches. Pure string operation —
+ * does not validate that the target exists.
+ */
+declare function rewriteSwaggerRefPrefix(ref: string): string;
+//#endregion
+export { DEFAULT_OPENAPI_CONTENT_TYPE, HTTP_METHODS, HttpMethod, REF_PREFIXES, REF_REWRITES, SWAGGER_2_METHODS, rewriteSwaggerRefPrefix };

package/dist/core/openapiConstants.mjs

@@ -0,0 +1,90 @@
+//#region src/core/openapiConstants.ts
+/**
+* Shared OpenAPI / Swagger constants and helpers.
+*
+* Single source of truth for HTTP method tuples, default content types, and
+* the Swagger 2.0 → OpenAPI 3.x reference-prefix rewriting table. Consumers
+* import the named exports rather than hand-maintaining sibling copies that
+* silently drift when methods or prefixes change.
+*/
+/**
+* Canonical OpenAPI 3.x HTTP method tuple in path-item iteration order.
+* Spec: https://spec.openapis.org/oas/v3.1.1#path-item-object
+*/
+const HTTP_METHODS = [
+	"get",
+	"put",
+	"post",
+	"delete",
+	"options",
+	"head",
+	"patch",
+	"trace"
+];
+/**
+* Swagger 2.0 omits `trace` — the keyword was introduced in OpenAPI 3.0.
+* Derived from `HTTP_METHODS` so adding a method to the canonical tuple
+* automatically propagates here (after which the filter may need updating).
+*/
+const SWAGGER_2_METHODS = HTTP_METHODS.filter((m) => m !== "trace");
+/**
+* Default media type used when an OpenAPI document elides `consumes` /
+* `produces` or a Schema Object stands alone (no parent Media Type).
+*/
+const DEFAULT_OPENAPI_CONTENT_TYPE = "application/json";
+/**
+* Canonical `$ref` prefix table for the JSON Pointer locations used by
+* OpenAPI 3.x and Swagger 2.0 documents.
+*/
+const REF_PREFIXES = {
+	/** OpenAPI 3.x — most schemas live under `components.schemas`. */
+	components: {
+		schemas: "#/components/schemas/",
+		parameters: "#/components/parameters/",
+		responses: "#/components/responses/",
+		requestBodies: "#/components/requestBodies/",
+		headers: "#/components/headers/",
+		examples: "#/components/examples/",
+		links: "#/components/links/",
+		callbacks: "#/components/callbacks/",
+		securitySchemes: "#/components/securitySchemes/",
+		pathItems: "#/components/pathItems/"
+	},
+	/** Swagger 2.0 legacy prefixes. */
+	swagger2: {
+		definitions: "#/definitions/",
+		parameters: "#/parameters/",
+		responses: "#/responses/"
+	}
+};
+/**
+* Swagger 2.0 → OpenAPI 3.x `$ref` prefix mapping. Applied during the
+* 2.0 → 3.x lift to rewrite legacy pointer prefixes onto their components
+* counterparts. Order matters: longer prefixes first prevents `#/parameters/`
+* from shadowing `#/components/parameters/` during a partial migration.
+*/
+const REF_REWRITES = [
+	{
+		from: REF_PREFIXES.swagger2.definitions,
+		to: REF_PREFIXES.components.schemas
+	},
+	{
+		from: REF_PREFIXES.swagger2.parameters,
+		to: REF_PREFIXES.components.parameters
+	},
+	{
+		from: REF_PREFIXES.swagger2.responses,
+		to: REF_PREFIXES.components.responses
+	}
+];
+/**
+* Rewrite a Swagger 2.0 ref prefix onto the equivalent OpenAPI 3.x location.
+* Returns the ref unchanged when no prefix matches. Pure string operation —
+* does not validate that the target exists.
+*/
+function rewriteSwaggerRefPrefix(ref) {
+	for (const { from, to } of REF_REWRITES) if (ref.startsWith(from)) return `${to}${ref.slice(from.length)}`;
+	return ref;
+}
+//#endregion
+export { DEFAULT_OPENAPI_CONTENT_TYPE, HTTP_METHODS, REF_PREFIXES, REF_REWRITES, SWAGGER_2_METHODS, rewriteSwaggerRefPrefix };

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-si8ViYun.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-DjLEKa_E.mjs";
+export { ExternalResolver, RECURSIVE_ANCHOR_SENTINEL, RefOptions, countDistinctRefs, dereference, findAnchor, resolveRef };

package/dist/core/ref.mjs

@@ -1,4 +1,5 @@
 import { isObject } from "./guards.mjs";
+import "./limits.mjs";
 import { emitDiagnostic } from "./diagnostics.mjs";
 import { isPrototypePollutingKey } from "./uri.mjs";
 //#region src/core/ref.ts
@@ -8,6 +9,31 @@ 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.
+*
+* TODO(round7-integration): once Agent D widens the walker's resolved-
+* ref handling to dispatch through `walkSubSchema`, drop this
+* translation and surface the boolean directly.
+*/
+function booleanSchemaToObject(value) {
+	if (value) return {};
+	return { not: {} };
+}
 function getString(obj, key) {
 	const value = obj[key];
 	return typeof value === "string" ? value : void 0;
@@ -96,6 +122,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);
 			}
 		}
@@ -130,6 +157,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);
@@ -137,6 +165,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;
@@ -144,11 +181,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;
 	}
@@ -161,18 +208,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;
 		}
@@ -180,11 +248,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-DI6ZYf7a.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/renderer.mjs

@@ -43,7 +43,6 @@ const RESOLVER_KEYS = [
 	"discriminatedUnion",
 	"conditional",
 	"negation",
-	"recursive",
 	"literal",
 	"file",
 	"never",
@@ -70,7 +69,6 @@ function typeToKey(type) {
 		case "discriminatedUnion":
 		case "conditional":
 		case "negation":
-		case "recursive":
 		case "literal":
 		case "file":
 		case "never":

package/dist/core/swagger2.d.mts

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

package/dist/core/swagger2.mjs

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