@kubb/ast 5.0.0-beta.58 → 5.0.0-beta.59

package/src/utils/refs.ts

@@ -0,0 +1,112 @@
+import { pascalCase } from '@internals/utils'
+import { narrowSchema } from '../guards.ts'
+import type { OperationNode, ParameterNode, SchemaNode } from '../nodes/index.ts'
+import type { SchemaType } from '../nodes/schema.ts'
+import type { OperationParamsResolver, ParamGroupType } from './operationParams.ts'
+
+const plainStringTypes = new Set<SchemaType>(['string', 'uuid', 'email', 'url', 'datetime'] as const)
+
+/**
+ * Returns the last path segment of a reference string.
+ *
+ * @example
+ * ```ts
+ * extractRefName('#/components/schemas/Pet') // 'Pet'
+ * ```
+ */
+export function extractRefName(ref: string): string {
+  return ref.split('/').at(-1) ?? ref
+}
+
+/**
+ * Resolves the schema name of a ref node, falling back through `ref` → `name` → nested `schema.name`.
+ *
+ * Returns `null` for non-ref nodes or when no name resolves.
+ *
+ * @example
+ * ```ts
+ * resolveRefName({ kind: 'Schema', type: 'ref', ref: '#/components/schemas/Pet' })
+ * // => 'Pet'
+ * ```
+ */
+export function resolveRefName(node: SchemaNode | undefined): string | null {
+  if (!node || node.type !== 'ref') return null
+  if (node.ref) return extractRefName(node.ref) ?? node.name ?? node.schema?.name ?? null
+
+  return node.name ?? node.schema?.name ?? null
+}
+
+/**
+ * Builds a PascalCase child schema name by joining a parent name and property name.
+ * Returns `null` when there is no parent to nest under.
+ *
+ * @example
+ * ```ts
+ * childName('Order', 'shipping_address') // 'OrderShippingAddress'
+ * childName(undefined, 'params')         // null
+ * ```
+ */
+export function childName(parentName: string | null | undefined, propName: string): string | null {
+  return parentName ? pascalCase([parentName, propName].join(' ')) : null
+}
+
+/**
+ * Builds a PascalCase enum name from the parent name, property name, and a suffix, skipping any
+ * empty parts.
+ *
+ * @example
+ * ```ts
+ * enumPropName('Order', 'status', 'enum') // 'OrderStatusEnum'
+ * ```
+ */
+export function enumPropName(parentName: string | null | undefined, propName: string, enumSuffix: string): string {
+  return pascalCase([parentName, propName, enumSuffix].filter(Boolean).join(' '))
+}
+
+/**
+ * Type guard that returns `true` when a schema emits as a plain `string` type.
+ *
+ * Covers `string`, `uuid`, `email`, `url`, and `datetime` types. For `date` and `time`
+ * types, returns `true` only when `representation` is `'string'` rather than `'date'`.
+ */
+export function isStringType(node: SchemaNode): boolean {
+  if (plainStringTypes.has(node.type)) {
+    return true
+  }
+
+  const temporal = narrowSchema(node, 'date') ?? narrowSchema(node, 'time')
+  if (temporal) {
+    return temporal.representation !== 'date'
+  }
+
+  return false
+}
+
+/**
+ * Derives a {@link ParamGroupType} for a query or header group from the resolver.
+ *
+ * Returns `null` when there is no resolver, no params, or the group name equals the
+ * individual param name (so there is no real group to emit).
+ */
+export function resolveGroupType({
+  node,
+  params,
+  group,
+  resolver,
+}: {
+  node: OperationNode
+  params: Array<ParameterNode>
+  group: 'query' | 'header'
+  resolver: OperationParamsResolver | undefined
+}): ParamGroupType | null {
+  if (!resolver || !params.length) {
+    return null
+  }
+  const firstParam = params[0]!
+  const groupMethod = group === 'query' ? resolver.resolveQueryParamsName : resolver.resolveHeaderParamsName
+  const groupName = groupMethod.call(resolver, node, firstParam)
+  if (groupName === resolver.resolveParamName(node, firstParam)) {
+    return null
+  }
+  return { type: groupName, optional: params.every((p) => !p.required) }
+}

package/src/utils/schemaGraph.ts

