/**
 * Catalog of every error this package can raise, with severity bucket,
 * human-readable title, and the anchor in `docs/ERRORS.md` that
 * documents it in long form.
 *
 * This is the **single source of truth** for error codes:
 *
 *   - {@link NodeSettingsErrorCode} is derived from its keys.
 *   - {@link NodeSettingsError.severity} and `.docsUrl` read from it
 *     at runtime.
 *   - `docs/ERRORS.md` is regenerated from it by
 *     `scripts/generate-errors-doc.mjs`.
 *   - `scripts/verify-errors.mjs` (part of `pnpm verify`) enforces
 *     that every entry has an actual `raise(...)` call somewhere in
 *     `src/` and a matching `<a id="...">` in the doc.
 *
 * Adding an error code: add an entry here and one `raise(...)` call
 * site — the rest follows.
 */
export declare const ERROR_CATALOG: {
    readonly INVALID_ENV_SCHEMA: {
        readonly severity: "config";
        readonly title: "envSchema is not a z.object";
        readonly docsAnchor: "invalid_env_schema";
    };
    readonly MISSING_ENV_KEY: {
        readonly severity: "config";
        readonly title: "envKey not found in envSchema";
        readonly docsAnchor: "missing_env_key";
    };
    readonly INVALID_ENV_KEY_TYPE: {
        readonly severity: "config";
        readonly title: "envKey is not a string / enum";
        readonly docsAnchor: "invalid_env_key_type";
    };
    readonly INVALID_OVERRIDE_KEY: {
        readonly severity: "config";
        readonly title: "overrideEnvKey not found in envSchema";
        readonly docsAnchor: "invalid_override_key";
    };
    readonly INVALID_ENV_OVERRIDE_KEY: {
        readonly severity: "config";
        readonly title: "envOverrides entry not found in envSchema or has an empty path";
        readonly docsAnchor: "invalid_env_override_key";
    };
    readonly PER_ENV_EMPTY: {
        readonly severity: "config";
        readonly title: "perEnv has no branches";
        readonly docsAnchor: "per_env_empty";
    };
    readonly PER_ENV_KEY_NOT_IN_ENUM: {
        readonly severity: "config";
        readonly title: "perEnv branch not in envKey enum";
        readonly docsAnchor: "per_env_key_not_in_enum";
    };
    readonly CLIENT_ENV_PREFIX_VIOLATION: {
        readonly severity: "config";
        readonly title: "defineClientEnv schema key missing required prefix";
        readonly docsAnchor: "client_env_prefix_violation";
    };
    readonly ENV_VALIDATION_FAILED: {
        readonly severity: "runtime";
        readonly title: "Zod env validation failed";
        readonly docsAnchor: "env_validation_failed";
    };
    readonly PER_ENV_BRANCH_MISSING: {
        readonly severity: "runtime";
        readonly title: "No perEnv branch matches the runtime envKey value";
        readonly docsAnchor: "per_env_branch_missing";
    };
    readonly PER_ENV_TODO: {
        readonly severity: "runtime";
        readonly title: "Loaded perEnv branch still has unfilled todo() sentinels";
        readonly docsAnchor: "per_env_todo";
    };
    readonly OVERRIDE_JSON_PARSE: {
        readonly severity: "runtime";
        readonly title: "Override env var is not valid JSON";
        readonly docsAnchor: "override_json_parse";
    };
    readonly OVERRIDE_JSON_NOT_OBJECT: {
        readonly severity: "runtime";
        readonly title: "Override env var parsed to a non-object value";
        readonly docsAnchor: "override_json_not_object";
    };
    readonly OVERRIDE_ENV_EMPTY: {
        readonly severity: "runtime";
        readonly title: "Override env var is set but contains only whitespace";
        readonly docsAnchor: "override_env_empty";
    };
    readonly CLIENT_ENV_UNDECLARED: {
        readonly severity: "runtime";
        readonly title: "Prefixed key present at runtime but not declared in the client schema";
        readonly docsAnchor: "client_env_undeclared";
    };
    readonly CLIENT_ENV_VALIDATION_FAILED: {
        readonly severity: "runtime";
        readonly title: "Zod validation of the client-side env failed";
        readonly docsAnchor: "client_env_validation_failed";
    };
    readonly CONFIG_NOT_FOUND: {
        readonly severity: "io";
        readonly title: "Settings config file not found";
        readonly docsAnchor: "config_not_found";
    };
    readonly CONFIG_LOAD_FAILED: {
        readonly severity: "io";
        readonly title: "Settings config file failed to load";
        readonly docsAnchor: "config_load_failed";
    };
    readonly CONFIG_INVALID_EXPORT: {
        readonly severity: "io";
        readonly title: "Settings config did not export a defineSettings(...) loader";
        readonly docsAnchor: "config_invalid_export";
    };
    readonly FILE_READ_FAILED: {
        readonly severity: "io";
        readonly title: "Could not read a dotenv file or K8s manifest";
        readonly docsAnchor: "file_read_failed";
    };
    readonly K8S_YAML_PARSE_FAILED: {
        readonly severity: "io";
        readonly title: "YAML input to `diff` did not parse";
        readonly docsAnchor: "k8s_yaml_parse_failed";
    };
    readonly INVALID_EXTENDS_ITEM: {
        readonly severity: "usage";
        readonly title: "extends[i] is not a defineSettings(...) loader";
        readonly docsAnchor: "invalid_extends_item";
    };
};
/**
 * Stable error codes thrown by `@env-kit/node-settings`. Match on
 * `.code`, not `.message` — messages may evolve across minor versions.
 *
 * The union is derived from {@link ERROR_CATALOG}, so adding a code
 * there extends this type automatically.
 */
