@kubb/core 5.10.0 → 5.10.2

package/dist/{Hookable-XjiJoKGb.cjs → Hookable-RTuEiBd9.cjs}

@@ -26,13 +26,13 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
 //#endregion
 let verkit = require("verkit");
 let node_async_hooks = require("node:async_hooks");
-let node_util = require("node:util");
 let node_fs_promises = require("node:fs/promises");
 let node_path = require("node:path");
 node_path = __toESM(node_path, 1);
+let node_util = require("node:util");
 let _kubb_ast = require("@kubb/ast");
 //#region package.json
-var version = "5.10.0";
+var version = "5.10.2";
 //#endregion
 //#region ../../internals/utils/src/casing.ts
 /**
@@ -88,6 +88,35 @@ function toError(value) {
 function getErrorMessage(value) {
 	return value instanceof Error ? value.message : String(value);
 }
+/**
+* Returns `error` followed by every error in its `cause` chain, outermost first. Stops at a
+* non-`Error` cause or a cycle.
+*
+* @example
+* ```ts
+* getErrorChain(new Error('Config failed loading', { cause: new Error('boom') })).map((error) => error.message)
+* // ['Config failed loading', 'boom']
+* ```
+*/
+function getErrorChain(error) {
+	const chain = [];
+	for (let current = error; current instanceof Error && !chain.includes(current); current = current.cause) chain.push(current);
+	return chain;
+}
+//#endregion
+//#region ../../internals/utils/src/jsonPointer.ts
+/**
+* Escapes a single JSON pointer reference token per RFC 6901 (`~` → `~0`, `/` → `~1`), so a
+* name holding those characters maps to a distinct pointer.
+*
+* @example
+* ```ts
+* escapePointerToken('/pets/{id}') // '~1pets~1{id}'
+* ```
+*/
+function escapePointerToken(token) {
+	return token.replaceAll("~", "~0").replaceAll("/", "~1");
+}
 //#endregion
 //#region ../../internals/utils/src/runtime.ts
 const isBun = typeof Bun !== "undefined";
@@ -288,375 +317,388 @@ function formatMs(ms) {
 	return `${Math.round(ms)}ms`;
 }
 //#endregion
