@bymax-one/nest-config 1.2.2 → 1.2.4

package/CHANGELOG.md

@@ -11,6 +11,92 @@ as the GitHub Release body, so each released version needs a matching
 
 ## [Unreleased]
 
+## [1.2.4] - 2026-11-01
+
+### Fixed
+
+- **A `source` that is present but `undefined` fails the boot.** `BymaxConfigModule.forRoot({ schema,
+source: loadSource() })` used to validate `process.env` when the loader returned nothing, and boot
+  successfully on configuration the host never meant to use. Passing the key with the value `undefined` or
+  `null` now throws a `TypeError` ("source was provided but is undefined or null"); omitting the key still reads
+  `process.env`.
+
+  #### Apply to a derived backend
+
+  Search for a `source:` option that can be `undefined`. If the host relied on the fall-back to
+  `process.env`, leave the key out instead of passing `undefined`.
+
+- **A `meta({ env })` that cannot name a variable is an issue.** An `env` that is present but is not
+  a non-empty string (`''`, `undefined`, a number) used to be skipped, and the leaf read the variable
+  derived from its path. The aggregated validation report now lists it, naming the variable the leaf
+  would read and the kind of value found, on any layer of the leaf: an inner layer whose `env` is
+  unusable is reported even when an outer layer's usable one wins. The issue is its own line for
+  that leaf, before the line about its value. A leaf with no `env` at all is unchanged, and
+  `resolveSourceNames` still answers the derived name.
+
+  #### Apply to a derived backend
+
+  Search the schemas for `meta({ env: ... })` whose argument can be empty or undefined (for example
+  `meta({ env: process.env.X })`) and give it a real name or remove the call.
+
+- **A test override that matches no leaf throws.** `createTestConfig` and `configTestingModule` used to
+  drop an override for a path the schema does not declare (a misspelled leaf, an undeclared namespace,
+  a stale override after a rename) and answer with a config that lacked it. They now throw a
+  `BymaxConfigValidationError` listing every unmatched path, before any provider is built, even when
+  the override's value is `undefined`. The path is the name shown in the report, and its footer asks
+  for a fix in the test rather than a restart of the process. A namespace given something other than
+  an object is reported once, by name, instead of once per character.
+
+  #### Apply to a derived backend
+
+  Run the test suites: an override that used to be silently ignored now fails. Correct the path or
+  delete the override.
+
+### Documentation
+
+- A leaf that ends in `.catch(fallback)` replaces an invalid value with its fallback and reports no
+  issue; the README now says so.
+
+### Changed
+
+- **A release that changes the public declarations must say so.** `check:api`
+  (`scripts/check-api-surface.mjs`) compares the built declarations with the previous published
+  version and fails when they differ unless the released version's CHANGELOG section has an
+  "Apply to a derived backend" note. Tooling only: nothing to apply in a derived backend.
+- **The mutation gate is 100.** `thresholds.break` moves from 95 to 100, and `high` and `low` with it,
+  because a cold run on `main` now has no survivor. Tooling only: nothing to apply in
+  a derived backend.
+- **The camelCase-to-variable converter has no equivalent mutant.** The acronym boundary is now a
+  zero-width lookaround instead of a capturing group with a quantifier whose shrunken form no input
+  could tell apart. Every derived variable name is unchanged: a new spec compares the converter
+  with the previous two-expression form on every string up to seven characters over
+  `a`, `B`, `C`, `1` and `_`. Nothing to apply in a derived backend.
+
+### Tests
+
+- **The README Quick Start is executed, not only type-checked.** A new spec takes the schema, the
+  `BymaxConfigModule.forRoot` registration and the `FeatureProvider` from the README text,
+  compiles and runs them against a real Nest testing graph, and asserts the stated outcomes: a
+  complete environment boots and the provider returns `<database url>::3000`, and an environment
+  missing both required variables fails with one error naming both. A wrong argument shape or a
+  value that fails validation now fails a test instead of reaching a reader. No source or
+  published-surface change, so there is nothing to apply in a derived backend.
+
+## [1.2.3] - 2026-10-31
+
+### Fixed
+
+- **A schema in which two leaves read one variable is rejected.** `a.bC` and `aB.c` both
+  derive `A_B_C`, and `httpServer.port` and `HTTPServer.port` both derive
+  `HTTP_SERVER_PORT`; so does giving two leaves the same `meta({ env })`. Each pair used to
+  read one value silently, so setting the variable satisfied both leaves and neither could
+  tell. `forRoot`, `createValidatedConfig` and the testing helpers now throw a
+  `BymaxConfigValidationError` before the source is read, with one `BYMAX_CONFIG_INVALID`
+  issue per colliding leaf naming the other leaves and the shared variable. There is no
+  opt-out. `resolveSourceNames` still returns every binding. **Apply to a derived
+  backend:** a colliding schema now fails at boot. Give one leaf of each pair a distinct
+  `meta({ env })`, or read one leaf and derive the other value from it in the consumer.
+
 ## [1.2.2] - 2026-10-31
 
 ### Added
@@ -468,4 +554,6 @@ have regressed from. They are kept because the reasoning is worth having.
 [1.2.0]: https://github.com/bymaxone/nest-config/compare/v1.1.3...v1.2.0
 [1.2.1]: https://github.com/bymaxone/nest-config/compare/v1.2.0...v1.2.1
 [1.2.2]: https://github.com/bymaxone/nest-config/compare/v1.2.1...v1.2.2
-[Unreleased]: https://github.com/bymaxone/nest-config/compare/v1.2.2...HEAD
+[1.2.3]: https://github.com/bymaxone/nest-config/compare/v1.2.2...v1.2.3
+[1.2.4]: https://github.com/bymaxone/nest-config/compare/v1.2.3...v1.2.4
+[Unreleased]: https://github.com/bymaxone/nest-config/compare/v1.2.4...HEAD

