@kubb/core 5.0.0-beta.4 → 5.0.0-beta.41

package/src/Telemetry.ts

@@ -0,0 +1,278 @@
+import { randomBytes } from 'node:crypto'
+import os from 'node:os'
+import process from 'node:process'
+import { executeIfOnline, isCIEnvironment } from '@internals/utils'
+import { OTLP_ENDPOINT } from './constants.ts'
+
+// OpenTelemetry OTLP JSON types
+// https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/trace/v1/trace.proto
+// https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/common/v1/common.proto
+
+type OtlpStringValue = { stringValue: string }
+type OtlpBoolValue = { boolValue: boolean }
+type OtlpIntValue = { intValue: number }
+type OtlpDoubleValue = { doubleValue: number }
+type OtlpBytesValue = { bytesValue: string }
+type OtlpArrayValue = { arrayValue: { values: Array<OtlpAnyValue> } }
+type OtlpKvListValue = { kvlistValue: { values: Array<OtlpKeyValue> } }
+
+type OtlpAnyValue = OtlpStringValue | OtlpBoolValue | OtlpIntValue | OtlpDoubleValue | OtlpBytesValue | OtlpArrayValue | OtlpKvListValue
+
+type OtlpKeyValue = {
+  key: string
+  value: OtlpAnyValue
+}
+
+type OtlpResource = {
+  attributes: Array<OtlpKeyValue>
+  droppedAttributesCount?: number
+}
+
+type OtlpInstrumentationScope = {
+  name: string
+  version?: string
+  attributes?: Array<OtlpKeyValue>
+  droppedAttributesCount?: number
+}
+
+/** https://github.com/open-telemetry/opentelemetry-proto/blob/main/opentelemetry/proto/trace/v1/trace.proto#L103 */
+type OtlpSpanKind = 0 | 1 | 2 | 3 | 4 | 5
+
+/** 0 = STATUS_CODE_UNSET, 1 = STATUS_CODE_OK, 2 = STATUS_CODE_ERROR */
+type OtlpStatusCode = 0 | 1 | 2
+
+type OtlpStatus = {
+  code: OtlpStatusCode
+  message?: string
+}
+
+type OtlpSpan = {
+  traceId: string
+  spanId: string
+  traceState?: string
+  parentSpanId?: string
+  name: string
+  kind: OtlpSpanKind
+  startTimeUnixNano: string
+  endTimeUnixNano: string
+  attributes?: Array<OtlpKeyValue>
+  droppedAttributesCount?: number
+  events?: Array<OtlpSpanEvent>
+  droppedEventsCount?: number
+  links?: Array<OtlpSpanLink>
+  droppedLinksCount?: number
+  status?: OtlpStatus
+}
+
+type OtlpSpanEvent = {
+  timeUnixNano: string
+  name: string
+  attributes?: Array<OtlpKeyValue>
+  droppedAttributesCount?: number
+}
+
+type OtlpSpanLink = {
+  traceId: string
+  spanId: string
+  traceState?: string
+  attributes?: Array<OtlpKeyValue>
+  droppedAttributesCount?: number
+}
+
+type OtlpScopeSpans = {
+  scope: OtlpInstrumentationScope
+  spans: Array<OtlpSpan>
+  schemaUrl?: string
+}
+
+type OtlpResourceSpans = {
+  resource: OtlpResource
+  scopeSpans: Array<OtlpScopeSpans>
+  schemaUrl?: string
+}
+
+/** Root payload sent to POST /v1/traces */
+type OtlpExportTraceServiceRequest = {
+  resourceSpans: Array<OtlpResourceSpans>
+}
+
+/**
+ * Anonymous plugin name and options snapshot sent with each telemetry event.
+ */
+export type TelemetryPlugin = {
+  /**
+   * Plugin name as registered in the Kubb config, e.g. `'@kubb/plugin-ts'`.
+   */
+  name: string
+  /**
+   * anonymized plugin options snapshot, values are included but cannot be traced back to the user.
+   */
+  options: Record<string, unknown>
+}
+
+export type TelemetryEvent = {
+  command: string
+  kubbVersion: string
+  nodeVersion: string
+  platform: string
+  ci: boolean
+  plugins: Array<TelemetryPlugin>
+  duration: number
+  filesCreated: number
+  status: 'success' | 'failed'
+}
+
+/**
+ * Anonymous OTLP usage telemetry for the Kubb run. All methods are static, so call them as
+ * `Telemetry.build(...)`, `Telemetry.send(...)`, and `Telemetry.isDisabled()`. No file paths,
+ * OpenAPI specs, or secrets are ever included, and sending fails silently to never break a run.
+ */
+export class Telemetry {
+  /**
+   * Returns `true` when telemetry is disabled via `DO_NOT_TRACK` or `KUBB_DISABLE_TELEMETRY`.
+   */
+  static isDisabled(): boolean {
+    return (
+      process.env['DO_NOT_TRACK'] === '1' ||
+      process.env['DO_NOT_TRACK'] === 'true' ||
+      process.env['KUBB_DISABLE_TELEMETRY'] === '1' ||
+      process.env['KUBB_DISABLE_TELEMETRY'] === 'true'
+    )
+  }
+
+  /**
+   * Build an anonymous telemetry payload from a completed generation run.
+   */
+  static build(options: {
+    command: 'generate' | 'mcp' | 'validate' | 'agent'
+    kubbVersion: string
+    plugins?: Array<TelemetryPlugin>
+    hrStart: [number, number]
+    filesCreated?: number
+    status: 'success' | 'failed'
+  }): TelemetryEvent {
+    const [seconds, nanoseconds] = process.hrtime(options.hrStart)
+    const duration = Math.round(seconds * 1000 + nanoseconds / 1e6)
+
+    return {
+      command: options.command,
+      kubbVersion: options.kubbVersion,
+      nodeVersion: process.versions.node.split('.')[0] as string,
+      platform: os.platform(),
+      ci: isCIEnvironment(),
+      plugins: options.plugins ?? [],
+      duration,
+      filesCreated: options.filesCreated ?? 0,
+      status: options.status,
+    }
+  }
+
+  /**
+   * Convert a {@link TelemetryEvent} into an OTLP-compatible JSON trace payload.
+   * See https://opentelemetry.io/docs/languages/sdk-configuration/otlp-exporter/
+   */
+  static buildOtlpPayload(event: TelemetryEvent): OtlpExportTraceServiceRequest {
+    const traceId = randomBytes(16).toString('hex')
+    const spanId = randomBytes(8).toString('hex')
+    const endTimeNs = BigInt(Date.now()) * 1_000_000n
+    const startTimeNs = endTimeNs - BigInt(event.duration) * 1_000_000n
+
+    const attributes: Array<OtlpKeyValue> = [
+      { key: 'kubb.command', value: { stringValue: event.command } },
+      { key: 'kubb.version', value: { stringValue: event.kubbVersion } },
+      { key: 'kubb.node_version', value: { stringValue: event.nodeVersion } },
+      { key: 'kubb.platform', value: { stringValue: event.platform } },
+      { key: 'kubb.ci', value: { boolValue: event.ci } },
+      { key: 'kubb.files_created', value: { intValue: event.filesCreated } },
+      { key: 'kubb.status', value: { stringValue: event.status } },
+      {
+        key: 'kubb.plugins',
+        value: {
+          arrayValue: {
+            values: event.plugins.map(
+              (p): OtlpKvListValue => ({
+                kvlistValue: {
+                  values: [
+                    { key: 'name', value: { stringValue: p.name } },
+                    {
+                      key: 'options',
+                      value: {
+                        stringValue: JSON.stringify({
+                          ...p.options,
+                          usedEnumNames: undefined,
+                        }),
+                      },
+                    },
+                  ],
+                },
+              }),
+            ),
+          },
+        },
+      },
+    ]
+
+    return {
+      resourceSpans: [
+        {
+          resource: {
+            attributes: [
+              { key: 'service.name', value: { stringValue: 'kubb-core' } },
+              {
+                key: 'service.version',
+                value: { stringValue: event.kubbVersion },
+              },
+              { key: 'telemetry.sdk.language', value: { stringValue: 'nodejs' } },
+            ],
+          },
+          scopeSpans: [
+            {
+              scope: { name: 'kubb-core', version: event.kubbVersion },
+              spans: [
+                {
+                  traceId,
+                  spanId,
+                  name: event.command,
+                  kind: 1 satisfies OtlpSpanKind,
+                  startTimeUnixNano: String(startTimeNs),
+                  endTimeUnixNano: String(endTimeNs),
+                  attributes,
+                  status: {
+                    code: (event.status === 'success' ? 1 : 2) satisfies OtlpStatusCode,
+                  },
+                },
+              ],
+            },
+          ],
+        },
+      ],
+    }
+  }
+
+  /**
+   * Send an anonymous telemetry event to the Kubb OTLP endpoint. Respects `DO_NOT_TRACK` and
+   * `KUBB_DISABLE_TELEMETRY`, and fails silently so telemetry never interrupts a run.
+   */
+  static async send(event: TelemetryEvent): Promise<void> {
+    if (Telemetry.isDisabled()) {
+      return
+    }
+
+    await executeIfOnline(async () => {
+      try {
+        await fetch(`${OTLP_ENDPOINT}/v1/traces`, {
+          method: 'POST',
+          headers: {
+            'Content-Type': 'application/json',
+            'Kubb-Telemetry-Version': '1',
+            'Kubb-Telemetry-Source': 'kubb-core',
+          },
+          body: JSON.stringify(Telemetry.buildOtlpPayload(event)),
+          signal: AbortSignal.timeout(5_000),
+        })
+      } catch (_e) {
+        // Fail silently, telemetry must never break the run
+      }
+    })
+  }
+}

