@kubb/ast 5.0.0-beta.30 → 5.0.0-beta.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/ast",
-  "version": "5.0.0-beta.30",
+  "version": "5.0.0-beta.32",
   "description": "Spec-agnostic AST layer for Kubb. Defines the node tree, visitor pattern, factory functions, and type guards used across all code generation plugins.",
   "keywords": [
     "ast",

package/src/dedupe.ts

@@ -0,0 +1,200 @@
+import { createSchema } from './factory.ts'
+import type { Node, OperationNode, SchemaNode } from './nodes/index.ts'
+import { signatureOf } from './signature.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>
+  /**
+   * 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>
+}
+
+/**
+ * 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.
+ *
+ * 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.canonicalBySignature)
+ * ```
+ */
+export function applyDedupe(node: SchemaNode, canonicalBySignature: ReadonlyMap<string, DedupeCanonical>, skipRootMatch?: boolean): SchemaNode
+export function applyDedupe(node: OperationNode, canonicalBySignature: ReadonlyMap<string, DedupeCanonical>, skipRootMatch?: boolean): OperationNode
+export function applyDedupe(node: Node, canonicalBySignature: ReadonlyMap<string, DedupeCanonical>, skipRootMatch = false): Node {
+  if (canonicalBySignature.size === 0) return node
+
+  const root = node
+
+  return transform(node, {
+    schema(schemaNode) {
+      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, that name becomes the canonical (so other top-level duplicates
+ * and inline copies turn into references to it); 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
+    topLevelName?: string
+  }
+  const groups = new Map<string, Group>()
+
+  function record(schemaNode: SchemaNode): void {
+    const signature = signatureOf(schemaNode)
+    if (!isCandidate(schemaNode)) return
+
+    const isTopLevel = topLevelNodes.has(schemaNode) && !!schemaNode.name
+    const group = groups.get(signature)
+    if (group) {
+      group.count++
+      if (isTopLevel && !group.topLevelName) group.topLevelName = schemaNode.name!
+    } else {
+      groups.set(signature, { count: 1, representative: schemaNode, topLevelName: isTopLevel ? schemaNode.name! : undefined })
+    }
+  }
+
+  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 pendingHoists: Array<{ name: string; representative: SchemaNode }> = []
+
+  for (const [signature, group] of groups) {
+    if (group.count < minOccurrences) continue
+
+    if (group.topLevelName) {
+      canonicalBySignature.set(signature, { name: group.topLevelName, ref: refFor(group.topLevelName) })
+      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, true), name))
+
+  return { canonicalBySignature, hoisted }
+}

package/src/guards.ts

@@ -1,19 +1,4 @@
-import type {
-  FunctionParameterNode,
-  FunctionParametersNode,
-  HttpOperationNode,
-  InputNode,
-  Node,
-  NodeKind,
-  OperationNode,
-  OutputNode,
-  ParameterGroupNode,
-  ParameterNode,
-  PropertyNode,
-  ResponseNode,
-  SchemaNode,
-  SchemaNodeByType,
-} from './nodes/index.ts'
+import type { HttpOperationNode, InputNode, Node, NodeKind, OperationNode, OutputNode, SchemaNode, SchemaNodeByType } from './nodes/index.ts'
 
 /**
  * Narrows a `SchemaNode` to the variant that matches `type`.
@@ -93,33 +78,3 @@ export function isHttpOperationNode(node: OperationNode): node is HttpOperationN
  * ```
  */
 export const isSchemaNode = isKind<SchemaNode>('Schema')
-
-/**
- * Returns `true` when the input is a `PropertyNode`.
- */
-export const isPropertyNode = isKind<PropertyNode>('Property')
-
-/**
- * Returns `true` when the input is a `ParameterNode`.
- */
-export const isParameterNode = isKind<ParameterNode>('Parameter')
-
-/**
- * Returns `true` when the input is a `ResponseNode`.
- */
-export const isResponseNode = isKind<ResponseNode>('Response')
-
-/**
- * Returns `true` when the input is a `FunctionParameterNode`.
- */
-export const isFunctionParameterNode = isKind<FunctionParameterNode>('FunctionParameter')
-
-/**
- * Returns `true` when the input is a `ParameterGroupNode`.
- */
-export const isParameterGroupNode = isKind<ParameterGroupNode>('ParameterGroup')
-
-/**
- * Returns `true` when the input is a `FunctionParametersNode`.
- */
-export const isFunctionParametersNode = isKind<FunctionParametersNode>('FunctionParameters')

package/src/index.ts

@@ -1,4 +1,5 @@
 export { httpMethods, isScalarPrimitive, mediaTypes, nodeKinds, schemaTypes } from './constants.ts'
+export { applyDedupe, buildDedupePlan } from './dedupe.ts'
 export { defineSchemaDialect } from './dialect.ts'
 export { dispatch } from './dispatch.ts'
 export {
@@ -34,6 +35,7 @@ export { isHttpOperationNode, isInputNode, isOperationNode, isOutputNode, isSche
 export { createPrinterFactory, definePrinter } from './printer.ts'
 export { extractRefName } from './refs.ts'
 export { childName, collectImports, enumPropName, findDiscriminator } from './resolvers.ts'
+export { isSchemaEqual, schemaSignature } from './signature.ts'
 export { mergeAdjacentObjects, mergeAdjacentObjectsLazy, setDiscriminatorEnum, setEnumName, simplifyUnion } from './transformers.ts'
 export type * from './types.ts'
 export {

package/src/refs.ts

@@ -1,4 +1,3 @@
-import type { InputNode } from './nodes/root.ts'
 import type { SchemaNode } from './nodes/schema.ts'
 
 /**
@@ -19,51 +18,3 @@ export type RefMap = Map<string, SchemaNode>
 export function extractRefName(ref: string): string {
   return ref.split('/').at(-1) ?? ref
 }
-
-/**
- * Builds a `RefMap` from `input.schemas` using each schema's `name`.
- *
- * Unnamed schemas are skipped.
- *
- * @example
- * ```ts
- * const refMap = buildRefMap(input)
- * const pet = refMap.get('Pet')
- * ```
- */
-export function buildRefMap(input: InputNode): RefMap {
-  const map: RefMap = new Map()
-
-  for (const schema of input.schemas) {
-    if (schema.name) {
-      map.set(schema.name, schema)
-    }
-  }
-  return map
-}
-
-/**
- * Resolves a schema by name from a `RefMap`.
- *
- * Returns `null` when the ref is not found.
- *
- * @example
- * ```ts
- * const petSchema = resolveRef(refMap, 'Pet')
- * ```
- */
-export function resolveRef(refMap: RefMap, ref: string): SchemaNode | null {
-  return refMap.get(ref) ?? null
-}
-
-/**
- * Converts a `RefMap` into a plain object.
- *
- * @example
- * ```ts
- * const refsObject = refMapToObject(refMap)
- * ```
- */
-export function refMapToObject(refMap: RefMap): Record<string, SchemaNode> {
-  return Object.fromEntries(refMap)
-}

package/src/signature.ts

@@ -0,0 +1,232 @@
+import { createHash } from 'node:crypto'
+import type { SchemaNode } from './nodes/index.ts'
+import { extractRefName } from './refs.ts'
+
+/**
+ * The shape-affecting flags shared by every node kind: base primitive, format, and `nullable`.
+ * Documentation and usage-slot flags (`optional`/`nullish`/`readOnly`/`writeOnly`) are
+ * intentionally excluded — they describe the property slot, not the type.
+ */
+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 schema node `type` to the ordered list of shape-contributing fields.
+ * Node types absent from this map (scalar types like boolean, null, any, etc.) fall
+ * back to `${type}|${flags}` with no additional fields.
+ */
+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-only descriptor for a node: its kind, flags, constraints, and its
+ * children's signatures. {@link signatureOf} hashes this string; children contribute their
+ * fixed-length signature rather than their own full descriptor, which keeps the result bounded.
+ */
+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('|')
+}
+
+/**
+ * Persistent hash-consing cache: `SchemaNode` → signature digest, keyed by node identity.
+ *
+ * A `WeakMap` so entries are released once the node is garbage-collected, and so a node hashed
+ * during dedupe planning is not re-hashed when the same tree is rewritten during streaming
+ * (where `schemaSignature` and `applyDedupe` would otherwise each walk it from scratch). Reuse
+ * across calls is sound because a signature depends only on a node's content, and schema nodes
+ * are immutable once created — transforms allocate new objects rather than mutating in place.
+ */
+const signatureCache = new WeakMap<SchemaNode, string>()
+
+/**
+ * Hash-consing: each node's signature is a fixed-length digest of its local shape plus its
+ * children's digests (a Merkle hash). Children contribute their 64-char hash instead of their
+ * full nested descriptor, so a signature stays bounded regardless of subtree depth, and the
+ * digest is identical across calls because it depends only on content — never on traversal
+ * order. This keeps the keys built during planning consistent with the ones recomputed later
+ * during streaming. {@link signatureCache} memoizes node → digest across every computation.
+ */
+export function signatureOf(node: SchemaNode): string {
+  const cached = signatureCache.get(node)
+  if (cached !== undefined) return cached
+  const signature = createHash('sha256').update(describeShape(node)).digest('hex')
+  signatureCache.set(node, signature)
+  return signature
+}
+
+/**
+ * Computes a deterministic, shape-only signature (a fixed-length 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. `ref` nodes compare by target name,
+ * which also keeps the algorithm terminating on circular shapes.
+ *
+ * @example Two enums with different descriptions share a signature
+ * ```ts
+ * schemaSignature(createSchema({ type: 'enum', primitive: 'string', enumValues: ['a', 'b'], description: 'x' })) ===
+ *   schemaSignature(createSchema({ type: 'enum', primitive: 'string', enumValues: ['a', 'b'] }))
+ * ```
+ */
+export function schemaSignature(node: SchemaNode): string {
+  return signatureOf(node)
+}
+
+/**
+ * Returns `true` when two schema nodes are structurally identical under shape-only equality.
+ *
+ * @example
+ * ```ts
+ * isSchemaEqual(a, b) // a and b produce the same TypeScript type
+ * ```
+ */
+export function isSchemaEqual(a: SchemaNode, b: SchemaNode): boolean {
+  return schemaSignature(a) === schemaSignature(b)
+}

package/src/types.ts

@@ -1,4 +1,5 @@
 export type { VisitorDepth } from './constants.ts'
+export type { BuildDedupePlanOptions, DedupeCanonical, DedupePlan } from './dedupe.ts'
 export type { SchemaDialect } from './dialect.ts'
 export type { DispatchRule } from './dispatch.ts'
 export type { DistributiveOmit } from './factory.ts'