@kubb/ast 5.0.0-beta.62 → 5.0.0-beta.64

package/src/dedupe.ts

@@ -1,231 +0,0 @@
-import type { Node, OperationNode, SchemaNode } from './nodes/index.ts'
-import { createSchema } from './nodes/schema.ts'
-import { signatureOf } from './signature.ts'
-import { extractRefName } from './utils/index.ts'
-import { collectLazy, transform } from './visitor.ts'
-
-/**
- * A canonical destination for a deduplicated shape: the shared schema name and
- * the synthetic `$ref` path that points at it.
- */
-export type DedupeCanonical = {
-  /**
-   * Canonical schema name every duplicate occurrence refers to.
-   */
-  name: string
-  /**
-   * `$ref` path stored on the generated `ref` nodes (for example `#/components/schemas/Status`).
-   */
-  ref: string
-}
-
-/**
- * The result of {@link buildDedupePlan}: a lookup from structural signature to its
- * canonical target, plus the freshly hoisted definitions that must be added to
- * the schema list.
- */
-export type DedupePlan = {
-  /**
-   * Maps a structural signature to the canonical schema that represents it.
-   */
-  canonicalBySignature: Map<string, DedupeCanonical>
-  /**
-   * Maps the name of a top-level schema that duplicates a canonical one to that canonical, so
-   * references to the duplicate can be repointed at the first schema with the same content.
-   */
-  aliasNames: Map<string, DedupeCanonical>
-  /**
-   * New top-level schema definitions created for inline shapes that had no existing
-   * named component. Nested duplicates inside each definition are already collapsed.
-   */
-  hoisted: Array<SchemaNode>
-}
-
-/**
- * The lookups {@link applyDedupe} needs from a {@link DedupePlan}.
- */
-export type DedupeLookups = Pick<DedupePlan, 'canonicalBySignature' | 'aliasNames'>
-
-/**
- * Options that inject the naming and candidate policy into {@link buildDedupePlan}.
- * The mechanics (grouping, counting, rewriting) live here. The policy lives in the caller.
- */
-export type BuildDedupePlanOptions = {
-  /**
-   * Returns `true` when a node should be deduplicated. This is the only gate, so it must
-   * reject both ineligible kinds (return `false` for anything other than, say, enums and
-   * objects) and unsafe shapes (e.g. nodes that reference a circular schema).
-   */
-  isCandidate: (node: SchemaNode) => boolean
-  /**
-   * Produces the canonical name for an inline shape with no existing named component.
-   * Return `null` to leave the shape inline (for example when no contextual name exists).
-   */
-  nameFor: (node: SchemaNode, signature: string) => string | null
-  /**
-   * Builds the `$ref` path for a canonical name.
-   */
-  refFor: (name: string) => string
-  /**
-   * Minimum number of occurrences before a shape is deduplicated.
-   *
-   * @default 2
-   */
-  minOccurrences?: number
-}
-
-/**
- * Builds the shared `ref` replacement for a duplicate occurrence, carrying the
- * usage-slot and documentation fields that are not part of the canonical type.
- */
-function createRefNode(node: SchemaNode, canonical: DedupeCanonical): SchemaNode {
-  return createSchema({
-    type: 'ref',
-    name: canonical.name,
-    ref: canonical.ref,
-    optional: node.optional,
-    nullish: node.nullish,
-    readOnly: node.readOnly,
-    writeOnly: node.writeOnly,
-    deprecated: node.deprecated,
-    description: node.description,
-    default: node.default,
-    example: node.example,
-  })
-}
-
-/**
- * Rewrites a node, replacing every candidate sub-schema whose signature has a canonical
- * target with a `ref` to that target. Replacing a node with a `ref` prunes its subtree,
- * so nested duplicates inside a replaced shape are not visited again. A `ref` that points
- * at a duplicate top-level schema (see `aliasNames`) is repointed at the first schema with
- * the same content.
- *
- * Pass `skipRootMatch` when rewriting a canonical definition so its own root is not
- * turned into a reference to itself. Nested duplicates are still collapsed.
- *
- * @example
- * ```ts
- * const next = applyDedupe(operationNode, plan)
- * ```
- */
-export function applyDedupe(node: SchemaNode, plan: DedupeLookups, skipRootMatch?: boolean): SchemaNode
-export function applyDedupe(node: OperationNode, plan: DedupeLookups, skipRootMatch?: boolean): OperationNode
-export function applyDedupe(node: Node, plan: DedupeLookups, skipRootMatch = false): Node {
-  const { canonicalBySignature, aliasNames } = plan
-  if (canonicalBySignature.size === 0 && aliasNames.size === 0) return node
-
-  const root = node
-
-  return transform(node, {
-    schema(schemaNode) {
-      if (schemaNode.type === 'ref') {
-        const target = schemaNode.ref ? extractRefName(schemaNode.ref) : schemaNode.name
-        const canonical = target ? aliasNames.get(target) : undefined
-
-        return canonical ? { ...schemaNode, name: canonical.name, ref: canonical.ref } : undefined
-      }
-
-      const signature = signatureOf(schemaNode)
-      if (skipRootMatch && schemaNode === root) return undefined
-
-      const canonical = canonicalBySignature.get(signature)
-      if (!canonical) return undefined
-
-      return createRefNode(schemaNode, canonical)
-    },
-  })
-}
-
-/**
- * Strips usage-slot flags from a hoisted definition and applies its canonical name.
- * A standalone definition is never optional, so `optional`/`nullish` are cleared.
- */
-function cleanDefinition(node: SchemaNode, name: string): SchemaNode {
-  return { ...node, name, optional: undefined, nullish: undefined }
-}
-
-/**
- * Scans a forest of schema and operation nodes and produces a {@link DedupePlan}.
- *
- * A shape that occurs at least `minOccurrences` times is deduplicated: if any occurrence
- * is a named top-level schema, the first one becomes the canonical (so other top-level
- * duplicates and inline copies turn into references to it). Every other top-level name with
- * the same content is recorded in `aliasNames`, so refs to it can be repointed at the
- * canonical. Otherwise a new definition is hoisted using `nameFor`. The plan is then applied
- * per node with {@link applyDedupe}.
- *
- * @example
- * ```ts
- * const plan = buildDedupePlan([...schemaNodes, ...operationNodes], {
- *   isCandidate: (node) => node.type === 'enum' || node.type === 'object',
- *   nameFor: (node) => node.name ?? null,
- *   refFor: (name) => `#/components/schemas/${name}`,
- * })
- * ```
- */
-export function buildDedupePlan(roots: ReadonlyArray<Node>, options: BuildDedupePlanOptions): DedupePlan {
-  const { isCandidate, nameFor, refFor, minOccurrences = 2 } = options
-
-  const topLevelNodes = new Set<SchemaNode>()
-
-  type Group = {
-    count: number
-    representative: SchemaNode
-    topLevelNames: Array<string>
-  }
-  const groups = new Map<string, Group>()
-
-  function record(schemaNode: SchemaNode): void {
-    if (!isCandidate(schemaNode)) return
-    const signature = signatureOf(schemaNode)
-
-    const isTopLevel = topLevelNodes.has(schemaNode) && !!schemaNode.name
-    const group = groups.get(signature)
-    if (group) {
-      group.count++
-      if (isTopLevel) group.topLevelNames.push(schemaNode.name!)
-    } else {
-      groups.set(signature, { count: 1, representative: schemaNode, topLevelNames: isTopLevel ? [schemaNode.name!] : [] })
-    }
-  }
-
-  for (const root of roots) {
-    if (root.kind === 'Schema') topLevelNodes.add(root)
-    for (const schemaNode of collectLazy<SchemaNode>(root, { schema: (node) => node })) {
-      record(schemaNode)
-    }
-  }
-
-  const canonicalBySignature = new Map<string, DedupeCanonical>()
-  const aliasNames = new Map<string, DedupeCanonical>()
-  const pendingHoists: Array<{ name: string; representative: SchemaNode }> = []
-
-  for (const [signature, group] of groups) {
-    if (group.count < minOccurrences) continue
-
-    const [firstName, ...duplicateNames] = group.topLevelNames
-    if (firstName) {
-      const canonical: DedupeCanonical = { name: firstName, ref: refFor(firstName) }
-      canonicalBySignature.set(signature, canonical)
-      for (const duplicate of duplicateNames) {
-        aliasNames.set(duplicate, canonical)
-      }
-      continue
-    }
-
-    const name = nameFor(group.representative, signature)
-    if (!name) continue
-
-    canonicalBySignature.set(signature, { name, ref: refFor(name) })
-    pendingHoists.push({ name, representative: group.representative })
-  }
-
-  // Build hoisted definitions only after every canonical name is known, so nested
-  // duplicates inside a definition also resolve to refs.
-  const hoisted = pendingHoists.map(({ name, representative }) =>
-    cleanDefinition(applyDedupe(representative, { canonicalBySignature, aliasNames }, true), name),
-  )
-
-  return { canonicalBySignature, aliasNames, hoisted }
-}

