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

package/src/defineMacro.ts

@@ -0,0 +1,139 @@
+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/{node.ts → defineNode.ts}

@@ -1,11 +1,16 @@
+import type { Dialect } from './dialect.ts'
 import type { BaseNode, NodeKind } from './nodes/base.ts'
-import type { SchemaNode } from './nodes/index.ts'
 
 /**
- * Visitor callback names, one per traversable node kind. Kept in sync with the
- * keys of `Visitor` in `visitor.ts`.
+ * Visitor callback names, one per traversable node kind, in traversal order.
+ * Kept in sync with the keys of `Visitor` in `visitor.ts`.
  */
-type VisitorKey = 'input' | 'output' | 'operation' | 'schema' | 'property' | 'parameter' | 'response'
+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.
@@ -27,25 +32,6 @@ function isKind<T extends BaseNode>(kind: NodeKind) {
   return (node: unknown): node is T => (node as BaseNode).kind === kind
 }
 
-/**
- * Updates a schema's `optional` and `nullish` flags from a parent's `required`
- * value and the schema's own `nullable`. Mirrors how OpenAPI parameters and
- * object properties combine "required" and "nullable" into a single AST.
- *
- * - Non-required + non-nullable → `optional: true`.
- * - Non-required + nullable → `nullish: true`.
- * - Required → both flags cleared.
- */
-export function syncOptionality(schema: SchemaNode, required: boolean): SchemaNode {
-  const nullable = schema.nullable ?? false
-
-  return {
-    ...schema,
-    optional: !required && !nullable ? true : undefined,
-    nullish: !required && nullable ? true : undefined,
-  }
-}
-
 /**
  * The single definition derived from one {@link defineNode} call: the node's
  * `create` builder, its `is` guard, and the traversal metadata the registry
@@ -57,9 +43,11 @@ export type NodeDef<TNode extends BaseNode = BaseNode, TInput = never> = {
    */
   kind: NodeKind
   /**
-   * Builds a node from its input, applying `defaults` and the optional `build` hook.
+   * 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) => TNode
+  create: (input: TInput, dialect?: Dialect) => TNode
   /**
    * Type guard matching this node kind.
    */
@@ -72,20 +60,14 @@ export type NodeDef<TNode extends BaseNode = BaseNode, TInput = never> = {
    * Visitor callback name. Feeds `VISITOR_KEY_BY_KIND`.
    */
   visitorKey?: VisitorKey
-  /**
-   * When `true`, `create` is rerun after children are rebuilt so computed fields
-   * stay in sync. Feeds `nodeRebuilders`.
-   */
-  rebuild?: boolean
 }
 
 type DefineNodeConfig<TNode extends BaseNode, TInput, TBuilt extends object> = {
   kind: TNode['kind']
   defaults?: Partial<TNode>
-  build?: (input: TInput) => TBuilt
+  build?: (input: TInput, dialect?: Dialect) => TBuilt
   children?: ReadonlyArray<string>
   visitorKey?: VisitorKey
-  rebuild?: boolean
 }
 
 /**
@@ -93,36 +75,31 @@ type DefineNodeConfig<TNode extends BaseNode, TInput, TBuilt extends object> = {
  * 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.
  *
- * Set `rebuild: true` when the `build` hook derives fields from children. After a
- * transform rewrites those children, the registry reruns `create` so the derived
- * fields stay correct.
- *
  * @example Simple node
  * ```ts
  * const importDef = defineNode<ImportNode>({ kind: 'Import' })
  * const createImport = importDef.create
  * ```
  *
- * @example Node with a build hook that is rerun on transform
+ * @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',
- *   rebuild: true,
  * })
  * ```
  */
 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, rebuild } = config
+  const { kind, defaults, build, children, visitorKey } = config
 
-  function create(input: TInput): TNode {
-    const base = build ? build(input) : input
+  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, rebuild }
+  return { kind, create, is: isKind<TNode>(kind), children, visitorKey }
 }

package/src/dialect.ts

