@kubb/ast 5.0.0-beta.75 → 5.0.0-beta.9

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@kubb/ast",
-  "version": "5.0.0-beta.75",
-  "description": "Spec-agnostic AST layer for Kubb. Defines nodes, visitor pattern, and factory functions used across codegen plugins.",
+  "version": "5.0.0-beta.9",
+  "description": "Spec-agnostic AST layer for Kubb. Defines the node tree, visitor pattern, factory functions, and type guards used across all code generation plugins.",
   "keywords": [
     "ast",
     "codegen",
     "kubb",
-    "openapi",
     "typescript"
   ],
   "license": "MIT",
@@ -40,7 +39,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "devDependencies": {
-    "@types/node": "^25.6.0",
+    "@types/node": "^22.19.19",
     "@internals/utils": "0.0.0"
   },
   "engines": {

package/src/index.ts

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

package/src/utils.ts

@@ -139,14 +139,14 @@ export type OperationParamsResolver = {
    * @example Individual path parameter name
    * `resolver.resolveParamName(node, param) // → 'DeletePetPathPetId'`
    */
-  resolveParamName(node: OperationNode, param: ParameterNode): string
+  resolveParamName(this: OperationParamsResolver, node: OperationNode, param: ParameterNode): string
   /**
    * Resolves the request body type name.
    *
    * @example Request body type name
    * `resolver.resolveDataName(node) // → 'CreatePetData'`
    */
-  resolveDataName(node: OperationNode): string
+  resolveDataName(this: OperationParamsResolver, node: OperationNode): string
   /**
    * Resolves the grouped path parameters type name.
    * When the return value equals `resolveParamName`, no indexed access is emitted.
@@ -154,7 +154,7 @@ export type OperationParamsResolver = {
    * @example Grouped path params type name
    * `resolver.resolvePathParamsName(node, param) // → 'DeletePetPathParams'`
    */
-  resolvePathParamsName(node: OperationNode, param: ParameterNode): string
+  resolvePathParamsName(this: OperationParamsResolver, node: OperationNode, param: ParameterNode): string
   /**
    * Resolves the grouped query parameters type name.
    * When the return value equals `resolveParamName`, an inline struct type is emitted instead.
@@ -162,7 +162,7 @@ export type OperationParamsResolver = {
    * @example Grouped query params type name
    * `resolver.resolveQueryParamsName(node, param) // → 'FindPetsByStatusQueryParams'`
    */
-  resolveQueryParamsName(node: OperationNode, param: ParameterNode): string
+  resolveQueryParamsName(this: OperationParamsResolver, node: OperationNode, param: ParameterNode): string
   /**
    * Resolves the grouped header parameters type name.
    * When the return value equals `resolveParamName`, an inline struct type is emitted instead.
@@ -170,7 +170,7 @@ export type OperationParamsResolver = {
    * @example Grouped header params type name
    * `resolver.resolveHeaderParamsName(node, param) // → 'DeletePetHeaderParams'`
    */
-  resolveHeaderParamsName(node: OperationNode, param: ParameterNode): string
+  resolveHeaderParamsName(this: OperationParamsResolver, node: OperationNode, param: ParameterNode): string
 }
 
 /**
@@ -652,6 +652,16 @@ export function combineImports(imports: Array<ImportNode>, exports: Array<Export
   const exportedNames = new Set(exports.flatMap((e) => (Array.isArray(e.name) ? e.name : e.name ? [e.name] : [])))
   const isUsed = (importName: string): boolean => !source || source.includes(importName) || exportedNames.has(importName)
 
+  // Memoize object import names so the same logical (propertyName, name) pair always
+  // reuses the same object reference — Set-based deduplication then works correctly.
+  const importNameMemo = new Map<string, { propertyName: string; name?: string }>()
+  const canonicalizeName = (n: string | { propertyName: string; name?: string }): string | { propertyName: string; name?: string } => {
+    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: Array<ImportNode> = []
   // Accumulates array-named imports keyed by `path:isTypeOnly` for name-merging
   const namedByPath = new Map<string, ImportNode>()
@@ -669,7 +679,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.map(canonicalizeName))].filter((item) => (typeof item === 'string' ? isUsed(item) : isUsed(item.name ?? item.propertyName)))
       if (!name.length) continue
 
       const key = pathTypeKey(path, isTypeOnly)
@@ -751,7 +761,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 +790,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.
  *