@wolfstar/http-framework 4.0.2 → 5.0.0-next-20260919094537

package/dist/esm/auto-imports.d.ts

@@ -1,4 +1,4 @@
-import { l as ResolvedImportsConfig } from "./resolve-CBovxOO3.js";
+import { l as ResolvedImportsConfig } from "./resolve-Blb-IcFd.js";
 import unplugin from "unimport/unplugin";
 //#region src/auto-imports.d.ts
 export interface AutoImportsPluginOptions extends Pick<ResolvedImportsConfig, 'dirs' | 'presets' | 'exclude' | 'dts'> {

package/dist/esm/config.d.ts

@@ -1,2 +1,2 @@
-import { A as StarsTypecheckConfig, B as LoadConfigFileOptions, C as StarsExperimentalConfig, D as StarsNitroConfig, E as StarsImportsConfig, F as loadStarsConfig, H as discoverConfigFile, I as ConfigError, L as ConfigErrorOptions, M as StarsViteConfig, N as defineConfig, O as StarsTsdownConfig, P as LoadStarsConfigOptions, R as CONFIG_EXTENSIONS, S as StarsDevConfig, T as StarsI18nCodegenConfig, U as loadConfigFile, V as LoadedConfigFile, _ as StarsBuildConfig, a as ResolvedDevConfig, b as StarsCompatibilityVersion, c as ResolvedI18nCodegenConfig, d as ResolvedStarsConfig, f as ResolvedTunnelConfig, g as resolveStarsConfig, h as readProjectEnvFiles, i as ResolvedCodegenConfig, j as StarsTypechecker, k as StarsTunnelConfig, l as ResolvedImportsConfig, m as displayPath, n as ResolveConfigOptions, o as ResolvedExperimentalConfig, p as ResolvedTypecheckConfig, r as ResolvedBuildConfig, s as ResolvedFutureConfig, t as PackageJsonLike, u as ResolvedNitroConfig, v as StarsBuildTool, w as StarsFutureConfig, x as StarsConfig, y as StarsCodegenConfig, z as CONFIG_FILE_NAMES } from "./resolve-CBovxOO3.js";
-export { CONFIG_EXTENSIONS, CONFIG_FILE_NAMES, ConfigError, type ConfigErrorOptions, type LoadConfigFileOptions, LoadStarsConfigOptions, type LoadedConfigFile, type PackageJsonLike, type ResolveConfigOptions, type ResolvedBuildConfig, type ResolvedCodegenConfig, type ResolvedDevConfig, type ResolvedExperimentalConfig, type ResolvedFutureConfig, type ResolvedI18nCodegenConfig, type ResolvedImportsConfig, type ResolvedNitroConfig, type ResolvedStarsConfig, type ResolvedTunnelConfig, type ResolvedTypecheckConfig, StarsBuildConfig, StarsBuildTool, StarsCodegenConfig, StarsCompatibilityVersion, StarsConfig, StarsDevConfig, StarsExperimentalConfig, StarsFutureConfig, StarsI18nCodegenConfig, StarsImportsConfig, StarsNitroConfig, StarsTsdownConfig, StarsTunnelConfig, StarsTypecheckConfig, StarsTypechecker, StarsViteConfig, defineConfig, discoverConfigFile, displayPath, loadConfigFile, loadStarsConfig, readProjectEnvFiles, resolveStarsConfig };
+import { A as StarsTypecheckConfig, B as LoadConfigFileOptions, C as StarsExperimentalConfig, D as StarsNitroConfig, E as StarsImportsConfig, F as loadStarsConfig, H as discoverConfigFile, I as ConfigDiagnosticCode, L as configDiagnostics, M as StarsViteConfig, N as defineConfig, O as StarsTsdownConfig, P as LoadStarsConfigOptions, R as CONFIG_EXTENSIONS, S as StarsDevConfig, T as StarsI18nCodegenConfig, U as loadConfigFile, V as LoadedConfigFile, _ as StarsBuildConfig, a as ResolvedDevConfig, b as StarsCompatibilityVersion, c as ResolvedI18nCodegenConfig, d as ResolvedStarsConfig, f as ResolvedTunnelConfig, g as resolveStarsConfig, h as readProjectEnvFiles, i as ResolvedCodegenConfig, j as StarsTypechecker, k as StarsTunnelConfig, l as ResolvedImportsConfig, m as displayPath, n as ResolveConfigOptions, o as ResolvedExperimentalConfig, p as ResolvedTypecheckConfig, r as ResolvedBuildConfig, s as ResolvedFutureConfig, t as PackageJsonLike, u as ResolvedNitroConfig, v as StarsBuildTool, w as StarsFutureConfig, x as StarsConfig, y as StarsCodegenConfig, z as CONFIG_FILE_NAMES } from "./resolve-Blb-IcFd.js";
+export { CONFIG_EXTENSIONS, CONFIG_FILE_NAMES, type ConfigDiagnosticCode, type LoadConfigFileOptions, LoadStarsConfigOptions, type LoadedConfigFile, type PackageJsonLike, type ResolveConfigOptions, type ResolvedBuildConfig, type ResolvedCodegenConfig, type ResolvedDevConfig, type ResolvedExperimentalConfig, type ResolvedFutureConfig, type ResolvedI18nCodegenConfig, type ResolvedImportsConfig, type ResolvedNitroConfig, type ResolvedStarsConfig, type ResolvedTunnelConfig, type ResolvedTypecheckConfig, StarsBuildConfig, StarsBuildTool, StarsCodegenConfig, StarsCompatibilityVersion, StarsConfig, StarsDevConfig, StarsExperimentalConfig, StarsFutureConfig, StarsI18nCodegenConfig, StarsImportsConfig, StarsNitroConfig, StarsTsdownConfig, StarsTunnelConfig, StarsTypecheckConfig, StarsTypechecker, StarsViteConfig, configDiagnostics, defineConfig, discoverConfigFile, displayPath, loadConfigFile, loadStarsConfig, readProjectEnvFiles, resolveStarsConfig };

package/dist/esm/config.js

@@ -1,29 +1,132 @@
-import { t as _defineProperty } from "./defineProperty-DeZQsruP.js";
 import { basename, dirname, extname, isAbsolute, join, relative, resolve } from "node:path";
 import { existsSync, readFileSync, statSync } from "node:fs";
+import { defineDiagnostics } from "nostics";
 
 //#region src/lib/config/errors.ts
 /**
-* A `stars.config.*` error: an invalid option, or a file that failed to load or parse.
+* Structured, stable diagnostic codes for every way a `stars.config.*` can fail to load or validate.
 *
-* This is a plain data error (no exit code or terminal formatting) so it stays meaningful outside a CLI, e.g. for a
-* dashboard or test that calls {@link loadStarsConfig} directly. `@wolfstar/cli` maps it to exit code `2` and renders
-* `message`, `path`, `file` and `hint` for the terminal.
+* This is a plain data error (no exit code or terminal formatting), so nothing here reports anywhere on its own —
+* `reporters` stays empty and each call only builds and returns a `Diagnostic`. That keeps it meaningful outside a
+* CLI, e.g. for a dashboard or test that calls {@link loadStarsConfig} directly; `@wolfstar/cli` is what renders it
+* and picks an exit code (`exitCodeOf`).
+*
+* The `sources` field (populated with the configuration file, when there is one) carries the "which file" grounding
+* `ConfigError` used to expose as `.file`; the "which option" grounding it exposed as `.path` is folded directly into
+* every `why`/`fix` message instead, the way every other diagnostic code already reads.
+*
+* `why` and `fix` are always given the same, fully-typed params object (even when one of them ignores part of it):
+* a bare `() => value` loses nostics' param-type inference (a zero-arg function widens to `unknown` params), so every
+* entry here spells out its shape on both sides instead.
 */
-var ConfigError = class extends Error {
-	constructor(message, options) {
-		super(message, options.cause === void 0 ? void 0 : { cause: options.cause });
-		_defineProperty(this, "code", void 0);
-		_defineProperty(this, "hint", void 0);
-		_defineProperty(this, "path", void 0);
-		_defineProperty(this, "file", void 0);
-		this.name = "ConfigError";
-		this.code = options.code;
-		this.hint = options.hint ?? null;
-		this.path = options.path ?? null;
-		this.file = options.file ?? null;
+const configDiagnostics = defineDiagnostics({
+	docsBase: (code) => `https://stars-components.js.org/docs/config/errors#${code.toLowerCase()}`,
+	reporters: [],
+	codes: {
+		ROOT_NOT_FOUND: {
+			why: (p) => `The project root does not exist: ${p.root}`,
+			fix: (_p) => "Point `root` to an existing directory, relative to the configuration file."
+		},
+		PACKAGE_JSON_INVALID: {
+			why: (p) => `Failed to parse ${p.file}: ${p.message}`,
+			fix: (_p) => "Fix the JSON syntax of the package.json file."
+		},
+		ENTRY_NOT_FOUND: {
+			why: (p) => `The entry file does not exist: ${p.entry}`,
+			fix: (_p) => "Point `entry` to the file that starts the bot, relative to the project root."
+		},
+		ENTRY_DEFAULT_NOT_FOUND: {
+			why: (p) => `Could not find the entry file in ${p.root}`,
+			fix: (p) => `Set \`entry\` in the configuration, or create one of ${p.defaults}.`
+		},
+		INVALID_BUILD_TOOL: {
+			why: (p) => `Unknown build tool "${p.tool}"`,
+			fix: (_p) => "Use one of 'tsdown', 'tsc', 'vite', 'none' or 'auto'."
+		},
+		EXPERIMENTAL_BUILD_TOOL: {
+			why: (p) => `The '${p.tool}' build tool is experimental`,
+			fix: (p) => `Set \`${p.flag}\` to true to use it.`
+		},
+		BUILD_TOOL_REQUIRED: {
+			why: (p) => `The entry ${p.entry} is TypeScript but the build tool is 'none'`,
+			fix: (_p) => "Set `build.tool` to 'tsdown' or 'tsc', or point `entry` to a JavaScript file."
+		},
+		TSCONFIG_EXPLICIT_NOT_FOUND: {
+			why: (p) => `The tsconfig file does not exist: ${p.tsconfig}`,
+			fix: (p) => `Point \`${p.path}\` to an existing tsconfig.json, relative to the project root.`
+		},
+		TSCONFIG_NOT_FOUND: {
+			why: (p) => `Could not find a tsconfig.json in ${p.root}`,
+			fix: (p) => `Create src/tsconfig.json or tsconfig.json, or set \`${p.suggestion}\`.`
+		},
+		TSDOWN_OPTIONS_REQUIRE_TSDOWN: {
+			why: (_p) => "`tsdown` options need the `tsdown` build tool",
+			fix: (p) => `Set \`build.tool\` to 'tsdown', or remove \`tsdown\` (the build tool is '${p.tool}').`
+		},
+		VITE_OPTIONS_REQUIRE_VITE: {
+			why: (_p) => "`vite` options need the `vite` build tool",
+			fix: (p) => `Set \`build.tool\` to 'vite' with \`experimental.enableVite\`, or remove \`vite\` (the build tool is '${p.tool}').`
+		},
+		TSDOWN_CONFIG_FILE_UNSUPPORTED: {
+			why: (p) => `\`${p.file}\` is not used with compatibility version ${p.version}`,
+			fix: (p) => `Move its options into \`tsdown\` here, drop the ${p.file} configuration, or set \`future.compatibilityVersion\` to ${p.legacyVersion}.`
+		},
+		INVALID_TYPE: {
+			why: (p) => `\`${p.path}\` must be ${p.expected}, received ${describeValue(p.value)}`,
+			fix: (p) => p.fix
+		},
+		INVALID_COMPATIBILITY_VERSION: {
+			why: (p) => `Unknown compatibility version ${describeValue(p.value)}`,
+			fix: (p) => `Use ${p.legacyVersion} for the legacy build pipeline or ${p.latestVersion} for today's defaults.`
+		},
+		UNKNOWN_OPTION: {
+			why: (p) => `Unknown option \`${p.path}\``,
+			fix: (p) => `Known options${p.parent ? ` of \`${p.parent}\`` : ""}: ${p.known}.`
+		},
+		EXPERIMENT_REQUIRED: {
+			why: (p) => `\`${p.path}\` needs \`${p.requires}\``,
+			fix: (p) => `Set \`${p.requires}\` to true as well, or drop \`${p.drop}\`.`
+		},
+		IMPORTS_REQUIRE_TSDOWN: {
+			why: (_p) => "`imports` requires the `tsdown` build tool",
+			fix: (_p) => "Set `build.tool` to 'tsdown', or remove `imports`/set it to `false`."
+		},
+		LOCALES_NOT_FOUND: {
+			why: (p) => `The locales directory does not exist: ${p.locales}`,
+			fix: (_p) => "Point `codegen.i18n.locales` to the base locale directory, relative to the project root."
+		},
+		INVALID_URL: {
+			why: (p) => `Invalid URL "${p.url}"`,
+			fix: (p) => p.fix
+		},
+		TUNNEL_URL_NOT_HTTPS: {
+			why: (p) => `The tunnel URL must be https, received "${p.url}"`,
+			fix: (_p) => "Discord only accepts an https interactions endpoint."
+		},
+		INVALID_TYPECHECKER: {
+			why: (p) => `Unknown type checker "${p.checker}"`,
+			fix: (_p) => "Use one of 'tsc', 'golar', 'tsz' or 'auto'."
+		},
+		CONFIG_NOT_FOUND: {
+			why: (p) => `Configuration file not found: ${p.file}`,
+			fix: (p) => `Pass an existing file to --config, or create one of ${p.names} in ${p.cwd}.`
+		},
+		CONFIG_LOAD_FAILED: {
+			why: (p) => `Failed to load the configuration: ${p.message}`,
+			fix: (_p) => "The file must be valid TypeScript/JavaScript and export the configuration as its default export."
+		},
+		CONFIG_NOT_OBJECT: {
+			why: (_p) => "The configuration file must export an object as its default export.",
+			fix: (_p) => "Use `export default defineConfig({ ... })` from '@wolfstar/http-framework/config'."
+		}
 	}
-};
+});
+function describeValue(value) {
+	if (value === null) return "null";
+	if (Array.isArray(value)) return "an array";
+	if (typeof value === "string") return `"${value}"`;
+	return typeof value === "object" ? "an object" : `${typeof value} ${String(value)}`;
+}
 
 //#endregion
 //#region src/lib/config/load.ts
@@ -55,9 +158,10 @@ async function loadConfigFile(options) {
 	let file;
 	if (options.configFile) {
 		file = resolve(cwd, options.configFile);
-		if (!isFile$1(file)) throw new ConfigError(`Configuration file not found: ${file}`, {
-			code: "CONFIG_NOT_FOUND",
-			hint: `Pass an existing file to --config, or create one of ${CONFIG_FILE_NAMES.join(", ")} in ${cwd}.`
+		if (!isFile$1(file)) throw configDiagnostics.CONFIG_NOT_FOUND({
+			file,
+			cwd,
+			names: CONFIG_FILE_NAMES.join(", ")
 		});
 	} else {
 		file = discoverConfigFile(cwd);
@@ -83,18 +187,13 @@ async function loadConfigFile(options) {
 		loaded = layer ? layer.config : result.config;
 	} catch (error) {
 		const message = error instanceof Error ? error.message : String(error);
-		throw new ConfigError(`Failed to load the configuration: ${message}`, {
-			code: "CONFIG_LOAD_FAILED",
-			file,
-			hint: "The file must be valid TypeScript/JavaScript and export the configuration as its default export.",
-			cause: error
+		throw configDiagnostics.CONFIG_LOAD_FAILED({
+			message,
+			cause: error,
+			sources: [file]
 		});
 	}
-	if (loaded === null || typeof loaded !== "object" || Array.isArray(loaded)) throw new ConfigError("The configuration file must export an object as its default export.", {
-		code: "CONFIG_NOT_OBJECT",
-		file,
-		hint: "Use `export default defineConfig({ ... })` from '@wolfstar/http-framework/config'."
-	});
+	if (loaded === null || typeof loaded !== "object" || Array.isArray(loaded)) throw configDiagnostics.CONFIG_NOT_OBJECT({ sources: [file] });
 	return {
 		configFile: file,
 		config: loaded
@@ -174,7 +273,7 @@ const TYPESCRIPT_EXTENSIONS = /* @__PURE__ */ new Set([
 /**
 * Applies defaults, validates every option and resolves all paths to absolute ones.
 *
-* @throws {ConfigError} with an actionable `hint` on the first invalid option.
+* @throws {Diagnostic} (from `nostics`, via {@link configDiagnostics}) with an actionable `fix` on the first invalid option.
 */
 function resolveStarsConfig(options) {
 	const cwd = resolve(options.cwd);
@@ -196,8 +295,8 @@ function resolveStarsConfig(options) {
 	]);
 	const baseDirectory = file ? dirname(file) : cwd;
 	const root = resolve(baseDirectory, validator.string(config.root, "root") ?? ".");
-	if (!isDirectory(root)) throw validator.error(`The project root does not exist: ${root}`, "root", "ROOT_NOT_FOUND", "Point `root` to an existing directory, relative to the configuration file.");
-	const packageJson = readPackageJson(root);
+	if (!isDirectory(root)) throw validator.error(configDiagnostics.ROOT_NOT_FOUND, { root });
+	const packageJson = readPackageJson(root, validator);
 	const experimental = resolveExperimental(config.experimental ?? {}, validator);
 	const future = resolveFuture(config.future ?? {}, validator);
 	const entry = resolveEntry(root, validator.string(config.entry, "entry"), validator);
@@ -207,8 +306,8 @@ function resolveStarsConfig(options) {
 	const dev = resolveDev(root, entry, packageJson, config.dev ?? {}, env, validator);
 	const codegen = resolveCodegen(root, config.codegen ?? {}, validator);
 	const imports = resolveImports(root, build.tool, future, config.imports, validator);
-	if (Object.keys(tsdown).length > 0 && build.tool !== "tsdown") throw validator.error("`tsdown` options need the `tsdown` build tool", "tsdown", "TSDOWN_OPTIONS_REQUIRE_TSDOWN", `Set \`build.tool\` to 'tsdown', or remove \`tsdown\` (the build tool is '${build.tool}').`);
-	if (Object.keys(vite).length > 0 && build.tool !== "vite") throw validator.error("`vite` options need the `vite` build tool", "vite", "VITE_OPTIONS_REQUIRE_VITE", `Set \`build.tool\` to 'vite' with \`experimental.enableVite\`, or remove \`vite\` (the build tool is '${build.tool}').`);
+	if (Object.keys(tsdown).length > 0 && build.tool !== "tsdown") throw validator.error(configDiagnostics.TSDOWN_OPTIONS_REQUIRE_TSDOWN, { tool: build.tool });
+	if (Object.keys(vite).length > 0 && build.tool !== "vite") throw validator.error(configDiagnostics.VITE_OPTIONS_REQUIRE_VITE, { tool: build.tool });
 	return {
 		configFile: file,
 		cwd,
@@ -236,14 +335,17 @@ function displayPath(root, path) {
 function resolveEntry(root, configured, validator) {
 	if (configured !== void 0) {
 		const entry = resolve(root, configured);
-		if (!isFile(entry)) throw validator.error(`The entry file does not exist: ${entry}`, "entry", "ENTRY_NOT_FOUND", "Point `entry` to the file that starts the bot, relative to the project root.");
+		if (!isFile(entry)) throw validator.error(configDiagnostics.ENTRY_NOT_FOUND, { entry });
 		return entry;
 	}
 	for (const candidate of DEFAULT_ENTRIES) {
 		const entry = join(root, candidate);
 		if (isFile(entry)) return entry;
 	}
-	throw validator.error(`Could not find the entry file in ${root}`, "entry", "ENTRY_NOT_FOUND", `Set \`entry\` in the configuration, or create one of ${DEFAULT_ENTRIES.join(", ")}.`);
+	throw validator.error(configDiagnostics.ENTRY_DEFAULT_NOT_FOUND, {
+		root,
+		defaults: DEFAULT_ENTRIES.join(", ")
+	});
 }
 function resolveBuild(root, entry, packageJson, config, experimental, future, hasTsdownOptions, validator) {
 	validator.knownKeys(config, "build", [
@@ -252,26 +354,39 @@ function resolveBuild(root, entry, packageJson, config, experimental, future, ha
 		"tsconfig"
 	]);
 	const requested = validator.string(config.tool, "build.tool") ?? "auto";
-	if (!BUILD_TOOLS.has(requested)) throw validator.error(`Unknown build tool "${requested}"`, "build.tool", "INVALID_BUILD_TOOL", "Use one of 'tsdown', 'tsc', 'vite', 'none' or 'auto'.");
-	if (requested === "vite" && !experimental.enableVite) throw validator.error("The 'vite' build tool is experimental", "build.tool", "EXPERIMENT_REQUIRED", "Set `experimental.enableVite` to true to use it.");
+	if (!BUILD_TOOLS.has(requested)) throw validator.error(configDiagnostics.INVALID_BUILD_TOOL, { tool: requested });
+	if (requested === "vite" && !experimental.enableVite) throw validator.error(configDiagnostics.EXPERIMENTAL_BUILD_TOOL, {
+		tool: "vite",
+		flag: "experimental.enableVite"
+	});
 	const isTypeScriptEntry = TYPESCRIPT_EXTENSIONS.has(extname(entry));
 	const tool = requested === "auto" ? detectBuildTool(root, packageJson, isTypeScriptEntry, experimental, future, hasTsdownOptions) : requested;
-	if (tool === "none" && isTypeScriptEntry) throw validator.error(`The entry ${displayPath(root, entry)} is TypeScript but the build tool is 'none'`, "build.tool", "BUILD_TOOL_REQUIRED", "Set `build.tool` to 'tsdown' or 'tsc', or point `entry` to a JavaScript file.");
+	if (tool === "none" && isTypeScriptEntry) throw validator.error(configDiagnostics.BUILD_TOOL_REQUIRED, { entry: displayPath(root, entry) });
 	const defaultOutDir = experimental.enableNitro ? ".output" : "dist";
 	const outDir = resolve(root, validator.string(config.outDir, "build.outDir") ?? defaultOutDir);
 	let tsconfig = null;
 	const configuredTsconfig = validator.string(config.tsconfig, "build.tsconfig");
 	if (configuredTsconfig !== void 0) {
 		tsconfig = resolve(root, configuredTsconfig);
-		if (!isFile(tsconfig)) throw validator.error(`The tsconfig file does not exist: ${tsconfig}`, "build.tsconfig", "TSCONFIG_NOT_FOUND", "Point `build.tsconfig` to an existing tsconfig.json, relative to the project root.");
+		if (!isFile(tsconfig)) throw validator.error(configDiagnostics.TSCONFIG_EXPLICIT_NOT_FOUND, {
+			tsconfig,
+			path: "build.tsconfig"
+		});
 	} else if (tool === "tsc" || tool === "tsdown") {
 		tsconfig = [join(root, "src", "tsconfig.json"), join(root, "tsconfig.json")].find((candidate) => isFile(candidate)) ?? null;
-		if (!tsconfig && tool === "tsc") throw validator.error(`Could not find a tsconfig.json in ${root}`, "build.tsconfig", "TSCONFIG_NOT_FOUND", "Create src/tsconfig.json or tsconfig.json, or set `build.tsconfig`.");
+		if (!tsconfig && tool === "tsc") throw validator.error(configDiagnostics.TSCONFIG_NOT_FOUND, {
+			root,
+			suggestion: "build.tsconfig"
+		});
 	}
 	const output = experimental.enableNitro ? join(outDir, "server", "index.mjs") : tool === "none" ? entry : resolveBuildOutput(root, entry, outDir, packageJson);
 	let configFile = findConfigFile(root, tool === "tsdown" ? TSDOWN_CONFIG_FILES : tool === "vite" ? VITE_CONFIG_FILES : []);
 	if (tool === "tsdown" && configFile === null && packageJson?.tsdown !== void 0) configFile = join(root, "package.json");
-	if (tool === "tsdown" && configFile !== null && future.compatibilityVersion >= 4) throw validator.error(`\`${displayPath(root, configFile)}\` is not used with compatibility version ${future.compatibilityVersion}`, "tsdown", "TSDOWN_CONFIG_FILE_UNSUPPORTED", `Move its options into \`tsdown\` here, drop the ${displayPath(root, configFile)} configuration, or set \`future.compatibilityVersion\` to ${3}.`);
+	if (tool === "tsdown" && configFile !== null && future.compatibilityVersion >= 4) throw validator.error(configDiagnostics.TSDOWN_CONFIG_FILE_UNSUPPORTED, {
+		file: displayPath(root, configFile),
+		version: future.compatibilityVersion,
+		legacyVersion: 3
+	});
 	return {
 		tool,
 		outDir,
@@ -301,11 +416,15 @@ function detectBuildTool(root, packageJson, isTypeScriptEntry, experimental, fut
 * Resolves the Nuxt-style compatibility block. Version 4 is the default; version 3 remains an explicit legacy mode.
 */
 function resolveFuture(config, validator) {
-	if (config === null || typeof config !== "object" || Array.isArray(config)) throw validator.error("`future` must be an object", "future", "INVALID_TYPE", "Use `{ compatibilityVersion }`.");
+	if (config === null || typeof config !== "object" || Array.isArray(config)) throw validator.typeError("future", "an object", config, "Use `{ compatibilityVersion }`.");
 	validator.knownKeys(config, "future", ["compatibilityVersion"]);
 	const version = config.compatibilityVersion;
 	if (version === void 0) return { compatibilityVersion: 4 };
-	if (typeof version !== "number" || !COMPATIBILITY_VERSIONS.has(version)) throw validator.error(`Unknown compatibility version ${describe(version)}`, "future.compatibilityVersion", "INVALID_COMPATIBILITY_VERSION", `Use ${3} for the legacy build pipeline or ${4} for today's defaults.`);
+	if (typeof version !== "number" || !COMPATIBILITY_VERSIONS.has(version)) throw validator.error(configDiagnostics.INVALID_COMPATIBILITY_VERSION, {
+		value: version,
+		legacyVersion: 3,
+		latestVersion: 4
+	});
 	return { compatibilityVersion: version };
 }
 /**
@@ -314,7 +433,7 @@ function resolveFuture(config, validator) {
 * confusing runtime failure.
 */
 function resolveExperimental(config, validator) {
-	if (config === null || typeof config !== "object" || Array.isArray(config)) throw validator.error("`experimental` must be an object", "experimental", "INVALID_TYPE", "Use `{ enableVite, enableExternalVite, enableNitro, nitro }`.");
+	if (config === null || typeof config !== "object" || Array.isArray(config)) throw validator.typeError("experimental", "an object", config, "Use `{ enableVite, enableExternalVite, enableNitro, nitro }`.");
 	validator.knownKeys(config, "experimental", [
 		"enableVite",
 		"enableExternalVite",
@@ -324,11 +443,23 @@ function resolveExperimental(config, validator) {
 	const enableVite = validator.boolean(config.enableVite, "experimental.enableVite") ?? false;
 	const enableExternalVite = validator.boolean(config.enableExternalVite, "experimental.enableExternalVite") ?? false;
 	const enableNitro = validator.boolean(config.enableNitro, "experimental.enableNitro") ?? false;
-	if (enableExternalVite && !enableVite) throw validator.error("`experimental.enableExternalVite` needs `experimental.enableVite`", "experimental.enableExternalVite", "EXPERIMENT_REQUIRED", "Set `experimental.enableVite` to true as well, or drop `enableExternalVite`.");
-	if (enableNitro && !enableVite) throw validator.error("`experimental.enableNitro` needs `experimental.enableVite`", "experimental.enableNitro", "EXPERIMENT_REQUIRED", "Set `experimental.enableVite` to true as well, or drop `enableNitro`.");
+	if (enableExternalVite && !enableVite) throw validator.error(configDiagnostics.EXPERIMENT_REQUIRED, {
+		path: "experimental.enableExternalVite",
+		requires: "experimental.enableVite",
+		drop: "enableExternalVite"
+	});
+	if (enableNitro && !enableVite) throw validator.error(configDiagnostics.EXPERIMENT_REQUIRED, {
+		path: "experimental.enableNitro",
+		requires: "experimental.enableVite",
+		drop: "enableNitro"
+	});
 	const rawNitro = "nitro" in config ? config.nitro : void 0;
-	if (rawNitro !== void 0 && !enableNitro) throw validator.error("`experimental.nitro` needs `experimental.enableNitro`", "experimental.nitro", "EXPERIMENT_REQUIRED", "Set `experimental.enableNitro` to true as well, or drop `nitro`.");
-	if (rawNitro !== void 0 && (rawNitro === null || typeof rawNitro !== "object" || Array.isArray(rawNitro))) throw validator.error("`experimental.nitro` must be an object", "experimental.nitro", "INVALID_TYPE", "Use `{ preset }`.");
+	if (rawNitro !== void 0 && !enableNitro) throw validator.error(configDiagnostics.EXPERIMENT_REQUIRED, {
+		path: "experimental.nitro",
+		requires: "experimental.enableNitro",
+		drop: "nitro"
+	});
+	if (rawNitro !== void 0 && (rawNitro === null || typeof rawNitro !== "object" || Array.isArray(rawNitro))) throw validator.typeError("experimental.nitro", "an object", rawNitro, "Use `{ preset }`.");
 	if (rawNitro) validator.knownKeys(rawNitro, "experimental.nitro", ["preset"]);
 	return {
 		enableVite,
@@ -412,7 +543,10 @@ function resolveDev(root, entry, packageJson, config, env, validator) {
 	if (url !== null) try {
 		new URL(url);
 	} catch {
-		throw validator.error(`Invalid URL "${url}"`, "dev.url", "INVALID_URL", "Use an absolute URL such as http://localhost:3000.");
+		throw validator.error(configDiagnostics.INVALID_URL, {
+			url,
+			fix: "Use an absolute URL such as http://localhost:3000."
+		});
 	}
 	else {
 		const port = devEnv.HTTP_PORT ?? env.HTTP_PORT ?? readDevPortFromEnvFile(root, env.NODE_ENV ?? "development") ?? String(3e3);
@@ -451,16 +585,19 @@ function resolveTypecheck(root, packageJson, config, validator) {
 	let configured;
 	let requestedChecker = "auto";
 	if (config !== true) {
-		if (config === null || typeof config !== "object" || Array.isArray(config)) throw validator.error("`dev.typecheck` must be a boolean or an object", "dev.typecheck", "INVALID_TYPE", "Use `true` to type-check with the project tsconfig, `{ tsconfig }` to pick one, or `false` to disable it.");
+		if (config === null || typeof config !== "object" || Array.isArray(config)) throw validator.typeError("dev.typecheck", "a boolean or an object", config, "Use `true` to type-check with the project tsconfig, `{ tsconfig }` to pick one, or `false` to disable it.");
 		validator.knownKeys(config, "dev.typecheck", ["tsconfig", "checker"]);
 		configured = validator.string(config.tsconfig, "dev.typecheck.tsconfig");
 		requestedChecker = validator.string(config.checker, "dev.typecheck.checker") ?? "auto";
-		if (!TYPECHECKERS.has(requestedChecker)) throw validator.error(`Unknown type checker "${requestedChecker}"`, "dev.typecheck.checker", "INVALID_TYPECHECKER", "Use one of 'tsc', 'golar', 'tsz' or 'auto'.");
+		if (!TYPECHECKERS.has(requestedChecker)) throw validator.error(configDiagnostics.INVALID_TYPECHECKER, { checker: requestedChecker });
 	}
 	const checker = requestedChecker === "auto" ? detectTypechecker(packageJson) : requestedChecker;
 	if (configured !== void 0) {
 		const tsconfig = resolve(root, configured);
-		if (!isFile(tsconfig)) throw validator.error(`The tsconfig file does not exist: ${tsconfig}`, "dev.typecheck.tsconfig", "TSCONFIG_NOT_FOUND", "Point `dev.typecheck.tsconfig` to an existing tsconfig.json, relative to the project root.");
+		if (!isFile(tsconfig)) throw validator.error(configDiagnostics.TSCONFIG_EXPLICIT_NOT_FOUND, {
+			tsconfig,
+			path: "dev.typecheck.tsconfig"
+		});
 		return {
 			enabled: true,
 			tsconfig,
@@ -468,7 +605,10 @@ function resolveTypecheck(root, packageJson, config, validator) {
 		};
 	}
 	const found = [join(root, "src", "tsconfig.json"), join(root, "tsconfig.json")].find((candidate) => isFile(candidate)) ?? null;
-	if (!found) throw validator.error(`Could not find a tsconfig.json in ${root}`, "dev.typecheck", "TSCONFIG_NOT_FOUND", "Create src/tsconfig.json or tsconfig.json, or set `dev.typecheck.tsconfig`.");
+	if (!found) throw validator.error(configDiagnostics.TSCONFIG_NOT_FOUND, {
+		root,
+		suggestion: "dev.typecheck.tsconfig"
+	});
 	return {
 		enabled: true,
 		tsconfig: found,
@@ -494,7 +634,7 @@ function resolveTunnel(config, validator) {
 	let path = "/";
 	if (typeof config === "string") url = config;
 	else if (config !== true) {
-		if (config === null || typeof config !== "object" || Array.isArray(config)) throw validator.error("`dev.tunnel` must be a boolean, an https URL or an object", "dev.tunnel", "INVALID_TYPE", "Use `true` for a cloudflared quick tunnel, an https URL you already serve, or `false` to disable it.");
+		if (config === null || typeof config !== "object" || Array.isArray(config)) throw validator.typeError("dev.tunnel", "a boolean, an https URL or an object", config, "Use `true` for a cloudflared quick tunnel, an https URL you already serve, or `false` to disable it.");
 		validator.knownKeys(config, "dev.tunnel", [
 			"url",
 			"updateEndpoint",
@@ -513,9 +653,12 @@ function resolveTunnel(config, validator) {
 	try {
 		parsed = new URL(url);
 	} catch {
-		throw validator.error(`Invalid URL "${url}"`, "dev.tunnel", "INVALID_URL", "Use an absolute https URL such as https://bot.example.com.");
+		throw validator.error(configDiagnostics.INVALID_URL, {
+			url,
+			fix: "Use an absolute https URL such as https://bot.example.com."
+		});
 	}
-	if (parsed.protocol !== "https:") throw validator.error(`The tunnel URL must be https, received "${url}"`, "dev.tunnel", "INVALID_URL", "Discord only accepts an https interactions endpoint.");
+	if (parsed.protocol !== "https:") throw validator.error(configDiagnostics.TUNNEL_URL_NOT_HTTPS, { url });
 	return {
 		mode: "url",
 		url,
@@ -533,10 +676,10 @@ function resolveCodegen(root, config, validator) {
 			output: join(root, DEFAULT_I18N_OUTPUT)
 		} : null };
 	}
-	if (config.i18n === null || typeof config.i18n !== "object") throw validator.error("`codegen.i18n` must be an object or `false`", "codegen.i18n", "INVALID_TYPE", "Use `{ locales, output }` to configure it or `false` to disable it.");
+	if (config.i18n === null || typeof config.i18n !== "object") throw validator.typeError("codegen.i18n", "an object or `false`", config.i18n, "Use `{ locales, output }` to configure it or `false` to disable it.");
 	validator.knownKeys(config.i18n, "codegen.i18n", ["locales", "output"]);
 	const locales = resolve(root, validator.string(config.i18n.locales, "codegen.i18n.locales") ?? "src/locales/en-US");
-	if (!isDirectory(locales)) throw validator.error(`The locales directory does not exist: ${locales}`, "codegen.i18n.locales", "LOCALES_NOT_FOUND", "Point `codegen.i18n.locales` to the base locale directory, relative to the project root.");
+	if (!isDirectory(locales)) throw validator.error(configDiagnostics.LOCALES_NOT_FOUND, { locales });
 	return { i18n: {
 		locales,
 		output: resolve(root, validator.string(config.i18n.output, "codegen.i18n.output") ?? "src/@types/i18next.d.ts")
@@ -564,7 +707,7 @@ function resolveImports(root, buildTool, future, config, validator) {
 	};
 	const forcedOn = config === true;
 	const options = forcedOn || config === void 0 ? {} : config;
-	if (typeof options !== "object" || options === null || Array.isArray(options)) throw validator.error("`imports` must be an object, `true` or `false`", "imports", "INVALID_TYPE", "Use `{ dirs, presets, exclude, dts }`, `true` to enable with defaults, or `false` to disable.");
+	if (typeof options !== "object" || options === null || Array.isArray(options)) throw validator.typeError("imports", "an object, `true` or `false`", options, "Use `{ dirs, presets, exclude, dts }`, `true` to enable with defaults, or `false` to disable.");
 	validator.knownKeys(options, "imports", [
 		"enabled",
 		"dirs",
@@ -573,7 +716,7 @@ function resolveImports(root, buildTool, future, config, validator) {
 		"dts"
 	]);
 	const requestedOn = forcedOn || validator.boolean(options.enabled, "imports.enabled");
-	if (requestedOn && buildTool !== "tsdown") throw validator.error("`imports` requires the `tsdown` build tool", "imports.enabled", "IMPORTS_REQUIRE_TSDOWN", "Set `build.tool` to 'tsdown', or remove `imports`/set it to `false`.");
+	if (requestedOn && buildTool !== "tsdown") throw validator.error(configDiagnostics.IMPORTS_REQUIRE_TSDOWN, {});
 	const dirs = (validator.stringArray(options.dirs, "imports.dirs") ?? [...DEFAULT_IMPORTS_DIRS]).map((dir) => resolve(root, dir));
 	const presets = validator.stringArray(options.presets, "imports.presets") ?? defaultPresets;
 	const exclude = validator.stringArray(options.exclude, "imports.exclude") ?? [];
@@ -591,19 +734,24 @@ var Validator = class {
 	constructor(file) {
 		this.file = file;
 	}
-	error(message, path, code, hint) {
-		return new ConfigError(message, {
-			code,
-			path,
-			hint,
-			file: this.file
+	get sources() {
+		return this.file ? [this.file] : void 0;
+	}
+	error(handle, params) {
+		return handle({
+			...params,
+			sources: this.sources
 		});
 	}
 	knownKeys(value, path, keys) {
 		for (const key of Object.keys(value)) {
 			if (keys.includes(key)) continue;
 			const fullPath = path ? `${path}.${key}` : key;
-			throw this.error(`Unknown option \`${fullPath}\``, fullPath, "UNKNOWN_OPTION", `Known options${path ? ` of \`${path}\`` : ""}: ${keys.join(", ")}.`);
+			throw this.error(configDiagnostics.UNKNOWN_OPTION, {
+				path: fullPath,
+				parent: path,
+				known: keys.join(", ")
+			});
 		}
 	}
 	string(value, path) {
@@ -637,29 +785,29 @@ var Validator = class {
 		if (value === null || typeof value !== "object" || Array.isArray(value) || !Object.values(value).every((item) => typeof item === "string")) throw this.typeError(path, "an object of string values", value);
 		return value;
 	}
-	typeError(path, expected, value) {
-		return this.error(`\`${path}\` must be ${expected}, received ${describe(value)}`, path, "INVALID_TYPE", `Set \`${path}\` to ${expected} or remove it to use the default.`);
+	/** A generic "wrong type" diagnostic. `fix` defaults to the standard "set it or remove it" wording. */
+	typeError(path, expected, value, fix) {
+		return this.error(configDiagnostics.INVALID_TYPE, {
+			path,
+			expected,
+			value,
+			fix: fix ?? `Set \`${path}\` to ${expected} or remove it to use the default.`
+		});
 	}
 };
-function describe(value) {
-	if (value === null) return "null";
-	if (Array.isArray(value)) return "an array";
-	if (typeof value === "string") return `"${value}"`;
-	return typeof value === "object" ? "an object" : `${typeof value} ${String(value)}`;
-}
 function hasDependency(packageJson, name) {
 	return Boolean(packageJson?.dependencies?.[name] ?? packageJson?.devDependencies?.[name]);
 }
-function readPackageJson(root) {
+function readPackageJson(root, validator) {
 	const file = join(root, "package.json");
 	if (!isFile(file)) return null;
 	try {
 		const parsed = JSON.parse(readFileSync(file, "utf-8"));
 		return parsed !== null && typeof parsed === "object" ? parsed : null;
 	} catch (error) {
-		throw new ConfigError(`Failed to parse ${file}: ${error instanceof Error ? error.message : String(error)}`, {
-			code: "PACKAGE_JSON_INVALID",
-			hint: "Fix the JSON syntax of the package.json file.",
+		throw validator.error(configDiagnostics.PACKAGE_JSON_INVALID, {
+			file,
+			message: error instanceof Error ? error.message : String(error),
 			cause: error
 		});
 	}
@@ -684,7 +832,7 @@ function isDirectory(path) {
 /**
 * Loads, validates and resolves a project's `stars.config.*`.
 *
-* @throws {ConfigError} when the configuration file cannot be loaded or contains an invalid option.
+* @throws {Diagnostic} (from `nostics`, via {@link configDiagnostics}) when the configuration file cannot be loaded or contains an invalid option.
 */
 async function loadStarsConfig(options = {}) {
 	const cwd = options.cwd ?? process.cwd();
@@ -720,5 +868,5 @@ function defineConfig(config) {
 }
 
 //#endregion
-export { CONFIG_EXTENSIONS, CONFIG_FILE_NAMES, ConfigError, defineConfig, discoverConfigFile, displayPath, loadConfigFile, loadStarsConfig, readProjectEnvFiles, resolveStarsConfig };
+export { CONFIG_EXTENSIONS, CONFIG_FILE_NAMES, configDiagnostics, defineConfig, discoverConfigFile, displayPath, loadConfigFile, loadStarsConfig, readProjectEnvFiles, resolveStarsConfig };
 //# sourceMappingURL=config.js.map