package/README.md

@@ -14,7 +14,7 @@
   <a href="https://www.npmjs.com/package/@bymax-one/nest-config"><img src="https://img.shields.io/npm/dm/@bymax-one/nest-config?style=flat-square&colorA=000000&colorB=000000" alt="npm downloads" /></a>
   <a href="https://github.com/bymaxone/nest-config/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/bymaxone/nest-config/ci.yml?branch=main&style=flat-square&colorA=000000&label=CI" alt="CI status" /></a>
   <a href="https://github.com/bymaxone/nest-config/actions/workflows/ci.yml"><img src="https://img.shields.io/badge/coverage-100%25-brightgreen?style=flat-square&colorA=000000" alt="coverage" /></a>
-  <a href="https://github.com/bymaxone/nest-config/blob/main/docs/mutation_testing_results.md"><img src="https://img.shields.io/badge/mutation-99.69%25-brightgreen?style=flat-square&colorA=000000" alt="mutation score" /></a>
+  <a href="https://github.com/bymaxone/nest-config/blob/main/docs/mutation_testing_results.md"><img src="https://img.shields.io/badge/mutation-100.00%25-brightgreen?style=flat-square&colorA=000000" alt="mutation score" /></a>
   <a href="https://scorecard.dev/viewer/?uri=github.com/bymaxone/nest-config"><img src="https://api.scorecard.dev/projects/github.com/bymaxone/nest-config/badge?style=flat-square" alt="OpenSSF Scorecard" /></a>
   <a href="https://github.com/bymaxone/nest-config/blob/main/LICENSE"><img src="https://img.shields.io/github/license/bymaxone/nest-config?style=flat-square&colorA=000000&colorB=000000" alt="license" /></a>
   <a href="https://www.typescriptlang.org/"><img src="https://img.shields.io/badge/TypeScript-strict-3178C6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" /></a>
@@ -206,8 +206,10 @@ BymaxConfigValidationError: environment validation failed (3 issues)
 Fix the variables above and restart the process.
 ```
 
-The report has one line per variable: when a leaf fails several rules, the line shows the first
-one Zod lists, and fixing it can reveal the next on the following start.
+The report has one line per violation: when a leaf fails several rules, the line shows the first
+one Zod lists, and fixing it can reveal the next on the following start. A `meta({ env })` that
+cannot name a variable adds its own line for that leaf, before the line about its value, because it
+is a different mistake: merging the two would hide the one that explains the other.
 
 In a message this package generates, raw values are never printed — not
 truncated, not masked, absent. That is a hard guarantee, verified by tests. The
@@ -265,6 +267,10 @@ including `'false'`, becomes `true`, so use `z.stringbool()` for a flag. And a v
 empty string is present, not missing: `z.string()` accepts it and `z.coerce.number()` turns it into
 `0`, so add `.min(1)` or a bound where empty should fail.
 
+A leaf that ends in `.catch(fallback)` replaces an invalid value with its fallback and reports no
+issue, so a mistyped variable reaches the application as the fallback; leave `.catch()` off a
+leaf whose failure should stop the boot.
+
 A leaf can override its derived variable name through schema metadata when a
 legacy name must be preserved:
 
@@ -276,9 +282,12 @@ database: z.object({
 ```
 
 The override is found wherever `meta` sits in the chain: `z.string().meta({ env: 'LEGACY' }).default('x')`
-and `z.string().default('x').meta({ env: 'LEGACY' })` both read `LEGACY`. When more than one layer sets it, the outermost usable one wins, and an
-empty or non-string value is skipped. `resolveSourceNames` answers the same, because validation
-reads its variables through it.
+and `z.string().default('x').meta({ env: 'LEGACY' })` both read `LEGACY`. When more than one layer sets it, the outermost usable one wins. An `env` that is present but
+is not a non-empty string (`''`, `undefined`, a number) cannot name a variable, so validation reports it
+as an issue instead of letting the leaf read the variable derived from its path, on any layer: an
+inner layer whose `env` is unusable is reported even when an outer layer's usable one wins. A leaf
+with no `env` at all is unaffected. `resolveSourceNames` skips an unusable `env` and answers the
+derived name.
 
 A namespace can declare itself **open**, which waives strict unknown-key
 detection for the rest of its prefix. Use it when the prefix is shared with
@@ -309,7 +318,7 @@ Write `.meta({ open: true })` last: methods that build a new object schema, such
 | Field               | Type                                              | Required | Notes                                                                                                                                                                                                                            |
 | ------------------- | ------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `schema`            | `EnvSchema`                                       | yes      | Produced by `defineEnv`.                                                                                                                                                                                                         |
