molex-env 0.2.5 → 0.3.1

package/README.md

@@ -16,6 +16,7 @@
 - **Type-safe parsing** - Automatic conversion of booleans, numbers, JSON, and dates
 - **Strict validation** - Schema enforcement with required fields and type checking
 - **Origin tracking** - Know exactly which file and line each value came from
+- **Debug mode** - See which files override values during cascading
 - **Immutable config** - Deep-freeze protection prevents accidental modifications
 - **Live reload** - Watch mode automatically reloads on file changes
 - **Deterministic merging** - Predictable cascading from base to profile files
@@ -125,8 +126,8 @@ OPTIONAL_KEY=
 
 Files are loaded and merged in this order (later files override earlier ones):
 
-1. `.menv` - Base configuration (committed to git)
-2. `.menv.local` - Local overrides (ignored by git)
+1. `.menv` - Base configuration
+2. `.menv.local` - Local overrides
 3. `.menv.{profile}` - Profile-specific config (e.g., `.menv.prod`)
 4. `.menv.{profile}.local` - Profile + local overrides (e.g., `.menv.prod.local`)
 
@@ -139,6 +140,18 @@ Files are loaded and merged in this order (later files override earlier ones):
 Final result: PORT=9000, DEBUG=false
 ```
 
+**Debug mode** - Use `debug: true` to see which files override values:
+```javascript
+load({ profile: 'prod', debug: true });
+// Console output:
+// [molex-env] Override: DEBUG
+//   Previous: .menv:2 = true
+//   New:      .menv.local:1 = false
+// [molex-env] Override: PORT
+//   Previous: .menv.local:3 = 3000
+//   New:      .menv.prod:1 = 8080
+```
+
 ## API Reference
 
 ### `load(options)` → `Object`
@@ -153,12 +166,13 @@ Load, merge, parse, and validate .menv files. This is the primary method you'll
 | `profile` | `string` | `undefined` | Profile name for `.menv.{profile}` files |
 | `files` | `Array<string>` | Auto-detected | Custom file list (absolute or relative to cwd) |
 | `schema` | `Object` | `{}` | Schema definition for validation and typing |
-| `strict` | `boolean` | `false` | Reject unknown keys, duplicates, and invalid lines |
+| `strict` | `boolean` | `false` | Reject unknown keys, within-file duplicates, and invalid lines |
 | `cast` | `boolean\|Object` | `true` | Enable/disable type casting (see Type Casting) |
 | `exportEnv` | `boolean` | `false` | Write parsed values to `process.env` |
 | `override` | `boolean` | `false` | Override existing `process.env` values |
 | `attach` | `boolean` | `true` | Attach parsed values to `process.menv` |
 | `freeze` | `boolean` | `true` | Deep-freeze the parsed config object |
+| `debug` | `boolean` | `false` | Log file precedence overrides to console |
 | `onWarning` | `Function` | `undefined` | Callback for non-strict warnings |
 
 **Returns:**
@@ -213,10 +227,12 @@ Parse a string of .menv content without loading files. Useful for testing or pro
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
 | `schema` | `Object` | `{}` | Schema definition for validation |
-| `strict` | `boolean` | `false` | Enable strict validation |
+| `strict` | `boolean` | `false` | Enable strict validation (rejects unknown keys, within-file duplicates, invalid lines) |
 | `cast` | `boolean\|Object` | `true` | Enable/disable type casting |
 | `freeze` | `boolean` | `true` | Deep-freeze the result |
 
+> **Note:** The `parse()` function processes a single string, so the `debug` option for file precedence and cross-file features don't apply here.
+
 **Returns:**
 
 ```javascript
@@ -261,23 +277,62 @@ Watch .menv files and reload automatically when they change. Perfect for develop
 
 **Arguments:**
 
-- `options` - Same options as `load()`
+- `options` - Same options as `load()`, including `debug` for automatic change logging
 - `onChange(error, result)` - Callback fired on file changes
 
