@kubb/ast 5.0.0-beta.6 → 5.0.0-beta.61

package/dist/visitor-DpKZ9Tk0.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"visitor-DpKZ9Tk0.cjs","names":["pascalCase","createSchema","inputDef","outputDef","operationDef","requestBodyDef","contentDef","responseDef","schemaDef","propertyDef","parameterDef","functionParameterDef","functionParametersDef","typeLiteralDef","indexedAccessTypeDef","objectBindingPatternDef","constDef","typeDef","functionDef","arrowFunctionDef","textDef","breakDef","jsxDef","importDef","exportDef","sourceDef","fileDef"],"sources":["../src/constants.ts","../src/guards.ts","../src/utils/refs.ts","../src/registry.ts","../src/visitor.ts"],"sourcesContent":["import type { HttpMethod } from './nodes/operation.ts'\nimport type { SchemaType } from './nodes/schema.ts'\n\n/**\n * Traversal depth for AST visitor utilities.\n *\n * - `'shallow'` visits only the immediate node, skipping children.\n * - `'deep'` recursively visits all descendant nodes.\n */\nexport type VisitorDepth = 'shallow' | 'deep'\n\nexport const visitorDepths = {\n  shallow: 'shallow',\n  deep: 'deep',\n} as const satisfies Record<VisitorDepth, VisitorDepth>\n\n/**\n * Schema type discriminators used by all AST schema nodes.\n *\n * Each value is a stable discriminator across the AST (for example `schema.type === schemaTypes.object`).\n * Call `isScalarPrimitive()` to check for the scalar types.\n */\nexport const schemaTypes = {\n  /**\n   * Text value.\n   */\n  string: 'string',\n  /**\n   * Floating-point number (`float`, `double`).\n   */\n  number: 'number',\n  /**\n   * Whole number (`int32`). Use `bigint` for `int64`.\n   */\n  integer: 'integer',\n  /**\n   * 64-bit integer (`int64`). Only used when `integerType` is set to `'bigint'`.\n   */\n  bigint: 'bigint',\n  /**\n   * Boolean value.\n   */\n  boolean: 'boolean',\n  /**\n   * Explicit null value.\n   */\n  null: 'null',\n  /**\n   * Any value (no type restriction).\n   */\n  any: 'any',\n  /**\n   * Unknown value (must be narrowed before usage).\n   */\n  unknown: 'unknown',\n  /**\n   * No return value (`void`).\n   */\n  void: 'void',\n  /**\n   * Object with named properties.\n   */\n  object: 'object',\n  /**\n   * Sequential list of items.\n   */\n  array: 'array',\n  /**\n   * Fixed-length list with position-specific items.\n   */\n  tuple: 'tuple',\n  /**\n   * \"One of\" multiple schema members.\n   */\n  union: 'union',\n  /**\n   * \"All of\" multiple schema members.\n   */\n  intersection: 'intersection',\n  /**\n   * Enum schema.\n   */\n  enum: 'enum',\n  /**\n   * Reference to another schema.\n   */\n  ref: 'ref',\n  /**\n   * Calendar date (for example `2026-03-24`).\n   */\n  date: 'date',\n  /**\n   * Date-time value (for example `2026-03-24T09:00:00Z`).\n   */\n  datetime: 'datetime',\n  /**\n   * Time-only value (for example `09:00:00`).\n   */\n  time: 'time',\n  /**\n   * UUID value.\n   */\n  uuid: 'uuid',\n  /**\n   * Email address value.\n   */\n  email: 'email',\n  /**\n   * URL value.\n   */\n  url: 'url',\n  /**\n   * IPv4 address value.\n   */\n  ipv4: 'ipv4',\n  /**\n   * IPv6 address value.\n   */\n  ipv6: 'ipv6',\n  /**\n   * Binary/blob value.\n   */\n  blob: 'blob',\n  /**\n   * Impossible value (`never`).\n   */\n  never: 'never',\n} as const satisfies Record<SchemaType, SchemaType>\n\nexport type ScalarPrimitive = 'string' | 'number' | 'integer' | 'bigint' | 'boolean'\n\n/**\n * Scalar primitive schema types used for union simplification and type narrowing.\n */\nconst SCALAR_PRIMITIVE_TYPES = new Set<ScalarPrimitive>(['string', 'number', 'integer', 'bigint', 'boolean'])\n\n/**\n * Returns `true` when `type` is a scalar primitive that can be assigned without wrapping\n * (for example `string | number | boolean`).\n */\nexport function isScalarPrimitive(type: string): type is ScalarPrimitive {\n  return SCALAR_PRIMITIVE_TYPES.has(type as ScalarPrimitive)\n}\n\n/**\n * HTTP method identifiers used by operation nodes.\n */\nexport const httpMethods = {\n  get: 'GET',\n  post: 'POST',\n  put: 'PUT',\n  patch: 'PATCH',\n  delete: 'DELETE',\n  head: 'HEAD',\n  options: 'OPTIONS',\n  trace: 'TRACE',\n} as const satisfies Record<Lowercase<HttpMethod>, HttpMethod>\n\n/**\n * Default concurrency limit for the `walk()` traversal utility.\n *\n * Set to 30 to balance I/O-bound resolver parallelism against event-loop and memory pressure\n * during large spec traversals. Override it for different hardware constraints.\n *\n * @example\n * ```ts\n * import { walk, WALK_CONCURRENCY } from '@kubb/ast'\n *\n * walk(root, { concurrency: WALK_CONCURRENCY, root: () => {} })\n * ```\n */\nexport const WALK_CONCURRENCY = 30\n\n/**\n * Number of spaces in one indentation level when assembling multi-line code as strings.\n * Set to 2, 3, … to change the indent width used by `buildObject`/`buildList`.\n */\nconst INDENT_SIZE = 2\n\n/**\n * One indentation level, derived from {@link INDENT_SIZE}.\n */\nexport const INDENT = Array.from({ length: INDENT_SIZE }, () => ' ').join('')\n","import type { HttpOperationNode, OperationNode, SchemaNode, SchemaNodeByType } from './nodes/index.ts'\n\n/**\n * Narrows a `SchemaNode` to the variant that matches `type`.\n *\n * @example\n * ```ts\n * const schema = createSchema({ type: 'string' })\n * const stringNode = narrowSchema(schema, 'string') // StringSchemaNode | null\n * ```\n */\nexport function narrowSchema<T extends SchemaNode['type']>(node: SchemaNode | undefined, type: T): SchemaNodeByType[T] | null {\n  return node?.type === type ? (node as SchemaNodeByType[T]) : null\n}\n\n/**\n * Narrows an `OperationNode` to an `HttpOperationNode` so `method` and `path` are present.\n *\n * @example\n * ```ts\n * if (isHttpOperationNode(node)) {\n *   console.log(node.method, node.path)\n * }\n * ```\n */\nexport function isHttpOperationNode(node: OperationNode): node is HttpOperationNode {\n  return node.protocol === 'http' || (node.method !== undefined && node.path !== undefined)\n}\n","import { pascalCase } from '@internals/utils'\nimport { narrowSchema } from '../guards.ts'\nimport type { OperationNode, ParameterNode, SchemaNode } from '../nodes/index.ts'\nimport { createSchema, type SchemaType } from '../nodes/schema.ts'\nimport type { OperationParamsResolver, ParamGroupType } from './operationParams.ts'\n\nconst plainStringTypes = new Set<SchemaType>(['string', 'uuid', 'email', 'url', 'datetime'] as const)\n\n/**\n * Returns the last path segment of a reference string.\n *\n * @example\n * ```ts\n * extractRefName('#/components/schemas/Pet') // 'Pet'\n * ```\n */\nexport function extractRefName(ref: string): string {\n  return ref.split('/').at(-1) ?? ref\n}\n\n/**\n * Resolves the schema name of a ref node, falling back through `ref` → `name` → nested `schema.name`.\n *\n * Returns `null` for non-ref nodes or when no name resolves.\n *\n * @example\n * ```ts\n * resolveRefName({ kind: 'Schema', type: 'ref', ref: '#/components/schemas/Pet' })\n * // => 'Pet'\n * ```\n */\nexport function resolveRefName(node: SchemaNode | undefined): string | null {\n  if (!node || node.type !== 'ref') return null\n  if (node.ref) return extractRefName(node.ref) ?? node.name ?? node.schema?.name ?? null\n\n  return node.name ?? node.schema?.name ?? null\n}\n\n/**\n * Builds a PascalCase child schema name by joining a parent name and property name.\n * Returns `null` when there is no parent to nest under.\n *\n * @example\n * ```ts\n * childName('Order', 'shipping_address') // 'OrderShippingAddress'\n * childName(undefined, 'params')         // null\n * ```\n */\nexport function childName(parentName: string | null | undefined, propName: string): string | null {\n  return parentName ? pascalCase([parentName, propName].join(' ')) : null\n}\n\n/**\n * Builds a PascalCase enum name from the parent name, property name, and a suffix, skipping any\n * empty parts.\n *\n * @example\n * ```ts\n * enumPropName('Order', 'status', 'enum') // 'OrderStatusEnum'\n * ```\n */\nexport function enumPropName(parentName: string | null | undefined, propName: string, enumSuffix: string): string {\n  return pascalCase([parentName, propName, enumSuffix].filter(Boolean).join(' '))\n}\n\n/**\n * Merges a ref node with its resolved schema, giving usage-site fields precedence.\n *\n * Usage-site fields (`description`, `readOnly`, `nullable`, `deprecated`) on the ref node override\n * the same fields in the resolved `node.schema`. Non-ref nodes are returned unchanged.\n *\n * @example\n * ```ts\n * const ref = createSchema({ type: 'ref', ref: '#/components/schemas/Pet', description: 'A cute pet' })\n * const merged = syncSchemaRef(ref) // merges with resolved Pet schema\n * ```\n */\nexport function syncSchemaRef(node: SchemaNode): SchemaNode {\n  const ref = narrowSchema(node, 'ref')\n\n  if (!ref) return node\n  if (!ref.schema) return node\n\n  const { kind: _kind, type: _type, name: _name, ref: _ref, schema: _schema, ...overrides } = ref\n\n  // Filter out undefined override values so they don't shadow the resolved schema's fields.\n  const definedOverrides = Object.fromEntries(Object.entries(overrides).filter(([, v]) => v !== undefined))\n\n  return createSchema({ ...ref.schema, ...definedOverrides })\n}\n\n/**\n * Type guard that returns `true` when a schema emits as a plain `string` type.\n *\n * Covers `string`, `uuid`, `email`, `url`, and `datetime` types. For `date` and `time`\n * types, returns `true` only when `representation` is `'string'` rather than `'date'`.\n */\nexport function isStringType(node: SchemaNode): boolean {\n  if (plainStringTypes.has(node.type)) {\n    return true\n  }\n\n  const temporal = narrowSchema(node, 'date') ?? narrowSchema(node, 'time')\n  if (temporal) {\n    return temporal.representation !== 'date'\n  }\n\n  return false\n}\n\n/**\n * Derives a {@link ParamGroupType} for a query or header group from the resolver.\n *\n * Returns `null` when there is no resolver, no params, or the group name equals the\n * individual param name (so there is no real group to emit).\n */\nexport function resolveGroupType({\n  node,\n  params,\n  group,\n  resolver,\n}: {\n  node: OperationNode\n  params: Array<ParameterNode>\n  group: 'query' | 'header'\n  resolver: OperationParamsResolver | undefined\n}): ParamGroupType | null {\n  if (!resolver || !params.length) {\n    return null\n  }\n  const firstParam = params[0]!\n  const groupMethod = group === 'query' ? resolver.resolveQueryParamsName : resolver.resolveHeaderParamsName\n  const groupName = groupMethod.call(resolver, node, firstParam)\n  if (groupName === resolver.resolveParamName(node, firstParam)) {\n    return null\n  }\n  return { type: groupName, optional: params.every((p) => !p.required) }\n}\n","import type { NodeDef } from './node.ts'\nimport { arrowFunctionDef, breakDef, constDef, functionDef, jsxDef, textDef, typeDef } from './nodes/code.ts'\nimport { contentDef } from './nodes/content.ts'\nimport { exportDef, fileDef, importDef, sourceDef } from './nodes/file.ts'\nimport { functionParameterDef, functionParametersDef, indexedAccessTypeDef, objectBindingPatternDef, typeLiteralDef } from './nodes/function.ts'\nimport { inputDef } from './nodes/input.ts'\nimport { operationDef } from './nodes/operation.ts'\nimport { outputDef } from './nodes/output.ts'\nimport { parameterDef } from './nodes/parameter.ts'\nimport { propertyDef } from './nodes/property.ts'\nimport { requestBodyDef } from './nodes/requestBody.ts'\nimport { responseDef } from './nodes/response.ts'\nimport { schemaDef } from './nodes/schema.ts'\n\n// Surface every def from one place so the package barrel re-exports them with `export * from './registry.ts'`.\n// Adding a node means adding its `defineNode` to a `nodes/*.ts` file and listing it in `nodeDefs` below, nothing else.\nexport {\n  arrowFunctionDef,\n  breakDef,\n  constDef,\n  contentDef,\n  exportDef,\n  fileDef,\n  functionDef,\n  functionParameterDef,\n  functionParametersDef,\n  importDef,\n  indexedAccessTypeDef,\n  inputDef,\n  jsxDef,\n  objectBindingPatternDef,\n  operationDef,\n  outputDef,\n  parameterDef,\n  propertyDef,\n  requestBodyDef,\n  responseDef,\n  schemaDef,\n  sourceDef,\n  textDef,\n  typeDef,\n  typeLiteralDef,\n}\n\n/**\n * Every node definition. Adding a node means adding its `defineNode` to one\n * `nodes/*.ts` file and listing it here. The visitor tables in `visitor.ts` derive from it.\n */\nexport const nodeDefs = [\n  inputDef,\n  outputDef,\n  operationDef,\n  requestBodyDef,\n  contentDef,\n  responseDef,\n  schemaDef,\n  propertyDef,\n  parameterDef,\n  functionParameterDef,\n  functionParametersDef,\n  typeLiteralDef,\n  indexedAccessTypeDef,\n  objectBindingPatternDef,\n  constDef,\n  typeDef,\n  functionDef,\n  arrowFunctionDef,\n  textDef,\n  breakDef,\n  jsxDef,\n  importDef,\n  exportDef,\n  sourceDef,\n  fileDef,\n] satisfies ReadonlyArray<NodeDef>\n","import type { VisitorDepth } from './constants.ts'\nimport { visitorDepths, WALK_CONCURRENCY } from './constants.ts'\nimport type { NodeDef } from './node.ts'\nimport type {\n  ContentNode,\n  InputNode,\n  Node,\n  NodeKind,\n  OperationNode,\n  OutputNode,\n  ParameterNode,\n  PropertyNode,\n  RequestBodyNode,\n  ResponseNode,\n  SchemaNode,\n} from './nodes/index.ts'\nimport { nodeDefs } from './registry.ts'\n\n/**\n * Child node fields per node kind, in traversal order (Babel's `VISITOR_KEYS`).\n * Derived from each definition's `children`.\n */\nconst VISITOR_KEYS = Object.fromEntries(nodeDefs.flatMap((def) => (def.children ? [[def.kind, def.children] as const] : []))) as Partial<\n  Record<NodeKind, ReadonlyArray<string>>\n>\n\n/**\n * Maps a node kind to the matching visitor callback name. Derived from each\n * definition's `visitorKey`.\n */\nconst VISITOR_KEY_BY_KIND = Object.fromEntries(nodeDefs.flatMap((def) => (def.visitorKey ? [[def.kind, def.visitorKey] as const] : []))) as Partial<\n  Record<NodeKind, NonNullable<NodeDef['visitorKey']>>\n>\n\n/**\n * Per-kind builders rerun after children are rebuilt. Derived from each\n * definition's `rebuild` flag.\n */\nconst nodeRebuilders = Object.fromEntries(\n  nodeDefs.flatMap((def) => (def.rebuild ? [[def.kind, def.create as unknown as (node: Node) => Node] as const] : [])),\n) as Partial<Record<NodeKind, (node: Node) => Node>>\n\n/**\n * Creates a small async concurrency limiter.\n *\n * At most `concurrency` tasks are in flight at once. Extra tasks are queued.\n *\n * @example\n * ```ts\n * const limit = createLimit(2)\n * for (const task of [taskA, taskB, taskC]) {\n *   await limit(() => task())\n * }\n * // only 2 tasks run at the same time\n * ```\n */\nfunction createLimit(concurrency: number) {\n  let active = 0\n  const queue: Array<() => void> = []\n\n  function next() {\n    if (active < concurrency && queue.length > 0) {\n      active++\n      queue.shift()!()\n    }\n  }\n\n  return function limit<T>(fn: () => Promise<T> | T): Promise<T> {\n    return new Promise<T>((resolve, reject) => {\n      queue.push(() => {\n        Promise.resolve(fn())\n          .then(resolve, reject)\n          .finally(() => {\n            active--\n            next()\n          })\n      })\n      next()\n    })\n  }\n}\n\ntype LimitFn = ReturnType<typeof createLimit>\n\n/**\n * Ordered mapping of `[NodeType, ParentType]` pairs.\n *\n * `ParentOf` uses this map to find parent types.\n */\ntype ParentNodeMap = [\n  [InputNode, undefined],\n  [OutputNode, undefined],\n  [OperationNode, InputNode],\n  [RequestBodyNode, OperationNode],\n  [ContentNode, RequestBodyNode | ResponseNode],\n  [SchemaNode, InputNode | ContentNode | SchemaNode | PropertyNode | ParameterNode],\n  [PropertyNode, SchemaNode],\n  [ParameterNode, OperationNode],\n  [ResponseNode, OperationNode],\n]\n\n/**\n * Resolves the parent node type for a given AST node type.\n *\n * Visitor context relies on this so `ctx.parent` is typed for each callback.\n *\n * @example\n * ```ts\n * type InputParent = ParentOf<InputNode>\n * // undefined\n * ```\n *\n * @example\n * ```ts\n * type PropertyParent = ParentOf<PropertyNode>\n * // SchemaNode\n * ```\n *\n * @example\n * ```ts\n * type SchemaParent = ParentOf<SchemaNode>\n * // InputNode | OperationNode | SchemaNode | PropertyNode | ParameterNode | ResponseNode\n * ```\n */\nexport type ParentOf<T extends Node, TEntries extends ReadonlyArray<[Node, unknown]> = ParentNodeMap> = TEntries extends [\n  infer TEntry extends [Node, unknown],\n  ...infer TRest extends ReadonlyArray<[Node, unknown]>,\n]\n  ? T extends TEntry[0]\n    ? TEntry[1]\n    : ParentOf<T, TRest>\n  : Node\n\n/**\n * Traversal context passed as the second argument to every visitor callback.\n * `parent` is typed from the current node type.\n *\n * @example\n * ```ts\n * const visitor: Visitor = {\n *   schema(node, { parent }) {\n *     // parent type is narrowed by node kind\n *   },\n * }\n * ```\n */\nexport type VisitorContext<T extends Node = Node> = {\n  /**\n   * Parent node of the currently visited node.\n   * For `InputNode`, this is `undefined`.\n   */\n  parent?: ParentOf<T>\n}\n\n/**\n * Synchronous visitor consumed by `transform`. Each optional callback runs\n * for the matching node type. Return a new node to replace it, or `undefined`\n * to leave it untouched.\n *\n * Plugins typically expose `transformer` so users can supply a `Visitor` that\n * rewrites the AST before printing.\n *\n * @example Prefix every operationId\n * ```ts\n * const visitor: Visitor = {\n *   operation(node) {\n *     return { ...node, operationId: `api_${node.operationId}` }\n *   },\n * }\n * ```\n *\n * @example Strip schema descriptions\n * ```ts\n * const visitor: Visitor = {\n *   schema(node) {\n *     return { ...node, description: undefined }\n *   },\n * }\n * ```\n */\nexport type Visitor = {\n  input?(node: InputNode, context: VisitorContext<InputNode>): undefined | null | InputNode\n  output?(node: OutputNode, context: VisitorContext<OutputNode>): undefined | null | OutputNode\n  operation?(node: OperationNode, context: VisitorContext<OperationNode>): undefined | null | OperationNode\n  schema?(node: SchemaNode, context: VisitorContext<SchemaNode>): undefined | null | SchemaNode\n  property?(node: PropertyNode, context: VisitorContext<PropertyNode>): undefined | null | PropertyNode\n  parameter?(node: ParameterNode, context: VisitorContext<ParameterNode>): undefined | null | ParameterNode\n  response?(node: ResponseNode, context: VisitorContext<ResponseNode>): undefined | null | ResponseNode\n}\n\n/**\n * A visitor callback result that may be sync or async.\n */\ntype MaybePromise<T> = T | Promise<T>\n\n/**\n * Async visitor for `walk`. Synchronous `Visitor` objects are compatible.\n *\n * @example\n * ```ts\n * const visitor: AsyncVisitor = {\n *   async operation(node) {\n *     await Promise.resolve(node.operationId)\n *   },\n * }\n * ```\n */\ntype AsyncVisitor = {\n  input?(node: InputNode, context: VisitorContext<InputNode>): MaybePromise<undefined | null | InputNode>\n  output?(node: OutputNode, context: VisitorContext<OutputNode>): MaybePromise<undefined | null | OutputNode>\n  operation?(node: OperationNode, context: VisitorContext<OperationNode>): MaybePromise<undefined | null | OperationNode>\n  schema?(node: SchemaNode, context: VisitorContext<SchemaNode>): MaybePromise<undefined | null | SchemaNode>\n  property?(node: PropertyNode, context: VisitorContext<PropertyNode>): MaybePromise<undefined | null | PropertyNode>\n  parameter?(node: ParameterNode, context: VisitorContext<ParameterNode>): MaybePromise<undefined | null | ParameterNode>\n  response?(node: ResponseNode, context: VisitorContext<ResponseNode>): MaybePromise<undefined | null | ResponseNode>\n}\n\n/**\n * Visitor used by `collect`.\n *\n * @example\n * ```ts\n * const visitor: CollectVisitor<string> = {\n *   operation(node) {\n *     return node.operationId\n *   },\n * }\n * ```\n */\ntype CollectVisitor<T> = {\n  input?(node: InputNode, context: VisitorContext<InputNode>): T | null | undefined\n  output?(node: OutputNode, context: VisitorContext<OutputNode>): T | null | undefined\n  operation?(node: OperationNode, context: VisitorContext<OperationNode>): T | null | undefined\n  schema?(node: SchemaNode, context: VisitorContext<SchemaNode>): T | null | undefined\n  property?(node: PropertyNode, context: VisitorContext<PropertyNode>): T | null | undefined\n  parameter?(node: ParameterNode, context: VisitorContext<ParameterNode>): T | null | undefined\n  response?(node: ResponseNode, context: VisitorContext<ResponseNode>): T | null | undefined\n}\n\n/**\n * Options for `transform`.\n *\n * @example\n * ```ts\n * const options: TransformOptions = { depth: 'deep', schema: (node) => node }\n * ```\n *\n * @example\n * ```ts\n * // Only transform the current node, not nested children\n * const options: TransformOptions = { depth: 'shallow', schema: (node) => node }\n * ```\n */\nexport type TransformOptions = Visitor & {\n  /**\n   * Traversal depth.\n   * @default 'deep'\n   */\n  depth?: VisitorDepth\n  /**\n   * Internal parent override used during recursion.\n   */\n  parent?: Node\n}\n\n/**\n * Options for `walk`.\n *\n * @example\n * ```ts\n * const options: WalkOptions = { depth: 'deep', concurrency: 10, root: () => {} }\n * ```\n */\nexport type WalkOptions = AsyncVisitor & {\n  /**\n   * Traversal depth.\n   * @default 'deep'\n   */\n  depth?: VisitorDepth\n  /**\n   * Maximum number of sibling nodes visited concurrently.\n   * @default 30\n   */\n  concurrency?: number\n}\n\n/**\n * Options for `collect`.\n *\n * @example\n * ```ts\n * const options: CollectOptions<string> = { depth: 'shallow', schema: () => undefined }\n * ```\n */\nexport type CollectOptions<T> = CollectVisitor<T> & {\n  /**\n   * Traversal depth.\n   * @default 'deep'\n   */\n  depth?: VisitorDepth\n  /**\n   * Internal parent override used during recursion.\n   */\n  parent?: Node\n}\n\nconst visitorKeysByKind = VISITOR_KEYS as Record<string, ReadonlyArray<string> | undefined>\n\n/**\n * Returns `true` when `value` is an AST node (an object carrying a `kind`).\n */\nfunction isNode(value: unknown): value is Node {\n  return typeof value === 'object' && value !== null && 'kind' in value\n}\n\n/**\n * Returns the immediate traversable children of `node` based on {@link VISITOR_KEYS}.\n *\n * `Schema` children are only included when `recurse` is `true`. Shallow mode skips them.\n *\n * @example\n * ```ts\n * const children = getChildren(operationNode, true)\n * // returns parameters, the request body, and responses\n * ```\n */\nfunction* getChildren(node: Node, recurse: boolean): Generator<Node, void, undefined> {\n  if (node.kind === 'Schema' && !recurse) return\n\n  const keys = visitorKeysByKind[node.kind]\n  if (!keys) return\n\n  const record = node as unknown as Record<string, unknown>\n  for (const key of keys) {\n    const value = record[key]\n    if (Array.isArray(value)) {\n      for (const item of value) if (isNode(item)) yield item\n    } else if (isNode(value)) {\n      yield value\n    }\n  }\n}\n\n/**\n * Runs the visitor callback that matches `node.kind` with the traversal\n * context. The result is a replacement node, a collected value, or `undefined`\n * when no callback is registered for the kind.\n *\n * Shared by `walk`, `transform`, and `collectLazy` so node-kind dispatch lives\n * in one place. `TResult` is the caller's expected return: the same node type\n * for `transform`, the collected value type for `collectLazy`, ignored for `walk`.\n */\nfunction applyVisitor<TResult>(node: Node, visitor: Visitor | AsyncVisitor | CollectVisitor<unknown>, parent: Node | undefined): TResult | null | undefined {\n  const key = VISITOR_KEY_BY_KIND[node.kind]\n  if (!key) return undefined\n\n  const fn = visitor[key] as ((node: Node, context: VisitorContext) => TResult | null | undefined) | undefined\n\n  return fn?.(node, { parent })\n}\n\n/**\n * Async depth-first traversal for side effects. Visitor return values are\n * ignored. Use `transform` when you want to rewrite nodes.\n *\n * Sibling nodes at each depth run concurrently up to `options.concurrency`\n * (defaults to `WALK_CONCURRENCY`). Higher values overlap I/O-bound visitor\n * work. Lower values reduce memory pressure.\n *\n * @example Log every operation\n * ```ts\n * await walk(root, {\n *   operation(node) {\n *     console.log(node.operationId)\n *   },\n * })\n * ```\n *\n * @example Only visit the root node\n * ```ts\n * await walk(root, { depth: 'shallow', input: () => {} })\n * ```\n */\nexport async function walk(node: Node, options: WalkOptions): Promise<void> {\n  const recurse = (options.depth ?? visitorDepths.deep) === visitorDepths.deep\n  const limit = createLimit(options.concurrency ?? WALK_CONCURRENCY)\n\n  return _walk(node, options, recurse, limit, undefined)\n}\n\nasync function _walk(node: Node, visitor: AsyncVisitor, recurse: boolean, limit: LimitFn, parent: Node | undefined): Promise<void> {\n  await limit(() => applyVisitor(node, visitor, parent))\n\n  // Visit siblings concurrently and let the shared `limit` cap how many callbacks\n  // run at once. Awaiting each child sequentially here would serialize the whole\n  // traversal and make `concurrency` inert. Every visitor callback would run one\n  // at a time regardless of the limit.\n  const children = Array.from(getChildren(node, recurse))\n  if (children.length === 0) return\n\n  await Promise.all(children.map((child) => _walk(child, visitor, recurse, limit, node)))\n}\n\n/**\n * Synchronous depth-first transform. Each visitor callback can return a\n * replacement node. Returning `undefined` keeps the original.\n *\n * The original tree is never mutated, a new tree is returned. Pass\n * `depth: 'shallow'` to skip recursion into children.\n *\n * @example Prefix every operationId\n * ```ts\n * const next = transform(root, {\n *   operation(node) {\n *     return { ...node, operationId: `prefixed_${node.operationId}` }\n *   },\n * })\n * ```\n *\n * @example Replace only the root node\n * ```ts\n * const next = transform(root, {\n *   depth: 'shallow',\n *   input: (node) => ({ ...node, meta: { ...node.meta, title: 'Rewritten' } }),\n * })\n * ```\n */\nexport function transform(node: InputNode, options: TransformOptions): InputNode\nexport function transform(node: OutputNode, options: TransformOptions): OutputNode\nexport function transform(node: OperationNode, options: TransformOptions): OperationNode\nexport function transform(node: SchemaNode, options: TransformOptions): SchemaNode\nexport function transform(node: PropertyNode, options: TransformOptions): PropertyNode\nexport function transform(node: ParameterNode, options: TransformOptions): ParameterNode\nexport function transform(node: ResponseNode, options: TransformOptions): ResponseNode\nexport function transform(node: Node, options: TransformOptions): Node\nexport function transform(node: Node, options: TransformOptions): Node {\n  const { depth, parent, ...visitor } = options\n  const recurse = (depth ?? visitorDepths.deep) === visitorDepths.deep\n\n  const visited = applyVisitor<Node>(node, visitor, parent) ?? node\n  const rebuilt = transformChildren(visited, options, recurse)\n\n  // Structural sharing: when the visitor and child rebuild both left this node\n  // untouched, return the original reference so callers can detect \"nothing\n  // changed\" by identity and ancestors can avoid reallocating.\n  if (rebuilt === node) return node\n\n  const rebuild = nodeRebuilders[rebuilt.kind]\n  return rebuild ? rebuild(rebuilt) : rebuilt\n}\n\n/**\n * Immutably rebuilds a node's children using {@link VISITOR_KEYS}, transforming\n * each child node and leaving non-node values (e.g. `additionalProperties: true`) intact.\n * `Schema` children are skipped in shallow mode.\n */\nfunction transformChildren(node: Node, options: TransformOptions, recurse: boolean): Node {\n  if (node.kind === 'Schema' && !recurse) return node\n\n  const keys = visitorKeysByKind[node.kind]\n  if (!keys) return node\n\n  const record = node as unknown as Record<string, unknown>\n  const childOptions = { ...options, parent: node }\n  let updates: Record<string, unknown> | undefined\n\n  for (const key of keys) {\n    if (!(key in record)) continue\n    const value = record[key]\n    if (Array.isArray(value)) {\n      let changed = false\n      const mapped = value.map((item) => {\n        if (!isNode(item)) return item\n        const next = transform(item, childOptions)\n        if (next !== item) changed = true\n        return next\n      })\n      if (changed) (updates ??= {})[key] = mapped\n    } else if (isNode(value)) {\n      const next = transform(value, childOptions)\n      if (next !== value) (updates ??= {})[key] = next\n    }\n  }\n\n  return updates ? ({ ...node, ...updates } as Node) : node\n}\n/**\n * Lazy depth-first collection pass. Yields every non-null value returned by\n * the visitor callbacks. Use `collect` for the eager array form.\n *\n * @example Collect every operationId\n * ```ts\n * const ids: string[] = []\n * for (const id of collectLazy<string>(root, {\n *   operation(node) {\n *     return node.operationId\n *   },\n * })) {\n *   ids.push(id)\n * }\n * ```\n */\nexport function* collectLazy<T>(node: Node, options: CollectOptions<T>): Generator<T, void, undefined> {\n  const { depth, parent, ...visitor } = options\n  const recurse = (depth ?? visitorDepths.deep) === visitorDepths.deep\n\n  const v = applyVisitor<T>(node, visitor, parent)\n  if (v != null) yield v\n\n  for (const child of getChildren(node, recurse)) {\n    yield* collectLazy(child, { ...options, parent: node })\n  }\n}\n\n/**\n * Eager depth-first collection pass. Gathers every non-null value the visitor\n * callbacks return into an array.\n *\n * @example Collect every operationId\n * ```ts\n * const ids = collect<string>(root, {\n *   operation(node) {\n *     return node.operationId\n *   },\n * })\n * ```\n */\nexport function collect<T>(node: Node, options: CollectOptions<T>): Array<T> {\n  return Array.from(collectLazy(node, options))\n}\n"],"mappings":";;AAWA,MAAa,gBAAgB;CAC3B,SAAS;CACT,MAAM;AACR;;;;;;;AAQA,MAAa,cAAc;;;;CAIzB,QAAQ;;;;CAIR,QAAQ;;;;CAIR,SAAS;;;;CAIT,QAAQ;;;;CAIR,SAAS;;;;CAIT,MAAM;;;;CAIN,KAAK;;;;CAIL,SAAS;;;;CAIT,MAAM;;;;CAIN,QAAQ;;;;CAIR,OAAO;;;;CAIP,OAAO;;;;CAIP,OAAO;;;;CAIP,cAAc;;;;CAId,MAAM;;;;CAIN,KAAK;;;;CAIL,MAAM;;;;CAIN,UAAU;;;;CAIV,MAAM;;;;CAIN,MAAM;;;;CAIN,OAAO;;;;CAIP,KAAK;;;;CAIL,MAAM;;;;CAIN,MAAM;;;;CAIN,MAAM;;;;CAIN,OAAO;AACT;;;;AAOA,MAAM,yBAAyB,IAAI,IAAqB;CAAC;CAAU;CAAU;CAAW;CAAU;AAAS,CAAC;;;;;AAM5G,SAAgB,kBAAkB,MAAuC;CACvE,OAAO,uBAAuB,IAAI,IAAuB;AAC3D;;;;AAKA,MAAa,cAAc;CACzB,KAAK;CACL,MAAM;CACN,KAAK;CACL,OAAO;CACP,QAAQ;CACR,MAAM;CACN,SAAS;CACT,OAAO;AACT;;;;AA0BA,MAAa,SAAS,MAAM,KAAK,EAAE,QAAQ,EAAY,SAAS,GAAG,CAAC,CAAC,KAAK,EAAE;;;;;;;;;;;;AC3K5E,SAAgB,aAA2C,MAA8B,MAAqC;CAC5H,OAAO,MAAM,SAAS,OAAQ,OAA+B;AAC/D;;;;;;;;;;;AAYA,SAAgB,oBAAoB,MAAgD;CAClF,OAAO,KAAK,aAAa,UAAW,KAAK,WAAW,KAAA,KAAa,KAAK,SAAS,KAAA;AACjF;;;ACrBA,MAAM,mBAAmB,IAAI,IAAgB;CAAC;CAAU;CAAQ;CAAS;CAAO;AAAU,CAAU;;;;;;;;;AAUpG,SAAgB,eAAe,KAAqB;CAClD,OAAO,IAAI,MAAM,GAAG,CAAC,CAAC,GAAG,EAAE,KAAK;AAClC;;;;;;;;;;;;AAaA,SAAgB,eAAe,MAA6C;CAC1E,IAAI,CAAC,QAAQ,KAAK,SAAS,OAAO,OAAO;CACzC,IAAI,KAAK,KAAK,OAAO,eAAe,KAAK,GAAG,KAAK,KAAK,QAAQ,KAAK,QAAQ,QAAQ;CAEnF,OAAO,KAAK,QAAQ,KAAK,QAAQ,QAAQ;AAC3C;;;;;;;;;;;AAYA,SAAgB,UAAU,YAAuC,UAAiC;CAChG,OAAO,aAAaA,iBAAAA,WAAW,CAAC,YAAY,QAAQ,CAAC,CAAC,KAAK,GAAG,CAAC,IAAI;AACrE;;;;;;;;;;AAWA,SAAgB,aAAa,YAAuC,UAAkB,YAA4B;CAChH,OAAOA,iBAAAA,WAAW;EAAC;EAAY;EAAU;CAAU,CAAC,CAAC,OAAO,OAAO,CAAC,CAAC,KAAK,GAAG,CAAC;AAChF;;;;;;;;;;;;;AAcA,SAAgB,cAAc,MAA8B;CAC1D,MAAM,MAAM,aAAa,MAAM,KAAK;CAEpC,IAAI,CAAC,KAAK,OAAO;CACjB,IAAI,CAAC,IAAI,QAAQ,OAAO;CAExB,MAAM,EAAE,MAAM,OAAO,MAAM,OAAO,MAAM,OAAO,KAAK,MAAM,QAAQ,SAAS,GAAG,cAAc;CAG5F,MAAM,mBAAmB,OAAO,YAAY,OAAO,QAAQ,SAAS,CAAC,CAAC,QAAQ,GAAG,OAAO,MAAM,KAAA,CAAS,CAAC;CAExG,OAAOC,iBAAAA,aAAa;EAAE,GAAG,IAAI;EAAQ,GAAG;CAAiB,CAAC;AAC5D;;;;;;;AAQA,SAAgB,aAAa,MAA2B;CACtD,IAAI,iBAAiB,IAAI,KAAK,IAAI,GAChC,OAAO;CAGT,MAAM,WAAW,aAAa,MAAM,MAAM,KAAK,aAAa,MAAM,MAAM;CACxE,IAAI,UACF,OAAO,SAAS,mBAAmB;CAGrC,OAAO;AACT;;;;;;;AAQA,SAAgB,iBAAiB,EAC/B,MACA,QACA,OACA,YAMwB;CACxB,IAAI,CAAC,YAAY,CAAC,OAAO,QACvB,OAAO;CAET,MAAM,aAAa,OAAO;CAE1B,MAAM,aADc,UAAU,UAAU,SAAS,yBAAyB,SAAS,wBAAA,CACrD,KAAK,UAAU,MAAM,UAAU;CAC7D,IAAI,cAAc,SAAS,iBAAiB,MAAM,UAAU,GAC1D,OAAO;CAET,OAAO;EAAE,MAAM;EAAW,UAAU,OAAO,OAAO,MAAM,CAAC,EAAE,QAAQ;CAAE;AACvE;;;;;;;ACzFA,MAAa,WAAW;CACtBC,iBAAAA;CACAC,iBAAAA;CACAC,iBAAAA;CACAC,iBAAAA;CACAC,iBAAAA;CACAC,iBAAAA;CACAC,iBAAAA;CACAC,iBAAAA;CACAC,iBAAAA;CACAC,iBAAAA;CACAC,iBAAAA;CACAC,iBAAAA;CACAC,iBAAAA;CACAC,iBAAAA;CACAC,iBAAAA;CACAC,iBAAAA;CACAC,iBAAAA;CACAC,iBAAAA;CACAC,iBAAAA;CACAC,iBAAAA;CACAC,iBAAAA;CACAC,iBAAAA;CACAC,iBAAAA;CACAC,iBAAAA;CACAC,iBAAAA;AACF;;;;;;;ACpDA,MAAM,eAAe,OAAO,YAAY,SAAS,SAAS,QAAS,IAAI,WAAW,CAAC,CAAC,IAAI,MAAM,IAAI,QAAQ,CAAU,IAAI,CAAC,CAAE,CAAC;;;;;AAQ5H,MAAM,sBAAsB,OAAO,YAAY,SAAS,SAAS,QAAS,IAAI,aAAa,CAAC,CAAC,IAAI,MAAM,IAAI,UAAU,CAAU,IAAI,CAAC,CAAE,CAAC;;;;;AAQvI,MAAM,iBAAiB,OAAO,YAC5B,SAAS,SAAS,QAAS,IAAI,UAAU,CAAC,CAAC,IAAI,MAAM,IAAI,MAAyC,CAAU,IAAI,CAAC,CAAE,CACrH;;;;;;;;;;;;;;;AAgBA,SAAS,YAAY,aAAqB;CACxC,IAAI,SAAS;CACb,MAAM,QAA2B,CAAC;CAElC,SAAS,OAAO;EACd,IAAI,SAAS,eAAe,MAAM,SAAS,GAAG;GAC5C;GACA,MAAM,MAAM,CAAC,CAAE;EACjB;CACF;CAEA,OAAO,SAAS,MAAS,IAAsC;EAC7D,OAAO,IAAI,SAAY,SAAS,WAAW;GACzC,MAAM,WAAW;IACf,QAAQ,QAAQ,GAAG,CAAC,CAAC,CAClB,KAAK,SAAS,MAAM,CAAC,CACrB,cAAc;KACb;KACA,KAAK;IACP,CAAC;GACL,CAAC;GACD,KAAK;EACP,CAAC;CACH;AACF;AAkOA,MAAM,oBAAoB;;;;AAK1B,SAAS,OAAO,OAA+B;CAC7C,OAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,UAAU;AAClE;;;;;;;;;;;;AAaA,UAAU,YAAY,MAAY,SAAoD;CACpF,IAAI,KAAK,SAAS,YAAY,CAAC,SAAS;CAExC,MAAM,OAAO,kBAAkB,KAAK;CACpC,IAAI,CAAC,MAAM;CAEX,MAAM,SAAS;CACf,KAAK,MAAM,OAAO,MAAM;EACtB,MAAM,QAAQ,OAAO;EACrB,IAAI,MAAM,QAAQ,KAAK;QAChB,MAAM,QAAQ,OAAO,IAAI,OAAO,IAAI,GAAG,MAAM;EAAA,OAC7C,IAAI,OAAO,KAAK,GACrB,MAAM;CAEV;AACF;;;;;;;;;;AAWA,SAAS,aAAsB,MAAY,SAA2D,QAAsD;CAC1J,MAAM,MAAM,oBAAoB,KAAK;CACrC,IAAI,CAAC,KAAK,OAAO,KAAA;CAEjB,MAAM,KAAK,QAAQ;CAEnB,OAAO,KAAK,MAAM,EAAE,OAAO,CAAC;AAC9B;;;;;;;;;;;;;;;;;;;;;;;AAwBA,eAAsB,KAAK,MAAY,SAAqC;CAI1E,OAAO,MAAM,MAAM,UAHF,QAAQ,SAAS,cAAc,UAAU,cAAc,MAC1D,YAAY,QAAQ,eAAA,EAEO,GAAG,KAAA,CAAS;AACvD;AAEA,eAAe,MAAM,MAAY,SAAuB,SAAkB,OAAgB,QAAyC;CACjI,MAAM,YAAY,aAAa,MAAM,SAAS,MAAM,CAAC;CAMrD,MAAM,WAAW,MAAM,KAAK,YAAY,MAAM,OAAO,CAAC;CACtD,IAAI,SAAS,WAAW,GAAG;CAE3B,MAAM,QAAQ,IAAI,SAAS,KAAK,UAAU,MAAM,OAAO,SAAS,SAAS,OAAO,IAAI,CAAC,CAAC;AACxF;AAkCA,SAAgB,UAAU,MAAY,SAAiC;CACrE,MAAM,EAAE,OAAO,QAAQ,GAAG,YAAY;CACtC,MAAM,WAAW,SAAS,cAAc,UAAU,cAAc;CAGhE,MAAM,UAAU,kBADA,aAAmB,MAAM,SAAS,MAAM,KAAK,MAClB,SAAS,OAAO;CAK3D,IAAI,YAAY,MAAM,OAAO;CAE7B,MAAM,UAAU,eAAe,QAAQ;CACvC,OAAO,UAAU,QAAQ,OAAO,IAAI;AACtC;;;;;;AAOA,SAAS,kBAAkB,MAAY,SAA2B,SAAwB;CACxF,IAAI,KAAK,SAAS,YAAY,CAAC,SAAS,OAAO;CAE/C,MAAM,OAAO,kBAAkB,KAAK;CACpC,IAAI,CAAC,MAAM,OAAO;CAElB,MAAM,SAAS;CACf,MAAM,eAAe;EAAE,GAAG;EAAS,QAAQ;CAAK;CAChD,IAAI;CAEJ,KAAK,MAAM,OAAO,MAAM;EACtB,IAAI,EAAE,OAAO,SAAS;EACtB,MAAM,QAAQ,OAAO;EACrB,IAAI,MAAM,QAAQ,KAAK,GAAG;GACxB,IAAI,UAAU;GACd,MAAM,SAAS,MAAM,KAAK,SAAS;IACjC,IAAI,CAAC,OAAO,IAAI,GAAG,OAAO;IAC1B,MAAM,OAAO,UAAU,MAAM,YAAY;IACzC,IAAI,SAAS,MAAM,UAAU;IAC7B,OAAO;GACT,CAAC;GACD,IAAI,SAAS,CAAC,YAAY,CAAC,EAAA,CAAG,OAAO;EACvC,OAAO,IAAI,OAAO,KAAK,GAAG;GACxB,MAAM,OAAO,UAAU,OAAO,YAAY;GAC1C,IAAI,SAAS,OAAO,CAAC,YAAY,CAAC,EAAA,CAAG,OAAO;EAC9C;CACF;CAEA,OAAO,UAAW;EAAE,GAAG;EAAM,GAAG;CAAQ,IAAa;AACvD;;;;;;;;;;;;;;;;;AAiBA,UAAiB,YAAe,MAAY,SAA2D;CACrG,MAAM,EAAE,OAAO,QAAQ,GAAG,YAAY;CACtC,MAAM,WAAW,SAAS,cAAc,UAAU,cAAc;CAEhE,MAAM,IAAI,aAAgB,MAAM,SAAS,MAAM;CAC/C,IAAI,KAAK,MAAM,MAAM;CAErB,KAAK,MAAM,SAAS,YAAY,MAAM,OAAO,GAC3C,OAAO,YAAY,OAAO;EAAE,GAAG;EAAS,QAAQ;CAAK,CAAC;AAE1D;;;;;;;;;;;;;;AAeA,SAAgB,QAAW,MAAY,SAAsC;CAC3E,OAAO,MAAM,KAAK,YAAY,MAAM,OAAO,CAAC;AAC9C"}

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@kubb/ast",
-  "version": "5.0.0-beta.6",
-  "description": "Spec-agnostic AST layer for Kubb. Defines nodes, visitor pattern, and factory functions used across codegen plugins.",
+  "version": "5.0.0-beta.61",
+  "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",
@@ -24,7 +23,6 @@
     "!/**/__snapshots__/**"
   ],
   "type": "module",
