@kubb/ast 5.13.1 → 5.14.0

package/dist/index.js

@@ -1,5 +1,5 @@
-import path from "node:path";
 import { hash } from "node:crypto";
+import path from "node:path";
 //#region \0rolldown/runtime.js
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
@@ -14,6 +14,30 @@ var __exportAll = (all, no_symbols) => {
 //#endregion
 //#region src/constants.ts
 /**
+* Node kind discriminators used by every AST node (for example `node.kind === nodeKinds.text`).
+*/
+const nodeKinds = {
+	input: "Input",
+	operation: "Operation",
+	schema: "Schema",
+	property: "Property",
+	parameter: "Parameter",
+	response: "Response",
+	requestBody: "RequestBody",
+	content: "Content",
+	type: "Type",
+	file: "File",
+	import: "Import",
+	export: "Export",
+	source: "Source",
+	const: "Const",
+	function: "Function",
+	arrowFunction: "ArrowFunction",
+	text: "Text",
+	break: "Break",
+	jsx: "Jsx"
+};
+/**
 * Schema type discriminators used by all AST schema nodes.
 *
 * Each value is a stable discriminator across the AST (for example `schema.type === schemaTypes.object`).
@@ -222,7 +246,7 @@ function isNodeRecord(value) {
 * ```
 */
 function getChildren(node, recurse) {
-	if (node.kind === "Schema" && !recurse) return [];
+	if (node.kind === nodeKinds.schema && !recurse) return [];
 	const children = [];
 	visitChildNodes(node, (child) => {
 		children.push(child);
@@ -280,7 +304,7 @@ function visitChildNodes(node, visit) {
 */
 function forEachSchema(node, visit) {
 	const walk = (current) => {
-		if (current.kind === "Schema") visit(current);
+		if (current.kind === nodeKinds.schema) visit(current);
 		forEachChild(current, walk);
 	};
 	walk(node);
@@ -298,7 +322,7 @@ function forEachSchema(node, visit) {
 function findSchema(node, { predicate, followRefs = false }) {
 	const seen = followRefs ? /* @__PURE__ */ new WeakSet() : void 0;
 	const walk = (current) => {
-		if (current.kind === "Schema") {
+		if (current.kind === nodeKinds.schema) {
 			if (predicate(current)) return current;
 			if (seen) {
 				if (seen.has(current)) return void 0;
@@ -374,7 +398,7 @@ function transformNode(node, visitor, recurse, parent) {
 * (e.g. `additionalProperties: true`) intact.
 */
 function transformChildren(node, visitor, recurse) {
-	const keys = node.kind === "Schema" && !recurse ? void 0 : VISITOR_KEYS[node.kind];
+	const keys = node.kind === nodeKinds.schema && !recurse ? void 0 : VISITOR_KEYS[node.kind];
 	if (!keys) return node;
 	const record = node;
 	let updates;
@@ -659,11 +683,11 @@ function extractStringsFromNodes(nodes) {
 			if (node) collected.push(node);
 			continue;
 		}
-		if (node.kind === "Text" || node.kind === "Jsx") {
+		if (node.kind === nodeKinds.text || node.kind === nodeKinds.jsx) {
 			if (node.value) collected.push(node.value);
 			continue;
 		}
-		if (node.kind === "Break") continue;
+		if (node.kind === nodeKinds.break) 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);
@@ -676,131 +700,539 @@ function extractStringsFromNodes(nodes) {
 	return collected.join("\n");
 }
 //#endregion
-//#region src/utils/refs.ts
-/** Returns the last segment of a `$ref` pointer, for example `'Pet'` for `#/components/schemas/Pet`. */
-function refName(ref) {
-	return ref.split("/").at(-1) ?? ref;
+//#region src/utils/combineFileMembers.ts
+const IDENTIFIER_RUN = /[\w$]+/g;
+/**
+* How many imports a file needs before indexing the source beats scanning it once per name.
+*/
+const INDEX_ABOVE_IMPORTS = 128;
+/**
+* Returns the local binding an import name item introduces: the alias when there is one, else the
+* imported name.
+*/
+function importLocalName(item) {
+	return typeof item === "string" ? item : item.name ?? item.propertyName;
 }
 /**
-* Resolves the emitted name of the schema a ref node points at. Prefers `targetName` (set when
-* the referenced schema was renamed, e.g. to break a collision), then the last segment of `ref`,
-* then `name`, then the nested `schema.name`.
-*
-* Returns `null` for non-ref nodes or when no name resolves.
-*
-* @example
-* `resolveRefName({ kind: 'Schema', type: 'ref', ref: '#/components/schemas/Pet' }) // 'Pet'`
-*
-* @example Collision-renamed target
-* `resolveRefName({ kind: 'Schema', type: 'ref', ref: '#/components/schemas/Order', targetName: 'OrderSchema' }) // 'OrderSchema'`
+* Computes a multi-level sort key for exports and imports:
+* non-array names first (wildcards/namespace aliases). Type-only before value. Alphabetical path. Unnamed before named.
 */
-function resolveRefName(node) {
-	if (!node || node.type !== "ref") return null;
-	if (node.targetName) return node.targetName;
-	if (node.ref) return refName(node.ref);
-	return node.name ?? node.schema?.name ?? null;
+function sortKey(node) {
+	const isArray = Array.isArray(node.name) ? "1" : "0";
+	const typeOnly = node.isTypeOnly ? "0" : "1";
+	const hasName = node.name != null ? "1" : "0";
+	const name = Array.isArray(node.name) ? node.name.toSorted().join("\0") : node.name ?? "";
+	return `${isArray}:${typeOnly}:${node.path}:${hasName}:${name}`;
 }
 /**
-* Follows a resolved ref chain to its target schema. Returns an unresolved or cyclic ref as is.
-*
-* @example
-* ```ts
-* const target = resolveRef(refSchema)
-* ```
+* Sorts members by {@link sortKey}. Keys are computed once per node, not per comparison.
 */
-function resolveRef(node) {
-	if (node.type !== "ref" || !node.schema) return node;
-	const seen = /* @__PURE__ */ new WeakSet();
-	let current = node;
-	while (current.type === "ref" && current.schema) {
-		if (seen.has(current)) return current;
-		seen.add(current);
-		current = current.schema;
-	}
-	return current;
+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);
 }
-/** Fields of a ref node that describe the ref itself, so they never override the resolved schema. */
-const REF_OWN_KEYS = /* @__PURE__ */ new Set([
-	"kind",
-	"type",
-	"name",
-	"ref",
-	"schema"
-]);
 /**
-* 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.
+* 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) {
+			for (const name of names) {
+				if (existing.seen.has(name)) continue;
+				existing.seen.add(name);
+				existing.names.push(name);
+			}
+			return;
+		}
+		const item = {
+			...node,
+			name: [...names]
+		};
+		result.push(item);
+		byPath.set(key, {
+			names: item.name,
+			seen: new Set(names)
+		});
+	};
+}
+/**
+* Deduplicates `SourceNode` objects by `name + isExportable + isTypeOnly`, keeping the first of each
+* key. An unnamed source only drops when the same node appears twice, so markdown can repeat a
+* paragraph or a table. Returns the deduplicated array in original order.
+*/
+function combineSources(sources) {
+	const seen = /* @__PURE__ */ new Set();
+	return sources.filter((source) => {
+		const key = source.name != null ? `${source.name}:${source.isExportable ?? false}:${source.isTypeOnly ?? false}` : source;
+		if (seen.has(key)) return false;
+		seen.add(key);
+		return true;
+	});
+}
+/**
+* Deduplicates and merges `ExportNode` objects by path and type.
 *
-* @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'
-* ```
+* Named exports with the same path and `isTypeOnly` flag have their names merged into a single export.
+* Non-array exports are deduplicated by exact identity. Returns a sorted, deduplicated array.
 */
-function mergeRefWithSchema(node) {
-	if (!node.schema) return node;
-	const merged = { ...node.schema };
-	for (const key of Object.keys(node)) {
-		const value = node[key];
-		if (value !== void 0 && !REF_OWN_KEYS.has(key)) merged[key] = value;
+function combineExports(exports) {
+	const result = [];
+	const merge = mergeByPath(result);
+	const seen = /* @__PURE__ */ new Set();
+	for (const curr of sortMembers(exports)) {
+		const { name, path, isTypeOnly, asAlias } = curr;
+		if (Array.isArray(name)) {
+			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 merged;
+	return result;
 }
 /**
-* Returns `true` when a schema is a bare ref without modifiers, metadata, or omit keys.
+* Deduplicates and merges `ImportNode` objects, filtering out unused imports.
 *
-* Modifiers inherited from the resolved schema are included in the check because a ref emits the
-* referenced schema variable with those modifiers already applied.
+* Retains imports that are referenced in `source` or re-exported. Imports with the same path and
+* `isTypeOnly` flag have their names merged. Returns a sorted, deduplicated, filtered array.
 */
-function isBareRef(node, keysToOmit) {
-	if (!node || node.type !== "ref") return false;
-	const meta = mergeRefWithSchema(node);
-	return !meta.nullable && !meta.optional && !meta.nullish && meta.default === void 0 && !meta.description && !meta.examples?.length && !keysToOmit?.length;
+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 ? 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) => {
+		if (typeof n === "string") return n;
+		const key = `${n.propertyName}:${n.name ?? ""}`;
+		if (!importNameMemo.has(key)) importNameMemo.set(key, n);
+		return importNameMemo.get(key);
+	};
+	const pathsWithUsedNamedImport = /* @__PURE__ */ new Set();
+	for (const node of imports) if (Array.isArray(node.name) && node.name.some((item) => isUsed(importLocalName(item)))) pathsWithUsedNamedImport.add(node.path);
+	const result = [];
+	const merge = mergeByPath(result);
+	const seen = /* @__PURE__ */ new Set();
+	for (const curr of sortMembers(imports)) {
+		if (curr.path === curr.root) continue;
+		const { name, path, isTypeOnly } = curr;
+		if (Array.isArray(name)) {
+			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;
 }
 //#endregion
-//#region ../../internals/utils/src/promise.ts
+//#region src/nodes/base.ts
+/** Builds a `createX` factory for a node whose only computed field is `kind`. */
+function nodeFactory(kind) {
+	return (input) => {
+		return {
+			...input,
+			kind
+		};
+	};
+}
+//#endregion
+//#region src/nodes/file.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.
+* Creates an `ImportNode` representing a language-agnostic import/dependency declaration.
 *
-* @example Single WeakMap key
+* @example Named import
 * ```ts
-* const cache = new WeakMap<SchemaNode, Set<string>>()
-* const getRefs = memoize(cache, (node) => collectRefs(node))
+* createImport({ name: ['useState'], path: 'react' })
+* // import { useState } from 'react'
 * ```
+*/
+const createImport = nodeFactory(nodeKinds.import);
+/**
+* Creates an `ExportNode` representing a language-agnostic export/public API declaration.
 *
-* @example Single Map key (primitive)
+* @example Named export
 * ```ts
-* const cache = new Map<string, Resolver>()
-* const getResolver = memoize(cache, (name) => buildResolver(name))
+* createExport({ name: ['Pet'], path: './Pet' })
+* // export { Pet } from './Pet'
 * ```
+*/
+const createExport = nodeFactory(nodeKinds.export);
+/**
+* Creates a `SourceNode` representing a fragment of source code within a file.
 *
-* @example Two-level (object + primitive)
+* @example
 * ```ts
-* const outer = new WeakMap<Params[], Map<string, Params[]>>()
-* const fn = memoize(outer, (params) => memoize(new Map(), (key) => transform(params, key)))
-* fn(params)('camelcase')
+* createSource({ name: 'Pet', nodes: [createText('export type Pet = { id: number }')], isExportable: true })
 * ```
 */
-function memoize(store, factory) {
-	return (key) => {
-		if (store.has(key)) return store.get(key);
-		const value = factory(key);
-		store.set(key, value);
-		return value;
-	};
-}
+const createSource = nodeFactory(nodeKinds.source);
+/**
+* Creates a fully resolved `FileNode` from a file input descriptor.
+*
+* Computes:
+* - `id` SHA256 hash of the file path
+* - `name` `baseName` without extension
+* - `extname` extension extracted from `baseName`
+*
+* Deduplicates:
+* - `sources` via `combineSources`
+* - `exports` via `combineExports`
+* - `imports` via `combineImports` (also filters unused imports)
+*
+* @throws {Error} when `baseName` has no extension.
+*
+* @example
+* ```ts
+* const file = createFile({
+*   baseName: 'petStore.ts',
+*   path: 'src/models/petStore.ts',
+*   sources: [createSource({ name: 'Pet', nodes: [createText('export type Pet = { id: number }')] })],
+*   imports: [createImport({ name: ['z'], path: 'zod' })],
+*   exports: [createExport({ name: ['Pet'], path: './petStore' })],
+* })
+* // file.id      = SHA256 hash of 'src/models/petStore.ts'
+* // file.name    = 'petStore'
+* // file.extname = '.ts'
+* ```
+*
+* @example Copy a real file into the output
+* ```ts
+* const file = createFile({
+*   baseName: 'client.ts',
+*   path: 'src/gen/client.ts',
+*   copy: '/abs/path/to/templates/client.ts',
+* })
+* ```
+*/
+function createFile(input) {
+	const extname = path.extname(input.baseName);
+	if (!extname) throw new Error(`No extname found for ${input.baseName}`);
+	const resolvedExports = input.exports?.length ? combineExports(input.exports) : [];
+	const resolvedSources = input.sources?.length ? combineSources(input.sources) : [];
+	const resolvedImports = (() => {
+		if (!input.imports?.length) return [];
+		const sourceParts = [];
+		const localNames = /* @__PURE__ */ new Set();
+		for (const item of resolvedSources) {
+			const extracted = item.nodes && extractStringsFromNodes(item.nodes);
+			if (extracted) sourceParts.push(extracted);
+			if (item.name) localNames.add(item.name);
+		}
+		const source = sourceParts.join("\n") || void 0;
+		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(importLocalName(item)));
+			if (!kept.length) return [];
+			return [kept.length === imp.name.length ? imp : {
+				...imp,
+				name: kept
+			}];
+		});
+	})();
+	return {
+		...input,
+		kind: nodeKinds.file,
+		id: hash("sha256", input.path, "hex"),
+		name: path.basename(input.baseName, extname),
+		extname,
+		imports: resolvedImports,
+		exports: resolvedExports,
+		sources: resolvedSources,
+		meta: input.meta ?? {}
+	};
+}
+//#endregion
+//#region src/utils/inline.ts
+/**
+* Whether every source of `file` is inline. Other files absorb such a file, so it is never written.
+*/
+function isVirtualFile(file) {
+	return file.sources.length > 0 && file.sources.every((source) => source.inline);
+}
+/**
+* Replaces every name a file imports from a virtual file (see {@link isVirtualFile}) with that name's
+* `inline.expression`, until no inline names are left. The definitions' own imports move to the importing file.
+*/
+function inlineFiles(files, { language }) {
+	const virtualFiles = new Map(files.filter(isVirtualFile).map((file) => [file.path, file]));
+	const result = {
+		files: [],
+		virtualPaths: [...virtualFiles.keys()],
+		problems: []
+	};
+	if (virtualFiles.size === 0) return result;
+	const definitions = /* @__PURE__ */ new Map();
+	function define(path, name, from, lang) {
+		const key = `${path}\0${name}`;
+		if (definitions.has(key)) {
+			const definition = definitions.get(key);
+			if (definition === null) result.problems.push({
+				path: from,
+				message: `"${name}" from "${path}" is defined in terms of itself.`
+			});
+			return definition ?? void 0;
+		}
+		const file = virtualFiles.get(path);
+		const inline = file.sources.find((source) => source.name === name)?.inline;
+		if (!inline) {
+			result.problems.push({
+				path: from,
+				message: `"${name}" is imported from "${path}", which never writes it and has no inline definition for it.`
+			});
+			return;
+		}
+		definitions.set(key, null);
+		const imports = [];
+		const { text, used } = replaceNames(inline.expression, file, lang, imports);
+		imports.push(...file.imports.flatMap((imp) => virtualFiles.has(imp.path) ? [] : pickNames(imp, used)));
+		const definition = {
+			expression: text,
+			imports
+		};
+		definitions.set(key, definition);
+		return definition;
+	}
+	function replaceNames(input, file, lang, imports) {
+		const used = /* @__PURE__ */ new Set();
+		return {
+			text: lang.replaceIdentifiers(input, (local) => {
+				const target = findTarget(file, local);
+				const definition = target && define(target.path, target.name, file.path, lang);
+				if (!definition) {
+					used.add(local);
+					return;
+				}
+				imports.push(...definition.imports);
+				return lang.wrap(definition.expression);
+			}),
+			used
+		};
+	}
+	function findTarget(file, local) {
+		if (virtualFiles.has(file.path) && file.sources.some((source) => source.name === local)) return {
+			path: file.path,
+			name: local
+		};
+		for (const imp of file.imports) {
+			const item = virtualFiles.has(imp.path) && [imp.name].flat().find((item) => importLocalName(item) === local);
+			if (item) return {
+				path: imp.path,
+				name: typeof item === "string" ? item : item.propertyName
+			};
+		}
+	}
+	for (const file of files) {
+		if (virtualFiles.has(file.path) || !file.imports.some((imp) => virtualFiles.has(imp.path))) continue;
+		const lang = language(file);
+		if (!lang) {
+			result.problems.push({
+				path: file.path,
+				message: `No parser for "${file.extname}" files supports inline sources.`
+			});
+			continue;
+		}
+		const carried = [];
+		const sources = file.sources.map((source) => ({
+			...source,
+			nodes: rewriteNodes(source.nodes, (text) => replaceNames(text, file, lang, carried).text)
+		}));
+		const imports = [...file.imports.filter((imp) => !virtualFiles.has(imp.path)), ...carried.map((imp) => imp.root ? {
+			...imp,
+			root: file.path
+		} : imp)];
+		result.files.push(createFile({
+			...file,
+			sources,
+			imports
+		}));
+	}
+	return result;
+}
+function pickNames(imp, used) {
+	if (!Array.isArray(imp.name)) return used.has(imp.name) ? [imp] : [];
+	const name = imp.name.filter((item) => used.has(importLocalName(item)));
+	return name.length > 0 ? [{
+		...imp,
+		name
+	}] : [];
+}
+function rewriteNodes(nodes, rewrite) {
+	return nodes?.map((node) => {
+		if (typeof node === "string") return rewrite(node);
+		switch (node.kind) {
+			case nodeKinds.break: return node;
+			case nodeKinds.text:
+			case nodeKinds.jsx: return {
+				...node,
+				value: rewrite(node.value)
+			};
+			case nodeKinds.function:
+			case nodeKinds.arrowFunction: return {
+				...node,
+				params: node.params && rewrite(node.params),
+				generics: Array.isArray(node.generics) ? node.generics.map(rewrite) : node.generics && rewrite(node.generics),
+				returnType: node.returnType && rewrite(node.returnType),
+				nodes: rewriteNodes(node.nodes, rewrite)
+			};
+			case nodeKinds.const: return {
+				...node,
+				type: node.type && rewrite(node.type),
+				nodes: rewriteNodes(node.nodes, rewrite)
+			};
+			default: return {
+				...node,
+				nodes: rewriteNodes(node.nodes, rewrite)
+			};
+		}
+	});
+}
+//#endregion
+//#region src/utils/refs.ts
+/** Returns the last segment of a `$ref` pointer, for example `'Pet'` for `#/components/schemas/Pet`. */
+function refName(ref) {
+	return ref.split("/").at(-1) ?? ref;
+}
+/**
+* Resolves the emitted name of the schema a ref node points at. Prefers `targetName` (set when
+* the referenced schema was renamed, e.g. to break a collision), then the last segment of `ref`,
+* then `name`, then the nested `schema.name`.
+*
+* Returns `null` for non-ref nodes or when no name resolves.
+*
+* @example
+* `resolveRefName({ kind: 'Schema', type: 'ref', ref: '#/components/schemas/Pet' }) // 'Pet'`
+*
+* @example Collision-renamed target
+* `resolveRefName({ kind: 'Schema', type: 'ref', ref: '#/components/schemas/Order', targetName: 'OrderSchema' }) // 'OrderSchema'`
+*/
+function resolveRefName(node) {
+	if (!node || node.type !== "ref") return null;
+	if (node.targetName) return node.targetName;
+	if (node.ref) return refName(node.ref);
+	return node.name ?? node.schema?.name ?? null;
+}
+/**
+* Follows a resolved ref chain to its target schema. Returns an unresolved or cyclic ref as is.
+*
+* @example
+* ```ts
+* const target = resolveRef(refSchema)
+* ```
+*/
+function resolveRef(node) {
+	if (node.type !== "ref" || !node.schema) return node;
+	const seen = /* @__PURE__ */ new WeakSet();
+	let current = node;
+	while (current.type === "ref" && current.schema) {
+		if (seen.has(current)) return current;
+		seen.add(current);
+		current = current.schema;
+	}
+	return current;
+}
+/** Fields of a ref node that describe the ref itself, so they never override the resolved schema. */
+const REF_OWN_KEYS = /* @__PURE__ */ new Set([
+	"kind",
+	"type",
+	"name",
+	"ref",
+	"schema"
+]);
+/**
+* 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 merged = { ...node.schema };
+	for (const key of Object.keys(node)) {
+		const value = node[key];
+		if (value !== void 0 && !REF_OWN_KEYS.has(key)) merged[key] = value;
+	}
+	return merged;
+}
+/**
+* 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
+* referenced schema variable with those modifiers already applied.
+*/
+function isBareRef(node, keysToOmit) {
+	if (!node || node.type !== "ref") return false;
+	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
 /**
@@ -1059,17 +1491,6 @@ function inferDiscriminatorPropertyName(members) {
 	}
 }
 //#endregion
-//#region src/nodes/base.ts
-/** Builds a `createX` factory for a node whose only computed field is `kind`. */
-function nodeFactory(kind) {
-	return (input) => {
-		return {
-			...input,
-			kind
-		};
-	};
-}
-//#endregion
 //#region src/nodes/code.ts
 /**
 * Creates a `ConstNode` representing a TypeScript `const` declaration.
@@ -1080,7 +1501,7 @@ function nodeFactory(kind) {
 * // export const pets: Pet[] = ... as const
 * ```
 */
-const createConst = nodeFactory("Const");
+const createConst = nodeFactory(nodeKinds.const);
 /**
 * Creates a `TypeNode` representing a TypeScript `type` alias declaration.
 *
@@ -1090,7 +1511,7 @@ const createConst = nodeFactory("Const");
 * // export type Pet = ...
 * ```
 */
-const createType = nodeFactory("Type");
+const createType = nodeFactory(nodeKinds.type);
 /**
 * Creates a `FunctionNode` representing a TypeScript `function` declaration.
 *
@@ -1100,7 +1521,7 @@ const createType = nodeFactory("Type");
 * // export async function fetchPet(): Promise<Pet> { ... }
 * ```
 */
-const createFunction = nodeFactory("Function");
+const createFunction = nodeFactory(nodeKinds.function);
 /**
 * Creates an `ArrowFunctionNode` representing a TypeScript arrow function.
 *
@@ -1110,7 +1531,7 @@ const createFunction = nodeFactory("Function");
 * // export const double = (n: number) => ...
 * ```
 */
-const createArrowFunction = nodeFactory("ArrowFunction");
+const createArrowFunction = nodeFactory(nodeKinds.arrowFunction);
 /**
 * Creates a {@link TextNode} representing a raw string fragment in the source output.
 *
@@ -1122,7 +1543,7 @@ const createArrowFunction = nodeFactory("ArrowFunction");
 */
 function createText(value) {
 	return {
-		kind: "Text",
+		kind: nodeKinds.text,
 		value
 	};
 }
@@ -1136,7 +1557,7 @@ function createText(value) {
 * ```
 */
 function createBreak() {
-	return { kind: "Break" };
+	return { kind: nodeKinds.break };
 }
 /**
 * Creates a {@link JsxNode} representing a raw JSX fragment in the source output.
@@ -1149,7 +1570,7 @@ function createBreak() {
 */
 function createJsx(value) {
 	return {
-		kind: "Jsx",
+		kind: nodeKinds.jsx,
 		value
 	};
 }
@@ -1158,259 +1579,7 @@ function createJsx(value) {
 /**
 * Creates a `ContentNode` for a single request-body or response content type.
 */
-const createContent = nodeFactory("Content");
-//#endregion
-//#region src/utils/combineFileMembers.ts
-const IDENTIFIER_RUN = /[\w$]+/g;
-/**
-* How many imports a file needs before indexing the source beats scanning it once per name.
-*/
-const INDEX_ABOVE_IMPORTS = 128;
-/**
-* Returns the local binding an import name item introduces: the alias when there is one, else the
-* imported name.
-*/
-function importLocalName(item) {
-	return typeof item === "string" ? item : item.name ?? item.propertyName;
-}
-/**
-* Computes a multi-level sort key for exports and imports:
-* non-array names first (wildcards/namespace aliases). Type-only before value. Alphabetical path. Unnamed before named.
-*/
-function sortKey(node) {
-	const isArray = Array.isArray(node.name) ? "1" : "0";
-	const typeOnly = node.isTypeOnly ? "0" : "1";
-	const hasName = node.name != null ? "1" : "0";
-	const name = Array.isArray(node.name) ? node.name.toSorted().join("\0") : node.name ?? "";
-	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) {
-			for (const name of names) {
-				if (existing.seen.has(name)) continue;
-				existing.seen.add(name);
-				existing.names.push(name);
-			}
-			return;
-		}
-		const item = {
-			...node,
-			name: [...names]
-		};
-		result.push(item);
-		byPath.set(key, {
-			names: item.name,
-			seen: new Set(names)
-		});
-	};
-}
-/**
-* Deduplicates `SourceNode` objects by `name + isExportable + isTypeOnly`, keeping the first of each
-* key. An unnamed source only drops when the same node appears twice, so markdown can repeat a
-* paragraph or a table. Returns the deduplicated array in original order.
-*/
-function combineSources(sources) {
-	const seen = /* @__PURE__ */ new Set();
-	return sources.filter((source) => {
-		const key = source.name != null ? `${source.name}:${source.isExportable ?? false}:${source.isTypeOnly ?? false}` : source;
-		if (seen.has(key)) return false;
-		seen.add(key);
-		return true;
-	});
-}
-/**
-* 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.
-* Non-array exports are deduplicated by exact identity. Returns a sorted, deduplicated array.
-*/
-function combineExports(exports) {
-	const result = [];
-	const merge = mergeByPath(result);
-	const seen = /* @__PURE__ */ new Set();
-	for (const curr of sortMembers(exports)) {
-		const { name, path, isTypeOnly, asAlias } = curr;
-		if (Array.isArray(name)) {
-			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;
-}
-/**
-* Deduplicates and merges `ImportNode` objects, filtering out unused imports.
-*
-* Retains imports that are referenced in `source` or re-exported. Imports with the same path and
-* `isTypeOnly` flag have their names merged. Returns a sorted, deduplicated, filtered array.
-*/
-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 ? 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) => {
-		if (typeof n === "string") return n;
-		const key = `${n.propertyName}:${n.name ?? ""}`;
-		if (!importNameMemo.has(key)) importNameMemo.set(key, n);
-		return importNameMemo.get(key);
-	};
-	const pathsWithUsedNamedImport = /* @__PURE__ */ new Set();
-	for (const node of imports) if (Array.isArray(node.name) && node.name.some((item) => isUsed(importLocalName(item)))) pathsWithUsedNamedImport.add(node.path);
-	const result = [];
-	const merge = mergeByPath(result);
-	const seen = /* @__PURE__ */ new Set();
-	for (const curr of sortMembers(imports)) {
-		if (curr.path === curr.root) continue;
-		const { name, path, isTypeOnly } = curr;
-		if (Array.isArray(name)) {
-			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;
-}
-//#endregion
-//#region src/nodes/file.ts
-/**
-* Creates an `ImportNode` representing a language-agnostic import/dependency declaration.
-*
-* @example Named import
-* ```ts
-* createImport({ name: ['useState'], path: 'react' })
-* // import { useState } from 'react'
-* ```
-*/
-const createImport = nodeFactory("Import");
-/**
-* Creates an `ExportNode` representing a language-agnostic export/public API declaration.
-*
-* @example Named export
-* ```ts
-* createExport({ name: ['Pet'], path: './Pet' })
-* // export { Pet } from './Pet'
-* ```
-*/
-const createExport = nodeFactory("Export");
-/**
-* Creates a `SourceNode` representing a fragment of source code within a file.
-*
-* @example
-* ```ts
-* createSource({ name: 'Pet', nodes: [createText('export type Pet = { id: number }')], isExportable: true })
-* ```
-*/
-const createSource = nodeFactory("Source");
-/**
-* Creates a fully resolved `FileNode` from a file input descriptor.
-*
-* Computes:
-* - `id` SHA256 hash of the file path
-* - `name` `baseName` without extension
-* - `extname` extension extracted from `baseName`
-*
-* Deduplicates:
-* - `sources` via `combineSources`
-* - `exports` via `combineExports`
-* - `imports` via `combineImports` (also filters unused imports)
-*
-* @throws {Error} when `baseName` has no extension.
-*
-* @example
-* ```ts
-* const file = createFile({
-*   baseName: 'petStore.ts',
-*   path: 'src/models/petStore.ts',
-*   sources: [createSource({ name: 'Pet', nodes: [createText('export type Pet = { id: number }')] })],
-*   imports: [createImport({ name: ['z'], path: 'zod' })],
-*   exports: [createExport({ name: ['Pet'], path: './petStore' })],
-* })
-* // file.id      = SHA256 hash of 'src/models/petStore.ts'
-* // file.name    = 'petStore'
-* // file.extname = '.ts'
-* ```
-*
-* @example Copy a real file into the output
-* ```ts
-* const file = createFile({
-*   baseName: 'client.ts',
-*   path: 'src/gen/client.ts',
-*   copy: '/abs/path/to/templates/client.ts',
-* })
-* ```
-*/
-function createFile(input) {
-	const extname = path.extname(input.baseName);
-	if (!extname) throw new Error(`No extname found for ${input.baseName}`);
-	const resolvedExports = input.exports?.length ? combineExports(input.exports) : [];
-	const resolvedSources = input.sources?.length ? combineSources(input.sources) : [];
-	const resolvedImports = (() => {
-		if (!input.imports?.length) return [];
-		const sourceParts = [];
-		const localNames = /* @__PURE__ */ new Set();
-		for (const item of resolvedSources) {
-			const extracted = item.nodes && extractStringsFromNodes(item.nodes);
-			if (extracted) sourceParts.push(extracted);
-			if (item.name) localNames.add(item.name);
-		}
-		const source = sourceParts.join("\n") || void 0;
-		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(importLocalName(item)));
-			if (!kept.length) return [];
-			return [kept.length === imp.name.length ? imp : {
-				...imp,
-				name: kept
-			}];
-		});
-	})();
-	return {
-		...input,
-		kind: "File",
-		id: hash("sha256", input.path, "hex"),
-		name: path.basename(input.baseName, extname),
-		extname,
-		imports: resolvedImports,
-		exports: resolvedExports,
-		sources: resolvedSources,
-		meta: input.meta ?? {}
-	};
-}
+const createContent = nodeFactory(nodeKinds.content);
 //#endregion
 //#region src/nodes/input.ts
 /**
@@ -1432,7 +1601,7 @@ function createInput(overrides = {}) {
 			enumNames: []
 		},
 		...overrides,
-		kind: "Input"
+		kind: nodeKinds.input
 	};
 }
 //#endregion
@@ -1440,7 +1609,7 @@ function createInput(overrides = {}) {
 /**
 * Creates a `RequestBodyNode`.
 */
-const createRequestBody = nodeFactory("RequestBody");
+const createRequestBody = nodeFactory(nodeKinds.requestBody);
 //#endregion
 //#region src/nodes/operation.ts
 function createOperation(props) {
@@ -1451,7 +1620,7 @@ function createOperation(props) {
 		parameters: [],
 		responses: [],
 		...rest,
-		kind: "Operation",
+		kind: nodeKinds.operation,
 		...isHttp ? { protocol: "http" } : {},
 		requestBody: requestBody ? createRequestBody(requestBody) : void 0
 	};
@@ -1478,7 +1647,7 @@ function createParameter(input) {
 		...input,
 		required,
 		schema: optionality(input.schema, required),
-		kind: "Parameter"
+		kind: nodeKinds.parameter
 	};
 }
 //#endregion
@@ -1503,7 +1672,7 @@ function createProperty(input) {
 		...input,
 		required,
 		schema: optionality(input.schema, required),
-		kind: "Property"
+		kind: nodeKinds.property
 	};
 }
 //#endregion
@@ -1530,7 +1699,7 @@ function createResponse(props) {
 	return {
 		...rest,
 		content: entries,
-		kind: "Response"
+		kind: nodeKinds.response
 	};
 }
 //#endregion
@@ -1565,12 +1734,12 @@ function createSchema(props) {
 		properties: [],
 		primitive: "object",
 		...props,
-		kind: "Schema"
+		kind: nodeKinds.schema
 	};
 	return {
 		primitive: TYPE_TO_PRIMITIVE[props.type],
 		...props,
-		kind: "Schema"
+		kind: nodeKinds.schema
 	};
 }
 //#endregion
@@ -1618,10 +1787,13 @@ var src_exports = /* @__PURE__ */ __exportAll({
 	forEachSchema: () => forEachSchema,
 	getSchemaLiteralValues: () => getSchemaLiteralValues,
 	inferDiscriminatorPropertyName: () => inferDiscriminatorPropertyName,
+	inlineFiles: () => inlineFiles,
 	isBareRef: () => isBareRef,
 	isHttpOperationNode: () => isHttpOperationNode,
+	isVirtualFile: () => isVirtualFile,
 	mergeRefWithSchema: () => mergeRefWithSchema,
 	narrowSchema: () => narrowSchema,
+	nodeKinds: () => nodeKinds,
 	optionality: () => optionality,
 	refName: () => refName,
 	resolveRef: () => resolveRef,
@@ -1631,6 +1803,6 @@ var src_exports = /* @__PURE__ */ __exportAll({
 	transform: () => transform
 });
 //#endregion
-export { applyMacros, src_exports as ast, collect, collectImportedRefNames, collectSchemaRefs, collectSync, collectUsedSchemaNames, composeMacros, createPrinter, defineMacro, extractStringsFromNodes, nodes_exports as factory, findCircularSchemas, findCircularSchemasFromGraph, findSchema, forEachChild, forEachSchema, getSchemaLiteralValues, inferDiscriminatorPropertyName, isBareRef, isHttpOperationNode, mergeRefWithSchema, narrowSchema, optionality, refName, resolveRef, resolveRefName, resolveSchemaProperties, schemaTypes, transform };
+export { applyMacros, src_exports as ast, collect, collectImportedRefNames, collectSchemaRefs, collectSync, collectUsedSchemaNames, composeMacros, createPrinter, defineMacro, extractStringsFromNodes, nodes_exports as factory, findCircularSchemas, findCircularSchemasFromGraph, findSchema, forEachChild, forEachSchema, getSchemaLiteralValues, inferDiscriminatorPropertyName, inlineFiles, isBareRef, isHttpOperationNode, isVirtualFile, mergeRefWithSchema, narrowSchema, nodeKinds, optionality, refName, resolveRef, resolveRefName, resolveSchemaProperties, schemaTypes, transform };
 
 //# sourceMappingURL=index.js.map