-**Example:**
+**Automatic Change Detection:**
+
+When `debug: true` is enabled, watch mode automatically logs what values changed on each reload:
 
 ```javascript
 const { watch } = require('molex-env');
 
-// Watch with callback
-watch({ profile: 'dev', strict: true }, (err, result) => {
+watch({ 
+  profile: 'dev',
+  debug: true,  // Automatically logs changes
+  schema: {
+    PORT: 'number',
+    DEBUG: 'boolean',
+    SERVICE_URL: 'string'
+  }
+}, (err, result) => {
+  if (err) {
+    console.error('Config reload failed:', err.message);
+    return;
+  }
+  console.log('✅ Config successfully reloaded');
+});
+
+// When you edit .menv files, automatic output:
+// [molex-env] Config reloaded - changes detected:
+//   PORT: 3000 → 8080
+//   SERVICE_URL: https://api.example.com → https://api.production.com
+// ✅ Config successfully reloaded
+```
+
+**Manual Change Detection:**
+
+Without `debug: true`, you can manually detect changes in your callback:
+
+```javascript
+let currentConfig;
+
+watch({ profile: 'dev' }, (err, result) => {
   if (err) {
     console.error('Config reload failed:', err.message);
     return;
   }
   
-  console.log('Config reloaded!');
-  console.log('New PORT:', result.parsed.PORT);
+  if (!currentConfig) {
+    console.log('Initial config loaded');
+  } else {
+    // Manually check what changed
+    if (currentConfig.PORT !== result.parsed.PORT) {
+      console.log(`PORT changed: ${currentConfig.PORT} → ${result.parsed.PORT}`);
+    }
+  }
+  
+  currentConfig = result.parsed;
   
   // Restart your server or update app state here
   if (global.server) {
@@ -309,10 +364,17 @@ function startServer(config) {
 const initial = require('molex-env').load({ profile: 'dev' });
 server = startServer(initial.parsed);
 
-// Watch for changes
-watch({ profile: 'dev' }, (err, result) => {
+// Watch for changes with automatic change logging
+watch({ 
+  profile: 'dev',
+  debug: true,
+  schema: {
+    PORT: 'number',
+    DEBUG: 'boolean'
+  }
+}, (err, result) => {
   if (!err && result.parsed.PORT !== initial.parsed.PORT) {
-    console.log('Port changed, restarting...');
+    console.log('Port changed, restarting server...');
     server.close(() => {
       server = startServer(result.parsed);
     });
@@ -452,9 +514,10 @@ Strict mode provides rigorous validation to catch configuration errors early.
 
 When `strict: true`:
 - ❌ **Unknown keys** - Keys not in schema are rejected
-- ❌ **Duplicate keys** - Same key in multiple files throws error
+- ❌ **Duplicate keys** - Same key appearing twice **in the same file** throws error
+  - **Note:** File precedence still works - different files can define the same key
 - ❌ **Invalid lines** - Malformed lines throw errors
-- ❌ **Type mismatches** - Values that can't be parsed as specified type
+- ✅ **Type validation** - When schema is present, type mismatches throw errors (enabled by default with schema)
 
 **Example:**
 
@@ -473,28 +536,56 @@ load({
 });
 ```
 
+**Valid with strict mode (different files):**
+```javascript
+// .menv
+PORT=3000
+
+// .menv.prod
+PORT=8080  // ✅ OK - overrides from different file
+
+load({ profile: 'prod', strict: true });
+// Result: PORT=8080
+```
+
+**Invalid with strict mode (same file):**
+```javascript
+// .menv
+PORT=3000
+PORT=8080  // ❌ ERROR - duplicate in same file
+
+load({ strict: true });  // Throws error
+```
+
 ### Non-Strict Mode (Default)
 
-Without strict mode:
+Without strict mode, the file precedence feature works as intended:
 - ✅ Unknown keys are allowed and parsed
-- ✅ Duplicates override (later files win)
+- ✅ **Duplicate keys override** - Later files can override keys from earlier files
 - ✅ Invalid lines are skipped
-- ⚠️  Warnings can be logged via `onWarning` callback
+- ⚠️  Warnings can be logged via `onWarning` callback for within-file duplicates
 
 **Example with warning handler:**
 
 ```javascript
+// .menv file with duplicate keys
+// PORT=3000
+// PORT=8080
+
 load({
-  schema: { PORT: 'number' },
   strict: false,
   onWarning: (info) => {
-    console.warn(`Warning: ${info.key} redefined`);
-    console.warn(`  Previous: ${info.previous.file}:${info.previous.line}`);
-    console.warn(`  New:      ${info.next.file}:${info.next.line}`);
+    if (info.type === 'duplicate') {
+      console.warn(`Warning: Duplicate key '${info.key}' in ${info.file}:${info.line}`);
+    }
   }
 });
+// Output: Warning: Duplicate key 'PORT' in .menv:2
+// Result: PORT=8080 (last value wins)
 ```
 
+**Tip:** Use `debug: true` to see cross-file overrides (file precedence), or `onWarning` to catch within-file duplicates.
+
 ---
 
 ## Origin Tracking
