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

package/src/nodes/schema.ts

@@ -1,3 +1,5 @@
+import type { InferSchemaNode } from '../infer.ts'
+import { defineNode, type DistributiveOmit } from '../node.ts'
 import type { BaseNode } from './base.ts'
 import type { PropertyNode } from './property.ts'
 
@@ -58,12 +60,12 @@ export type PrimitiveSchemaType =
 /**
  * Composite schema types.
  */
-export type ComplexSchemaType = 'tuple' | 'union' | 'intersection' | 'enum'
+type ComplexSchemaType = 'tuple' | 'union' | 'intersection' | 'enum'
 
 /**
  * Schema types that need special handling in generators.
  */
-export type SpecialSchemaType = 'ref' | 'datetime' | 'time' | 'uuid' | 'email' | 'url' | 'ipv4' | 'ipv6' | 'blob'
+type SpecialSchemaType = 'ref' | 'datetime' | 'time' | 'uuid' | 'email' | 'url' | 'ipv4' | 'ipv6' | 'blob'
 
 /**
  * All schema type strings.
@@ -154,6 +156,10 @@ type SchemaNodeBase = BaseNode & {
    * For example, this is `'string'` for a `uuid` schema.
    */
   primitive?: PrimitiveSchemaType
+  /**
+   * Schema `format` value.
+   */
+  format?: string
 }
 
 /**
@@ -174,7 +180,7 @@ export type ObjectSchemaNode = SchemaNodeBase & {
    */
   type: 'object'
   /**
-   * Primitive type — always `'object'` for object schemas.
+   * Primitive type, always `'object'` for object schemas.
    */
   primitive: 'object'
   /**
@@ -274,8 +280,9 @@ export type UnionSchemaNode = CompositeSchemaNodeBase & {
    */
   discriminatorPropertyName?: string
   /**
-   * Logical strategy applied to union members: 'one' means exactly one member must be valid (from `oneOf`),
-   * 'any' means any number of members can be valid (from `anyOf`).
+   * How many union members must be valid.
+   * - `'one'`: exactly one member, from `oneOf`
+   * - `'any'`: any number of members, from `anyOf`
    */
   strategy?: 'one' | 'any'
 }
