@kubb/ast 5.0.0-alpha.13 → 5.0.0-alpha.14

package/dist/{visitor-D68E3x_d.d.ts → visitor-UlWOe-In.d.ts}

@@ -623,12 +623,19 @@ declare function createSchema<T extends DistributiveOmit<Exclude<SchemaNode, Obj
   kind: 'Schema';
 };
 declare function createSchema(props: DistributiveOmit<SchemaNode, 'kind'>): SchemaNode;
+/**
+ * Derives `schema.optional` and `schema.nullish` from `required` and `schema.nullable`.
+ * This keeps `PropertyNode.required` as the single source of truth for optionality.
+ */
+declare function syncPropertySchema(required: boolean, schema: SchemaNode): SchemaNode;
 /**
  * Creates a `PropertyNode`. `required` defaults to `false`.
+ * `schema.optional` and `schema.nullish` are auto-derived from `required` and `schema.nullable`.
  */
 declare function createProperty(props: Pick<PropertyNode, 'name' | 'schema'> & Partial<Omit<PropertyNode, 'kind' | 'name' | 'schema'>>): PropertyNode;
 /**
  * Creates a `ParameterNode`. `required` defaults to `false`.
+ * `schema.optional` is auto-derived from `required` and `schema.nullable`.
  */
 declare function createParameter(props: Pick<ParameterNode, 'name' | 'in' | 'schema'> & Partial<Omit<ParameterNode, 'kind' | 'name' | 'in' | 'schema'>>): ParameterNode;
 /**
@@ -852,69 +859,103 @@ declare function refMapToObject(refMap: RefMap): Record<string, SchemaNode>;
 //#endregion
 //#region src/visitor.d.ts
 /**
- * Shared options for `walk`, `transform`, and `collect`.
+ * Single source of truth: ordered list of `[NodeType, ParentType]` pairs
+ * describing which node types can be the parent of a given node in the AST.
+ *
+ * `ParentOf` walks this tuple and returns the parent type of the first matching entry.
  */