-| `source`            | `Record<string, string \| undefined>`             | no       | Defaults to `process.env` in the provider factory. Injectable for tests.                                                                                                                                                         |
+| `source`            | `Record<string, string \| undefined>`             | no       | Defaults to `process.env` when the key is omitted; a key present with the value `undefined` or `null` throws at boot. Injectable for tests.                                                                                      |
 | `onValidationError` | `(issues: ReadonlyArray<ConfigIssue>) => unknown` | no       | Observability hook invoked before the fail-fast throw; a promise it returns is awaited. Cannot suppress the failure.                                                                                                             |
 | `strict`            | `boolean`                                         | no       | When true, source variables matching a namespace prefix but no declared leaf raise `BYMAX_CONFIG_UNKNOWN_KEY`. Defaults to `false`. Read [Strict mode and shared prefixes](#strict-mode-and-shared-prefixes) before enabling it. |
 
@@ -604,7 +613,8 @@ resolves its variables through, so the list cannot drift from what `forRoot` rea
 `SourceBinding` is `{ path: string; variable: string }`: the leaf's dot path and the
 environment variable it reads. The list has one entry per declared leaf, in declaration
 order. A leaf reads its `meta({ env })` override when that is a non-empty string, and
-otherwise `NAMESPACE_LEAF` in SCREAMING_SNAKE_CASE, with a camelCase key split into words.
+`NAMESPACE_LEAF` in SCREAMING_SNAKE_CASE, with a camelCase key split into words, when it has no
+`env` at all.
 It reads the schema only, never a source record, so it works on a schema exported as a
 value.
 
@@ -638,8 +648,9 @@ it('documents every variable the schema reads in .env.example', () => {
   the schema reads it.
 - **Two paths can read one variable.** Names are derived from the keys, so `a.bC` and
   `aB.c` both derive `A_B_C`, and `httpServer.port` and `HTTPServer.port` both derive
-  `HTTP_SERVER_PORT`. Every binding is returned and none is dropped; validation reads the
-  shared variable for both leaves.
+  `HTTP_SERVER_PORT`. Every binding is returned and none is dropped, so a tool can see the
+  collision; validation rejects such a schema (see the error catalog). Giving two leaves
+  the same `meta({ env })` is the same collision, and there is no opt-out.
 - **An open namespace changes nothing.** `meta({ open: true })` only waives strict
   unknown-key detection, so the list is the same whether a namespace is open or closed. It
   does not help to find variables in `.env.example` that no leaf reads.
@@ -648,12 +659,12 @@ it('documents every variable the schema reads in .env.example', () => {
 
 ## 🚨 Error Catalog
 
-| Code                       | Meaning                                                |
-| -------------------------- | ------------------------------------------------------ |
-| `BYMAX_CONFIG_VALIDATION`  | One or more schema violations (top-level error code).  |
-| `BYMAX_CONFIG_MISSING`     | Required variable absent from the source (issue code). |
-| `BYMAX_CONFIG_INVALID`     | Present but failed its constraint (issue code).        |
-| `BYMAX_CONFIG_UNKNOWN_KEY` | Strict mode: source variable matches no declared leaf. |
+| Code                       | Meaning                                                   |
+| -------------------------- | --------------------------------------------------------- |
+| `BYMAX_CONFIG_VALIDATION`  | One or more schema violations (top-level error code).     |
+| `BYMAX_CONFIG_MISSING`     | Required variable absent from the source (issue code).    |
+| `BYMAX_CONFIG_INVALID`     | Failed its constraint, or shares a variable (issue code). |
+| `BYMAX_CONFIG_UNKNOWN_KEY` | Strict mode: source variable matches no declared leaf.    |
 
 ## 🏗️ Architecture
 
@@ -815,9 +826,8 @@ Configuration decides whether a process may start at all, so the suite is held t
 beyond "the tests pass".
 
 - ✅ **100% line coverage** — statements, branches, functions and lines, enforced as a gate
-- ✅ **99.69% mutation score** — verified with [Stryker](https://stryker-mutator.io/) at
-  `break: 95`; ten provable equivalents carry their reason inline, and the one survivor left
-  is an equivalent no directive can reach, so it stays counted rather than silenced
+- ✅ **100.00% mutation score** — verified with [Stryker](https://stryker-mutator.io/) at
+  `break: 100`; provable equivalents carry their reason inline and nothing else survives
   ([report](./docs/mutation_testing_results.md))
 - ✅ **The value-free guarantee is tested, not assumed** — a sentinel secret is placed in a
   source and the assertion is that it appears nowhere in the rendered report or in the thrown
@@ -826,7 +836,8 @@ beyond "the tests pass".
   proven is the guarantee this package makes for its own generated text
 - ✅ **Published-artifact gates** — `check:exports` resolves the types the way each module
   system does, `check:runtime` loads every subpath from the packed tarball in ESM and
-  CommonJS, and `check:published` compiles this README's snippets against `dist/`
+  CommonJS, `check:published` compiles this README's snippets against `dist/`, and `check:api`
+  requires an "Apply to a derived backend" CHANGELOG note when the built declarations change
 - ✅ **Every suppression carries its reason** — no coverage directives anywhere; each
   `// Stryker disable` in the production source names, after the `:` Stryker reads it from,
   why the mutant it silences is behaviour-preserving, and `check:mutants` proves those
@@ -836,7 +847,7 @@ beyond "the tests pass".
 ```bash
 pnpm test          # unit suite
 pnpm test:cov      # unit suite with the 100% coverage gate
-pnpm mutation      # Stryker mutation testing (break: 95)
+pnpm mutation      # Stryker mutation testing (break: 100)
 pnpm typecheck     # tsc strict check
 pnpm lint          # ESLint
 ```
@@ -900,7 +911,9 @@ const moduleRef = await Test.createTestingModule({
 
 Overrides mirror the `namespace.leaf` shape with every key optional and typed from the schema. Each value is converted with `String(value)` before validation, so give
 a leaf what its environment variable would hold; an object becomes `'[object Object]'`, and an override
-of `undefined` is ignored, so a defaulted leaf cannot be unset. Neither helper takes `strict`, a
+of `undefined` is ignored, so a defaulted leaf cannot be unset. An override whose path matches no leaf
+of the schema throws, listing every such path, even when its value is `undefined`; a namespace given
+something other than an object is reported once, by name. Neither helper takes `strict`, a
 custom `source`, a hook or `isGlobal`: `configTestingModule` registers the module globally, and a
 failure case (a missing variable, a strict violation) is built with
 `BymaxConfigModule.forRoot({ schema, source, strict: true })` and a source you write.

package/dist/internal/index.cjs

@@ -53,25 +53,30 @@ var MIN_VARIABLE_COLUMN = 20;
 var VARIABLE_GUTTER = 2;
 var REPORT_HEADER = "environment validation failed";
 var REPORT_FOOTER = "Fix the variables above and restart the process.";
+var OVERRIDE_FOOTER = "Fix the overrides above in the test.";
 function pluralizeIssues(count) {
   const noun = count === 1 ? "issue" : "issues";
   return `${count} ${noun}`;
 }
+function nameOf(issue) {
+  return issue.variable === "" ? issue.path : issue.variable;
+}
 function computeColumnWidth(issues) {
   let longest = MIN_VARIABLE_COLUMN;
   for (const issue of issues) {
-    longest = Math.max(longest, issue.variable.length);
+    longest = Math.max(longest, nameOf(issue).length);
   }
   return longest + VARIABLE_GUTTER;
 }
 function formatIssueLine(issue, columnWidth) {
-  return `${REPORT_INDENT}${issue.variable.padEnd(columnWidth)}${issue.message}`;
+  return `${REPORT_INDENT}${nameOf(issue).padEnd(columnWidth)}${issue.message}`;
 }
 function formatIssueReport(issues) {
   const columnWidth = computeColumnWidth(issues);
   const lines = issues.map((issue) => formatIssueLine(issue, columnWidth));
   const header = `${REPORT_HEADER} (${pluralizeIssues(issues.length)})`;
-  return [header, "", ...lines, "", REPORT_FOOTER].join("\n");
+  const aboutOverrides = issues.length > 0 && issues.every((issue) => issue.variable === "");
+  return [header, "", ...lines, "", aboutOverrides ? OVERRIDE_FOOTER : REPORT_FOOTER].join("\n");
 }
 
 // src/errors.ts
@@ -119,7 +124,7 @@ var BymaxConfigValidationError = class _BymaxConfigValidationError extends Error
 
 // src/source-mapping.ts
 function toScreamingSnake(segment) {
-  return segment.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2").toUpperCase();
+  return segment.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/(?<=[A-Z])(?=[A-Z][a-z])/g, "_").toUpperCase();
 }
 function readEnvOverride(leaf) {
   for (let node = leaf; node !== void 0; ) {
@@ -143,6 +148,33 @@ function resolveSourceNames(schema) {
     }))
   );
 }
+function describeUnusable(value) {
+  if (value === "") return "an empty string";
+  if (value === void 0) return "undefined";
+  if (value === null) return "null";
+  return `${typeof value === "object" ? "an" : "a"} ${typeof value}`;
+}
+function describeUnusableEnv(leaf) {
+  for (let node = leaf; node !== void 0; ) {
+    const meta = node.meta();
+    if (meta !== void 0 && "env" in meta) {
+      const value = meta.env;
+      if (typeof value !== "string" || value.length === 0) return describeUnusable(value);
+    }
+    node = node._zod.def.innerType ?? node._zod.def.in;
+  }
+  return void 0;
+}
+function findUnusableEnvOverrides(schema) {
+  const unusable = [];
+  for (const [namespace, namespaceSchema] of Object.entries(schema.shape)) {
+    for (const [leafKey, leafSchema] of Object.entries(namespaceSchema.shape)) {
+      const found = describeUnusableEnv(leafSchema);
+      if (found !== void 0) unusable.push({ path: `${namespace}.${leafKey}`, found });
+    }
+  }
+  return unusable;
+}
 function resolveNamespacePrefixes(schema) {
   return Object.entries(schema.shape).map(([namespace, namespaceSchema]) => ({
     namespace,
@@ -282,20 +314,54 @@ function detectUnknownKeys(prefixes, bindings, source) {
     (left, right) => Number(left.variable > right.variable) - Number(left.variable < right.variable)
   );
 }
+function assertDistinctVariables(bindings) {
+  const byVariable = /* @__PURE__ */ new Map();
+  for (const { path, variable } of bindings) {
+    byVariable.set(variable, [...byVariable.get(variable) ?? [], path]);
+  }
+  const issues = [];
+  for (const [variable, paths] of byVariable) {
+    if (paths.length < 2) continue;
+    for (const path of paths) {
+      const others = paths.filter((other) => other !== path).join(", ");
+      issues.push({
+        path,
+        variable,
+        code: ConfigErrorCode.INVALID,
+        message: `shares this variable with ${others}; rename one with meta({ env })`
+      });
+    }
+  }
+  if (issues.length > 0) throw new BymaxConfigValidationError(issues);
+}
+function unusableOverrideIssues(schema, bindings) {
+  const variables = new Map(bindings.map((binding) => [binding.path, binding.variable]));
+  return findUnusableEnvOverrides(schema).map(({ path, found }) => {
+    const variable = variables.get(path);
+    return {
+      path,
+      variable,
+      code: ConfigErrorCode.INVALID,
+      message: `meta({ env }) must be a non-empty string, found ${found}; the leaf would read ${variable}`
+    };
+  });
+}
 function validateEnv(schema, source, options) {
   const bindings = resolveSourceNames(schema);
+  assertDistinctVariables(bindings);
   const sourceMap = new Map(Object.entries(source));
   const namespaces = Object.keys(schema.shape);
   const candidate = buildCandidate(namespaces, collectPresentLeaves(bindings, sourceMap));
   const result = schema.safeParse(candidate);
   const prefixes = resolveNamespacePrefixes(schema);
   const unknown = options?.strict === true ? detectUnknownKeys(prefixes, bindings, sourceMap) : [];
+  const overrides = unusableOverrideIssues(schema, bindings);
   if (result.success) {
-    if (unknown.length === 0) return result.data;
-    throw new BymaxConfigValidationError(unknown);
+    if (unknown.length === 0 && overrides.length === 0) return result.data;
+    throw new BymaxConfigValidationError([...overrides, ...unknown]);
   }
   const issues = translateIssues(result.error.issues, bindings, prefixes, sourceMap);
-  throw new BymaxConfigValidationError([...issues, ...unknown]);
+  throw new BymaxConfigValidationError([...overrides, ...issues, ...unknown]);
 }
 
 // src/config.providers.ts
@@ -313,6 +379,11 @@ async function reportIssues(hook, error) {
   }
 }
 function createValidatedConfig(options) {
+  if ("source" in options && (options.source === void 0 || options.source === null)) {
+    throw new TypeError(
+      "BymaxConfigModule: source was provided but is undefined or null; omit the key to validate process.env, or pass the source that failed to load"
+    );
+  }
   const source = options.source ?? process.env;
   return deepFreeze(validateEnv(options.schema, source, { strict: options.strict === true }));
 }
@@ -516,6 +587,8 @@ exports.BYMAX_CONFIG = BYMAX_CONFIG;
 exports.BYMAX_CONFIG_OPTIONS = BYMAX_CONFIG_OPTIONS;
 exports.BymaxConfigValidationError = BymaxConfigValidationError;
 exports.ConfigErrorCode = ConfigErrorCode;
+exports.assertDistinctVariables = assertDistinctVariables;
 exports.createValidatedConfig = createValidatedConfig;
 exports.defineEnv = defineEnv;
 exports.resolveSourceNames = resolveSourceNames;
+exports.unusableOverrideIssues = unusableOverrideIssues;

package/dist/internal/index.d.cts

@@ -557,6 +557,8 @@ declare function defineEnv<TShape extends EnvShape>(shape: TShape): EnvSchema<TS
  * @param options - The resolved module options (schema, source, strict).
  * @returns The validated, deep-frozen configuration output.
  * @throws {BymaxConfigValidationError} When the source fails the schema.
+ * @throws {TypeError} When `source` is present with the value `undefined` or `null`, which would
+ * otherwise validate `process.env` in place of the source that failed to load.
  * @example
  * ```typescript
  * const config = createValidatedConfig({ schema: envSchema });
@@ -604,7 +606,7 @@ interface SourceBinding {
  * never a source record. Declared is not required: a leaf with a default or an
  * optional leaf is listed like any other. Two distinct paths can resolve to one
  * variable (`a.bC` and `aB.c` both derive `A_B_C`); both bindings are returned
- * and none is dropped. An open namespace changes nothing here, since opening
+ * and none is dropped, though validation rejects a schema that holds such a pair. An open namespace changes nothing here, since opening
  * only waives strict unknown-key detection.
  *
  * @typeParam TShape - The two-level shape the schema was composed from.
@@ -619,4 +621,42 @@ interface SourceBinding {
  */
 declare function resolveSourceNames<TShape extends EnvShape = EnvShape>(schema: EnvSchema<TShape>): readonly SourceBinding[];
 
-export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, type BymaxConfigModuleOptions, BymaxConfigValidationError, ConfigErrorCode, type ConfigIssue, type ConfigIssueCode, ConfigService, type ConfigValidationCode, type EnvLeaf, type EnvNamespace, type EnvOutput, type EnvSchema, type EnvShape, type Path, type PathValue, type SourceBinding, createValidatedConfig, defineEnv, resolveSourceNames };
+/**
+ * @fileoverview Single-pass environment validator. Maps a flat source record
+ * onto the nested schema through the resolved source-name bindings, runs exactly
+ * one Zod parse, and either returns the typed parsed output or throws a
+ * BymaxConfigValidationError aggregating every violation. Zod issues are
+ * translated into value-free ConfigIssue descriptions that state only the
+ * expected constraint, never the received value. The one exception is the
+ * message a schema author attaches to a `custom` issue (`.check`, `.refine`,
+ * `.superRefine`), which is reported as written: it is schema text, not input,
+ * and it is the only place a conditional or cross-field rule can explain itself.
+ * @layer Service
+ */
+
+/**
+ * Reject a schema in which two leaves read one source variable.
+ *
+ * Two leaves that derive, or are told through `meta({ env })`, the same variable would
+ * each read the one value and neither could report on its own, so the schema is wrong
+ * before any source is looked at. One issue is produced per colliding leaf, in order of
+ * first appearance, each naming the other leaves that share its variable.
+ *
+ * @param bindings - Every leaf binding of a schema, from `resolveSourceNames`.
+ * @throws {BymaxConfigValidationError} When any variable is bound by more than one leaf.
+ */
+declare function assertDistinctVariables(bindings: ReadonlyArray<SourceBinding>): void;
+/**
+ * Describe every leaf whose `meta({ env })` is present but cannot name a variable.
+ *
+ * The leaf would silently read the variable derived from its path, so it is a mistake in the
+ * schema, reported beside the violations of the source. The message names the variable the
+ * leaf reads and the kind of value `env` held, never the value.
+ *
+ * @param schema - A schema produced by `defineEnv`.
+ * @param bindings - Every leaf binding of the schema, from `resolveSourceNames`.
+ * @returns One issue per affected leaf, in schema order.
+ */
+declare function unusableOverrideIssues<TShape extends EnvShape>(schema: EnvSchema<TShape>, bindings: ReadonlyArray<SourceBinding>): ConfigIssue[];
+
+export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, type BymaxConfigModuleOptions, BymaxConfigValidationError, ConfigErrorCode, type ConfigIssue, type ConfigIssueCode, ConfigService, type ConfigValidationCode, type EnvLeaf, type EnvNamespace, type EnvOutput, type EnvSchema, type EnvShape, type Path, type PathValue, type SourceBinding, assertDistinctVariables, createValidatedConfig, defineEnv, resolveSourceNames, unusableOverrideIssues };

package/dist/internal/index.d.ts

@@ -557,6 +557,8 @@ declare function defineEnv<TShape extends EnvShape>(shape: TShape): EnvSchema<TS
  * @param options - The resolved module options (schema, source, strict).
  * @returns The validated, deep-frozen configuration output.
  * @throws {BymaxConfigValidationError} When the source fails the schema.
+ * @throws {TypeError} When `source` is present with the value `undefined` or `null`, which would
+ * otherwise validate `process.env` in place of the source that failed to load.
  * @example
  * ```typescript
  * const config = createValidatedConfig({ schema: envSchema });
@@ -604,7 +606,7 @@ interface SourceBinding {
  * never a source record. Declared is not required: a leaf with a default or an
  * optional leaf is listed like any other. Two distinct paths can resolve to one
  * variable (`a.bC` and `aB.c` both derive `A_B_C`); both bindings are returned
- * and none is dropped. An open namespace changes nothing here, since opening
+ * and none is dropped, though validation rejects a schema that holds such a pair. An open namespace changes nothing here, since opening
  * only waives strict unknown-key detection.
  *
  * @typeParam TShape - The two-level shape the schema was composed from.
@@ -619,4 +621,42 @@ interface SourceBinding {
  */
 declare function resolveSourceNames<TShape extends EnvShape = EnvShape>(schema: EnvSchema<TShape>): readonly SourceBinding[];
 
-export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, type BymaxConfigModuleOptions, BymaxConfigValidationError, ConfigErrorCode, type ConfigIssue, type ConfigIssueCode, ConfigService, type ConfigValidationCode, type EnvLeaf, type EnvNamespace, type EnvOutput, type EnvSchema, type EnvShape, type Path, type PathValue, type SourceBinding, createValidatedConfig, defineEnv, resolveSourceNames };
+/**
+ * @fileoverview Single-pass environment validator. Maps a flat source record
+ * onto the nested schema through the resolved source-name bindings, runs exactly
+ * one Zod parse, and either returns the typed parsed output or throws a
+ * BymaxConfigValidationError aggregating every violation. Zod issues are
+ * translated into value-free ConfigIssue descriptions that state only the
+ * expected constraint, never the received value. The one exception is the
+ * message a schema author attaches to a `custom` issue (`.check`, `.refine`,
+ * `.superRefine`), which is reported as written: it is schema text, not input,
+ * and it is the only place a conditional or cross-field rule can explain itself.
+ * @layer Service
+ */
+
+/**
+ * Reject a schema in which two leaves read one source variable.
+ *
+ * Two leaves that derive, or are told through `meta({ env })`, the same variable would
+ * each read the one value and neither could report on its own, so the schema is wrong
+ * before any source is looked at. One issue is produced per colliding leaf, in order of
+ * first appearance, each naming the other leaves that share its variable.
+ *
+ * @param bindings - Every leaf binding of a schema, from `resolveSourceNames`.
+ * @throws {BymaxConfigValidationError} When any variable is bound by more than one leaf.
+ */
+declare function assertDistinctVariables(bindings: ReadonlyArray<SourceBinding>): void;
+/**
+ * Describe every leaf whose `meta({ env })` is present but cannot name a variable.
+ *
+ * The leaf would silently read the variable derived from its path, so it is a mistake in the
+ * schema, reported beside the violations of the source. The message names the variable the
+ * leaf reads and the kind of value `env` held, never the value.
+ *
+ * @param schema - A schema produced by `defineEnv`.
+ * @param bindings - Every leaf binding of the schema, from `resolveSourceNames`.
+ * @returns One issue per affected leaf, in schema order.
+ */
+declare function unusableOverrideIssues<TShape extends EnvShape>(schema: EnvSchema<TShape>, bindings: ReadonlyArray<SourceBinding>): ConfigIssue[];
+
+export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, type BymaxConfigModuleOptions, BymaxConfigValidationError, ConfigErrorCode, type ConfigIssue, type ConfigIssueCode, ConfigService, type ConfigValidationCode, type EnvLeaf, type EnvNamespace, type EnvOutput, type EnvSchema, type EnvShape, type Path, type PathValue, type SourceBinding, assertDistinctVariables, createValidatedConfig, defineEnv, resolveSourceNames, unusableOverrideIssues };

package/dist/internal/index.mjs

@@ -51,25 +51,30 @@ var MIN_VARIABLE_COLUMN = 20;
 var VARIABLE_GUTTER = 2;
 var REPORT_HEADER = "environment validation failed";
 var REPORT_FOOTER = "Fix the variables above and restart the process.";
+var OVERRIDE_FOOTER = "Fix the overrides above in the test.";
 function pluralizeIssues(count) {
   const noun = count === 1 ? "issue" : "issues";
   return `${count} ${noun}`;
 }
+function nameOf(issue) {
+  return issue.variable === "" ? issue.path : issue.variable;
+}
 function computeColumnWidth(issues) {
   let longest = MIN_VARIABLE_COLUMN;
   for (const issue of issues) {
-    longest = Math.max(longest, issue.variable.length);
+    longest = Math.max(longest, nameOf(issue).length);
   }
   return longest + VARIABLE_GUTTER;
 }
 function formatIssueLine(issue, columnWidth) {
-  return `${REPORT_INDENT}${issue.variable.padEnd(columnWidth)}${issue.message}`;
+  return `${REPORT_INDENT}${nameOf(issue).padEnd(columnWidth)}${issue.message}`;
 }
 function formatIssueReport(issues) {
   const columnWidth = computeColumnWidth(issues);
   const lines = issues.map((issue) => formatIssueLine(issue, columnWidth));
   const header = `${REPORT_HEADER} (${pluralizeIssues(issues.length)})`;
-  return [header, "", ...lines, "", REPORT_FOOTER].join("\n");
+  const aboutOverrides = issues.length > 0 && issues.every((issue) => issue.variable === "");
+  return [header, "", ...lines, "", aboutOverrides ? OVERRIDE_FOOTER : REPORT_FOOTER].join("\n");
 }
 
 // src/errors.ts
@@ -117,7 +122,7 @@ var BymaxConfigValidationError = class _BymaxConfigValidationError extends Error
 
 // src/source-mapping.ts
 function toScreamingSnake(segment) {
-  return segment.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/([A-Z]+)([A-Z][a-z])/g, "$1_$2").toUpperCase();
+  return segment.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/(?<=[A-Z])(?=[A-Z][a-z])/g, "_").toUpperCase();
 }
 function readEnvOverride(leaf) {
   for (let node = leaf; node !== void 0; ) {
@@ -141,6 +146,33 @@ function resolveSourceNames(schema) {
     }))
   );
 }
+function describeUnusable(value) {
+  if (value === "") return "an empty string";
+  if (value === void 0) return "undefined";
+  if (value === null) return "null";
+  return `${typeof value === "object" ? "an" : "a"} ${typeof value}`;
+}
+function describeUnusableEnv(leaf) {
+  for (let node = leaf; node !== void 0; ) {
+    const meta = node.meta();
+    if (meta !== void 0 && "env" in meta) {
+      const value = meta.env;
+      if (typeof value !== "string" || value.length === 0) return describeUnusable(value);
+    }
+    node = node._zod.def.innerType ?? node._zod.def.in;
+  }
+  return void 0;
+}
+function findUnusableEnvOverrides(schema) {
+  const unusable = [];
+  for (const [namespace, namespaceSchema] of Object.entries(schema.shape)) {
+    for (const [leafKey, leafSchema] of Object.entries(namespaceSchema.shape)) {
+      const found = describeUnusableEnv(leafSchema);
+      if (found !== void 0) unusable.push({ path: `${namespace}.${leafKey}`, found });
+    }
+  }
+  return unusable;
+}
 function resolveNamespacePrefixes(schema) {
   return Object.entries(schema.shape).map(([namespace, namespaceSchema]) => ({
     namespace,
@@ -280,20 +312,54 @@ function detectUnknownKeys(prefixes, bindings, source) {
     (left, right) => Number(left.variable > right.variable) - Number(left.variable < right.variable)
   );
 }
+function assertDistinctVariables(bindings) {
+  const byVariable = /* @__PURE__ */ new Map();
+  for (const { path, variable } of bindings) {
+    byVariable.set(variable, [...byVariable.get(variable) ?? [], path]);
+  }
+  const issues = [];
+  for (const [variable, paths] of byVariable) {
+    if (paths.length < 2) continue;
+    for (const path of paths) {
+      const others = paths.filter((other) => other !== path).join(", ");
+      issues.push({
+        path,
+        variable,
+        code: ConfigErrorCode.INVALID,
+        message: `shares this variable with ${others}; rename one with meta({ env })`
+      });
+    }
+  }
+  if (issues.length > 0) throw new BymaxConfigValidationError(issues);
+}
+function unusableOverrideIssues(schema, bindings) {
+  const variables = new Map(bindings.map((binding) => [binding.path, binding.variable]));
+  return findUnusableEnvOverrides(schema).map(({ path, found }) => {
+    const variable = variables.get(path);
+    return {
+      path,
+      variable,
+      code: ConfigErrorCode.INVALID,
+      message: `meta({ env }) must be a non-empty string, found ${found}; the leaf would read ${variable}`
+    };
+  });
+}
 function validateEnv(schema, source, options) {
   const bindings = resolveSourceNames(schema);
+  assertDistinctVariables(bindings);
   const sourceMap = new Map(Object.entries(source));
   const namespaces = Object.keys(schema.shape);
   const candidate = buildCandidate(namespaces, collectPresentLeaves(bindings, sourceMap));
   const result = schema.safeParse(candidate);
   const prefixes = resolveNamespacePrefixes(schema);
   const unknown = options?.strict === true ? detectUnknownKeys(prefixes, bindings, sourceMap) : [];
+  const overrides = unusableOverrideIssues(schema, bindings);
   if (result.success) {
-    if (unknown.length === 0) return result.data;
-    throw new BymaxConfigValidationError(unknown);
+    if (unknown.length === 0 && overrides.length === 0) return result.data;
+    throw new BymaxConfigValidationError([...overrides, ...unknown]);
   }
   const issues = translateIssues(result.error.issues, bindings, prefixes, sourceMap);
-  throw new BymaxConfigValidationError([...issues, ...unknown]);
+  throw new BymaxConfigValidationError([...overrides, ...issues, ...unknown]);
 }
 
 // src/config.providers.ts
@@ -311,6 +377,11 @@ async function reportIssues(hook, error) {
   }
 }
 function createValidatedConfig(options) {
+  if ("source" in options && (options.source === void 0 || options.source === null)) {
+    throw new TypeError(
+      "BymaxConfigModule: source was provided but is undefined or null; omit the key to validate process.env, or pass the source that failed to load"
+    );
+  }
   const source = options.source ?? process.env;
   return deepFreeze(validateEnv(options.schema, source, { strict: options.strict === true }));
 }
@@ -510,4 +581,4 @@ function defineEnv(shape) {
   return z.object(shape);
 }
 
-export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, BymaxConfigValidationError, ConfigErrorCode, ConfigService, createValidatedConfig, defineEnv, resolveSourceNames };
+export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, BymaxConfigValidationError, ConfigErrorCode, ConfigService, assertDistinctVariables, createValidatedConfig, defineEnv, resolveSourceNames, unusableOverrideIssues };

package/dist/testing/index.cjs

@@ -167,19 +167,49 @@ function synthesizePlaceholderSource(schema) {
 }
 
 // src/testing/create-test-config.ts
-function flattenOverrides(overrides) {
+function unplacedIssue(path, code, message) {
+  return { path, variable: "", code, message };
+}
+function flattenOverrides(overrides, declared) {
   const flat = /* @__PURE__ */ new Map();
+  const unplaced = [];
   for (const [namespace, leaves] of Object.entries(overrides)) {
+    if (typeof leaves !== "object") {
+      unplaced.push(
+        unplacedIssue(
+          namespace,
+          internal.ConfigErrorCode.INVALID,
+          `the override for \`${namespace}\` must be an object`
+        )
+      );
+      continue;
+    }
     for (const [leaf, value] of Object.entries(leaves)) {
-      flat.set(`${namespace}.${leaf}`, value);
+      const path = `${namespace}.${leaf}`;
+      if (declared.has(path)) {
+        flat.set(path, value);
+      } else {
+        unplaced.push(
+          unplacedIssue(
+            path,
+            internal.ConfigErrorCode.UNKNOWN_KEY,
+            "no leaf of the schema is at this path; the override was not applied"
+          )
+        );
+      }
     }
   }
-  return flat;
+  return { flat, unplaced };
 }
 function applyOverrides(schema, base, overrides, overridden) {
-  const flat = flattenOverrides(overrides ?? {});
+  const bindings = internal.resolveSourceNames(schema);
+  const { flat, unplaced } = flattenOverrides(
+    overrides ?? {},
+    new Set(bindings.map((binding) => binding.path))
+  );
+  if (unplaced.length > 0) throw new internal.BymaxConfigValidationError(unplaced);
   const entries = new Map(Object.entries(base));
-  for (const binding of internal.resolveSourceNames(schema)) {
+  for (const binding of bindings) {
     const value = flat.get(binding.path);
     if (value === void 0) continue;
     entries.set(binding.variable, String(value));
@@ -200,6 +230,10 @@ function explainUnsatisfiedLeaves(error, overridden) {
   );
 }
 function prepareTestConfig(schema, overrides) {
+  const bindings = internal.resolveSourceNames(schema);
+  internal.assertDistinctVariables(bindings);
+  const unusable = internal.unusableOverrideIssues(schema, bindings);
+  if (unusable.length > 0) throw new internal.BymaxConfigValidationError(unusable);
   const overridden = /* @__PURE__ */ new Set();
   const source = applyOverrides(schema, synthesizePlaceholderSource(schema), overrides, overridden);
   try {

package/dist/testing/index.mjs

@@ -1,4 +1,4 @@
-import { BymaxConfigModule, createValidatedConfig, BymaxConfigValidationError, resolveSourceNames } from '@bymax-one/nest-config/internal';
+import { BymaxConfigModule, resolveSourceNames, assertDistinctVariables, unusableOverrideIssues, BymaxConfigValidationError, createValidatedConfig, ConfigErrorCode } from '@bymax-one/nest-config/internal';
 
 // src/testing/create-test-config.ts
 var FILLER_CHARACTER = "a";
@@ -165,19 +165,49 @@ function synthesizePlaceholderSource(schema) {
 }
 
 // src/testing/create-test-config.ts
-function flattenOverrides(overrides) {
+function unplacedIssue(path, code, message) {
+  return { path, variable: "", code, message };
+}
+function flattenOverrides(overrides, declared) {
   const flat = /* @__PURE__ */ new Map();
+  const unplaced = [];
   for (const [namespace, leaves] of Object.entries(overrides)) {
+    if (typeof leaves !== "object") {
+      unplaced.push(
+        unplacedIssue(
+          namespace,
+          ConfigErrorCode.INVALID,
+          `the override for \`${namespace}\` must be an object`
+        )
+      );
+      continue;
+    }
     for (const [leaf, value] of Object.entries(leaves)) {
-      flat.set(`${namespace}.${leaf}`, value);
+      const path = `${namespace}.${leaf}`;
+      if (declared.has(path)) {
+        flat.set(path, value);
+      } else {
+        unplaced.push(
+          unplacedIssue(
+            path,
+            ConfigErrorCode.UNKNOWN_KEY,
+            "no leaf of the schema is at this path; the override was not applied"
+          )
+        );
+      }
     }
   }
-  return flat;
+  return { flat, unplaced };
 }
 function applyOverrides(schema, base, overrides, overridden) {
-  const flat = flattenOverrides(overrides ?? {});
+  const bindings = resolveSourceNames(schema);
+  const { flat, unplaced } = flattenOverrides(
+    overrides ?? {},
+    new Set(bindings.map((binding) => binding.path))
+  );
+  if (unplaced.length > 0) throw new BymaxConfigValidationError(unplaced);
   const entries = new Map(Object.entries(base));
-  for (const binding of resolveSourceNames(schema)) {
+  for (const binding of bindings) {
     const value = flat.get(binding.path);
     if (value === void 0) continue;
     entries.set(binding.variable, String(value));
@@ -198,6 +228,10 @@ function explainUnsatisfiedLeaves(error, overridden) {
   );
 }
 function prepareTestConfig(schema, overrides) {
+  const bindings = resolveSourceNames(schema);
+  assertDistinctVariables(bindings);
+  const unusable = unusableOverrideIssues(schema, bindings);
+  if (unusable.length > 0) throw new BymaxConfigValidationError(unusable);
   const overridden = /* @__PURE__ */ new Set();
   const source = applyOverrides(schema, synthesizePlaceholderSource(schema), overrides, overridden);
   try {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bymax-one/nest-config",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "Typed and validated environment configuration entry point for NestJS 11 applications, built on Zod v4.",
   "author": "Bymax One <support@bymax.one>",
   "license": "MIT",
@@ -55,6 +55,7 @@
   },
   "scripts": {
     "build": "pnpm clean && tsup",
+    "check:api": "node scripts/check-api-surface.mjs",
     "check:exports": "attw --pack . --profile strict",
     "check:lint-graph": "node scripts/check-lint-graph-rules.mjs",
     "check:mutants": "node scripts/check-mutation-directives.mjs",