@@ -0,0 +1,169 @@
+import { memoize } from '@internals/utils'
+import type { OperationNode, SchemaNode } from '../nodes/index.ts'
+import { collect, collectLazy } from '../visitor.ts'
+import { resolveRefName } from './refs.ts'
+
+/**
+ * Collects every named schema referenced transitively from a node through its ref edges.
+ *
+ * Refs are followed by name only, so the resolved `node.schema` is never traversed inline.
+ *
+ * @example Collect refs from a single schema
+ * ```ts
+ * const names = collectReferencedSchemaNames(petSchema)
+ * // → Set { 'Category', 'Tag' }
+ * ```
+ *
+ * @example Accumulate refs from multiple schemas into one set
+ * ```ts
+ * const out = new Set<string>()
+ * for (const schema of schemas) {
+ *   collectReferencedSchemaNames(schema, out)
+ * }
+ * ```
+ */
+const collectSchemaRefs = memoize(new WeakMap<SchemaNode, ReadonlySet<string>>(), (node: SchemaNode): ReadonlySet<string> => {
+  const refs = new Set<string>()
+  collect<void>(node, {
+    schema(child) {
+      if (child.type === 'ref') {
+        const name = resolveRefName(child)
+        if (name) refs.add(name)
+      }
+    },
+  })
+  return refs
+})
+
+export function collectReferencedSchemaNames(node: SchemaNode | undefined, out: Set<string> = new Set()): Set<string> {
+  if (!node) return out
+  for (const name of collectSchemaRefs(node)) out.add(name)
+  return out
+}
+
+/**
+ * Collects the names of all top-level schemas transitively used by a set of operations.
+ *
+ * An operation uses a schema when its parameters, request body, or responses reference it, directly
+ * or through other named schemas. The walk is iterative, so reference cycles are safe.
+ *
+ * Pair it with `include` filters so schemas reachable only from excluded operations stay ungenerated.
+ *
+ * @example Only generate schemas referenced by included operations
+ * ```ts
+ * const includedOps = operations.filter((op) => resolver.resolveOptions(op, { options, include }) !== null)
+ * const allowed = collectUsedSchemaNames(includedOps, schemas)
+ *
+ * for (const schema of schemas) {
+ *   if (schema.name && !allowed.has(schema.name)) continue
+ *   // … generate schema
+ * }
+ * ```
+ */
+const collectUsedSchemaNamesMemo = memoize(new WeakMap<ReadonlyArray<OperationNode>, (schemas: ReadonlyArray<SchemaNode>) => Set<string>>(), (ops) =>
+  memoize(new WeakMap<ReadonlyArray<SchemaNode>, Set<string>>(), (schemas) => computeUsedSchemaNames(ops, schemas)),
+)
+
+function computeUsedSchemaNames(operations: ReadonlyArray<OperationNode>, schemas: ReadonlyArray<SchemaNode>): Set<string> {
+  const schemaMap = new Map<string, SchemaNode>()
+  for (const schema of schemas) {
+    if (schema.name) schemaMap.set(schema.name, schema)
+  }
+
+  const result = new Set<string>()
+
+  function visitSchema(schema: SchemaNode): void {
+    const directRefs = collectReferencedSchemaNames(schema)
+    for (const name of directRefs) {
+      if (!result.has(name)) {
+        result.add(name)
+        const namedSchema = schemaMap.get(name)
+        if (namedSchema) visitSchema(namedSchema)
+      }
+    }
+  }
+
+  for (const op of operations) {
+    for (const schema of collectLazy<SchemaNode>(op, { depth: 'shallow', schema: (node) => node })) {
+      visitSchema(schema)
+    }
+  }
+
+  return result
+}
+
+export function collectUsedSchemaNames(operations: ReadonlyArray<OperationNode>, schemas: ReadonlyArray<SchemaNode>): Set<string> {
+  return collectUsedSchemaNamesMemo(operations)(schemas)
+}
+
+const EMPTY_CIRCULAR_SET = new Set<string>()
+
+const findCircularSchemasMemo = memoize(new WeakMap<ReadonlyArray<SchemaNode>, Set<string>>(), (schemas: ReadonlyArray<SchemaNode>): Set<string> => {
+  const graph = new Map<string, Set<string>>()
+
+  for (const schema of schemas) {
+    if (!schema.name) continue
+    graph.set(schema.name, collectReferencedSchemaNames(schema))
+  }
+
+  const circular = new Set<string>()
+  for (const start of graph.keys()) {
+    const visited = new Set<string>()
+    const stack: Array<string> = [...(graph.get(start) ?? [])]
+    while (stack.length > 0) {
+      const node = stack.pop()!
+      if (node === start) {
+        circular.add(start)
+        break
+      }
+      if (visited.has(node)) continue
+      visited.add(node)
+
+      const next = graph.get(node)
+      if (next) for (const r of next) stack.push(r)
+    }
+  }
+
+  return circular
+})
+
+/**
+ * Finds every schema that takes part in a circular dependency chain, including direct self-loops.
+ *
+ * Wrap the returned schema positions in a deferred construct (a lazy getter or `z.lazy(() => …)`) so
+ * the generated code does not recurse forever. Refs are followed by name only, so the walk stays
+ * linear in the size of the schema graph.
+ *
+ * @note Call this once on the full graph, then check individual schemas with `containsCircularRef()`.
+ */
+export function findCircularSchemas(schemas: ReadonlyArray<SchemaNode>): Set<string> {
+  if (schemas.length === 0) return EMPTY_CIRCULAR_SET
+  return findCircularSchemasMemo(schemas)
+}
+
+/**
+ * Returns `true` when a schema, or anything nested inside it, references a circular schema.
+ *
+ * Pass `excludeName` to skip refs to a specific schema, which helps when self-references are handled
+ * on their own. Pair it with `findCircularSchemas()` to decide where lazy wrappers go.
+ *
+ * @note Stops at the first matching circular ref.
+ */
+export function containsCircularRef(
+  node: SchemaNode | undefined,
+  { circularSchemas, excludeName }: { circularSchemas: ReadonlySet<string>; excludeName?: string },
+): boolean {
+  if (!node || circularSchemas.size === 0) return false
+
+  for (const _ of collectLazy<true>(node, {
+    schema(child) {
+      if (child.type !== 'ref') return null
+      const name = resolveRefName(child)
+      return name && name !== excludeName && circularSchemas.has(name) ? true : null
+    },
+  })) {
+    return true
+  }
+
+  return false
+}