-type VisitorOptions = {
-  depth?: VisitorDepth;
-  /**
-   * Maximum number of sibling nodes visited concurrently inside `walk`.
-   * @default 30
-   */
-  concurrency?: number;
+type ParentNodeMap = [[RootNode, undefined], [OperationNode, RootNode], [SchemaNode, RootNode | OperationNode | SchemaNode | PropertyNode | ParameterNode | ResponseNode], [PropertyNode, SchemaNode], [ParameterNode, OperationNode], [ResponseNode, OperationNode]];
+type ParentOf<T extends Node, TEntries extends ReadonlyArray<[Node, unknown]> = ParentNodeMap> = TEntries extends [infer TEntry extends [Node, unknown], ...infer TRest extends ReadonlyArray<[Node, unknown]>] ? T extends TEntry[0] ? TEntry[1] : ParentOf<T, TRest> : Node;
+/**
+ * Traversal context passed as the second argument to every visitor callback.
+ * The `parent` field is narrowed based on the node type being visited.
+ */
+type VisitorContext<T extends Node = Node> = {
+  parent?: ParentOf<T>;
 };
 /**
  * Synchronous visitor for `transform` and `walk`.
  */
 type Visitor = {
-  root?(node: RootNode): void | RootNode;
-  operation?(node: OperationNode): void | OperationNode;
-  schema?(node: SchemaNode): void | SchemaNode;
-  property?(node: PropertyNode): void | PropertyNode;
-  parameter?(node: ParameterNode): void | ParameterNode;
-  response?(node: ResponseNode): void | ResponseNode;
+  root?(node: RootNode, context: VisitorContext<RootNode>): void | RootNode;
+  operation?(node: OperationNode, context: VisitorContext<OperationNode>): void | OperationNode;
+  schema?(node: SchemaNode, context: VisitorContext<SchemaNode>): void | SchemaNode;
+  property?(node: PropertyNode, context: VisitorContext<PropertyNode>): void | PropertyNode;
+  parameter?(node: ParameterNode, context: VisitorContext<ParameterNode>): void | ParameterNode;
+  response?(node: ResponseNode, context: VisitorContext<ResponseNode>): void | ResponseNode;
 };
 type MaybePromise<T> = T | Promise<T>;
 /**
  * Async visitor for `walk`. Synchronous `Visitor` objects are compatible.
  */
 type AsyncVisitor = {
-  root?(node: RootNode): MaybePromise<void | RootNode>;
-  operation?(node: OperationNode): MaybePromise<void | OperationNode>;
-  schema?(node: SchemaNode): MaybePromise<void | SchemaNode>;
-  property?(node: PropertyNode): MaybePromise<void | PropertyNode>;
-  parameter?(node: ParameterNode): MaybePromise<void | ParameterNode>;
-  response?(node: ResponseNode): MaybePromise<void | ResponseNode>;
+  root?(node: RootNode, context: VisitorContext<RootNode>): MaybePromise<void | RootNode>;
+  operation?(node: OperationNode, context: VisitorContext<OperationNode>): MaybePromise<void | OperationNode>;
+  schema?(node: SchemaNode, context: VisitorContext<SchemaNode>): MaybePromise<void | SchemaNode>;
+  property?(node: PropertyNode, context: VisitorContext<PropertyNode>): MaybePromise<void | PropertyNode>;
+  parameter?(node: ParameterNode, context: VisitorContext<ParameterNode>): MaybePromise<void | ParameterNode>;
+  response?(node: ResponseNode, context: VisitorContext<ResponseNode>): MaybePromise<void | ResponseNode>;
 };
 /**
  * Visitor for `collect`.
  */
 type CollectVisitor<T> = {
-  root?(node: RootNode): T | undefined;
-  operation?(node: OperationNode): T | undefined;
-  schema?(node: SchemaNode): T | undefined;
-  property?(node: PropertyNode): T | undefined;
-  parameter?(node: ParameterNode): T | undefined;
-  response?(node: ResponseNode): T | undefined;
+  root?(node: RootNode, context: VisitorContext<RootNode>): T | undefined;
+  operation?(node: OperationNode, context: VisitorContext<OperationNode>): T | undefined;
+  schema?(node: SchemaNode, context: VisitorContext<SchemaNode>): T | undefined;
+  property?(node: PropertyNode, context: VisitorContext<PropertyNode>): T | undefined;
+  parameter?(node: ParameterNode, context: VisitorContext<ParameterNode>): T | undefined;
+  response?(node: ResponseNode, context: VisitorContext<ResponseNode>): T | undefined;
+};
+/**
+ * Options for `transform` and `collect`. Extends `Visitor` with traversal settings.
+ */
+type TransformOptions = Visitor & {
+  depth?: VisitorDepth;
+  parent?: Node;
+};
+/**
+ * Options for `walk`. Extends `AsyncVisitor` with traversal settings.
+ */
+type WalkOptions = AsyncVisitor & {
+  depth?: VisitorDepth;
+  /**
+   * Maximum number of sibling nodes visited concurrently.
+   * @default 30
+   */
+  concurrency?: number;
+};
+/**
+ * Options for `collect`. Extends `CollectVisitor` with traversal settings.
+ */
+type CollectOptions<T> = CollectVisitor<T> & {
+  depth?: VisitorDepth;
+  parent?: Node;
 };
 /**
  * Depth-first traversal for side effects. Visitor return values are ignored.
  * Sibling nodes at each level are visited concurrently up to `options.concurrency` (default: 30).
  */
-declare function walk(node: Node, visitor: AsyncVisitor, options?: VisitorOptions): Promise<void>;
+declare function walk(node: Node, options: WalkOptions): Promise<void>;
 /**
  * Depth-first immutable transformation. Visitor return values replace nodes; `undefined` keeps the original.
  */
-declare function transform(node: RootNode, visitor: Visitor, options?: VisitorOptions): RootNode;
-declare function transform(node: OperationNode, visitor: Visitor, options?: VisitorOptions): OperationNode;
-declare function transform(node: SchemaNode, visitor: Visitor, options?: VisitorOptions): SchemaNode;
-declare function transform(node: PropertyNode, visitor: Visitor, options?: VisitorOptions): PropertyNode;
-declare function transform(node: ParameterNode, visitor: Visitor, options?: VisitorOptions): ParameterNode;
-declare function transform(node: ResponseNode, visitor: Visitor, options?: VisitorOptions): ResponseNode;
-declare function transform(node: Node, visitor: Visitor, options?: VisitorOptions): Node;
+declare function transform(node: RootNode, options: TransformOptions): RootNode;
+declare function transform(node: OperationNode, options: TransformOptions): OperationNode;
+declare function transform(node: SchemaNode, options: TransformOptions): SchemaNode;
+declare function transform(node: PropertyNode, options: TransformOptions): PropertyNode;
+declare function transform(node: ParameterNode, options: TransformOptions): ParameterNode;
+declare function transform(node: ResponseNode, options: TransformOptions): ResponseNode;
+declare function transform(node: Node, options: TransformOptions): Node;
+/**
+ * Combines multiple visitors into a single visitor that applies them sequentially (left to right).
+ * For each node kind, the output of one visitor becomes the input of the next.
+ */
+declare function composeTransformers(...visitors: Array<Visitor>): Visitor;
 /**
  * Depth-first synchronous reduction. Collects non-`undefined` visitor return values into an array.
  */
-declare function collect<T>(node: Node, visitor: CollectVisitor<T>, options?: VisitorOptions): Array<T>;
+declare function collect<T>(node: Node, options: CollectOptions<T>): Array<T>;
 //#endregion
-export { TimeSchemaNode as $, HttpStatusCode as A, EnumValueNode as B, createSchema as C, HttpMethod as D, RootNode as E, ArraySchemaNode as F, RefSchemaNode as G, NumberSchemaNode as H, ComplexSchemaType as I, SchemaNode as J, ScalarSchemaNode as K, DateSchemaNode as L, StatusCode as M, ParameterLocation as N, OperationNode as O, ParameterNode as P, StringSchemaNode as Q, DatetimeSchemaNode as R, createRoot as S, RootMeta as T, ObjectSchemaNode as U, IntersectionSchemaNode as V, PrimitiveSchemaType as W, SchemaType as X, SchemaNodeByType as Y, SpecialSchemaType as Z, createObjectBindingParameter as _, transform as a, FunctionParameterNode as at, createProperty as b, buildRefMap as c, BaseNode as ct, Printer as d, httpMethods as dt, UnionSchemaNode as et, PrinterFactoryOptions as f, mediaTypes as ft, createFunctionParameters as g, createFunctionParameter as h, collect as i, FunctionNodeType as it, MediaType as j, ResponseNode as k, refMapToObject as l, NodeKind as lt, DistributiveOmit as m, schemaTypes as mt, CollectVisitor as n, PropertyNode as nt, walk as o, FunctionParametersNode as ot, definePrinter as p, nodeKinds as pt, ScalarSchemaType as q, Visitor as r, FunctionNode as rt, RefMap as s, ObjectBindingParameterNode as st, AsyncVisitor as t, UrlSchemaNode as tt, resolveRef as u, VisitorDepth as ut, createOperation as v, Node as w, createResponse as x, createParameter as y, EnumSchemaNode as z };
-//# sourceMappingURL=visitor-D68E3x_d.d.ts.map
+export { ScalarSchemaNode as $, syncPropertySchema as A, ParameterLocation as B, createObjectBindingParameter as C, createResponse as D, createProperty as E, OperationNode as F, DatetimeSchemaNode as G, ArraySchemaNode as H, ResponseNode as I, IntersectionSchemaNode as J, EnumSchemaNode as K, HttpStatusCode as L, RootMeta as M, RootNode as N, createRoot as O, HttpMethod as P, RefSchemaNode as Q, MediaType as R, createFunctionParameters as S, createParameter as T, ComplexSchemaType as U, ParameterNode as V, DateSchemaNode as W, ObjectSchemaNode as X, NumberSchemaNode as Y, PrimitiveSchemaType as Z, Printer as _, VisitorDepth as _t, TransformOptions as a, StringSchemaNode as at, DistributiveOmit as b, nodeKinds as bt, WalkOptions as c, UrlSchemaNode as ct, transform as d, FunctionNodeType as dt, ScalarSchemaType as et, walk as f, FunctionParameterNode as ft, resolveRef as g, NodeKind as gt, refMapToObject as h, BaseNode as ht, ParentOf as i, SpecialSchemaType as it, Node as j, createSchema as k, collect as l, PropertyNode as lt, buildRefMap as m, ObjectBindingParameterNode as mt, CollectOptions as n, SchemaNodeByType as nt, Visitor as o, TimeSchemaNode as ot, RefMap as p, FunctionParametersNode as pt, EnumValueNode as q, CollectVisitor as r, SchemaType as rt, VisitorContext as s, UnionSchemaNode as st, AsyncVisitor as t, SchemaNode as tt, composeTransformers as u, FunctionNode as ut, PrinterFactoryOptions as v, httpMethods as vt, createOperation as w, createFunctionParameter as x, schemaTypes as xt, definePrinter as y, mediaTypes as yt, StatusCode as z };
+//# sourceMappingURL=visitor-UlWOe-In.d.ts.map

package/package.json

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

package/src/factory.ts

@@ -60,27 +60,48 @@ export function createSchema(props: Record<string, unknown>): Record<string, unk
   return { ...props, kind: 'Schema' }
 }
 
