@bymax-one/nest-config 1.2.0 → 1.2.2

package/CHANGELOG.md

@@ -11,6 +11,96 @@ as the GitHub Release body, so each released version needs a matching
 
 ## [Unreleased]
 
+## [1.2.2] - 2026-10-31
+
+### Added
+
+- **`resolveSourceNames` and the `SourceBinding` type are exported from the package root.**
+  `resolveSourceNames(schema)` returns one `{ path, variable }` binding per leaf of a
+  `defineEnv` schema, in declaration order: the environment variable that leaf reads. It is the
+  function validation resolves its variables through, so the list equals what `forRoot` reads,
+  and a test can assert that every variable the schema declares appears in `.env.example`
+  without re-deriving the naming rules. Two distinct paths can derive one variable and both
+  bindings are returned, and declared is not required; the README section lists what the list
+  does not tell you. Both names were already importable from `./internal`, which promises
+  nothing; they are public now. **Apply to a derived backend:** nothing is required; import
+  `resolveSourceNames` from `@bymax-one/nest-config` rather than from `./internal`.
+
+### Fixed
+
+- **A rule on a namespace that names no leaf is reported, not dropped.** A `.check`, `.refine` or
+  `.superRefine` on a namespace whose issue sets no `path` made the validation fail with
+  `environment validation failed (0 issues)` and an empty report. It is reported against the
+  namespace now: the issue's `path` is the namespace key, the variable column shows its prefix
+  followed by `*` (`STORAGE_*`), and the author's message is kept; a rule on the whole schema
+  reports `(schema)`. Such a rule runs once the namespace's own leaves are valid.
+- **`meta({ env })` is found wherever it sits in the chain.** `z.string().meta({ env: 'L' }).default('x')`
+  silently read the derived name, because a wrapper builds a node that carries no metadata.
+  The override is read through them, the outermost usable one wins, and `resolveSourceNames` gives
+  the same answer as validation. **Apply to a derived backend:** a leaf that wrote `meta({ env })`
+  before a wrapper now reads that variable instead of the derived one; check that the variable is
+  set where the derived name was.
+- **An asynchronous `onValidationError` that rejects no longer leaves an unhandled rejection.** The
+  provider awaits the hook, so the boot fails after it finishes, with the original validation error;
+  the hook's error, thrown or rejected, is attached to it as a non-enumerable `cause`. A hook that
+  threw was swallowed with no trace before. The hook's type returns `unknown`, so every existing
+  hook still compiles; a hook that never settles now holds the boot, since there is no timeout.
+- **`createTestConfig` and `configTestingModule` synthesize more leaf types and say what to
+  override.** Leaf types that used to fail validation now get a placeholder or are left to the
+  schema. A leaf no placeholder can satisfy (a regex, a `.refine`)
+  fails with an issue that names it and says to override it, and `configTestingModule` raises
+  that when it is called instead of when the module compiles.
+
+### Documentation
+
+- **The README now states what the code does.** The sample failure report printed messages
+  the validator never produces and was misaligned; it is now the exact output for the inputs
+  it documents. The Tech Stack and mutation-score figures, and the `configTestingModule`
+  example, now match the code, and the library is no longer said to have property-based
+  tests (the value-free guarantee is held by sentinel-secret tests).
+
+- **Where "deep-frozen" stops is stated.** Plain objects and arrays are frozen; a `Date`, `Map`
+  or `Set` leaf is frozen as an object but keeps its mutators.
+
+### Tests
+
+- **A contract spec pins the README to the code.** `src/readme-contract.spec.ts` parses the
+  README and asserts its documented defaults, error catalog, peer table, mutation score and
+  first sample report against the code, so the next drift fails CI.
+
+## [1.2.1] - 2026-10-30
+
+### Security
+
+- **The `zod` peer range now starts at `4.6.6`, the first release without
+  GHSA-mrhx-c7xc-m3w5** (high: memory exhaustion while validating oversized constrained
+  collections). The range `^4.0.0` declared installs below it as supported, and the
+  advisory applies to them in an application that validates untrusted collection input
+  through its own schemas. **Apply to a derived backend:** raise `zod` to `4.6.6` or later
+  (`pnpm up zod`); an install below it is outside the declared peer range.
+
+### Documentation
+
+- **Support policy: only the latest minor receives security fixes, and the Discussions
+  link is gone.** `SECURITY.md` supports the latest minor alone; earlier versions get no fix and no
+  backport, and the guidance is to upgrade. The issue-template chooser no longer links to
+  Discussions; the security contact by e-mail remains.
+
+- **`strict` names the two prefixed-variable sources a search will not find.** Both came
+  from an adopter enabling it in a real deployment. A container's own `environment:` block
+  assigns a variable whose host-side name is a different one, so a search over
+  interpolations misses it — and it fails on the default path, because Compose assigns an
+  unset interpolation the empty string rather than absent, and validation skips only
+  `undefined`. Kubernetes service links appear in no file at all: at the default
+  `enableServiceLinks`, a Service named `redis` supplies `REDIS_PORT`,
+  `REDIS_SERVICE_HOST`, `REDIS_SERVICE_PORT` and the `REDIS_PORT_6379_TCP*` family into a
+  closed `redis` namespace — a crash loop in production that never appears in CI.
+
+  The cost of an open namespace is also stated in its sharpest form rather than its
+  general one: the typo it cannot catch may be in that namespace's own declared variable,
+  so `OTEL_ENABLE` is waived, the leaf falls back to its default, and the feature stays
+  off with nothing reported.
+
 ## [1.2.0] - 2026-09-04
 
 ### Added
