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

package/src/registry.ts

@@ -3,7 +3,6 @@ import { arrowFunctionDef, breakDef, constDef, functionDef, jsxDef, textDef, typ
 import { contentDef } from './nodes/content.ts'
 import { exportDef, fileDef, importDef, sourceDef } from './nodes/file.ts'
 import { functionParameterDef, functionParametersDef, indexedAccessTypeDef, objectBindingPatternDef, typeLiteralDef } from './nodes/function.ts'
-import type { Node, NodeKind } from './nodes/index.ts'
 import { inputDef } from './nodes/input.ts'
 import { operationDef } from './nodes/operation.ts'
 import { outputDef } from './nodes/output.ts'
@@ -13,9 +12,39 @@ import { requestBodyDef } from './nodes/requestBody.ts'
 import { responseDef } from './nodes/response.ts'
 import { schemaDef } from './nodes/schema.ts'
 
+// Surface every def from one place so the package barrel re-exports them with `export * from './registry.ts'`.
+// Adding a node means adding its `defineNode` to a `nodes/*.ts` file and listing it in `nodeDefs` below, nothing else.
+export {
+  arrowFunctionDef,
+  breakDef,
+  constDef,
+  contentDef,
+  exportDef,
+  fileDef,
+  functionDef,
+  functionParameterDef,
+  functionParametersDef,
+  importDef,
+  indexedAccessTypeDef,
+  inputDef,
+  jsxDef,
+  objectBindingPatternDef,
+  operationDef,
+  outputDef,
+  parameterDef,
+  propertyDef,
+  requestBodyDef,
+  responseDef,
+  schemaDef,
+  sourceDef,
+  textDef,
+  typeDef,
+  typeLiteralDef,
+}
+
 /**
  * Every node definition. Adding a node means adding its `defineNode` to one
- * `nodes/*.ts` file and listing it here. The visitor tables below derive from it.
+ * `nodes/*.ts` file and listing it here. The visitor tables in `visitor.ts` derive from it.
  */
 export const nodeDefs = [
   inputDef,
@@ -44,27 +73,3 @@ export const nodeDefs = [
   sourceDef,
   fileDef,
 ] satisfies ReadonlyArray<NodeDef>
-
-/**
- * Child node fields per node kind, in traversal order (Babel's `VISITOR_KEYS`).
- * Derived from each definition's `children`.
- */
-export 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`.
- */
-export 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.
- */
-export 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>>

package/src/signature.ts

@@ -170,9 +170,9 @@ function describeShape(node: SchemaNode): string {
 }
 
 /**
- * Node → digest cache, keyed by identity. A `WeakMap` so entries die with the node, and so a tree
- * hashed during dedupe planning is not walked again when it is rewritten during streaming. Reuse
- * is safe because a signature depends only on content, and nodes are immutable once created.
+ * Caches the digest per node, keyed by identity. A `WeakMap` so entries die with the node, and so
+ * a tree hashed during dedupe planning is not walked again when it is rewritten during streaming.
+ * Reuse is safe because a signature depends only on content, and nodes are immutable once created.
  */
 const signatureCache = new WeakMap<SchemaNode, string>()
 

package/src/transformers.ts

@@ -2,7 +2,7 @@ import { isScalarPrimitive } from './constants.ts'
 import { narrowSchema } from './guards.ts'
 import { createProperty } from './nodes/property.ts'
 import { createSchema, type SchemaNode } from './nodes/schema.ts'
-import { enumPropName } from './utils/index.ts'
+import { enumPropName } from './utils/refs.ts'
 
 /**
  * Replaces a discriminator property's schema with a string enum of allowed values.
@@ -162,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

@@ -2,59 +2,8 @@ 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 {
-  ArraySchemaNode,
-  ArrowFunctionNode,
-  CodeNode,
-  ConstNode,
-  DateSchemaNode,
-  DatetimeSchemaNode,
-  EnumSchemaNode,
-  ExportNode,
-  FileNode,
-  FunctionNode,
-  FunctionParamKind,
-  FunctionParameterNode,
-  FunctionParametersNode,
-  FunctionParamNode,
-  HttpMethod,
-  HttpOperationNode,
-  ImportNode,
-  IndexedAccessTypeNode,
-  InputMeta,
-  InputNode,
-  IntersectionSchemaNode,
-  JSDocNode,
-  JsxNode,
-  Node,
-  NodeKind,
-  NumberSchemaNode,
-  ObjectBindingPatternNode,
-  ObjectSchemaNode,
-  OperationNode,
-  OutputNode,
-  ParameterLocation,
-  ParameterNode,
-  PrimitiveSchemaType,
-  PropertyNode,
-  RefSchemaNode,
-  ResponseNode,
-  ScalarSchemaType,
-  SchemaNode,
-  SchemaNodeByType,
-  SchemaType,
-  SourceNode,
-  StatusCode,
-  StringSchemaNode,
-  TextNode,
-  TimeSchemaNode,
-  TypeExpression,
-  TypeLiteralNode,
-  TypeNode,
-  UnionSchemaNode,
-  UrlSchemaNode,
-} from './nodes/index.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 { OperationParamsResolver } from './utils/ast.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/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
+}