@kubb/adapter-oas 5.0.0-beta.61 → 5.0.0-beta.63

package/dist/index.js

@@ -14,10 +14,9 @@ import { collect, narrowSchema } from "@kubb/ast";
 *
 * @example
 * ```ts
-* import { DEFAULT_PARSER_OPTIONS } from '@kubb/adapter-oas'
+* import { DEFAULT_PARSER_OPTIONS, parseOas } from '@kubb/adapter-oas'
 *
-* const parser = createOasParser(oas)
-* const root = parser.parse({ ...DEFAULT_PARSER_OPTIONS, dateType: 'date' })
+* const { root } = parseOas(document, { ...DEFAULT_PARSER_OPTIONS, dateType: 'date' })
 * ```
 */
 const DEFAULT_PARSER_OPTIONS = {
@@ -88,12 +87,24 @@ const structuralKeys = new Set([
 	"not"
 ]);
 /**
+* Formats `convertFormat` maps to a dedicated type without going through `formatMap`:
+* `int64` and the date/time family. Keep this in sync with the `convertFormat`
+* special-cases in `parser.ts`. `isHandledFormat` reads it so the
+* `KUBB_UNSUPPORTED_FORMAT` diagnostic and the parser agree on what is handled.
+*/
+const specialCasedFormats = new Set([
+	"int64",
+	"date-time",
+	"date",
+	"time"
+]);
+/**
 * Static map from OAS `format` strings to Kubb `SchemaType` values.
 *
 * Only formats whose AST type differs from the OAS `type` field appear here.
-* Formats that depend on runtime options (`int64`, `date-time`, `date`, `time`) are handled separately
-* in the parser. `ipv4` and `ipv6` map to their own dedicated schema types. `hostname` and
-* `idn-hostname` map to `'url'` as the closest generic string-format type.
+* Formats that depend on runtime options (`int64`, `date-time`, `date`, `time`) are handled
+* separately in the parser. `ipv4` and `ipv6` map to their own dedicated schema types. `hostname`
+* and `idn-hostname` map to `'url'` as the closest generic string-format type.
 *
 * @example
 * ```ts
@@ -104,18 +115,6 @@ const structuralKeys = new Set([
 * formatMap['float']  // 'number'
 * ```
 */
-/**
-* Formats `convertFormat` maps to a dedicated type without going through `formatMap`:
-* `int64` and the date/time family. Keep this in sync with the `convertFormat`
-* special-cases in `parser.ts`. `isHandledFormat` reads it so the
-* `KUBB_UNSUPPORTED_FORMAT` diagnostic and the parser agree on what is handled.
-*/
-const specialCasedFormats = new Set([
-	"int64",
-	"date-time",
-	"date",
-	"time"
-]);
 const formatMap = {
 	uuid: "uuid",
 	email: "email",
@@ -636,7 +635,7 @@ function isDiscriminator(obj) {
 //#endregion
 //#region src/factory.ts
 /**
-* Loads and dereferences an OpenAPI document, returning the raw `Document`.
+* Loads and bundles an OpenAPI document, returning the raw `Document`.
 *
 * Accepts a file path string or an already-parsed document object. File paths and URLs are
 * bundled via `api-ref-bundler`, hoisting external file schemas into named `components.schemas`
@@ -747,17 +746,180 @@ async function validateDocument(document, { throwOnError = false } = {}) {
 	}
 }
 //#endregion
+//#region src/dedupe.ts
+/**
+* Minimum occurrences before a shape is deduplicated.
+*/
+const MIN_OCCURRENCES = 2;
+/**
+* Builds the shared `ref` replacement for a duplicate occurrence, carrying the
+* usage-slot and documentation fields that are not part of the shared type.
+*/
+function createRefNode(node, target) {
+	return ast.factory.createSchema({
+		type: "ref",
+		name: target.name,
+		ref: target.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
+	});
+}
+/**
+* Strips usage-slot flags from an extracted definition and applies its 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
+	};
+}
+/**
+* Returns `true` when a node is eligible for deduplication. Only enums and objects qualify, and
+* object shapes that take part in a circular chain are rejected so recursive structures are not
+* extracted (which would break the cycle).
+*/
+function isCandidate(node, circularSchemas) {
+	if (node.type === "enum") return true;
+	if (node.type !== "object") return false;
+	if (node.name && circularSchemas.has(node.name)) return false;
+	return !containsCircularRef(node, { circularSchemas });
+}
+/**
+* Produces the name for an inline shape with no existing named component, resolving
+* collisions against `usedNames`. Returns `null` for an unnamed shape, which stays inline.
+*/
+function nameFor(node, usedNames) {
+	const base = node.name;
+	if (!base) return null;
+	let name = base;
+	let counter = 2;
+	while (usedNames.has(name)) name = `${base}${counter++}`;
+	usedNames.add(name);
+	return name;
+}
+/**
+* Scans a forest of schema and operation nodes and produces a {@link Plan}.
+*
+* A shape that occurs at least {@link MIN_OCCURRENCES} times is deduplicated: if any occurrence is
+* a named top-level schema, the first one becomes the target (so other top-level duplicates and
+* inline copies turn into references to it). Other top-level names with the same content are
+* recorded as aliases. Otherwise a new definition is extracted using {@link nameFor}. The returned
+* plan rewrites nodes against those decisions.
+*
+* @example
+* ```ts
+* const dedupePlan = plan([...schemaNodes, ...operationNodes], { circularSchemas, usedNames })
+* ```
+*/
+function plan(roots, context) {
+	const { circularSchemas, usedNames } = context;
+	const topLevelNodes = /* @__PURE__ */ new Set();
+	const groups = /* @__PURE__ */ new Map();
+	for (const root of roots) {
+		if (root.kind === "Schema") topLevelNodes.add(root);
+		for (const schemaNode of ast.collect(root, { schema: (node) => node })) {
+			if (!isCandidate(schemaNode, circularSchemas)) continue;
+			const signature = ast.signatureOf(schemaNode);
+			const isTopLevel = topLevelNodes.has(schemaNode) && !!schemaNode.name;
+			const group = groups.get(signature);
+			if (group) {
+				group.count++;
+				if (isTopLevel) group.topLevelNames.push(schemaNode.name);
+			} else groups.set(signature, {
+				count: 1,
+				representative: schemaNode,
+				topLevelNames: isTopLevel ? [schemaNode.name] : []
+			});
+		}
+	}
+	const bySignature = /* @__PURE__ */ new Map();
+	const byName = /* @__PURE__ */ new Map();
+	const pendingExtractions = [];
+	for (const [signature, group] of groups) {
+		if (group.count < MIN_OCCURRENCES) continue;
+		const [firstName, ...duplicateNames] = group.topLevelNames;
+		if (firstName) {
+			const target = {
+				name: firstName,
+				ref: `${SCHEMA_REF_PREFIX}${firstName}`
+			};
+			bySignature.set(signature, target);
+			for (const duplicate of duplicateNames) byName.set(duplicate, target);
+			continue;
+		}
+		const name = nameFor(group.representative, usedNames);
+		if (!name) continue;
+		bySignature.set(signature, {
+			name,
+			ref: `${SCHEMA_REF_PREFIX}${name}`
+		});
+		pendingExtractions.push({
+			name,
+			representative: group.representative
+		});
+	}
+	function rewrite(node, skipRootMatch) {
+		if (bySignature.size === 0 && byName.size === 0) return node;
+		const root = node;
+		return ast.transform(node, { schema(schemaNode) {
+			if (schemaNode.type === "ref") {
+				const refName = schemaNode.ref ? extractRefName(schemaNode.ref) : schemaNode.name;
+				const target = refName ? byName.get(refName) : void 0;
+				return target ? {
+					...schemaNode,
+					name: target.name,
+					ref: target.ref
+				} : void 0;
+			}
+			if (skipRootMatch && schemaNode === root) return void 0;
+			const target = bySignature.get(ast.signatureOf(schemaNode));
+			if (!target) return void 0;
+			return createRefNode(schemaNode, target);
+		} });
+	}
+	return {
+		extracted: pendingExtractions.map(({ name, representative }) => cleanDefinition(rewrite(representative, true), name)),
+		apply(node) {
+			return rewrite(node, false);
+		},
+		applyTopLevel(node) {
+			const target = bySignature.get(ast.signatureOf(node));
+			if (target && target.name !== node.name) return ast.factory.createSchema({
+				type: "ref",
+				name: node.name ?? null,
+				ref: target.ref,
+				description: node.description,
+				deprecated: node.deprecated
+			});
+			return rewrite(node, true);
+		},
+		isAlias(name) {
+			return byName.has(name);
+		}
+	};
+}
+//#endregion
 //#region src/refs.ts
 const _refCache = /* @__PURE__ */ new WeakMap();
 /**
 * Resolves a local JSON pointer reference from a document.
 *
-* Accepts `#/...` refs. Returns `null` for empty or non-local refs.
-* Throws when the pointer cannot be resolved.
+* Accepts `#/...` refs. Returns `null` for an empty or non-local ref. When the pointer cannot be
+* resolved, reports a `refNotFound` diagnostic into the active build and returns `null`. Outside a
+* build there is no sink to collect it, so it throws instead.
 *
 * @example
 * ```ts
-* resolveRef<SchemaObject>(document, '#/components/schemas/Pet') // SchemaObject | null
+* resolveRef<SchemaObject>(document, '#/components/schemas/Pet')
 * ```
 */
 function resolveRef(document, $ref) {
@@ -832,18 +994,21 @@ function dereferenceWithRef(document, schema) {
 * const parser = createSchemaParser(context, oasDialect) // explicit
 * ```
 */
-const oasDialect = ast.defineSchemaDialect({
+const oasDialect = ast.defineDialect({
 	name: "oas",
-	isNullable,
-	isReference,
-	isDiscriminator,
-	isBinary: (schema) => schema.type === "string" && schema.contentMediaType === "application/octet-stream",
-	resolveRef
+	schema: {
+		isNullable,
+		isReference,
+		isDiscriminator,
+		isBinary: (schema) => schema.type === "string" && schema.contentMediaType === "application/octet-stream",
+		resolveRef
+	},
+	dedupe: { plan }
 });
 //#endregion
 //#region src/discriminator.ts
 /**
-* Builds a map of child schema names → discriminator patch data by scanning the given
+* Maps each child schema name to its discriminator patch data by scanning the given
 * top-level AST schema nodes for union schemas that carry a `discriminatorPropertyName`.
 *
 * The streaming path calls this on a small pre-parsed subset of schemas (only the
@@ -959,9 +1124,8 @@ function findDiscriminator(mapping, ref) {
 /**
 * MIME type fragments that mark a media type as JSON-like.
 *
-* Matches the substrings used by the `oas` library's `matchesMimeType.json`, so a content type is
-* JSON when it contains any of these. The `+json` entry catches structured-syntax suffixes such as
-* `application/vnd.api+json`.
+* A content type is JSON when it contains any of these substrings. The `+json` entry catches
+* structured-syntax suffixes such as `application/vnd.api+json`.
 */
 const jsonMimeFragments = [
 	"application/json",
@@ -1057,8 +1221,8 @@ function getRequestContent({ document, operation, mediaType }) {
 	return available ? [available, content[available]] : false;
 }
 /**
-* Returns the primary request content type. Prefers a JSON-like media type (the last one wins,
-* matching the previous behavior), then the first declared one, defaulting to `'application/json'`.
+* Returns the primary request content type. Prefers a JSON-like media type (the last one wins
+* when several are declared), then the first declared one, defaulting to `'application/json'`.
 */
 function getRequestContentType({ document, operation }) {
 	const content = getRequestBodyContent({
@@ -1153,9 +1317,9 @@ function getSchemaType(format) {
 	return formatMap[format] ?? null;
 }
 /**
-* Whether the parser maps `format` to a dedicated type. True for any `formatMap` entry and the
-* `specialCasedFormats` `convertFormat` handles directly. False means the format falls back to the
-* base type, which is what `KUBB_UNSUPPORTED_FORMAT` flags. Reading both sources keeps the
+* Whether the parser maps `format` to a dedicated type. True for any `formatMap` entry, plus the
+* `specialCasedFormats` that `convertFormat` handles directly. False means the format falls back to
+* the base type, which is what `KUBB_UNSUPPORTED_FORMAT` flags. Reading both sources keeps the
 * diagnostic in step with the parser as `formatMap` grows.
 */
 function isHandledFormat(format) {
@@ -1173,7 +1337,7 @@ function getPrimitiveType(type) {
 /**
 * Returns all parameters for an operation, merging path-level and operation-level entries.
 * Operation-level parameters override path-level ones with the same `in:name` key.
-* `$ref` parameters resolve via `dereferenceWithRef` for backward compatibility.
+* Each `$ref` parameter is dereferenced via `dereferenceWithRef` before merging.
 *
 * @example
 * ```ts
@@ -1274,7 +1438,10 @@ function getRequestSchema(document, operation, options = {}) {
 * ```ts
 * flattenSchema({ allOf: [{ description: 'A pet' }], type: 'object', properties: {} })
 * // { type: 'object', properties: {}, description: 'A pet' }
+* ```
 *
+* @example
+* ```ts
 * flattenSchema({ allOf: [{ $ref: '#/components/schemas/Pet' }] })
 * // returned unchanged, contains a $ref
 * ```
@@ -1561,6 +1728,21 @@ function normalizeArrayEnum(schema) {
 	};
 }
 /**
+* Builds a `null` scalar node carrying the schema's documentation. Shared by the `const: null`
+* and the drf-spectacular `NullEnum` (`{ enum: [null] }`) branches, which render identically.
+*/
+function createNullSchema(schema, name) {
+	return ast.factory.createSchema({
+		type: "null",
+		primitive: "null",
+		name,
+		title: schema.title,
+		description: schema.description,
+		deprecated: schema.deprecated,
+		format: schema.format
+	});
+}
+/**
 * Names the inline enums on a property's schema, and on each item when the property is a tuple, from
 * the parent and property name. Wraps `macroEnumName` at the property construction site.
 */
@@ -1616,7 +1798,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		if (refPath && !resolvingRefs.has(refPath)) {
 			if (!resolvedRefCache.has(refPath)) {
 				try {
-					const referenced = dialect.resolveRef(document, refPath);
+					const referenced = dialect.schema.resolveRef(document, refPath);
 					if (referenced) {
 						resolvingRefs.add(refPath);
 						resolvedSchema = parseSchema({ schema: referenced }, rawOptions);
@@ -1665,13 +1847,13 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		}
 		const filteredDiscriminantValues = [];
 		const allOfMembers = schema.allOf.filter((item) => {
-			if (!dialect.isReference(item) || !name) return true;
-			const deref = dialect.resolveRef(document, item.$ref);
-			if (!deref || !dialect.isDiscriminator(deref)) return true;
+			if (!dialect.schema.isReference(item) || !name) return true;
+			const deref = dialect.schema.resolveRef(document, item.$ref);
+			if (!deref || !dialect.schema.isDiscriminator(deref)) return true;
 			const parentUnion = deref.oneOf ?? deref.anyOf;
 			if (!parentUnion) return true;
 			const childRef = `${SCHEMA_REF_PREFIX}${name}`;
-			const inOneOf = parentUnion.some((oneOfItem) => dialect.isReference(oneOfItem) && oneOfItem.$ref === childRef);
+			const inOneOf = parentUnion.some((oneOfItem) => dialect.schema.isReference(oneOfItem) && oneOfItem.$ref === childRef);
 			const inMapping = Object.values(deref.discriminator.mapping ?? {}).some((v) => v === childRef);
 			if (inOneOf || inMapping) {
 				const discriminatorValue = findDiscriminator(deref.discriminator.mapping, childRef);
@@ -1692,9 +1874,9 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 			const missingRequired = schema.required.filter((key) => !outerKeys.has(key));
 			if (missingRequired.length) {
 				const resolvedMembers = schema.allOf.flatMap((item) => {
-					if (!dialect.isReference(item)) return [item];
-					const deref = dialect.resolveRef(document, item.$ref);
-					return deref && !dialect.isReference(deref) ? [deref] : [];
+					if (!dialect.schema.isReference(item)) return [item];
+					const deref = dialect.schema.resolveRef(document, item.$ref);
+					return deref && !dialect.schema.isReference(deref) ? [deref] : [];
 				});
 				for (const key of missingRequired) for (const resolved of resolvedMembers) if (resolved.properties?.[key]) {
 					allOfMembers.push(parseSchema({
@@ -1739,10 +1921,10 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		const strategy = schema.oneOf ? "one" : "any";
 		const unionBase = {
 			...buildSchemaNode(schema, name, nullable, defaultValue),
-			discriminatorPropertyName: dialect.isDiscriminator(schema) ? schema.discriminator.propertyName : void 0,
+			discriminatorPropertyName: dialect.schema.isDiscriminator(schema) ? schema.discriminator.propertyName : void 0,
 			strategy
 		};
-		const discriminator = dialect.isDiscriminator(schema) ? schema.discriminator : void 0;
+		const discriminator = dialect.schema.isDiscriminator(schema) ? schema.discriminator : void 0;
 		const sharedPropertiesNode = schema.properties ? (() => {
 			const { oneOf: _oneOf, anyOf: _anyOf, ...schemaWithoutUnion } = schema;
 			return parseSchema({
@@ -1752,7 +1934,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		})() : void 0;
 		if (sharedPropertiesNode || discriminator?.mapping) {
 			const members = unionMembers.map((s) => {
-				const ref = dialect.isReference(s) ? s.$ref : void 0;
+				const ref = dialect.schema.isReference(s) ? s.$ref : void 0;
 				const discriminatorValue = findDiscriminator(discriminator?.mapping, ref);
 				const memberNode = parseSchema({
 					schema: s,
@@ -1798,15 +1980,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 	*/
 	function convertConst({ schema, name, nullable, defaultValue }) {
 		const constValue = schema.const;
-		if (constValue === null) return ast.factory.createSchema({
-			type: "null",
-			primitive: "null",
-			name,
-			title: schema.title,
-			description: schema.description,
-			deprecated: schema.deprecated,
-			format: schema.format
-		});
+		if (constValue === null) return createNullSchema(schema, name);
 		const constPrimitive = getPrimitiveType(typeof constValue === "number" ? "number" : typeof constValue === "boolean" ? "boolean" : "string");
 		return ast.factory.createSchema({
 			type: "enum",
@@ -1895,15 +2069,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		}, rawOptions);
 		const nullInEnum = schema.enum.includes(null);
 		const filteredValues = nullInEnum ? schema.enum.filter((v) => v !== null) : schema.enum;
-		if (nullInEnum && filteredValues.length === 0) return ast.factory.createSchema({
-			type: "null",
-			primitive: "null",
-			name,
-			title: schema.title,
-			description: schema.description,
-			deprecated: schema.deprecated,
-			format: schema.format
-		});
+		if (nullInEnum && filteredValues.length === 0) return createNullSchema(schema, name);
 		const enumNullable = nullable || nullInEnum || void 0;
 		const enumDefault = schema.default === null && enumNullable ? void 0 : schema.default;
 		const enumPrimitive = getPrimitiveType(type);
@@ -1953,7 +2119,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		const properties = schema.properties ? Object.entries(schema.properties).map(([propName, propSchema]) => {
 			const required = Array.isArray(schema.required) ? schema.required.includes(propName) : !!schema.required;
 			const resolvedPropSchema = propSchema;
-			const propNullable = dialect.isNullable(resolvedPropSchema);
+			const propNullable = dialect.schema.isNullable(resolvedPropSchema);
 			const schemaNode = nameEnums(parseSchema({
 				schema: resolvedPropSchema,
 				name: childName(name, propName)
@@ -1990,7 +2156,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 			maxProperties: schema.maxProperties,
 			...buildSchemaNode(schema, name, nullable, defaultValue)
 		});
-		if (dialect.isDiscriminator(schema) && schema.discriminator.mapping) {
+		if (dialect.schema.isDiscriminator(schema) && schema.discriminator.mapping) {
 			const discPropName = schema.discriminator.propertyName;
 			const values = Object.keys(schema.discriminator.mapping);
 			const enumName = name ? enumPropName(name, discPropName, options.enumSuffix) : void 0;
@@ -2134,7 +2300,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 	const schemaRules = [
 		{
 			name: "ref",
-			match: ({ schema }) => dialect.isReference(schema),
+			match: ({ schema }) => dialect.schema.isReference(schema),
 			convert: convertRef
 		},
 		{
@@ -2159,7 +2325,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		},
 		{
 			name: "blob",
-			match: ({ schema }) => dialect.isBinary(schema),
+			match: ({ schema }) => dialect.schema.isBinary(schema),
 			convert: convertBlob
 		},
 		{
@@ -2240,7 +2406,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 			schema: flattenedSchema,
 			name
 		}, rawOptions);
-		const nullable = dialect.isNullable(schema) || void 0;
+		const nullable = dialect.schema.isNullable(schema) || void 0;
 		const schemaCtx = {
 			schema,
 			name,
@@ -2317,7 +2483,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		const keys = [];
 		for (const key in schema.properties) {
 			const prop = schema.properties[key];
-			if (prop && !dialect.isReference(prop) && prop[flag]) keys.push(key);
+			if (prop && !dialect.schema.isReference(prop) && prop[flag]) keys.push(key);
 		}
 		return keys.length ? keys : null;
 	}
@@ -2334,14 +2500,14 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 		const content = allContentTypes.flatMap((ct) => {
 			const schema = getRequestSchema(document, operation, { contentType: ct });
 			if (!schema) return [];
-			return [{
+			return [ast.factory.createContent({
 				contentType: ct,
-				schema: ast.syncOptionality(parseSchema({
+				schema: ast.optionality(parseSchema({
 					schema,
 					name: requestBodyName
 				}, options), requestBodyMeta.required),
 				keysToOmit: collectPropertyKeysByFlag(schema, "readOnly")
-			}];
+			})];
 		});
 		const requestBody = content.length > 0 || requestBodyMeta.description ? {
 			description: requestBodyMeta.description,
@@ -2366,17 +2532,17 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 					keysToOmit: collectPropertyKeysByFlag(raw, "writeOnly")
 				};
 			};
-			const content = (ctx.contentType ? [ctx.contentType] : getResponseBodyContentTypes(document, operation, statusCode)).map((contentType) => ({
+			const content = (ctx.contentType ? [ctx.contentType] : getResponseBodyContentTypes(document, operation, statusCode)).map((contentType) => ast.factory.createContent({
 				contentType,
 				...parseEntrySchema(contentType)
 			}));
-			if (content.length === 0) content.push({
+			if (content.length === 0) content.push(ast.factory.createContent({
 				contentType: getRequestContentType({
 					document,
 					operation
 				}) || "application/json",
 				...parseEntrySchema(ctx.contentType)
-			});
+			}));
 			return ast.factory.createResponse({
 				statusCode,
 				description,
@@ -2384,7 +2550,7 @@ function createSchemaParser(ctx, dialect = oasDialect) {
 			});
 		});
 		const pathItem = document.paths?.[operation.path];
-		const pathItemDoc = pathItem && !dialect.isReference(pathItem) ? pathItem : void 0;
+		const pathItemDoc = pathItem && !dialect.schema.isReference(pathItem) ? pathItem : void 0;
 		const pickDoc = (key) => {
 			const own = operation.schema[key];
 			if (typeof own === "string") return own;
@@ -2469,36 +2635,6 @@ function visit(node, pointer) {
 //#endregion
 //#region src/stream.ts
 /**
-* Builds the deduplication plan from the already-parsed top-level schema nodes plus a
-* single extra parse pass over operations (so duplicates in request/response bodies are seen).
-*
-* Only enums and objects are candidates, and object shapes that reference a circular schema are
-* rejected to avoid hoisting recursive structures. Inline shapes reuse their context-derived
-* name (collision-resolved against existing component names). Shapes without a name stay inline.
-*/
-function createDedupePlan({ schemaNodes, operationNodes, schemaNames, circularNames }) {
-	const circularSchemas = new Set(circularNames);
-	const usedNames = new Set(schemaNames);
-	return ast.buildDedupePlan([...schemaNodes, ...operationNodes], {
-		isCandidate: (node) => {
-			if (node.type === "enum") return true;
-			if (node.type !== "object") return false;
-			if (node.name && circularSchemas.has(node.name)) return false;
-			return !containsCircularRef(node, { circularSchemas });
-		},
-		nameFor: (node) => {
-			const base = node.name;
-			if (!base) return null;
-			let name = base;
-			let counter = 2;
-			while (usedNames.has(name)) name = `${base}${counter++}`;
-			usedNames.add(name);
-			return name;
-		},
-		refFor: (name) => `${SCHEMA_REF_PREFIX}${name}`
-	});
-}
-/**
 * Reads the server URL from the document's `servers` array at `serverIndex`,
 * interpolating any `serverVariables` into the URL template.
 *
@@ -2567,18 +2703,17 @@ function preScan({ schemas, parseSchema, parseOperation, document, parserOptions
 			const operationNode = parseOperation(parserOptions, operation);
 			if (operationNode) operationNodes.push(operationNode);
 		}
-		dedupePlan = createDedupePlan({
-			schemaNodes: allNodes,
-			operationNodes,
-			schemaNames: Object.keys(schemas),
-			circularNames
+		const circularSchemas = new Set(circularNames);
+		const usedNames = new Set(Object.keys(schemas));
+		dedupePlan = oasDialect.dedupe.plan([...allNodes, ...operationNodes], {
+			circularSchemas,
+			usedNames
 		});
-		for (const definition of dedupePlan.hoisted) if (definition.type === "enum" && definition.name) enumNames.push(definition.name);
+		for (const definition of dedupePlan.extracted) if (definition.type === "enum" && definition.name) enumNames.push(definition.name);
 	}
-	const aliasNames = dedupePlan?.aliasNames;
 	return {
 		refAliasMap,
-		enumNames: aliasNames && aliasNames.size > 0 ? enumNames.filter((name) => !aliasNames.has(name)) : enumNames,
+		enumNames: dedupePlan ? enumNames.filter((name) => !dedupePlan.isAlias(name)) : enumNames,
 		circularNames,
 		discriminatorChildMap,
 		dedupePlan
@@ -2603,39 +2738,29 @@ function preScan({ schemas, parseSchema, parseOperation, document, parserOptions
 * ```
 */
 function createInputStream({ schemas, parseSchema, parseOperation, document, parserOptions, refAliasMap, discriminatorChildMap, dedupePlan, meta }) {
-	const rewriteTopLevelSchema = (node) => {
-		if (!dedupePlan) return node;
-		const canonical = dedupePlan.canonicalBySignature.get(ast.signatureOf(node));
-		if (canonical && canonical.name !== node.name) return ast.factory.createSchema({
-			type: "ref",
-			name: node.name ?? null,
-			ref: canonical.ref,
-			description: node.description,
-			deprecated: node.deprecated
-		});
-		return ast.applyDedupe(node, dedupePlan, true);
-	};
 	const schemasIterable = { [Symbol.asyncIterator]() {
 		return (async function* () {
-			if (dedupePlan) for (const definition of dedupePlan.hoisted) yield definition;
+			if (dedupePlan) for (const definition of dedupePlan.extracted) yield definition;
 			for (const [name, schema] of Object.entries(schemas)) {
-				if (dedupePlan?.aliasNames.has(name)) continue;
+				if (dedupePlan?.isAlias(name)) continue;
 				const alias = refAliasMap.get(name);
 				if (alias?.name && schemas[alias.name]) {
-					yield rewriteTopLevelSchema({
+					const aliasNode = {
 						...parseSchema({
 							schema: schemas[alias.name],
 							name: alias.name
 						}, parserOptions),
 						name
-					});
+					};
+					yield dedupePlan ? dedupePlan.applyTopLevel(aliasNode) : aliasNode;
 					continue;
 				}
 				const parsed = parseSchema({
 					schema,
 					name
 				}, parserOptions);
-				yield rewriteTopLevelSchema(discriminatorChildMap?.get(name) ? patchDiscriminatorNode(parsed, discriminatorChildMap.get(name)) : parsed);
+				const node = discriminatorChildMap?.get(name) ? patchDiscriminatorNode(parsed, discriminatorChildMap.get(name)) : parsed;
+				yield dedupePlan ? dedupePlan.applyTopLevel(node) : node;
 			}
 		})();
 	} };
@@ -2643,7 +2768,7 @@ function createInputStream({ schemas, parseSchema, parseOperation, document, par
 		return (async function* () {
 			for (const operation of getOperations(document)) {
 				const node = parseOperation(parserOptions, operation);
-				if (node) yield dedupePlan ? ast.applyDedupe(node, dedupePlan) : node;
+				if (node) yield dedupePlan ? dedupePlan.apply(node) : node;
 			}
 		})();
 	} };
@@ -2657,7 +2782,7 @@ function createInputStream({ schemas, parseSchema, parseOperation, document, par
 //#endregion
 //#region src/adapter.ts
 /**
-* Canonical adapter name for `@kubb/adapter-oas`. Used for driver lookups.
+* The `name` of `@kubb/adapter-oas`, used to identify this adapter in a Kubb config.
 */
 const adapterOasName = "oas";
 /**