@kubb/ast 5.0.0-beta.36 → 5.0.0-beta.38

package/src/nodes/function.ts

@@ -4,9 +4,9 @@ import type { BaseNode } from './base.ts'
  * AST node representing a language-agnostic type expression used as a function parameter
  * type annotation. Each language printer renders the variant into its own syntax.
  *
- * - `struct` — an inline anonymous type grouping named fields.
+ * - `struct` an inline anonymous type grouping named fields.
  *   TypeScript renders as `{ petId: string; name?: string }`.
- * - `member` — a single named field accessed from a named group type.
+ * - `member` a single named field accessed from a named group type.
  *   TypeScript renders as `PathParams['petId']`.
  *
  * @example Reference variant
@@ -35,7 +35,7 @@ export type ParamsTypeNode = BaseNode & {
 } & (
     | {
         /**
-         * Reference variant — a plain type name or identifier.
+         * Reference variant, a plain type name or identifier.
          * TypeScript renders as-is, e.g. `string`, `QueryParams`, `Partial<Config>`.
          */
         variant: 'reference'
@@ -46,7 +46,7 @@ export type ParamsTypeNode = BaseNode & {
       }
     | {
         /**
-         * Struct variant — an inline anonymous type grouping named fields.
+         * Struct variant, an inline anonymous type grouping named fields.
          * TypeScript renders as `{ key: Type; other?: OtherType }`.
          */
         variant: 'struct'
@@ -61,7 +61,7 @@ export type ParamsTypeNode = BaseNode & {
       }
     | {
         /**
-         * Member variant — a single named field accessed from a group type.
+         * Member variant, a single named field accessed from a group type.
          * TypeScript renders as `Base['key']`.
          */
         variant: 'member'
@@ -122,7 +122,7 @@ export type FunctionParameterNode = BaseNode & {
    */
   rest?: boolean
 } /**
- * Optional parameter — rendered with `?` and may be omitted by the caller.
+ * Optional parameter, rendered with `?` and may be omitted by the caller.
  * Cannot be combined with `default` because a defaulted parameter is already optional.
  */ & (
     | { optional: true; default?: never }
@@ -196,10 +196,10 @@ export type ParameterGroupNode = BaseNode & {
  * Nodes are plain immutable data.
  *
  * Renders differently depending on the output mode:
- * - `declaration` → `(id: string, config: Config = {})` — function declaration parameters
- * - `call`        → `(id, { method, url })` — function call arguments
- * - `keys`        → `{ id, config }` — key names only (for destructuring)
- * - `values`      → `{ id: id, config: config }` — key → value pairs
+ * - `declaration` → `(id: string, config: Config = {})` function declaration parameters
+ * - `call`        → `(id, { method, url })` function call arguments
+ * - `keys`        → `{ id, config }` key names only (for destructuring)
+ * - `values`      → `{ id: id, config: config }` key → value pairs
  */
 export type FunctionParametersNode = BaseNode & {
   /**
@@ -218,6 +218,6 @@ export type FunctionParametersNode = BaseNode & {
 export type FunctionParamNode = FunctionParameterNode | ParameterGroupNode | FunctionParametersNode | ParamsTypeNode
 
 /**
- * Handler map keys — one per `FunctionParamNode` kind.
+ * Handler map keys, one per `FunctionParamNode` kind.
  */
 export type FunctionNodeType = 'functionParameter' | 'parameterGroup' | 'functionParameters' | 'paramsType'

package/src/nodes/root.ts

@@ -5,7 +5,7 @@ import type { SchemaNode } from './schema.ts'
 /**
  * Metadata for an API document, populated by the adapter and available to every generator.
  *
- * All fields are plain JSON-serializable values — no `Set`, no `Map`, no class instances.
+ * All fields are plain JSON-serializable values, no `Set`, no `Map`, no class instances.
  * Computed fields (`circularNames`, `enumNames`) are pre-calculated once during the adapter
  * pre-scan so generators never need to iterate the full schema list themselves.
  *
@@ -33,7 +33,7 @@ export type InputMeta = {
   baseURL?: string | null
   /**
    * Names of schemas that participate in a circular reference chain.
-   * Computed once during the adapter pre-scan — use this instead of calling
+   * Computed once during the adapter pre-scan, use this instead of calling
    * `findCircularSchemas` per generator call.
    *
    * Convert to a `Set` once at the start of a generator, not per-schema,
@@ -48,7 +48,7 @@ export type InputMeta = {
   circularNames: ReadonlyArray<string>
   /**
    * Names of schemas whose type is `enum`.
-   * Computed once during the adapter pre-scan — use this instead of filtering
+   * Computed once during the adapter pre-scan, use this instead of filtering
    * schemas per generator call.
    *
    * Convert to a `Set` once at the start of a generator when you need repeated
@@ -96,14 +96,14 @@ export type InputNode = BaseNode & {
 /**
  * Streaming variant of `InputNode` for memory-efficient processing of large API specs.
  *
- * `schemas` and `operations` are `AsyncIterable` rather than arrays — each `for await`
+ * `schemas` and `operations` are `AsyncIterable` rather than arrays, each `for await`
  * loop creates a fresh parse pass from the cached in-memory document, so multiple
  * consumers (plugins) can iterate independently without keeping all nodes in memory.
  *
  * @example
  * ```ts
  * for await (const schema of inputStreamNode.schemas) {
- *   // only this one SchemaNode is live here; previous ones are GC-eligible
+ *   // only this one SchemaNode is live here. Previous ones are GC-eligible
  * }
  * ```
  */

package/src/nodes/schema.ts

@@ -178,7 +178,7 @@ export type ObjectSchemaNode = SchemaNodeBase & {
    */
   type: 'object'
   /**
-   * Primitive type — always `'object'` for object schemas.
+   * Primitive type, always `'object'` for object schemas.
    */
   primitive: 'object'
   /**
@@ -381,13 +381,10 @@ export type RefSchemaNode = SchemaNodeBase & {
    */
   pattern?: string
   /**
-   * The fully-parsed schema that this ref resolves to.
-   * Populated during OAS parsing when the referenced definition can be resolved.
-   * `null` when the ref cannot be resolved or is part of a circular chain.
-   * `undefined` when resolution has not been attempted.
-   *
-   * Useful for inspecting the referenced schema's structure (e.g. `primitive`, `properties`)
-   * without following the reference manually.
+   * The fully-parsed schema this ref resolves to, so its structure (`primitive`, `properties`)
+   * can be read without following the reference. Populated during OAS parsing when the
+   * definition resolves, `null` when it can't or the ref is circular, and `undefined` when
+   * resolution has not been attempted.
    */
   schema?: SchemaNode | null
 }

package/src/printer.ts

@@ -46,7 +46,7 @@ export type PrinterHandler<TOutput, TOptions extends object, T extends SchemaTyp
  * Partial map of per-node-type handler overrides for a printer.
  *
  * Each key is a `SchemaType` string (e.g. `'date'`, `'string'`).
- * Supply only the handlers you want to replace; the printer's built-in
+ * Supply only the handlers you want to replace. The printer's built-in
  * defaults fill in the rest.
  *
  * @example
@@ -69,10 +69,10 @@ export type PrinterPartial<TOutput, TOptions extends object> = Partial<{
 /**
  * Generic shape used by `definePrinter`.
  *
- * - `TName`        — unique string identifier (e.g. `'zod'`, `'ts'`)
- * - `TOptions`     — options passed to and stored on the printer instance
- * - `TOutput`      — the type emitted by node handlers
- * - `TPrintOutput` — type returned by public `print` (defaults to `TOutput`)
+ * - `TName` unique string identifier (e.g. `'zod'`, `'ts'`)
+ * - `TOptions` options passed to and stored on the printer instance
+ * - `TOutput` the type emitted by node handlers
+ * - `TPrintOutput` type returned by public `print` (defaults to `TOutput`)
  *
  * @example
  * ```ts
@@ -104,8 +104,8 @@ export type Printer<T extends PrinterFactoryOptions = PrinterFactoryOptions> = {
    */
   options: T['options']
   /**
-   * Node-level dispatcher — converts a `SchemaNode` directly to `TOutput` using the `nodes` handlers.
-   * Always dispatches through the `nodes` map; never calls the `print` override.
+   * Node-level dispatcher, converts a `SchemaNode` directly to `TOutput` using the `nodes` handlers.
+   * Always dispatches through the `nodes` map. Never calls the `print` override.
    * Use this when you need the raw output (e.g. `ts.TypeNode`) without declaration wrapping.
    */
   transform: (node: SchemaNode) => T['output'] | null
@@ -143,7 +143,7 @@ type PrinterBuilder<T extends PrinterFactoryOptions> = (options: T['options']) =
   /**
    * Optional root-level print override. When provided, becomes the public `printer.print`.
    * Use `this.transform(node)` inside this function to dispatch to the node-level handlers (`nodes`),
-   * not the override itself — so recursion is safe.
+   * not the override itself, so recursion is safe.
    */
   print?: (this: PrinterHandlerContext<T['output'], T['options']>, node: SchemaNode) => T['printOutput'] | null
 }
@@ -155,11 +155,11 @@ type PrinterBuilder<T extends PrinterFactoryOptions> = (options: T['options']) =
  *
  * The builder receives resolved options and returns:
  *
- * - `name` — unique identifier for the printer.
- * - `options` — stored on the returned printer instance.
- * - `nodes` — map of `SchemaType` → handler. Handlers return the rendered
+ * - `name` unique identifier for the printer.
+ * - `options` stored on the returned printer instance.
+ * - `nodes` map of `SchemaType` → handler. Handlers return the rendered
  *   output (a string, a TypeScript AST node, ...) for that schema type.
- * - `print` (optional) — top-level override exposed as `printer.print`.
+ * - `print` (optional), top-level override exposed as `printer.print`.
  *   Use `this.transform(node)` inside it to dispatch to `nodes` recursively.
  *
  * Without a `print` override, `printer.print` falls back to `printer.transform`

package/src/signature.ts

@@ -5,7 +5,7 @@ import { extractRefName } from './refs.ts'
 /**
  * The shape-affecting flags shared by every node kind: base primitive, format, and `nullable`.
  * Documentation and usage-slot flags (`optional`/`nullish`/`readOnly`/`writeOnly`) are
- * intentionally excluded — they describe the property slot, not the type.
+ * intentionally excluded, they describe the property slot, not the type.
  */
 function flagsDescriptor(node: SchemaNode): string {
   return `${node.primitive ?? ''};${node.format ?? ''};${node.nullable ? 1 : 0}`
@@ -157,7 +157,7 @@ function serializeShapeField(field: ShapeField, node: SchemaNode, record: Record
 
 /**
  * Builds the local, shape-only descriptor for a node: its kind, flags, constraints, and its
- * children's signatures. {@link signatureOf} hashes this string; children contribute their
+ * children's signatures. {@link signatureOf} hashes this string. Children contribute their
  * fixed-length signature rather than their own full descriptor, which keeps the result bounded.
  */
 function describeShape(node: SchemaNode): string {
@@ -180,7 +180,7 @@ function describeShape(node: SchemaNode): string {
  * during dedupe planning is not re-hashed when the same tree is rewritten during streaming
  * (where `schemaSignature` and `applyDedupe` would otherwise each walk it from scratch). Reuse
  * across calls is sound because a signature depends only on a node's content, and schema nodes
- * are immutable once created — transforms allocate new objects rather than mutating in place.
+ * are immutable once created, transforms allocate new objects rather than mutating in place.
  */
 const signatureCache = new WeakMap<SchemaNode, string>()
 
@@ -188,7 +188,7 @@ const signatureCache = new WeakMap<SchemaNode, string>()
  * Hash-consing: each node's signature is a fixed-length digest of its local shape plus its
  * children's digests (a Merkle hash). Children contribute their 64-char hash instead of their
  * full nested descriptor, so a signature stays bounded regardless of subtree depth, and the
- * digest is identical across calls because it depends only on content — never on traversal
+ * digest is identical across calls because it depends only on content, never on traversal
  * order. This keeps the keys built during planning consistent with the ones recomputed later
  * during streaming. {@link signatureCache} memoizes node → digest across every computation.
  */

package/src/utils.ts

@@ -249,7 +249,7 @@ export type CreateOperationParamsOptions = {
    * Applies a uniform transformation to every resolved type name before it is used
    * in a parameter node. Use this for framework-level type wrappers.
    *
-   * @example Vue Query — wrap every parameter type with `MaybeRefOrGetter`
+   * @example Vue Query, wrap every parameter type with `MaybeRefOrGetter`
    * `typeWrapper: (t) => \`MaybeRefOrGetter<${t}>\``
    */
   typeWrapper?: (type: string) => string
@@ -315,7 +315,7 @@ export function createOperationParams(node: OperationNode, options: CreateOperat
       variant: 'reference',
       name: typeWrapper ? typeWrapper(type) : type,
     })
-  // Only reference-variant TypeNodes are wrapped — they hold a plain type name string that needs casing applied.
+  // Only reference-variant TypeNodes are wrapped, they hold a plain type name string that needs casing applied.
   // Member and struct TypeNodes are pre-resolved structured expressions and are passed through unchanged.
   const wrapTypeNode = (type: ParamsTypeNode): ParamsTypeNode => (type.kind === 'ParamsType' && type.variant === 'reference' ? wrapType(type.name) : type)
 
@@ -570,7 +570,7 @@ function importKey(path: string, name: string | null | undefined, isTypeOnly: bo
 
 /**
  * Computes a multi-level sort key for exports and imports:
- * non-array names first (wildcards/namespace aliases); type-only before value; alphabetical path; unnamed before named.
+ * non-array names first (wildcards/namespace aliases). Type-only before value. Alphabetical path. Unnamed before named.
  */
 function sortKey(node: { name?: string | Array<unknown> | null; isTypeOnly?: boolean | null; path: string }): string {
   const isArray = Array.isArray(node.name) ? '1' : '0'
@@ -618,7 +618,7 @@ export function combineExports(exports: Array<ExportNode>): Array<ExportNode> {
   // Deduplicates non-array exports by their exact identity
   const seen = new Set<string>()
 
-  // Precompute sort keys once — avoids recomputing per comparison.
+  // Precompute sort keys once, avoids recomputing per comparison.
   const keyed = exports.map((node) => ({ node, key: sortKey(node) }))
   keyed.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
 
@@ -664,7 +664,7 @@ export function combineImports(imports: Array<ImportNode>, exports: Array<Export
   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.
+  // 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
@@ -674,7 +674,7 @@ export function combineImports(imports: Array<ImportNode>, exports: Array<Export
   }
 
   // Paths that keep at least one used named import. A default import from such a path is retained
-  // even when its binding can't be found in `source` — e.g. a generated `client` default import
+  // even when its binding can't be found in `source` e.g. a generated `client` default import
   // alongside `import type { Client } from <same path>`, where merged grouped output omits the body.
   const pathsWithUsedNamedImport = new Set<string>()
   for (const node of imports) {
@@ -690,7 +690,7 @@ export function combineImports(imports: Array<ImportNode>, exports: Array<Export
   // Deduplicates non-array imports by their exact identity
   const seen = new Set<string>()
 
-  // Precompute sort keys once — avoids recomputing per comparison.
+  // Precompute sort keys once, avoids recomputing per comparison.
   const keyed = imports.map((node) => ({ node, key: sortKey(node) }))
   keyed.sort((a, b) => (a.key < b.key ? -1 : a.key > b.key ? 1 : 0))
 
@@ -783,7 +783,7 @@ export function resolveRefName(node: SchemaNode | undefined): string | null {
 /**
  * Collects every named schema referenced (transitively) from a node via ref edges.
  *
- * Refs are followed by name only — the resolved `node.schema` is not traversed inline.
+ * 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.
  *
  * @example Collect refs from a single schema
@@ -823,7 +823,7 @@ export function collectReferencedSchemaNames(node: SchemaNode | undefined, 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.
+ * 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`
@@ -934,7 +934,7 @@ export function findCircularSchemas(schemas: ReadonlyArray<SchemaNode>): Set<str
  * Use `excludeName` to ignore refs to specific schemas (useful when self-references are handled separately).
  * Commonly used with `findCircularSchemas()` to detect where lazy wrappers are needed in code generation.
  *
- * @note Returns `true` for the first matching circular ref found; use for fast dependency checks.
+ * @note Returns `true` for the first matching circular ref found. Use for fast dependency checks.
  */
 export function containsCircularRef(
   node: SchemaNode | undefined,

package/src/visitor.ts

@@ -284,8 +284,8 @@ export type CollectOptions<T> = CollectVisitor<T> & {
 /**
  * Child node fields per node kind, in traversal order (Babel's `VISITOR_KEYS`).
  *
- * Each listed property holds a child node, an array of child nodes, or — for
- * `additionalProperties` — a node or the literal `true` (skipped). Every value
+ * Each listed property holds a child node, an array of child nodes, or, for
+ * `additionalProperties` a node or the literal `true` (skipped). Every value
  * in a child slot is a node, so one table drives both `getChildren` and `transform`.
  */
 const VISITOR_KEYS = {
@@ -311,7 +311,7 @@ function isNode(value: unknown): value is Node {
 /**
  * Returns the immediate traversable children of `node` based on {@link VISITOR_KEYS}.
  *
- * `Schema` children are only included when `recurse` is `true`; shallow mode skips them.
+ * `Schema` children are only included when `recurse` is `true`. Shallow mode skips them.
  *
  * @example
  * ```ts
@@ -338,7 +338,7 @@ function* getChildren(node: Node, recurse: boolean): Generator<Node, void, undef
 
 /**
  * Maps a node `kind` to the matching visitor callback name. Only the seven
- * traversable node kinds have an entry; every other kind resolves to
+ * traversable node kinds have an entry. Every other kind resolves to
  * `undefined` and is skipped.
  */
 const VISITOR_KEY_BY_KIND: Partial<Record<NodeKind, keyof Visitor>> = {
@@ -375,7 +375,7 @@ function applyVisitor<TResult>(node: Node, visitor: Visitor | AsyncVisitor | Col
  *
  * Sibling nodes at each depth run concurrently up to `options.concurrency`
  * (defaults to `WALK_CONCURRENCY`). Higher values overlap I/O-bound visitor
- * work; lower values reduce memory pressure.
+ * work. Lower values reduce memory pressure.
  *
  * @example Log every operation
  * ```ts
@@ -403,7 +403,7 @@ async function _walk(node: Node, visitor: AsyncVisitor, recurse: boolean, limit:
 
   // Visit siblings concurrently and let the shared `limit` cap how many callbacks
   // run at once. Awaiting each child sequentially here would serialize the whole
-  // traversal and make `concurrency` inert — every visitor callback would run one
+  // traversal and make `concurrency` inert, every visitor callback would run one
   // at a time regardless of the limit.
   const children = Array.from(getChildren(node, recurse))
   if (children.length === 0) return
@@ -415,7 +415,7 @@ async function _walk(node: Node, visitor: AsyncVisitor, recurse: boolean, limit:
  * Synchronous depth-first transform. Each visitor callback gets a chance to
  * return a replacement node; `undefined` keeps the original.
  *
- * The transform is immutable. The original tree is not mutated; a new tree
+ * The transform is immutable. The original tree is not mutated. A new tree
  * is returned. Use `depth: 'shallow'` to skip recursion into children.
  *
  * @example Prefix every operationId