package/src/Transform.ts

@@ -0,0 +1,58 @@
+import type { OperationNode, SchemaNode, Visitor } from '@kubb/ast'
+import { transform } from '@kubb/ast'
+
+/**
+ * Holds one `Visitor` per plugin, keyed by plugin name. Each plugin's transformer runs in
+ * isolation on the original adapter node. `applyTo` is a lookup, not a chain, so plugin A's
+ * visitor never sees plugin B's output. When no transformer is registered, `applyTo` returns
+ * the original node reference, and the `@kubb/ast` `transform` primitive does the same when
+ * its visitor leaves the tree untouched. Callers can compare by identity to detect a no-op.
+ *
+ * Registration order matches the order setup hooks fire, which the driver has already sorted
+ * by `enforce` and dependency edges. The registry does not re-order anything.
+ */
+export class Transform {
+  readonly #visitors = new Map<string, Visitor>()
+
+  /**
+   * Number of plugins with a registered transformer.
+   */
+  get size(): number {
+    return this.#visitors.size
+  }
+
+  /**
+   * Records `visitor` as the transformer for `pluginName`. A second call for the same plugin
+   * replaces the first.
+   */
+  register(pluginName: string, visitor: Visitor): void {
+    this.#visitors.set(pluginName, visitor)
+  }
+
+  /**
+   * Looks up the transformer for `pluginName`. The generator context uses this so plugins can
+   * read their own visitor through `ctx.transformer`.
+   */
+  get(pluginName: string): Visitor | undefined {
+    return this.#visitors.get(pluginName)
+  }
+
+  /**
+   * Runs the plugin's transformer on `node`. Returns the original node reference when the
+   * plugin has no transformer, so callers can compare by identity to detect a no-op.
+   */
+  applyTo<TNode extends SchemaNode | OperationNode>(pluginName: string, node: TNode): TNode {
+    const visitor = this.#visitors.get(pluginName)
+    if (!visitor) return node
+
+    return transform(node, visitor) as TNode
+  }
+
+  /**
+   * Clears every registration. Called from the driver's `dispose()` so visitors do not leak
+   * across builds.
+   */
+  dispose(): void {
+    this.#visitors.clear()
+  }
+}