package/src/defineMacro.ts

@@ -1,139 +0,0 @@
-import type { VisitorDepth } from './constants.ts'
-import type { VisitorKey } from './defineNode.ts'
-import { visitorKeys } from './defineNode.ts'
-import type { Node } from './nodes/index.ts'
-import type { Visitor, VisitorContext } from './visitor.ts'
-import { transform } from './visitor.ts'
-
-/**
- * Ordering hint shared by macros and plugins. `pre` runs before unmarked items, `post` after,
- * and `undefined` keeps declaration order.
- */
-export type Enforce = 'pre' | 'post'
-
-/**
- * Sort weight for an `enforce` hint. `pre` sorts before unmarked items and `post` after, so a plain
- * list keeps its authored order.
- */
-function enforceWeight(enforce?: Enforce): number {
-  if (enforce === 'pre') return 0
-  if (enforce === 'post') return 2
-  return 1
-}
-
-/**
- * A named, composable transform over the Kubb AST. It carries the same per-kind callbacks as a
- * {@link Visitor} (`schema`, `operation`, …), plus a `name`, an optional `enforce` order, and an
- * optional `when` gate. Macros run on the shared AST, so the same macro works across every adapter
- * and output target. Exports follow the `macro<Name>` convention, mirroring plugins (`pluginTs`).
- */
-export type Macro = Visitor & {
-  /**
-   * Macro identifier, surfaced in diagnostics. Follows the `macro<Name>` convention.
-   */
-  name: string
-  /**
-   * Ordering hint. `pre` macros run before unmarked macros, `post` macros run after.
-   * Ordering within a bucket follows list order.
-   */
-  enforce?: Enforce
-  /**
-   * Gate checked against the current node before any callback runs. When it returns `false`
-   * the macro is skipped for that node.
-   */
-  when?: (node: Node) => boolean
-}
-
-/**
- * Types a macro for inference and a single construction site, mirroring `definePlugin`.
- * Adds no runtime behavior.
- *
- * @example
- * ```ts
- * const macroUntagged = defineMacro({
- *   name: 'untagged',
- *   operation(node) {
- *     return node.tags?.length ? undefined : { ...node, tags: ['untagged'] }
- *   },
- * })
- * ```
- */
-export function defineMacro(macro: Macro): Macro {
-  return macro
-}
-
-type MacroCallback = (node: Node, context: VisitorContext) => Node | null | undefined
-
-type ChainProps = {
-  macros: ReadonlyArray<Macro>
-  key: VisitorKey
-  node: Node
-  context: VisitorContext
-}
-
-/**
- * Runs every macro's callback for one node kind in order, chaining the result so each macro sees
- * the previous macro's output. Returns `undefined` when nothing changed, so `transform` keeps the
- * original reference (structural sharing).
- */
-function chain({ macros, key, node, context }: ChainProps): Node | undefined {
-  let current = node
-
-  for (const macro of macros) {
-    const callback = macro[key] as MacroCallback | undefined
-    if (!callback) continue
-    if (macro.when && !macro.when(current)) continue
-
-    const next = callback(current, context)
-    if (next != null) current = next
-  }
-
-  return current === node ? undefined : current
-}
-
-/**
- * Folds an ordered list of macros into a single {@link Visitor} that `transform` (and the per-plugin
- * transform layer in `@kubb/core`) can run. Macros are stable-sorted by `enforce`, then applied
- * sequentially per node so later macros see earlier output. This differs from a plain visitor, which
- * has no names, ordering, or composition.
- *
- * @example
- * ```ts
- * const visitor = composeMacros([macroSimplifyUnion, macroDiscriminatorEnum])
- * const next = transform(root, visitor)
- * ```
- */
-export function composeMacros(macros: ReadonlyArray<Macro>): Visitor {
-  const ordered = [...macros].sort((a, b) => enforceWeight(a.enforce) - enforceWeight(b.enforce))
-
-  const visitor: Visitor = {}
-  for (const key of visitorKeys) {
-    if (!ordered.some((macro) => typeof macro[key] === 'function')) continue
-
-    const callback = (node: Node, context: VisitorContext) => chain({ macros: ordered, key, node, context })
-    ;(visitor as Record<VisitorKey, MacroCallback>)[key] = callback
-  }
-
-  return visitor
-}
-
-/**
- * Runs a list of macros over a node tree and returns the rewritten tree. Keeps `transform`'s
- * structural sharing, so an empty or no-op macro list returns the same reference. Pass
- * `depth: 'shallow'` to rewrite the root node only.
- *
- * @example
- * ```ts
- * const next = applyMacros(root, [macroIntegerToString])
- * ```
- *
- * @example Apply to the root node only
- * ```ts
- * const named = applyMacros(node, [macroEnumName({ parentName, propName, enumSuffix })], { depth: 'shallow' })
- * ```
- */
-export function applyMacros<TNode extends Node>(root: TNode, macros: ReadonlyArray<Macro>, options?: { depth?: VisitorDepth }): TNode {
-  if (macros.length === 0) return root
-
-  return transform(root, { ...composeMacros(macros), ...options }) as TNode
-}

