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

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

@@ -1,297 +1,9 @@
-import { isIdentifier, pascalCase, singleQuote } from '@internals/utils'
-import { INDENT } from '../constants.ts'
-
 export { isValidVarName } from '@internals/utils'
-
-/**
- * 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 value to a single-quoted string literal, stripping any surrounding quote
- * characters first. Escaping comes from `JSON.stringify`, then the quote style switches to single
- * quotes so 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("']?.['")}']`}`
-}
-
-/**
- * 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}`
-}
-
-/**
- * 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
-}
-
-/**
- * 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(' '))
-}
-
-/**
- * Returns the discriminator key whose mapping value matches `ref`, or `null` when there is no match.
- *
- * @example
- * ```ts
- * findDiscriminator({ dog: '#/components/schemas/Dog' }, '#/components/schemas/Dog') // 'dog'
- * ```
- */
-export function findDiscriminator(mapping: Record<string, string> | undefined, ref: string | undefined): string | null {
-  if (!mapping || !ref) return null
-  return Object.entries(mapping).find(([, value]) => value === ref)?.[0] ?? null
-}
+export { buildJSDoc, buildList, buildObject, objectKey } from './codegen.ts'
+export { extractStringsFromNodes } from './extractStringsFromNodes.ts'
+export { childName, enumPropName, extractRefName, isStringType, resolveGroupType } 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 { buildGroupParam, buildTypeLiteral, caseParams, createOperationParams, resolveParamType } from './operationParams.ts'
+export type { BuildGroupArgs, ParamGroupType } from './operationParams.ts'