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

package/src/transformers.ts

@@ -1,8 +1,8 @@
 import { isScalarPrimitive } from './constants.ts'
-import { createProperty, createSchema } from './factory.ts'
 import { narrowSchema } from './guards.ts'
-import type { SchemaNode } from './nodes/schema.ts'
-import { enumPropName } from './resolvers.ts'
+import { createProperty } from './nodes/property.ts'
+import { createSchema, type SchemaNode } from './nodes/schema.ts'
+import { enumPropName } from './utils/refs.ts'
 
 /**
  * Replaces a discriminator property's schema with a string enum of allowed values.
@@ -73,25 +73,30 @@ export function setDiscriminatorEnum({
  * ])
  * ```
  */
-export function mergeAdjacentObjects(members: Array<SchemaNode>): Array<SchemaNode> {
-  return members.reduce<Array<SchemaNode>>((acc, member) => {
+export function* mergeAdjacentObjectsLazy(members: Iterable<SchemaNode>): Generator<SchemaNode, void, undefined> {
+  let acc: SchemaNode | undefined
+
+  for (const member of members) {
     const objectMember = narrowSchema(member, 'object')
-    if (objectMember && !objectMember.name) {
-      const previous = acc.at(-1)
-      const previousObject = previous ? narrowSchema(previous, 'object') : undefined
-
-      if (previousObject && !previousObject.name) {
-        acc[acc.length - 1] = createSchema({
-          ...previousObject,
-          properties: [...(previousObject.properties ?? []), ...(objectMember.properties ?? [])],
+    if (objectMember && !objectMember.name && acc !== undefined) {
+      const accObject = narrowSchema(acc, 'object')
+      if (accObject && !accObject.name) {
+        acc = createSchema({
+          ...accObject,
+          properties: [...(accObject.properties ?? []), ...(objectMember.properties ?? [])],
         })
-        return acc
+        continue
       }
     }
+    if (acc !== undefined) yield acc
+    acc = member
+  }
+
+  if (acc !== undefined) yield acc
+}
 
-    acc.push(member)
-    return acc
-  }, [])
+export function mergeAdjacentObjects(members: Array<SchemaNode>): Array<SchemaNode> {
+  return [...mergeAdjacentObjectsLazy(members)]
 }
 
 /**
@@ -145,7 +150,7 @@ export function setEnumName(propNode: SchemaNode, parentName: string | null | un
   const enumNode = narrowSchema(propNode, 'enum')
 
   if (enumNode?.primitive === 'boolean') {
-    return { ...propNode, name: undefined }
+    return { ...propNode, name: null }
   }
 
   if (enumNode) {
@@ -157,3 +162,30 @@ export function setEnumName(propNode: SchemaNode, parentName: string | null | un
 
   return propNode
 }
+
+/**
+ * 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 })
+}

package/src/types.ts

@@ -1,70 +1,9 @@
-export type { VisitorDepth } from './constants.ts'
-export type { DistributiveOmit } from './factory.ts'
-export type { InferSchema, InferSchemaNode, ParserOptions } from './infer.ts'
-export type {
-  ArraySchemaNode,
-  ArrowFunctionNode,
-  BaseNode,
-  BreakNode,
-  CodeNode,
-  ComplexSchemaType,
-  ConstNode,
-  DateSchemaNode,
-  DatetimeSchemaNode,
-  EnumSchemaNode,
-  EnumValueNode,
-  ExportNode,
-  FileNode,
-  FormatStringSchemaNode,
-  FunctionNode,
-  FunctionNodeType,
-  FunctionParameterNode,
-  FunctionParametersNode,
-  FunctionParamNode,
-  HttpMethod,
-  HttpStatusCode,
-  ImportNode,
-  InputMeta,
-  InputNode,
-  IntersectionSchemaNode,
-  Ipv4SchemaNode,
-  Ipv6SchemaNode,
-  JSDocNode,
-  JsxNode,
-  MediaType,
-  Node,
-  NodeKind,
-  NumberSchemaNode,
-  ObjectSchemaNode,
-  OperationNode,
-  OutputNode,
-  ParameterGroupNode,
-  ParameterLocation,
-  ParameterNode,
-  ParamsTypeNode,
-  PrimitiveSchemaType,
-  PropertyNode,
-  RefSchemaNode,
-  ResponseNode,
-  ScalarSchemaNode,
-  ScalarSchemaType,
-  SchemaNode,
-  SchemaNodeByType,
-  SchemaType,
-  SourceNode,
-  SpecialSchemaType,
-  StatusCode,
-  StringSchemaNode,
-  TextNode,
-  TimeSchemaNode,
-  TypeDeclarationNode,
-  TypeNode,
-  UnionSchemaNode,
-  UrlSchemaNode,
-} from './nodes/index.ts'
-export type { RefMap } from './refs.ts'
-export type { AsyncVisitor, CollectOptions, CollectVisitor, ParentOf, TransformOptions, Visitor, VisitorContext, WalkOptions } from './visitor.ts'
+export type { DedupeCanonical, DedupeLookups, DedupePlan } from './dedupe.ts'
+export type { SchemaDialect } from './dialect.ts'
+export type { DistributiveOmit } from './node.ts'
+export type { InferSchemaNode, ParserOptions } from './infer.ts'
+export type * from './nodes/index.ts'
+export type { ParentOf, Visitor, VisitorContext } from './visitor.ts'
 export type { Printer, PrinterFactoryOptions, PrinterPartial } from './printer.ts'
-export type { ScalarPrimitive } from './constants.ts'
-export type { OperationParamsResolver } from './utils.ts'
+export type { OperationParamsResolver } from './utils/operationParams.ts'
 export type { UserFileNode } from './factory.ts'

package/src/utils/codegen.ts

@@ -0,0 +1,104 @@
+import { isIdentifier, singleQuote } from '@internals/utils'
+import { INDENT } from '../constants.ts'
+
+/**
+ * Builds a JSDoc comment block from an array of lines, returning `fallback` when there are no
+ * comments so callers always get a usable string.
+ *
+ * @example
+ * ```ts
+ * buildJSDoc(['@type string', '@example hello'])
+ * // '/**\n   * @type string\n   * @example hello\n   *\/\n  '
+ * ```
+ */
+export function buildJSDoc(
+  comments: Array<string>,
+  options: {
+    /**
+     * String used to indent each comment line.
+     * @default '   * '
+     */
+    indent?: string
+    /**
+     * String appended after the closing tag.
+     * @default '\n  '
+     */
+    suffix?: string
+    /**
+     * Returned as-is when `comments` is empty.
+     * @default '  '
+     */
+    fallback?: string
+  } = {},
+): string {
+  const { indent = '   * ', suffix = '\n  ', fallback = '  ' } = options
+
+  if (comments.length === 0) return fallback
+
+  return `/**\n${comments.map((c) => `${indent}${c}`).join('\n')}\n   */${suffix}`
+}
+
+/**
+ * Indents every non-empty line of `text` by one indent level, leaving blank lines empty.
+ */
+function indentLines(text: string): string {
+  if (!text) return ''
+  return text
+    .split('\n')
+    .map((line) => (line.trim() ? `${INDENT}${line}` : ''))
+    .join('\n')
+}
+
+/**
+ * Renders an object key, quoting it with single quotes only when it is not a valid identifier.
+ * Reserved words and globals (`name`, `class`, …) are valid bare keys and stay unquoted.
+ *
+ * @example
+ * ```ts
+ * objectKey('name')    // 'name'
+ * objectKey('x-total') // "'x-total'"
+ * ```
+ */
+export function objectKey(name: string): string {
+  return isIdentifier(name) ? name : singleQuote(name)
+}
+
+/**
+ * Assembles a multi-line object literal from already-rendered `entries`, indenting each entry one
+ * level and closing the brace at column zero. Nested objects built the same way indent cumulatively,
+ * so callers never re-parse the generated code. A trailing comma is added per entry to match the
+ * formatter's multi-line style.
+ *
+ * @example
+ * ```ts
+ * buildObject(['id: z.number()', 'name: z.string()'])
+ * // '{\n  id: z.number(),\n  name: z.string(),\n}'
+ * ```
+ */
+export function buildObject(entries: Array<string>): string {
+  if (entries.length === 0) return '{}'
+  const body = entries.map((entry) => `${indentLines(entry)},`).join('\n')
+
+  return `{\n${body}\n}`
+}
+
+/**
+ * Assembles a bracketed list (array by default) from already-rendered `items`. Keeps everything on
+ * one line when no item spans multiple lines, and otherwise puts each item on its own line, indented
+ * one level with a trailing comma and the closing bracket at column zero. Use it for `z.union([…])`,
+ * `z.array([…])`, and similar member lists so objects inside them nest correctly.
+ *
+ * @example
+ * ```ts
+ * buildList(['z.string()', 'z.number()'])
+ * // '[z.string(), z.number()]'
+ * ```
+ */
+export function buildList(items: Array<string>, brackets: [open: string, close: string] = ['[', ']']): string {
+  const [open, close] = brackets
+  if (items.length === 0) return `${open}${close}`
+  if (!items.some((item) => item.includes('\n'))) return `${open}${items.join(', ')}${close}`
+  const body = items.map((item) => `${indentLines(item)},`).join('\n')
+
+  return `${open}\n${body}\n${close}`
+}

package/src/utils/extractStringsFromNodes.ts

@@ -0,0 +1,34 @@
+import type { CodeNode } from '../nodes/code.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.
+ */
+export function extractStringsFromNodes(nodes: Array<CodeNode> | undefined): string {
+  if (!nodes?.length) return ''
+  return nodes
+    .map((node) => {
+      // Backward-compat: compiled plugins may still pass bare strings at runtime
+      if (typeof node === 'string') return node as string
+      if (node.kind === 'Text') return node.value
+      if (node.kind === 'Break') return ''
+      if (node.kind === 'Jsx') return node.value
+
+      const parts: Array<string> = []
+
+      if ('params' in node && node.params) parts.push(node.params)
+      if ('generics' in node && node.generics) parts.push(Array.isArray(node.generics) ? node.generics.join(', ') : node.generics)
+      if ('returnType' in node && node.returnType) parts.push(node.returnType)
+      if ('type' in node && typeof node.type === 'string') parts.push(node.type)
+
+      const nested = extractStringsFromNodes(node.nodes)
+
+      if (nested) parts.push(nested)
+
+      return parts.join('\n')
+    })
+    .filter(Boolean)
+    .join('\n')
+}

package/src/utils/fileMerge.ts

@@ -0,0 +1,184 @@
+/**
+ * File-member merging. `combineImports`, `combineExports`, and `combineSources` deduplicate and sort
+ * the import, export, and source entries of one file, and drop imports nothing references. This works
+ * on a file's members, not on schema content.
+ *
+ * For collapsing duplicate schema shapes by structural signature, see `dedupe.ts`.
+ */
+import type { ExportNode, ImportNode, SourceNode } from '../nodes/index.ts'
+import { extractStringsFromNodes } from './extractStringsFromNodes.ts'
+
+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.
+ */
+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
+}

package/src/utils/index.ts

@@ -0,0 +1,11 @@
+export { isValidVarName } from '@internals/utils'
+export { buildJSDoc, buildList, buildObject, objectKey } from './codegen.ts'
+export { extractStringsFromNodes } from './extractStringsFromNodes.ts'
+export { childName, enumPropName, extractRefName, isStringType, resolveGroupType, resolveRefName } from './refs.ts'
+export { syncSchemaRef } from '../transformers.ts'
+export { getNestedAccessor, jsStringEscape, stringify, stringifyObject, toRegExpString, trimQuotes } from './strings.ts'
+export { collectUsedSchemaNames, containsCircularRef, findCircularSchemas } from './schemaGraph.ts'
+export { lazyGetter, mapSchemaItems, mapSchemaMembers, mapSchemaProperties } from './schemaTraversal.ts'
+export type { MappedProperty, MappedSchema, SchemaTransform } from './schemaTraversal.ts'
+export { buildGroupParam, buildTypeLiteral, caseParams, createOperationParams, resolveParamType } from './operationParams.ts'
+export type { BuildGroupArgs, ParamGroupType } from './operationParams.ts'