package/src/constants.ts

@@ -1,35 +1,127 @@
-import type { FileNode } from '@kubb/ast'
+/**
+ * Number of file writes to batch in parallel during `flushPendingFiles`.
+ */
+export const STREAM_FLUSH_EVERY = 50
+
+/**
+ * OpenTelemetry ingestion endpoint for anonymous usage telemetry.
+ */
+export const OTLP_ENDPOINT = 'https://otlp.kubb.dev' as const
 
 /**
- * Base URL for the Kubb Studio web app.
+ * Maximum number of █ characters in a plugin timing bar.
  */
-export const DEFAULT_STUDIO_URL = 'https://studio.kubb.dev' as const
+export const SUMMARY_MAX_BAR_LENGTH = 10 as const
 
 /**
- * Maximum number of files processed in parallel by FileProcessor.
+ * Divides elapsed milliseconds into bar-length units (1 block per 100 ms).
  */
-export const PARALLEL_CONCURRENCY_LIMIT = 100
+export const SUMMARY_TIME_SCALE_DIVISOR = 100 as const
 
 /**
- * Default banner style written at the top of every generated file.
+ * Number of schema/operation nodes to dispatch concurrently during generation.
  */
-export const DEFAULT_BANNER = 'simple' as const
+export const SCHEMA_PARALLEL = 8
 
 /**
- * Default file-extension mapping used when no explicit mapping is configured.
+ * Upper bound of hook listeners a single plugin can add to one event (its schema, operation,
+ * and operations generators, plus lifecycle hooks). Used to size the hooks emitter's
+ * max-listener ceiling so a multi-generator plugin set does not trip Node's leak warning.
  */
