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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/ast",
-  "version": "5.0.0-beta.1",
+  "version": "5.0.0-beta.2",
   "description": "Spec-agnostic AST layer for Kubb. Defines nodes, visitor pattern, and factory functions used across codegen plugins.",
   "keywords": [
     "ast",

package/src/index.ts

@@ -33,6 +33,7 @@ export type * from './types.ts'
 export {
   caseParams,
   collectReferencedSchemaNames,
+  collectUsedSchemaNames,
   containsCircularRef,
   createDiscriminantNode,
   createOperationParams,

package/src/utils.ts

@@ -669,7 +669,7 @@ export function combineImports(imports: Array<ImportNode>, exports: Array<Export
     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)].filter((item) => (typeof item === 'string' ? isUsed(item) : isUsed(item.name ?? item.propertyName)))
       if (!name.length) continue
 
       const key = pathTypeKey(path, isTypeOnly)
@@ -751,7 +751,19 @@ export function resolveRefName(node: SchemaNode | undefined): string | undefined
  * 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)
+ * }
+ * ```
  */
 export function collectReferencedSchemaNames(node: SchemaNode | undefined, out: Set<string> = new Set()): Set<string> {
   if (!node) return out
@@ -768,6 +780,66 @@ export function collectReferencedSchemaNames(node: SchemaNode | undefined, out:
   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
+ * ```
+ */
+export function collectUsedSchemaNames(operations: ReadonlyArray<OperationNode>, schemas: ReadonlyArray<SchemaNode>): Set<string> {
+  const schemaMap = new Map<string, SchemaNode>()
+  for (const schema of schemas) {
+    if (schema.name) {
+      schemaMap.set(schema.name, schema)
+    }
+  }
+
+  const result = new Set<string>()
+
+  function visitSchema(schema: SchemaNode): void {
+    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<SchemaNode>(op, { depth: 'shallow', schema: (node) => node })) {
+      visitSchema(schema)
+    }
+  }
+
+  return result
+}
+
 /**
  * Identifies all schemas that participate in circular dependency chains, including direct self-loops.
  *