-//#region src/constants.ts
-/**
-* 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.
-*/
-const diagnosticCode = {
-	/**
-	* Fallback for an unstructured error with no specific code.
-	*/
-	unknown: "KUBB_UNKNOWN",
-	/**
-	* The file or URL set as `input` could not be read.
-	*/
-	inputNotFound: "KUBB_INPUT_NOT_FOUND",
-	/**
-	* A URL set as `input` (or referenced by a `$ref`) answered with a 4xx or 5xx status
-	* instead of the document.
-	*/
-	inputRequestFailed: "KUBB_INPUT_REQUEST_FAILED",
-	/**
-	* A URL set as `input` (or referenced by a `$ref`) never answered, so the request failed
-	* before a status was returned.
-	*/
-	inputUnreachable: "KUBB_INPUT_UNREACHABLE",
-	/**
-	* An adapter was configured without an `input`.
-	*/
-	inputRequired: "KUBB_INPUT_REQUIRED",
-	/**
-	* `input` uses the v4 `{ path }` / `{ data }` wrapper, which v5 reads as a parsed
-	* document instead of a pointer to one.
-	*/
-	legacyInput: "KUBB_LEGACY_INPUT",
-	/**
-	* The parsed `input` carries no `openapi` or `swagger` version, so it is not a
-	* document the adapter can read.
-	*/
-	invalidDocument: "KUBB_INVALID_DOCUMENT",
-	/** The document fails OpenAPI schema validation. Reported as a warning. */
-	invalidSpec: "KUBB_INVALID_SPEC",
-	/**
-	* 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",
-	/**
-	* The running Kubb or Node.js version is outside a plugin's `meta.compatibility`.
-	*/
-	incompatibleExtension: "KUBB_INCOMPATIBLE_EXTENSION",
-	/**
-	* A required entry in a plugin's `dependencies` record is missing from the config.
-	*/
-	missingDependency: "KUBB_MISSING_DEPENDENCY",
-	/**
-	* A dependency's `meta.version` is outside the range a plugin's `dependencies` record declares.
-	*/
-	incompatibleDependency: "KUBB_INCOMPATIBLE_DEPENDENCY",
-	/**
-	* A plugin threw while generating.
-	*/
-	pluginFailed: "KUBB_PLUGIN_FAILED",
-	/** An adapter threw while parsing the input. */
-	adapterFailed: "KUBB_ADAPTER_FAILED",
-	/** A parser threw while printing a generated file. */
-	parserFailed: "KUBB_PARSER_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 `kubb/kit` composable was called outside a plugin's `setup` and `kubb:plugin:setup`.
-	*/
-	noContext: "KUBB_NO_CONTEXT",
-	/**
-	* 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",
-	/**
-	* `output.clean` is enabled but `output.path` resolves to the project root or a parent of it,
-	* so cleaning would delete kubb.config and every source file.
-	*/
-	cleanRoot: "KUBB_CLEAN_ROOT",
-	/**
-	* A plugin's options are invalid, for example `output.mode: 'file'` paired with a `group` option.
-	*/
-	invalidPluginOptions: "KUBB_INVALID_PLUGIN_OPTIONS",
-	/**
-	* A post-generate command (`output.postGenerate`) exited with a failure.
-	*/
-	postGenerateFailed: "KUBB_POST_GENERATE_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",
-	/**
-	* A barrel tries to re-export the same name from more than one module.
-	*/
-	barrelDuplicateExport: "KUBB_BARREL_DUPLICATE_EXPORT",
-	/**
-	* 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"
-};
-//#endregion
-//#region src/Diagnostics.ts
-/**
-* Docs major version, derived from the package version so the link tracks the published major.
-*/
-const docsMajor = version.split(".")[0] ?? "5";
-/**
-* Builds a type guard that narrows a {@link Diagnostic} to the variant for `kind`. A diagnostic
-* with no `kind` is treated as a `problem`.
-*/
-function isKind(kind) {
-	return (diagnostic) => (diagnostic.kind ?? "problem") === kind;
-}
-/**
-* Returns `true` when the diagnostic is a build {@link ProblemDiagnostic}.
-*
-* @example
-* ```ts
-* if (isProblem(diagnostic)) {
-*   console.log(diagnostic.location)
-* }
-* ```
-*/
-const isProblem = isKind("problem");
-/**
-* Returns `true` when the diagnostic is a per-plugin {@link PerformanceDiagnostic}.
-*
-* @example
-* ```ts
-* const timings = diagnostics.filter(isPerformance)
-* ```
-*/
-const isPerformance = isKind("performance");
-/**
-* Returns `true` when the diagnostic is a version-update {@link UpdateDiagnostic}.
-*
-* @example
-* ```ts
-* if (isUpdate(diagnostic)) {
-*   console.log(diagnostic.latestVersion)
-* }
-* ```
-*/
-const isUpdate = isKind("update");
+//#region src/diagnosticCatalog.ts
 /**
-* Accent color per severity. The color tints the `[CODE]` tag (red error, yellow warning,
-* blue info).
-*/
-const severityStyle = {
-	error: "red",
-	warning: "yellow",
-	info: "blue"
-};
-const failedCode = {
-	plugin: diagnosticCode.pluginFailed,
-	adapter: diagnosticCode.adapterFailed,
-	parser: diagnosticCode.parserFailed
-};
-const countKey = {
-	error: "errors",
-	warning: "warnings",
-	info: "infos"
-};
-/**
-* Explanation for every {@link diagnosticCode}. Use {@link Diagnostics.explain} to look one up
-* and `Diagnostics.docsUrl` for the matching kubb.dev page.
+* Every diagnostic code with its docs entry: a short title, what triggers it, and how to resolve
+* it. The source of truth for {@link diagnosticCode}, and the kubb.dev `/reference/diagnostics`
+* sections mirror it.
 */
 const diagnosticCatalog = {
-	[diagnosticCode.unknown]: {
+	unknown: {
+		code: "KUBB_UNKNOWN",
 		title: "Unknown error",
 		cause: "An error was thrown without a stable Kubb code, so it is reported as-is.",
 		fix: "Read the underlying message and stack. If it comes from a plugin or adapter, check its configuration; otherwise report it as a possible Kubb bug."
 	},
-	[diagnosticCode.inputNotFound]: {
+	inputNotFound: {
+		code: "KUBB_INPUT_NOT_FOUND",
 		title: "Input not found",
 		cause: "The file set as `input` (or passed as `kubb generate PATH`) could not be read. A URL reports `KUBB_INPUT_REQUEST_FAILED` or `KUBB_INPUT_UNREACHABLE` instead.",
 		fix: "Check that the path exists and is readable, then set it as `input` or pass it on the CLI."
 	},
-	[diagnosticCode.inputRequestFailed]: {
+	inputRequestFailed: {
+		code: "KUBB_INPUT_REQUEST_FAILED",
 		title: "Input request failed",
 		cause: "A URL set as `input` (or reached through a `$ref`) answered with a 4xx or 5xx status instead of the document.",
 		fix: "Open the URL to see what the server returns. A 401 or 403 needs credentials Kubb does not send, so download the document and point `input` at the local file. A 404 means the path is wrong, and a 5xx means the server itself failed."
 	},
-	[diagnosticCode.inputUnreachable]: {
+	inputUnreachable: {
+		code: "KUBB_INPUT_UNREACHABLE",
 		title: "Input unreachable",
 		cause: "A URL set as `input` (or reached through a `$ref`) never answered, so the request failed before a status came back. A refused connection, an unknown host, an expired certificate, and a timeout all land here.",
 		fix: "Check that the host is running and reachable from this machine. For a local server, start it and confirm the port matches the one in `input`."
 	},
-	[diagnosticCode.inputRequired]: {
+	inputRequired: {
+		code: "KUBB_INPUT_REQUIRED",
 		title: "Input required",
 		cause: "An adapter is configured but no `input` was provided.",
 		fix: "Set `input` to a file path, a URL, an inline spec (JSON/YAML string), or a parsed object in your Kubb config."
 	},
-	[diagnosticCode.legacyInput]: {
+	legacyInput: {
+		code: "KUBB_LEGACY_INPUT",
 		title: "Legacy input shape",
 		cause: "`input` is a `{ path }` or `{ data }` wrapper, which v4 used to point at a document and v5 reads as the document itself.",
 		fix: "Unwrap it: `input: { path: \"./petStore.yaml\" }` becomes `input: \"./petStore.yaml\"`, and `input: { data: spec }` becomes `input: spec`."
 	},
-	[diagnosticCode.invalidDocument]: {
+	invalidDocument: {
+		code: "KUBB_INVALID_DOCUMENT",
 		title: "Invalid document",
-		cause: "The parsed `input` has no `openapi` or `swagger` version field, so it is not an OpenAPI or Swagger document.",
-		fix: "Point `input` at a document that declares `openapi` or `swagger`, and check that a passed object is the spec itself rather than a wrapper around it."
+		cause: "The `input` cannot be read as an OpenAPI or Swagger document: its JSON or YAML has a syntax error, it declares no `openapi` or `swagger` version field, or its version cannot be upgraded to OpenAPI 3.1.",
+		fix: "Fix the syntax at the reported line, and check that `input` points at the spec and not an HTML page. Point `input` at a Swagger 2.0, OpenAPI 3.0, or OpenAPI 3.1 document, and check that a passed object is the spec itself rather than a wrapper around it."
 	},
-	[diagnosticCode.invalidSpec]: {
+	invalidSpec: {
+		code: "KUBB_INVALID_SPEC",
 		title: "Invalid spec",
 		cause: "The document does not pass OpenAPI schema validation. Kubb still generates from it, but the output can be incomplete or wrong.",
 		fix: "Fix the reported problem in the spec. Run `kubb validate` to list every error, or set `validate: false` on the adapter to skip the check."
 	},
-	[diagnosticCode.refNotFound]: {
+	refNotFound: {
+		code: "KUBB_REF_NOT_FOUND",
 		title: "Reference not found",
 		cause: "A `$ref` could not be resolved in the source document.",
 		fix: "Add the missing definition (for example under `components.schemas`) or fix the `$ref`. Run `kubb validate` to check the spec."
 	},
-	[diagnosticCode.invalidServerVariable]: {
+	invalidServerVariable: {
+		code: "KUBB_INVALID_SERVER_VARIABLE",
 		title: "Invalid server variable",
 		cause: "A server variable value is not allowed by its `enum`.",
 		fix: "Use one of the values listed in the server variable `enum`, or update the spec."
 	},
-	[diagnosticCode.pluginNotFound]: {
+	pluginNotFound: {
+		code: "KUBB_PLUGIN_NOT_FOUND",
 		title: "Plugin not found",
 		cause: "A plugin that another plugin depends on is missing from the config.",
 		fix: "Add the required plugin to the `plugins` array in kubb.config.ts, or remove the dependency on it."
 	},
-	[diagnosticCode.incompatibleExtension]: {
+	incompatibleExtension: {
+		code: "KUBB_INCOMPATIBLE_EXTENSION",
 		title: "Incompatible extension",
 		cause: "A plugin sets `meta.compatibility.kubb` or `meta.compatibility.node` to a range the running Kubb or Node.js version does not satisfy.",
 		fix: "Upgrade Kubb or Node.js to a version in the range, or install a version of the plugin that supports your current Kubb and Node.js."
 	},
-	[diagnosticCode.missingDependency]: {
+	missingDependency: {
+		code: "KUBB_MISSING_DEPENDENCY",
 		title: "Missing dependency",
 		cause: "A plugin lists another plugin in its `dependencies` record without `optional: true`, and the config does not include it.",
 		fix: "Add the missing plugin to the `plugins` array in kubb.config.ts."
 	},
-	[diagnosticCode.incompatibleDependency]: {
+	incompatibleDependency: {
+		code: "KUBB_INCOMPATIBLE_DEPENDENCY",
 		title: "Incompatible dependency",
 		cause: "A plugin's `dependencies` record sets a `version` range, and the configured plugin's `meta.version` falls outside it.",
 		fix: "Install a version of the dependency inside the range, or a version of the dependent plugin that supports the installed dependency."
 	},
-	[diagnosticCode.pluginFailed]: {
+	pluginFailed: {
+		code: "KUBB_PLUGIN_FAILED",
 		title: "Plugin failed",
 		cause: "A plugin threw while generating, or reported an error through `ctx.error`.",
-		fix: "Read the underlying error and check the plugin options and the schema or operation it failed on. If the plugin crashed, rerun with `--verbose` for the stack trace and report it to the plugin maintainers, at the `report:` link when one is shown."
+		fix: "Check the plugin options and the node at `at:`. If it is a bug, report it with the stack at `report:`."
 	},
-	[diagnosticCode.adapterFailed]: {
+	adapterFailed: {
+		code: "KUBB_ADAPTER_FAILED",
 		title: "Adapter failed",
 		cause: "The adapter threw an unexpected error while parsing the input.",
-		fix: "This is likely a bug in the adapter. Rerun with `--verbose` for the stack trace and report it to the adapter maintainers, at the `report:` link when one is shown."
+		fix: "Check the input and the adapter options. If it is a bug, report it with the stack at `report:`."
 	},
-	[diagnosticCode.parserFailed]: {
+	parserFailed: {
+		code: "KUBB_PARSER_FAILED",
 		title: "Parser failed",
 		cause: "A parser threw an unexpected error while printing a generated file.",
-		fix: "This is likely a bug in the parser. Rerun with `--verbose` for the stack trace and report it to the parser maintainers, at the `report:` link when one is shown."
+		fix: "Check the parser options. If it is a bug, report it with the stack at `report:`."
 	},
-	[diagnosticCode.pluginWarning]: {
+	pluginWarning: {
+		code: "KUBB_PLUGIN_WARNING",
 		title: "Plugin warning",
 		cause: "A plugin reported a non-fatal warning through `ctx.warn`.",
 		fix: "Review the message. It does not fail the build; adjust the plugin options or input if the warning is unwanted."
 	},
-	[diagnosticCode.pluginInfo]: {
+	pluginInfo: {
+		code: "KUBB_PLUGIN_INFO",
 		title: "Plugin info",
 		cause: "A plugin reported an informational message through `ctx.info`.",
 		fix: "Informational only. No action is required."
 	},
-	[diagnosticCode.noContext]: {
+	noContext: {
+		code: "KUBB_NO_CONTEXT",
 		title: "No plugin context",
 		cause: "A `kubb/kit` composable such as `useKubb()` or `addGenerator()` ran outside the `setup` and `kubb:plugin:setup` of a plugin, so there is no plugin to apply it to.",
 		fix: "Call the composable inside `setup` or `kubb:plugin:setup`, including in code that setup awaits."
 	},
-	[diagnosticCode.unsupportedFormat]: {
+	unsupportedFormat: {
+		code: "KUBB_UNSUPPORTED_FORMAT",
 		title: "Unsupported format",
 		cause: "A schema uses a `format` Kubb does not map to a specific type, so it falls back to the base type.",
 		fix: "Use a format Kubb supports, or handle the custom format with a parser or plugin."
 	},
-	[diagnosticCode.deprecated]: {
+	deprecated: {
+		code: "KUBB_DEPRECATED",
 		title: "Deprecated",
 		cause: "A referenced schema or operation is marked `deprecated`.",
 		fix: "Migrate off the deprecated definition if the warning is unwanted."
 	},
-	[diagnosticCode.adapterRequired]: {
+	adapterRequired: {
+		code: "KUBB_ADAPTER_REQUIRED",
 		title: "Adapter required",
 		cause: "An action needs an adapter but none is configured.",
 		fix: "Set `adapter` in kubb.config.ts, for example `adapterOas()`."
 	},
-	[diagnosticCode.pathTraversal]: {
+	pathTraversal: {
+		code: "KUBB_PATH_TRAVERSAL",
 		title: "Path traversal",
 		cause: "A resolved output path escaped the output directory, which can stem from a path traversal in the spec or a misconfigured `group.name`.",
 		fix: "Keep generated paths within the output directory. Review the `group.name` function and the names coming from the spec."
 	},
-	[diagnosticCode.cleanRoot]: {
+	cleanRoot: {
+		code: "KUBB_CLEAN_ROOT",
 		title: "Clean targets the project root",
 		cause: "`output.clean` is enabled and `output.path` resolves to the project root or a parent of it, so cleaning would delete `kubb.config` and every source file.",
 		fix: "Point `output.path` at a subdirectory such as `./src/gen` so clean only removes generated code, or disable `output.clean`."
 	},
-	[diagnosticCode.invalidPluginOptions]: {
+	invalidPluginOptions: {
+		code: "KUBB_INVALID_PLUGIN_OPTIONS",
 		title: "Invalid plugin options",
 		cause: "A plugin was configured with options that cannot be honored, for example `output.mode: 'file'` paired with a `group` option.",
 		fix: "Fix the plugin options. A single-file output has nothing to group, so remove the `group` option or use `output.mode: 'directory'`."
 	},
-	[diagnosticCode.postGenerateFailed]: {
+	postGenerateFailed: {
+		code: "KUBB_POST_GENERATE_FAILED",
 		title: "Post-generate command failed",
 		cause: "A post-generate command (`output.postGenerate`) exited with a non-zero status.",
 		fix: "Check the command is installed and correct, and run it manually to see the error."
 	},
-	[diagnosticCode.formatFailed]: {
+	formatFailed: {
+		code: "KUBB_FORMAT_FAILED",
 		title: "Format failed",
 		cause: "The formatter pass over the generated files failed.",
 		fix: "Check the formatter (oxfmt, biome, or prettier) is installed and its config is valid, then run it manually on the output."
 	},
-	[diagnosticCode.lintFailed]: {
+	lintFailed: {
+		code: "KUBB_LINT_FAILED",
 		title: "Lint failed",
 		cause: "The linter pass over the generated files failed.",
 		fix: "Check the linter (oxlint, biome, or eslint) is installed and its config is valid, then run it manually on the output."
 	},
-	[diagnosticCode.barrelDuplicateExport]: {
+	barrelDuplicateExport: {
+		code: "KUBB_BARREL_DUPLICATE_EXPORT",
 		title: "Duplicate barrel export",
 		cause: "Two generated modules export the same name, so the barrel cannot re-export both.",
 		fix: "Rename one of the colliding declarations, or configure the plugin resolver to produce distinct names."
 	},
-	[diagnosticCode.performance]: {
+	internalError: {
+		code: "KUBB_INTERNAL_ERROR",
+		title: "Internal error",
+		cause: "Kubb hit a state it does not expect. This is a bug in Kubb, not in your config.",
+		fix: "Rerun with `--reporter json` or `--verbose` to get the stack. Then report it at https://github.com/kubb-labs/kubb/issues with the spec and config that trigger it."
+	},
+	performance: {
+		code: "KUBB_PERFORMANCE",
 		title: "Performance",
 		cause: "Not a failure. Records a plugin’s elapsed time, summed into the run total.",
 		fix: "No action. This is an informational metric."
 	},
-	[diagnosticCode.updateAvailable]: {
+	updateAvailable: {
+		code: "KUBB_UPDATE_AVAILABLE",
 		title: "Update available",
 		cause: "A newer Kubb version is published on npm than the one running.",
 		fix: "Update the `@kubb/*` packages, for example `npm install -g @kubb/cli`, to get the latest fixes."
 	}
 };
 /**
+* Stable codes Kubb attaches to a `Diagnostic`, derived from {@link diagnosticCatalog}. Reference
+* these instead of inlining the string at a throw site.
+*/
+const diagnosticCode = Object.fromEntries(Object.entries(diagnosticCatalog).map(([key, { code }]) => [key, code]));
+//#endregion
+//#region src/formatDiagnostic.ts
+/** A problem's `help`, or the catalog fix. `info` gets none: its catalog fix says no action is needed. */
+function getHelp(problem) {
+	if (problem.help || problem.severity === "info") return problem.help;
+	return Diagnostics.explain(problem.code).fix;
+}
+/** The `cause` chain's messages, outermost first, minus those `message` already contains. */
+function getCauses(problem) {
+	return getErrorChain(problem.cause).filter((error) => !problem.message.includes(error.message)).map((error) => error.name === "Error" ? error.message : `${error.name}: ${error.message}`);
+}
+/**
+* Accent color per severity, which paints the icon in the `human` layout (red error, yellow
+* warning, blue info). The code itself stays dim.
+*/
+const severityStyle = {
+	error: "red",
+	warning: "yellow",
+	info: "blue"
+};
+const severityIcon = {
+	error: "✖",
+	warning: "⚠",
+	info: "ℹ"
+};
+/**
+* Codes for a crash, which carry the root cause's stack.
+*/
+const crashCodes = /* @__PURE__ */ new Set([
+	diagnosticCode.unknown,
+	diagnosticCode.internalError,
+	diagnosticCode.pluginFailed,
+	diagnosticCode.adapterFailed,
+	diagnosticCode.parserFailed
+]);
+/**
+* Reduces a diagnostic to its JSON-safe fields plus a `docsUrl`, for machine-readable
+* consumers, with the catalog `title`, `cause`, and fix, and the `cause` error as `causes` and
+* `stack`. Absent optional fields are omitted.
+*/
+function serialize(diagnostic) {
+	const problem = Diagnostics.isProblem(diagnostic) ? diagnostic : void 0;
+	const doc = problem ? Diagnostics.explain(problem.code) : void 0;
+	const help = problem ? getHelp(problem) : void 0;
+	const causes = problem ? getCauses(problem) : [];
+	const stack = problem && crashCodes.has(problem.code) ? getErrorChain(problem.cause).at(-1)?.stack : void 0;
+	return {
+		code: diagnostic.code,
+		severity: diagnostic.severity,
+		message: diagnostic.message,
+		...doc ? {
+			title: doc.title,
+			cause: doc.cause
+		} : {},
+		...problem?.location ? { location: problem.location } : {},
+		...help ? { help } : {},
+		...problem?.plugin ? { plugin: problem.plugin } : {},
+		...problem?.issues ? { issues: problem.issues } : {},
+		...causes.length ? { causes } : {},
+		...stack ? { stack } : {},
+		...diagnostic.code === diagnosticCode.unknown ? {} : { docsUrl: Diagnostics.docsUrl(diagnostic.code) }
+	};
+}
+/**
+* Renders a {@link Diagnostic} as lines: a headline, then indented detail rows. `agent` (the default)
+* prints uncolored labeled rows (`at:`, `why:`, `fix:`, `caused by:`, `stack:` for a crash,
+* `docs:`, `report:`). `human` prints an icon, the bold message, and the code aligned to `width`,
+* with `at`, `fix`, the first cause, and `Learn more` for an error, and one row for a warning.
+* `verbose` adds the full stack.
+*/
+function format(diagnostic, { audience = "agent", verbose = false, width = 0 } = {}) {
+	const { code, severity, message } = diagnostic;
+	const problem = Diagnostics.isProblem(diagnostic) ? diagnostic : void 0;
+	const human = audience === "human";
+	const paint = human ? node_util.styleText : (_format, text) => text;
+	const [firstLine = "", ...rest] = message.split("\n");
+	const pointer = problem?.location && "pointer" in problem.location ? problem.location.pointer : void 0;
+	const help = problem ? getHelp(problem) : void 0;
+	const causes = problem ? getCauses(problem) : [];
+	const crash = problem ? crashCodes.has(problem.code) : false;
+	const frames = (problem && (verbose || !human && crash) ? getErrorChain(problem.cause).at(-1)?.stack : void 0)?.split("\n").slice(1, verbose ? void 0 : 4).map((frame) => `    ${paint("dim", frame.trim())}`);
+	if (!human) {
+		const details = rest.filter((line) => line.trim()).map((line) => `  ${line}`);
+		const row = (label, value) => {
+			if (value) details.push(`  ${label}: ${value}`);
+		};
+		row("at", pointer);
+		if (problem && severity !== "info") row("why", Diagnostics.explain(problem.code).cause);
+		row("fix", help);
+		for (const cause of causes) row("caused by", cause);
+		if (frames?.length) details.push("  stack:", ...frames);
+		if (code !== diagnosticCode.unknown) row("docs", Diagnostics.docsUrl(code));
+		row("report", problem?.issues);
+		return [`${severity} ${code}${problem?.plugin ? ` [${problem.plugin}]` : ""}: ${firstLine}`, ...details];
+	}
+	const left = `${paint(severityStyle[severity], severityIcon[severity])} ${paint("bold", firstLine)}`;
+	const gap = Math.max(2, width - (0, node_util.stripVTControlCharacters)(left).length - code.length);
+	const headline = `${left}${" ".repeat(gap)}${paint("dim", code)}`;
+	const frame = rest.filter((line) => line.trim()).map((line) => `  ${paint("dim", line)}`);
+	const label = (name) => paint("dim", name.length < 4 ? name.padEnd(4) : `${name} `);
+	const rows = [["at", pointer && paint("cyan", pointer)], ["fix", help]];
+	if (severity !== "error") {
+		const first = rows.find(([, value]) => value);
+		return [
+			headline,
+			...frame,
+			...first ? [`  ${label(first[0])} ${first[1]}`] : []
+		];
+	}
+	rows.push(["caused by", causes[0]], ["report", problem?.issues && paint("cyan", problem.issues)]);
+	const details = [...frame, ...rows.flatMap(([name, value]) => value ? [`  ${label(name)} ${value}`] : [])];
+	if (frames?.length) details.push(`  ${paint("dim", "stack")}`, ...frames);
+	if (code !== diagnosticCode.unknown) details.push(`  ${paint("dim", "↳ Learn more")}  ${paint("cyan", Diagnostics.docsUrl(code).replace(/^https:\/\//, ""))}`);
+	return [headline, ...details];
+}
+//#endregion
+//#region src/Diagnostics.ts
+/**
+* Docs major version, derived from the package version so the link tracks the published major.
+*/
+const docsMajor = version.split(".")[0] ?? "5";
+/**
+* Builds a type guard that narrows a {@link Diagnostic} to the variant for `kind`. A diagnostic
+* with no `kind` is treated as a `problem`.
+*/
+function isKind(kind) {
+	return (diagnostic) => (diagnostic.kind ?? "problem") === kind;
+}
+/**
+* Returns `true` when the diagnostic is a build {@link ProblemDiagnostic}.
+*
+* @example
+* ```ts
+* if (isProblem(diagnostic)) {
+*   console.log(diagnostic.location)
+* }
+* ```
+*/
+const isProblem = isKind("problem");
+/**
+* Returns `true` when the diagnostic is a per-plugin {@link PerformanceDiagnostic}.
+*
+* @example
+* ```ts
+* const timings = diagnostics.filter(isPerformance)
+* ```
+*/
+const isPerformance = isKind("performance");
+/**
+* Returns `true` when the diagnostic is a version-update {@link UpdateDiagnostic}.
+*
+* @example
+* ```ts
+* if (isUpdate(diagnostic)) {
+*   console.log(diagnostic.latestVersion)
+* }
+* ```
+*/
+const isUpdate = isKind("update");
+const failedCode = {
+	plugin: diagnosticCode.pluginFailed,
+	adapter: diagnosticCode.adapterFailed,
+	parser: diagnosticCode.parserFailed
+};
+const docsByCode = new Map(Object.values(diagnosticCatalog).map((doc) => [doc.code, doc]));
+const countKey = {
+	error: "errors",
+	warning: "warnings",
+	info: "infos"
+};
+/**
 * Static helpers for working with {@link Diagnostic}s, plus the run-scoped sink
 * that lets deep code report a diagnostic without threading a callback.
 *
@@ -731,27 +773,37 @@ var Diagnostics = class Diagnostics {
 		return true;
 	}
 	/**
-	* Emits a diagnostic on the run's `kubb:diagnostic` hook so the loggers render it live.
-	* Use it instead of calling `hooks.callHook('kubb:diagnostic', ...)` directly. To collect a
-	* diagnostic into the build result from deep in a run, use {@link Diagnostics.report} instead.
+	* Emits a diagnostic, or any thrown value, on the run's hooks so the loggers render it live.
+	* A coded problem or an update goes to `kubb:diagnostic`. An uncoded one goes to `kubb:error`
+	* whole, so every wrapper's message, its help, and the stack survive. To collect a diagnostic into
+	* the build result from deep in a run, use {@link Diagnostics.report} instead.
 	*/
-	static async emit(hooks, diagnostic) {
-		await hooks.callHook("kubb:diagnostic", { diagnostic });
+	static async emit(hooks, value) {
+		const thrown = value instanceof Error || typeof value?.code !== "string";
+		const diagnostic = thrown ? Diagnostics.from(value) : value;
+		if (!isProblem(diagnostic) || diagnostic.code !== diagnosticCode.unknown) {
+			await hooks.callHook("kubb:diagnostic", { diagnostic });
+			return;
+		}
+		const { cause, help, message } = diagnostic;
+		const bare = cause && !help && cause.message === message;
+		await hooks.callHook("kubb:error", { error: thrown ? toError(value) : bare ? cause : new Diagnostics.Error(diagnostic) });
 	}
 	/**
 	* Coerces any thrown value into a {@link ProblemDiagnostic}. A {@link Diagnostics.Error}
 	* keeps its structured data, and anything else becomes a `KUBB_UNKNOWN` error.
 	*/
 	static from(error) {
-		const seen = /* @__PURE__ */ new Set();
-		let current = error;
-		let root;
-		while (current instanceof Error && !seen.has(current)) {
-			if (Diagnostics.isError(current)) return current.diagnostic;
-			seen.add(current);
-			root = current;
-			current = current.cause;
+		const chain = getErrorChain(error);
+		const coded = chain.findLast((current) => Diagnostics.isError(current));
+		if (coded) {
+			const { diagnostic } = coded;
+			return diagnostic.cause || !crashCodes.has(diagnostic.code) ? diagnostic : {
+				...diagnostic,
+				cause: coded
+			};
 		}
+		const root = chain.at(-1);
 		return {
 			code: diagnosticCode.unknown,
 			severity: "error",
@@ -769,7 +821,9 @@ var Diagnostics = class Diagnostics {
 		const diagnostic = Diagnostics.from(error);
 		const name = extension.meta?.name ?? extension.name;
 		const owner = kind === "plugin" ? { plugin: diagnostic.plugin ?? name } : {};
-		if (diagnostic.code !== diagnosticCode.unknown || diagnostic.cause?.name === "AbortError") return {
+		const crashed = diagnostic.code === diagnosticCode.unknown && diagnostic.cause?.name !== "AbortError";
+		const failed = Object.values(failedCode).includes(diagnostic.code);
+		if (!crashed && !failed) return {
 			...diagnostic,
 			...owner
 		};
@@ -777,8 +831,8 @@ var Diagnostics = class Diagnostics {
 		return {
 			...diagnostic,
 			...owner,
-			code: failedCode[kind],
-			message: kind === "plugin" ? diagnostic.message : `${kind} "${name}" crashed: ${diagnostic.message}`,
+			code: crashed ? failedCode[kind] : diagnostic.code,
+			message: crashed && kind !== "plugin" ? `${kind} "${name}" crashed: ${diagnostic.message}` : diagnostic.message,
 			...issues ? { issues } : {}
 		};
 	}
@@ -869,71 +923,33 @@ var Diagnostics = class Diagnostics {
 	* `/reference/diagnostics#<slug>` section.
 	*/
 	static explain(code) {
-		return diagnosticCatalog[code];
+		return docsByCode.get(code);
 	}
 	/**
 	* Reduces a diagnostic to its JSON-safe fields plus a `docsUrl`, for machine-readable
-	* consumers. The `cause`, `kind`, and `duration` are dropped, and absent optional
-	* fields are omitted rather than set to `undefined`.
+	* consumers, with the catalog `title`, `cause`, and fix, and the `cause` error as `causes` and
+	* `stack`. Absent optional fields are omitted.
 	*/
-	static serialize(diagnostic) {
-		const problem = isProblem(diagnostic) ? diagnostic : void 0;
-		return {
-			code: diagnostic.code,
-			severity: diagnostic.severity,
-			message: diagnostic.message,
-			...problem?.location ? { location: problem.location } : {},
-			...problem?.help ? { help: problem.help } : {},
-			...problem?.plugin ? { plugin: problem.plugin } : {},
-			...problem?.issues ? { issues: problem.issues } : {},
-			...diagnostic.code === diagnosticCode.unknown ? {} : { docsUrl: Diagnostics.docsUrl(diagnostic.code) }
-		};
-	}
-	/**
-	* Renders a {@link Diagnostic} for terminal output as its parts: the `headline`
-	* (`[CODE] plugin: message`, with the code in the severity color) and the indented `details`
-	* rows (`at:` pointer, `fix:` help, `see:` docs link, `report:` issue tracker).
-	*
-	* Hosts compose these to fit their gutter: a clack logger passes `[headline, ...details]` as the
-	* message with no gutter symbol, while plain text outputs use {@link Diagnostics.formatLines}.
-	*/
-	static format(diagnostic) {
-		const { code, severity, message } = diagnostic;
-		const color = severityStyle[severity];
-		const problem = isProblem(diagnostic) ? diagnostic : void 0;
-		const tag = (0, node_util.styleText)(color, (0, node_util.styleText)("bold", `[${code}]`));
-		const headline = problem?.plugin ? `${tag} ${problem.plugin}: ${message}` : `${tag}: ${message}`;
-		const details = [];
-		if (problem?.location && "pointer" in problem.location) details.push(`  ${(0, node_util.styleText)("dim", "at:")} ${(0, node_util.styleText)("cyan", problem.location.pointer)}`);
-		if (problem?.help) details.push(`  ${(0, node_util.styleText)("cyan", "fix:")} ${problem.help}`);
-		if (code !== diagnosticCode.unknown) details.push(`  ${(0, node_util.styleText)("dim", "see:")} ${(0, node_util.styleText)("cyan", Diagnostics.docsUrl(code))}`);
-		if (problem?.issues) details.push(`  ${(0, node_util.styleText)("dim", "report:")} ${(0, node_util.styleText)("cyan", problem.issues)}`);
-		return {
-			headline,
-			details
-		};
-	}
+	static serialize = serialize;
 	/**
-	* The self-contained block form of {@link Diagnostics.format}: the `headline` followed by the
-	* indented detail rows. Used where there is no gutter (plain and file output).
+	* Renders a diagnostic as lines for an `agent` (the default) or a `human`. See {@link format}.
 	*/
-	static formatLines(diagnostic) {
-		const { headline, details } = Diagnostics.format(diagnostic);
-		return [headline, ...details];
-	}
+	static format = format;
 };
 //#endregion
 //#region src/defineExtension.ts
 /**
 * Returns `meta`, or `{ name }` for an extension that only sets the deprecated `name`. Throws `KUBB_INVALID_PLUGIN_OPTIONS` when it has neither.
 */
-function resolveMeta({ name, meta }) {
+function resolveMeta(extension) {
+	const { name, meta } = extension;
 	if (meta) return meta;
 	if (name) return { name };
+	const keys = Object.keys(extension);
 	throw new Diagnostics.Error({
 		code: Diagnostics.code.invalidPluginOptions,
 		severity: "error",
-		message: "An extension has neither `meta.name` nor `name`.",
+		message: `An extension has neither \`meta.name\` nor \`name\`. Received keys: ${keys.length ? keys.join(", ") : "none"}.`,
 		help: "Set `meta: { name }` on the plugin or parser.",
 		location: { kind: "config" }
 	});
@@ -1770,7 +1786,13 @@ async function parseCopy(file, parser) {
 	try {
 		content = await (0, node_fs_promises.readFile)(file.copy, "utf8");
 	} catch (err) {
-		throw new Error(`[kubb] Could not copy file into output: ${file.copy}`, { cause: err });
+		throw new Diagnostics.Error({
+			code: Diagnostics.code.pluginFailed,
+			severity: "error",
+			message: `Could not copy file into output: ${file.copy}`,
+			help: "Check that the file a plugin copies into the output exists and is readable.",
+			cause: toError(err)
+		});
 	}
 	if (parser?.copy) return runParser(parser, () => parser.parse(_kubb_ast.ast.factory.createFile(parser.copy(file, content))));
 	return [
@@ -2012,6 +2034,50 @@ function normalizePluginOptions(rawOptions, pluginName) {
 	});
 	return options;
 }
+/**
+* Throws `KUBB_INVALID_PLUGIN_OPTIONS` when a `plugins` entry is not a plugin object, such as a
+* factory passed without calling it.
+*/
+function assertPluginEntry(entry, index) {
+	if (typeof entry === "function") {
+		const name = entry.name || "pluginName";
+		throw new Diagnostics.Error({
+			code: Diagnostics.code.invalidPluginOptions,
+			severity: "error",
+			message: `plugins[${index}] is a function ("${name}"), not a plugin.`,
+			help: `Call it: ${name}()`,
+			location: { kind: "config" }
+		});
+	}
+	if (typeof entry !== "object" || entry === null) throw new Diagnostics.Error({
+		code: Diagnostics.code.invalidPluginOptions,
+		severity: "error",
+		message: `plugins[${index}] is ${entry === null ? "null" : typeof entry}, not a plugin.`,
+		help: "Pass the result of a plugin factory, for example `pluginTs()`, or remove the entry.",
+		location: { kind: "config" }
+	});
+}
+/**
+* Where a generator crashed: a label naming the node and, when the node has one, a JSON pointer
+* to it. Built from the node fields so core stays adapter-agnostic.
+*/
+function getCrashSite(node) {
+	if (node.kind === "Schema") return node.name ? {
+		label: `schema "${node.name}"`,
+		location: {
+			kind: "schema",
+			pointer: `#/components/schemas/${escapePointerToken(node.name)}`
+		}
+	} : { label: "an inline schema" };
+	if (!node.method || !node.path) return { label: `operation "${node.operationId}"` };
+	return {
+		label: `operation "${node.operationId}" (${node.method.toUpperCase()} ${node.path})`,
+		location: {
+			kind: "operation",
+			pointer: `#/paths/${escapePointerToken(node.path)}/${node.method.toLowerCase()}`
+		}
+	};
+}
 var KubbDriver = class {
 	config;
 	options;
@@ -2051,9 +2117,19 @@ var KubbDriver = class {
 	async setup() {
 		this.options.signal?.throwIfAborted();
 		for (const extension of [this.config.adapter, ...this.config.parsers]) if (extension?.meta) checkCompatibility(extension.meta);
-		const normalized = this.#sortPlugins(this.config.plugins.map((rawPlugin) => {
+		const names = /* @__PURE__ */ new Set();
+		const normalized = this.#sortPlugins(this.config.plugins.map((rawPlugin, index) => {
+			assertPluginEntry(rawPlugin, index);
 			if (rawPlugin.meta) checkCompatibility(rawPlugin.meta);
 			const meta = resolveMeta(rawPlugin);
+			if (names.has(meta.name)) throw new Diagnostics.Error({
+				code: Diagnostics.code.invalidPluginOptions,
+				severity: "error",
+				message: `Plugin "${meta.name}" appears twice in \`plugins\`.`,
+				help: "Remove the duplicate, or merge its options.",
+				location: { kind: "config" }
+			});
+			names.add(meta.name);
 			return {
 				name: meta.name,
 				meta,
@@ -2379,7 +2455,8 @@ var KubbDriver = class {
 				operationGenerators: generators.filter((generator) => generator.operation),
 				operationsGenerators: generators.filter((generator) => generator.operations),
 				pluginOperations: [],
-				error: null
+				error: null,
+				crashSite: void 0
 			};
 		});
 		const resolveForPlugin = (state, node) => {
@@ -2423,6 +2500,7 @@ var KubbDriver = class {
 					await this.hooks.callHook("kubb:generate:schema", transformedNode, ctx);
 				} catch (caughtError) {
 					state.error = toError(caughtError);
+					state.crashSite = getCrashSite(node);
 				}
 			}
 		}
@@ -2451,6 +2529,7 @@ var KubbDriver = class {
 					}
 				} catch (caughtError) {
 					state.error = toError(caughtError);
+					state.crashSite = getCrashSite(node);
 				}
 			}
 		}
@@ -2479,10 +2558,18 @@ var KubbDriver = class {
 				success: !state.error,
 				error: state.error ?? void 0
 			});
-			if (state.error) diagnostics.push(Diagnostics.fromExtension(state.error, {
-				kind: "plugin",
-				extension: state.plugin
-			}));
+			if (state.error) {
+				const diagnostic = Diagnostics.fromExtension(state.error, {
+					kind: "plugin",
+					extension: state.plugin
+				});
+				const site = diagnostic.code === Diagnostics.code.pluginFailed && !diagnostic.location ? state.crashSite : void 0;
+				diagnostics.push(site ? {
+					...diagnostic,
+					message: `While generating ${site.label}: ${diagnostic.message}`,
+					...site.location ? { location: site.location } : {}
+				} : diagnostic);
+			}
 			diagnostics.push(Diagnostics.performance({
 				plugin: state.plugin.name,
 				duration
@@ -2557,27 +2644,37 @@ var KubbDriver = class {
 			get resolver() {
 				return driver.getResolver(plugin.name);
 			},
-			warn(message) {
+			warn(message, options) {
 				report({
 					code: Diagnostics.code.pluginWarning,
 					severity: "warning",
-					message
+					message,
+					...options
 				});
 			},
-			error(error) {
+			error(error, options) {
+				if (Diagnostics.isError(error)) {
+					report({
+						...options,
+						...error.diagnostic
+					});
+					return;
+				}
 				const cause = typeof error === "string" ? void 0 : error;
 				report({
 					code: Diagnostics.code.pluginFailed,
 					severity: "error",
 					message: typeof error === "string" ? error : error.message,
-					cause
+					cause,
+					...options
 				});
 			},
-			info(message) {
+			info(message, options) {
 				report({
 					code: Diagnostics.code.pluginInfo,
 					severity: "info",
-					message
+					message,
+					...options
 				});
 			}
 		};
@@ -2944,4 +3041,4 @@ Object.defineProperty(exports, "write", {
 	}
 });
 
-//# sourceMappingURL=Hookable-XjiJoKGb.cjs.map
+//# sourceMappingURL=Hookable-RTuEiBd9.cjs.map