+/**
+ * Derives `schema.optional` and `schema.nullish` from `required` and `schema.nullable`.
+ * This keeps `PropertyNode.required` as the single source of truth for optionality.
+ */
+export function syncPropertySchema(required: boolean, schema: SchemaNode): SchemaNode {
+  const nullable = schema.nullable ?? false
+
+  return {
+    ...schema,
+    optional: !required && !nullable ? true : undefined,
+    nullish: !required && nullable ? true : undefined,
+  }
+}
+
 /**
  * Creates a `PropertyNode`. `required` defaults to `false`.
+ * `schema.optional` and `schema.nullish` are auto-derived from `required` and `schema.nullable`.
  */
 export function createProperty(props: Pick<PropertyNode, 'name' | 'schema'> & Partial<Omit<PropertyNode, 'kind' | 'name' | 'schema'>>): PropertyNode {
+  const required = props.required ?? false
+
   return {
-    required: false,
     ...props,
     kind: 'Property',
+    required,
+    schema: syncPropertySchema(required, props.schema),
   }
 }
 
 /**
  * Creates a `ParameterNode`. `required` defaults to `false`.
+ * `schema.optional` is auto-derived from `required` and `schema.nullable`.
  */
 export function createParameter(
   props: Pick<ParameterNode, 'name' | 'in' | 'schema'> & Partial<Omit<ParameterNode, 'kind' | 'name' | 'in' | 'schema'>>,
 ): ParameterNode {
+  const required = props.required ?? false
   return {
-    required: false,
     ...props,
     kind: 'Parameter',
+    required,
+    schema: syncPropertySchema(required, props.schema),
   }
 }
 