export type NodeSettingsErrorCode = keyof typeof ERROR_CATALOG;
/**
 * Buckets that classify *who* is responsible for fixing the error and
 * *when* it surfaces. Consumers wire these to alarms / log levels:
 *
 *   - `config`   misconfiguration in `defineSettings(...)` source —
 *                CI / build alarm; the developer must fix the code.
 *   - `runtime`  bad env values at boot — on-call alarm; the
 *                operator fixes the deploy environment.
 *   - `io`       file system / parse failures from CLI or loaders —
 *                operator or CI alarm depending on context.
 *   - `usage`    the caller used the public API incorrectly (rare; a
 *                code-review-time bug).
 */
export type ErrorSeverity = "config" | "runtime" | "io" | "usage";
/** Default base URL for `err.docsUrl`. Overridable via `reportError(err, { docsBase })`. */
export declare const DEFAULT_DOCS_BASE = "https://github.com/Changsik00/node-settings/blob/main/docs/ERRORS.md";
/**
 * Single error class for every problem this package can raise. Carries
 * a stable `code` plus an optional `hint` with a remediation tip.
 *
 * @example
 * ```ts
 * try {
 *   const settings = loadSettings(process.env);
 * } catch (err) {
 *   if (err instanceof NodeSettingsError && err.code === 'ENV_VALIDATION_FAILED') {
 *     console.error('Bad env:', err.message);
 *   } else {
 *     throw err;
 *   }
 * }
 * ```
 */
export declare class NodeSettingsError extends Error {
    readonly code: NodeSettingsErrorCode;
    readonly hint: string | undefined;
    /** Original error if this wraps another (e.g. a zod ZodError). */
    readonly cause?: unknown;
    constructor(code: NodeSettingsErrorCode, message: string, options?: {
        hint?: string;
        cause?: unknown;
    });
    /** Severity bucket from {@link ERROR_CATALOG}. */
    get severity(): ErrorSeverity;
    /** Short human title for dashboards and log subjects. */
    get title(): string;
    /** Direct link to the long-form doc entry for this code. */
    get docsUrl(): string;
}
/**
 * Throw a {@link NodeSettingsError}. Returns `never` so call sites
 * don't need an unreachable `throw` and TypeScript can narrow types
 * after the call.
 *
 * @example
 * ```ts
 * if (!(key in shape)) {
 *   raise("MISSING_ENV_KEY", `envKey '${key}' is not defined.`, {
 *     hint: `Known: ${keys.join(", ")}`,
 *   });
 * }
 * ```
 */
export declare function raise(code: NodeSettingsErrorCode, message: string, options?: {
    hint?: string;
    cause?: unknown;
}): never;
//# sourceMappingURL=errors.d.ts.map