@@ -302,7 +309,7 @@ export type IntersectionSchemaNode = CompositeSchemaNodeBase & {
 /**
  * One named enum item.
  */
-export type EnumValueNode = {
+type EnumValueNode = {
   /**
    * Enum item name.
    */
@@ -364,8 +371,9 @@ export type RefSchemaNode = SchemaNodeBase & {
   type: 'ref'
   /**
    * Referenced schema name.
+   * `null` means Kubb has processed this and determined there is no applicable name.
    */
-  name?: string
+  name?: string | null
   /**
    * Original `$ref` path, for example, `#/components/schemas/Order`.
    * Used to resolve names later.
@@ -376,14 +384,12 @@ export type RefSchemaNode = SchemaNodeBase & {
    */
   pattern?: string
   /**
-   * The fully-parsed schema that this ref resolves to.
-   * Populated during OAS parsing when the referenced definition can be resolved.
-   * `undefined` when the ref cannot be resolved or is part of a circular chain.
-   *
-   * Useful for inspecting the referenced schema's structure (e.g. `primitive`, `properties`)
-   * without following the reference manually.
+   * The fully-parsed schema this ref resolves to, so its structure (`primitive`, `properties`)
+   * can be read without following the reference. Populated during OAS parsing when the
+   * definition resolves, `null` when it can't or the ref is circular, and `undefined` when
+   * resolution has not been attempted.
    */
-  schema?: SchemaNode
+  schema?: SchemaNode | null
 }
 
 /**
@@ -556,7 +562,7 @@ export type UrlSchemaNode = SchemaNodeBase & {
  * const uuidSchema: FormatStringSchemaNode = { kind: 'Schema', type: 'uuid', min: 36, max: 36 }
  * ```
  */
-export type FormatStringSchemaNode = SchemaNodeBase & {
+type FormatStringSchemaNode = SchemaNodeBase & {
   /**
    * Schema type discriminator.
    */
@@ -579,7 +585,7 @@ export type FormatStringSchemaNode = SchemaNodeBase & {
  * const ipv4Schema: Ipv4SchemaNode = { kind: 'Schema', type: 'ipv4' }
  * ```
  */
-export type Ipv4SchemaNode = SchemaNodeBase & {
+type Ipv4SchemaNode = SchemaNodeBase & {
   /**
    * Schema type discriminator.
    */
@@ -594,7 +600,7 @@ export type Ipv4SchemaNode = SchemaNodeBase & {
  * const ipv6Schema: Ipv6SchemaNode = { kind: 'Schema', type: 'ipv6' }
  * ```
  */
-export type Ipv6SchemaNode = SchemaNodeBase & {
+type Ipv6SchemaNode = SchemaNodeBase & {
   /**
    * Schema type discriminator.
    */
@@ -654,3 +660,73 @@ export type SchemaNode =
   | Ipv4SchemaNode
   | Ipv6SchemaNode
   | ScalarSchemaNode
+
+type CreateSchemaObjectInput = Omit<ObjectSchemaNode, 'kind' | 'properties' | 'primitive'> & { properties?: Array<PropertyNode>; primitive?: 'object' }
+type CreateSchemaInput = CreateSchemaObjectInput | DistributiveOmit<Exclude<SchemaNode, ObjectSchemaNode>, 'kind'>
+type CreateSchemaOutput<T extends CreateSchemaInput> = InferSchemaNode<T> & {
+  kind: 'Schema'
+}
+
+/**
+ * Maps schema `type` to its underlying `primitive`.
+ * Primitive types map to themselves. Special string formats map to `'string'`.
+ * Complex types (`ref`, `enum`, `union`, `intersection`, `tuple`, `blob`) are left unset.
+ */
+const TYPE_TO_PRIMITIVE: Partial<Record<SchemaNode['type'], PrimitiveSchemaType>> = {
+  string: 'string',
+  number: 'number',
+  integer: 'integer',
+  bigint: 'bigint',
+  boolean: 'boolean',
+  null: 'null',
+  any: 'any',
+  unknown: 'unknown',
+  void: 'void',
+  never: 'never',
+  object: 'object',
+  array: 'array',
+  date: 'date',
+  uuid: 'string',
+  email: 'string',
+  url: 'string',
+  datetime: 'string',
+  time: 'string',
+}
+
+/**
+ * Definition for the {@link SchemaNode}. Object schemas default `properties` to an
+ * empty array, and `primitive` is inferred from `type` when not explicitly provided.
+ */
+export const schemaDef = defineNode<SchemaNode, CreateSchemaInput>({
+  kind: 'Schema',
+  build: (props) => {
+    if (props.type === 'object') {
+      return { properties: [], primitive: 'object' as const, ...props }
+    }
+
+    return { primitive: TYPE_TO_PRIMITIVE[props.type as keyof typeof TYPE_TO_PRIMITIVE], ...props }
+  },
+  children: ['properties', 'items', 'members', 'additionalProperties'],
+  visitorKey: 'schema',
+})
+
+/**
+ * Creates a `SchemaNode`, narrowed to the variant of `props.type`.
+ *
+ * @example
+ * ```ts
+ * const scalar = createSchema({ type: 'string' })
+ * // { kind: 'Schema', type: 'string', primitive: 'string' }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const object = createSchema({ type: 'object' })
+ * // { kind: 'Schema', type: 'object', primitive: 'object', properties: [] }
+ * ```
+ */
+export function createSchema<T extends CreateSchemaInput>(props: T): CreateSchemaOutput<T>
+export function createSchema(props: CreateSchemaInput): SchemaNode
+export function createSchema(props: CreateSchemaInput): SchemaNode {
+  return schemaDef.create(props)
+}

package/src/printer.ts

@@ -13,12 +13,12 @@ import type { SchemaNode, SchemaNodeByType, SchemaType } from './nodes/index.ts'
  * }
  * ```
  */
-export type PrinterHandlerContext<TOutput, TOptions extends object> = {
+type PrinterHandlerContext<TOutput, TOptions extends object> = {
   /**
    * Recursively transform a nested `SchemaNode` to `TOutput` using the node-level handlers.
    * Use `this.transform` inside `nodes` handlers and inside the `print` override.
    */
-  transform: (node: SchemaNode) => TOutput | null | undefined
+  transform: (node: SchemaNode) => TOutput | null
   /**
    * Options for this printer instance.
    */
@@ -37,16 +37,16 @@ export type PrinterHandlerContext<TOutput, TOptions extends object> = {
  * }
  * ```
  */
-export type PrinterHandler<TOutput, TOptions extends object, T extends SchemaType = SchemaType> = (
+type PrinterHandler<TOutput, TOptions extends object, T extends SchemaType = SchemaType> = (
   this: PrinterHandlerContext<TOutput, TOptions>,
   node: SchemaNodeByType[T],
-) => TOutput | null | undefined
+) => TOutput | null
 
 /**
  * Partial map of per-node-type handler overrides for a printer.
  *
  * Each key is a `SchemaType` string (e.g. `'date'`, `'string'`).
- * Supply only the handlers you want to replace; the printer's built-in
+ * Supply only the handlers you want to replace. The printer's built-in
  * defaults fill in the rest.
  *
  * @example
@@ -69,10 +69,10 @@ export type PrinterPartial<TOutput, TOptions extends object> = Partial<{
 /**
  * Generic shape used by `definePrinter`.
  *
- * - `TName`        — unique string identifier (e.g. `'zod'`, `'ts'`)
- * - `TOptions`     — options passed to and stored on the printer instance
- * - `TOutput`      — the type emitted by node handlers
- * - `TPrintOutput` — type returned by public `print` (defaults to `TOutput`)
+ * - `TName` unique string identifier (e.g. `'zod'`, `'ts'`)
+ * - `TOptions` options passed to and stored on the printer instance
+ * - `TOutput` the type emitted by node handlers
+ * - `TPrintOutput` type returned by public `print` (defaults to `TOutput`)
  *
  * @example
  * ```ts
@@ -104,17 +104,17 @@ export type Printer<T extends PrinterFactoryOptions = PrinterFactoryOptions> = {
    */
   options: T['options']
   /**
-   * Node-level dispatcher — converts a `SchemaNode` directly to `TOutput` using the `nodes` handlers.
-   * Always dispatches through the `nodes` map; never calls the `print` override.
-   * Use this when you need the raw output (e.g. `ts.TypeNode`) without declaration wrapping.
+   * Node-level dispatcher, converts a `SchemaNode` directly to `TOutput` using the `nodes` handlers.
+   * Always dispatches through the `nodes` map. Never calls the `print` override.
+   * Reach for it when you need the raw output (e.g. `ts.TypeNode`) without declaration wrapping.
    */
-  transform: (node: SchemaNode) => T['output'] | null | undefined
+  transform: (node: SchemaNode) => T['output'] | null
   /**
    * Public printer. If the builder provides a root-level `print`, this calls that
    * higher-level function (which may produce full declarations).
    * Otherwise, falls back to the node-level dispatcher.
    */
-  print: (node: SchemaNode) => T['printOutput'] | null | undefined
+  print: (node: SchemaNode) => T['printOutput'] | null
 }
 
 /**
@@ -143,28 +143,32 @@ type PrinterBuilder<T extends PrinterFactoryOptions> = (options: T['options']) =
   /**
    * Optional root-level print override. When provided, becomes the public `printer.print`.
    * Use `this.transform(node)` inside this function to dispatch to the node-level handlers (`nodes`),
-   * not the override itself — so recursion is safe.
+   * not the override itself, so recursion is safe.
    */
   print?: (this: PrinterHandlerContext<T['output'], T['options']>, node: SchemaNode) => T['printOutput'] | null
 }
-
 /**
- * Creates a schema printer factory.
- *
- * This function wraps a builder and makes options optional at call sites.
+ * Defines a schema printer: a function that takes a `SchemaNode` and emits
+ * code in your target language. Each plugin that produces code from schemas
+ * (TypeScript types, Zod schemas, Faker factories) ships a printer built
+ * with this helper.
  *
  * The builder receives resolved options and returns:
- * - `name` — a unique identifier for the printer
- * - `options` — options stored on the returned printer instance
- * - `nodes` — a map of `SchemaType` → handler functions that convert a `SchemaNode` to `TOutput`
- * - `print` _(optional)_ — top-level override exposed as `printer.print`
- *   - Inside this function, use `this.transform(node)` to dispatch to the `nodes` map
- *   - This keeps recursion safe and avoids self-calls
  *
- * When no `print` override is provided, `printer.print` falls back to `printer.transform` (the node-level dispatcher).
+ * - `name` unique identifier for the printer.
+ * - `options` stored on the returned printer instance.
+ * - `nodes` map of `SchemaType` → handler. Handlers return the rendered
+ *   output (a string, a TypeScript AST node, ...) for that schema type.
+ * - `print` (optional), top-level override exposed as `printer.print`.
+ *   Use `this.transform(node)` inside it to dispatch to `nodes` recursively.
+ *
+ * Without a `print` override, `printer.print` falls back to `printer.transform`
+ * (the node-level dispatcher).
  *
- * @example Basic usage — Zod schema printer
+ * @example Tiny Zod printer
  * ```ts
+ * import { definePrinter, type PrinterFactoryOptions } from '@kubb/ast'
+ *
  * type PrinterZod = PrinterFactoryOptions<'zod', { strict?: boolean }, string>
  *
  * export const zodPrinter = definePrinter<PrinterZod>((options) => ({
@@ -173,7 +177,9 @@ type PrinterBuilder<T extends PrinterFactoryOptions> = (options: T['options']) =
  *   nodes: {
  *     string: () => 'z.string()',
  *     object(node) {
- *       const props = node.properties.map(p => `${p.name}: ${this.transform(p.schema)}`).join(', ')
+ *       const props = node.properties
+ *         .map((p) => `${p.name}: ${this.transform(p.schema)}`)
+ *         .join(', ')
  *       return `z.object({ ${props} })`
  *     },
  *   },
@@ -186,15 +192,15 @@ export function definePrinter<T extends PrinterFactoryOptions = PrinterFactoryOp
 
 /**
  * Generic printer-factory function used by `definePrinter` and `defineFunctionPrinter`.
- **
+ *
  * @example
  * ```ts
- * export const defineFunctionPrinter = createPrinterFactory<FunctionNode, FunctionNodeType, FunctionNodeByType>(
- *   (node) => kindToHandlerKey[node.kind],
+ * export const defineFunctionPrinter = createPrinterFactory<FunctionParamNode, FunctionParamKind, Partial<Record<FunctionParamKind, FunctionParamNode>>>(
+ *   (node) => node.kind,
  * )
  * ```
  */
-export function createPrinterFactory<TNode, TKey extends string, TNodeByKey extends Partial<Record<TKey, TNode>>>(getKey: (node: TNode) => TKey | undefined) {
+export function createPrinterFactory<TNode, TKey extends string, TNodeByKey extends Partial<Record<TKey, TNode>>>(getKey: (node: TNode) => TKey | null) {
   return function <T extends PrinterFactoryOptions>(
     build: (options: T['options']) => {
       name: T['name']
@@ -202,40 +208,40 @@ export function createPrinterFactory<TNode, TKey extends string, TNodeByKey exte
       nodes: Partial<{
         [K in TKey]: (
           this: {
-            transform: (node: TNode) => T['output'] | null | undefined
+            transform: (node: TNode) => T['output'] | null
             options: T['options']
           },
           node: TNodeByKey[K],
-        ) => T['output'] | null | undefined
+        ) => T['output'] | null
       }>
       print?: (
         this: {
-          transform: (node: TNode) => T['output'] | null | undefined
+          transform: (node: TNode) => T['output'] | null
           options: T['options']
         },
         node: TNode,
-      ) => T['printOutput'] | null | undefined
+      ) => T['printOutput'] | null
     },
   ): (options?: T['options']) => {
     name: T['name']
     options: T['options']
-    transform: (node: TNode) => T['output'] | null | undefined
-    print: (node: TNode) => T['printOutput'] | null | undefined
+    transform: (node: TNode) => T['output'] | null
+    print: (node: TNode) => T['printOutput'] | null
   } {
     return (options) => {
       const { name, options: resolvedOptions, nodes, print: printOverride } = build(options ?? ({} as T['options']))
 
       const context = {
         options: resolvedOptions,
-        transform: (node: TNode): T['output'] | null | undefined => {
+        transform: (node: TNode): T['output'] | null => {
           const key = getKey(node)
-          if (key === undefined) return null
+          if (key === null) return null
 
           const handler = nodes[key]
 
           if (!handler) return null
 
-          return (handler as (this: typeof context, node: TNode) => T['output'] | null | undefined).call(context, node)
+          return (handler as (this: typeof context, node: TNode) => T['output'] | null).call(context, node)
         },
       }
 
@@ -243,7 +249,7 @@ export function createPrinterFactory<TNode, TKey extends string, TNodeByKey exte
         name,
         options: resolvedOptions,
         transform: context.transform,
-        print: (printOverride ? printOverride.bind(context) : context.transform) as (node: TNode) => T['printOutput'] | null | undefined,
+        print: (printOverride ? printOverride.bind(context) : context.transform) as (node: TNode) => T['printOutput'] | null,
       }
     }
   }

package/src/registry.ts

@@ -0,0 +1,75 @@
+import type { NodeDef } from './node.ts'
+import { arrowFunctionDef, breakDef, constDef, functionDef, jsxDef, textDef, typeDef } from './nodes/code.ts'
+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 { inputDef } from './nodes/input.ts'
+import { operationDef } from './nodes/operation.ts'
+import { outputDef } from './nodes/output.ts'
+import { parameterDef } from './nodes/parameter.ts'
+import { propertyDef } from './nodes/property.ts'
+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 in `visitor.ts` derive from it.
+ */
+export const nodeDefs = [
+  inputDef,
+  outputDef,
+  operationDef,
+  requestBodyDef,
+  contentDef,
+  responseDef,
+  schemaDef,
+  propertyDef,
+  parameterDef,
+  functionParameterDef,
+  functionParametersDef,
+  typeLiteralDef,
+  indexedAccessTypeDef,
+  objectBindingPatternDef,
+  constDef,
+  typeDef,
+  functionDef,
+  arrowFunctionDef,
+  textDef,
+  breakDef,
+  jsxDef,
+  importDef,
+  exportDef,
+  sourceDef,
+  fileDef,
+] satisfies ReadonlyArray<NodeDef>

package/src/signature.ts

@@ -0,0 +1,207 @@
+import { hash } from 'node:crypto'
+import type { SchemaNode } from './nodes/index.ts'
+import { extractRefName } from './utils/index.ts'
+
+/**
+ * The flags shared by every node kind that affect its type: `primitive`, `format`, `nullable`.
+ */
+function flagsDescriptor(node: SchemaNode): string {
+  return `${node.primitive ?? ''};${node.format ?? ''};${node.nullable ? 1 : 0}`
+}
+
+function refTargetName(node: Extract<SchemaNode, { type: 'ref' }>): string {
+  if (node.ref) return extractRefName(node.ref)
+  return node.name ?? ''
+}
+
+type ScalarField = { kind: 'scalar'; key: string; prefix: string }
+type BoolField = { kind: 'bool'; key: string; prefix: string }
+type ChildField = { kind: 'child'; key: string; prefix: string }
+type ChildrenField = { kind: 'children'; key: string; prefix: string }
+type ObjectPropsField = { kind: 'objectProps' }
+type AdditionalPropsField = { kind: 'additionalProps' }
+type PatternPropsField = { kind: 'patternProps' }
+type EnumValuesField = { kind: 'enumValues' }
+type RefTargetField = { kind: 'refTarget' }
+
+type ShapeField =
+  | ScalarField
+  | BoolField
+  | ChildField
+  | ChildrenField
+  | ObjectPropsField
+  | AdditionalPropsField
+  | PatternPropsField
+  | EnumValuesField
+  | RefTargetField
+
+const arrayTupleFields: ReadonlyArray<ShapeField> = [
+  { kind: 'children', key: 'items', prefix: 'i' },
+  { kind: 'child', key: 'rest', prefix: 'r' },
+  { kind: 'scalar', key: 'min', prefix: 'mn' },
+  { kind: 'scalar', key: 'max', prefix: 'mx' },
+  { kind: 'bool', key: 'unique', prefix: 'u' },
+]
+
+const numericFields: ReadonlyArray<ShapeField> = [
+  { kind: 'scalar', key: 'min', prefix: 'mn' },
+  { kind: 'scalar', key: 'max', prefix: 'mx' },
+  { kind: 'scalar', key: 'exclusiveMinimum', prefix: 'emn' },
+  { kind: 'scalar', key: 'exclusiveMaximum', prefix: 'emx' },
+  { kind: 'scalar', key: 'multipleOf', prefix: 'mo' },
+]
+
+const rangeFields: ReadonlyArray<ShapeField> = [
+  { kind: 'scalar', key: 'min', prefix: 'mn' },
+  { kind: 'scalar', key: 'max', prefix: 'mx' },
+]
+
+/**
+ * Maps each node `type` to its ordered shape-contributing fields. Types absent from the map
+ * (boolean, null, any, and other scalars) fall back to `${type}|${flags}`.
+ */
+const SHAPE_KEYS: Partial<Record<SchemaNode['type'], ReadonlyArray<ShapeField>>> = {
+  object: [
+    { kind: 'objectProps' },
+    { kind: 'additionalProps' },
+    { kind: 'patternProps' },
+    { kind: 'scalar', key: 'minProperties', prefix: 'mn' },
+    { kind: 'scalar', key: 'maxProperties', prefix: 'mx' },
+  ],
+  array: arrayTupleFields,
+  tuple: arrayTupleFields,
+  union: [
+    { kind: 'scalar', key: 'strategy', prefix: 's' },
+    { kind: 'scalar', key: 'discriminatorPropertyName', prefix: 'd' },
+    { kind: 'children', key: 'members', prefix: 'm' },
+  ],
+  intersection: [{ kind: 'children', key: 'members', prefix: 'm' }],
+  enum: [{ kind: 'enumValues' }],
+  ref: [{ kind: 'refTarget' }],
+  string: [
+    { kind: 'scalar', key: 'min', prefix: 'mn' },
+    { kind: 'scalar', key: 'max', prefix: 'mx' },
+    { kind: 'scalar', key: 'pattern', prefix: 'pt' },
+  ],
+  number: numericFields,
+  integer: numericFields,
+  bigint: numericFields,
+  url: [
+    { kind: 'scalar', key: 'path', prefix: 'path' },
+    { kind: 'scalar', key: 'min', prefix: 'mn' },
+    { kind: 'scalar', key: 'max', prefix: 'mx' },
+  ],
+  uuid: rangeFields,
+  email: rangeFields,
+  datetime: [
+    { kind: 'bool', key: 'offset', prefix: 'o' },
+    { kind: 'bool', key: 'local', prefix: 'l' },
+  ],
+  date: [{ kind: 'scalar', key: 'representation', prefix: 'rep' }],
+  time: [{ kind: 'scalar', key: 'representation', prefix: 'rep' }],
+}
+
+function serializeShapeField(field: ShapeField, node: SchemaNode, record: Record<string, unknown>): string {
+  switch (field.kind) {
+    case 'scalar':
+      return `${field.prefix}:${record[field.key] ?? ''}`
+    case 'bool':
+      return `${field.prefix}:${record[field.key] ? 1 : 0}`
+    case 'child': {
+      const child = record[field.key] as SchemaNode | undefined
+      return `${field.prefix}:${child ? signatureOf(child) : ''}`
+    }
+    case 'children': {
+      const children = (record[field.key] as Array<SchemaNode> | undefined) ?? []
+      return `${field.prefix}[${children.map((c) => signatureOf(c)).join(',')}]`
+    }
+    case 'objectProps': {
+      const obj = node as Extract<SchemaNode, { type: 'object' }>
+      const props = (obj.properties ?? []).map((prop) => `${prop.name}${prop.required ? '!' : '?'}${signatureOf(prop.schema)}`).join(',')
+      return `p[${props}]`
+    }
+    case 'additionalProps': {
+      const obj = node as Extract<SchemaNode, { type: 'object' }>
+      if (typeof obj.additionalProperties === 'boolean') return `ab:${obj.additionalProperties}`
+      if (obj.additionalProperties) return `as:${signatureOf(obj.additionalProperties)}`
+      return ''
+    }
+    case 'patternProps': {
+      const obj = node as Extract<SchemaNode, { type: 'object' }>
+      const pattern = obj.patternProperties
+        ? Object.keys(obj.patternProperties)
+            .sort()
+            .map((key) => `${key}=${signatureOf(obj.patternProperties![key]!)}`)
+            .join(',')
+        : ''
+      return `pp[${pattern}]`
+    }
+    case 'enumValues': {
+      const en = node as Extract<SchemaNode, { type: 'enum' }>
+      let values = ''
+      if (en.namedEnumValues?.length) {
+        values = en.namedEnumValues.map((entry) => `${entry.name}=${entry.primitive}:${String(entry.value)}`).join(',')
+      } else if (en.enumValues?.length) {
+        values = en.enumValues.map((value) => `${value === null ? 'null' : typeof value}:${String(value)}`).join(',')
+      }
+      return `v[${values}]`
+    }
+    case 'refTarget': {
+      return `->${refTargetName(node as Extract<SchemaNode, { type: 'ref' }>)}`
+    }
+  }
+}
+
+/**
+ * Builds the local shape descriptor that {@link signatureOf} hashes: the node's kind, flags,
+ * constraints, and its children's signatures.
+ */
+function describeShape(node: SchemaNode): string {
+  const flags = flagsDescriptor(node)
+  const fields = SHAPE_KEYS[node.type]
+  if (!fields) return `${node.type}|${flags}`
+
+  const record = node as unknown as Record<string, unknown>
+  const parts: Array<string> = [`${node.type}|${flags}`]
+  for (const field of fields) {
+    parts.push(serializeShapeField(field, node, record))
+  }
+  return parts.join('|')
+}
+
+/**
+ * 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>()
+
+/**
+ * Computes a deterministic, shape-only signature (a content hash) for a schema node. Two schemas
+ * share a signature when they are structurally identical, ignoring documentation (`name`, `title`,
+ * `description`, `example`, `default`, `deprecated`) and usage-slot flags (`optional`, `nullish`,
+ * `readOnly`, `writeOnly`). `nullable` is kept because it changes the produced type, and `ref`
+ * nodes compare by target name, which also terminates on circular shapes.
+ *
+ * @example Two enums with different descriptions share a signature
+ * ```ts
+ * signatureOf(createSchema({ type: 'enum', primitive: 'string', enumValues: ['a', 'b'], description: 'x' })) ===
+ *   signatureOf(createSchema({ type: 'enum', primitive: 'string', enumValues: ['a', 'b'] }))
+ * ```
+ */
+export function signatureOf(node: SchemaNode): string {
+  const cached = signatureCache.get(node)
+  if (cached !== undefined) return cached
+  const signature = hash('sha256', describeShape(node), 'hex')
+  signatureCache.set(node, signature)
+
+  return signature
+}
+
+/**
+ * Returns `true` when two schema nodes are structurally identical under shape-only equality,
+ * meaning they produce the same TypeScript type.
+ */
+export function isSchemaEqual(a: SchemaNode, b: SchemaNode): boolean {
+  return signatureOf(a) === signatureOf(b)
+}