@kubb/ast 5.5.6 → 5.6.0

package/dist/index.cjs

@@ -363,63 +363,6 @@ const contentDef = defineNode({
 */
 const createContent = contentDef.create;
 //#endregion
-//#region ../../internals/utils/src/fs.ts
-/**
-* Strips the file extension from a path or file name.
-* Only removes the last `.ext` segment when the dot is not part of a directory name.
-*
-* @example
-* trimExtName('petStore.ts')             // 'petStore'
-* trimExtName('/src/models/pet.ts')      // '/src/models/pet'
-* trimExtName('/project.v2/gen/pet.ts')  // '/project.v2/gen/pet'
-* trimExtName('noExtension')             // 'noExtension'
-*/
-function trimExtName(text) {
-	const dotIndex = text.lastIndexOf(".");
-	if (dotIndex > 0 && !text.includes("/", dotIndex)) return text.slice(0, dotIndex);
-	return text;
-}
-//#endregion
-//#region ../../internals/utils/src/promise.ts
-/**
-* Wraps `factory` with a keyed cache backed by the provided store.
-*
-* Pass a `WeakMap` for object keys (results are GC-eligible when the key is
-* collected) or a `Map` for primitive keys. For multi-argument functions,
-* nest two `memoize` calls — the outer keyed by the first argument, the
-* inner (created once per outer miss) keyed by the second.
-*
-* Because the cache is owned by the caller, it can be shared, inspected, or
-* cleared independently of the memoized function.
-*
-* @example Single WeakMap key
-* ```ts
-* const cache = new WeakMap<SchemaNode, Set<string>>()
-* const getRefs = memoize(cache, (node) => collectRefs(node))
-* ```
-*
-* @example Single Map key (primitive)
-* ```ts
-* const cache = new Map<string, Resolver>()
-* const getResolver = memoize(cache, (name) => buildResolver(name))
-* ```
-*
-* @example Two-level (object + primitive)
-* ```ts
-* const outer = new WeakMap<Params[], Map<string, Params[]>>()
-* const fn = memoize(outer, (params) => memoize(new Map(), (key) => transform(params, key)))
-* fn(params)('camelcase')
-* ```
-*/
-function memoize(store, factory) {
-	return (key) => {
-		if (store.has(key)) return store.get(key);
-		const value = factory(key);
-		store.set(key, value);
-		return value;
-	};
-}
-//#endregion
 //#region src/utils/extractStringsFromNodes.ts
 /**
 * Extracts all string content from a `CodeNode` tree recursively.
@@ -435,15 +378,11 @@ function extractStringsFromNodes(nodes) {
 			if (node) collected.push(node);
 			continue;
 		}
-		if (node.kind === "Text") {
+		if (node.kind === "Text" || node.kind === "Jsx") {
 			if (node.value) collected.push(node.value);
 			continue;
 		}
 		if (node.kind === "Break") continue;
-		if (node.kind === "Jsx") {
-			if (node.value) collected.push(node.value);
-			continue;
-		}
 		const parts = [];
 		if ("params" in node && node.params) parts.push(node.params);
 		if ("generics" in node && node.generics) parts.push(Array.isArray(node.generics) ? node.generics.join(", ") : node.generics);
@@ -463,22 +402,11 @@ const IDENTIFIER_RUN = /[\w$]+/g;
 */
 const INDEX_ABOVE_IMPORTS = 128;
 /**
-* Every unbroken run of identifier characters in the source.
+* Returns the local binding an import name item introduces: the alias when there is one, else the
+* imported name.
 */
-function collectIdentifiers(source) {
-	return new Set(source.match(IDENTIFIER_RUN));
-}
-function sourceKey(source) {
-	return `${source.name ?? extractStringsFromNodes(source.nodes)}:${source.isExportable ?? false}:${source.isTypeOnly ?? false}`;
-}
-function pathTypeKey(path, isTypeOnly) {
-	return `${path}:${isTypeOnly ?? false}`;
-}
-function exportKey(path, name, isTypeOnly, asAlias) {
-	return `${path}:${name ?? ""}:${isTypeOnly ?? false}:${asAlias ?? ""}`;
-}
-function importKey(path, name, isTypeOnly) {
-	return `${path}:${name ?? ""}:${isTypeOnly ?? false}`;
+function importLocalName(item) {
+	return typeof item === "string" ? item : item.name ?? item.propertyName;
 }
 /**
 * Computes a multi-level sort key for exports and imports:
@@ -492,6 +420,36 @@ function sortKey(node) {
 	return `${isArray}:${typeOnly}:${node.path}:${hasName}:${name}`;
 }
 /**
+* Sorts members by {@link sortKey}. Keys are computed once per node, not per comparison.
+*/
+function sortMembers(nodes) {
+	return nodes.map((node) => ({
+		node,
+		key: sortKey(node)
+	})).sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0).map(({ node }) => node);
+}
+/**
+* Returns a collector for array-named members. A member whose path and `isTypeOnly` were already
+* seen folds its names into that entry, otherwise it joins `result` as a new entry.
+*/
+function mergeByPath(result) {
+	const byPath = /* @__PURE__ */ new Map();
+	return ({ node, names }) => {
+		const key = `${node.path}:${node.isTypeOnly ?? false}`;
+		const existing = byPath.get(key);
+		if (existing && Array.isArray(existing.name)) {
+			existing.name = [.../* @__PURE__ */ new Set([...existing.name, ...names])];
+			return;
+		}
+		const item = {
+			...node,
+			name: names
+		};
+		result.push(item);
+		byPath.set(key, item);
+	};
+}
+/**
 * Deduplicates `SourceNode` objects by `name + isExportable + isTypeOnly`, keeping the first of each
 * key. Unnamed sources fall back to their extracted node strings as the name part of the key. Returns
 * the deduplicated array in original order.
@@ -499,22 +457,12 @@ function sortKey(node) {
 function combineSources(sources) {
 	const seen = /* @__PURE__ */ new Map();
 	for (const source of sources) {
-		const key = sourceKey(source);
+		const key = `${source.name ?? extractStringsFromNodes(source.nodes)}:${source.isExportable ?? false}:${source.isTypeOnly ?? false}`;
 		if (!seen.has(key)) seen.set(key, source);
 	}
 	return [...seen.values()];
 }
 /**
-* Merges `incoming` names into `existing`, preserving order and dropping duplicates.
-*
-* Shared by `combineExports` and `combineImports` for the same-path name-merge case.
-*/
-function mergeNameArrays(existing, incoming) {
-	const merged = new Set(existing);
-	for (const name of incoming) merged.add(name);
-	return [...merged];
-}
-/**
 * Deduplicates and merges `ExportNode` objects by path and type.
 *
 * Named exports with the same path and `isTypeOnly` flag have their names merged into a single export.
@@ -522,34 +470,21 @@ function mergeNameArrays(existing, incoming) {
 */
 function combineExports(exports) {
 	const result = [];
-	const namedByPath = /* @__PURE__ */ new Map();
+	const merge = mergeByPath(result);
 	const seen = /* @__PURE__ */ new Set();
-	const keyed = exports.map((node) => ({
-		node,
-		key: sortKey(node)
-	}));
-	keyed.sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
-	for (const { node: curr } of keyed) {
+	for (const curr of sortMembers(exports)) {
 		const { name, path, isTypeOnly, asAlias } = curr;
 		if (Array.isArray(name)) {
-			if (!name.length) continue;
-			const key = pathTypeKey(path, isTypeOnly);
-			const existing = namedByPath.get(key);
-			if (existing && Array.isArray(existing.name)) existing.name = mergeNameArrays(existing.name, name);
-			else {
-				const newItem = {
-					...curr,
-					name: [...new Set(name)]
-				};
-				result.push(newItem);
-				namedByPath.set(key, newItem);
-			}
-		} else {
-			const key = exportKey(path, name, isTypeOnly, asAlias);
-			if (!seen.has(key)) {
-				result.push(curr);
-				seen.add(key);
-			}
+			if (name.length) merge({
+				node: curr,
+				names: [...new Set(name)]
+			});
+			continue;
+		}
+		const key = `${path}:${name ?? ""}:${isTypeOnly ?? false}:${asAlias ?? ""}`;
+		if (!seen.has(key)) {
+			result.push(curr);
+			seen.add(key);
 		}
 	}
 	return result;
@@ -562,7 +497,7 @@ function combineExports(exports) {
 */
 function combineImports(imports, exports, source) {
 	const exportedNames = new Set(exports.flatMap((e) => Array.isArray(e.name) ? e.name : e.name ? [e.name] : []));
-	const identifiers = source && imports.length > INDEX_ABOVE_IMPORTS ? collectIdentifiers(source) : null;
+	const identifiers = source && imports.length > INDEX_ABOVE_IMPORTS ? new Set(source.match(IDENTIFIER_RUN)) : null;
 	const isUsed = (importName) => !source || identifiers?.has(importName) || source.includes(importName) || exportedNames.has(importName);
 	const importNameMemo = /* @__PURE__ */ new Map();
 	const canonicalizeName = (n) => {
@@ -572,43 +507,26 @@ function combineImports(imports, exports, source) {
 		return importNameMemo.get(key);
 	};
 	const pathsWithUsedNamedImport = /* @__PURE__ */ new Set();
-	for (const node of imports) {
-		if (!Array.isArray(node.name)) continue;
-		if (node.name.some((item) => typeof item === "string" ? isUsed(item) : isUsed(item.name ?? item.propertyName))) pathsWithUsedNamedImport.add(node.path);
-	}
+	for (const node of imports) if (Array.isArray(node.name) && node.name.some((item) => isUsed(importLocalName(item)))) pathsWithUsedNamedImport.add(node.path);
 	const result = [];
-	const namedByPath = /* @__PURE__ */ new Map();
+	const merge = mergeByPath(result);
 	const seen = /* @__PURE__ */ new Set();
-	const keyed = imports.map((node) => ({
-		node,
-		key: sortKey(node)
-	}));
-	keyed.sort((a, b) => a.key < b.key ? -1 : a.key > b.key ? 1 : 0);
-	for (const { node: curr } of keyed) {
+	for (const curr of sortMembers(imports)) {
 		if (curr.path === curr.root) continue;
-		const { path, isTypeOnly } = curr;
-		let { name } = curr;
+		const { name, path, isTypeOnly } = curr;
 		if (Array.isArray(name)) {
-			name = [...new Set(name.map(canonicalizeName))].filter((item) => typeof item === "string" ? isUsed(item) : isUsed(item.name ?? item.propertyName));
-			if (!name.length) continue;
-			const key = pathTypeKey(path, isTypeOnly);
-			const existing = namedByPath.get(key);
-			if (existing && Array.isArray(existing.name)) existing.name = mergeNameArrays(existing.name, name);
-			else {
-				const newItem = {
-					...curr,
-					name
-				};
-				result.push(newItem);
-				namedByPath.set(key, newItem);
-			}
-		} else {
-			if (name && !isUsed(name) && !pathsWithUsedNamedImport.has(path)) continue;
-			const key = importKey(path, name, isTypeOnly);
-			if (!seen.has(key)) {
-				result.push(curr);
-				seen.add(key);
-			}
+			const names = [...new Set(name.map(canonicalizeName))].filter((item) => isUsed(importLocalName(item)));
+			if (names.length) merge({
+				node: curr,
+				names
+			});
+			continue;
+		}
+		if (!isUsed(name) && !pathsWithUsedNamedImport.has(path)) continue;
+		const key = `${path}:${name}:${isTypeOnly ?? false}`;
+		if (!seen.has(key)) {
+			result.push(curr);
+			seen.add(key);
 		}
 	}
 	return result;
@@ -713,12 +631,10 @@ function createFile(input) {
 			if (item.name) localNames.add(item.name);
 		}
 		const source = sourceParts.join("\n") || void 0;
-		const combinedImports = combineImports(input.imports, resolvedExports, source);
-		const nameOf = (item) => typeof item === "string" ? item : item.name ?? item.propertyName;
-		return combinedImports.flatMap((imp) => {
+		return combineImports(input.imports, resolvedExports, source).flatMap((imp) => {
 			if (imp.path === input.path) return [];
 			if (!Array.isArray(imp.name)) return typeof imp.name === "string" && localNames.has(imp.name) ? [] : [imp];
-			const kept = imp.name.filter((item) => !localNames.has(nameOf(item)));
+			const kept = imp.name.filter((item) => !localNames.has(importLocalName(item)));
 			if (!kept.length) return [];
 			return [kept.length === imp.name.length ? imp : {
 				...imp,
@@ -731,7 +647,7 @@ function createFile(input) {
 		kind: "File",
 		...input,
 		id: (0, node_crypto.hash)("sha256", input.path, "hex"),
-		name: trimExtName(input.baseName),
+		name: node_path.default.basename(input.baseName, extname),
 		extname,
 		imports: resolvedImports,
 		exports: resolvedExports,
@@ -746,14 +662,15 @@ function createFile(input) {
 */
 const inputDef = defineNode({
 	kind: "Input",
-	defaults: {
+	build: (props) => ({
 		schemas: [],
 		operations: [],
 		meta: {
 			circularNames: [],
 			enumNames: []
-		}
-	},
+		},
+		...props
+	}),
 	children: ["schemas", "operations"],
 	visitorKey: "input"
 });
@@ -851,22 +768,27 @@ function optionality(schema, required) {
 		nullish: !required && nullable ? true : void 0
 	};
 }
+/**
+* Defaults `required` to `false` and derives the schema's `optional`/`nullish` flags from it.
+* Shared build step of `createProperty` and `createParameter`.
+*/
+function withRequired(props) {
+	const required = props.required ?? false;
+	return {
+		...props,
+		required,
+		schema: optionality(props.schema, required)
+	};
+}
 //#endregion
 //#region src/nodes/parameter.ts
 /**
 * Definition for the {@link ParameterNode}. `required` defaults to `false`, and the schema's
-* `optional`/`nullish` flags are derived from it through {@link optionality}.
+* `optional`/`nullish` flags are derived from it through {@link withRequired}.
 */
 const parameterDef = defineNode({
 	kind: "Parameter",
-	build: (props) => {
-		const required = props.required ?? false;
-		return {
-			...props,
-			required,
-			schema: optionality(props.schema, required)
-		};
-	},
+	build: withRequired,
 	children: ["schema"],
 	visitorKey: "parameter"
 });
@@ -888,18 +810,11 @@ const createParameter = parameterDef.create;
 //#region src/nodes/property.ts
 /**
 * Definition for the {@link PropertyNode}. `required` defaults to `false`, and the schema's
-* `optional`/`nullish` flags are derived from it through {@link optionality}.
+* `optional`/`nullish` flags are derived from it through {@link withRequired}.
 */
 const propertyDef = defineNode({
 	kind: "Property",
-	build: (props) => {
-		const required = props.required ?? false;
-		return {
-			...props,
-			required,
-			schema: optionality(props.schema, required)
-		};
-	},
+	build: withRequired,
 	children: ["schema"],
 	visitorKey: "property"
 });
@@ -1000,7 +915,9 @@ const schemaDef = defineNode({
 		"properties",
 		"items",
 		"members",
-		"additionalProperties"
+		"additionalProperties",
+		"patternProperties",
+		"rest"
 	],
 	visitorKey: "schema"
 });
@@ -1055,9 +972,21 @@ function isNode(value) {
 	return typeof value === "object" && value !== null && typeof value.kind === "string";
 }
 /**
-* Returns the immediate traversable children of `node` based on {@link VISITOR_KEYS}.
-*
-* `Schema` children are only included when `recurse` is `true`. Shallow mode skips them.
+* Returns `true` for a plain object that maps names to nodes, such as `patternProperties`.
+*/
+function isNodeRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Returns the child fields of `node` to walk, from {@link VISITOR_KEYS}, or `undefined` when there
+* is nothing to walk. `Schema` children are only walked when `recurse` is `true`.
+*/
+function childKeys(node, recurse) {
+	if (node.kind === "Schema" && !recurse) return void 0;
+	return visitorKeysByKind[node.kind];
+}
+/**
+* Returns the immediate traversable children of `node`.
 *
 * @example
 * ```ts
@@ -1066,8 +995,7 @@ function isNode(value) {
 * ```
 */
 function* getChildren(node, recurse) {
-	if (node.kind === "Schema" && !recurse) return;
-	const keys = visitorKeysByKind[node.kind];
+	const keys = childKeys(node, recurse);
 	if (!keys) return;
 	const record = node;
 	for (const key of keys) {
@@ -1076,7 +1004,13 @@ function* getChildren(node, recurse) {
 			for (const item of value) if (isNode(item)) yield item;
 			continue;
 		}
-		if (isNode(value)) yield value;
+		if (isNode(value)) {
+			yield value;
+			continue;
+		}
+		if (isNodeRecord(value)) {
+			for (const item of Object.values(value)) if (isNode(item)) yield item;
+		}
 	}
 }
 /**
@@ -1094,6 +1028,30 @@ function applyVisitor(node, visitor, parent) {
 	const fn = visitor[key];
 	return fn?.(node, { parent });
 }
+/**
+* Synchronous depth-first transform. Each visitor callback can return a
+* replacement node. Returning `undefined` keeps the original.
+*
+* The original tree is never mutated, a new tree is returned. Pass
+* `depth: 'shallow'` to skip recursion into children.
+*
+* @example Prefix every operationId
+* ```ts
+* const next = transform(root, {
+*   operation(node) {
+*     return { ...node, operationId: `prefixed_${node.operationId}` }
+*   },
+* })
+* ```
+*
+* @example Replace only the root node
+* ```ts
+* const next = transform(root, {
+*   depth: 'shallow',
+*   input: (node) => ({ ...node, meta: { ...node.meta, title: 'Rewritten' } }),
+* })
+* ```
+*/
 function transform(node, options) {
 	const { depth, parent, ...visitor } = options;
 	return transformNode(node, visitor, (depth ?? visitorDepths.deep) === visitorDepths.deep, parent);
@@ -1107,13 +1065,11 @@ function transformNode(node, visitor, recurse, parent) {
 	return transformChildren(applyVisitor(node, visitor, parent) ?? node, visitor, recurse);
 }
 /**
-* Immutably rebuilds a node's children using {@link VISITOR_KEYS}, transforming
-* each child node and leaving non-node values (e.g. `additionalProperties: true`) intact.
-* `Schema` children are skipped in shallow mode.
+* Immutably rebuilds a node's children, transforming each child node and leaving non-node values
+* (e.g. `additionalProperties: true`) intact.
 */
 function transformChildren(node, visitor, recurse) {
-	if (node.kind === "Schema" && !recurse) return node;
-	const keys = visitorKeysByKind[node.kind];
+	const keys = childKeys(node, recurse);
 	if (!keys) return node;
 	const record = node;
 	let updates;
@@ -1136,6 +1092,15 @@ function transformChildren(node, visitor, recurse) {
 		if (isNode(value)) {
 			const next = transformNode(value, visitor, recurse, node);
 			if (next !== value) (updates ??= {})[key] = next;
+			continue;
+		}
+		if (isNodeRecord(value)) {
+			let mapped;
+			for (const [name, item] of Object.entries(value)) {
+				const next = isNode(item) ? transformNode(item, visitor, recurse, node) : item;
+				if (next !== item) (mapped ??= { ...value })[name] = next;
+			}
+			if (mapped) (updates ??= {})[key] = mapped;
 		}
 	}
 	if (!updates) return node;
@@ -1329,21 +1294,18 @@ function createPrinter(build) {
 			...overrides
 		} : nodes;
 		const collectedImports = [];
+		const dispatch = (table) => (node) => {
+			const handler = table[node.type];
+			if (!handler) return null;
+			return handler.call(context, node);
+		};
 		const context = {
 			options: resolvedOptions,
 			import: (node) => {
 				collectedImports.push(node);
 			},
-			transform: (node) => {
-				const handler = merged[node.type];
-				if (!handler) return null;
-				return handler.call(context, node);
-			},
-			base: (node) => {
-				const handler = nodes[node.type];
-				if (!handler) return null;
-				return handler.call(context, node);
-			}
+			transform: dispatch(merged),
+			base: dispatch(nodes)
 		};
 		return {
 			name,
@@ -1376,6 +1338,29 @@ function resolveRefName(node) {
 	return node.name ?? node.schema?.name ?? null;
 }
 /**
+* Merges a ref node with its resolved schema, giving the fields set at the usage site precedence.
+*
+* Every field on the ref except `kind`, `type`, `name`, `ref`, and `schema` overrides the same field
+* of the resolved `schema` (for example `description`, `nullable`, `readOnly`, `deprecated`). Fields
+* left `undefined` on the ref do not shadow the resolved schema. A ref without a resolved `schema`
+* is returned as is.
+*
+* @example
+* ```ts
+* const ref = createSchema({ type: 'ref', ref: '#/components/schemas/Pet', description: 'A pet', schema: petSchema })
+* mergeRefWithSchema(ref) // petSchema's fields with description 'A pet'
+* ```
+*/
+function mergeRefWithSchema(node) {
+	if (!node.schema) return node;
+	const { kind: _kind, type: _type, name: _name, ref: _ref, schema: _schema, ...overrides } = node;
+	const definedOverrides = Object.fromEntries(Object.entries(overrides).filter(([, value]) => value !== void 0));
+	return {
+		...node.schema,
+		...definedOverrides
+	};
+}
+/**
 * Returns `true` when a schema is a bare ref without modifiers, metadata, or omit keys.
 *
 * Modifiers inherited from the resolved schema are included in the check because a ref emits the
@@ -1383,21 +1368,62 @@ function resolveRefName(node) {
 */
 function isBareRef(node, keysToOmit) {
 	if (!node || node.type !== "ref") return false;
-	const meta = (() => {
-		if (!node.schema) return node;
-		const { kind: _kind, type: _type, name: _name, ref: _ref, schema: _schema, ...overrides } = node;
-		const definedOverrides = Object.fromEntries(Object.entries(overrides).filter(([, value]) => value !== void 0));
-		return {
-			...node.schema,
-			...definedOverrides
-		};
-	})();
+	const meta = mergeRefWithSchema(node);
 	return !meta.nullable && !meta.optional && !meta.nullish && meta.default === void 0 && !meta.description && !meta.examples?.length && !keysToOmit?.length;
 }
 //#endregion
+//#region ../../internals/utils/src/promise.ts
+/**
+* Wraps `factory` with a keyed cache backed by the provided store.
+*
+* Pass a `WeakMap` for object keys (results are GC-eligible when the key is
+* collected) or a `Map` for primitive keys. For multi-argument functions,
+* nest two `memoize` calls — the outer keyed by the first argument, the
+* inner (created once per outer miss) keyed by the second.
+*
+* Because the cache is owned by the caller, it can be shared, inspected, or
+* cleared independently of the memoized function.
+*
+* @example Single WeakMap key
+* ```ts
+* const cache = new WeakMap<SchemaNode, Set<string>>()
+* const getRefs = memoize(cache, (node) => collectRefs(node))
+* ```
+*
+* @example Single Map key (primitive)
+* ```ts
+* const cache = new Map<string, Resolver>()
+* const getResolver = memoize(cache, (name) => buildResolver(name))
+* ```
+*
+* @example Two-level (object + primitive)
+* ```ts
+* const outer = new WeakMap<Params[], Map<string, Params[]>>()
+* const fn = memoize(outer, (params) => memoize(new Map(), (key) => transform(params, key)))
+* fn(params)('camelcase')
+* ```
+*/
+function memoize(store, factory) {
+	return (key) => {
+		if (store.has(key)) return store.get(key);
+		const value = factory(key);
+		store.set(key, value);
+		return value;
+	};
+}
+//#endregion
 //#region src/utils/schemaGraph.ts
 /**
-* Memoized inner pass that walks a single node and returns the names of every schema it references.
+* Collects the names of every schema a node's subtree references, resolved with `resolveRefName`.
+* Each ref contributes its name only, so the schema it points to is never traversed. The walk is
+* memoized by node identity, which lets `findCircularSchemas` and `containsCircularRef` share one
+* scan per schema.
+*
+* @example
+* ```ts
+* collectSchemaRefs(petSchema)
+* // Set { 'Category', 'Tag' }
+* ```
 */
 const collectSchemaRefs = memoize(/* @__PURE__ */ new WeakMap(), (node) => {
 	const refs = /* @__PURE__ */ new Set();
@@ -1410,31 +1436,6 @@ const collectSchemaRefs = memoize(/* @__PURE__ */ new WeakMap(), (node) => {
 	return refs;
 });
 /**
-* Collects the names of every ref found anywhere inside a node's own subtree.
-*
-* Each ref contributes its name only, so the schema it points to is never traversed here. Pass `out`
-* to accumulate names from several nodes into one set.
-*
-* @example Collect refs from a single schema
-* ```ts
-* const names = collectReferencedSchemaNames(petSchema)
-* // Set { 'Category', 'Tag' }
-* ```
-*
-* @example Accumulate refs from multiple schemas into one set
-* ```ts
-* const out = new Set<string>()
-* for (const schema of schemas) {
-*   collectReferencedSchemaNames(schema, out)
-* }
-* ```
-*/
-function collectReferencedSchemaNames(node, out = /* @__PURE__ */ new Set()) {
-	if (!node) return out;
-	for (const name of collectSchemaRefs(node)) out.add(name);
-	return out;
-}
-/**
 * Collects the de-duplicated target names of every pointer-carrying ref in a node's subtree, in
 * first-occurrence order. The walk is memoized by node identity, so the subtree is scanned once and
 * `resolver.imports` reads the same result across the ts, zod, and faker plugins instead of
@@ -1442,8 +1443,7 @@ function collectReferencedSchemaNames(node, out = /* @__PURE__ */ new Set()) {
 *
 * Only refs that carry a `$ref` pointer count, so a synthesized ref pointing at a sibling in the
 * same file (a union member created by name) is left out. That leaves exactly the set
-* `resolver.imports` emits. This is the ordered, import-facing counterpart to
-* {@link collectReferencedSchemaNames}, which returns an unordered set for graph analysis.
+* `resolver.imports` emits.
 *
 * @example
 * ```ts
@@ -1464,24 +1464,6 @@ const collectImportedRefNames = memoize(/* @__PURE__ */ new WeakMap(), (node) =>
 	} });
 	return names;
 });
-function computeUsedSchemaNames(operations, schemas) {
-	const schemaMap = /* @__PURE__ */ new Map();
-	for (const schema of schemas) if (schema.name) schemaMap.set(schema.name, schema);
-	const result = /* @__PURE__ */ new Set();
-	function visitSchema(schema) {
-		const directRefs = collectReferencedSchemaNames(schema);
-		for (const name of directRefs) if (!result.has(name)) {
-			result.add(name);
-			const namedSchema = schemaMap.get(name);
-			if (namedSchema) visitSchema(namedSchema);
-		}
-	}
-	for (const op of operations) for (const schema of collect(op, {
-		depth: "shallow",
-		schema: (node) => node
-	})) visitSchema(schema);
-	return result;
-}
 /**
 * Collects the names of all top-level schemas transitively used by a set of operations.
 *
@@ -1503,9 +1485,22 @@ function computeUsedSchemaNames(operations, schemas) {
 * ```
 */
 function collectUsedSchemaNames(operations, schemas) {
-	return computeUsedSchemaNames(operations, schemas);
+	const schemaMap = /* @__PURE__ */ new Map();
+	for (const schema of schemas) if (schema.name) schemaMap.set(schema.name, schema);
+	const result = /* @__PURE__ */ new Set();
+	function visitSchema(schema) {
+		for (const name of collectSchemaRefs(schema)) if (!result.has(name)) {
+			result.add(name);
+			const namedSchema = schemaMap.get(name);
+			if (namedSchema) visitSchema(namedSchema);
+		}
+	}
+	for (const op of operations) for (const schema of collect(op, {
+		depth: "shallow",
+		schema: (node) => node
+	})) visitSchema(schema);
+	return result;
 }
-const EMPTY_CIRCULAR_SET = /* @__PURE__ */ new Set();
 /**
 * Finds every schema that takes part in a circular dependency chain in a schema dependency graph
 * that maps each schema name to the names it references directly.
@@ -1542,14 +1537,6 @@ function findCircularSchemasFromGraph(graph) {
 	}
 	return circular;
 }
-const findCircularSchemasMemo = memoize(/* @__PURE__ */ new WeakMap(), (schemas) => {
-	const graph = /* @__PURE__ */ new Map();
-	for (const schema of schemas) {
-		if (!schema.name) continue;
-		graph.set(schema.name, collectReferencedSchemaNames(schema));
-	}
-	return findCircularSchemasFromGraph(graph);
-});
 /**
 * Finds every schema that takes part in a circular dependency chain, including direct self-loops.
 *
@@ -1560,8 +1547,9 @@ const findCircularSchemasMemo = memoize(/* @__PURE__ */ new WeakMap(), (schemas)
 * @note Call this once on the full graph, then check individual schemas with `containsCircularRef()`.
 */
 function findCircularSchemas(schemas) {
-	if (schemas.length === 0) return EMPTY_CIRCULAR_SET;
-	return findCircularSchemasMemo(schemas);
+	const graph = /* @__PURE__ */ new Map();
+	for (const schema of schemas) if (schema.name) graph.set(schema.name, collectSchemaRefs(schema));
+	return findCircularSchemasFromGraph(graph);
 }
 //#endregion
 //#region src/utils/schemaProperties.ts
@@ -1736,6 +1724,7 @@ var exports_exports = /* @__PURE__ */ __exportAll({
 	breakDef: () => breakDef,
 	collect: () => collect,
 	collectImportedRefNames: () => collectImportedRefNames,
+	collectSchemaRefs: () => collectSchemaRefs,
 	collectSync: () => collectSync,
 	collectUsedSchemaNames: () => collectUsedSchemaNames,
 	composeMacros: () => composeMacros,
@@ -1758,6 +1747,7 @@ var exports_exports = /* @__PURE__ */ __exportAll({
 	isBareRef: () => isBareRef,
 	isHttpOperationNode: () => isHttpOperationNode,
 	jsxDef: () => jsxDef,
+	mergeRefWithSchema: () => mergeRefWithSchema,
 	narrowSchema: () => narrowSchema,
 	nodeDefs: () => nodeDefs,
 	operationDef: () => operationDef,
@@ -1788,6 +1778,7 @@ Object.defineProperty(exports, "ast", {
 exports.breakDef = breakDef;
 exports.collect = collect;
 exports.collectImportedRefNames = collectImportedRefNames;
+exports.collectSchemaRefs = collectSchemaRefs;
 exports.collectSync = collectSync;
 exports.collectUsedSchemaNames = collectUsedSchemaNames;
 exports.composeMacros = composeMacros;
@@ -1815,6 +1806,7 @@ exports.inputDef = inputDef;
 exports.isBareRef = isBareRef;
 exports.isHttpOperationNode = isHttpOperationNode;
 exports.jsxDef = jsxDef;
+exports.mergeRefWithSchema = mergeRefWithSchema;
 exports.narrowSchema = narrowSchema;
 exports.nodeDefs = nodeDefs;
 exports.operationDef = operationDef;