@@ -612,10 +703,9 @@ console.log(`PORT: ${process.menv.PORT}`);
 ```javascript
 const { watch } = require('molex-env');
 
-let currentConfig;
-
 watch({
   profile: 'dev',
+  debug: true,  // Automatic change detection
   schema: {
     PORT: 'number',
     DEBUG: 'boolean',
@@ -627,24 +717,15 @@ watch({
     return;
   }
   
-  const changed = [];
-  if (!currentConfig) {
-    console.log('Initial config loaded');
-  } else {
-    // Detect what changed
-    Object.keys(result.parsed).forEach(key => {
-      if (currentConfig[key] !== result.parsed[key]) {
-        changed.push(`${key}: ${currentConfig[key]} → ${result.parsed[key]}`);
-      }
-    });
-    
-    if (changed.length > 0) {
-      console.log('Config updated:', changed.join(', '));
-    }
-  }
-  
-  currentConfig = result.parsed;
+  console.log('Config reloaded and ready to use');
+  // result.parsed has the new values
 });
+
+console.log('Watching for changes...');
+// Output on file change:
+// [molex-env] Config reloaded - changes detected:
+//   DEBUG: false → true
+//   API_URL: https://api.example.com → https://api.dev.local
 ```
 
 ### Validation and Error Handling
