@kubb/ast 5.0.0-beta.30 → 5.0.0-beta.32

package/dist/index.cjs

@@ -224,60 +224,6 @@ const mediaTypes = {
 	videoMp4: "video/mp4"
 };
 //#endregion
-//#region src/dialect.ts
-/**
-* Identity helper that types a {@link SchemaDialect} for an adapter. Like
-* `defineParser`, it adds no runtime behavior — it pins the dialect's type for
-* inference and gives adapter authors a discoverable anchor.
-*
-* @example
-* ```ts
-* export const oasDialect = defineSchemaDialect({
-*   name: 'oas',
-*   isNullable,
-*   isReference,
-*   isDiscriminator,
-*   isBinary: (schema) => schema.type === 'string' && schema.contentMediaType === 'application/octet-stream',
-*   resolveRef,
-* })
-* ```
-*/
-function defineSchemaDialect(dialect) {
-	return dialect;
-}
-//#endregion
-//#region src/dispatch.ts
-/**
-* Walks an ordered list of {@link DispatchRule}s and returns the first node produced.
-*
-* This is the shared backbone for spec adapters (OpenAPI today, AsyncAPI and others later).
-* The contract an adapter follows is intentionally minimal:
-*
-*     context → [rule.match → rule.convert] → node
-*
-* An adapter derives a context from a source spec node, then declares an ordered table of
-* rules mapping spec shapes onto Kubb AST nodes. To add support for a new spec, write a new
-* context type and a new rules table — the traversal here is reused unchanged.
-*
-* Order is significant: earlier rules win, so list higher-precedence or more specific shapes
-* first (e.g. composition keywords before plain `type`). A rule whose `match` returns `true`
-* may still `convert` to `null` to defer to later rules. When no rule produces a node this
-* returns `null`, leaving the caller to apply its own fallback.
-*
-* @example
-* ```ts
-* const node = dispatch(schemaRules, schemaContext) ?? createSchema({ type: fallbackType })
-* ```
-*/
-function dispatch(rules, context) {
-	for (const rule of rules) {
-		if (!rule.match(context)) continue;
-		const node = rule.convert(context);
-		if (node !== null && node !== void 0) return node;
-	}
-	return null;
-}
-//#endregion
 //#region ../../internals/utils/src/casing.ts
 /**
 * Shared implementation for camelCase and PascalCase conversion.
@@ -2138,6 +2084,454 @@ function createJsx(value) {
 	};
 }
 //#endregion
+//#region src/signature.ts
+/**
+* The shape-affecting flags shared by every node kind: base primitive, format, and `nullable`.
+* Documentation and usage-slot flags (`optional`/`nullish`/`readOnly`/`writeOnly`) are
+* intentionally excluded — they describe the property slot, not the type.
+*/
+function flagsDescriptor(node) {
+	return `${node.primitive ?? ""};${node.format ?? ""};${node.nullable ? 1 : 0}`;
+}
+function refTargetName(node) {
+	if (node.ref) return extractRefName(node.ref);
+	return node.name ?? "";
+}
+const arrayTupleFields = [
+	{
+		kind: "children",
+		key: "items",
+		prefix: "i"
+	},
+	{
+		kind: "child",
+		key: "rest",
+		prefix: "r"
+	},
+	{
+		kind: "scalar",
+		key: "min",
+		prefix: "mn"
+	},
+	{
+		kind: "scalar",
+		key: "max",
+		prefix: "mx"
+	},
+	{
+		kind: "bool",
+		key: "unique",
+		prefix: "u"
+	}
+];
+const numericFields = [
+	{
+		kind: "scalar",
+		key: "min",
+		prefix: "mn"
+	},
+	{
+		kind: "scalar",
+		key: "max",
+		prefix: "mx"
+	},
+	{
+		kind: "scalar",
+		key: "exclusiveMinimum",
+		prefix: "emn"
+	},
+	{
+		kind: "scalar",
+		key: "exclusiveMaximum",
+		prefix: "emx"
+	},
+	{
+		kind: "scalar",
+		key: "multipleOf",
+		prefix: "mo"
+	}
+];
+const rangeFields = [{
+	kind: "scalar",
+	key: "min",
+	prefix: "mn"
+}, {
+	kind: "scalar",
+	key: "max",
+	prefix: "mx"
+}];
+/**
+* Maps each schema node `type` to the ordered list of shape-contributing fields.
+* Node types absent from this map (scalar types like boolean, null, any, etc.) fall
+* back to `${type}|${flags}` with no additional fields.
+*/
+const SHAPE_KEYS = {
+	object: [
+		{ kind: "objectProps" },
+		{ kind: "additionalProps" },
+		{ kind: "patternProps" },
+		{
+			kind: "scalar",
+			key: "minProperties",
+			prefix: "mn"
+		},
+		{
+			kind: "scalar",
+			key: "maxProperties",
+			prefix: "mx"
+		}
+	],
+	array: arrayTupleFields,
+	tuple: arrayTupleFields,
+	union: [
+		{
+			kind: "scalar",
+			key: "strategy",
+			prefix: "s"
+		},
+		{
+			kind: "scalar",
+			key: "discriminatorPropertyName",
+			prefix: "d"
+		},
+		{
+			kind: "children",
+			key: "members",
+			prefix: "m"
+		}
+	],
+	intersection: [{
+		kind: "children",
+		key: "members",
+		prefix: "m"
+	}],
+	enum: [{ kind: "enumValues" }],
+	ref: [{ kind: "refTarget" }],
+	string: [
+		{
+			kind: "scalar",
+			key: "min",
+			prefix: "mn"
+		},
+		{
+			kind: "scalar",
+			key: "max",
+			prefix: "mx"
+		},
+		{
+			kind: "scalar",
+			key: "pattern",
+			prefix: "pt"
+		}
+	],
+	number: numericFields,
+	integer: numericFields,
+	bigint: numericFields,
+	url: [
+		{
+			kind: "scalar",
+			key: "path",
+			prefix: "path"
+		},
+		{
+			kind: "scalar",
+			key: "min",
+			prefix: "mn"
+		},
+		{
+			kind: "scalar",
+			key: "max",
+			prefix: "mx"
+		}
+	],
+	uuid: rangeFields,
+	email: rangeFields,
+	datetime: [{
+		kind: "bool",
+		key: "offset",
+		prefix: "o"
+	}, {
+		kind: "bool",
+		key: "local",
+		prefix: "l"
+	}],
+	date: [{
+		kind: "scalar",
+		key: "representation",
+		prefix: "rep"
+	}],
+	time: [{
+		kind: "scalar",
+		key: "representation",
+		prefix: "rep"
+	}]
+};
+function serializeShapeField(field, node, record) {
+	switch (field.kind) {
+		case "scalar": return `${field.prefix}:${record[field.key] ?? ""}`;
+		case "bool": return `${field.prefix}:${record[field.key] ? 1 : 0}`;
+		case "child": {
+			const child = record[field.key];
+			return `${field.prefix}:${child ? signatureOf(child) : ""}`;
+		}
+		case "children": {
+			const children = record[field.key] ?? [];
+			return `${field.prefix}[${children.map((c) => signatureOf(c)).join(",")}]`;
+		}
+		case "objectProps": return `p[${(node.properties ?? []).map((prop) => `${prop.name}${prop.required ? "!" : "?"}${signatureOf(prop.schema)}`).join(",")}]`;
+		case "additionalProps": {
+			const obj = node;
+			if (typeof obj.additionalProperties === "boolean") return `ab:${obj.additionalProperties}`;
+			if (obj.additionalProperties) return `as:${signatureOf(obj.additionalProperties)}`;
+			return "";
+		}
+		case "patternProps": {
+			const obj = node;
+			return `pp[${obj.patternProperties ? Object.keys(obj.patternProperties).sort().map((key) => `${key}=${signatureOf(obj.patternProperties[key])}`).join(",") : ""}]`;
+		}
+		case "enumValues": {
+			const en = node;
+			let values = "";
+			if (en.namedEnumValues?.length) values = en.namedEnumValues.map((entry) => `${entry.name}=${entry.primitive}:${String(entry.value)}`).join(",");
+			else if (en.enumValues?.length) values = en.enumValues.map((value) => `${value === null ? "null" : typeof value}:${String(value)}`).join(",");
+			return `v[${values}]`;
+		}
+		case "refTarget": return `->${refTargetName(node)}`;
+	}
+}
+/**
+* Builds the local, shape-only descriptor for a node: its kind, flags, constraints, and its
+* children's signatures. {@link signatureOf} hashes this string; children contribute their
+* fixed-length signature rather than their own full descriptor, which keeps the result bounded.
+*/
+function describeShape(node) {
+	const flags = flagsDescriptor(node);
+	const fields = SHAPE_KEYS[node.type];
+	if (!fields) return `${node.type}|${flags}`;
+	const record = node;
+	const parts = [`${node.type}|${flags}`];
+	for (const field of fields) parts.push(serializeShapeField(field, node, record));
+	return parts.join("|");
+}
+/**
+* Persistent hash-consing cache: `SchemaNode` → signature digest, keyed by node identity.
+*
+* A `WeakMap` so entries are released once the node is garbage-collected, and so a node hashed
+* during dedupe planning is not re-hashed when the same tree is rewritten during streaming
+* (where `schemaSignature` and `applyDedupe` would otherwise each walk it from scratch). Reuse
+* across calls is sound because a signature depends only on a node's content, and schema nodes
+* are immutable once created — transforms allocate new objects rather than mutating in place.
+*/
+const signatureCache = /* @__PURE__ */ new WeakMap();
+/**
+* Hash-consing: each node's signature is a fixed-length digest of its local shape plus its
+* children's digests (a Merkle hash). Children contribute their 64-char hash instead of their
+* full nested descriptor, so a signature stays bounded regardless of subtree depth, and the
+* digest is identical across calls because it depends only on content — never on traversal
+* order. This keeps the keys built during planning consistent with the ones recomputed later
+* during streaming. {@link signatureCache} memoizes node → digest across every computation.
+*/
+function signatureOf(node) {
+	const cached = signatureCache.get(node);
+	if (cached !== void 0) return cached;
+	const signature = (0, node_crypto.createHash)("sha256").update(describeShape(node)).digest("hex");
+	signatureCache.set(node, signature);
+	return signature;
+}
+/**
+* Computes a deterministic, shape-only signature (a fixed-length content hash) for a schema node.
+*
+* Two schemas share a signature when they are structurally identical, ignoring
+* documentation (`name`, `title`, `description`, `example`, `default`, `deprecated`)
+* and usage-slot flags (`optional`, `nullish`, `readOnly`, `writeOnly`). `nullable`
+* is kept because it changes the produced type. `ref` nodes compare by target name,
+* which also keeps the algorithm terminating on circular shapes.
+*
+* @example Two enums with different descriptions share a signature
+* ```ts
+* schemaSignature(createSchema({ type: 'enum', primitive: 'string', enumValues: ['a', 'b'], description: 'x' })) ===
+*   schemaSignature(createSchema({ type: 'enum', primitive: 'string', enumValues: ['a', 'b'] }))
+* ```
+*/
+function schemaSignature(node) {
+	return signatureOf(node);
+}
+/**
+* Returns `true` when two schema nodes are structurally identical under shape-only equality.
+*
+* @example
+* ```ts
+* isSchemaEqual(a, b) // a and b produce the same TypeScript type
+* ```
+*/
+function isSchemaEqual(a, b) {
+	return schemaSignature(a) === schemaSignature(b);
+}
+//#endregion
+//#region src/dedupe.ts
+/**
+* Builds the shared `ref` replacement for a duplicate occurrence, carrying the
+* usage-slot and documentation fields that are not part of the canonical type.
+*/
+function createRefNode(node, canonical) {
+	return createSchema({
+		type: "ref",
+		name: canonical.name,
+		ref: canonical.ref,
+		optional: node.optional,
+		nullish: node.nullish,
+		readOnly: node.readOnly,
+		writeOnly: node.writeOnly,
+		deprecated: node.deprecated,
+		description: node.description,
+		default: node.default,
+		example: node.example
+	});
+}
+function applyDedupe(node, canonicalBySignature, skipRootMatch = false) {
+	if (canonicalBySignature.size === 0) return node;
+	const root = node;
+	return transform(node, { schema(schemaNode) {
+		const signature = signatureOf(schemaNode);
+		if (skipRootMatch && schemaNode === root) return void 0;
+		const canonical = canonicalBySignature.get(signature);
+		if (!canonical) return void 0;
+		return createRefNode(schemaNode, canonical);
+	} });
+}
+/**
+* Strips usage-slot flags from a hoisted definition and applies its canonical name.
+* A standalone definition is never optional, so `optional`/`nullish` are cleared.
+*/
+function cleanDefinition(node, name) {
+	return {
+		...node,
+		name,
+		optional: void 0,
+		nullish: void 0
+	};
+}
+/**
+* Scans a forest of schema and operation nodes and produces a {@link DedupePlan}.
+*
+* A shape that occurs at least `minOccurrences` times is deduplicated: if any occurrence
+* is a named top-level schema, that name becomes the canonical (so other top-level duplicates
+* and inline copies turn into references to it); otherwise a new definition is hoisted using
+* `nameFor`. The plan is then applied per node with {@link applyDedupe}.
+*
+* @example
+* ```ts
+* const plan = buildDedupePlan([...schemaNodes, ...operationNodes], {
+*   isCandidate: (node) => node.type === 'enum' || node.type === 'object',
+*   nameFor: (node) => node.name ?? null,
+*   refFor: (name) => `#/components/schemas/${name}`,
+* })
+* ```
+*/
+function buildDedupePlan(roots, options) {
+	const { isCandidate, nameFor, refFor, minOccurrences = 2 } = options;
+	const topLevelNodes = /* @__PURE__ */ new Set();
+	const groups = /* @__PURE__ */ new Map();
+	function record(schemaNode) {
+		const signature = signatureOf(schemaNode);
+		if (!isCandidate(schemaNode)) return;
+		const isTopLevel = topLevelNodes.has(schemaNode) && !!schemaNode.name;
+		const group = groups.get(signature);
+		if (group) {
+			group.count++;
+			if (isTopLevel && !group.topLevelName) group.topLevelName = schemaNode.name;
+		} else groups.set(signature, {
+			count: 1,
+			representative: schemaNode,
+			topLevelName: isTopLevel ? schemaNode.name : void 0
+		});
+	}
+	for (const root of roots) {
+		if (root.kind === "Schema") topLevelNodes.add(root);
+		for (const schemaNode of collectLazy(root, { schema: (node) => node })) record(schemaNode);
+	}
+	const canonicalBySignature = /* @__PURE__ */ new Map();
+	const pendingHoists = [];
+	for (const [signature, group] of groups) {
+		if (group.count < minOccurrences) continue;
+		if (group.topLevelName) {
+			canonicalBySignature.set(signature, {
+				name: group.topLevelName,
+				ref: refFor(group.topLevelName)
+			});
+			continue;
+		}
+		const name = nameFor(group.representative, signature);
+		if (!name) continue;
+		canonicalBySignature.set(signature, {
+			name,
+			ref: refFor(name)
+		});
+		pendingHoists.push({
+			name,
+			representative: group.representative
+		});
+	}
+	return {
+		canonicalBySignature,
+		hoisted: pendingHoists.map(({ name, representative }) => cleanDefinition(applyDedupe(representative, canonicalBySignature, true), name))
+	};
+}
+//#endregion
+//#region src/dialect.ts
+/**
+* Identity helper that types a {@link SchemaDialect} for an adapter. Like
+* `defineParser`, it adds no runtime behavior — it pins the dialect's type for
+* inference and gives adapter authors a discoverable anchor.
+*
+* @example
+* ```ts
+* export const oasDialect = defineSchemaDialect({
+*   name: 'oas',
+*   isNullable,
+*   isReference,
+*   isDiscriminator,
+*   isBinary: (schema) => schema.type === 'string' && schema.contentMediaType === 'application/octet-stream',
+*   resolveRef,
+* })
+* ```
+*/
+function defineSchemaDialect(dialect) {
+	return dialect;
+}
+//#endregion
+//#region src/dispatch.ts
+/**
+* Walks an ordered list of {@link DispatchRule}s and returns the first node produced.
+*
+* This is the shared backbone for spec adapters (OpenAPI today, AsyncAPI and others later).
+* The contract an adapter follows is intentionally minimal:
+*
+*     context → [rule.match → rule.convert] → node
+*
+* An adapter derives a context from a source spec node, then declares an ordered table of
+* rules mapping spec shapes onto Kubb AST nodes. To add support for a new spec, write a new
+* context type and a new rules table — the traversal here is reused unchanged.
+*
+* Order is significant: earlier rules win, so list higher-precedence or more specific shapes
+* first (e.g. composition keywords before plain `type`). A rule whose `match` returns `true`
+* may still `convert` to `null` to defer to later rules. When no rule produces a node this
+* returns `null`, leaving the caller to apply its own fallback.
+*
+* @example
+* ```ts
+* const node = dispatch(schemaRules, schemaContext) ?? createSchema({ type: fallbackType })
+* ```
+*/
+function dispatch(rules, context) {
+	for (const rule of rules) {
+		if (!rule.match(context)) continue;
+		const node = rule.convert(context);
+		if (node !== null && node !== void 0) return node;
+	}
+	return null;
+}
+//#endregion
 //#region src/printer.ts
 /**
 * Defines a schema printer: a function that takes a `SchemaNode` and emits
@@ -2354,6 +2748,8 @@ function setEnumName(propNode, parentName, propName, enumSuffix) {
 	return propNode;
 }
 //#endregion
+exports.applyDedupe = applyDedupe;
+exports.buildDedupePlan = buildDedupePlan;
 exports.caseParams = caseParams;
 exports.childName = childName;
 exports.collect = collect;
@@ -2404,6 +2800,7 @@ exports.isInputNode = isInputNode;
 exports.isOperationNode = isOperationNode;
 exports.isOutputNode = isOutputNode;
 exports.isScalarPrimitive = isScalarPrimitive;
+exports.isSchemaEqual = isSchemaEqual;
 exports.isSchemaNode = isSchemaNode;
 exports.isStringType = isStringType;
 exports.mediaTypes = mediaTypes;
@@ -2412,6 +2809,7 @@ exports.mergeAdjacentObjectsLazy = mergeAdjacentObjectsLazy;
 exports.narrowSchema = narrowSchema;
 exports.nodeKinds = nodeKinds;
 exports.resolveRefName = resolveRefName;
+exports.schemaSignature = schemaSignature;
 exports.schemaTypes = schemaTypes;
 exports.setDiscriminatorEnum = setDiscriminatorEnum;
 exports.setEnumName = setEnumName;