package/src/index.ts

@@ -9,6 +9,7 @@ export {
   createResponse,
   createRoot,
   createSchema,
+  syncPropertySchema,
 } from './factory.ts'
 export { functionPrinter } from './functionPrinter.ts'
 export {
@@ -26,4 +27,4 @@ export {
 export { definePrinter } from './printer.ts'
 export { buildRefMap, refMapToObject, resolveRef } from './refs.ts'
 export { applyParamsCasing, isPlainStringType } from './utils.ts'
-export { collect, transform, walk } from './visitor.ts'
+export { collect, composeTransformers, transform, walk } from './visitor.ts'

package/src/types.ts

@@ -44,4 +44,4 @@ export type {
 } from './nodes/index.ts'
 export type { Printer, PrinterFactoryOptions } from './printer.ts'
 export type { RefMap } from './refs.ts'
-export type { AsyncVisitor, CollectVisitor, Visitor } from './visitor.ts'
+export type { AsyncVisitor, CollectOptions, CollectVisitor, ParentOf, TransformOptions, Visitor, VisitorContext, WalkOptions } from './visitor.ts'

package/src/visitor.ts

@@ -1,5 +1,6 @@
 import type { VisitorDepth } from './constants.ts'
 import { visitorDepths, WALK_CONCURRENCY } from './constants.ts'
+import { createParameter, createProperty } from './factory.ts'
 import type { Node, OperationNode, ParameterNode, PropertyNode, ResponseNode, RootNode, SchemaNode } from './nodes/index.ts'
 
 /**
@@ -35,27 +36,47 @@ function createLimit(concurrency: number) {
 type LimitFn = ReturnType<typeof createLimit>
 
 /**
- * Shared options for `walk`, `transform`, and `collect`.
+ * Single source of truth: ordered list of `[NodeType, ParentType]` pairs
+ * describing which node types can be the parent of a given node in the AST.
+ *
+ * `ParentOf` walks this tuple and returns the parent type of the first matching entry.
  */
-export type VisitorOptions = {
-  depth?: VisitorDepth
-  /**
-   * Maximum number of sibling nodes visited concurrently inside `walk`.
-   * @default 30
-   */
-  concurrency?: number
+type ParentNodeMap = [
+  [RootNode, undefined],
+  [OperationNode, RootNode],
+  [SchemaNode, RootNode | OperationNode | SchemaNode | PropertyNode | ParameterNode | ResponseNode],
+  [PropertyNode, SchemaNode],
+  [ParameterNode, OperationNode],
+  [ResponseNode, OperationNode],
+]
+
+export type ParentOf<T extends Node, TEntries extends ReadonlyArray<[Node, unknown]> = ParentNodeMap> = TEntries extends [
+  infer TEntry extends [Node, unknown],
+  ...infer TRest extends ReadonlyArray<[Node, unknown]>,
+]
+  ? T extends TEntry[0]
+    ? TEntry[1]
+    : ParentOf<T, TRest>
+  : Node
+
+/**
+ * Traversal context passed as the second argument to every visitor callback.
+ * The `parent` field is narrowed based on the node type being visited.
+ */
+export type VisitorContext<T extends Node = Node> = {
+  parent?: ParentOf<T>
 }
 
 /**
  * Synchronous visitor for `transform` and `walk`.
  */
 export type Visitor = {
-  root?(node: RootNode): void | RootNode
-  operation?(node: OperationNode): void | OperationNode
-  schema?(node: SchemaNode): void | SchemaNode
-  property?(node: PropertyNode): void | PropertyNode
-  parameter?(node: ParameterNode): void | ParameterNode
-  response?(node: ResponseNode): void | ResponseNode
+  root?(node: RootNode, context: VisitorContext<RootNode>): void | RootNode
+  operation?(node: OperationNode, context: VisitorContext<OperationNode>): void | OperationNode
+  schema?(node: SchemaNode, context: VisitorContext<SchemaNode>): void | SchemaNode
+  property?(node: PropertyNode, context: VisitorContext<PropertyNode>): void | PropertyNode
+  parameter?(node: ParameterNode, context: VisitorContext<ParameterNode>): void | ParameterNode
+  response?(node: ResponseNode, context: VisitorContext<ResponseNode>): void | ResponseNode
 }
 
 type MaybePromise<T> = T | Promise<T>
@@ -64,24 +85,52 @@ type MaybePromise<T> = T | Promise<T>
  * Async visitor for `walk`. Synchronous `Visitor` objects are compatible.
  */
 export type AsyncVisitor = {
-  root?(node: RootNode): MaybePromise<void | RootNode>
-  operation?(node: OperationNode): MaybePromise<void | OperationNode>
-  schema?(node: SchemaNode): MaybePromise<void | SchemaNode>
-  property?(node: PropertyNode): MaybePromise<void | PropertyNode>
-  parameter?(node: ParameterNode): MaybePromise<void | ParameterNode>
-  response?(node: ResponseNode): MaybePromise<void | ResponseNode>
+  root?(node: RootNode, context: VisitorContext<RootNode>): MaybePromise<void | RootNode>
+  operation?(node: OperationNode, context: VisitorContext<OperationNode>): MaybePromise<void | OperationNode>
+  schema?(node: SchemaNode, context: VisitorContext<SchemaNode>): MaybePromise<void | SchemaNode>
+  property?(node: PropertyNode, context: VisitorContext<PropertyNode>): MaybePromise<void | PropertyNode>
+  parameter?(node: ParameterNode, context: VisitorContext<ParameterNode>): MaybePromise<void | ParameterNode>
+  response?(node: ResponseNode, context: VisitorContext<ResponseNode>): MaybePromise<void | ResponseNode>
 }
 
 /**
  * Visitor for `collect`.
  */
 export type CollectVisitor<T> = {
-  root?(node: RootNode): T | undefined
-  operation?(node: OperationNode): T | undefined
-  schema?(node: SchemaNode): T | undefined
-  property?(node: PropertyNode): T | undefined
-  parameter?(node: ParameterNode): T | undefined
-  response?(node: ResponseNode): T | undefined
+  root?(node: RootNode, context: VisitorContext<RootNode>): T | undefined
+  operation?(node: OperationNode, context: VisitorContext<OperationNode>): T | undefined
+  schema?(node: SchemaNode, context: VisitorContext<SchemaNode>): T | undefined
+  property?(node: PropertyNode, context: VisitorContext<PropertyNode>): T | undefined
+  parameter?(node: ParameterNode, context: VisitorContext<ParameterNode>): T | undefined
+  response?(node: ResponseNode, context: VisitorContext<ResponseNode>): T | undefined
+}
+
+/**
+ * Options for `transform` and `collect`. Extends `Visitor` with traversal settings.
+ */
+export type TransformOptions = Visitor & {
+  depth?: VisitorDepth
+  parent?: Node
+}
+
+/**
+ * Options for `walk`. Extends `AsyncVisitor` with traversal settings.
+ */
+export type WalkOptions = AsyncVisitor & {
+  depth?: VisitorDepth
+  /**
+   * Maximum number of sibling nodes visited concurrently.
+   * @default 30
+   */
+  concurrency?: number
+}
+
+/**
+ * Options for `collect`. Extends `CollectVisitor` with traversal settings.
+ */
+export type CollectOptions<T> = CollectVisitor<T> & {
+  depth?: VisitorDepth
+  parent?: Node
 }
 
 /**
@@ -125,34 +174,31 @@ function getChildren(node: Node, recurse: boolean): Array<Node> {
  * Depth-first traversal for side effects. Visitor return values are ignored.
  * Sibling nodes at each level are visited concurrently up to `options.concurrency` (default: 30).
  */
-export async function walk(node: Node, visitor: AsyncVisitor, options: VisitorOptions = {}): Promise<void> {
+export async function walk(node: Node, options: WalkOptions): Promise<void> {
   const recurse = (options.depth ?? visitorDepths.deep) === visitorDepths.deep
   const limit = createLimit(options.concurrency ?? WALK_CONCURRENCY)
-  return _walk(node, visitor, recurse, limit)
+  return _walk(node, options, recurse, limit, undefined)
 }
 
-/**
- * Internal recursive walk implementation — calls visitor then recurses into children.
- */
-async function _walk(node: Node, visitor: AsyncVisitor, recurse: boolean, limit: LimitFn): Promise<void> {
+async function _walk(node: Node, visitor: AsyncVisitor, recurse: boolean, limit: LimitFn, parent: Node | undefined): Promise<void> {
   switch (node.kind) {
     case 'Root':
-      await limit(() => visitor.root?.(node))
+      await limit(() => visitor.root?.(node, { parent: parent as ParentOf<RootNode> }))
       break
     case 'Operation':
-      await limit(() => visitor.operation?.(node))
+      await limit(() => visitor.operation?.(node, { parent: parent as ParentOf<OperationNode> }))
       break
     case 'Schema':
-      await limit(() => visitor.schema?.(node))
+      await limit(() => visitor.schema?.(node, { parent: parent as ParentOf<SchemaNode> }))
       break
     case 'Property':
-      await limit(() => visitor.property?.(node))
+      await limit(() => visitor.property?.(node, { parent: parent as ParentOf<PropertyNode> }))
       break
     case 'Parameter':
-      await limit(() => visitor.parameter?.(node))
+      await limit(() => visitor.parameter?.(node, { parent: parent as ParentOf<ParameterNode> }))
       break
     case 'Response':
-      await limit(() => visitor.response?.(node))
+      await limit(() => visitor.response?.(node, { parent: parent as ParentOf<ResponseNode> }))
       break
     case 'FunctionParameter':
     case 'ObjectBindingParameter':
@@ -161,91 +207,94 @@ async function _walk(node: Node, visitor: AsyncVisitor, recurse: boolean, limit:
   }
 
   const children = getChildren(node, recurse)
-  await Promise.all(children.map((child) => _walk(child, visitor, recurse, limit)))
+  await Promise.all(children.map((child) => _walk(child, visitor, recurse, limit, node)))
 }
 
 /**
  * Depth-first immutable transformation. Visitor return values replace nodes; `undefined` keeps the original.
  */
-export function transform(node: RootNode, visitor: Visitor, options?: VisitorOptions): RootNode
-export function transform(node: OperationNode, visitor: Visitor, options?: VisitorOptions): OperationNode
-export function transform(node: SchemaNode, visitor: Visitor, options?: VisitorOptions): SchemaNode
-export function transform(node: PropertyNode, visitor: Visitor, options?: VisitorOptions): PropertyNode
-export function transform(node: ParameterNode, visitor: Visitor, options?: VisitorOptions): ParameterNode
-export function transform(node: ResponseNode, visitor: Visitor, options?: VisitorOptions): ResponseNode
-export function transform(node: Node, visitor: Visitor, options?: VisitorOptions): Node
-export function transform(node: Node, visitor: Visitor, options: VisitorOptions = {}): Node {
-  const recurse = (options.depth ?? visitorDepths.deep) === visitorDepths.deep
+export function transform(node: RootNode, options: TransformOptions): RootNode
+export function transform(node: OperationNode, options: TransformOptions): OperationNode
+export function transform(node: SchemaNode, options: TransformOptions): SchemaNode
+export function transform(node: PropertyNode, options: TransformOptions): PropertyNode
+export function transform(node: ParameterNode, options: TransformOptions): ParameterNode
+export function transform(node: ResponseNode, options: TransformOptions): ResponseNode
+export function transform(node: Node, options: TransformOptions): Node
+export function transform(node: Node, options: TransformOptions): Node {
+  const { depth, parent, ...visitor } = options
+  const recurse = (depth ?? visitorDepths.deep) === visitorDepths.deep
 
   switch (node.kind) {
     case 'Root': {
       let root = node
-      const replaced = visitor.root?.(root)
+      const replaced = visitor.root?.(root, { parent: parent as ParentOf<RootNode> })
       if (replaced) root = replaced
 
       return {
         ...root,
-        schemas: root.schemas.map((s) => transform(s, visitor, options)),
-        operations: root.operations.map((op) => transform(op, visitor, options)),
+        schemas: root.schemas.map((s) => transform(s, { ...options, parent: root })),
+        operations: root.operations.map((op) => transform(op, { ...options, parent: root })),
       }
     }
     case 'Operation': {
       let op = node
-      const replaced = visitor.operation?.(op)
+      const replaced = visitor.operation?.(op, { parent: parent as ParentOf<OperationNode> })
       if (replaced) op = replaced
 
       return {
         ...op,
-        parameters: op.parameters.map((p) => transform(p, visitor, options)),
+        parameters: op.parameters.map((p) => transform(p, { ...options, parent: op })),
         requestBody: op.requestBody
-          ? { ...op.requestBody, schema: op.requestBody.schema ? transform(op.requestBody.schema, visitor, options) : undefined }
+          ? { ...op.requestBody, schema: op.requestBody.schema ? transform(op.requestBody.schema, { ...options, parent: op }) : undefined }
           : undefined,
-        responses: op.responses.map((r) => transform(r, visitor, options)),
+        responses: op.responses.map((r) => transform(r, { ...options, parent: op })),
       }
     }
     case 'Schema': {
       let schema = node
-      const replaced = visitor.schema?.(schema)
+      const replaced = visitor.schema?.(schema, { parent: parent as ParentOf<SchemaNode> })
       if (replaced) schema = replaced
 
+      const childOptions = { ...options, parent: schema }
+
       return {
         ...schema,
-        ...('properties' in schema && recurse ? { properties: schema.properties.map((p) => transform(p, visitor, options)) } : {}),
-        ...('items' in schema && recurse ? { items: schema.items?.map((i) => transform(i, visitor, options)) } : {}),
-        ...('members' in schema && recurse ? { members: schema.members?.map((m) => transform(m, visitor, options)) } : {}),
+        ...('properties' in schema && recurse ? { properties: schema.properties.map((p) => transform(p, childOptions)) } : {}),
+        ...('items' in schema && recurse ? { items: schema.items?.map((i) => transform(i, childOptions)) } : {}),
+        ...('members' in schema && recurse ? { members: schema.members?.map((m) => transform(m, childOptions)) } : {}),
         ...('additionalProperties' in schema && recurse && schema.additionalProperties && schema.additionalProperties !== true
-          ? { additionalProperties: transform(schema.additionalProperties, visitor, options) }
+          ? { additionalProperties: transform(schema.additionalProperties, childOptions) }
           : {}),
-      }
+      } as SchemaNode
     }
     case 'Property': {
       let prop = node
-      const replaced = visitor.property?.(prop)
+      const replaced = visitor.property?.(prop, { parent: parent as ParentOf<PropertyNode> })
       if (replaced) prop = replaced
 
-      return {
+      return createProperty({
         ...prop,
-        schema: transform(prop.schema, visitor, options),
-      }
+        schema: transform(prop.schema, { ...options, parent: prop }),
+      })
     }
     case 'Parameter': {
       let param = node
-      const replaced = visitor.parameter?.(param)
+      const replaced = visitor.parameter?.(param, { parent: parent as ParentOf<ParameterNode> })
       if (replaced) param = replaced
 
-      return {
+      return createParameter({
         ...param,
-        schema: transform(param.schema, visitor, options),
-      }
+        schema: transform(param.schema, { ...options, parent: param }),
+      })
     }
     case 'Response': {
       let response = node
-      const replaced = visitor.response?.(response)
+      const replaced = visitor.response?.(response, { parent: parent as ParentOf<ResponseNode> })
       if (replaced) response = replaced
 
       return {
         ...response,
-        schema: transform(response.schema, visitor, options),
+        schema: transform(response.schema, { ...options, parent: response }),
       }
     }
     case 'FunctionParameter':
@@ -255,32 +304,60 @@ export function transform(node: Node, visitor: Visitor, options: VisitorOptions
   }
 }
 
+/**
+ * Combines multiple visitors into a single visitor that applies them sequentially (left to right).
+ * For each node kind, the output of one visitor becomes the input of the next.
+ */
+export function composeTransformers(...visitors: Array<Visitor>): Visitor {
+  return {
+    root(node, context) {
+      return visitors.reduce<RootNode>((acc, v) => v.root?.(acc, context) ?? acc, node)
+    },
+    operation(node, context) {
+      return visitors.reduce<OperationNode>((acc, v) => v.operation?.(acc, context) ?? acc, node)
+    },
+    schema(node, context) {
+      return visitors.reduce<SchemaNode>((acc, v) => v.schema?.(acc, context) ?? acc, node)
+    },
+    property(node, context) {
+      return visitors.reduce<PropertyNode>((acc, v) => v.property?.(acc, context) ?? acc, node)
+    },
+    parameter(node, context) {
+      return visitors.reduce<ParameterNode>((acc, v) => v.parameter?.(acc, context) ?? acc, node)
+    },
+    response(node, context) {
+      return visitors.reduce<ResponseNode>((acc, v) => v.response?.(acc, context) ?? acc, node)
+    },
+  }
+}
+
 /**
  * Depth-first synchronous reduction. Collects non-`undefined` visitor return values into an array.
  */
-export function collect<T>(node: Node, visitor: CollectVisitor<T>, options: VisitorOptions = {}): Array<T> {
-  const recurse = (options.depth ?? visitorDepths.deep) === visitorDepths.deep
+export function collect<T>(node: Node, options: CollectOptions<T>): Array<T> {
+  const { depth, parent, ...visitor } = options
+  const recurse = (depth ?? visitorDepths.deep) === visitorDepths.deep
   const results: Array<T> = []
 
   let v: T | undefined
   switch (node.kind) {
     case 'Root':
-      v = visitor.root?.(node)
+      v = visitor.root?.(node, { parent: parent as ParentOf<RootNode> })
       break
     case 'Operation':
-      v = visitor.operation?.(node)
+      v = visitor.operation?.(node, { parent: parent as ParentOf<OperationNode> })
       break
     case 'Schema':
-      v = visitor.schema?.(node)
+      v = visitor.schema?.(node, { parent: parent as ParentOf<SchemaNode> })
       break
     case 'Property':
-      v = visitor.property?.(node)
+      v = visitor.property?.(node, { parent: parent as ParentOf<PropertyNode> })
       break
     case 'Parameter':
-      v = visitor.parameter?.(node)
+      v = visitor.parameter?.(node, { parent: parent as ParentOf<ParameterNode> })
       break
     case 'Response':
-      v = visitor.response?.(node)
+      v = visitor.response?.(node, { parent: parent as ParentOf<ResponseNode> })
       break
     case 'FunctionParameter':
     case 'ObjectBindingParameter':
@@ -290,7 +367,7 @@ export function collect<T>(node: Node, visitor: CollectVisitor<T>, options: Visi
   if (v !== undefined) results.push(v)
 
   for (const child of getChildren(node, recurse)) {
-    for (const item of collect(child, visitor, options)) {
+    for (const item of collect(child, { ...options, parent: node })) {
       results.push(item)
     }
   }