@@ -685,34 +766,19 @@ try {
 
 ## Best Practices
 
-### Git Configuration
-
-Add to `.gitignore`:
-```gitignore
-# Keep base configs in git
-# .menv
-# .menv.dev
-# .menv.prod
-
-# Ignore local overrides (machine-specific, secrets)
-.menv.local
-.menv.*.local
-```
-
 ### Environment Strategy
 
 ```
 Development:   .menv + .menv.local
 Staging:       .menv + .menv.staging
-Production:    .menv + .menv.prod + .menv.prod.local (secrets)
+Production:    .menv + .menv.prod + .menv.prod.local
 ```
 
 ### Security Tips
 
-- ✅ **DO** use `.menv.local` for secrets and add to `.gitignore`
-- ✅ **DO** use `strict: true` in production to catch misconfigurations
+- ✅ **DO** use `strict: true` in production to catch unknown keys and configuration errors
+- ✅ **DO** use `debug: true` during development to understand file precedence
 - ✅ **DO** validate sensitive values (URLs, ports, etc.) after loading
-- ❌ **DON'T** commit production secrets to git
 - ❌ **DON'T** use `exportEnv: true` if you need immutable config
 
 ### Performance
@@ -748,11 +814,25 @@ The example demonstrates:
 
 **Problem:** Getting errors about unknown keys when loading config.
 
-**Solution:** Add all keys to your schema or disable strict mode:
+**Cause:** You have a key in your `.menv` file that isn't defined in your schema, and `strict: true` is enabled.
+
+**Solution:** Either add the key to your schema or disable strict mode:
 ```javascript
-load({ strict: false });  // Allow unknown keys
+// Option 1: Add missing key to schema
+load({ 
+  strict: true,
+  schema: { 
+    PORT: 'number',
+    YOUR_MISSING_KEY: 'string'  // Add this
+  }
+});
+
+// Option 2: Disable strict mode to allow unknown keys
+load({ strict: false });
 ```
 
+> **Note:** This is different from "required" - unknown keys exist in your file but not in schema. Required keys exist in schema but not in your file.
+
 ### Values are strings instead of typed
 
 **Problem:** `PORT` is `"3000"` (string) instead of `3000` (number).
@@ -786,6 +866,22 @@ METADATA={"key":"value"}
 START_DATE=2026-02-02
 ```
 
+### Understanding which file sets a value
+
+**Problem:** Not sure which file is providing a specific config value.
+
+**Solution:** Use `debug: true` to see file precedence in action:
+```javascript
+load({ profile: 'prod', debug: true });
+// Shows console output for each override
+```
+
+Or check the `origins` object:
+```javascript
+const result = load({ profile: 'prod' });
+console.log(result.origins.PORT);  // { file: '.menv.prod', line: 1, raw: '8080' }
+```
+
 ---
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "molex-env",
-  "version": "0.2.5",
+  "version": "0.3.1",
   "description": "Native .menv loader with profiles, typing, and origin tracking.",
   "main": "src/index.js",
   "files": [

package/src/lib/apply.js

@@ -5,15 +5,15 @@ const { coerceType, autoCast } = require('./cast');
 
 /**
  * Apply a parsed entry to the state with schema/type checks.
- * @param {{values: object, origins: object, seen: Set<string>}} state
+ * @param {{values: object, origins: object, seenPerFile: Map<string, Set<string>>}} state
  * @param {{key: string, raw: string, line: number}} entry
- * @param {{schema: object|null, strict: boolean, cast: object, onWarning?: Function}} options
+ * @param {{schema: object|null, strict: boolean, cast: object, onWarning?: Function, debug?: boolean}} options
  * @param {string} filePath
  * @returns {void}
  */
 function applyEntry(state, entry, options, filePath)
 {
-    const { schema, strict, cast, onWarning } = options;
+    const { schema, strict, cast, onWarning, debug } = options;
     const { key, raw, line } = entry;
 
     if (schema && strict && !schema[key])
@@ -21,7 +21,15 @@ function applyEntry(state, entry, options, filePath)
         throw unknownKeyError(key, filePath, line);
     }
 
-    if (state.seen.has(key))
+    // Initialize per-file tracking if needed
+    if (!state.seenPerFile.has(filePath))
+    {
+        state.seenPerFile.set(filePath, new Set());
+    }
+    const fileKeys = state.seenPerFile.get(filePath);
+
+    // Check for duplicates ONLY within the same file
+    if (fileKeys.has(key))
     {
         if (strict)
         {
@@ -38,6 +46,15 @@ function applyEntry(state, entry, options, filePath)
         }
     }
 
+    // Debug logging for file precedence
+    if (debug && state.values[key] !== undefined)
+    {
+        const prevOrigin = state.origins[key];
+        console.log(`[molex-env] Override: ${key}`);
+        console.log(`  Previous: ${prevOrigin.file}:${prevOrigin.line} = ${prevOrigin.raw}`);
+        console.log(`  New:      ${filePath}:${line} = ${raw}`);
+    }
+
     const def = schema ? schema[key] : null;
     let value;
     if (def && def.type)
@@ -50,7 +67,7 @@ function applyEntry(state, entry, options, filePath)
 
     state.values[key] = value;
     state.origins[key] = { file: filePath, line, raw };
-    state.seen.add(key);
+    fileKeys.add(key);
 }
 
 module.exports = {

package/src/lib/core.js

@@ -11,14 +11,14 @@ const { deepFreeze } = require('./utils');
 
 /**
  * Build a new parsing state container.
- * @returns {{values: object, origins: object, seen: Set<string>}}
+ * @returns {{values: object, origins: object, seenPerFile: Map<string, Set<string>>}}
  */
 function buildState()
 {
     return {
         values: {},
         origins: {},
-        seen: new Set()
+        seenPerFile: new Map()
     };
 }
 
@@ -79,7 +79,8 @@ function load(options = {})
                 schema: normalizedSchema,
                 strict,
                 cast,
-                onWarning: options.onWarning
+                onWarning: options.onWarning,
+                debug: options.debug
             }, filePath);
         }
         readFiles.push(filePath);

package/src/lib/watch.js

@@ -27,6 +27,7 @@ function watch(options, onChange, load)
     const basenames = new Set(files.map((file) => path.basename(file)));
     const watchers = [];
     let timer = null;
+    let previousConfig = null;
 
     const trigger = () =>
     {
@@ -35,7 +36,40 @@ function watch(options, onChange, load)
         {
             try
             {
-                const result = load(options);
+                // Disable file precedence debug during reload to avoid conflicts with watch change detection
+                const reloadOptions = { ...options, debug: false };
+                const result = load(reloadOptions);
+                
+                // Auto-detect changes if debug mode was enabled
+                if (options.debug && previousConfig)
+                {
+                    const changes = [];
+                    for (const key in result.parsed)
+                    {
+                        const oldValue = previousConfig[key];
+                        const newValue = result.parsed[key];
+                        
+                        // Compare values (handle dates and objects)
+                        const oldStr = oldValue instanceof Date ? oldValue.toISOString() : JSON.stringify(oldValue);
+                        const newStr = newValue instanceof Date ? newValue.toISOString() : JSON.stringify(newValue);
+                        
+                        if (oldStr !== newStr)
+                        {
+                            changes.push({ key, old: oldValue, new: newValue });
+                        }
+                    }
+                    
+                    if (changes.length > 0)
+                    {
+                        console.log('[molex-env] Config reloaded - changes detected:');
+                        changes.forEach(({ key, old, new: newVal }) =>
+                        {
+                            console.log(`  ${key}: ${old} → ${newVal}`);
+                        });
+                    }
+                }
+                
+                previousConfig = { ...result.parsed };
                 onChange(null, result);
             } catch (err)
             {