@kubb/ast 5.0.0-beta.4 → 5.0.0-beta.40

package/dist/types.d.ts

@@ -0,0 +1,2 @@
+import { $t as ScalarSchemaType, At as FunctionParameterNode, Bt as DateSchemaNode, C as PrinterFactoryOptions, Ct as HttpStatusCode, D as DistributiveOmit, Dt as ParameterNode, Et as ParameterLocation, Ft as FileNode, Gt as IntersectionSchemaNode, Ht as EnumSchemaNode, It as ImportNode, Jt as NumberSchemaNode, Kt as Ipv4SchemaNode, Lt as SourceNode, Mt as ParameterGroupNode, Nt as ParamsTypeNode, O as UserFileNode, Ot as FunctionNodeType, Pt as ExportNode, Qt as ScalarSchemaNode, Rt as ArraySchemaNode, S as Printer, Sn as VisitorDepth, St as ResponseNode, Tt as StatusCode, Ut as EnumValueNode, Vt as DatetimeSchemaNode, Wt as FormatStringSchemaNode, Xt as PrimitiveSchemaType, Yt as ObjectSchemaNode, Zt as RefSchemaNode, _ as VisitorContext, _n as TypeDeclarationNode, _t as HttpMethod, an as TimeSchemaNode, bn as NodeKind, bt as OperationNodeBase, cn as PropertyNode, ct as DedupePlan, d as AsyncVisitor, dn as CodeNode, dt as Node, en as SchemaNode, et as InferSchemaNode, f as CollectOptions, fn as ConstNode, ft as InputMeta, g as Visitor, gn as TextNode, gt as GenericOperationNode, h as TransformOptions, hn as JsxNode, ht as OutputNode, in as StringSchemaNode, it as SchemaDialect, jt as FunctionParametersNode, kt as FunctionParamNode, ln as ArrowFunctionNode, m as ParentOf, mn as JSDocNode, mt as InputStreamNode, nn as SchemaType, nt as DispatchRule, on as UnionSchemaNode, ot as BuildDedupePlanOptions, p as CollectVisitor, pn as FunctionNode, pt as InputNode, qt as Ipv6SchemaNode, rn as SpecialSchemaType, sn as UrlSchemaNode, st as DedupeCanonical, t as OperationParamsResolver, tn as SchemaNodeByType, tt as ParserOptions, un as BreakNode, v as WalkOptions, vn as TypeNode, vt as HttpOperationNode, w as PrinterPartial, wt as MediaType, xn as ScalarPrimitive, xt as OperationProtocol, yn as BaseNode, yt as OperationNode, zt as ComplexSchemaType } from "./types-CEIHPTfs.js";
+export type { ArraySchemaNode, ArrowFunctionNode, AsyncVisitor, BaseNode, BreakNode, BuildDedupePlanOptions, CodeNode, CollectOptions, CollectVisitor, ComplexSchemaType, ConstNode, DateSchemaNode, DatetimeSchemaNode, DedupeCanonical, DedupePlan, DispatchRule, DistributiveOmit, EnumSchemaNode, EnumValueNode, ExportNode, FileNode, FormatStringSchemaNode, FunctionNode, FunctionNodeType, FunctionParamNode, FunctionParameterNode, FunctionParametersNode, GenericOperationNode, HttpMethod, HttpOperationNode, HttpStatusCode, ImportNode, InferSchemaNode, InputMeta, InputNode, InputStreamNode, IntersectionSchemaNode, Ipv4SchemaNode, Ipv6SchemaNode, JSDocNode, JsxNode, MediaType, Node, NodeKind, NumberSchemaNode, ObjectSchemaNode, OperationNode, OperationNodeBase, OperationParamsResolver, OperationProtocol, OutputNode, ParameterGroupNode, ParameterLocation, ParameterNode, ParamsTypeNode, ParentOf, ParserOptions, PrimitiveSchemaType, Printer, PrinterFactoryOptions, PrinterPartial, PropertyNode, RefSchemaNode, ResponseNode, ScalarPrimitive, ScalarSchemaNode, ScalarSchemaType, SchemaDialect, SchemaNode, SchemaNodeByType, SchemaType, SourceNode, SpecialSchemaType, StatusCode, StringSchemaNode, TextNode, TimeSchemaNode, TransformOptions, TypeDeclarationNode, TypeNode, UnionSchemaNode, UrlSchemaNode, UserFileNode, Visitor, VisitorContext, VisitorDepth, WalkOptions };

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@kubb/ast",
-  "version": "5.0.0-beta.4",
-  "description": "Spec-agnostic AST layer for Kubb. Defines nodes, visitor pattern, and factory functions used across codegen plugins.",
+  "version": "5.0.0-beta.40",
+  "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",
     "codegen",
     "kubb",