@@ -1,53 +1,76 @@
+import type { SchemaNode } from './nodes/index.ts'
+
 /**
  * The spec-specific questions a schema parser answers while turning a source document into Kubb
  * AST nodes. The rest of the pipeline is generic JSON Schema, so this is the one seam where
  * OpenAPI, AsyncAPI, and plain JSON Schema differ.
  */
 export type SchemaDialect<TSchema = unknown, TRef = TSchema, TDiscriminated = TSchema, TDocument = unknown> = {
-  /**
-   * Identifies the dialect in logs and diagnostics.
-   */
-  name: string
   /**
    * Whether the schema is nullable.
    */
-  isNullable: (schema?: TSchema) => boolean
+  isNullable(schema?: TSchema): boolean
   /**
    * Whether the value is a `$ref` pointer.
    */
-  isReference: (value?: unknown) => value is TRef
+  isReference(value?: unknown): value is TRef
   /**
    * Whether the schema carries a discriminator for polymorphism.
    */
-  isDiscriminator: (value?: unknown) => value is TDiscriminated
+  isDiscriminator(value?: unknown): value is TDiscriminated
   /**
    * Whether the schema is binary data, converted to a `blob` node.
    */
-  isBinary: (schema: TSchema) => boolean
+  isBinary(schema: TSchema): boolean
   /**
    * Resolves a local `$ref` against the document, or nullish when it cannot.
    */
-  resolveRef: <TResolved>(document: TDocument, ref: string) => TResolved | null | undefined
+  resolveRef<TResolved>(document: TDocument, ref: string): TResolved | null | undefined
+  /**
+   * Derives a schema's `optional`/`nullish` flags from a parent's `required` value and the
+   * schema's own `nullable`. How "required" and "nullable" combine is spec-specific, so the
+   * dialect owns it. Method syntax keeps a concrete dialect assignable to the base
+   * `SchemaDialect` (bivariant parameters).
+   */
+  optionality(schema: SchemaNode, required: boolean): SchemaNode
+}
+
+/**
+ * A spec adapter's dialect. `name` identifies it in logs and diagnostics; `schema` holds the
+ * spec-specific schema questions the parser answers.
+ */
+export type Dialect<TSchema = unknown, TRef = TSchema, TDiscriminated = TSchema, TDocument = unknown> = {
+  /**
+   * Identifies the dialect in logs and diagnostics.
+   */
+  name: string
+  /**
+   * The spec-specific schema behavior. See {@link SchemaDialect}.
+   */
+  schema: SchemaDialect<TSchema, TRef, TDiscriminated, TDocument>
 }
 
 /**
- * Types a {@link SchemaDialect} for an adapter. Adds no runtime behavior and only pins the
+ * Types a {@link Dialect} for an adapter. Adds no runtime behavior and only pins the
  * dialect's type for inference.
  *
  * @example
  * ```ts
- * export const oasDialect = defineSchemaDialect({
+ * export const oasDialect = defineDialect({
  *   name: 'oas',
- *   isNullable,
- *   isReference,
- *   isDiscriminator,
- *   isBinary: (schema) => schema.type === 'string' && schema.contentMediaType === 'application/octet-stream',
- *   resolveRef,
+ *   schema: {
+ *     isNullable,
+ *     isReference,
+ *     isDiscriminator,
+ *     isBinary: (schema) => schema.type === 'string' && schema.contentMediaType === 'application/octet-stream',
+ *     resolveRef,
+ *     optionality,
+ *   },
  * })
  * ```
  */