@@ -49,8 +139,9 @@ as the GitHub Release body, so each released version needs a matching
   (GHSA-5jgf-p345-68v8, GHSA-jqff-g426-hqxp — host confusion; GHSA-f65p-4m7j-42xc,
   GHSA-fph4-wmhf-6fwf — server-side request forgery; CVSS 7.5 each) and `qs`
   (GHSA-4mjr-xmp4-gh2g, GHSA-x5fp-wj9c-mxmx, CVSS 6.3 each). All three are reached through
-  the mutation-testing and commit-tooling chains, none is a runtime dependency, and this
-  package ships `dist` alone — so no consumer resolved a vulnerable version through it.
+  the mutation-testing and commit-tooling chains, none is a runtime dependency, and the
+  package ships only `dist` as runtime code — so no consumer resolved a vulnerable version
+  through it.
 
   Recorded here rather than omitted as internal because a consumer reading an advisory feed
   needs to know whether a library in their tree pulled one in, and "it did not" is an answer
@@ -375,4 +466,6 @@ have regressed from. They are kept because the reasoning is worth having.
 [1.1.2]: https://github.com/bymaxone/nest-config/compare/v1.1.1...v1.1.2
 [1.1.3]: https://github.com/bymaxone/nest-config/compare/v1.1.2...v1.1.3
 [1.2.0]: https://github.com/bymaxone/nest-config/compare/v1.1.3...v1.2.0
