@kubb/ast 5.0.0-beta.1 → 5.0.0-beta.3

package/dist/index.d.ts

@@ -3377,9 +3377,50 @@ declare function resolveRefName(node: SchemaNode | undefined): string | undefine
  * Refs are followed by name only — the resolved `node.schema` is not traversed inline.
  * Use this to determine schema dependencies, build reference graphs, or detect what schemas need to be emitted.
  *
- * @note Returns a Set of schema names for efficient membership testing.
+ * @example Collect refs from a single schema
+ * ```ts
+ * const names = collectReferencedSchemaNames(petSchema)
+ * // → Set { 'Category', 'Tag' }
+ * ```
+ *
+ * @example Accumulate refs from multiple schemas into one set
+ * ```ts
+ * const out = new Set<string>()
+ * for (const schema of schemas) {
+ *   collectReferencedSchemaNames(schema, out)
+ * }
+ * ```
  */
 declare function collectReferencedSchemaNames(node: SchemaNode | undefined, out?: Set<string>): Set<string>;
+/**
+ * Collects the names of all top-level schemas transitively used by a set of operations.
+ *
+ * An operation uses a schema when any of its parameters, request body content, or responses
+ * reference it — directly or indirectly through other named schemas.
+ * The walk is iterative and safe against reference cycles.
+ *
+ * Use this together with `include` filters to determine which schemas from `components/schemas`
+ * are reachable from the allowed operations, so that schemas used only by excluded operations
+ * are not generated.
+ *
+ * @example Only generate schemas referenced by included operations
+ * ```ts
+ * const includedOps = inputNode.operations.filter(op => resolver.resolveOptions(op, { options, include }) !== null)
+ * const allowed = collectUsedSchemaNames(includedOps, inputNode.schemas)
+ *
+ * for (const schema of inputNode.schemas) {
+ *   if (schema.name && !allowed.has(schema.name)) continue
+ *   // … generate schema
+ * }
+ * ```
+ *
+ * @example Check whether a specific schema is needed
+ * ```ts
+ * const allowed = collectUsedSchemaNames(includedOps, inputNode.schemas)
+ * allowed.has('OrderStatus') // false when no included operation references OrderStatus
+ * ```
+ */
+declare function collectUsedSchemaNames(operations: ReadonlyArray<OperationNode>, schemas: ReadonlyArray<SchemaNode>): Set<string>;
 /**
  * Identifies all schemas that participate in circular dependency chains, including direct self-loops.
  *
@@ -3406,5 +3447,5 @@ declare function containsCircularRef(node: SchemaNode | undefined, {
   excludeName?: string;
 }): boolean;
 //#endregion
-export { type ArraySchemaNode, type ArrowFunctionNode, AsyncVisitor, type BaseNode, type BreakNode, type CodeNode, CollectOptions, CollectVisitor, type ComplexSchemaType, type ConstNode, type DateSchemaNode, type DatetimeSchemaNode, DistributiveOmit, type EnumSchemaNode, type EnumValueNode, type ExportNode, type FileNode, type FormatStringSchemaNode, type FunctionNode, type FunctionNodeType, type FunctionParamNode, type FunctionParameterNode, type FunctionParametersNode, type HttpMethod, type HttpStatusCode, type ImportNode, InferSchema, InferSchemaNode, type InputMeta, type InputNode, type IntersectionSchemaNode, type Ipv4SchemaNode, type Ipv6SchemaNode, type JSDocNode, type JsxNode, type MediaType, Node, type NodeKind, type NumberSchemaNode, type ObjectSchemaNode, type OperationNode, OperationParamsResolver, type OutputNode, type ParameterGroupNode, type ParameterLocation, type ParameterNode, type ParamsTypeNode, ParentOf, ParserOptions, type PrimitiveSchemaType, Printer, PrinterFactoryOptions, PrinterPartial, type PropertyNode, RefMap, type RefSchemaNode, type ResponseNode, ScalarPrimitive, type ScalarSchemaNode, type ScalarSchemaType, type SchemaNode, type SchemaNodeByType, type SchemaType, type SourceNode, type SpecialSchemaType, type StatusCode, type StringSchemaNode, type TextNode, type TimeSchemaNode, TransformOptions, type TypeDeclarationNode, type TypeNode, type UnionSchemaNode, type UrlSchemaNode, UserFileNode, Visitor, VisitorContext, VisitorDepth, WalkOptions, caseParams, childName, collect, collectImports, collectReferencedSchemaNames, containsCircularRef, createArrowFunction, createBreak, createConst, createDiscriminantNode, createExport, createFile, createFunction, createFunctionParameter, createFunctionParameters, createImport, createInput, createJsx, createOperation, createOperationParams, createOutput, createParameter, createParameterGroup, createParamsType, createPrinterFactory, createProperty, createResponse, createSchema, createSource, createText, createType, definePrinter, enumPropName, extractRefName, extractStringsFromNodes, findCircularSchemas, findDiscriminator, httpMethods, isInputNode, isOperationNode, isOutputNode, isScalarPrimitive, isSchemaNode, isStringType, mediaTypes, mergeAdjacentObjects, narrowSchema, nodeKinds, resolveRefName, schemaTypes, setDiscriminatorEnum, setEnumName, simplifyUnion, syncOptionality, syncSchemaRef, transform, walk };
+export { type ArraySchemaNode, type ArrowFunctionNode, AsyncVisitor, type BaseNode, type BreakNode, type CodeNode, CollectOptions, CollectVisitor, type ComplexSchemaType, type ConstNode, type DateSchemaNode, type DatetimeSchemaNode, DistributiveOmit, type EnumSchemaNode, type EnumValueNode, type ExportNode, type FileNode, type FormatStringSchemaNode, type FunctionNode, type FunctionNodeType, type FunctionParamNode, type FunctionParameterNode, type FunctionParametersNode, type HttpMethod, type HttpStatusCode, type ImportNode, InferSchema, InferSchemaNode, type InputMeta, type InputNode, type IntersectionSchemaNode, type Ipv4SchemaNode, type Ipv6SchemaNode, type JSDocNode, type JsxNode, type MediaType, Node, type NodeKind, type NumberSchemaNode, type ObjectSchemaNode, type OperationNode, OperationParamsResolver, type OutputNode, type ParameterGroupNode, type ParameterLocation, type ParameterNode, type ParamsTypeNode, ParentOf, ParserOptions, type PrimitiveSchemaType, Printer, PrinterFactoryOptions, PrinterPartial, type PropertyNode, RefMap, type RefSchemaNode, type ResponseNode, ScalarPrimitive, type ScalarSchemaNode, type ScalarSchemaType, type SchemaNode, type SchemaNodeByType, type SchemaType, type SourceNode, type SpecialSchemaType, type StatusCode, type StringSchemaNode, type TextNode, type TimeSchemaNode, TransformOptions, type TypeDeclarationNode, type TypeNode, type UnionSchemaNode, type UrlSchemaNode, UserFileNode, Visitor, VisitorContext, VisitorDepth, WalkOptions, caseParams, childName, collect, collectImports, collectReferencedSchemaNames, collectUsedSchemaNames, containsCircularRef, createArrowFunction, createBreak, createConst, createDiscriminantNode, createExport, createFile, createFunction, createFunctionParameter, createFunctionParameters, createImport, createInput, createJsx, createOperation, createOperationParams, createOutput, createParameter, createParameterGroup, createParamsType, createPrinterFactory, createProperty, createResponse, createSchema, createSource, createText, createType, definePrinter, enumPropName, extractRefName, extractStringsFromNodes, findCircularSchemas, findDiscriminator, httpMethods, isInputNode, isOperationNode, isOutputNode, isScalarPrimitive, isSchemaNode, isStringType, mediaTypes, mergeAdjacentObjects, narrowSchema, nodeKinds, resolveRefName, schemaTypes, setDiscriminatorEnum, setEnumName, simplifyUnion, syncOptionality, syncSchemaRef, transform, walk };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1157,6 +1157,13 @@ function combineExports(exports) {
 function combineImports(imports, exports, source) {
 	const exportedNames = new Set(exports.flatMap((e) => Array.isArray(e.name) ? e.name : e.name ? [e.name] : []));
 	const isUsed = (importName) => !source || 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 result = [];
 	const namedByPath = /* @__PURE__ */ new Map();
 	const seen = /* @__PURE__ */ new Set();
