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

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,277 @@ 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 ?? "";
+}
+/**
+* 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, signatures) {
+	const flags = flagsDescriptor(node);
+	switch (node.type) {
+		case "object": {
+			const props = (node.properties ?? []).map((prop) => `${prop.name}${prop.required ? "!" : "?"}${signatureOf(prop.schema, signatures)}`).join(",");
+			let additional = "";
+			if (typeof node.additionalProperties === "boolean") additional = `ab:${node.additionalProperties}`;
+			else if (node.additionalProperties) additional = `as:${signatureOf(node.additionalProperties, signatures)}`;
+			const pattern = node.patternProperties ? Object.keys(node.patternProperties).sort().map((key) => `${key}=${signatureOf(node.patternProperties[key], signatures)}`).join(",") : "";
+			return `object|${flags}|p[${props}]|${additional}|pp[${pattern}]|mn:${node.minProperties ?? ""}|mx:${node.maxProperties ?? ""}`;
+		}
+		case "array":
+		case "tuple": {
+			const items = (node.items ?? []).map((item) => signatureOf(item, signatures)).join(",");
+			const rest = node.rest ? signatureOf(node.rest, signatures) : "";
+			return `${node.type}|${flags}|i[${items}]|r:${rest}|mn:${node.min ?? ""}|mx:${node.max ?? ""}|u:${node.unique ? 1 : 0}`;
+		}
+		case "union": {
+			const members = (node.members ?? []).map((member) => signatureOf(member, signatures)).join(",");
+			return `union|${flags}|s:${node.strategy ?? ""}|d:${node.discriminatorPropertyName ?? ""}|m[${members}]`;
+		}
+		case "intersection": return `intersection|${flags}|m[${(node.members ?? []).map((member) => signatureOf(member, signatures)).join(",")}]`;
+		case "enum": {
+			let values = "";
+			if (node.namedEnumValues?.length) values = node.namedEnumValues.map((entry) => `${entry.name}=${entry.primitive}:${String(entry.value)}`).join(",");
+			else if (node.enumValues?.length) values = node.enumValues.map((value) => `${value === null ? "null" : typeof value}:${String(value)}`).join(",");
+			return `enum|${flags}|v[${values}]`;
+		}
+		case "ref": return `ref|${flags}|->${refTargetName(node)}`;
+		case "string": return `string|${flags}|mn:${node.min ?? ""}|mx:${node.max ?? ""}|pt:${node.pattern ?? ""}`;
+		case "number":
+		case "integer":
+		case "bigint": return `${node.type}|${flags}|mn:${node.min ?? ""}|mx:${node.max ?? ""}|emn:${node.exclusiveMinimum ?? ""}|emx:${node.exclusiveMaximum ?? ""}|mo:${node.multipleOf ?? ""}`;
+		case "url": return `url|${flags}|path:${node.path ?? ""}|mn:${node.min ?? ""}|mx:${node.max ?? ""}`;
+		case "uuid":
+		case "email": return `${node.type}|${flags}|mn:${node.min ?? ""}|mx:${node.max ?? ""}`;
+		case "datetime": return `datetime|${flags}|o:${node.offset ? 1 : 0}|l:${node.local ? 1 : 0}`;
+		case "date":
+		case "time": return `${node.type}|${flags}|rep:${node.representation}`;
+		default: return `${node.type}|${flags}`;
+	}
+}
+/**
+* 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. `signatures` memoizes node → digest within a single computation.
+*/
+function signatureOf(node, signatures) {
+	const cached = signatures.get(node);
+	if (cached !== void 0) return cached;
+	const signature = (0, node_crypto.createHash)("sha256").update(describeShape(node, signatures)).digest("hex");
+	signatures.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, /* @__PURE__ */ new Map());
+}
+/**
+* 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 signatures = /* @__PURE__ */ new Map();
+	const root = node;
+	return transform(node, { schema(schemaNode) {
+		const signature = signatureOf(schemaNode, signatures);
+		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 signatures = /* @__PURE__ */ new Map();
+	const topLevelNodes = /* @__PURE__ */ new Set();
+	const groups = /* @__PURE__ */ new Map();
+	function record(schemaNode) {
+		const signature = signatureOf(schemaNode, signatures);
+		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 +2571,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 +2623,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 +2632,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;