@kubb/core 5.0.0-beta.36 → 5.0.0-beta.38

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,29 +1,31 @@
-import type { FileNode } from '@kubb/ast'
-
 /**
  * Base URL for the Kubb Studio web app.
  */
 export const DEFAULT_STUDIO_URL = 'https://kubb.studio' as const
 
 /**
- * Default banner style written at the top of every generated file.
+ * Number of file writes to batch in parallel during `flushPendingFiles`.
  */
-export const DEFAULT_BANNER = 'simple' as const
+export const STREAM_FLUSH_EVERY = 50
 
 /**
- * Default file-extension mapping used when no explicit mapping is configured.
+ * Number of schema/operation nodes to dispatch concurrently during generation.
  */
-export const DEFAULT_EXTENSION: Record<FileNode['extname'], FileNode['extname'] | ''> = { '.ts': '.ts' }
+export const SCHEMA_PARALLEL = 8
 
 /**
- * Number of file writes to batch in parallel during `flushPendingFiles`.
+ * 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 STREAM_FLUSH_EVERY = 50
+export const HOOK_LISTENERS_PER_PLUGIN = 4
 
 /**
- * Number of schema/operation nodes to dispatch concurrently during generation.
+ * 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 SCHEMA_PARALLEL = 8
+export const OPERATION_FILTER_TYPES: ReadonlySet<string> = new Set(['tag', 'operationId', 'path', 'method', 'contentType'])
 
 /**
  * Numeric log-level thresholds used internally to compare verbosity.
@@ -36,5 +38,97 @@ export const logLevel = {
   warn: 1,
   info: 3,
   verbose: 4,
-  debug: 5,
 } as const
+
+/**
+ * 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',
+  /**
+   * The `devtools` config is set to something other than an object.
+   */
+  devtoolsInvalid: 'KUBB_DEVTOOLS_INVALID',
+  /**
+   * 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]