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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubb/ast",
-  "version": "5.0.0-alpha.30",
+  "version": "5.0.0-alpha.32",
   "description": "Spec-agnostic AST layer for Kubb. Defines nodes, visitor pattern, and factory functions used across codegen plugins.",
   "keywords": [
     "kubb",
@@ -45,7 +45,7 @@
     "!/**/__snapshots__/**"
   ],
   "devDependencies": {
-    "@types/node": "^22.19.16",
+    "@types/node": "^22.19.17",
     "@internals/utils": "0.0.0"
   },
   "main": "./dist/index.cjs",

package/src/constants.ts

@@ -15,7 +15,8 @@ export const visitorDepths = {
 } as const satisfies Record<VisitorDepth, VisitorDepth>
 
 export const nodeKinds = {
-  root: 'Root',
+  input: 'Input',
+  output: 'Output',
   operation: 'Operation',
   schema: 'Schema',
   property: 'Property',
@@ -24,6 +25,11 @@ export const nodeKinds = {
   functionParameter: 'FunctionParameter',
   parameterGroup: 'ParameterGroup',
   functionParameters: 'FunctionParameters',
+  type: 'Type',
+  file: 'File',
+  import: 'Import',
+  export: 'Export',
+  source: 'Source',
 } as const satisfies Record<string, NodeKind>
 
 /**

package/src/factory.ts

@@ -1,18 +1,31 @@
+import { createHash } from 'node:crypto'
+import path from 'node:path'
+import { trimExtName } from '@internals/utils'
 import type { InferSchemaNode } from './infer.ts'
 import type {
+  ArrowFunctionNode,
+  ConstNode,
+  ExportNode,
+  FileNode,
+  FunctionNode,
   FunctionParameterNode,
   FunctionParametersNode,
+  ImportNode,
+  InputNode,
   ObjectSchemaNode,
   OperationNode,
+  OutputNode,
   ParameterGroupNode,
   ParameterNode,
+  ParamsTypeNode,
   PrimitiveSchemaType,
   PropertyNode,
   ResponseNode,
-  RootNode,
   SchemaNode,
+  SourceNode,
   TypeNode,
 } from './nodes/index.ts'
+import { combineExports, combineImports, combineSources } from './utils.ts'
 
 /**
  * Syncs property/parameter schema optionality flags from `required` and `schema.nullable`.
@@ -48,26 +61,48 @@ type CreateSchemaInput = CreateSchemaObjectInput | DistributiveOmit<Exclude<Sche
 type CreateSchemaOutput<T extends CreateSchemaInput> = InferSchemaNode<T> & { kind: 'Schema' }
 
 /**
- * Creates a `RootNode` with stable defaults for `schemas` and `operations`.
+ * Creates an `InputNode` with stable defaults for `schemas` and `operations`.
  *
  * @example
  * ```ts
- * const root = createRoot()
- * // { kind: 'Root', schemas: [], operations: [] }
+ * const input = createInput()
+ * // { kind: 'Input', schemas: [], operations: [] }
  * ```
  *
  * @example
  * ```ts
- * const root = createRoot({ schemas: [petSchema] })
+ * const input = createInput({ schemas: [petSchema] })
  * // keeps default operations: []
  * ```
  */
-export function createRoot(overrides: Partial<Omit<RootNode, 'kind'>> = {}): RootNode {
+export function createInput(overrides: Partial<Omit<InputNode, 'kind'>> = {}): InputNode {
   return {
     schemas: [],
     operations: [],
     ...overrides,
-    kind: 'Root',
+    kind: 'Input',
+  }
+}
+
+/**
+ * Creates an `OutputNode` with a stable default for `files`.
+ *
+ * @example
+ * ```ts
+ * const output = createOutput()
+ * // { kind: 'Output', files: [] }
+ * ```
+ *
+ * @example
+ * ```ts
+ * const output = createOutput({ files: [petFile] })
+ * ```
+ */
+export function createOutput(overrides: Partial<Omit<OutputNode, 'kind'>> = {}): OutputNode {
+  return {
+    files: [],
+    ...overrides,
+    kind: 'Output',
   }
 }
 
@@ -176,6 +211,8 @@ export function createSchema(props: CreateSchemaInput): SchemaNode {
   return { primitive: inferredPrimitive, ...props, kind: 'Schema' } as CreateSchemaOutput<typeof props>
 }
 
+type UserPropertyNode = Pick<PropertyNode, 'name' | 'schema'> & Partial<Omit<PropertyNode, 'kind' | 'name' | 'schema'>>
+
 /**
  * Creates a `PropertyNode`.
  *
@@ -201,7 +238,7 @@ export function createSchema(props: CreateSchemaInput): SchemaNode {
  * // required=true, no optional/nullish
  * ```
  */
-export function createProperty(props: Pick<PropertyNode, 'name' | 'schema'> & Partial<Omit<PropertyNode, 'kind' | 'name' | 'schema'>>): PropertyNode {
+export function createProperty(props: UserPropertyNode): PropertyNode {
   const required = props.required ?? false
 
   return {
@@ -278,24 +315,24 @@ export function createResponse(
  *
  * @example Required typed param
  * ```ts
- * createFunctionParameter({ name: 'petId', type: createTypeNode({ variant: 'reference', name: 'string' }) })
+ * createFunctionParameter({ name: 'petId', type: createParamsType({ variant: 'reference', name: 'string' }) })
  * // → petId: string
  * ```
  *
  * @example Optional param
  * ```ts
- * createFunctionParameter({ name: 'params', type: createTypeNode({ variant: 'reference', name: 'QueryParams' }), optional: true })
+ * createFunctionParameter({ name: 'params', type: createParamsType({ variant: 'reference', name: 'QueryParams' }), optional: true })
  * // → params?: QueryParams
  * ```
  *
  * @example Param with default (implicitly optional; cannot combine with `optional: true`)
  * ```ts
- * createFunctionParameter({ name: 'config', type: createTypeNode({ variant: 'reference', name: 'RequestConfig' }), default: '{}' })
+ * createFunctionParameter({ name: 'config', type: createParamsType({ variant: 'reference', name: 'RequestConfig' }), default: '{}' })
  * // → config: RequestConfig = {}
  * ```
  */
 export function createFunctionParameter(
-  props: { name: string; type?: TypeNode; rest?: boolean } & ({ optional: true; default?: never } | { optional?: false; default?: string }),
+  props: { name: string; type?: ParamsTypeNode; rest?: boolean } & ({ optional: true; default?: never } | { optional?: false; default?: string }),
 ): FunctionParameterNode {
   return {
     optional: false,
@@ -313,26 +350,26 @@ export function createFunctionParameter(
  *
  * @example Reference type (TypeScript: `QueryParams`)
  * ```ts
- * createTypeNode({ variant: 'reference', name: 'QueryParams' })
+ * createParamsType({ variant: 'reference', name: 'QueryParams' })
  * ```
  *
  * @example Struct type (TypeScript: `{ petId: string }`)
  * ```ts
- * createTypeNode({ variant: 'struct', properties: [{ name: 'petId', optional: false, type: createTypeNode({ variant: 'reference', name: 'string' }) }] })
+ * createParamsType({ variant: 'struct', properties: [{ name: 'petId', optional: false, type: createParamsType({ variant: 'reference', name: 'string' }) }] })
  * ```
  *
  * @example Member type (TypeScript: `DeletePetPathParams['petId']`)
  * ```ts
- * createTypeNode({ variant: 'member', base: 'DeletePetPathParams', key: 'petId' })
+ * createParamsType({ variant: 'member', base: 'DeletePetPathParams', key: 'petId' })
  * ```
  */
-export function createTypeNode(
+export function createParamsType(
   props:
     | { variant: 'reference'; name: string }
-    | { variant: 'struct'; properties: Array<{ name: string; optional: boolean; type: TypeNode }> }
+    | { variant: 'struct'; properties: Array<{ name: string; optional: boolean; type: ParamsTypeNode }> }
     | { variant: 'member'; base: string; key: string },
-): TypeNode {
-  return { ...props, kind: 'Type' } as TypeNode
+): ParamsTypeNode {
+  return { ...props, kind: 'ParamsType' } as ParamsTypeNode
 }
 
 /**
@@ -342,8 +379,8 @@ export function createTypeNode(
  * ```ts
  * createParameterGroup({
  *   properties: [
- *     createFunctionParameter({ name: 'id', type: createTypeNode({ variant: 'reference', name: 'string' }), optional: false }),
- *     createFunctionParameter({ name: 'name', type: createTypeNode({ variant: 'reference', name: 'string' }), optional: true }),
+ *     createFunctionParameter({ name: 'id', type: createParamsType({ variant: 'reference', name: 'string' }), optional: false }),
+ *     createFunctionParameter({ name: 'name', type: createParamsType({ variant: 'reference', name: 'string' }), optional: true }),
  *   ],
  *   default: '{}',
  * })
@@ -354,7 +391,7 @@ export function createTypeNode(
  * @example Inline (spread) — children emitted as individual top-level parameters
  * ```ts
  * createParameterGroup({
- *   properties: [createFunctionParameter({ name: 'petId', type: createTypeNode({ variant: 'reference', name: 'string' }), optional: false })],
+ *   properties: [createFunctionParameter({ name: 'petId', type: createParamsType({ variant: 'reference', name: 'string' }), optional: false })],
  *   inline: true,
  * })
  * // declaration → petId: string
@@ -377,8 +414,8 @@ export function createParameterGroup(
  * ```ts
  * createFunctionParameters({
  *   params: [
- *     createFunctionParameter({ name: 'petId', type: createTypeNode({ variant: 'reference', name: 'string' }), optional: false }),
- *     createFunctionParameter({ name: 'config', type: createTypeNode({ variant: 'reference', name: 'RequestConfig' }), optional: false, default: '{}' }),
+ *     createFunctionParameter({ name: 'petId', type: createParamsType({ variant: 'reference', name: 'string' }), optional: false }),
+ *     createFunctionParameter({ name: 'config', type: createParamsType({ variant: 'reference', name: 'RequestConfig' }), optional: false, default: '{}' }),
  *   ],
  * })
  * ```
@@ -396,3 +433,238 @@ export function createFunctionParameters(props: Partial<Omit<FunctionParametersN
     kind: 'FunctionParameters',
   }
 }
+
+/**
+ * Creates an `ImportNode` representing a language-agnostic import/dependency declaration.
+ *
+ * @example Named import
+ * ```ts
+ * createImport({ name: ['useState'], path: 'react' })
+ * // import { useState } from 'react'
+ * ```
+ *
+ * @example Type-only import
+ * ```ts
+ * createImport({ name: ['FC'], path: 'react', isTypeOnly: true })
+ * // import type { FC } from 'react'
+ * ```
+ */
+export function createImport(props: Omit<ImportNode, 'kind'>): ImportNode {
+  return { ...props, kind: 'Import' }
+}
+
+/**
+ * Creates an `ExportNode` representing a language-agnostic export/public API declaration.
+ *
+ * @example Named export
+ * ```ts
+ * createExport({ name: ['Pet'], path: './Pet' })
+ * // export { Pet } from './Pet'
+ * ```
+ *
+ * @example Wildcard export
+ * ```ts
+ * createExport({ path: './utils' })
+ * // export * from './utils'
+ * ```
+ */
+export function createExport(props: Omit<ExportNode, 'kind'>): ExportNode {
+  return { ...props, kind: 'Export' }
+}
+
+/**
+ * Creates a `SourceNode` representing a fragment of source code within a file.
+ *
+ * @example
+ * ```ts
+ * createSource({ name: 'Pet', value: 'export type Pet = { id: number }', isExportable: true })
+ * ```
+ */
+export function createSource(props: Omit<SourceNode, 'kind'>): SourceNode {
+  return { ...props, kind: 'Source' }
+}
+
+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', value: '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 ?? []).map((item) => item.value).join('\n\n')
+  const resolvedExports = input.exports?.length ? combineExports(input.exports) : []
+  const resolvedImports = input.imports?.length && source ? combineImports(input.imports, resolvedExports, source) : []
+  const resolvedSources = input.sources?.length ? combineSources(input.sources) : []
+
+  return {
+    kind: 'File',
+    ...input,
+    id: createHash('sha256').update(input.path).digest('hex'),
+    name: trimExtName(input.baseName),
+    extname,
+    imports: resolvedImports,
+    exports: resolvedExports,
+    sources: resolvedSources,
+    meta: input.meta ?? ({} as TMeta),
+  }
+}
+
+/**
+ * Creates a `ConstNode` representing a TypeScript `const` declaration.
+ *
+ * Mirrors the `Const` component from `@kubb/react-fabric`.
+ * The component's `children` are represented as `nodes`.
+ *
+ * @example Simple constant
+ * ```ts
+ * createConst({ name: 'pet' })
+ * // const pet = ...
+ * ```
+ *
+ * @example Exported constant with type and `as const`
+ * ```ts
+ * createConst({ name: 'pets', export: true, type: 'Pet[]', asConst: true })
+ * // export const pets: Pet[] = ... as const
+ * ```
+ *
+ * @example With JSDoc and child nodes
+ * ```ts
+ * createConst({
+ *   name: 'config',
+ *   export: true,
+ *   JSDoc: { comments: ['@description App configuration'] },
+ *   nodes: [],
+ * })
+ * ```
+ */
+export function createConst(props: Omit<ConstNode, 'kind'>): ConstNode {
+  return { ...props, kind: 'Const' }
+}
+
+/**
+ * Creates a `TypeNode` representing a TypeScript `type` alias declaration.
+ *
+ * Mirrors the `Type` component from `@kubb/react-fabric`.
+ * The component's `children` are represented as `nodes`.
+ *
+ * @example Simple type alias
+ * ```ts
+ * createType({ name: 'Pet' })
+ * // type Pet = ...
+ * ```
+ *
+ * @example Exported type with JSDoc
+ * ```ts
+ * createType({
+ *   name: 'PetStatus',
+ *   export: true,
+ *   JSDoc: { comments: ['@description Status of a pet'] },
+ * })
+ * // export type PetStatus = ...
+ * ```
+ */
+export function createType(props: Omit<TypeNode, 'kind'>): TypeNode {
+  return { ...props, kind: 'Type' }
+}
+
+/**
+ * Creates a `FunctionNode` representing a TypeScript `function` declaration.
+ *
+ * Mirrors the `Function` component from `@kubb/react-fabric`.
+ * The component's `children` are represented as `nodes`.
+ *
+ * @example Simple function
+ * ```ts
+ * createFunction({ name: 'getPet' })
+ * // function getPet() { ... }
+ * ```
+ *
+ * @example Exported async function with return type
+ * ```ts
+ * createFunction({ name: 'fetchPet', export: true, async: true, returnType: 'Pet' })
+ * // export async function fetchPet(): Promise<Pet> { ... }
+ * ```
+ *
+ * @example Function with generics and params
+ * ```ts
+ * createFunction({
+ *   name: 'identity',
+ *   export: true,
+ *   generics: ['T'],
+ *   params: 'value: T',
+ *   returnType: 'T',
+ * })
+ * // export function identity<T>(value: T): T { ... }
+ * ```
+ */
+export function createFunction(props: Omit<FunctionNode, 'kind'>): FunctionNode {
+  return { ...props, kind: 'Function' }
+}
+
+/**
+ * Creates an `ArrowFunctionNode` representing a TypeScript arrow function.
+ *
+ * Mirrors the `Function.Arrow` component from `@kubb/react-fabric`.
+ * The component's `children` are represented as `nodes`.
+ *
+ * @example Simple arrow function
+ * ```ts
+ * createArrowFunction({ name: 'getPet' })
+ * // const getPet = () => { ... }
+ * ```
+ *
+ * @example Single-line exported arrow function
+ * ```ts
+ * createArrowFunction({ name: 'double', export: true, params: 'n: number', singleLine: true })
+ * // export const double = (n: number) => ...
+ * ```
+ *
+ * @example Async arrow function with generics
+ * ```ts
+ * createArrowFunction({
+ *   name: 'fetchPet',
+ *   export: true,
+ *   async: true,
+ *   generics: ['T'],
+ *   params: 'id: string',
+ *   returnType: 'T',
+ * })
+ * // export const fetchPet = async <T>(id: string): Promise<T> => { ... }
+ * ```
+ */
+export function createArrowFunction(props: Omit<ArrowFunctionNode, 'kind'>): ArrowFunctionNode {
+  return { ...props, kind: 'ArrowFunction' }
+}

package/src/guards.ts

@@ -1,14 +1,15 @@
 import type {
   FunctionParameterNode,
   FunctionParametersNode,
+  InputNode,
   Node,
   NodeKind,
   OperationNode,
+  OutputNode,
   ParameterGroupNode,
   ParameterNode,
   PropertyNode,
   ResponseNode,
-  RootNode,
   SchemaNode,
   SchemaNodeByType,
 } from './nodes/index.ts'
@@ -31,16 +32,28 @@ function isKind<T extends Node>(kind: NodeKind) {
 }
 
 /**
- * Returns `true` when the input is a `RootNode`.
+ * Returns `true` when the input is an `InputNode`.
  *
  * @example
  * ```ts
- * if (isRootNode(node)) {
+ * if (isInputNode(node)) {
  *   console.log(node.schemas.length)
  * }
  * ```
  */
-export const isRootNode = isKind<RootNode>('Root')
+export const isInputNode = isKind<InputNode>('Input')
+
+/**
+ * Returns `true` when the input is an `OutputNode`.
+ *
+ * @example
+ * ```ts
+ * if (isOutputNode(node)) {
+ *   console.log(node.files.length)
+ * }
+ * ```
+ */
+export const isOutputNode = isKind<OutputNode>('Output')
 
 /**
  * Returns `true` when the input is an `OperationNode`.

package/src/index.ts

@@ -1,19 +1,28 @@
 export type { ScalarPrimitive } from './constants.ts'
-export { httpMethods, isScalarPrimitive, mediaTypes, schemaTypes } from './constants.ts'
+export { httpMethods, isScalarPrimitive, mediaTypes, nodeKinds, schemaTypes } from './constants.ts'
 export {
+  createArrowFunction,
+  createConst,
+  createExport,
+  createFile,
+  createFunction,
   createFunctionParameter,
   createFunctionParameters,
+  createImport,
+  createInput,
   createOperation,
+  createOutput,
   createParameter,
   createParameterGroup,
+  createParamsType,
   createProperty,
   createResponse,
-  createRoot,
   createSchema,
-  createTypeNode,
+  createSource,
+  createType,
   syncOptionality,
 } from './factory.ts'
-export { isOperationNode, isSchemaNode, narrowSchema } from './guards.ts'
+export { isInputNode, isOperationNode, isOutputNode, isSchemaNode, narrowSchema } from './guards.ts'
 export type { ParserOptions } from './infer.ts'
 export type { Printer, PrinterFactoryOptions, PrinterPartial } from './printer.ts'
 export { createPrinterFactory, definePrinter } from './printer.ts'
@@ -21,5 +30,14 @@ export { extractRefName } from './refs.ts'
 export { childName, collectImports, enumPropName, findDiscriminator } from './resolvers.ts'
 export { mergeAdjacentObjects, setDiscriminatorEnum, setEnumName, simplifyUnion } from './transformers.ts'
 export type { OperationParamsResolver } from './utils.ts'
-export { caseParams, createDiscriminantNode, createOperationParams, isStringType, syncSchemaRef } from './utils.ts'
+export {
+  caseParams,
+  combineExports,
+  combineImports,
+  combineSources,
+  createDiscriminantNode,
+  createOperationParams,
+  isStringType,
+  syncSchemaRef,
+} from './utils.ts'
 export { collect, composeTransformers, transform, walk } from './visitor.ts'

package/src/mocks.ts

@@ -1,10 +1,10 @@
-import { createOperation, createParameter, createProperty, createResponse, createRoot, createSchema } from './factory.ts'
-import type { RootNode } from './nodes/root.ts'
+import { createInput, createOperation, createParameter, createProperty, createResponse, createSchema } from './factory.ts'
+import type { InputNode } from './nodes/root.ts'
 
 /**
  * Builds a minimal sample AST with one `Pet` schema and one `getPetById` operation.
  */
-export function buildSampleTree(): RootNode {
+export function buildSampleTree(): InputNode {
   const petSchema = createSchema({
     type: 'object',
     name: 'Pet',
@@ -29,7 +29,7 @@ export function buildSampleTree(): RootNode {
     ],
   })
 
-  return createRoot({ schemas: [petSchema], operations: [operation] })
+  return createInput({ schemas: [petSchema], operations: [operation] })
 }
 
 /**
@@ -37,11 +37,11 @@ export function buildSampleTree(): RootNode {
  * - six named schemas (`Pet`, `NewPet`, `PetList`, `Error`, `PetOrError`, `FullPet`)
  * - two operations (`listPets`, `createPet`)
  */
-export function buildFixture(): RootNode {
+export function buildFixture(): InputNode {
   const refPet = createSchema({ type: 'ref', ref: 'Pet' })
   const refError = createSchema({ type: 'ref', ref: 'Error' })
 
-  return createRoot({
+  return createInput({
     schemas: [
       createSchema({
         name: 'Pet',

package/src/nodes/base.ts

@@ -7,7 +7,8 @@
  * ```
  */
 export type NodeKind =
-  | 'Root'
+  | 'Input'
+  | 'Output'
   | 'Operation'
   | 'Schema'
   | 'Property'
@@ -17,13 +18,21 @@ export type NodeKind =
   | 'ParameterGroup'
   | 'FunctionParameters'
   | 'Type'
+  | 'ParamsType'
+  | 'File'
+  | 'Import'
+  | 'Export'
+  | 'Source'
+  | 'Const'
+  | 'Function'
+  | 'ArrowFunction'
 
 /**
  * Base shape shared by all AST nodes.
  *
  * @example
  * ```ts
- * const base: BaseNode = { kind: 'Root' }
+ * const base: BaseNode = { kind: 'Input' }
  * ```
  */
 export type BaseNode = {