@kubb/core 5.10.0 → 5.10.2

package/dist/{Hookable-DBB42ADP.js → Hookable-Bjfoua7Y.js}

@@ -1,12 +1,12 @@
 import "./rolldown-runtime-CRm0XQPb.js";
 import { satisfies } from "verkit";
 import { AsyncLocalStorage } from "node:async_hooks";
-import { styleText } from "node:util";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path, { dirname, isAbsolute, relative, resolve } from "node:path";
+import { stripVTControlCharacters, styleText } from "node:util";
 import { ast, collectImportedRefNames, collectUsedSchemaNames, extractStringsFromNodes } from "@kubb/ast";
 //#region package.json
-var version = "5.10.0";
+var version = "5.10.2";
 //#endregion
 //#region ../../internals/utils/src/casing.ts
 /**
@@ -62,6 +62,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";
@@ -262,375 +291,388 @@ function formatMs(ms) {
 	return `${Math.round(ms)}ms`;
 }
 //#endregion
-//#region src/constants.ts
+//#region src/diagnosticCatalog.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");
-/**
-* 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 ? 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 - 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.
 *
@@ -705,27 +747,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",
@@ -743,7 +795,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
 		};
@@ -751,8 +805,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 } : {}
 		};
 	}
@@ -843,71 +897,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 = styleText(color, styleText("bold", `[${code}]`));
-		const headline = problem?.plugin ? `${tag} ${problem.plugin}: ${message}` : `${tag}: ${message}`;
-		const details = [];
-		if (problem?.location && "pointer" in problem.location) details.push(`  ${styleText("dim", "at:")} ${styleText("cyan", problem.location.pointer)}`);
-		if (problem?.help) details.push(`  ${styleText("cyan", "fix:")} ${problem.help}`);
-		if (code !== diagnosticCode.unknown) details.push(`  ${styleText("dim", "see:")} ${styleText("cyan", Diagnostics.docsUrl(code))}`);
-		if (problem?.issues) details.push(`  ${styleText("dim", "report:")} ${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" }
 	});
@@ -1744,7 +1760,13 @@ async function parseCopy(file, parser) {
 	try {
 		content = await 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(ast.factory.createFile(parser.copy(file, content))));
 	return [
@@ -1986,6 +2008,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;
@@ -2025,9 +2091,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,
@@ -2353,7 +2429,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) => {
@@ -2397,6 +2474,7 @@ var KubbDriver = class {
 					await this.hooks.callHook("kubb:generate:schema", transformedNode, ctx);
 				} catch (caughtError) {
 					state.error = toError(caughtError);
+					state.crashSite = getCrashSite(node);
 				}
 			}
 		}
@@ -2425,6 +2503,7 @@ var KubbDriver = class {
 					}
 				} catch (caughtError) {
 					state.error = toError(caughtError);
+					state.crashSite = getCrashSite(node);
 				}
 			}
 		}
@@ -2453,10 +2532,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
@@ -2531,27 +2618,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
 				});
 			}
 		};
@@ -2691,4 +2788,4 @@ var Hookable = class {
 //#endregion
 export { inParallel as A, useOptions as C, Diagnostics as D, resolveMeta as E, toError as F, camelCase as I, read as M, toPosixPath as N, formatMs as O, write as P, useKubb as S, defineExtension as T, setMacros as _, FileManager as a, tryUseKubb as b, Resolver as c, definePlugin as d, addGenerator as f, requirePlugin as g, kubbContext as h, createNodeCache as i, isPathInside as j, getElapsedMs as k, getInputKind as l, injectFile as m, KubbDriver as n, _usingCtx as o, addMacro as p, pluginNotFoundError as r, createResolver as s, Hookable as t, assertPluginOption as u, setOptions as v, checkCompatibility as w, useConfig as x, setResolver as y };
 
-//# sourceMappingURL=Hookable-DBB42ADP.js.map
+//# sourceMappingURL=Hookable-Bjfoua7Y.js.map