-  "sideEffects": false,
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -33,6 +31,22 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./factory": {
+      "import": "./dist/factory.js",
+      "require": "./dist/factory.cjs"
+    },
+    "./macros": {
+      "import": "./dist/macros.js",
+      "require": "./dist/macros.cjs"
+    },
+    "./types": {
+      "import": "./dist/types.js",
+      "require": "./dist/types.cjs"
+    },
+    "./utils": {
+      "import": "./dist/utils.js",
+      "require": "./dist/utils.cjs"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -40,7 +54,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "devDependencies": {
-    "@types/node": "^22.19.17",
+    "@types/node": "^22.19.21",
     "@internals/utils": "0.0.0"
   },
   "engines": {
@@ -48,11 +62,12 @@
   },
   "scripts": {
     "build": "tsdown",
-    "clean": "npx rimraf ./dist",
+    "clean": "node -e \"require('node:fs').rmSync('./dist', {recursive:true,force:true})\"",
     "lint": "oxlint .",
     "lint:fix": "oxlint --fix .",
     "release": "pnpm publish --no-git-check",
     "release:canary": "bash ../../.github/canary.sh && node ../../scripts/build.js canary && pnpm publish --no-git-check",
+    "release:stage": "pnpm stage publish --no-git-check",
     "start": "tsdown --watch",
     "test": "vitest --passWithNoTests",
     "typecheck": "tsc -p ./tsconfig.json --noEmit --emitDeclarationOnly false"

package/src/constants.ts

@@ -1,13 +1,11 @@
-import type { NodeKind } from './nodes/base.ts'
-import type { MediaType } from './nodes/http.ts'
 import type { HttpMethod } from './nodes/operation.ts'
 import type { SchemaType } from './nodes/schema.ts'
 
 /**
  * Traversal depth for AST visitor utilities.
  *
- * - `'shallow'` — visits only the immediate node, skipping children.
- * - `'deep'` — recursively visits all descendant nodes.
+ * - `'shallow'` visits only the immediate node, skipping children.
+ * - `'deep'` recursively visits all descendant nodes.
  */
 export type VisitorDepth = 'shallow' | 'deep'
 
@@ -16,32 +14,11 @@ export const visitorDepths = {
   deep: 'deep',
 } as const satisfies Record<VisitorDepth, VisitorDepth>
 
-export const nodeKinds = {
-  input: 'Input',
-  output: 'Output',
-  operation: 'Operation',
-  schema: 'Schema',
-  property: 'Property',
-  parameter: 'Parameter',
-  response: 'Response',
-  functionParameter: 'FunctionParameter',
-  parameterGroup: 'ParameterGroup',
-  functionParameters: 'FunctionParameters',
-  type: 'Type',
-  file: 'File',
-  import: 'Import',
-  export: 'Export',
-  source: 'Source',
-  text: 'Text',
-  break: 'Break',
-} as const satisfies Record<string, NodeKind>
-
 /**
  * Schema type discriminators used by all AST schema nodes.
  *
- * These values serve as stable discriminators across the AST (e.g., `schema.type === schemaTypes.object`).
- * Grouped by category: primitives (`string`, `number`, `boolean`), structural types (`object`, `array`, `union`),
- * and format-specific types (`date`, `uuid`, `email`). Use `isScalarPrimitive()` to check for scalar types.
+ * Each value is a stable discriminator across the AST (for example `schema.type === schemaTypes.object`).
+ * Call `isScalarPrimitive()` to check for the scalar types.
  */
 export const schemaTypes = {
   /**
@@ -61,7 +38,7 @@ export const schemaTypes = {
    */
   bigint: 'bigint',
   /**
-   * Boolean value
+   * Boolean value.
    */
   boolean: 'boolean',
   /**
@@ -154,15 +131,12 @@ export type ScalarPrimitive = 'string' | 'number' | 'integer' | 'bigint' | 'bool
 
 /**
  * Scalar primitive schema types used for union simplification and type narrowing.
- *
- * Use `isScalarPrimitive()` to safely check whether a type is a scalar primitive.
  */
-export const SCALAR_PRIMITIVE_TYPES = new Set<ScalarPrimitive>(['string', 'number', 'integer', 'bigint', 'boolean'])
+const SCALAR_PRIMITIVE_TYPES = new Set<ScalarPrimitive>(['string', 'number', 'integer', 'bigint', 'boolean'])
 
 /**
- * Type guard that returns `true` when `type` is a scalar primitive schema type.
- *
- * Use this to check if a schema type can be directly assigned without wrapping (e.g., `string | number | boolean`).
+ * Returns `true` when `type` is a scalar primitive that can be assigned without wrapping
+ * (for example `string | number | boolean`).
  */
 export function isScalarPrimitive(type: string): type is ScalarPrimitive {
   return SCALAR_PRIMITIVE_TYPES.has(type as ScalarPrimitive)
@@ -170,8 +144,6 @@ export function isScalarPrimitive(type: string): type is ScalarPrimitive {
 
 /**
  * HTTP method identifiers used by operation nodes.
- *
- * Includes all standard HTTP methods (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACE).
  */
 export const httpMethods = {
   get: 'GET',
@@ -185,10 +157,10 @@ export const httpMethods = {
 } as const satisfies Record<Lowercase<HttpMethod>, HttpMethod>
 
 /**
- * Default concurrency limit for `walk()` traversal utility.
+ * Default concurrency limit for the `walk()` traversal utility.
  *
- * Set to 30 to balance I/O-bound resolver parallelism against event loop pressure and memory usage during large spec traversals.
- * Use `WALK_CONCURRENCY` when calling `walk()` or override for different hardware constraints.
+ * Set to 30 to balance I/O-bound resolver parallelism against event-loop and memory pressure
+ * during large spec traversals. Override it for different hardware constraints.
  *
  * @example
  * ```ts
@@ -200,29 +172,12 @@ export const httpMethods = {
 export const WALK_CONCURRENCY = 30
 
 /**
- * Common MIME types used in request/response content negotiation.
- *
- * Covers JSON, XML, form data, PDFs, images, audio, and video formats.
- * Use these as keys when serializing request/response bodies.
+ * Number of spaces in one indentation level when assembling multi-line code as strings.
+ * Set to 2, 3, … to change the indent width used by `buildObject`/`buildList`.
+ */
+const INDENT_SIZE = 2
+
+/**
+ * One indentation level, derived from {@link INDENT_SIZE}.
  */
-export const mediaTypes = {
-  applicationJson: 'application/json',
-  applicationXml: 'application/xml',
-  applicationFormUrlEncoded: 'application/x-www-form-urlencoded',
-  applicationOctetStream: 'application/octet-stream',
-  applicationPdf: 'application/pdf',
-  applicationZip: 'application/zip',
-  applicationGraphql: 'application/graphql',
-  multipartFormData: 'multipart/form-data',
-  textPlain: 'text/plain',
-  textHtml: 'text/html',
-  textCsv: 'text/csv',
-  textXml: 'text/xml',
-  imagePng: 'image/png',
-  imageJpeg: 'image/jpeg',
-  imageGif: 'image/gif',
-  imageWebp: 'image/webp',
-  imageSvgXml: 'image/svg+xml',
-  audioMpeg: 'audio/mpeg',
-  videoMp4: 'video/mp4',
-} as const satisfies Record<string, MediaType>
+export const INDENT = Array.from({ length: INDENT_SIZE }, () => ' ').join('')

package/src/dedupe.ts

@@ -0,0 +1,239 @@
+/**
+ * Schema-shape deduplication. `buildDedupePlan` finds top-level and inline schemas that share a
+ * structural signature, picks one canonical definition, and `applyDedupe` repoints every duplicate
+ * at it. This works on `SchemaNode` content, not on files.
+ *
+ * For merging a file's imports, exports, and source nodes, see `utils/fileMerge.ts`. Same idea of
+ * collapsing duplicates, but a different domain.
+ */
+import type { Node, OperationNode, SchemaNode } from './nodes/index.ts'
+import { createSchema } from './nodes/schema.ts'
+import { signatureOf } from './signature.ts'
+import { extractRefName } from './utils/index.ts'
+import { collectLazy, transform } from './visitor.ts'
+
+/**
+ * A canonical destination for a deduplicated shape: the shared schema name and
+ * the synthetic `$ref` path that points at it.
+ */
+export type DedupeCanonical = {
+  /**
+   * Canonical schema name every duplicate occurrence refers to.
+   */
+  name: string
+  /**
+   * `$ref` path stored on the generated `ref` nodes (for example `#/components/schemas/Status`).
+   */
+  ref: string
+}
+
+/**
+ * The result of {@link buildDedupePlan}: a lookup from structural signature to its
+ * canonical target, plus the freshly hoisted definitions that must be added to
+ * the schema list.
+ */
+export type DedupePlan = {
+  /**
+   * Maps a structural signature to the canonical schema that represents it.
+   */
+  canonicalBySignature: Map<string, DedupeCanonical>
+  /**
+   * Maps the name of a top-level schema that duplicates a canonical one to that canonical, so
+   * references to the duplicate can be repointed at the first schema with the same content.
+   */
+  aliasNames: Map<string, DedupeCanonical>
+  /**
+   * New top-level schema definitions created for inline shapes that had no existing
+   * named component. Nested duplicates inside each definition are already collapsed.
+   */
+  hoisted: Array<SchemaNode>
+}
+
+/**
+ * The lookups {@link applyDedupe} needs from a {@link DedupePlan}.
+ */
+export type DedupeLookups = Pick<DedupePlan, 'canonicalBySignature' | 'aliasNames'>
+
+/**
+ * Options that inject the naming and candidate policy into {@link buildDedupePlan}.
+ * The mechanics (grouping, counting, rewriting) live here. The policy lives in the caller.
+ */
+export type BuildDedupePlanOptions = {
+  /**
+   * Returns `true` when a node should be deduplicated. This is the only gate, so it must
+   * reject both ineligible kinds (return `false` for anything other than, say, enums and
+   * objects) and unsafe shapes (e.g. nodes that reference a circular schema).
+   */
+  isCandidate: (node: SchemaNode) => boolean
+  /**
+   * Produces the canonical name for an inline shape with no existing named component.
+   * Return `null` to leave the shape inline (for example when no contextual name exists).
+   */
+  nameFor: (node: SchemaNode, signature: string) => string | null
+  /**
+   * Builds the `$ref` path for a canonical name.
+   */
+  refFor: (name: string) => string
+  /**
+   * Minimum number of occurrences before a shape is deduplicated.
+   *
+   * @default 2
+   */
+  minOccurrences?: number
+}
+
+/**
+ * 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: SchemaNode, canonical: DedupeCanonical): SchemaNode {
+  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,
+  })
+}
+
+/**
+ * Rewrites a node, replacing every candidate sub-schema whose signature has a canonical
+ * target with a `ref` to that target. Replacing a node with a `ref` prunes its subtree,
+ * so nested duplicates inside a replaced shape are not visited again. A `ref` that points
+ * at a duplicate top-level schema (see `aliasNames`) is repointed at the first schema with
+ * the same content.
+ *
+ * Pass `skipRootMatch` when rewriting a canonical definition so its own root is not
+ * turned into a reference to itself. Nested duplicates are still collapsed.
+ *
+ * @example
+ * ```ts
+ * const next = applyDedupe(operationNode, plan)
+ * ```
+ */
+export function applyDedupe(node: SchemaNode, plan: DedupeLookups, skipRootMatch?: boolean): SchemaNode
+export function applyDedupe(node: OperationNode, plan: DedupeLookups, skipRootMatch?: boolean): OperationNode
+export function applyDedupe(node: Node, plan: DedupeLookups, skipRootMatch = false): Node {
+  const { canonicalBySignature, aliasNames } = plan
+  if (canonicalBySignature.size === 0 && aliasNames.size === 0) return node
+
+  const root = node
+
+  return transform(node, {
+    schema(schemaNode) {
+      if (schemaNode.type === 'ref') {
+        const target = schemaNode.ref ? extractRefName(schemaNode.ref) : schemaNode.name
+        const canonical = target ? aliasNames.get(target) : undefined
+
+        return canonical ? { ...schemaNode, name: canonical.name, ref: canonical.ref } : undefined
+      }
+
+      const signature = signatureOf(schemaNode)
+      if (skipRootMatch && schemaNode === root) return undefined
+
+      const canonical = canonicalBySignature.get(signature)
+      if (!canonical) return undefined
+
+      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: SchemaNode, name: string): SchemaNode {
+  return { ...node, name, optional: undefined, nullish: undefined }
+}
+
+/**
+ * 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, the first one becomes the canonical (so other top-level
+ * duplicates and inline copies turn into references to it). Every other top-level name with
+ * the same content is recorded in `aliasNames`, so refs to it can be repointed at the
+ * canonical. 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}`,
+ * })
+ * ```
+ */
+export function buildDedupePlan(roots: ReadonlyArray<Node>, options: BuildDedupePlanOptions): DedupePlan {
+  const { isCandidate, nameFor, refFor, minOccurrences = 2 } = options
+
+  const topLevelNodes = new Set<SchemaNode>()
+
+  type Group = {
+    count: number
+    representative: SchemaNode
+    topLevelNames: Array<string>
+  }
+  const groups = new Map<string, Group>()
+
+  function record(schemaNode: SchemaNode): void {
+    const signature = signatureOf(schemaNode)
+    if (!isCandidate(schemaNode)) return
+
+    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!] : [] })
+    }
+  }
+
+  for (const root of roots) {
+    if (root.kind === 'Schema') topLevelNodes.add(root)
+    for (const schemaNode of collectLazy<SchemaNode>(root, { schema: (node) => node })) {
+      record(schemaNode)
+    }
+  }
+
+  const canonicalBySignature = new Map<string, DedupeCanonical>()
+  const aliasNames = new Map<string, DedupeCanonical>()
+  const pendingHoists: Array<{ name: string; representative: SchemaNode }> = []
+
+  for (const [signature, group] of groups) {
+    if (group.count < minOccurrences) continue
+
+    const [firstName, ...duplicateNames] = group.topLevelNames
+    if (firstName) {
+      const canonical: DedupeCanonical = { name: firstName, ref: refFor(firstName) }
+      canonicalBySignature.set(signature, canonical)
+      for (const duplicate of duplicateNames) {
+        aliasNames.set(duplicate, canonical)
+      }
+      continue
+    }
+
+    const name = nameFor(group.representative, signature)
+    if (!name) continue
+
+    canonicalBySignature.set(signature, { name, ref: refFor(name) })
+    pendingHoists.push({ name, representative: group.representative })
+  }
+
+  // Build hoisted definitions only after every canonical name is known, so nested
+  // duplicates inside a definition also resolve to refs.
+  const hoisted = pendingHoists.map(({ name, representative }) =>
+    cleanDefinition(applyDedupe(representative, { canonicalBySignature, aliasNames }, true), name),
+  )
+
+  return { canonicalBySignature, aliasNames, hoisted }
+}

package/src/defineMacro.ts

@@ -0,0 +1,132 @@
+import type { VisitorDepth } from './constants.ts'
+import type { Node } from './nodes/index.ts'
+import type { Visitor, VisitorContext } from './visitor.ts'
+import { transform } from './visitor.ts'
+
+/**
+ * Visitor callback names a macro can implement, one per traversable node kind.
+ * Mirrors the keys of {@link Visitor}.
+ */
+const macroKeys = ['input', 'output', 'operation', 'schema', 'property', 'parameter', 'response'] as const
+
+type MacroKey = (typeof macroKeys)[number]
+
+/**
+ * Sort weight for an `enforce` hint. `pre` sorts before unmarked items and `post` after, so a plain
+ * list keeps its authored order.
+ */
+function enforceWeight(enforce?: 'pre' | 'post'): number {
+  if (enforce === 'pre') return 0
+  if (enforce === 'post') return 2
+  return 1
+}
+
+/**
+ * A named, composable transform over the Kubb AST. It carries the same per-kind callbacks as a
+ * {@link Visitor} (`schema`, `operation`, …), plus a `name`, an optional `enforce` order, and an
+ * optional `when` gate. Macros run on the shared AST, so the same macro works across every adapter
+ * and output target. Exports follow the `macro<Name>` convention, mirroring plugins (`pluginTs`).
+ */
+export type Macro = Visitor & {
+  /**
+   * Macro identifier, surfaced in diagnostics. Follows the `macro<Name>` convention.
+   */
+  name: string
+  /**
+   * Ordering hint. `pre` macros run before unmarked macros, `post` macros run after.
+   * Ordering within a bucket follows list order.
+   */
+  enforce?: 'pre' | 'post'
+  /**
+   * Gate checked against the current node before any callback runs. When it returns `false`
+   * the macro is skipped for that node.
+   */
+  when?: (node: Node) => boolean
+}
+
+/**
+ * Types a macro for inference and a single construction site, mirroring `definePlugin`.
+ * Adds no runtime behavior.
+ *
+ * @example
+ * ```ts
+ * const macroUntagged = defineMacro({
+ *   name: 'untagged',
+ *   operation(node) {
+ *     return node.tags?.length ? undefined : { ...node, tags: ['untagged'] }
+ *   },
+ * })
+ * ```
+ */
+export function defineMacro(macro: Macro): Macro {
+  return macro
+}
+
+type MacroCallback = (node: Node, context: VisitorContext) => Node | null | undefined
+
+/**
+ * Runs every macro's callback for one node kind in order, chaining the result so each macro sees
+ * the previous macro's output. Returns `undefined` when nothing changed, so `transform` keeps the
+ * original reference (structural sharing).
+ */
+function chain(macros: ReadonlyArray<Macro>, key: MacroKey, node: Node, context: VisitorContext): Node | undefined {
+  let current = node
+
+  for (const macro of macros) {
+    const callback = macro[key] as MacroCallback | undefined
+    if (!callback) continue
+    if (macro.when && !macro.when(current)) continue
+
+    const next = callback(current, context)
+    if (next != null) current = next
+  }
+
+  return current === node ? undefined : current
+}
+
+/**
+ * Folds an ordered list of macros into a single {@link Visitor} that `transform` (and the per-plugin
+ * transform layer in `@kubb/core`) can run. Macros are stable-sorted by `enforce`, then applied
+ * sequentially per node so later macros see earlier output. This differs from a plain visitor, which
+ * has no names, ordering, or composition.
+ *
+ * @example
+ * ```ts
+ * const visitor = composeMacros([macroSimplifyUnion, macroDiscriminatorEnum])
+ * const next = transform(root, visitor)
+ * ```
+ */
+export function composeMacros(macros: ReadonlyArray<Macro>): Visitor {
+  const ordered = [...macros].sort((a, b) => enforceWeight(a.enforce) - enforceWeight(b.enforce))
+
+  const visitor: Visitor = {}
+  for (const key of macroKeys) {
+    if (!ordered.some((macro) => typeof macro[key] === 'function')) continue
+
+    const callback = (node: Node, context: VisitorContext) => chain(ordered, key, node, context)
+    ;(visitor as Record<MacroKey, MacroCallback>)[key] = callback
+  }
+
+  return visitor
+}
+
+/**
+ * Runs a list of macros over a node tree and returns the rewritten tree. Keeps `transform`'s
+ * structural sharing, so an empty or no-op macro list returns the same reference. Pass
+ * `depth: 'shallow'` to rewrite the root node only.
+ *
+ * @example
+ * ```ts
+ * const next = applyMacros(root, [macroIntegerToString])
+ * ```
+ *
+ * @example Apply to the root node only
+ * ```ts
+ * const named = applyMacros(node, [macroEnumName({ parentName, propName, enumSuffix })], { depth: 'shallow' })
+ * ```
+ */
+export function applyMacros<TNode extends Node>(root: TNode, macros: ReadonlyArray<Macro>, options?: { depth?: VisitorDepth }): TNode {
+  if (macros.length === 0) return root
+
+  return transform(root, { ...composeMacros(macros), depth: options?.depth }) as TNode
+}