@@ -1170,7 +1177,7 @@ function combineImports(imports, exports, source) {
 		const { path, isTypeOnly } = curr;
 		let { name } = curr;
 		if (Array.isArray(name)) {
-			name = [...new Set(name)].filter((item) => typeof item === "string" ? isUsed(item) : isUsed(item.propertyName));
+			name = [...new Set(name.map(canonicalizeName))].filter((item) => typeof item === "string" ? isUsed(item) : isUsed(item.name ?? item.propertyName));
 			if (!name.length) continue;
 			const key = pathTypeKey(path, isTypeOnly);
 			const existing = namedByPath.get(key);
@@ -1243,7 +1250,19 @@ function resolveRefName(node) {
 * Refs are followed by name only — the resolved `node.schema` is not traversed inline.
 * Use this to determine schema dependencies, build reference graphs, or detect what schemas need to be emitted.
 *
-* @note Returns a Set of schema names for efficient membership testing.
+* @example Collect refs from a single schema
+* ```ts
+* const names = collectReferencedSchemaNames(petSchema)
+* // → Set { 'Category', 'Tag' }
+* ```
+*
+* @example Accumulate refs from multiple schemas into one set
+* ```ts
+* const out = new Set<string>()
+* for (const schema of schemas) {
+*   collectReferencedSchemaNames(schema, out)
+* }
+* ```
 */
 function collectReferencedSchemaNames(node, out = /* @__PURE__ */ new Set()) {
 	if (!node) return out;
@@ -1256,6 +1275,52 @@ function collectReferencedSchemaNames(node, out = /* @__PURE__ */ new Set()) {
 	return out;
 }
 /**
+* Collects the names of all top-level schemas transitively used by a set of operations.
+*
+* An operation uses a schema when any of its parameters, request body content, or responses
+* reference it — directly or indirectly through other named schemas.
+* The walk is iterative and safe against reference cycles.
+*
+* Use this together with `include` filters to determine which schemas from `components/schemas`
+* are reachable from the allowed operations, so that schemas used only by excluded operations
+* are not generated.
+*
+* @example Only generate schemas referenced by included operations
+* ```ts
+* const includedOps = inputNode.operations.filter(op => resolver.resolveOptions(op, { options, include }) !== null)
+* const allowed = collectUsedSchemaNames(includedOps, inputNode.schemas)
+*
+* for (const schema of inputNode.schemas) {
+*   if (schema.name && !allowed.has(schema.name)) continue
+*   // … generate schema
+* }
+* ```
+*
+* @example Check whether a specific schema is needed
+* ```ts
+* const allowed = collectUsedSchemaNames(includedOps, inputNode.schemas)
+* allowed.has('OrderStatus') // false when no included operation references OrderStatus
+* ```
+*/
+function collectUsedSchemaNames(operations, schemas) {
+	const schemaMap = /* @__PURE__ */ new Map();
+	for (const schema of schemas) if (schema.name) schemaMap.set(schema.name, schema);
+	const result = /* @__PURE__ */ new Set();
+	function visitSchema(schema) {
+		const directRefs = collectReferencedSchemaNames(schema);
+		for (const name of directRefs) if (!result.has(name)) {
+			result.add(name);
+			const namedSchema = schemaMap.get(name);
+			if (namedSchema) visitSchema(namedSchema);
+		}
+	}
+	for (const op of operations) for (const schema of collect(op, {
+		depth: "shallow",
+		schema: (node) => node
+	})) visitSchema(schema);
+	return result;
+}
+/**
 * Identifies all schemas that participate in circular dependency chains, including direct self-loops.
 *
 * Returns a Set of schema names with circular dependencies. Use this to wrap recursive schema positions
@@ -2133,6 +2198,6 @@ function setEnumName(propNode, parentName, propName, enumSuffix) {
 	return propNode;
 }
 //#endregion
-export { caseParams, childName, collect, collectImports, collectReferencedSchemaNames, containsCircularRef, createArrowFunction, createBreak, createConst, createDiscriminantNode, createExport, createFile, createFunction, createFunctionParameter, createFunctionParameters, createImport, createInput, createJsx, createOperation, createOperationParams, createOutput, createParameter, createParameterGroup, createParamsType, createPrinterFactory, createProperty, createResponse, createSchema, createSource, createText, createType, definePrinter, enumPropName, extractRefName, extractStringsFromNodes, findCircularSchemas, findDiscriminator, httpMethods, isInputNode, isOperationNode, isOutputNode, isScalarPrimitive, isSchemaNode, isStringType, mediaTypes, mergeAdjacentObjects, narrowSchema, nodeKinds, resolveRefName, schemaTypes, setDiscriminatorEnum, setEnumName, simplifyUnion, syncOptionality, syncSchemaRef, transform, walk };
+export { caseParams, childName, collect, collectImports, collectReferencedSchemaNames, collectUsedSchemaNames, containsCircularRef, createArrowFunction, createBreak, createConst, createDiscriminantNode, createExport, createFile, createFunction, createFunctionParameter, createFunctionParameters, createImport, createInput, createJsx, createOperation, createOperationParams, createOutput, createParameter, createParameterGroup, createParamsType, createPrinterFactory, createProperty, createResponse, createSchema, createSource, createText, createType, definePrinter, enumPropName, extractRefName, extractStringsFromNodes, findCircularSchemas, findDiscriminator, httpMethods, isInputNode, isOperationNode, isOutputNode, isScalarPrimitive, isSchemaNode, isStringType, mediaTypes, mergeAdjacentObjects, narrowSchema, nodeKinds, resolveRefName, schemaTypes, setDiscriminatorEnum, setEnumName, simplifyUnion, syncOptionality, syncSchemaRef, transform, walk };
 
 //# sourceMappingURL=index.js.map