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

package/src/utils/ast.ts

@@ -1,816 +0,0 @@
-import { camelCase, isValidVarName, memoize } from '@internals/utils'
-
-import { narrowSchema } from '../guards.ts'
-import { createFunctionParameter, createFunctionParameters, createIndexedAccessType, createTypeLiteral } from '../nodes/function.ts'
-import { createProperty } from '../nodes/property.ts'
-import { createSchema } from '../nodes/schema.ts'
-import type {
-  ExportNode,
-  FunctionParameterNode,
-  FunctionParametersNode,
-  ImportNode,
-  OperationNode,
-  ParameterNode,
-  SchemaNode,
-  SourceNode,
-  TypeExpression,
-  TypeLiteralNode,
-} from '../nodes/index.ts'
-import type { SchemaType } from '../nodes/schema.ts'
-import { extractRefName, extractStringsFromNodes, resolveGroupType } from './index.ts'
-import { collect, collectLazy } from '../visitor.ts'
-
-const plainStringTypes = new Set<SchemaType>(['string', 'uuid', 'email', 'url', 'datetime'] as const)
-
-/**
- * Merges a ref node with its resolved schema, giving usage-site fields precedence.
- *
- * Usage-site fields (`description`, `readOnly`, `nullable`, `deprecated`) on the ref node
- * override the same fields in the resolved `node.schema`. Non-ref nodes are returned unchanged.
- *
- * @example
- * ```ts
- * // Ref with description override
- * const ref = createSchema({ type: 'ref', ref: '#/components/schemas/Pet', description: 'A cute pet' })
- * const merged = syncSchemaRef(ref)  // merges with resolved Pet schema
- * ```
- */
-export function syncSchemaRef(node: SchemaNode): SchemaNode {
-  const ref = narrowSchema(node, 'ref')
-
-  if (!ref) return node
-  if (!ref.schema) return node
-
-  const { kind: _kind, type: _type, name: _name, ref: _ref, schema: _schema, ...overrides } = ref
-
-  // Filter out undefined override values so they don't shadow the resolved schema's fields.
-  const definedOverrides = Object.fromEntries(Object.entries(overrides).filter(([, v]) => v !== undefined))
-
-  return createSchema({ ...ref.schema, ...definedOverrides })
-}
-
-/**
- * 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
-}
-
-/**
- * Applies casing rules to parameter names and returns a new parameter array.
- *
- * Use this before passing parameters to schema builders so output property keys match
- * the desired casing while preserving `OperationNode.parameters` for other consumers.
- * The input array is not mutated. When `casing` is not set, the original array is returned unchanged.
- */
-const caseParamsMemo = memoize(new WeakMap<Array<ParameterNode>, (casing: string) => Array<ParameterNode>>(), (params) =>
-  memoize(new Map<string, Array<ParameterNode>>(), (casing: string) =>
-    params.map((param) => {
-      const transformed = casing === 'camelcase' || !isValidVarName(param.name) ? camelCase(param.name) : param.name
-      return { ...param, name: transformed }
-    }),
-  ),
-)
-
-export function caseParams(params: Array<ParameterNode>, casing: 'camelcase' | undefined): Array<ParameterNode> {
-  if (!casing) return params
-  return caseParamsMemo(params)(casing)
-}
-
-/**
- * Creates a single-property object schema used as a discriminator literal.
- *
- * @example
- * ```ts
- * createDiscriminantNode({ propertyName: 'type', value: 'dog' })
- * // -> { type: 'object', properties: [{ name: 'type', required: true, schema: enum('dog') }] }
- * ```
- */
-export function createDiscriminantNode({ propertyName, value }: { propertyName: string; value: string }): SchemaNode {
-  return createSchema({
-    type: 'object',
-    primitive: 'object',
-    properties: [
-      createProperty({
-        name: propertyName,
-        schema: createSchema({
-          type: 'enum',
-          primitive: 'string',
-          enumValues: [value],
-        }),
-        required: true,
-      }),
-    ],
-  })
-}
-
-/**
- * Named type for a group of parameters (query or header) emitted as a single typed parameter.
- */
-export type ParamGroupType = {
-  /**
-   * Type expression for the group, a plain group-name reference.
-   */
-  type: TypeExpression
-  /**
-   * Whether the parameter group is optional.
-   */
-  optional: boolean
-}
-
-/**
- * A single member of a destructured parameter group, fed to `createFunctionParameter({ properties })`.
- */
-type GroupProperty = {
-  name: string
-  type: TypeExpression
-  optional?: boolean
-}
-
-/**
- * Resolver interface for {@link createOperationParams}.
- *
- * `ResolverTs` from `@kubb/plugin-ts` satisfies this interface and can be passed directly.
- */
-export type OperationParamsResolver = {
-  /**
-   * Resolves the type name for an individual parameter.
-   *
-   * @example Individual path parameter name
-   * `resolver.resolveParamName(node, param) // → 'DeletePetPathPetId'`
-   */
-  resolveParamName(node: OperationNode, param: ParameterNode): string
-  /**
-   * Resolves the request body type name.
-   *
-   * @example Request body type name
-   * `resolver.resolveDataName(node) // → 'CreatePetData'`
-   */
-  resolveDataName(node: OperationNode): string
-  /**
-   * Resolves the grouped path parameters type name.
-   * When the return value equals `resolveParamName`, no indexed access is emitted.
-   *
-   * @example Grouped path params type name
-   * `resolver.resolvePathParamsName(node, param) // → 'DeletePetPathParams'`
-   */
-  resolvePathParamsName(node: OperationNode, param: ParameterNode): string
-  /**
-   * Resolves the grouped query parameters type name.
-   * When the return value equals `resolveParamName`, an inline struct type is emitted instead.
-   *
-   * @example Grouped query params type name
-   * `resolver.resolveQueryParamsName(node, param) // → 'FindPetsByStatusQueryParams'`
-   */
-  resolveQueryParamsName(node: OperationNode, param: ParameterNode): string
-  /**
-   * Resolves the grouped header parameters type name.
-   * When the return value equals `resolveParamName`, an inline struct type is emitted instead.
-   *
-   * @example Grouped header params type name
-   * `resolver.resolveHeaderParamsName(node, param) // → 'DeletePetHeaderParams'`
-   */
-  resolveHeaderParamsName(node: OperationNode, param: ParameterNode): string
-}
-
-/**
- * Options for {@link createOperationParams}.
- */
-export type CreateOperationParamsOptions = {
-  /**
-   * How all operation parameters are grouped in the function signature.
-   * - `'object'` wraps all params into a single destructured object `{ petId, data, params }`
-   * - `'inline'` emits each param category as a separate top-level parameter
-   */
-  paramsType: 'object' | 'inline'
-  /**
-   * How path parameters are emitted when `paramsType` is `'inline'`.
-   * - `'object'` groups them as `{ petId, storeId }: PathParams`
-   * - `'inline'` spreads them as individual parameters `petId: string, storeId: string`
-   * - `'inlineSpread'` emits a single rest parameter `...pathParams: PathParams`
-   */
-  pathParamsType: 'object' | 'inline' | 'inlineSpread'
-  /**
-   * Converts parameter names to camelCase before output.
-   */
-  paramsCasing?: 'camelcase'
-  /**
-   * Resolver for parameter and request body type names.
-   * Pass `ResolverTs` from `@kubb/plugin-ts` directly.
-   * When omitted, falls back to the schema primitive or `'unknown'`.
-   */
-  resolver?: OperationParamsResolver
-  /**
-   * Default value for the path parameters binding when `pathParamsType` is `'object'`.
-   * Falls back to `'{}'` when all path params are optional.
-   */
-  pathParamsDefault?: string
-  /**
-   * Extra parameters appended after the standard operation parameters.
-   *
-   * @example Plugin-specific trailing parameter
-   * ```ts
-   * extraParams: [createFunctionParameter({ name: 'options', type: 'Partial<RequestOptions>', default: '{}' })]
-   * ```
-   */
-  extraParams?: Array<FunctionParameterNode>
-  /**
-   * Override the default parameter names used for body, query, header, and rest-path groups.
-   *
-   * Useful when targeting languages or frameworks with different naming conventions.
-   *
-   * @default { data: 'data', params: 'params', headers: 'headers', path: 'pathParams' }
-   */
-  paramNames?: {
-    /**
-     * Name for the request body parameter.
-     * @default 'data'
-     */
-    data?: string
-    /**
-     * Name for the query parameters group parameter.
-     * @default 'params'
-     */
-    params?: string
-    /**
-     * Name for the header parameters group parameter.
-     * @default 'headers'
-     */
-    headers?: string
-    /**
-     * Name for the rest path-parameters parameter when `pathParamsType` is `'inlineSpread'`.
-     * @default 'pathParams'
-     */
-    path?: string
-  }
-  /**
-   * 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`
-   * `typeWrapper: (t) => \`MaybeRefOrGetter<${t}>\``
-   */
-  typeWrapper?: (type: string) => string
-}
-
-/**
- * Resolves the {@link TypeExpression} for an individual parameter.
- *
- * Without a resolver, falls back to the schema primitive (a plain type-name string).
- * When the parameter belongs to a named group, emits an {@link IndexedAccessTypeNode}
- * (`GroupParams['petId']`); otherwise the resolved individual name as a plain string.
- */
-export function resolveParamType({
-  node,
-  param,
-  resolver,
-}: {
-  node: OperationNode
-  param: ParameterNode
-  resolver: OperationParamsResolver | undefined
-}): TypeExpression {
-  if (!resolver) {
-    return param.schema.primitive ?? 'unknown'
-  }
-
-  const individualName = resolver.resolveParamName(node, param)
-
-  const groupLocation = param.in === 'path' || param.in === 'query' || param.in === 'header' ? param.in : undefined
-
-  const groupResolvers = {
-    path: resolver.resolvePathParamsName,
-    query: resolver.resolveQueryParamsName,
-    header: resolver.resolveHeaderParamsName,
-  } as const
-
-  const groupName = groupLocation ? groupResolvers[groupLocation].call(resolver, node, param) : undefined
-
-  if (groupName && groupName !== individualName) {
-    return createIndexedAccessType({ objectType: groupName, indexType: param.name })
-  }
-
-  return individualName
-}
-
-/**
- * Converts an `OperationNode` into function parameters for code generation.
- *
- * Centralizes parameter grouping logic for all plugins. `paramsType` chooses between one
- * destructured object parameter (`object`) and separate top-level parameters (`inline`), while
- * `pathParamsType` controls how path params render in inline mode. Provide a `resolver` for type
- * name resolution and `extraParams` for plugin-specific trailing parameters such as an `options` object.
- */
-export function createOperationParams(node: OperationNode, options: CreateOperationParamsOptions): FunctionParametersNode {
-  const { paramsType, pathParamsType, paramsCasing, resolver, pathParamsDefault, extraParams = [], paramNames, typeWrapper } = options
-
-  const dataName = paramNames?.data ?? 'data'
-  const paramsName = paramNames?.params ?? 'params'
-  const headersName = paramNames?.headers ?? 'headers'
-  const pathName = paramNames?.path ?? 'pathParams'
-
-  const wrapType = (type: string): string => (typeWrapper ? typeWrapper(type) : type)
-  // Only plain type-name references are wrapped, they need casing applied.
-  // TypeLiteral and IndexedAccessType expressions are pre-resolved and pass through unchanged.
-  const wrapTypeExpression = (type: TypeExpression): TypeExpression => (typeof type === 'string' ? wrapType(type) : type)
-
-  const casedParams = caseParams(node.parameters, paramsCasing)
-  const pathParams = casedParams.filter((p) => p.in === 'path')
-  const queryParams = casedParams.filter((p) => p.in === 'query')
-  const headerParams = casedParams.filter((p) => p.in === 'header')
-
-  const toProperty = (param: ParameterNode): GroupProperty => ({
-    name: param.name,
-    type: wrapTypeExpression(resolveParamType({ node, param, resolver })),
-    optional: !param.required,
-  })
-  const emptyObjectDefault = (props: Array<GroupProperty>): string | undefined => (props.every((p) => p.optional) ? '{}' : undefined)
-
-  const bodyType = node.requestBody?.content?.[0]?.schema ? wrapType(resolver?.resolveDataName(node) ?? 'unknown') : undefined
-  const bodyProperty: Array<GroupProperty> = bodyType ? [{ name: dataName, type: bodyType, optional: !(node.requestBody?.required ?? false) }] : []
-
-  const trailingGroups: Array<BuildGroupArgs> = [
-    { name: paramsName, node, params: queryParams, groupType: resolveGroupType({ node, params: queryParams, group: 'query', resolver }), resolver, wrapType },
-    {
-      name: headersName,
-      node,
-      params: headerParams,
-      groupType: resolveGroupType({ node, params: headerParams, group: 'header', resolver }),
-      resolver,
-      wrapType,
-    },
-  ]
-
-  const params: Array<FunctionParameterNode> = []
-
-  if (paramsType === 'object') {
-    const children = [...pathParams.map(toProperty), ...bodyProperty, ...trailingGroups.flatMap(buildGroupProperty)]
-    if (children.length) {
-      params.push(createFunctionParameter({ properties: children, default: emptyObjectDefault(children) }))
-    }
-  } else {
-    if (pathParamsType === 'inlineSpread' && pathParams.length) {
-      const spreadType = resolver?.resolvePathParamsName(node, pathParams[0]!)
-      params.push(createFunctionParameter({ name: pathName, type: spreadType ? wrapType(spreadType) : undefined, rest: true }))
-    } else if (pathParamsType === 'inline') {
-      params.push(...pathParams.map((p) => createFunctionParameter(toProperty(p))))
-    } else if (pathParams.length) {
-      const pathChildren = pathParams.map(toProperty)
-      params.push(createFunctionParameter({ properties: pathChildren, default: pathParamsDefault ?? emptyObjectDefault(pathChildren) }))
-    }
-
-    params.push(...bodyProperty.map((p) => createFunctionParameter(p)))
-    params.push(...trailingGroups.flatMap(buildGroupParam))
-  }
-
-  params.push(...extraParams)
-
-  return createFunctionParameters({ params })
-}
-
-/**
- * Shared arguments for building a query or header parameter group.
- */
-export type BuildGroupArgs = {
-  name: string
-  node: OperationNode
-  params: Array<ParameterNode>
-  groupType: ParamGroupType | null
-  resolver: OperationParamsResolver | undefined
-  wrapType: (type: string) => string
-}
-
-/**
- * Builds the property descriptor for a query or header group.
- * Returns an empty array when there are no params to emit.
- *
- * A pre-resolved `groupType` emits `name: GroupType`. Otherwise it builds an inline
- * {@link TypeLiteralNode} from the individual params.
- */
-function buildGroupProperty({ name, node, params, groupType, resolver, wrapType }: BuildGroupArgs): Array<GroupProperty> {
-  if (groupType) {
-    const type = typeof groupType.type === 'string' ? wrapType(groupType.type) : groupType.type
-    return [{ name, type, optional: groupType.optional }]
-  }
-  if (params.length) {
-    return [{ name, type: buildTypeLiteral({ node, params, resolver }), optional: params.every((p) => !p.required) }]
-  }
-  return []
-}
-
-/**
- * Builds a single {@link FunctionParameterNode} for a query or header group.
- * Returns an empty array when there are no params to emit.
- *
- * A pre-resolved `groupType` emits `name: GroupType`. Otherwise it builds an inline
- * {@link TypeLiteralNode} from the individual params.
- */
-export function buildGroupParam(args: BuildGroupArgs): Array<FunctionParameterNode> {
-  return buildGroupProperty(args).map((p) => createFunctionParameter(p))
-}
-
-/**
- * Builds a {@link TypeLiteralNode} for an inline anonymous type grouping named fields.
- *
- * Used when query or header parameters have no dedicated group type name.
- * Each language printer renders this appropriately (TypeScript: `{ petId: string; name?: string }`).
- */
-export function buildTypeLiteral({
-  node,
-  params,
-  resolver,
-}: {
-  node: OperationNode
-  params: Array<ParameterNode>
-  resolver: OperationParamsResolver | undefined
-}): TypeLiteralNode {
-  return createTypeLiteral({
-    members: params.map((p) => ({
-      name: p.name,
-      type: resolveParamType({ node, param: p, resolver }),
-      optional: !p.required,
-    })),
-  })
-}
-
-function sourceKey(source: SourceNode): string {
-  const nameKey = source.name ?? extractStringsFromNodes(source.nodes)
-  return `${nameKey}:${source.isExportable ?? false}:${source.isTypeOnly ?? false}`
-}
-
-function pathTypeKey(path: string, isTypeOnly: boolean | null | undefined): string {
-  return `${path}:${isTypeOnly ?? false}`
-}
-
-function exportKey(path: string, name: string | null | undefined, isTypeOnly: boolean | null | undefined, asAlias: boolean | null | undefined): string {
-  return `${path}:${name ?? ''}:${isTypeOnly ?? false}:${asAlias ?? ''}`
-}
-
-function importKey(path: string, name: string | null | undefined, isTypeOnly: boolean | null | undefined): string {
-  return `${path}:${name ?? ''}:${isTypeOnly ?? false}`
-}
-
-/**
- * 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.
- */
-function sortKey(node: { name?: string | Array<unknown> | null; isTypeOnly?: boolean | null; path: string }): string {
-  const isArray = Array.isArray(node.name) ? '1' : '0'
-  const typeOnly = node.isTypeOnly ? '0' : '1'
-  const hasName = node.name != null ? '1' : '0'
-  const name = Array.isArray(node.name) ? node.name.toSorted().join('\0') : (node.name ?? '')
-  return `${isArray}:${typeOnly}:${node.path}:${hasName}:${name}`
-}
-
-/**
- * Deduplicates and merges `SourceNode` objects by `name + isExportable + isTypeOnly`.
- *
- * Unnamed sources are deduplicated by object reference. Returns a deduplicated array in original order.
- */
-export function combineSources(sources: Array<SourceNode>): Array<SourceNode> {
-  const seen = new Map<string, SourceNode>()
-  for (const source of sources) {
-    const key = sourceKey(source)
-    if (!seen.has(key)) seen.set(key, source)
-  }
-  return [...seen.values()]
-}
-
-/**
- * Merges `incoming` names into `existing`, preserving order and dropping duplicates.
- *
- * Shared by `combineExports` and `combineImports` for the same-path name-merge case.
- */
-function mergeNameArrays<TName>(existing: Array<TName>, incoming: Array<TName>): Array<TName> {
-  const merged = new Set(existing)
-  for (const name of incoming) merged.add(name)
-  return [...merged]
-}
-
-/**
- * Deduplicates and merges `ExportNode` objects by path and type.
- *
- * Named exports with the same path and `isTypeOnly` flag have their names merged into a single export.
- * Non-array exports are deduplicated by exact identity. Returns a sorted, deduplicated array.
- */
-export function combineExports(exports: Array<ExportNode>): Array<ExportNode> {
-  const result: Array<ExportNode> = []
-  // Accumulates array-named exports keyed by `path:isTypeOnly` for name-merging
-  const namedByPath = new Map<string, ExportNode>()
-  // Deduplicates non-array exports by their exact identity
-  const seen = new Set<string>()
-
-  // 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))
-
-  for (const { node: curr } of keyed) {
-    const { name, path, isTypeOnly, asAlias } = curr
-
-    if (Array.isArray(name)) {
-      if (!name.length) continue
-
-      const key = pathTypeKey(path, isTypeOnly)
-      const existing = namedByPath.get(key)
-
-      if (existing && Array.isArray(existing.name)) {
-        existing.name = mergeNameArrays(existing.name, name)
-      } else {
-        const newItem: ExportNode = { ...curr, name: [...new Set(name)] }
-        result.push(newItem)
-        namedByPath.set(key, newItem)
-      }
-    } else {
-      const key = exportKey(path, name, isTypeOnly, asAlias)
-      if (!seen.has(key)) {
-        result.push(curr)
-        seen.add(key)
-      }
-    }
-  }
-
-  return result
-}
-
-/**
- * Deduplicates and merges `ImportNode` objects, filtering out unused imports.
- *
- * Retains imports that are referenced in `source` or re-exported. Imports with the same path and
- * `isTypeOnly` flag have their names merged. Returns a sorted, deduplicated, filtered array.
- *
- * @note Use this when combining imports from multiple files to avoid duplicate declarations.
- */
-export function combineImports(imports: Array<ImportNode>, exports: Array<ExportNode>, source?: string): Array<ImportNode> {
-  // Build a lookup of all exported names to retain imports that are re-exported
-  const exportedNames = new Set(exports.flatMap((e) => (Array.isArray(e.name) ? e.name : e.name ? [e.name] : [])))
-  const isUsed = (importName: string): boolean => !source || source.includes(importName) || exportedNames.has(importName)
-
-  // Memoize object import names so the same logical (propertyName, name) pair always
-  // reuses the same object reference. Set-based deduplication then works correctly.
-  const importNameMemo = new Map<string, { propertyName: string; name?: string }>()
-  const canonicalizeName = (n: string | { propertyName: string; name?: string }): string | { propertyName: string; name?: string } => {
-    if (typeof n === 'string') return n
-    const key = `${n.propertyName}:${n.name ?? ''}`
-    if (!importNameMemo.has(key)) importNameMemo.set(key, n)
-    return importNameMemo.get(key)!
-  }
-
-  // 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
-  // alongside `import type { Client } from <same path>`, where merged grouped output omits the body.
-  const pathsWithUsedNamedImport = new Set<string>()
-  for (const node of imports) {
-    if (!Array.isArray(node.name)) continue
-    if (node.name.some((item) => (typeof item === 'string' ? isUsed(item) : isUsed(item.name ?? item.propertyName)))) {
-      pathsWithUsedNamedImport.add(node.path)
-    }
-  }
-
-  const result: Array<ImportNode> = []
-  // Accumulates array-named imports keyed by `path:isTypeOnly` for name-merging
-  const namedByPath = new Map<string, ImportNode>()
-  // Deduplicates non-array imports by their exact identity
-  const seen = new Set<string>()
-
-  // 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))
-
-  for (const { node: curr } of keyed) {
-    if (curr.path === curr.root) continue
-
-    const { path, isTypeOnly } = curr
-    let { name } = curr
-
-    if (Array.isArray(name)) {
-      name = [...new Set(name.map(canonicalizeName))].filter((item) => (typeof item === 'string' ? isUsed(item) : isUsed(item.name ?? item.propertyName)))
-      if (!name.length) continue
-
-      const key = pathTypeKey(path, isTypeOnly)
-      const existing = namedByPath.get(key)
-
-      if (existing && Array.isArray(existing.name)) {
-        existing.name = mergeNameArrays(existing.name, name)
-      } else {
-        const newItem: ImportNode = { ...curr, name }
-        result.push(newItem)
-        namedByPath.set(key, newItem)
-      }
-    } else {
-      if (name && !isUsed(name) && !pathsWithUsedNamedImport.has(path)) continue
-
-      const key = importKey(path, name, isTypeOnly)
-      if (!seen.has(key)) {
-        result.push(curr)
-        seen.add(key)
-      }
-    }
-  }
-
-  return result
-}
-
-/**
- * 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 can be resolved. Use this to get a schema's
- * identifier for type definitions or error messages.
- *
- * @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
-}
-
-/**
- * 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.
- * Use this to determine schema dependencies, build reference graphs, or detect what schemas need to be emitted.
- *
- * @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 any of its parameters, request body content, or responses
- * reference it, directly or indirectly through other named schemas.
- * The walk is iterative and safe against reference cycles.
- *
- * Use this together with `include` filters to determine which schemas from `components/schemas`
- * are reachable from the allowed operations, so that schemas used only by excluded operations
- * are not generated.
- *
- * @example Only generate schemas referenced by included operations
- * ```ts
- * const includedOps = 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
- * }
- * ```
- *
- * @example Check whether a specific schema is needed
- * ```ts
- * const allowed = collectUsedSchemaNames(includedOps, schemas)
- * allowed.has('OrderStatus') // false when no included operation references OrderStatus
- * ```
- */
-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
-})
-
-/**
- * Identifies all schemas that participate in circular dependency chains, including direct self-loops.
- *
- * Returns a Set of schema names with circular dependencies. Use this to wrap recursive schema positions
- * in deferred constructs (lazy getter, `z.lazy(() => …)`) to prevent infinite recursion when generated code runs.
- * Refs are followed by name only, keeping the algorithm linear in the schema graph size.
- *
- * @note Call this once on the full schema graph, then use `containsCircularRef()` to check individual schemas.
- */
-export function findCircularSchemas(schemas: ReadonlyArray<SchemaNode>): Set<string> {
-  if (schemas.length === 0) return EMPTY_CIRCULAR_SET
-  return findCircularSchemasMemo(schemas)
-}
-
-/**
- * Type guard returning `true` when a schema or anything nested within it contains a ref to a circular schema.
- *
- * 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.
- */
-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
-}