package/src/utils/strings.ts

@@ -0,0 +1,139 @@
+/**
+ * Strips a single matching pair of `"..."`, `'...'`, or `` `...` `` from both ends of `text`.
+ * Returns the string unchanged when no balanced quote pair is found.
+ *
+ * @example
+ * ```ts
+ * trimQuotes('"hello"') // 'hello'
+ * trimQuotes('hello')   // 'hello'
+ * ```
+ */
+export function trimQuotes(text: string): string {
+  if (text.length >= 2) {
+    const first = text[0]
+    const last = text[text.length - 1]
+    if ((first === '"' && last === '"') || (first === "'" && last === "'") || (first === '`' && last === '`')) {
+      return text.slice(1, -1)
+    }
+  }
+  return text
+}
+
+/**
+ * Serializes a primitive to a single-quoted string literal, stripping any surrounding quotes first.
+ *
+ * Escaping runs through `JSON.stringify`, then the result switches to single quotes so the generated
+ * code matches the repo style without a formatter.
+ *
+ * @example
+ * ```ts
+ * stringify('hello')   // "'hello'"
+ * stringify('"hello"') // "'hello'"
+ * ```
+ */
+export function stringify(value: string | number | boolean | undefined): string {
+  if (value === undefined || value === null) return "''"
+  const json = JSON.stringify(trimQuotes(value.toString()))
+  const inner = json.slice(1, -1).replace(/\\"/g, '"').replace(/'/g, "\\'")
+  return `'${inner}'`
+}
+
+/**
+ * Escapes characters that are not allowed inside JS string literals, covering quotes, backslashes,
+ * and the Unicode line terminators U+2028 and U+2029.
+ *
+ * @see http://www.ecma-international.org/ecma-262/5.1/#sec-7.8.4
+ *
+ * @example
+ * ```ts
+ * jsStringEscape('say "hi"\nbye') // 'say \\"hi\\"\\nbye'
+ * ```
+ */
+export function jsStringEscape(input: unknown): string {
+  return `${input}`.replace(/["'\\\n\r\u2028\u2029]/g, (character) => {
+    switch (character) {
+      case '"':
+      case "'":
+      case '\\':
+        return `\\${character}`
+      case '\n':
+        return '\\n'
+      case '\r':
+        return '\\r'
+      case '\u2028':
+        return '\\u2028'
+      case '\u2029':
+        return '\\u2029'
+      default:
+        return ''
+    }
+  })
+}
+
+/**
+ * Converts a pattern string into a `new RegExp(...)` constructor call or a regex literal string.
+ * Inline flags expressed as a `^(?im)` prefix are extracted and applied to the resulting expression.
+ * Pass `null` as the second argument to emit a `/pattern/flags` literal instead.
+ *
+ * @example
+ * ```ts
+ * toRegExpString('^(?im)foo')       // 'new RegExp("^foo", "im")'
+ * toRegExpString('^(?im)foo', null) // '/^foo/im'
+ * ```
+ */
+export function toRegExpString(text: string, func: string | null = 'RegExp'): string {
+  const raw = trimQuotes(text)
+
+  const match = raw.match(/^\^(\(\?([igmsuy]+)\))/i)
+  const replacementTarget = match?.[1] ?? ''
+  const matchedFlags = match?.[2]
+  const cleaned = raw
+    .replace(/^\\?\//, '')
+    .replace(/\\?\/$/, '')
+    .replace(replacementTarget, '')
+
+  const { source, flags } = new RegExp(cleaned, matchedFlags)
+
+  if (func === null) return `/${source}/${flags}`
+
+  return `new ${func}(${JSON.stringify(source)}${flags ? `, ${JSON.stringify(flags)}` : ''})`
+}
+
+/**
+ * Renders a plain object as multi-line `key: value` source for embedding in generated code. Nested
+ * objects recurse with fixed indentation, so the result drops straight into an object literal
+ * without re-parsing.
+ *
+ * @example
+ * ```ts
+ * stringifyObject({ foo: 'bar', nested: { a: 1 } })
+ * // 'foo: bar,\nnested: {\n        a: 1\n      }'
+ * ```
+ */
+export function stringifyObject(value: Record<string, unknown>): string {
+  const items = Object.entries(value)
+    .map(([key, val]) => {
+      if (val !== null && typeof val === 'object') {
+        return `${key}: {\n        ${stringifyObject(val as Record<string, unknown>)}\n      }`
+      }
+      return `${key}: ${val}`
+    })
+    .filter(Boolean)
+  return items.join(',\n')
+}
+
+/**
+ * Renders a dotted path or string array as an optional-chaining accessor expression rooted at
+ * `accessor`. Returns `null` for an empty path.
+ *
+ * @example
+ * ```ts
+ * getNestedAccessor('pagination.next.id', 'lastPage')
+ * // "lastPage?.['pagination']?.['next']?.['id']"
+ * ```
+ */
+export function getNestedAccessor(param: string | Array<string>, accessor: string): string | null {
+  const parts = Array.isArray(param) ? param : param.split('.')
+  if (parts.length === 0 || (parts.length === 1 && parts[0] === '')) return null
+  return `${accessor}?.['${`${parts.join("']?.['")}']`}`
+}

package/src/visitor.ts

@@ -1,10 +1,11 @@
 import type { VisitorDepth } from './constants.ts'
 import { visitorDepths, WALK_CONCURRENCY } from './constants.ts'
-import { nodeRebuilders, VISITOR_KEY_BY_KIND, VISITOR_KEYS } from './registry.ts'
+import type { NodeDef } from './node.ts'
 import type {
   ContentNode,
   InputNode,
   Node,
+  NodeKind,
   OperationNode,
   OutputNode,
   ParameterNode,
@@ -13,6 +14,31 @@ import type {
   ResponseNode,
   SchemaNode,
 } from './nodes/index.ts'
+import { nodeDefs } from './registry.ts'
+
+/**
+ * Child node fields per node kind, in traversal order (Babel's `VISITOR_KEYS`).
+ * Derived from each definition's `children`.
+ */
+const VISITOR_KEYS = Object.fromEntries(nodeDefs.flatMap((def) => (def.children ? [[def.kind, def.children] as const] : []))) as Partial<
+  Record<NodeKind, ReadonlyArray<string>>
+>
+
+/**
+ * Maps a node kind to the matching visitor callback name. Derived from each
+ * definition's `visitorKey`.
+ */
+const VISITOR_KEY_BY_KIND = Object.fromEntries(nodeDefs.flatMap((def) => (def.visitorKey ? [[def.kind, def.visitorKey] as const] : []))) as Partial<
+  Record<NodeKind, NonNullable<NodeDef['visitorKey']>>
+>
+
+/**
+ * Per-kind builders rerun after children are rebuilt. Derived from each
+ * definition's `rebuild` flag.
+ */
+const nodeRebuilders = Object.fromEntries(
+  nodeDefs.flatMap((def) => (def.rebuild ? [[def.kind, def.create as unknown as (node: Node) => Node] as const] : [])),
+) as Partial<Record<NodeKind, (node: Node) => Node>>
 
 /**
  * Creates a small async concurrency limiter.
@@ -76,8 +102,7 @@ type ParentNodeMap = [
 /**
  * Resolves the parent node type for a given AST node type.
  *
- * This is used by visitor context so `ctx.parent` is correctly typed
- * for each callback.
+ * Visitor context relies on this so `ctx.parent` is typed for each callback.
  *
  * @example
  * ```ts
@@ -133,8 +158,7 @@ export type VisitorContext<T extends Node = Node> = {
  * to leave it untouched.
  *
  * Plugins typically expose `transformer` so users can supply a `Visitor` that
- * rewrites operation IDs, drops descriptions, or otherwise tweaks the AST
- * before printing.
+ * rewrites the AST before printing.
  *
  * @example Prefix every operationId
  * ```ts
@@ -165,7 +189,7 @@ export type Visitor = {
 }
 
 /**
- * Utility type for values that can be returned directly or asynchronously.
+ * A visitor callback result that may be sync or async.
  */
 type MaybePromise<T> = T | Promise<T>
 
@@ -229,7 +253,7 @@ type CollectVisitor<T> = {
  */
 export type TransformOptions = Visitor & {
   /**
-   * Traversal depth (`'deep'` by default).
+   * Traversal depth.
    * @default 'deep'
    */
   depth?: VisitorDepth
@@ -249,7 +273,7 @@ export type TransformOptions = Visitor & {
  */
 export type WalkOptions = AsyncVisitor & {
   /**
-   * Traversal depth (`'deep'` by default).
+   * Traversal depth.
    * @default 'deep'
    */
   depth?: VisitorDepth
@@ -270,7 +294,7 @@ export type WalkOptions = AsyncVisitor & {
  */
 export type CollectOptions<T> = CollectVisitor<T> & {
   /**
-   * Traversal depth (`'deep'` by default).
+   * Traversal depth.
    * @default 'deep'
    */
   depth?: VisitorDepth
@@ -318,9 +342,9 @@ function* getChildren(node: Node, recurse: boolean): Generator<Node, void, undef
 }
 
 /**
- * Invokes the visitor callback that matches `node.kind`, passing the traversal
- * context. Returns the callback's result (a replacement node, a collected
- * value, or `undefined` when no callback is registered for the kind).
+ * Runs the visitor callback that matches `node.kind` with the traversal
+ * context. The result is a replacement node, a collected value, or `undefined`
+ * when no callback is registered for the kind.
  *
  * Shared by `walk`, `transform`, and `collectLazy` so node-kind dispatch lives
  * in one place. `TResult` is the caller's expected return: the same node type
@@ -369,7 +393,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
@@ -378,11 +402,11 @@ 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.
+ * Synchronous depth-first transform. Each visitor callback can return a
+ * replacement node. Returning `undefined` keeps the original.
  *
- * The transform is immutable. The original tree is not mutated. A new tree
- * is returned. Use `depth: 'shallow'` to skip recursion into children.
+ * The original tree is never mutated, a new tree is returned. Pass
+ * `depth: 'shallow'` to skip recursion into children.
  *
  * @example Prefix every operationId
  * ```ts
@@ -489,8 +513,8 @@ export function* collectLazy<T>(node: Node, options: CollectOptions<T>): Generat
 }
 
 /**
- * Eager depth-first collection pass. Returns an array of every non-null value
- * the visitor callbacks return.
+ * Eager depth-first collection pass. Gathers every non-null value the visitor
+ * callbacks return into an array.
  *
  * @example Collect every operationId
  * ```ts

package/dist/extractStringsFromNodes-Bn9cOos9.d.ts

@@ -1,14 +0,0 @@
-import { n as __name } from "./chunk-CNktS9qV.js";
-import { Ht as CodeNode } from "./ast-ClnJg9BN.js";
-
-//#region src/utils/extractStringsFromNodes.d.ts
-/**
- * Extracts all string content from a `CodeNode` tree recursively.
- *
- * Collects text node values, identifier references in string fields (`params`, `generics`, `returnType`, `type`),
- * and nested node content. Used to build the full source string for import filtering.
- */
-declare function extractStringsFromNodes(nodes: Array<CodeNode> | undefined): string;
-//#endregion
-export { extractStringsFromNodes as t };
-//# sourceMappingURL=extractStringsFromNodes-Bn9cOos9.d.ts.map