-export const DEFAULT_EXTENSION: Record<FileNode['extname'], FileNode['extname'] | ''> = { '.ts': '.ts' }
+export const HOOK_LISTENERS_PER_PLUGIN = 4
 
 /**
- * Numeric log-level thresholds used internally to compare verbosity.
- *
- * Higher numbers are more verbose.
+ * Plugin `include` filter types that select operations directly. When one of these is set
+ * without a `schemaName` include, the generate phase pre-scans operations to compute the set
+ * of schemas they reach, so unreachable schemas can be pruned for that plugin.
  */
-export const logLevel = {
-  silent: Number.NEGATIVE_INFINITY,
-  error: 0,
-  warn: 1,
-  info: 3,
-  verbose: 4,
-  debug: 5,
+export const OPERATION_FILTER_TYPES: ReadonlySet<string> = new Set(['tag', 'operationId', 'path', 'method', 'contentType'])
+
+/**
+ * Stable codes Kubb attaches to a `Diagnostic`. Each maps to a known failure mode
+ * and stays stable so it can be referenced in tooling and (later) docs. Reference
+ * these instead of inlining the string at a throw site.
+ */
+export const diagnosticCode = {
+  /**
+   * Fallback for an unstructured error with no specific code.
+   */
+  unknown: 'KUBB_UNKNOWN',
+  /**
+   * The `input.path` file or URL could not be read.
+   */
+  inputNotFound: 'KUBB_INPUT_NOT_FOUND',
+  /**
+   * An adapter was configured without an `input`.
+   */
+  inputRequired: 'KUBB_INPUT_REQUIRED',
+  /**
+   * A `$ref` (or equivalent reference) could not be resolved in the source document.
+   */
+  refNotFound: 'KUBB_REF_NOT_FOUND',
+  /**
+   * A server variable value is not allowed by its `enum`.
+   */
+  invalidServerVariable: 'KUBB_INVALID_SERVER_VARIABLE',
+  /**
+   * A required plugin is missing from the config.
+   */
+  pluginNotFound: 'KUBB_PLUGIN_NOT_FOUND',
+  /**
+   * A plugin threw while generating.
+   */
+  pluginFailed: 'KUBB_PLUGIN_FAILED',
+  /**
+   * A plugin reported a non-fatal warning through `ctx.warn`.
+   */
+  pluginWarning: 'KUBB_PLUGIN_WARNING',
+  /**
+   * A plugin reported an informational message through `ctx.info`.
+   */
+  pluginInfo: 'KUBB_PLUGIN_INFO',
+  /**
+   * A schema uses a `format` Kubb does not map to a specific type. Reserved for
+   * adapters to emit as a `warning`.
+   */
+  unsupportedFormat: 'KUBB_UNSUPPORTED_FORMAT',
+  /**
+   * A referenced schema or operation is marked `deprecated`. Reserved for adapters
+   * to emit as an `info`.
+   */
+  deprecated: 'KUBB_DEPRECATED',
+  /**
+   * An adapter is required but the config has none. The build cannot read the input
+   * without one.
+   */
+  adapterRequired: 'KUBB_ADAPTER_REQUIRED',
+  /**
+   * A resolved output path escapes the output directory, which can stem from a path
+   * traversal in the spec or a misconfigured `group.name`.
+   */
+  pathTraversal: 'KUBB_PATH_TRAVERSAL',
+  /**
+   * A post-generate shell hook (`hooks.done`) exited with a failure.
+   */
+  hookFailed: 'KUBB_HOOK_FAILED',
+  /**
+   * The formatter pass over the generated files failed.
+   */
+  formatFailed: 'KUBB_FORMAT_FAILED',
+  /**
+   * The linter pass over the generated files failed.
+   */
+  lintFailed: 'KUBB_LINT_FAILED',
+  /**
+   * Not a failure. Carries a plugin's elapsed time, summed into the run total.
+   */
+  performance: 'KUBB_PERFORMANCE',
+  /**
+   * Not a failure. A newer Kubb version is available on npm.
+   */
+  updateAvailable: 'KUBB_UPDATE_AVAILABLE',
 } as const
+
+/**
+ * Union of the stable {@link diagnosticCode} values.
+ */
+export type DiagnosticCode = (typeof diagnosticCode)[keyof typeof diagnosticCode]

package/src/createAdapter.ts

@@ -1,30 +1,126 @@
-import type { Adapter, AdapterFactoryOptions } from './types.ts'
+import type { PossiblePromise } from '@internals/utils'
+import type { ImportNode, InputNode, InputStreamNode, SchemaNode } from '@kubb/ast'
 
-type AdapterBuilder<T extends AdapterFactoryOptions> = (options: T['options']) => Adapter<T>
+/**
+ * Source data handed to an adapter's `parse` function. Mirrors the config
+ * input shape with paths resolved to absolute.
+ *
+ * - `{ type: 'path' }`: single file on disk.
+ * - `{ type: 'paths' }`: multiple files (e.g. split spec).
+ * - `{ type: 'data' }`: raw string or parsed object provided inline.
+ */
+export type AdapterSource = { type: 'path'; path: string } | { type: 'data'; data: string | unknown } | { type: 'paths'; paths: Array<string> }
 
 /**
- * Factory for implementing custom adapters that translate non-OpenAPI specs into Kubb's AST.
+ * Generic parameters used by `createAdapter` and the resulting `Adapter` type.
  *
- * Use this to support GraphQL schemas, gRPC definitions, AsyncAPI, or custom domain-specific languages.
- * Built-in adapters include `@kubb/adapter-oas` for OpenAPI and Swagger documents.
+ * - `TName`: unique adapter identifier (`'oas'`, `'asyncapi'`, ...).
+ * - `TOptions`: user-facing options accepted by the adapter factory.
+ * - `TResolvedOptions`: options after defaults are applied.
+ * - `TDocument`: type of the parsed source document.
+ */
+export type AdapterFactoryOptions<
+  TName extends string = string,
+  TOptions extends object = object,
+  TResolvedOptions extends object = TOptions,
+  TDocument = unknown,
+> = {
+  name: TName
+  options: TOptions
+  resolvedOptions: TResolvedOptions
+  document: TDocument
+}
+
+/**
+ * Converts input files or inline data into Kubb's universal AST `InputNode`.
  *
- * @note Adapters must parse their input format to Kubb's `InputNode` structure.
+ * Adapters live between the spec format and the plugins. The built-in
+ * `@kubb/adapter-oas` handles OpenAPI 2.0, 3.0, and 3.1; custom adapters can
+ * support GraphQL, gRPC, AsyncAPI, or any domain-specific schema language.
  *
  * @example
  * ```ts
- * export const myAdapter = createAdapter<MyAdapter>((options) => {
- *   return {
- *     name: 'my-adapter',
- *     options,
- *     async parse(source) {
- *       // Transform source format to InputNode
- *       return { ... }
- *     },
- *   }
+ * import { defineConfig } from 'kubb'
+ * import { adapterOas } from '@kubb/adapter-oas'
+ * import { pluginTs } from '@kubb/plugin-ts'
+ *
+ * export default defineConfig({
+ *   input: { path: './petStore.yaml' },
+ *   output: { path: './src/gen' },
+ *   adapter: adapterOas(),
+ *   plugins: [pluginTs()],
  * })
+ * ```
+ */
+export type Adapter<TOptions extends AdapterFactoryOptions = AdapterFactoryOptions> = {
+  /**
+   * Human-readable adapter identifier (e.g. `'oas'`, `'asyncapi'`).
+   */
+  name: TOptions['name']
+  /**
+   * Resolved adapter options after defaults have been applied.
+   */
+  options: TOptions['resolvedOptions']
+  /**
+   * Parsed source document after the first `parse()` call. `null` before parsing.
+   */
+  document: TOptions['document'] | null
+  /**
+   * Parse the source into a universal `InputNode`.
+   */
+  parse: (source: AdapterSource) => PossiblePromise<InputNode>
+  /**
+   * Extract `ImportNode` entries for a schema tree.
+   * Returns an empty array before the first `parse()` call.
+   *
+   * The `resolve` callback receives the collision-corrected schema name and must
+   * return `{ name, path }` for the import, or `undefined` to skip it.
+   */
+  getImports: (node: SchemaNode, resolve: (schemaName: string) => { name: string; path: string }) => Array<ImportNode>
+  /**
+   * Validate the document at the given path or URL.
+   */
+  validate: (input: string, options?: { throwOnError?: boolean }) => Promise<void>
+  /**
+   * Memory-efficient streaming variant of `parse()`.
+   *
+   * Returns an `InputStreamNode` whose `schemas` and `operations` are `AsyncIterable`.
+   * Each `for await` loop creates a fresh parse pass over the cached in-memory document.
+   * No pre-built arrays are held in memory.
+   */
+  stream?: (source: AdapterSource) => Promise<InputStreamNode>
+}
+
+type AdapterBuilder<T extends AdapterFactoryOptions> = (options: T['options']) => Adapter<T>
+
+/**
+ * Defines a custom adapter that translates a spec format into Kubb's universal
+ * AST. Use this when you need to consume GraphQL, gRPC, AsyncAPI, or another
+ * domain-specific schema. Built-in adapters: `@kubb/adapter-oas` for
+ * OpenAPI/Swagger documents.
+ *
+ * Adapters must return an `InputNode` from `parse`. That node is what every
+ * plugin in the build consumes.
+ *
+ * @example
+ * ```ts
+ * import { createAdapter, ast, type AdapterFactoryOptions } from '@kubb/core'
+ *
+ * type MyAdapter = AdapterFactoryOptions<'my-adapter', { validate?: boolean }>
  *
- * // Instantiate:
- * const adapter = myAdapter({ validate: true })
+ * export const myAdapter = createAdapter<MyAdapter>((options) => ({
+ *   name: 'my-adapter',
+ *   options,
+ *   document: null,
+ *   async parse(_source) {
+ *     // Convert `source` (path or inline data) into an InputNode.
+ *     return ast.createInput()
+ *   },
+ *   getImports: () => [],
+ *   async validate() {
+ *     // Throw or call ctx.error here when the spec is invalid.
+ *   },
+ * }))
  * ```
  */
 export function createAdapter<T extends AdapterFactoryOptions = AdapterFactoryOptions>(build: AdapterBuilder<T>): (options?: T['options']) => Adapter<T> {