@kubb/ast 5.0.0-beta.65 → 5.0.0-beta.67

package/dist/{schema-BkvrrOAr.cjs → refs-DDIY_Tpn.cjs}

@@ -36,6 +36,154 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 let node_crypto = require("node:crypto");
 let node_path = require("node:path");
 node_path = __toESM(node_path, 1);
+//#region src/constants.ts
+const visitorDepths = {
+	shallow: "shallow",
+	deep: "deep"
+};
+/**
+* Schema type discriminators used by all AST schema nodes.
+*
+* Each value is a stable discriminator across the AST (for example `schema.type === schemaTypes.object`).
+*/
+const schemaTypes = {
+	/**
+	* Text value.
+	*/
+	string: "string",
+	/**
+	* Floating-point number (`float`, `double`).
+	*/
+	number: "number",
+	/**
+	* Whole number (`int32`). Use `bigint` for `int64`.
+	*/
+	integer: "integer",
+	/**
+	* 64-bit integer (`int64`). Only used when `integerType` is set to `'bigint'`.
+	*/
+	bigint: "bigint",
+	/**
+	* Boolean value.
+	*/
+	boolean: "boolean",
+	/**
+	* Explicit null value.
+	*/
+	null: "null",
+	/**
+	* Any value (no type restriction).
+	*/
+	any: "any",
+	/**
+	* Unknown value (must be narrowed before usage).
+	*/
+	unknown: "unknown",
+	/**
+	* No return value (`void`).
+	*/
+	void: "void",
+	/**
+	* Object with named properties.
+	*/
+	object: "object",
+	/**
+	* Sequential list of items.
+	*/
+	array: "array",
+	/**
+	* Fixed-length list with position-specific items.
+	*/
+	tuple: "tuple",
+	/**
+	* "One of" multiple schema members.
+	*/
+	union: "union",
+	/**
+	* "All of" multiple schema members.
+	*/
+	intersection: "intersection",
+	/**
+	* Enum schema.
+	*/
+	enum: "enum",
+	/**
+	* Reference to another schema.
+	*/
+	ref: "ref",
+	/**
+	* Calendar date (for example `2026-03-24`).
+	*/
+	date: "date",
+	/**
+	* Date-time value (for example `2026-03-24T09:00:00Z`).
+	*/
+	datetime: "datetime",
+	/**
+	* Time-only value (for example `09:00:00`).
+	*/
+	time: "time",
+	/**
+	* UUID value.
+	*/
+	uuid: "uuid",
+	/**
+	* Email address value.
+	*/
+	email: "email",
+	/**
+	* URL value.
+	*/
+	url: "url",
+	/**
+	* IPv4 address value.
+	*/
+	ipv4: "ipv4",
+	/**
+	* IPv6 address value.
+	*/
+	ipv6: "ipv6",
+	/**
+	* Binary/blob value.
+	*/
+	blob: "blob",
+	/**
+	* Impossible value (`never`).
+	*/
+	never: "never"
+};
+/**
+* One indentation level, derived from {@link INDENT_SIZE}.
+*/
+const INDENT = Array.from({ length: 2 }, () => " ").join("");
+//#endregion
+//#region src/guards.ts
+/**
+* Narrows a `SchemaNode` to the variant that matches `type`.
+*
+* @example
+* ```ts
+* const schema = createSchema({ type: 'string' })
+* const stringNode = narrowSchema(schema, 'string') // StringSchemaNode | null
+* ```
+*/
+function narrowSchema(node, type) {
+	return node?.type === type ? node : null;
+}
+/**
+* Narrows an `OperationNode` to an `HttpOperationNode` so `method` and `path` are present.
+*
+* @example
+* ```ts
+* if (isHttpOperationNode(node)) {
+*   console.log(node.method, node.path)
+* }
+* ```
+*/
+function isHttpOperationNode(node) {
+	return node.protocol === "http" || node.method !== void 0 && node.path !== void 0;
+}
+//#endregion
 //#region src/defineNode.ts
 /**
 * Visitor callback names, one per traversable node kind, in traversal order.
@@ -940,6 +1088,364 @@ function createSchema(props) {
 	return schemaDef.create(props);
 }
 //#endregion
+//#region src/registry.ts
+/**
+* Every node definition. Adding a node means adding its `defineNode` to one
+* `nodes/*.ts` file and listing it here. The visitor tables in `visitor.ts` derive from it.
+*/
+const nodeDefs = [
+	inputDef,
+	outputDef,
+	operationDef,
+	requestBodyDef,
+	contentDef,
+	responseDef,
+	schemaDef,
+	propertyDef,
+	parameterDef,
+	functionParameterDef,
+	functionParametersDef,
+	typeLiteralDef,
+	indexedAccessTypeDef,
+	objectBindingPatternDef,
+	constDef,
+	typeDef,
+	functionDef,
+	arrowFunctionDef,
+	textDef,
+	breakDef,
+	jsxDef,
+	importDef,
+	exportDef,
+	sourceDef,
+	fileDef
+];
+//#endregion
+//#region src/visitor.ts
+/**
+* Child node fields per node kind, in traversal order (Babel's `VISITOR_KEYS`).
+* Derived from each definition's `children`.
+*/
+const VISITOR_KEYS = Object.fromEntries(nodeDefs.flatMap((def) => def.children ? [[def.kind, def.children]] : []));
+/**
+* Maps a node kind to the matching visitor callback name. Derived from each
+* definition's `visitorKey`.
+*/
+const VISITOR_KEY_BY_KIND = Object.fromEntries(nodeDefs.flatMap((def) => def.visitorKey ? [[def.kind, def.visitorKey]] : []));
+/**
+* Creates a small async concurrency limiter.
+*
+* At most `concurrency` tasks are in flight at once. Extra tasks are queued.
+*
+* @example
+* ```ts
+* const limit = createLimit(2)
+* for (const task of [taskA, taskB, taskC]) {
+*   await limit(() => task())
+* }
+* // only 2 tasks run at the same time
+* ```
+*/
+function createLimit(concurrency) {
+	let active = 0;
+	const queue = [];
+	function next() {
+		if (active < concurrency && queue.length > 0) {
+			active++;
+			queue.shift()();
+		}
+	}
+	return function limit(fn) {
+		return new Promise((resolve, reject) => {
+			queue.push(() => {
+				Promise.resolve(fn()).then(resolve, reject).finally(() => {
+					active--;
+					next();
+				});
+			});
+			next();
+		});
+	};
+}
+const visitorKeysByKind = VISITOR_KEYS;
+/**
+* Returns `true` when `value` is an AST node (an object carrying a `kind`).
+*/
+function isNode(value) {
+	return typeof value === "object" && value !== null && "kind" in value;
+}
+/**
+* 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.
+*
+* @example
+* ```ts
+* const children = getChildren(operationNode, true)
+* // returns parameters, the request body, and responses
+* ```
+*/
+function* getChildren(node, recurse) {
+	if (node.kind === "Schema" && !recurse) return;
+	const keys = visitorKeysByKind[node.kind];
+	if (!keys) return;
+	const record = node;
+	for (const key of keys) {
+		const value = record[key];
+		if (Array.isArray(value)) {
+			for (const item of value) if (isNode(item)) yield item;
+		} else if (isNode(value)) yield value;
+	}
+}
+/**
+* Runs the visitor callback that matches `node.kind` with the traversal
+* context. The result is a replacement node, a collected value, or `undefined`
+* when no callback is registered for the kind.
+*
+* Shared by `walk`, `transform`, and `collectLazy` so node-kind dispatch lives
+* in one place. `TResult` is the caller's expected return: the same node type
+* for `transform`, the collected value type for `collectLazy`, ignored for `walk`.
+*/
+function applyVisitor(node, visitor, parent) {
+	const key = VISITOR_KEY_BY_KIND[node.kind];
+	if (!key) return void 0;
+	const fn = visitor[key];
+	return fn?.(node, { parent });
+}
+/**
+* Async depth-first traversal for side effects. Visitor return values are
+* ignored. Use `transform` when you want to rewrite nodes.
+*
+* Sibling nodes at each depth run concurrently up to `options.concurrency`
+* (defaults to `WALK_CONCURRENCY`). Higher values overlap I/O-bound visitor
+* work. Lower values reduce memory pressure.
+*
+* @example Log every operation
+* ```ts
+* await walk(root, {
+*   operation(node) {
+*     console.log(node.operationId)
+*   },
+* })
+* ```
+*
+* @example Only visit the root node
+* ```ts
+* await walk(root, { depth: 'shallow', input: () => {} })
+* ```
+*/
+async function walk(node, options) {
+	return _walk(node, options, (options.depth ?? visitorDepths.deep) === visitorDepths.deep, createLimit(options.concurrency ?? 30), void 0);
+}
+async function _walk(node, visitor, recurse, limit, parent) {
+	await limit(() => applyVisitor(node, visitor, parent));
+	const children = Array.from(getChildren(node, recurse));
+	if (children.length === 0) return;
+	await Promise.all(children.map((child) => _walk(child, visitor, recurse, limit, node)));
+}
+function transform(node, options) {
+	const { depth, parent, ...visitor } = options;
+	const recurse = (depth ?? visitorDepths.deep) === visitorDepths.deep;
+	return transformChildren(applyVisitor(node, visitor, parent) ?? node, options, 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.
+*/
+function transformChildren(node, options, recurse) {
+	if (node.kind === "Schema" && !recurse) return node;
+	const keys = visitorKeysByKind[node.kind];
+	if (!keys) return node;
+	const record = node;
+	const childOptions = {
+		...options,
+		parent: node
+	};
+	let updates;
+	for (const key of keys) {
+		if (!(key in record)) continue;
+		const value = record[key];
+		if (Array.isArray(value)) {
+			let changed = false;
+			const mapped = value.map((item) => {
+				if (!isNode(item)) return item;
+				const next = transform(item, childOptions);
+				if (next !== item) changed = true;
+				return next;
+			});
+			if (changed) (updates ??= {})[key] = mapped;
+		} else if (isNode(value)) {
+			const next = transform(value, childOptions);
+			if (next !== value) (updates ??= {})[key] = next;
+		}
+	}
+	return updates ? {
+		...node,
+		...updates
+	} : node;
+}
+/**
+* Lazy depth-first collection pass. Yields every non-null value returned by
+* the visitor callbacks. Use `collect` for the eager array form.
+*
+* @example Collect every operationId
+* ```ts
+* const ids: string[] = []
+* for (const id of collectLazy<string>(root, {
+*   operation(node) {
+*     return node.operationId
+*   },
+* })) {
+*   ids.push(id)
+* }
+* ```
+*/
+function* collectLazy(node, options) {
+	const { depth, parent, ...visitor } = options;
+	const recurse = (depth ?? visitorDepths.deep) === visitorDepths.deep;
+	const v = applyVisitor(node, visitor, parent);
+	if (v != null) yield v;
+	for (const child of getChildren(node, recurse)) yield* collectLazy(child, {
+		...options,
+		parent: node
+	});
+}
+/**
+* Eager depth-first collection pass. Gathers every non-null value the visitor
+* callbacks return into an array.
+*
+* @example Collect every operationId
+* ```ts
+* const ids = collect<string>(root, {
+*   operation(node) {
+*     return node.operationId
+*   },
+* })
+* ```
+*/
+function collect(node, options) {
+	return Array.from(collectLazy(node, options));
+}
+//#endregion
+//#region src/utils/refs.ts
+const plainStringTypes = new Set([
+	"string",
+	"uuid",
+	"email",
+	"url",
+	"datetime"
+]);
+/**
+* Returns the last path segment of a reference string.
+*
+* @example
+* `extractRefName('#/components/schemas/Pet') // 'Pet'`
+*/
+function extractRefName(ref) {
+	return ref.split("/").at(-1) ?? ref;
+}
+/**
+* Resolves the schema name of a ref node. Uses the last segment of `ref` when set, otherwise falls
+* back to `name` then 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'`
+*/
+function resolveRefName(node) {
+	if (!node || node.type !== "ref") return null;
+	if (node.ref) return extractRefName(node.ref) ?? node.name ?? node.schema?.name ?? null;
+	return node.name ?? node.schema?.name ?? null;
+}
+/**
+* Builds a PascalCase child schema name by joining a parent name and property name.
+* Returns `null` when there is no parent to nest under.
+*
+* @example Nested under a parent
+* `childName('Order', 'shipping_address') // 'OrderShippingAddress'`
+*
+* @example No parent
+* `childName(undefined, 'params') // null`
+*/
+function childName(parentName, propName) {
+	return parentName ? pascalCase([parentName, propName].join(" ")) : null;
+}
+/**
+* Builds a PascalCase enum name from the parent name, property name, and a suffix, skipping any
+* empty parts.
+*
+* @example
+* `enumPropName('Order', 'status', 'enum') // 'OrderStatusEnum'`
+*/
+function enumPropName(parentName, propName, enumSuffix) {
+	return pascalCase([
+		parentName,
+		propName,
+		enumSuffix
+	].filter(Boolean).join(" "));
+}
+/**
+* Merges a ref node with its resolved schema, giving usage-site fields precedence.
+*
+* Every field set on the ref node except `kind`, `type`, `name`, `ref`, and `schema` overrides the
+* same field in the resolved `node.schema` (for example `description`, `nullable`, `readOnly`,
+* `deprecated`). Fields left `undefined` on the ref do not shadow the resolved schema. Non-ref
+* nodes and refs without a resolved `schema` are returned unchanged.
+*
+* @example
+* ```ts
+* const ref = createSchema({ type: 'ref', ref: '#/components/schemas/Pet', description: 'A cute pet' })
+* const merged = syncSchemaRef(ref) // merges with resolved Pet schema
+* ```
+*/
+function syncSchemaRef(node) {
+	const ref = narrowSchema(node, "ref");
+	if (!ref) return node;
+	if (!ref.schema) return node;
+	const { kind: _kind, type: _type, name: _name, ref: _ref, schema: _schema, ...overrides } = ref;
+	const definedOverrides = Object.fromEntries(Object.entries(overrides).filter(([, v]) => v !== void 0));
+	return createSchema({
+		...ref.schema,
+		...definedOverrides
+	});
+}
+/**
+* Type guard that returns `true` when a schema emits as a plain `string` type.
+*
+* Covers `string`, `uuid`, `email`, `url`, and `datetime` types. For `date` and `time`
+* types, returns `true` only when `representation` is `'string'` rather than `'date'`.
+*/
+function isStringType(node) {
+	if (plainStringTypes.has(node.type)) return true;
+	const temporal = narrowSchema(node, "date") ?? narrowSchema(node, "time");
+	if (temporal) return temporal.representation !== "date";
+	return false;
+}
+/**
+* Derives a {@link ParamGroupType} for a query or header group from the resolver.
+*
+* Returns `null` when there is no resolver, no params, or the group name equals the
+* individual param name (so there is no real group to emit).
+*/
+function resolveGroupType({ node, params, group, resolver }) {
+	if (!resolver || !params.length) return null;
+	const firstParam = params[0];
+	const groupName = (group === "query" ? resolver.resolveQueryParamsName : resolver.resolveHeaderParamsName).call(resolver, node, firstParam);
+	if (groupName === resolver.resolveParamName(node, firstParam)) return null;
+	return {
+		type: groupName,
+		optional: params.every((p) => !p.required)
+	};
+}
+//#endregion
+Object.defineProperty(exports, "INDENT", {
+	enumerable: true,
+	get: function() {
+		return INDENT;
+	}
+});
 Object.defineProperty(exports, "__exportAll", {
 	enumerable: true,
 	get: function() {
@@ -970,6 +1476,24 @@ Object.defineProperty(exports, "camelCase", {
 		return camelCase;
 	}
 });
+Object.defineProperty(exports, "childName", {
+	enumerable: true,
+	get: function() {
+		return childName;
+	}
+});
+Object.defineProperty(exports, "collect", {
+	enumerable: true,
+	get: function() {
+		return collect;
+	}
+});
+Object.defineProperty(exports, "collectLazy", {
+	enumerable: true,
+	get: function() {
+		return collectLazy;
+	}
+});
 Object.defineProperty(exports, "constDef", {
 	enumerable: true,
 	get: function() {
@@ -1138,12 +1662,24 @@ Object.defineProperty(exports, "defineNode", {
 		return defineNode;
 	}
 });
+Object.defineProperty(exports, "enumPropName", {
+	enumerable: true,
+	get: function() {
+		return enumPropName;
+	}
+});
 Object.defineProperty(exports, "exportDef", {
 	enumerable: true,
 	get: function() {
 		return exportDef;
 	}
 });
+Object.defineProperty(exports, "extractRefName", {
+	enumerable: true,
+	get: function() {
+		return extractRefName;
+	}
+});
 Object.defineProperty(exports, "extractStringsFromNodes", {
 	enumerable: true,
 	get: function() {
@@ -1192,12 +1728,36 @@ Object.defineProperty(exports, "inputDef", {
 		return inputDef;
 	}
 });
+Object.defineProperty(exports, "isHttpOperationNode", {
+	enumerable: true,
+	get: function() {
+		return isHttpOperationNode;
+	}
+});
+Object.defineProperty(exports, "isStringType", {
+	enumerable: true,
+	get: function() {
+		return isStringType;
+	}
+});
 Object.defineProperty(exports, "jsxDef", {
 	enumerable: true,
 	get: function() {
 		return jsxDef;
 	}
 });
+Object.defineProperty(exports, "narrowSchema", {
+	enumerable: true,
+	get: function() {
+		return narrowSchema;
+	}
+});
+Object.defineProperty(exports, "nodeDefs", {
+	enumerable: true,
+	get: function() {
+		return nodeDefs;
+	}
+});
 Object.defineProperty(exports, "objectBindingPatternDef", {
 	enumerable: true,
 	get: function() {
@@ -1228,12 +1788,6 @@ Object.defineProperty(exports, "parameterDef", {
 		return parameterDef;
 	}
 });
-Object.defineProperty(exports, "pascalCase", {
-	enumerable: true,
-	get: function() {
-		return pascalCase;
-	}
-});
 Object.defineProperty(exports, "propertyDef", {
 	enumerable: true,
 	get: function() {
@@ -1246,6 +1800,18 @@ Object.defineProperty(exports, "requestBodyDef", {
 		return requestBodyDef;
 	}
 });
+Object.defineProperty(exports, "resolveGroupType", {
+	enumerable: true,
+	get: function() {
+		return resolveGroupType;
+	}
+});
+Object.defineProperty(exports, "resolveRefName", {
+	enumerable: true,
+	get: function() {
+		return resolveRefName;
+	}
+});
 Object.defineProperty(exports, "responseDef", {
 	enumerable: true,
 	get: function() {
@@ -1258,18 +1824,36 @@ Object.defineProperty(exports, "schemaDef", {
 		return schemaDef;
 	}
 });
+Object.defineProperty(exports, "schemaTypes", {
+	enumerable: true,
+	get: function() {
+		return schemaTypes;
+	}
+});
 Object.defineProperty(exports, "sourceDef", {
 	enumerable: true,
 	get: function() {
 		return sourceDef;
 	}
 });
+Object.defineProperty(exports, "syncSchemaRef", {
+	enumerable: true,
+	get: function() {
+		return syncSchemaRef;
+	}
+});
 Object.defineProperty(exports, "textDef", {
 	enumerable: true,
 	get: function() {
 		return textDef;
 	}
 });
+Object.defineProperty(exports, "transform", {
+	enumerable: true,
+	get: function() {
+		return transform;
+	}
+});
 Object.defineProperty(exports, "typeDef", {
 	enumerable: true,
 	get: function() {
@@ -1288,5 +1872,11 @@ Object.defineProperty(exports, "visitorKeys", {
 		return visitorKeys;
 	}
 });
+Object.defineProperty(exports, "walk", {
+	enumerable: true,
+	get: function() {
+		return walk;
+	}
+});
 
-//# sourceMappingURL=schema-BkvrrOAr.cjs.map
+//# sourceMappingURL=refs-DDIY_Tpn.cjs.map