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

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@kubb/ast",
-  "version": "5.0.0-beta.6",
-  "description": "Spec-agnostic AST layer for Kubb. Defines nodes, visitor pattern, and factory functions used across codegen plugins.",
+  "version": "5.0.0-beta.60",
+  "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",
@@ -24,7 +23,6 @@
     "!/**/__snapshots__/**"
   ],
   "type": "module",
-  "sideEffects": false,
   "main": "./dist/index.cjs",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -33,6 +31,18 @@
       "import": "./dist/index.js",
       "require": "./dist/index.cjs"
     },
+    "./factory": {
+      "import": "./dist/factory.js",
+      "require": "./dist/factory.cjs"
+    },
+    "./types": {
+      "import": "./dist/types.js",
+      "require": "./dist/types.cjs"
+    },
+    "./utils": {
+      "import": "./dist/utils.js",
+      "require": "./dist/utils.cjs"
+    },
     "./package.json": "./package.json"
   },
   "publishConfig": {
@@ -40,7 +50,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "devDependencies": {
-    "@types/node": "^22.19.17",
+    "@types/node": "^22.19.21",
     "@internals/utils": "0.0.0"
   },
   "engines": {
@@ -48,11 +58,12 @@
   },
   "scripts": {
     "build": "tsdown",
-    "clean": "npx rimraf ./dist",
+    "clean": "node -e \"require('node:fs').rmSync('./dist', {recursive:true,force:true})\"",
     "lint": "oxlint .",
     "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,32 +14,11 @@ 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.
  *
- * These values serve as stable discriminators across the AST (e.g., `schema.type === schemaTypes.object`).
- * Grouped by category: primitives (`string`, `number`, `boolean`), structural types (`object`, `array`, `union`),
- * and format-specific types (`date`, `uuid`, `email`). Use `isScalarPrimitive()` to check for scalar types.
+ * Each value is a stable discriminator across the AST (for example `schema.type === schemaTypes.object`).
+ * Call `isScalarPrimitive()` to check for the scalar types.
  */
 export const schemaTypes = {
   /**
@@ -61,7 +38,7 @@ export const schemaTypes = {
    */
   bigint: 'bigint',
   /**
-   * Boolean value
+   * Boolean value.
    */
   boolean: 'boolean',
   /**
@@ -154,15 +131,12 @@ export type ScalarPrimitive = 'string' | 'number' | 'integer' | 'bigint' | 'bool
 
 /**
  * Scalar primitive schema types used for union simplification and type narrowing.
- *
- * Use `isScalarPrimitive()` to safely check whether a type is a scalar primitive.
  */
-export const SCALAR_PRIMITIVE_TYPES = new Set<ScalarPrimitive>(['string', 'number', 'integer', 'bigint', 'boolean'])
+const SCALAR_PRIMITIVE_TYPES = new Set<ScalarPrimitive>(['string', 'number', 'integer', 'bigint', 'boolean'])
 
 /**
- * Type guard that returns `true` when `type` is a scalar primitive schema type.
- *
- * Use this to check if a schema type can be directly assigned without wrapping (e.g., `string | number | boolean`).
+ * Returns `true` when `type` is a scalar primitive that can be assigned without wrapping
+ * (for example `string | number | boolean`).
  */
 export function isScalarPrimitive(type: string): type is ScalarPrimitive {
   return SCALAR_PRIMITIVE_TYPES.has(type as ScalarPrimitive)
@@ -170,8 +144,6 @@ export function isScalarPrimitive(type: string): type is ScalarPrimitive {
 
 /**
  * HTTP method identifiers used by operation nodes.
- *
- * Includes all standard HTTP methods (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS, TRACE).
  */
 export const httpMethods = {
   get: 'GET',
@@ -185,10 +157,10 @@ export const httpMethods = {
 } as const satisfies Record<Lowercase<HttpMethod>, HttpMethod>
 
 /**
- * Default concurrency limit for `walk()` traversal utility.
+ * Default concurrency limit for the `walk()` traversal utility.
  *
- * Set to 30 to balance I/O-bound resolver parallelism against event loop pressure and memory usage during large spec traversals.
- * Use `WALK_CONCURRENCY` when calling `walk()` or override for different hardware constraints.
+ * Set to 30 to balance I/O-bound resolver parallelism against event-loop and memory pressure
+ * during large spec traversals. Override it for different hardware constraints.
  *
  * @example
  * ```ts
@@ -200,29 +172,12 @@ 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.
+ * Number of spaces in one indentation level when assembling multi-line code as strings.
+ * Set to 2, 3, … to change the indent width used by `buildObject`/`buildList`.
+ */
+const INDENT_SIZE = 2
+
+/**
+ * One indentation level, derived from {@link INDENT_SIZE}.
  */
-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>
+export const INDENT = Array.from({ length: INDENT_SIZE }, () => ' ').join('')

package/src/dedupe.ts

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

package/src/dialect.ts

@@ -0,0 +1,53 @@
+/**
+ * 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
+  /**
+   * Whether the value is a `$ref` pointer.
+   */
+  isReference: (value?: unknown) => value is TRef
+  /**
+   * Whether the schema carries a discriminator for polymorphism.
+   */
+  isDiscriminator: (value?: unknown) => value is TDiscriminated
+  /**
+   * Whether the schema is binary data, converted to a `blob` node.
+   */
+  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
+}
+
+/**
+ * Types a {@link SchemaDialect} for an adapter. Adds no runtime behavior and only pins the
+ * dialect's type for inference.
+ *
+ * @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
+}