-export function defineSchemaDialect<TSchema, TRef, TDiscriminated, TDocument>(
-  dialect: SchemaDialect<TSchema, TRef, TDiscriminated, TDocument>,
-): SchemaDialect<TSchema, TRef, TDiscriminated, TDocument> {
+export function defineDialect<TSchema, TRef, TDiscriminated, TDocument>(
+  dialect: Dialect<TSchema, TRef, TDiscriminated, TDocument>,
+): Dialect<TSchema, TRef, TDiscriminated, TDocument> {
   return dialect
 }

package/src/factory.ts

@@ -1,16 +1,12 @@
-import { hash } from 'node:crypto'
-import path from 'node:path'
-import { trimExtName } from '@internals/utils'
-import type { FileNode, Node } from './nodes/index.ts'
-import { extractStringsFromNodes } from './utils/extractStringsFromNodes.ts'
-import { combineExports, combineImports, combineSources } from './utils/fileMerge.ts'
+import type { Node } from './nodes/index.ts'
 
 // Node constructors, grouped under the `factory` namespace the way the TypeScript compiler exposes
 // `ts.factory.createX`. Aggregating them here lets `export * as factory from './factory.ts'` in the
 // barrel surface every `createX` alongside the `createFile`/`update` helpers from a single module.
 export { createArrowFunction, createBreak, createConst, createFunction, createJsx, createText, createType } from './nodes/code.ts'
 export { createContent } from './nodes/content.ts'
-export { createExport, createImport, createSource } from './nodes/file.ts'
+export { createExport, createFile, createImport, createSource } from './nodes/file.ts'
+export type { UserFileNode } from './nodes/file.ts'
 export { createFunctionParameter, createFunctionParameters, createIndexedAccessType, createObjectBindingPattern, createTypeLiteral } from './nodes/function.ts'
 export { createInput } from './nodes/input.ts'
 export { createOperation } from './nodes/operation.ts'
@@ -46,86 +42,3 @@ export function update<T extends Node>(node: T, changes: Partial<T>): T {
 
   return node
 }
-
-/**
- * Input descriptor for {@link createFile}, before `id`, `name`, and `extname` are computed
- * and `imports`/`exports`/`sources` are deduplicated.
- */
-export type UserFileNode<TMeta extends object = object> = Omit<FileNode<TMeta>, 'kind' | 'id' | 'name' | 'extname' | 'imports' | 'exports' | 'sources'> &
-  Pick<Partial<FileNode<TMeta>>, 'imports' | 'exports' | 'sources'>
-
-/**
- * Creates a fully resolved `FileNode` from a file input descriptor.
- *
- * Computes:
- * - `id` SHA256 hash of the file path
- * - `name` `baseName` without extension
- * - `extname` extension extracted from `baseName`
- *
- * Deduplicates:
- * - `sources` via `combineSources`
- * - `exports` via `combineExports`
- * - `imports` via `combineImports` (also filters unused imports)
- *
- * @throws {Error} when `baseName` has no extension.
- *
- * @example
- * ```ts
- * const file = createFile({
- *   baseName: 'petStore.ts',
- *   path: 'src/models/petStore.ts',
- *   sources: [createSource({ name: 'Pet', nodes: [createText('export type Pet = { id: number }')] })],
- *   imports: [createImport({ name: ['z'], path: 'zod' })],
- *   exports: [createExport({ name: ['Pet'], path: './petStore' })],
- * })
- * // file.id      = SHA256 hash of 'src/models/petStore.ts'
- * // file.name    = 'petStore'
- * // file.extname = '.ts'
- * ```
- */
-export function createFile<TMeta extends object = object>(input: UserFileNode<TMeta>): FileNode<TMeta> {
-  const rawExtname = path.extname(input.baseName)
-  // Handle dotfile basename like '.ts' where path.extname returns ''
-  const extname = (rawExtname || (input.baseName.startsWith('.') ? input.baseName : '')) as `.${string}`
-  if (!extname) {
-    throw new Error(`No extname found for ${input.baseName}`)
-  }
-
-  const source = (input.sources ?? [])
-    .flatMap((item) => item.nodes ?? [])
-    .map((node) => extractStringsFromNodes([node]))
-    .filter(Boolean)
-    .join('\n\n')
-  const resolvedExports = input.exports?.length ? combineExports(input.exports) : []
-  const combinedImports = input.imports?.length ? combineImports(input.imports, resolvedExports, source || undefined) : []
-  const localNames = new Set((input.sources ?? []).map((item) => item.name).filter((name): name is string => Boolean(name)))
-  const nameOf = (item: string | { propertyName: string; name?: string }): string => (typeof item === 'string' ? item : (item.name ?? item.propertyName))
-  // Drop self-imports. Consolidating output (`mode: 'file'`) can place a symbol's
-  // definition and a cross-file import of it in the same file. The first pass catches imports that
-  // resolve to this file's own path. The second drops imports of names the file already defines,
-  // the case consolidation produces when the import path no longer matches `input.path`. Sources
-  // stay intact, so the local definition remains. Bare specifiers like `'zod'` never match a path.
-  const resolvedImports = combinedImports
-    .filter((imp) => imp.path !== input.path)
-    .flatMap((imp) => {
-      if (!Array.isArray(imp.name)) {
-        return typeof imp.name === 'string' && localNames.has(imp.name) ? [] : [imp]
-      }
-      const kept = imp.name.filter((item) => !localNames.has(nameOf(item)))
-      if (!kept.length) return []
-      return [kept.length === imp.name.length ? imp : { ...imp, name: kept }]
-    })
-  const resolvedSources = input.sources?.length ? combineSources(input.sources) : []
-
-  return {
-    kind: 'File',
-    ...input,
-    id: hash('sha256', input.path, 'hex'),
-    name: trimExtName(input.baseName),
-    extname,
-    imports: resolvedImports,
-    exports: resolvedExports,
-    sources: resolvedSources,
-    meta: input.meta ?? ({} as TMeta),
-  }
-}

package/src/index.ts

@@ -1,19 +1,13 @@
-export { httpMethods, schemaTypes } from './constants.ts'
+export { schemaTypes } from './constants.ts'
 export { applyDedupe, buildDedupePlan } from './dedupe.ts'
-export { defineSchemaDialect } from './dialect.ts'
-// Node constructors, also published as the `@kubb/ast/factory` subpath, mirroring `ts.factory.createX`.
-export * as factory from './factory.ts'
+export { defineDialect } from './dialect.ts'
 export { isHttpOperationNode, narrowSchema } from './guards.ts'
-export { defineNode } from './node.ts'
-export type { NodeDef } from './node.ts'
-export { syncOptionality } from './node.ts'
-// Every node def plus `nodeDefs` in one line, so adding a node never edits this barrel. The visitor
-// tables derived from `nodeDefs` stay internal to `visitor.ts`.
-export * from './registry.ts'
-export { createPrinterFactory, definePrinter } from './printer.ts'
+export { applyMacros, composeMacros, defineMacro } from './defineMacro.ts'
+export { defineNode } from './defineNode.ts'
+export { createPrinterFactory, definePrinter } from './definePrinter.ts'
 export { signatureOf } from './signature.ts'
-export { mergeAdjacentObjectsLazy, setDiscriminatorEnum, setEnumName, simplifyUnion } from './transformers.ts'
-export type * from './types.ts'
-// The node/AST helpers in ./utils/ live on the `@kubb/ast/utils` subpath, not the root barrel.
-export { extractStringsFromNodes } from './utils/extractStringsFromNodes.ts'
 export { collect, transform, walk } from './visitor.ts'
+
+export * as factory from './factory.ts'
+export * from './registry.ts'
+export type * from './types.ts'

package/src/macros/index.ts

@@ -0,0 +1,3 @@
+export { macroDiscriminatorEnum } from './macroDiscriminatorEnum.ts'
+export { macroEnumName } from './macroEnumName.ts'
+export { macroSimplifyUnion } from './macroSimplifyUnion.ts'

package/src/macros/macroDiscriminatorEnum.ts

@@ -0,0 +1,50 @@
+import { defineMacro } from '../defineMacro.ts'
+import { narrowSchema } from '../guards.ts'
+import { createProperty } from '../nodes/property.ts'
+import { createSchema } from '../nodes/schema.ts'
+
+type Props = {
+  propertyName: string
+  values: Array<string>
+  enumName?: string
+}
+
+/**
+ * Builds a macro that replaces a discriminator property's schema with a string enum of the given
+ * values. Object schemas that lack the property are returned unchanged.
+ *
+ * @example
+ * ```ts
+ * const macro = macroDiscriminatorEnum({ propertyName: 'type', values: ['dog', 'cat'] })
+ * const next = applyMacros(objectSchema, [macro], { depth: 'shallow' })
+ * ```
+ */
+export function macroDiscriminatorEnum({ propertyName, values, enumName }: Props) {
+  return defineMacro({
+    name: 'discriminator-enum',
+    schema(node) {
+      const objectNode = narrowSchema(node, 'object')
+      if (!objectNode?.properties?.length) return undefined
+      if (!objectNode.properties.some((prop) => prop.name === propertyName)) return undefined
+
+      return createSchema({
+        ...objectNode,
+        properties: objectNode.properties.map((prop) => {
+          if (prop.name !== propertyName) return prop
+
+          return createProperty({
+            ...prop,
+            schema: createSchema({
+              type: 'enum',
+              primitive: 'string',
+              enumValues: values,
+              name: enumName,
+              readOnly: prop.schema.readOnly,
+              writeOnly: prop.schema.writeOnly,
+            }),
+          })
+        }),
+      })
+    },
+  })
+}

package/src/macros/macroEnumName.ts

@@ -0,0 +1,33 @@
+import { defineMacro } from '../defineMacro.ts'
+import { narrowSchema } from '../guards.ts'
+import { enumPropName } from '../utils/refs.ts'
+
+type Props = {
+  parentName: string | null | undefined
+  propName: string
+  enumSuffix: string
+}
+
+/**
+ * Builds a macro that names an inline enum schema from its parent and property name. Boolean enums
+ * are left anonymous; non-enum nodes are returned unchanged.
+ *
+ * @example
+ * ```ts
+ * const macro = macroEnumName({ parentName: 'Pet', propName: 'status', enumSuffix: 'enum' })
+ * const named = applyMacros(propSchema, [macro], { depth: 'shallow' })
+ * ```
+ */
+export function macroEnumName({ parentName, propName, enumSuffix }: Props) {
+  return defineMacro({
+    name: 'enum-name',
+    schema(node) {
+      const enumNode = narrowSchema(node, 'enum')
+
+      if (enumNode?.primitive === 'boolean') return { ...node, name: null }
+      if (enumNode) return { ...node, name: enumPropName(parentName, propName, enumSuffix) }
+
+      return undefined
+    },
+  })
+}

package/src/macros/macroSimplifyUnion.ts

@@ -0,0 +1,60 @@
+import { defineMacro } from '../defineMacro.ts'
+import { narrowSchema } from '../guards.ts'
+import type { SchemaNode } from '../nodes/schema.ts'
+
+type ScalarPrimitive = 'string' | 'number' | 'integer' | 'bigint' | 'boolean'
+
+/**
+ * Scalar primitive schema types used for union simplification and type narrowing.
+ */
+const SCALAR_PRIMITIVE_TYPES = new Set<ScalarPrimitive>(['string', 'number', 'integer', 'bigint', 'boolean'])
+
+function isScalarPrimitive(type: string): type is ScalarPrimitive {
+  return SCALAR_PRIMITIVE_TYPES.has(type as ScalarPrimitive)
+}
+
+/**
+ * Filters union members, dropping enum members that a broader scalar primitive already covers.
+ */
+function simplifyUnionMembers(members: Array<SchemaNode>): Array<SchemaNode> {
+  const scalarPrimitives = new Set(members.filter((member) => isScalarPrimitive(member.type)).map((m) => m.type))
+  if (!scalarPrimitives.size) return members
+
+  return members.filter((member) => {
+    const enumNode = narrowSchema(member, 'enum')
+    if (!enumNode) return true
+
+    const primitive = enumNode.primitive
+    if (!primitive) return true
+
+    const enumValueCount = enumNode.namedEnumValues?.length ?? enumNode.enumValues?.length ?? 0
+    if (enumValueCount <= 1) return true
+
+    if (scalarPrimitives.has(primitive)) return false
+    if ((primitive === 'integer' || primitive === 'number') && (scalarPrimitives.has('integer') || scalarPrimitives.has('number'))) return false
+
+    return true
+  })
+}
+
+/**
+ * Removes union members a broader scalar primitive already covers, such as a multi-value string enum
+ * sitting next to a plain `string`. Single-value enums are kept.
+ *
+ * @example
+ * ```ts
+ * const next = applyMacros(unionSchema, [macroSimplifyUnion], { depth: 'shallow' })
+ * ```
+ */
+export const macroSimplifyUnion = defineMacro({
+  name: 'simplify-union',
+  schema(node) {
+    const unionNode = narrowSchema(node, 'union')
+    if (!unionNode?.members?.length) return undefined
+
+    const simplified = simplifyUnionMembers(unionNode.members)
+    if (simplified.length === unionNode.members.length) return undefined
+
+    return { ...unionNode, members: simplified }
+  },
+})