-[Unreleased]: https://github.com/bymaxone/nest-config/compare/v1.2.0...HEAD
+[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

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.62%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-99.69%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>
@@ -75,8 +75,10 @@ minimal.
 
 ### 🔒 The Validated Object
 
-- ✅ **Immutable by construction** — deep-frozen before it enters the DI container;
-  configuration is a fact about the process, not a mutable bag
+- ✅ **Immutable by construction** — plain objects and arrays are deep-frozen before the
+  object enters the DI container; configuration is a fact about the process, not a mutable
+  bag (a `Date`, `Map` or `Set` leaf is frozen as an object but keeps its own mutators, see
+  [The validated object is frozen](#the-validated-object-is-frozen))
 - ✅ **Typed dot-path access** — `get('database.url')` is `string`, `get('server.port')` is
   `number`, with no casts and no `any` in the chain
 - ✅ **Injectable environment** — the raw source defaults to `process.env` but is a plain
@@ -101,7 +103,7 @@ minimal.
 
 | Subpath      | Contents                                                                                                                                                                   |
 | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `.`          | `BymaxConfigModule`, `ConfigService`, `defineEnv`, the DI tokens, `BymaxConfigValidationError` and every option type                                                       |
+| `.`          | `BymaxConfigModule`, `ConfigService`, `defineEnv`, `resolveSourceNames`, the DI tokens, `BymaxConfigValidationError` and every option type                                 |
 | `./testing`  | `configTestingModule`, `createTestConfig` — a validated config for a test without booting the application's own                                                            |
 | `./internal` | The shared runtime both entry points build on. **Not public API**: it is in the `exports` map because it has to resolve at runtime, not because it is meant to be imported |
 
@@ -125,7 +127,7 @@ pnpm add @bymax-one/nest-config @nestjs/common @nestjs/core reflect-metadata zod
 | `@nestjs/common`   | `^11.0.16` |
 | `@nestjs/core`     | `^11.1.18` |
 | `reflect-metadata` | `^0.2.0`   |
-| `zod`              | `^4.0.0`   |
+| `zod`              | `^4.6.6`   |
 
 ## 🚀 Quick Start
 
@@ -197,13 +199,16 @@ aggregated report, never one violation at a time:
 ```
 BymaxConfigValidationError: environment validation failed (3 issues)
 
-  DATABASE_URL          missing required value (expected: url)
-  AUTH_JWT_SECRET        too short (expected: string, minimum 32 characters)
-  SERVER_PORT            invalid value (expected: integer between 1 and 65535)
+  DATABASE_URL          missing required value
+  AUTH_JWT_SECRET       too short (expected: string, minimum 32 characters)
+  SERVER_PORT           out of range (expected: number <= 65535)
 
 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.
+
 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
 one exception is a message you write yourself, described next.
@@ -237,6 +242,13 @@ that exact string is reserved — a schema that authors it verbatim reports
 custom error map) the default no longer matches, so the localized default is
 reported as written instead.
 
+A rule on a namespace as a whole, such as a `.check` that compares two of its leaves, names no
+leaf unless its issue sets a `path`. Without one it is reported against the namespace: the
+`path` is the namespace key, the variable column shows its prefix followed by `*`
+(`STORAGE_*`), and the message is the one the rule wrote. A rule on the whole schema is reported
+with the variable column `(schema)` and an empty `path`. Zod does not run a namespace's own rule
+once one of that namespace's leaves has failed, so such a rule appears once the leaves are valid.
+
 ## 📖 API Reference
 
 ### `defineEnv(shape)`
@@ -248,6 +260,11 @@ rewriting, cloning, or wrapping them, so coercion and defaults stay explicit
 consumer choices. Leaves use `z.coerce.*` because the source arrives as
 strings (the shape of `process.env`).
 
+Two things follow from that. `z.coerce.boolean()` is `Boolean(value)`: any non-empty string,
+including `'false'`, becomes `true`, so use `z.stringbool()` for a flag. And a variable set to the
+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 can override its derived variable name through schema metadata when a
 legacy name must be preserved:
 
@@ -258,6 +275,11 @@ 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.
+
 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
 another program that reads its own variables — see
@@ -272,6 +294,9 @@ otel: z.object({ enabled: z.stringbool().default(false) }).meta({ open: true })
 Only the literal `true` opens a namespace. Any other value, and any metadata
 without the key, leaves detection in force.
 
+Write `.meta({ open: true })` last: methods that build a new object schema, such as `.strict()`,
+`.extend()` or `.pick()`, drop the metadata and close the namespace again.
+
 ### `BymaxConfigModule`
 
 | Method                  | Signature                                                         |
@@ -281,12 +306,12 @@ without the key, leaves detection in force.
 
 `BymaxConfigModuleOptions`:
 
-| 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.                                                                                                                                                         |
-| `onValidationError` | `(issues: ReadonlyArray<ConfigIssue>) => void` | no       | Observability hook invoked before the fail-fast throw. 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. |
+| 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.                                                                                                                                                         |
+| `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. |
 
 `forRootAsync` resolves the source through another provider, for example a
 secrets-manager client composed with `process.env`:
@@ -304,6 +329,21 @@ BymaxConfigModule.forRootAsync({
 })
 ```
 
+`forRootAsync` takes Nest's configurable-module options: `useFactory` with
+`inject` and `imports`, shown above; `useClass`, a class whose `create()` returns the options; and
+`useExisting`, which reuses a provider that is already registered (import its module through
+`imports`):
+
+```typescript
+class ConfigOptionsFactory {
+  public create(): { schema: typeof envSchema; source: Record<string, string | undefined> } {
+    return { schema: envSchema, source: { ...process.env } }
+  }
+}
+
+BymaxConfigModule.forRootAsync({ useClass: ConfigOptionsFactory })
+```
+
 `isGlobal` defaults to `true` and can be set to `false` through the standard
 extras when an application intentionally scopes configuration to a submodule.
 
@@ -343,11 +383,60 @@ What the waiver does and does not do:
   and `otelExporter` (closed), `OTEL_EXPORTER_TYPO` belongs to `otelExporter`
   and is still reported.
 
+#### Where prefixed variables come from that a sweep will miss
+
+Before enabling `strict`, know that reading your own repository does not enumerate
+what reaches `process.env`. Two sources defeat a migration sweep in different ways
+— one because the search you would naturally run is the wrong one, the other
+because there is nothing to search — and both were found by adopters rather than
+by reading manifests.
+
+**A container's own `environment:` block.** Compose assigns variables to the
+container with no `${...}` on the host side to give them away:
+
+```yaml
+services:
+  app:
+    environment:
+      REDIS_PASSWORD: ${STACK_REDIS_PASSWORD:-}
+```
+
+`REDIS_PASSWORD` lands in the application's environment. A repository-wide search
+for the prefix does find this line — but the search a migration actually reaches
+for is over interpolations, `${REDIS_`, and that one finds nothing, because the
+interpolated name is the _other_ one. The variable the container receives and the
+variable the host supplies are different names on the same line.
+
+This one fails on the default path rather than only when someone opts in, and the
+reason is worth stating: **Compose assigns an unset interpolation the empty string,
+not absent.** Validation skips a variable whose value is `undefined` — an absent
+variable is the schema's business, not strict mode's — and `''` is not `undefined`.
+So the boot fails even when nobody set a password. That is deliberate: a validator
+that ignored empty strings would also ignore a real misconfiguration that sets one.
+
+**Kubernetes service links, which appear in no file at all.** With
+`enableServiceLinks` at its default, a pod receives Docker-link-compatible
+variables for every Service in its namespace. A Service named `redis` supplies
+`REDIS_PORT`, `REDIS_SERVICE_HOST`, `REDIS_SERVICE_PORT` and the
+`REDIS_PORT_6379_TCP*` family — all inside a closed `redis` namespace, none
+declared, none written down anywhere you can search. Under `strict` that is a crash
+loop in production over variables the application never reads, and it will not have
+appeared in CI.
+
+Set `enableServiceLinks: false` on the pod spec, or open the namespace. Managed
+add-ons injecting names like `REDIS_PUBLIC_URL` or `DATABASE_URL_UNPOOLED` are the
+same family.
+
 **The cost, stated plainly:** an open namespace cannot tell a foreign variable
-from a misspelled local one. Under an open `otel`, a typo of `OTEL_ENABLED`
-passes silently and the leaf falls back to its default. No design removes this —
-the two cases are indistinguishable by name — so open the namespaces whose
-prefix genuinely belongs to someone else, and leave the rest closed.
+from a misspelled local one. No design removes this — the two cases are
+indistinguishable by name — so open the namespaces whose prefix genuinely belongs
+to someone else, and leave the rest closed.
+
+The sharpest form of that cost is worth seeing before you accept it. The typo can
+be in the open namespace's **own** declared variable: write `OTEL_ENABLE` instead
+of `OTEL_ENABLED` and it is waived like any other unclaimed name, the leaf falls
+back to its default, and the feature you meant to switch on stays off with nothing
+reported. A closed namespace would have named that variable and refused to boot.
 
 > Filtering the foreign names out of `source` instead is **not** equivalent, and
 > is worse in a way that is easy to miss: removing `OTEL_*` from the source also
@@ -368,6 +457,10 @@ Because validation completed at bootstrap, `get` never throws for a declared
 path: every leaf either passed validation, received its default, or the
 process did not start.
 
+The class is named `ConfigService`, as the one in `@nestjs/config` is; a backend that imports both
+aliases one of them: `import { ConfigService as BymaxConfigService } from '@bymax-one/nest-config'`.
+`has` is `value !== undefined`, so an absent optional leaf is `false` and a `null` is `true`.
+
 ### `BymaxConfigValidationError` and `ConfigIssue`
 
 ```typescript
@@ -397,6 +490,13 @@ exception is the one described above: a `custom` message written by your own sch
 is printed as written, so if one of yours interpolates a value, reviewing it before
 it reaches a log is the schema author's job, not this package's.
 
+The hook may be asynchronous: a promise it returns is awaited before the boot fails, so a
+report on its way to a log sink is not cut off by the process exiting. There is no timeout, so
+a hook that never settles holds the boot. If the hook throws or rejects, the boot still fails
+with the original validation error, unchanged in class, `code`, `issues` and `message`, and the
+hook's error is attached to it as `error.cause` (non-enumerable, so `code` and `issues` stay
+the only own enumerable properties).
+
 If you also log the thrown error from a bootstrap `catch`, how you pass it decides
 what survives. `code` and `issues` are the **only two own enumerable properties** of
 `BymaxConfigValidationError`; `name`, `message` and `stack` are non-enumerable, as
@@ -467,9 +567,10 @@ failure, and `issues` is what an alert or a dashboard keys on per variable.
 
 ### Injection tokens
 
-`BYMAX_CONFIG` and `BYMAX_CONFIG_OPTIONS` are module-local `Symbol` tokens,
-exported for advanced factory-style wiring that needs the raw frozen config
-or the resolved options directly instead of going through `ConfigService`:
+`BYMAX_CONFIG` is a `Symbol` token for the raw frozen config, exported by the module for advanced
+factory-style wiring that does not go through `ConfigService`. `BYMAX_CONFIG_OPTIONS` is the token of
+the module's own options: it is provided inside the module only, so a provider in another module
+cannot inject it, and the options it holds include the raw `source` record. Do not build on it.
 
 ```typescript
 import { Inject, Injectable } from '@nestjs/common'
@@ -487,10 +588,64 @@ export class RawConfigConsumer {
 `EnvSchema`, `EnvShape`, `EnvOutput`, `EnvLeaf`, and `EnvNamespace` type the
 two-level schema shape produced by `defineEnv`; `Path<T>` and `PathValue<T, P>`
 are the template-literal utilities behind `ConfigService.get`'s compile-time
-dot-path inference, limited to the two-level namespace convention. All five
+dot-path inference, limited to the two-level namespace convention. All of them
 are exported for advanced generic code (custom decorators, typed wrappers)
 that needs to reference the schema shape directly.
 
+### `resolveSourceNames(schema)`
+
+Lists the variable every leaf of a schema reads. It is the function validation itself
+resolves its variables through, so the list cannot drift from what `forRoot` reads.
+
+| Parameter | Type                         | Returns                    |
+| --------- | ---------------------------- | -------------------------- |
+| `schema`  | `EnvSchema` from `defineEnv` | `readonly SourceBinding[]` |
+
+`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.
+It reads the schema only, never a source record, so it works on a schema exported as a
+value.
+
+```typescript
+// For the Quick Start schema:
+resolveSourceNames(envSchema).map((binding) => binding.variable)
+// ['SERVER_PORT', 'SERVER_ENV', 'DATABASE_URL', 'REDIS_URL', 'LOG_LEVEL']
+```
+
+A test that keeps `.env.example` honest is the usual use:
+
+```typescript
+import { readFileSync } from 'node:fs'
+import { resolveSourceNames } from '@bymax-one/nest-config'
+import { envSchema } from './config/env.schema'
+
+it('documents every variable the schema reads in .env.example', () => {
+  const example = readFileSync('.env.example', 'utf8')
+  const documented = new Set(
+    example.split('\n').map((line) => /^#?\s*([A-Z][A-Z0-9_]*)=/.exec(line)?.[1])
+  )
+  const missing = resolveSourceNames(envSchema).filter(({ variable }) => !documented.has(variable))
+  expect(missing).toEqual([])
+})
+```
+
+#### What it does not tell you
+
+- **Declared is not required.** A leaf with a default, or an optional leaf, is listed like
+  any other. Whether it belongs in a template file is your policy; the list says only that
+  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.
+- **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.
+- **Two-level schemas only.** Deeper nesting is outside this contract, as it
+  is for `Path` and `PathValue`.
+
 ## 🚨 Error Catalog
 
 | Code                       | Meaning                                                |
@@ -572,7 +727,7 @@ guaranteed to be printed, logged, and pasted into an issue. That shapes the whol
 Every message this library generates states the _expected_ constraint — the type, the
 allowed enum options taken from the schema, the bound — and never the received value.
 `env-validator` and `report-formatter` each say so in their own contracts, and
-property-based tests hold them to it. The messages you write yourself are the exception,
+sentinel-secret tests hold them to it. The messages you write yourself are the exception,
 covered below.
 
 ### The service does not serialize its configuration
@@ -594,8 +749,16 @@ does not serve one request.
 
 ### The validated object is frozen
 
-It is deep-frozen before it enters the container, so nothing in the running process
-rewrites configuration under a component that already read it.
+Plain objects and arrays are deep-frozen before the object enters the container, so nothing
+in the running process rewrites those values under a component that already read them.
+
+A `Date`, a `Map` or a `Set` leaf is frozen as an object but is **not** made immutable:
+`setTime`, `Map.prototype.set` and `Set.prototype.add` still work, because the state they
+change lives in internal slots that `Object.freeze` cannot reach, and the entries of a `Map` or
+`Set` are not visited. Wrapping them in a read-only proxy was measured and rejected: it fails
+`util.types.isDate`, reports `[object Object]` to `Object.prototype.toString`, cannot be given to
+`structuredClone`, and does not satisfy `assert.deepStrictEqual` against a real `Date`. Prefer a
+string or number leaf, or a `.transform` to a plain value, where immutability matters.
 
 ### Nothing is read from anywhere but the source you name
 
@@ -620,7 +783,7 @@ report.
 | Error messages | Expected constraint only — type, schema-declared enum options, bounds; never the received value. A `custom` message from your own schema is the exception: it prints as written |
 | Failure mode   | Refuse to start; the whole schema is validated before the context finishes building                                                                                             |
 | Aggregation    | Every failure reported at once, so a fix cycle is one restart rather than one per variable                                                                                      |
-| Immutability   | The validated result is frozen before it is provided                                                                                                                            |
+| Immutability   | Plain objects and arrays in the validated result are frozen before it is provided; a `Date`, `Map` or `Set` keeps its mutators                                                  |
 | Service state  | The root lives in a private field; serializing the injected service yields namespace names only                                                                                 |
 | Sources        | `process.env` only — no file, no network, no remote provider                                                                                                                    |
 | Type surface   | Dot paths checked against the schema at compile time; a typo is a build error, not a runtime `undefined`                                                                        |
@@ -637,11 +800,11 @@ report.
 
 - **Runtime:** Node.js 24+
 - **Framework:** NestJS 11 (`ConfigurableModuleBuilder`, `@Global()`, `Symbol()` tokens)
-- **Validation:** Zod `^4` (peer) — the schema language, the coercion and the error source
+- **Validation:** Zod `^4.6.6` (peer) — the schema language, the coercion and the error source
 - **Build:** tsup — ESM + CJS per subpath, with `.d.ts` _and_ `.d.cts` declarations,
   and one shared `./internal` bundle so the module and its testing entry point hold
   a single class identity
-- **Tests:** Jest, including property-based tests over the report formatter + Stryker (mutation)
+- **Tests:** Jest, including sentinel-secret tests over the validator and the report formatter, + Stryker (mutation)
 - **TypeScript:** 5.x strict (`noUncheckedIndexedAccess`, `exactOptionalPropertyTypes`), zero `any`
 
 ---
@@ -652,7 +815,7 @@ 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.61% mutation score** — verified with [Stryker](https://stryker-mutator.io/) at
+- ✅ **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
   ([report](./docs/mutation_testing_results.md))
@@ -687,6 +850,30 @@ values elsewhere), applies selective overrides, then runs the exact
 production pipeline (validate, freeze), so a test exercises the same code
 path a running application does.
 
+```typescript
+// Leaves createTestConfig fills without an override:
+defineEnv({
+  text: z.object({ a: z.string().min(8), b: z.email(), c: z.url(), d: z.uuid() }),
+  time: z.object({
+    at: z.iso.datetime(),
+    on: z.iso.date(),
+    clock: z.iso.time(),
+    when: z.coerce.date()
+  }),
+  scalar: z.object({
+    n: z.coerce.number().int().min(1),
+    flag: z.stringbool(),
+    kind: z.enum(['a', 'b']),
+    fixed: z.literal('x')
+  })
+})
+```
+
+A leaf no placeholder can be known to satisfy, such as a
+`z.string().regex(...)` or a `.refine(...)` rule, makes the helper throw a
+`BymaxConfigValidationError` whose issue says `no placeholder satisfies this leaf` and names it
+(`pass an override for region.code`); give that leaf an override and the helper builds.
+
 ```typescript
 import { createTestConfig } from '@bymax-one/nest-config/testing'
 import { envSchema } from './config/env.schema'
@@ -706,11 +893,18 @@ import { envSchema } from './config/env.schema'
 import { FeatureProvider } from './feature.provider'
 
 const moduleRef = await Test.createTestingModule({
-  imports: [configTestingModule(envSchema, { server: { port: 0 } })],
+  imports: [configTestingModule(envSchema, { server: { port: 8080 } })],
   providers: [FeatureProvider]
 }).compile()
 ```
 
+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
+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.
+
 Placeholder synthesis never fabricates values that could accidentally pass a
 secret-strength constraint; length and format constraints are honored. The
 subpath has no Jest dependency and works with any runner, though the family

package/dist/index.cjs

@@ -32,3 +32,7 @@ Object.defineProperty(exports, "defineEnv", {
   enumerable: true,
   get: function () { return internal.defineEnv; }
 });
+Object.defineProperty(exports, "resolveSourceNames", {
+  enumerable: true,
+  get: function () { return internal.resolveSourceNames; }
+});

package/dist/index.d.cts

@@ -1 +1 @@
-export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, BymaxConfigModuleOptions, BymaxConfigValidationError, ConfigErrorCode, ConfigIssue, ConfigIssueCode, ConfigService, ConfigValidationCode, EnvLeaf, EnvNamespace, EnvOutput, EnvSchema, EnvShape, Path, PathValue, defineEnv } from '@bymax-one/nest-config/internal';
+export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, BymaxConfigModuleOptions, BymaxConfigValidationError, ConfigErrorCode, ConfigIssue, ConfigIssueCode, ConfigService, ConfigValidationCode, EnvLeaf, EnvNamespace, EnvOutput, EnvSchema, EnvShape, Path, PathValue, SourceBinding, defineEnv, resolveSourceNames } from '@bymax-one/nest-config/internal';

package/dist/index.d.ts

@@ -1 +1 @@
-export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, BymaxConfigModuleOptions, BymaxConfigValidationError, ConfigErrorCode, ConfigIssue, ConfigIssueCode, ConfigService, ConfigValidationCode, EnvLeaf, EnvNamespace, EnvOutput, EnvSchema, EnvShape, Path, PathValue, defineEnv } from '@bymax-one/nest-config/internal';
+export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, BymaxConfigModuleOptions, BymaxConfigValidationError, ConfigErrorCode, ConfigIssue, ConfigIssueCode, ConfigService, ConfigValidationCode, EnvLeaf, EnvNamespace, EnvOutput, EnvSchema, EnvShape, Path, PathValue, SourceBinding, defineEnv, resolveSourceNames } from '@bymax-one/nest-config/internal';

package/dist/index.mjs

@@ -1 +1 @@
-export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, BymaxConfigValidationError, ConfigErrorCode, ConfigService, defineEnv } from '@bymax-one/nest-config/internal';
+export { BYMAX_CONFIG, BYMAX_CONFIG_OPTIONS, BymaxConfigModule, BymaxConfigValidationError, ConfigErrorCode, ConfigService, defineEnv, resolveSourceNames } from '@bymax-one/nest-config/internal';