Config Drift Guard

Schema-driven configuration resolution and drift diffing. Zero runtime dependencies, zero I/O: you pass raw string sources -- files you already parsed, process.env, CLI flags you already parsed -- plus a schema, and it returns the typed value, that value's PROVENANCE, and whether two environments have quietly diverged.

THE SILENT FAILURE. Configuration is strings, and JavaScript is eager to turn strings into whatever the surrounding code needs. Nothing throws. The application runs as though it were configured differently than it actually is, and every symptom looks like something else.

"false" IS TRUTHY. if (process.env.ENABLE_X) is true when ENABLE_X="false". The flag intended to disable a feature enables it, and the config file reads exactly as the author intended. This is the single most common configuration bug in the language, precisely because the code that trips over it looks correct.

Number("") IS 0. An unset-but-present variable becomes a valid-looking zero: a timeout of 0, a retry count of 0, a port of 0 -- which binds a random port instead of failing to bind. Number(undefined) is NaN, which at least propagates visibly; the empty string is the quiet one, because 0 is a value everything downstream accepts without complaint.

DEV DEFAULTS REACH PRODUCTION. DATABASE_URL ?? "postgres://localhost" means a production deploy missing that variable starts SUCCESSFULLY and points at nothing -- or at whatever localhost resolves to in that container. The service is up, the health check passes, and the data goes somewhere else.

DRIFT. Staging and production diverge one manual edit at a time. The bug that surfaces in production cannot be reproduced in staging, and the fix cannot be verified anywhere it matters.

Every resolved value carries where it came from, so 'why is this value what it is' has an answer that does not require guessing at precedence.

VERIFIED: 72 tests, re-measured by running the suite, 11/11 mutations killed. An adversarial reviewer found that it PRINTED A SECRET IN CLEARTEXT: redaction was chosen from the side being printed, so diffing a schema that marked a key secret against a drifted copy that had lost the flag produced left=[REDACTED] right="sk-live-...". Redaction is now the union of both sides, and the case is covered by tests.

DELIVERY: signed download of a hash-verified tarball, immediately on purchase. Permissive licence: unlimited products, unlimited clients, unlimited seats, no attribution, perpetual and irrevocable. One restriction, do not republish the source as source.

Interface

What you call, and what comes back. Types and signatures only — the implementation ships with the source.

  export function diffConfigs(left: ResolvedConfig, right: ResolvedConfig): DiffReport;
  export function formatDiffReport(report: DiffReport): string;
  export function parseBoolean(raw: string): ParseResult;
  export function parseNumber(raw: string, spec: NumberConstraints): ParseResult;
  export function parseString(raw: string, spec: StringConstraints): ParseResult;
  export function parseEnum(raw: string, values: readonly string[]): ParseResult;
  export function parseField(raw: string, spec: FieldSpec): ParseResult;
  export function toPlainValues(config: ResolvedConfig): Record<string, FieldValue>;
  export function toRedactedValues(config: ResolvedConfig): Record<string, unknown>;
  export function toSourceMap(config: ResolvedConfig): Record<string, string>;
  export function resolveConfig( schema: Schema, sources: readonly ConfigSource[], options: ResolveOptions, ): ResolveResult;

  export type DiffKind = 'missing-left' | 'missing-right' | 'value-differs' | 'type-differs' | 'source-differs' | 'same';
  export type ParseResult = | { readonly ok: true;
  export type Environment = string;
  export type FieldSpec = BooleanFieldSpec | NumberFieldSpec | StringFieldSpec | EnumFieldSpec;
  export type Schema = Readonly<Record<string, FieldSpec>>;
  export type FieldValue = boolean | number | string | undefined;