@kubb/ast 5.5.6 → 5.6.1

package/dist/index.js

@@ -331,63 +331,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.
@@ -403,15 +346,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);
@@ -431,22 +370,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:
@@ -460,6 +388,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.
@@ -467,22 +425,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.
@@ -490,34 +438,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;
@@ -530,7 +465,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) => {
@@ -540,43 +475,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;
@@ -681,12 +599,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,
@@ -699,7 +615,7 @@ function createFile(input) {
 		kind: "File",
 		...input,
 		id: hash("sha256", input.path, "hex"),
-		name: trimExtName(input.baseName),
+		name: path.basename(input.baseName, extname),
 		extname,
 		imports: resolvedImports,
 		exports: resolvedExports,
@@ -714,14 +630,15 @@ function createFile(input) {
 */
 const inputDef = defineNode({
 	kind: "Input",
-	defaults: {
+	build: (props) => ({
 		schemas: [],
 		operations: [],
 		meta: {
 			circularNames: [],
 			enumNames: []
-		}
-	},
+		},
+		...props
+	}),
 	children: ["schemas", "operations"],
 	visitorKey: "input"
 });
@@ -819,22 +736,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"
 });
@@ -856,18 +778,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"
 });
@@ -968,7 +883,9 @@ const schemaDef = defineNode({
 		"properties",
 		"items",
 		"members",
-		"additionalProperties"
+		"additionalProperties",
+		"patternProperties",
+		"rest"
 	],
 	visitorKey: "schema"
 });
@@ -1023,9 +940,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
@@ -1034,8 +963,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) {
@@ -1044,7 +972,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;
+		}
 	}
 }
 /**
@@ -1062,6 +996,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);
@@ -1075,13 +1033,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;
@@ -1104,6 +1060,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;
@@ -1297,21 +1262,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,
@@ -1344,6 +1306,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
@@ -1351,21 +1336,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();
@@ -1378,31 +1404,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
@@ -1410,8 +1411,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
@@ -1432,24 +1432,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.
 *
@@ -1471,9 +1453,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.
@@ -1510,14 +1505,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.
 *
@@ -1528,8 +1515,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
@@ -1704,6 +1692,7 @@ var exports_exports = /* @__PURE__ */ __exportAll({
 	breakDef: () => breakDef,
 	collect: () => collect,
 	collectImportedRefNames: () => collectImportedRefNames,
+	collectSchemaRefs: () => collectSchemaRefs,
 	collectSync: () => collectSync,
 	collectUsedSchemaNames: () => collectUsedSchemaNames,
 	composeMacros: () => composeMacros,
@@ -1726,6 +1715,7 @@ var exports_exports = /* @__PURE__ */ __exportAll({
 	isBareRef: () => isBareRef,
 	isHttpOperationNode: () => isHttpOperationNode,
 	jsxDef: () => jsxDef,
+	mergeRefWithSchema: () => mergeRefWithSchema,
 	narrowSchema: () => narrowSchema,
 	nodeDefs: () => nodeDefs,
 	operationDef: () => operationDef,
@@ -1745,6 +1735,6 @@ var exports_exports = /* @__PURE__ */ __exportAll({
 	typeDef: () => typeDef
 });
 //#endregion
-export { applyMacros, arrowFunctionDef, exports_exports as ast, breakDef, collect, collectImportedRefNames, collectSync, collectUsedSchemaNames, composeMacros, constDef, contentDef, createPrinter, defineMacro, defineNode, exportDef, extractStringsFromNodes, factory_exports as factory, fileDef, findCircularSchemas, findCircularSchemasFromGraph, functionDef, getSchemaLiteralValues, importDef, inferDiscriminatorPropertyName, inputDef, isBareRef, isHttpOperationNode, jsxDef, narrowSchema, nodeDefs, operationDef, optionality, outputDef, parameterDef, propertyDef, requestBodyDef, resolveRefName, resolveSchemaProperties, responseDef, schemaDef, schemaTypes, sourceDef, textDef, transform, typeDef };
+export { applyMacros, arrowFunctionDef, exports_exports as ast, breakDef, collect, collectImportedRefNames, collectSchemaRefs, collectSync, collectUsedSchemaNames, composeMacros, constDef, contentDef, createPrinter, defineMacro, defineNode, exportDef, extractStringsFromNodes, factory_exports as factory, fileDef, findCircularSchemas, findCircularSchemasFromGraph, functionDef, getSchemaLiteralValues, importDef, inferDiscriminatorPropertyName, inputDef, isBareRef, isHttpOperationNode, jsxDef, mergeRefWithSchema, narrowSchema, nodeDefs, operationDef, optionality, outputDef, parameterDef, propertyDef, requestBodyDef, resolveRefName, resolveSchemaProperties, responseDef, schemaDef, schemaTypes, sourceDef, textDef, transform, typeDef };
 
 //# sourceMappingURL=index.js.map