-    "openapi",
     "typescript"
   ],
   "license": "MIT",
@@ -33,6 +32,10 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./types": {
+      "import": "./dist/types.js",
+      "require": "./dist/types.cjs"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -40,7 +43,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "devDependencies": {
-    "@types/node": "^25.6.0",
+    "@types/node": "^22.19.19",
     "@internals/utils": "0.0.0"
   },
   "engines": {
@@ -53,6 +56,7 @@
     "lint:fix": "oxlint --fix .",
     "release": "pnpm publish --no-git-check",
     "release:canary": "bash ../../.github/canary.sh && node ../../scripts/build.js canary && pnpm publish --no-git-check",
+    "release:stage": "pnpm stage publish --no-git-check",
     "start": "tsdown --watch",
     "test": "vitest --passWithNoTests",
     "typecheck": "tsc -p ./tsconfig.json --noEmit --emitDeclarationOnly false"

package/src/constants.ts

@@ -1,13 +1,11 @@
-import type { NodeKind } from './nodes/base.ts'
-import type { MediaType } from './nodes/http.ts'
 import type { HttpMethod } from './nodes/operation.ts'
 import type { SchemaType } from './nodes/schema.ts'
 
 /**
  * Traversal depth for AST visitor utilities.
  *
- * - `'shallow'` — visits only the immediate node, skipping children.
- * - `'deep'` — recursively visits all descendant nodes.
+ * - `'shallow'` visits only the immediate node, skipping children.
+ * - `'deep'` recursively visits all descendant nodes.
  */
 export type VisitorDepth = 'shallow' | 'deep'
 
@@ -16,26 +14,6 @@ export const visitorDepths = {
   deep: 'deep',
 } as const satisfies Record<VisitorDepth, VisitorDepth>
 
-export const nodeKinds = {
-  input: 'Input',
-  output: 'Output',
-  operation: 'Operation',
-  schema: 'Schema',
-  property: 'Property',
-  parameter: 'Parameter',
-  response: 'Response',
-  functionParameter: 'FunctionParameter',
-  parameterGroup: 'ParameterGroup',
-  functionParameters: 'FunctionParameters',
-  type: 'Type',
-  file: 'File',
-  import: 'Import',
-  export: 'Export',
-  source: 'Source',
-  text: 'Text',
-  break: 'Break',
-} as const satisfies Record<string, NodeKind>
-
 /**
  * Schema type discriminators used by all AST schema nodes.
  *
@@ -198,31 +176,3 @@ export const httpMethods = {
  * ```
  */
 export const WALK_CONCURRENCY = 30
-
-/**
- * Common MIME types used in request/response content negotiation.
- *
- * Covers JSON, XML, form data, PDFs, images, audio, and video formats.
- * Use these as keys when serializing request/response bodies.
- */
-export const mediaTypes = {
-  applicationJson: 'application/json',
-  applicationXml: 'application/xml',
-  applicationFormUrlEncoded: 'application/x-www-form-urlencoded',
-  applicationOctetStream: 'application/octet-stream',
-  applicationPdf: 'application/pdf',
-  applicationZip: 'application/zip',
-  applicationGraphql: 'application/graphql',
-  multipartFormData: 'multipart/form-data',
-  textPlain: 'text/plain',
-  textHtml: 'text/html',
-  textCsv: 'text/csv',
-  textXml: 'text/xml',
-  imagePng: 'image/png',
-  imageJpeg: 'image/jpeg',
-  imageGif: 'image/gif',
-  imageWebp: 'image/webp',
-  imageSvgXml: 'image/svg+xml',
-  audioMpeg: 'audio/mpeg',
-  videoMp4: 'video/mp4',
-} as const satisfies Record<string, MediaType>

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/dialect.ts

@@ -0,0 +1,58 @@
+/**
+ * The spec-specific decisions a schema parser makes when converting a source document's schemas
+ * into Kubb AST nodes. Everything else in an adapter's schema pipeline is generic JSON Schema,
+ * shared across specs, so the dialect is the one seam where specs differ, like a database driver
+ * targeting Postgres vs MySQL. Pair it with {@link dispatch}: the rule table picks which converter
+ * runs, the dialect answers the spec-specific questions inside it.
+ *
+ * The guards (`isReference`, `isDiscriminator`) are type predicates, so converters narrow the
+ * schema after a check and the type parameters carry the narrowed types through.
+ *
+ * This is the seam for the JSON Schema family: OpenAPI, AsyncAPI, and plain JSON Schema share
+ * `$ref`, `allOf`/`oneOf`, `enum`, and `format` and differ only in these few decisions. A spec on
+ * a different type system (GraphQL, with non-null wrappers and named-type references instead of
+ * `$ref`) skips `SchemaDialect` and reuses the universal layer directly: the `Adapter` port, the
+ * AST factories, and {@link dispatch} with its own rule table.
+ *
+ * @typeParam TSchema - The adapter's schema object type (e.g. an OpenAPI `SchemaObject`).
+ * @typeParam TRef - The narrowed `$ref` pointer type `isReference` proves.
+ * @typeParam TDiscriminated - The narrowed discriminated-schema type `isDiscriminator` proves.
+ * @typeParam TDocument - The source document `resolveRef` resolves against.
+ */
+export type SchemaDialect<TSchema = unknown, TRef = TSchema, TDiscriminated = TSchema, TDocument = unknown> = {
+  /** Identifies the dialect in logs and while debugging dispatch. */
+  name: string
+  /** Whether a schema should be treated as nullable. */
+  isNullable: (schema?: TSchema) => boolean
+  /** Whether a value is a `$ref` pointer object. */
+  isReference: (value?: unknown) => value is TRef
+  /** Whether a schema carries a structured discriminator (polymorphism). */
+  isDiscriminator: (value?: unknown) => value is TDiscriminated
+  /** Whether a schema represents binary data (converted to a `blob` node). */
+  isBinary: (schema: TSchema) => boolean
+  /** Resolves a local `$ref` pointer against the document, or nullish when it cannot. */
+  resolveRef: <TResolved>(document: TDocument, ref: string) => TResolved | null | undefined
+}
+
+/**
+ * Identity helper that types a {@link SchemaDialect} for an adapter. Like
+ * `defineParser`, it adds no runtime behavior, it pins the dialect's type for
+ * inference and gives adapter authors a discoverable anchor.
+ *
+ * @example
+ * ```ts
+ * export const oasDialect = defineSchemaDialect({
+ *   name: 'oas',
+ *   isNullable,
+ *   isReference,
+ *   isDiscriminator,
+ *   isBinary: (schema) => schema.type === 'string' && schema.contentMediaType === 'application/octet-stream',
+ *   resolveRef,
+ * })
+ * ```
+ */
+export function defineSchemaDialect<TSchema, TRef, TDiscriminated, TDocument>(
+  dialect: SchemaDialect<TSchema, TRef, TDiscriminated, TDocument>,
+): SchemaDialect<TSchema, TRef, TDiscriminated, TDocument> {
+  return dialect
+}

package/src/dispatch.ts

@@ -0,0 +1,53 @@
+/**
+ * One entry in an ordered dispatch table: a predicate paired with a converter.
+ *
+ * @typeParam TContext - Per-input context handed to every rule. A spec adapter typically
+ *   pre-computes this once per node (the source spec node plus derived fields like a
+ *   normalized type or resolved options) so individual rules stay cheap predicates.
+ * @typeParam TNode - The node a rule produces, e.g. a Kubb AST `SchemaNode`.
+ */
+export type DispatchRule<TContext, TNode> = {
+  /** Identifies the rule when reading the table or debugging which branch ran. */
+  name: string
+  /** Returns `true` when this rule is responsible for the given context. */
+  match: (context: TContext) => boolean
+  /**
+   * Produces a node for the context, or `null` to fall through to the next rule.
+   *
+   * Returning `null` lets a broad `match` defer: e.g. "has a `format`" matches many schemas,
+   * but only some formats are convertible, the rest fall through to plain `type` handling.
+   */
+  convert: (context: TContext) => TNode | null
+}
+
+/**
+ * Walks an ordered list of {@link DispatchRule}s and returns the first node produced.
+ *
+ * This is the shared backbone for spec adapters (OpenAPI today, AsyncAPI and others later).
+ * The contract an adapter follows is intentionally minimal:
+ *
+ *     context → [rule.match → rule.convert] → node
+ *
+ * An adapter derives a context from a source spec node, then declares an ordered table of
+ * rules mapping spec shapes onto Kubb AST nodes. To add support for a new spec, write a new
+ * context type and a new rules table, the traversal here is reused unchanged.
+ *
+ * Order is significant: earlier rules win, so list higher-precedence or more specific shapes
+ * first (e.g. composition keywords before plain `type`). A rule whose `match` returns `true`
+ * may still `convert` to `null` to defer to later rules. When no rule produces a node this
+ * returns `null`, leaving the caller to apply its own fallback.
+ *
+ * @example
+ * ```ts
+ * const node = dispatch(schemaRules, schemaContext) ?? createSchema({ type: fallbackType })
+ * ```
+ */
+export function dispatch<TContext, TNode>(rules: ReadonlyArray<DispatchRule<TContext, TNode>>, context: TContext): TNode | null {
+  for (const rule of rules) {
+    if (!rule.match(context)) continue
+    const node = rule.convert(context)
+    if (node !== null && node !== undefined) return node
+  }
+
+  return null
+}