@kubb/core 5.0.0-alpha.9 → 5.0.0-beta.10

package/src/devtools.ts

@@ -1,10 +1,17 @@
-import type { RootNode } from '@kubb/ast/types'
+import type { InputNode } from '@kubb/ast'
 import { deflateSync, inflateSync } from 'fflate'
 import { x } from 'tinyexec'
-import type { DevtoolsOptions } from './types.ts'
+
+export type DevtoolsOptions = {
+  /**
+   * Open the AST inspector in Kubb Studio (`/ast`). Defaults to the main Studio page.
+   * @default false
+   */
+  ast?: boolean
+}
 
 /**
- * Encodes a `RootNode` as a compressed, URL-safe string.
+ * Encodes an `InputNode` as a compressed, URL-safe string.
  *
  * The JSON representation is deflate-compressed with {@link deflateSync} before
  * base64url encoding, which typically reduces payload size by 70–80 % and
@@ -12,41 +19,41 @@ import type { DevtoolsOptions } from './types.ts'
  *
  * Use {@link decodeAst} to reverse.
  */
-export function encodeAst(root: RootNode): string {
-  const compressed = deflateSync(new TextEncoder().encode(JSON.stringify(root)))
+export function encodeAst(input: InputNode): string {
+  const compressed = deflateSync(new TextEncoder().encode(JSON.stringify(input)))
   return Buffer.from(compressed).toString('base64url')
 }
 
 /**
- * Decodes a `RootNode` from a string produced by {@link encodeAst}.
+ * Decodes an `InputNode` from a string produced by {@link encodeAst}.
  *
  * Works in both Node.js and the browser — no streaming APIs required.
  */
-export function decodeAst(encoded: string): RootNode {
+export function decodeAst(encoded: string): InputNode {
   const bytes = Buffer.from(encoded, 'base64url')
-  return JSON.parse(new TextDecoder().decode(inflateSync(bytes))) as RootNode
+  return JSON.parse(new TextDecoder().decode(inflateSync(bytes))) as InputNode
 }
 
 /**
- * Constructs the Kubb Studio URL for the given `RootNode`.
+ * Constructs the Kubb Studio URL for the given `InputNode`.
  * When `options.ast` is `true`, navigates to the AST inspector (`/ast`).
- * The `root` is encoded and attached as the `?root=` query parameter so Studio
+ * The `input` is encoded and attached as the `?root=` query parameter so Studio
  * can decode and render it without a round-trip to any server.
  */
-export function getStudioUrl(root: RootNode, studioUrl: string, options: DevtoolsOptions = {}): string {
+export function getStudioUrl(input: InputNode, studioUrl: string, options: DevtoolsOptions = {}): string {
   const baseUrl = studioUrl.replace(/\/$/, '')
   const path = options.ast ? '/ast' : ''
 
-  return `${baseUrl}${path}?root=${encodeAst(root)}`
+  return `${baseUrl}${path}?root=${encodeAst(input)}`
 }
 
 /**
- * Opens the Kubb Studio URL for the given `RootNode` in the default browser —
+ * Opens the Kubb Studio URL for the given `InputNode` in the default browser —
  *
  * Falls back to printing the URL if the browser cannot be launched.
  */
-export async function openInStudio(root: RootNode, studioUrl: string, options: DevtoolsOptions = {}): Promise<void> {
-  const url = getStudioUrl(root, studioUrl, options)
+export async function openInStudio(input: InputNode, studioUrl: string, options: DevtoolsOptions = {}): Promise<void> {
+  const url = getStudioUrl(input, studioUrl, options)
 
   const cmd = process.platform === 'win32' ? 'cmd' : process.platform === 'darwin' ? 'open' : 'xdg-open'
   const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url]

package/src/index.ts

@@ -1,22 +1,20 @@
-export { definePrinter } from '@kubb/ast'
-export { build, build as default, safeBuild, setup } from './build.ts'
-export { type CLIOptions, type ConfigInput, defineConfig, isInputPath } from './config.ts'
-export { formatters, linters, logLevel } from './constants.ts'
+export { AsyncEventEmitter, URLPath } from '@internals/utils'
+export * as ast from '@kubb/ast'
+export { logLevel } from './constants.ts'
 export { createAdapter } from './createAdapter.ts'
-export { createPlugin } from './createPlugin.ts'
+export { createKubb } from './createKubb.ts'
+export { createRenderer } from './createRenderer.ts'
 export { createStorage } from './createStorage.ts'
 export { defineGenerator } from './defineGenerator.ts'
 export { defineLogger } from './defineLogger.ts'
-export { defaultResolveOptions, defineResolver } from './defineResolver.ts'
-export { getMode, PluginDriver } from './PluginDriver.ts'
+export { defineMiddleware } from './defineMiddleware.ts'
+export { defineParser } from './defineParser.ts'
+export { definePlugin } from './definePlugin.ts'
+export { defineResolver } from './defineResolver.ts'
+export { FileManager } from './FileManager.ts'
+export { FileProcessor } from './FileProcessor.ts'
+export { PluginDriver } from './PluginDriver.ts'
 export { fsStorage } from './storages/fsStorage.ts'
 export { memoryStorage } from './storages/memoryStorage.ts'
 export * from './types.ts'
-export type { FunctionParamsAST } from './utils/FunctionParams.ts'
-export { FunctionParams } from './utils/FunctionParams.ts'
-export { detectFormatter } from './utils/formatters.ts'
-export type { FileMetaBase } from './utils/getBarrelFiles.ts'
-export { getBarrelFiles } from './utils/getBarrelFiles.ts'
-export { getConfigs } from './utils/getConfigs.ts'
-export { detectLinter } from './utils/linters.ts'
-export { satisfiesDependency } from './utils/packageJSON.ts'
+export { isInputPath } from './createKubb.ts'

package/src/mocks.ts

@@ -0,0 +1,177 @@
+import { resolve } from 'node:path'
+import type { FileNode, OperationNode, SchemaNode, Visitor } from '@kubb/ast'
+import { transform } from '@kubb/ast'
+import { FileManager } from './FileManager.ts'
+import { applyHookResult, PluginDriver } from './PluginDriver.ts'
+import type { Adapter, AdapterFactoryOptions, Config, Generator, GeneratorContext, NormalizedPlugin, PluginFactoryOptions } from './types.ts'
+
+/**
+
+ * Creates a minimal `PluginDriver` mock for unit tests.
+ */
+export function createMockedPluginDriver(options: { name?: string; plugin?: NormalizedPlugin; config?: Config } = {}): PluginDriver {
+  return {
+    config: options?.config ?? {
+      root: '.',
+      output: {
+        path: './path',
+      },
+    },
+    getPlugin(_pluginName: string): NormalizedPlugin | undefined {
+      return options?.plugin
+    },
+    getResolver: (_pluginName: string) => options?.plugin?.resolver,
+    fileManager: new FileManager(),
+  } as unknown as PluginDriver
+}
+
+/**
+ * Creates a minimal `Adapter` mock for unit tests.
+ * `parse` returns an empty `InputNode` by default; override via `options.parse`.
+ * `getImports` returns `[]` by default.
+ */
+export function createMockedAdapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptions>(
+  options: {
+    name?: TOptions['name']
+    resolvedOptions?: TOptions['resolvedOptions']
+    inputNode?: Adapter<TOptions>['inputNode']
+    parse?: Adapter<TOptions>['parse']
+    getImports?: Adapter<TOptions>['getImports']
+  } = {},
+): Adapter<TOptions> {
+  const inputNode = options.inputNode ?? null
+  return {
+    name: (options.name ?? 'oas') as TOptions['name'],
+    options: (options.resolvedOptions ?? {}) as TOptions['resolvedOptions'],
+    inputNode,
+    parse: options.parse ?? (async () => ({ kind: 'Input' as const, schemas: [], operations: [] })),
+    getImports: options.getImports ?? ((_node: SchemaNode, _resolve: (schemaName: string) => { name: string; path: string }) => []),
+  } as Adapter<TOptions>
+}
+
+/**
+ * Creates a minimal plugin mock for unit tests.
+ *
+ * @example
+ * `const plugin = createMockedPlugin<PluginTs>({ name: '@kubb/plugin-ts', options })`
+ */
+export function createMockedPlugin<TOptions extends PluginFactoryOptions = PluginFactoryOptions>(params: {
+  name: TOptions['name']
+  options: TOptions['resolvedOptions']
+  resolver?: TOptions['resolver']
+  transformer?: Visitor
+  dependencies?: Array<string>
+}): NormalizedPlugin<TOptions> {
+  return {
+    name: params.name,
+    options: params.options,
+    resolver: params.resolver,
+    transformer: params.transformer,
+    dependencies: params.dependencies,
+    hooks: {},
+  } as unknown as NormalizedPlugin<TOptions>
+}
+
+type RenderGeneratorOptions<TOptions extends PluginFactoryOptions> = {
+  config: Config
+  adapter: Adapter
+  driver: PluginDriver
+  plugin: NormalizedPlugin<TOptions>
+  options: TOptions['resolvedOptions']
+  resolver: TOptions['resolver']
+}
+
+function createMockedPluginContext<TOptions extends PluginFactoryOptions>(opts: RenderGeneratorOptions<TOptions>): Omit<GeneratorContext<TOptions>, 'options'> {
+  const root = resolve(opts.config.root, opts.config.output.path)
+
+  return {
+    config: opts.config,
+    root,
+    getMode: (output: { path: string }) => PluginDriver.getMode(resolve(root, output.path)),
+    adapter: opts.adapter,
+    resolver: opts.resolver,
+    plugin: opts.plugin,
+    driver: opts.driver,
+    getResolver: (name: string) => opts.driver.getResolver(name),
+    inputNode: { kind: 'Input', schemas: [], operations: [] },
+    addFile: async (...files: Array<FileNode>) => opts.driver.fileManager.add(...files),
+    upsertFile: async (...files: Array<FileNode>) => opts.driver.fileManager.upsert(...files),
+    hooks: opts.driver.hooks ?? ({} as never),
+    warn: (msg: string) => console.warn(msg),
+    error: (msg: string) => console.error(msg),
+    info: (msg: string) => console.info(msg),
+    openInStudio: async () => {},
+  } as unknown as Omit<GeneratorContext<TOptions>, 'options'>
+}
+
+/**
+ * Renders a generator's `schema` method in a test context.
+ *
+ * @example
+ * ```ts
+ * await renderGeneratorSchema(typeGenerator, node, { config, adapter, driver, plugin, options, resolver })
+ * await matchFiles(driver.fileManager.files)
+ * ```
+ */
+export async function renderGeneratorSchema<TOptions extends PluginFactoryOptions>(
+  generator: Generator<TOptions>,
+  node: SchemaNode,
+  opts: RenderGeneratorOptions<TOptions>,
+): Promise<void> {
+  if (!generator.schema) return
+  const context = createMockedPluginContext(opts)
+  const transformedNode = opts.plugin.transformer ? transform(node, opts.plugin.transformer) : node
+  const result = await generator.schema(transformedNode, {
+    ...context,
+    options: opts.options,
+  })
+  await applyHookResult(result, opts.driver, generator.renderer ?? undefined)
+}
+
+/**
+ * Renders a generator's `operation` method in a test context.
+ *
+ * @example
+ * ```ts
+ * await renderGeneratorOperation(typeGenerator, node, { config, adapter, driver, plugin, options, resolver })
+ * await matchFiles(driver.fileManager.files)
+ * ```
+ */
+export async function renderGeneratorOperation<TOptions extends PluginFactoryOptions>(
+  generator: Generator<TOptions>,
+  node: OperationNode,
+  opts: RenderGeneratorOptions<TOptions>,
+): Promise<void> {
+  if (!generator.operation) return
+  const context = createMockedPluginContext(opts)
+  const transformedNode = opts.plugin.transformer ? transform(node, opts.plugin.transformer) : node
+  const result = await generator.operation(transformedNode, {
+    ...context,
+    options: opts.options,
+  })
+  await applyHookResult(result, opts.driver, generator.renderer ?? undefined)
+}
+
+/**
+ * Renders a generator's `operations` method in a test context.
+ *
+ * @example
+ * ```ts
+ * await renderGeneratorOperations(classClientGenerator, nodes, { config, adapter, driver, plugin, options, resolver })
+ * await matchFiles(driver.fileManager.files)
+ * ```
+ */
+export async function renderGeneratorOperations<TOptions extends PluginFactoryOptions>(
+  generator: Generator<TOptions>,
+  nodes: Array<OperationNode>,
+  opts: RenderGeneratorOptions<TOptions>,
+): Promise<void> {
+  if (!generator.operations) return
+  const context = createMockedPluginContext(opts)
+  const transformedNodes = opts.plugin.transformer ? nodes.map((n) => transform(n, opts.plugin.transformer!)) : nodes
+  const result = await generator.operations(transformedNodes, {
+    ...context,
+    options: opts.options,
+  })
+  await applyHookResult(result, opts.driver, generator.renderer ?? undefined)
+}

package/src/storages/fsStorage.ts

@@ -7,7 +7,7 @@ import { createStorage } from '../createStorage.ts'
 /**
  * Built-in filesystem storage driver.
  *
- * This is the default storage when no `storage` option is configured in `output`.
+ * This is the default storage when no `storage` option is configured in the root config.
  * Keys are resolved against `process.cwd()`, so root-relative paths such as
  * `src/gen/api/getPets.ts` are written to the correct location without extra configuration.
  *
@@ -19,11 +19,13 @@ import { createStorage } from '../createStorage.ts'
  *
  * @example
  * ```ts
- * import { defineConfig, fsStorage } from '@kubb/core'
+ * import { fsStorage } from '@kubb/core'
+ * import { defineConfig } from 'kubb'
  *
  * export default defineConfig({
  *   input:  { path: './petStore.yaml' },
- *   output: { path: './src/gen', storage: fsStorage() },
+ *   output: { path: './src/gen' },
+ *   storage: fsStorage(),
  * })
  * ```
  */
@@ -33,14 +35,14 @@ export const fsStorage = createStorage(() => ({
     try {
       await access(resolve(key))
       return true
-    } catch {
+    } catch (_error) {
       return false
     }
   },
   async getItem(key: string) {
     try {
       return await readFile(resolve(key), 'utf8')
-    } catch {
+    } catch (_error) {
       return null
     }
   },
@@ -52,12 +54,15 @@ export const fsStorage = createStorage(() => ({
   },
   async getKeys(base?: string) {
     const keys: Array<string> = []
+    const resolvedBase = resolve(base ?? process.cwd())
 
     async function walk(dir: string, prefix: string): Promise<void> {
       let entries: Array<Dirent>
       try {
-        entries = (await readdir(dir, { withFileTypes: true })) as Array<Dirent>
-      } catch {
+        entries = (await readdir(dir, {
+          withFileTypes: true,
+        })) as Array<Dirent>
+      } catch (_error) {
         return
       }
       for (const entry of entries) {
@@ -70,7 +75,7 @@ export const fsStorage = createStorage(() => ({
       }
     }
 
-    await walk(resolve(base ?? process.cwd()), '')
+    await walk(resolvedBase, '')
 
     return keys
   },

package/src/storages/memoryStorage.ts

@@ -9,11 +9,13 @@ import { createStorage } from '../createStorage.ts'
  *
  * @example
  * ```ts
- * import { defineConfig, memoryStorage } from '@kubb/core'
+ * import { memoryStorage } from '@kubb/core'
+ * import { defineConfig } from 'kubb'
  *
  * export default defineConfig({
  *   input:  { path: './petStore.yaml' },
- *   output: { path: './src/gen', storage: memoryStorage() },
+ *   output: { path: './src/gen' },
+ *   storage: memoryStorage(),
  * })
  * ```
  */