package/src/defineNode.ts

@@ -1,105 +0,0 @@
-import type { Dialect } from './dialect.ts'
-import type { BaseNode, NodeKind } from './nodes/base.ts'
-
-/**
- * Visitor callback names, one per traversable node kind, in traversal order.
- * Kept in sync with the keys of `Visitor` in `visitor.ts`.
- */
-export const visitorKeys = ['input', 'output', 'operation', 'schema', 'property', 'parameter', 'response'] as const
-
-/**
- * One of the {@link visitorKeys} callback names.
- */
-export type VisitorKey = (typeof visitorKeys)[number]
-
-/**
- * Distributive `Omit` that preserves each member of a union.
- *
- * @example
- * ```ts
- * type A = { kind: 'a'; keep: string; drop: number }
- * type B = { kind: 'b'; keep: boolean; drop: number }
- * type Result = DistributiveOmit<A | B, 'drop'>
- * // -> { kind: 'a'; keep: string } | { kind: 'b'; keep: boolean }
- * ```
- */
-export type DistributiveOmit<T, K extends PropertyKey> = T extends unknown ? Omit<T, K> : never
-
-/**
- * Builds a type guard that matches nodes of the given `kind`.
- */
-function isKind<T extends BaseNode>(kind: NodeKind) {
-  return (node: unknown): node is T => (node as BaseNode).kind === kind
-}
-
-/**
- * The single definition derived from one {@link defineNode} call: the node's
- * `create` builder, its `is` guard, and the traversal metadata the registry
- * collects into the visitor tables.
- */
-export type NodeDef<TNode extends BaseNode = BaseNode, TInput = never> = {
-  /**
-   * Node discriminator this definition owns.
-   */
-  kind: NodeKind
-  /**
-   * Builds a node from its input, applying `defaults` and the optional `build` hook. An
-   * optional `dialect` is forwarded to `build` so nodes can derive spec-specific fields
-   * (e.g. a schema's `optional`/`nullish`) through `dialect.schema.optionality` when one is given.
-   */
-  create: (input: TInput, dialect?: Dialect) => TNode
-  /**
-   * Type guard matching this node kind.
-   */
-  is: (node: unknown) => node is TNode
-  /**
-   * Child node fields in traversal order. Feeds `VISITOR_KEYS`.
-   */
-  children?: ReadonlyArray<string>
-  /**
-   * Visitor callback name. Feeds `VISITOR_KEY_BY_KIND`.
-   */
-  visitorKey?: VisitorKey
-}
-
-type DefineNodeConfig<TNode extends BaseNode, TInput, TBuilt extends object> = {
-  kind: TNode['kind']
-  defaults?: Partial<TNode>
-  build?: (input: TInput, dialect?: Dialect) => TBuilt
-  children?: ReadonlyArray<string>
-  visitorKey?: VisitorKey
-}
-
-/**
- * Defines a node once and derives its `create` builder, `is` guard, and traversal
- * metadata. `create` merges `defaults`, the `build` hook (or the raw input), and the
- * `kind`, so node construction lives in one place without scattered `as` casts.
- *
- * @example Simple node
- * ```ts
- * const importDef = defineNode<ImportNode>({ kind: 'Import' })
- * const createImport = importDef.create
- * ```
- *
- * @example Node with a build hook
- * ```ts
- * const propertyDef = defineNode<PropertyNode, UserPropertyNode>({
- *   kind: 'Property',
- *   build: (props) => ({ ...props, required: props.required ?? false }),
- *   children: ['schema'],
- *   visitorKey: 'property',
- * })
- * ```
- */
-export function defineNode<TNode extends BaseNode, TInput = Omit<TNode, 'kind'>, TBuilt extends object = Omit<TNode, 'kind'>>(
-  config: DefineNodeConfig<TNode, TInput, TBuilt>,
-): NodeDef<TNode, TInput> {
-  const { kind, defaults, build, children, visitorKey } = config
-
-  function create(input: TInput, dialect?: Dialect): TNode {
-    const base = build ? build(input, dialect) : input
-    return { ...defaults, ...(base as object), kind } as TNode
-  }
-
-  return { kind, create, is: isKind<TNode>(kind), children, visitorKey }
-}