@karmaniverous/get-dotenv 6.0.0-0 → 6.0.0

package/dist/config.d.ts

@@ -1,31 +1,188 @@
-type Scripts = Record<string, string | {
-    cmd: string;
+/**
+ * Minimal root options shape shared by CLI and generator layers.
+ * Keep keys optional to respect exactOptionalPropertyTypes semantics.
+ *
+ * @public
+ */
+interface RootOptionsShape {
+    /** Target environment (dotenv-expanded). */
+    env?: string;
+    /** Explicit variable overrides (dotenv-expanded). */
+    vars?: string;
+    /** Command to execute (dotenv-expanded). */
+    command?: string;
+    /** Output path for the consolidated environment file (dotenv-expanded). */
+    outputPath?: string;
+    /**
+     * Shell execution strategy.
+     * - `true`: use default OS shell.
+     * - `false`: use plain execution (no shell).
+     * - string: use specific shell path.
+     */
     shell?: string | boolean;
-}>;
-
-type GetDotenvConfigResolved = {
-    dotenvToken?: string;
-    privateToken?: string;
-    paths?: string[];
+    /** Whether to load variables into `process.env`. */
     loadProcess?: boolean;
+    /** Exclude all variables from loading. */
+    excludeAll?: boolean;
+    /** Exclude dynamic variables. */
+    excludeDynamic?: boolean;
+    /** Exclude environment-specific variables. */
+    excludeEnv?: boolean;
+    /** Exclude global variables. */
+    excludeGlobal?: boolean;
+    /** Exclude private variables. */
+    excludePrivate?: boolean;
+    /** Exclude public variables. */
+    excludePublic?: boolean;
+    /** Enable console logging of loaded variables. */
     log?: boolean;
-    shell?: string | boolean;
+    /** Enable debug logging to stderr. */
+    debug?: boolean;
+    /** Capture child process stdio (useful for tests/CI). */
+    capture?: boolean;
+    /** Fail on validation errors (schema/requiredKeys). */
+    strict?: boolean;
+    /** Enable presentation-time redaction of secret-like keys. */
+    redact?: boolean;
+    /** Enable entropy warnings for high-entropy values. */
+    warnEntropy?: boolean;
+    /** Entropy threshold (bits/char) for warnings (default 3.8). */
+    entropyThreshold?: number;
+    /** Minimum string length to check for entropy (default 16). */
+    entropyMinLength?: number;
+    /** Regex patterns for keys to exclude from entropy checks. */
+    entropyWhitelist?: ReadonlyArray<string>;
+    /** Additional regex patterns for keys to redact. */
+    redactPatterns?: string[];
+    /** Default target environment when not specified. */
+    defaultEnv?: string;
+    /** Token indicating a dotenv file (default: ".env"). */
+    dotenvToken?: string;
+    /** Path to dynamic variables module (default: undefined). */
+    dynamicPath?: string;
+    /**
+     * Emit diagnostics for child env composition.
+     * - `true`: trace all keys.
+     * - `string[]`: trace selected keys.
+     */
+    trace?: boolean | string[];
+    /** Paths to search for dotenv files (space-delimited string or array). */
+    paths?: string;
+    /** Delimiter for paths string (default: space). */
+    pathsDelimiter?: string;
+    /** Regex pattern for paths delimiter. */
+    pathsDelimiterPattern?: string;
+    /** Token indicating private variables (default: "local"). */
+    privateToken?: string;
+    /** Delimiter for vars string (default: space). */
+    varsDelimiter?: string;
+    /** Regex pattern for vars delimiter. */
+    varsDelimiterPattern?: string;
+    /** Assignment operator for vars (default: "="). */
+    varsAssignor?: string;
+    /** Regex pattern for vars assignment operator. */
+    varsAssignorPattern?: string;
+    /** Table of named scripts for execution. */
+    scripts?: ScriptsTable;
+}
+/**
+ * Definition for a single script entry.
+ */
+interface ScriptDef<TShell extends string | boolean = string | boolean> {
+    /** The command string to execute. */
+    cmd: string;
+    /** Shell override for this script. */
+    shell?: TShell | undefined;
+}
+/**
+ * Scripts table shape.
+ */
+type ScriptsTable<TShell extends string | boolean = string | boolean> = Record<string, string | ScriptDef<TShell>>;
+
+/**
+ * Canonical programmatic options and helpers for get-dotenv.
+ *
+ * Requirements addressed:
+ * - GetDotenvOptions derives from the Zod schema output (single source of truth).
+ * - Removed deprecated/compat flags from the public shape (e.g., useConfigLoader).
+ * - Provide Vars-aware defineDynamic and a typed config builder defineGetDotenvConfig\<Vars, Env\>().
+ * - Preserve existing behavior for defaults resolution and compat converters.
+ */
+
+/**
+ * A minimal representation of an environment key/value mapping.
+ * Values may be `undefined` to represent "unset".
+ */
+type ProcessEnv = Record<string, string | undefined>;
+
+/**
+ * Unify Scripts via the generic ScriptsTable<TShell> so shell types propagate.
+ */
+type Scripts = ScriptsTable;
+
+type GetDotenvConfigResolved = {
+    /**
+     * Help-time/runtime root defaults applied by the host (collapsed families; CLI‑like).
+     */
+    rootOptionDefaults?: Partial<RootOptionsShape>;
+    /**
+     * Help-time visibility for root flags; when a key is false the corresponding
+     * option(s) are hidden in root help output.
+     */
+    rootOptionVisibility?: Partial<Record<keyof RootOptionsShape, boolean>>;
+    /**
+     * Merged scripts table for resolving commands and shell behavior.
+     * Entries may be strings or objects with `cmd` and optional `shell`.
+     */
     scripts?: Scripts;
+    /**
+     * Keys required to be present in the final composed environment.
+     * Validation occurs after overlays and dynamics.
+     */
     requiredKeys?: string[];
+    /**
+     * Optional validation schema (e.g., Zod). When present and it exposes
+     * `safeParse(finalEnv)`, the host executes it once after overlays.
+     */
     schema?: unknown;
+    /**
+     * Public global variables (string‑only).
+     */
     vars?: Record<string, string>;
+    /**
+     * Public per‑environment variables (string‑only).
+     */
     envVars?: Record<string, Record<string, string>>;
+    /**
+     * Dynamic variable definitions (JS/TS configs only).
+     */
     dynamic?: unknown;
+    /**
+     * Per‑plugin configuration slices keyed by realized mount path
+     * (for example, "aws/whoami").
+     */
     plugins?: Record<string, unknown>;
 };
 
+/**
+ * Privacy scope of a configuration file ('public' is checked into git, 'local' is gitignored).
+ */
 type ConfigPrivacy = 'public' | 'local';
+/**
+ * Origin scope of a configuration file ('packaged' inside the library, 'project' in the consumer repo).
+ */
 type ConfigScope = 'packaged' | 'project';
-type ConfigFile = {
+/**
+ * Represents a discovered configuration file.
+ */
+interface ConfigFile {
+    /** Absolute path to the config file. */
     path: string;
+    /** Privacy scope (public vs local). */
     privacy: ConfigPrivacy;
+    /** Origin scope (packaged vs project). */
     scope: ConfigScope;
-};
+}
 /**
  * Discover JSON/YAML config files in the packaged root and project root.
  * Order: packaged public → project public → project local. */
@@ -38,18 +195,39 @@ declare const discoverConfigFiles: (importMetaUrl?: string) => Promise<ConfigFil
  * For JS/TS: default export is loaded; "dynamic" is allowed.
  */
 declare const loadConfigFile: (filePath: string) => Promise<GetDotenvConfigResolved>;
-type ResolvedConfigSources = {
+interface ResolvedConfigSources {
+    /** Configuration from the package root (public only). */
     packaged?: GetDotenvConfigResolved;
+    /** Configuration from the project root. */
     project?: {
+        /** Project public configuration. */
         public?: GetDotenvConfigResolved;
+        /** Project local configuration. */
         local?: GetDotenvConfigResolved;
     };
-};
+}
 /**
  * Discover and load configs into resolved shapes, ordered by scope/privacy.
  * JSON/YAML/JS/TS supported; first match per scope/privacy applies.
  */
 declare const resolveGetDotenvConfigSources: (importMetaUrl?: string) => Promise<ResolvedConfigSources>;
+/**
+ * Utility primarily for tests: create a file: URL string from a path.
+ * @param p - File path.
+ */
 declare const toFileUrl: (p: string) => string;
 
-export { discoverConfigFiles, loadConfigFile, resolveGetDotenvConfigSources, toFileUrl };
+/**
+ * Validate a composed env against config-provided validation surfaces.
+ * Precedence for validation definitions:
+ *   project.local -\> project.public -\> packaged
+ *
+ * Behavior:
+ * - If a JS/TS `schema` is present, use schema.safeParse(finalEnv).
+ * - Else if `requiredKeys` is present, check presence (value !== undefined).
+ * - Returns a flat list of issue strings; caller decides warn vs fail.
+ */
+declare const validateEnvAgainstSources: (finalEnv: ProcessEnv, sources: ResolvedConfigSources) => string[];
+
+export { discoverConfigFiles, loadConfigFile, resolveGetDotenvConfigSources, toFileUrl, validateEnvAgainstSources };
+export type { ConfigFile, ConfigPrivacy, ConfigScope, ResolvedConfigSources };

package/dist/config.mjs

@@ -1,30 +1,98 @@
 import fs from 'fs-extra';
 import { packageDirectory } from 'package-directory';
 import path, { join, extname } from 'path';
-import { pathToFileURL, fileURLToPath } from 'url';
+import url, { pathToFileURL, fileURLToPath } from 'url';
 import YAML from 'yaml';
 import { z } from 'zod';
+import { createHash } from 'crypto';
 
+/**
+ * Zod schemas for programmatic GetDotenv options.
+ *
+ * Canonical source of truth for options shape. Public types are derived
+ * from these schemas (see consumers via z.output\<\>).
+ */
+/**
+ * Minimal process env representation used by options and helpers.
+ * Values may be `undefined` to indicate "unset".
+ */
+const processEnvSchema = z.record(z.string(), z.string().optional());
+// RAW: all fields optional — undefined means "inherit" from lower layers.
+const getDotenvOptionsSchemaRaw = z.object({
+    defaultEnv: z.string().optional(),
+    dotenvToken: z.string().optional(),
+    dynamicPath: z.string().optional(),
+    // Dynamic map is intentionally wide for now; refine once sources are normalized.
+    dynamic: z.record(z.string(), z.unknown()).optional(),
+    env: z.string().optional(),
+    excludeDynamic: z.boolean().optional(),
+    excludeEnv: z.boolean().optional(),
+    excludeGlobal: z.boolean().optional(),
+    excludePrivate: z.boolean().optional(),
+    excludePublic: z.boolean().optional(),
+    loadProcess: z.boolean().optional(),
+    log: z.boolean().optional(),
+    logger: z.unknown().default(console),
+    outputPath: z.string().optional(),
+    paths: z.array(z.string()).optional(),
+    privateToken: z.string().optional(),
+    vars: processEnvSchema.optional(),
+});
+
+/**
+ * Zod schemas for CLI-facing GetDotenv options (raw/resolved stubs).
+ *
+ * RAW allows stringly inputs (paths/vars + splitters). RESOLVED will later
+ * reflect normalized types (paths: string[], vars: ProcessEnv), applied in the
+ * CLI resolution pipeline.
+ */
+const getDotenvCliOptionsSchemaRaw = getDotenvOptionsSchemaRaw.extend({
+    // CLI-specific fields (stringly inputs before preprocessing)
+    debug: z.boolean().optional(),
+    strict: z.boolean().optional(),
+    capture: z.boolean().optional(),
+    trace: z.union([z.boolean(), z.array(z.string())]).optional(),
+    redact: z.boolean().optional(),
+    warnEntropy: z.boolean().optional(),
+    entropyThreshold: z.number().optional(),
+    entropyMinLength: z.number().optional(),
+    entropyWhitelist: z.array(z.string()).optional(),
+    redactPatterns: z.array(z.string()).optional(),
+    paths: z.string().optional(),
+    pathsDelimiter: z.string().optional(),
+    pathsDelimiterPattern: z.string().optional(),
+    scripts: z.record(z.string(), z.unknown()).optional(),
+    shell: z.union([z.boolean(), z.string()]).optional(),
+    vars: z.string().optional(),
+    varsAssignor: z.string().optional(),
+    varsAssignorPattern: z.string().optional(),
+    varsDelimiter: z.string().optional(),
+    varsDelimiterPattern: z.string().optional(),
+});
+
+const visibilityMap = z.record(z.string(), z.boolean());
 /**
  * Zod schemas for configuration files discovered by the new loader.
  *
  * Notes:
- * - RAW: all fields optional; shapes are stringly-friendly (paths may be string[] or string).
- * - RESOLVED: normalized shapes (paths always string[]).
- * - For JSON/YAML configs, the loader rejects "dynamic" and "schema" (JS/TS-only).
+ * - RAW: all fields optional; only allowed top-level keys are:
+ *   - rootOptionDefaults, rootOptionVisibility
+ *   - scripts, vars, envVars
+ *   - dynamic (JS/TS only), schema (JS/TS only)
+ *   - plugins, requiredKeys
+ * - RESOLVED: mirrors RAW (no path normalization).
+ * - For JSON/YAML configs, the loader rejects "dynamic" and "schema" (JS/TS only).
  */
 // String-only env value map
 const stringMap = z.record(z.string(), z.string());
 const envStringMap = z.record(z.string(), stringMap);
-// Allow string[] or single string for "paths" in RAW; normalize later.
-const rawPathsSchema = z.union([z.array(z.string()), z.string()]).optional();
+/**
+ * Raw configuration schema for get‑dotenv config files (JSON/YAML/JS/TS).
+ * Validates allowed top‑level keys without performing path normalization.
+ */
 const getDotenvConfigSchemaRaw = z.object({
-    dotenvToken: z.string().optional(),
-    privateToken: z.string().optional(),
-    paths: rawPathsSchema,
-    loadProcess: z.boolean().optional(),
-    log: z.boolean().optional(),
-    shell: z.union([z.string(), z.boolean()]).optional(),
+    rootOptionDefaults: getDotenvCliOptionsSchemaRaw.optional(),
+    rootOptionVisibility: visibilityMap.optional(),
     scripts: z.record(z.string(), z.unknown()).optional(), // Scripts validation left wide; generator validates elsewhere
     requiredKeys: z.array(z.string()).optional(),
     schema: z.unknown().optional(), // JS/TS-only; loader rejects in JSON/YAML
@@ -35,109 +103,157 @@ const getDotenvConfigSchemaRaw = z.object({
     // Per-plugin config bag; validated by plugins/host when used.
     plugins: z.record(z.string(), z.unknown()).optional(),
 });
-// Normalize paths to string[]
-const normalizePaths = (p) => p === undefined ? undefined : Array.isArray(p) ? p : [p];
-const getDotenvConfigSchemaResolved = getDotenvConfigSchemaRaw.transform((raw) => ({
-    ...raw,
-    paths: normalizePaths(raw.paths),
-}));
+/**
+ * Resolved configuration schema which preserves the raw shape while narrowing
+ * the output to {@link GetDotenvConfigResolved}. Consumers get a strongly typed
+ * object, while the underlying validation remains Zod‑driven.
+ */
+const getDotenvConfigSchemaResolved = getDotenvConfigSchemaRaw.transform((raw) => raw);
 
-// Discovery candidates (first match wins per scope/privacy).
-// Order preserves historical JSON/YAML precedence; JS/TS added afterwards.
-const PUBLIC_FILENAMES = [
-    'getdotenv.config.json',
-    'getdotenv.config.yaml',
-    'getdotenv.config.yml',
-    'getdotenv.config.js',
-    'getdotenv.config.mjs',
-    'getdotenv.config.cjs',
-    'getdotenv.config.ts',
-    'getdotenv.config.mts',
-    'getdotenv.config.cts',
-];
-const LOCAL_FILENAMES = [
-    'getdotenv.config.local.json',
-    'getdotenv.config.local.yaml',
-    'getdotenv.config.local.yml',
-    'getdotenv.config.local.js',
-    'getdotenv.config.local.mjs',
-    'getdotenv.config.local.cjs',
-    'getdotenv.config.local.ts',
-    'getdotenv.config.local.mts',
-    'getdotenv.config.local.cts',
-];
-const isYaml = (p) => ['.yaml', '.yml'].includes(extname(p).toLowerCase());
-const isJson = (p) => extname(p).toLowerCase() === '.json';
-const isJsOrTs = (p) => ['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts'].includes(extname(p).toLowerCase());
-// --- Internal JS/TS module loader helpers (default export) ---
 const importDefault = async (fileUrl) => {
     const mod = (await import(fileUrl));
     return mod.default;
 };
-const cacheName = (absPath, suffix) => {
-    // sanitized filename with suffix; recompile on mtime changes not tracked here (simplified)
-    const base = path.basename(absPath).replace(/[^a-zA-Z0-9._-]/g, '_');
-    return `${base}.${suffix}.mjs`;
-};
-const ensureDir = async (dir) => {
-    await fs.ensureDir(dir);
-    return dir;
+const cacheHash = (absPath, mtimeMs) => createHash('sha1')
+    .update(absPath)
+    .update(String(mtimeMs))
+    .digest('hex')
+    .slice(0, 12);
+/**
+ * Remove older compiled cache files for a given source base name, keeping
+ * at most `keep` most-recent files. Errors are ignored by design.
+ */
+const cleanupOldCacheFiles = async (cacheDir, baseName, keep = Math.max(1, Number.parseInt(process.env.GETDOTENV_CACHE_KEEP ?? '2'))) => {
+    try {
+        const entries = await fs.readdir(cacheDir);
+        const mine = entries
+            .filter((f) => f.startsWith(`${baseName}.`) && f.endsWith('.mjs'))
+            .map((f) => path.join(cacheDir, f));
+        if (mine.length <= keep)
+            return;
+        const stats = await Promise.all(mine.map(async (p) => ({ p, mtimeMs: (await fs.stat(p)).mtimeMs })));
+        stats.sort((a, b) => b.mtimeMs - a.mtimeMs);
+        const toDelete = stats.slice(keep).map((s) => s.p);
+        await Promise.all(toDelete.map(async (p) => {
+            try {
+                await fs.remove(p);
+            }
+            catch {
+                // best-effort cleanup
+            }
+        }));
+    }
+    catch {
+        // best-effort cleanup
+    }
 };
-const loadJsTsDefault = async (absPath) => {
-    const fileUrl = pathToFileURL(absPath).toString();
-    const ext = extname(absPath).toLowerCase();
-    if (ext === '.js' || ext === '.mjs' || ext === '.cjs') {
+/**
+ * Load a module default export from a JS/TS file with robust fallbacks:
+ * - .js/.mjs/.cjs: direct import * - .ts/.mts/.cts/.tsx:
+ *   1) try direct import (if a TS loader is active),
+ *   2) esbuild bundle to a temp ESM file,
+ *   3) typescript.transpileModule fallback for simple modules.
+ *
+ * @param absPath - absolute path to source file
+ * @param cacheDirName - cache subfolder under .tsbuild
+ */
+const loadModuleDefault = async (absPath, cacheDirName) => {
+    const ext = path.extname(absPath).toLowerCase();
+    const fileUrl = url.pathToFileURL(absPath).toString();
+    if (!['.ts', '.mts', '.cts', '.tsx'].includes(ext)) {
         return importDefault(fileUrl);
     }
-    // Try direct import first in case a TS loader is active.
+    // Try direct import first (TS loader active)
     try {
-        const val = await importDefault(fileUrl);
-        if (val)
-            return val;
+        const dyn = await importDefault(fileUrl);
+        if (dyn)
+            return dyn;
     }
     catch {
-        /* fallthrough */
+        /* fall through */
     }
-    // esbuild bundle to a temp ESM file
+    const stat = await fs.stat(absPath);
+    const hash = cacheHash(absPath, stat.mtimeMs);
+    const cacheDir = path.resolve('.tsbuild', cacheDirName);
+    await fs.ensureDir(cacheDir);
+    const cacheFile = path.join(cacheDir, `${path.basename(absPath)}.${hash}.mjs`);
+    // Try esbuild
     try {
         const esbuild = (await import('esbuild'));
-        const outDir = await ensureDir(path.resolve('.tsbuild', 'getdotenv-config'));
-        const outfile = path.join(outDir, cacheName(absPath, 'bundle'));
         await esbuild.build({
             entryPoints: [absPath],
             bundle: true,
             platform: 'node',
             format: 'esm',
             target: 'node20',
-            outfile,
+            outfile: cacheFile,
             sourcemap: false,
             logLevel: 'silent',
         });
-        return await importDefault(pathToFileURL(outfile).toString());
+        const result = await importDefault(url.pathToFileURL(cacheFile).toString());
+        // Best-effort: trim older cache files for this source.
+        await cleanupOldCacheFiles(cacheDir, path.basename(absPath));
+        return result;
     }
     catch {
-        /* fallthrough to TS transpile */
+        /* fall through to TS transpile */
     }
-    // typescript.transpileModule simple transpile (single-file)
+    // TypeScript transpile fallback
     try {
         const ts = (await import('typescript'));
-        const src = await fs.readFile(absPath, 'utf-8');
-        const out = ts.transpileModule(src, {
+        const code = await fs.readFile(absPath, 'utf-8');
+        const out = ts.transpileModule(code, {
             compilerOptions: {
                 module: 'ESNext',
                 target: 'ES2022',
                 moduleResolution: 'NodeNext',
             },
         }).outputText;
-        const outDir = await ensureDir(path.resolve('.tsbuild', 'getdotenv-config'));
-        const outfile = path.join(outDir, cacheName(absPath, 'ts'));
-        await fs.writeFile(outfile, out, 'utf-8');
-        return await importDefault(pathToFileURL(outfile).toString());
+        await fs.writeFile(cacheFile, out, 'utf-8');
+        const result = await importDefault(url.pathToFileURL(cacheFile).toString());
+        // Best-effort: trim older cache files for this source.
+        await cleanupOldCacheFiles(cacheDir, path.basename(absPath));
+        return result;
     }
     catch {
-        throw new Error(`Unable to load JS/TS config: ${absPath}. Install 'esbuild' for robust bundling or ensure a TS loader.`);
+        // Caller decides final error wording; rethrow for upstream mapping.
+        throw new Error(`Unable to load JS/TS module: ${absPath}. Install 'esbuild' or ensure a TS loader.`);
     }
 };
+
+/**
+ * @packageDocumentation
+ * Configuration discovery and loading for get‑dotenv. Discovers config files
+ * in the packaged root and project root, loads JSON/YAML/JS/TS documents, and
+ * validates them against Zod schemas.
+ */
+// Discovery candidates (first match wins per scope/privacy).
+// Order preserves historical JSON/YAML precedence; JS/TS added afterwards.
+const PUBLIC_FILENAMES = [
+    'getdotenv.config.json',
+    'getdotenv.config.yaml',
+    'getdotenv.config.yml',
+    'getdotenv.config.js',
+    'getdotenv.config.mjs',
+    'getdotenv.config.cjs',
+    'getdotenv.config.ts',
+    'getdotenv.config.mts',
+    'getdotenv.config.cts',
+];
+const LOCAL_FILENAMES = [
+    'getdotenv.config.local.json',
+    'getdotenv.config.local.yaml',
+    'getdotenv.config.local.yml',
+    'getdotenv.config.local.js',
+    'getdotenv.config.local.mjs',
+    'getdotenv.config.local.cjs',
+    'getdotenv.config.local.ts',
+    'getdotenv.config.local.mts',
+    'getdotenv.config.local.cts',
+];
+const isYaml = (p) => ['.yaml', '.yml'].includes(extname(p).toLowerCase());
+const isJson = (p) => extname(p).toLowerCase() === '.json';
+const isJsOrTs = (p) => ['.js', '.mjs', '.cjs', '.ts', '.mts', '.cts'].includes(extname(p).toLowerCase());
 /**
  * Discover JSON/YAML config files in the packaged root and project root.
  * Order: packaged public → project public → project local. */
@@ -190,8 +306,8 @@ const loadConfigFile = async (filePath) => {
     try {
         const abs = path.resolve(filePath);
         if (isJsOrTs(abs)) {
-            // JS/TS support: load default export via robust pipeline.
-            const mod = await loadJsTsDefault(abs);
+            // JS/TS support: load default export via shared robust pipeline.
+            const mod = await loadModuleDefault(abs, 'getdotenv-config');
             raw = mod ?? {};
         }
         else {
@@ -241,7 +357,66 @@ const resolveGetDotenvConfigSources = async (importMetaUrl) => {
     }
     return result;
 };
-// Utility primarily for tests: create a file: URL string from a path
+/**
+ * Utility primarily for tests: create a file: URL string from a path.
+ * @param p - File path.
+ */
 const toFileUrl = (p) => pathToFileURL(path.resolve(p)).toString();
 
-export { discoverConfigFiles, loadConfigFile, resolveGetDotenvConfigSources, toFileUrl };
+/**
+ * Validate a composed env against config-provided validation surfaces.
+ * Precedence for validation definitions:
+ *   project.local -\> project.public -\> packaged
+ *
+ * Behavior:
+ * - If a JS/TS `schema` is present, use schema.safeParse(finalEnv).
+ * - Else if `requiredKeys` is present, check presence (value !== undefined).
+ * - Returns a flat list of issue strings; caller decides warn vs fail.
+ */
+const validateEnvAgainstSources = (finalEnv, sources) => {
+    const pick = (getter) => {
+        const pl = sources.project?.local;
+        const pp = sources.project?.public;
+        const pk = sources.packaged;
+        return ((pl && getter(pl)) ||
+            (pp && getter(pp)) ||
+            (pk && getter(pk)) ||
+            undefined);
+    };
+    const schema = pick((cfg) => cfg['schema']);
+    if (schema &&
+        typeof schema.safeParse === 'function') {
+        try {
+            const parsed = schema.safeParse(finalEnv);
+            if (!parsed.success) {
+                // Try to render zod-style issues when available.
+                const err = parsed.error;
+                const issues = Array.isArray(err.issues) && err.issues.length > 0
+                    ? err.issues.map((i) => {
+                        const path = Array.isArray(i.path) ? i.path.join('.') : '';
+                        const msg = i.message ?? 'Invalid value';
+                        return path ? `[schema] ${path}: ${msg}` : `[schema] ${msg}`;
+                    })
+                    : ['[schema] validation failed'];
+                return issues;
+            }
+            return [];
+        }
+        catch {
+            // If schema invocation fails, surface a single diagnostic.
+            return [
+                '[schema] validation failed (unable to execute schema.safeParse)',
+            ];
+        }
+    }
+    const requiredKeys = pick((cfg) => cfg['requiredKeys']);
+    if (Array.isArray(requiredKeys) && requiredKeys.length > 0) {
+        const missing = requiredKeys.filter((k) => finalEnv[k] === undefined);
+        if (missing.length > 0) {
+            return missing.map((k) => `[requiredKeys] missing: ${k}`);
+        }
+    }
+    return [];
+};
+
+export { discoverConfigFiles, loadConfigFile, resolveGetDotenvConfigSources, toFileUrl, validateEnvAgainstSources };