dotenv-diff 1.2.0 → 1.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Chrilleweb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,8 +1,6 @@
 # dotenv-diff
 
-![Terminal_view](public/image.png)
-
-Easily compare your `.env` and `.env.example` files in Node.js projects to detect missing, extra, empty, or mismatched environment variables.
+Easily compare your .env, .env.example, and other environment files (like .env.local, .env.production) to detect missing, extra, empty, or mismatched variables — and ensure they’re properly ignored by Git.
 
 [![npm version](https://img.shields.io/npm/v/dotenv-diff.svg)](https://www.npmjs.com/package/dotenv-diff)
 [![npm downloads](https://img.shields.io/npm/dt/dotenv-diff.svg)](https://www.npmjs.com/package/dotenv-diff)
@@ -26,11 +24,12 @@ pnpm add -g dotenv-diff
 ```bash
 dotenv-diff
 ```
-## Compares .env and .env.example in the current working directory and checks for:
-- Missing variables in `.env.example`
-- Extra variables in `.env`
-- Empty variables in `.env`
-- Mismatched values between `.env` and `.env.example`
+## What it checks
+dotenv-diff will automatically compare all matching .env* files in your project against .env.example, including:
+- `.env`
+- `.env.local`
+- `.env.production`
+- Any other .env.* file
 
 ## Optional: Check values too 
 
@@ -40,6 +39,20 @@ dotenv-diff --check-values
 
 When using the `--check-values` option, the tool will also compare the actual values of the variables in `.env` and `.env.example`. It will report any mismatches found and it also compares values if .env.example defines a non-empty expected value.
 
+## Automatic file creation prompts
+
+If one of the files is missing, `dotenv-diff` will ask if you want to create it from the other:
+
+- **`.env` missing** → prompts to create it from `.env.example`
+- **`.env.example` missing** → prompts to create it from `.env` *(keys only, no values)*
+
+This makes it quick to set up environment files without manually copying or retyping variable names.
+
+## Also checks your .gitignore
+
+`dotenv-diff` will warn you if your `.env` file is **not** ignored by Git.  
+This helps prevent accidentally committing sensitive environment variables.
+
 ## 🤝 Contributing
 
 Contributions are welcome! Feel free to open an issue or a pull request.

package/dist/cli.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * CLI entry point for the `dotenv-diff` tool.
+ *
+ * - Compares `.env` and `.env.example` files.
+ * - Optionally checks for value mismatches.
+ * - Warns about missing keys, extra keys, empty values, and mismatches.
+ */
+export {};

package/dist/cli.js

@@ -13,6 +13,7 @@ import chalk from 'chalk';
 import prompts from 'prompts';
 import { parseEnvFile } from './lib/parseEnv.js';
 import { diffEnv } from './lib/diffEnv.js';
+import { warnIfEnvNotIgnored } from './lib/checkGitignore.js';
 const program = new Command();
 program
     .name('dotenv-diff')
@@ -22,13 +23,21 @@ program
 const options = program.opts();
 const checkValues = options.checkValues ?? false;
 const cwd = process.cwd();
-const envPath = path.resolve(cwd, '.env');
-const examplePath = path.resolve(cwd, '.env.example');
+const envFiles = fs
+    .readdirSync(cwd)
+    .filter((f) => f.startsWith('.env') && !f.startsWith('.env.example'))
+    .sort((a, b) => (a === '.env' ? -1 : b === '.env' ? 1 : a.localeCompare(b)));
+// Brug første .env* fil som "main" hvis flere findes
+// (resten håndteres senere i et loop)
+const primaryEnv = envFiles.includes('.env') ? '.env' : envFiles[0] || '.env';
+const primaryExample = '.env.example';
+const envPath = path.resolve(cwd, primaryEnv);
+const examplePath = path.resolve(cwd, primaryExample);
 const envExists = fs.existsSync(envPath);
 const exampleExists = fs.existsSync(examplePath);
-// Case 1: Neither file exists
-if (!envExists && !exampleExists) {
-    console.log(chalk.yellow('⚠️  No .env or .env.example file found. Skipping comparison.'));
+// Case 1: No env files and no .env.example → nothing to do
+if (envFiles.length === 0 && !exampleExists) {
+    console.log(chalk.yellow('⚠️  No .env* or .env.example file found. Skipping comparison.'));
     process.exit(0);
 }
 // Case 2: .env is missing but .env.example exists
@@ -40,9 +49,9 @@ if (!envExists && exampleExists) {
         message: '❓ Do you want to create a new .env file from .env.example?',
         choices: [
             { title: 'Yes', value: true },
-            { title: 'No', value: false }
+            { title: 'No', value: false },
         ],
-        initial: 0
+        initial: 0,
     });
     if (!response.createEnv) {
         console.log(chalk.gray('🚫 Skipping .env creation.'));
@@ -51,6 +60,7 @@ if (!envExists && exampleExists) {
     const exampleContent = fs.readFileSync(examplePath, 'utf-8');
     fs.writeFileSync(envPath, exampleContent);
     console.log(chalk.green('✅ .env file created successfully from .env.example.\n'));
+    warnIfEnvNotIgnored();
 }
 // Case 3: .env exists, but .env.example is missing
 if (envExists && !exampleExists) {
@@ -61,15 +71,25 @@ if (envExists && !exampleExists) {
         message: '❓ Do you want to create a new .env.example file from .env?',
         choices: [
             { title: 'Yes', value: true },
-            { title: 'No', value: false }
+            { title: 'No', value: false },
         ],
-        initial: 0
+        initial: 0,
     });
     if (!response.createExample) {
         console.log(chalk.gray('🚫 Skipping .env.example creation.'));
         process.exit(0);
     }
-    const envContent = fs.readFileSync(envPath, 'utf-8');
+    const envContent = fs
+        .readFileSync(envPath, 'utf-8')
+        .split('\n')
+        .map((line) => {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            return trimmed;
+        const [key] = trimmed.split('=');
+        return `${key}=`;
+    })
+        .join('\n');
     fs.writeFileSync(examplePath, envContent);
     console.log(chalk.green('✅ .env.example file created successfully from .env.\n'));
 }
@@ -78,40 +98,60 @@ if (!fs.existsSync(envPath) || !fs.existsSync(examplePath)) {
     console.error(chalk.red('❌ Error: .env or .env.example is missing after setup.'));
     process.exit(1);
 }
-// Case 5: Both files exist, proceed with comparison
-console.log(chalk.bold('🔍 Comparing .env and .env.example...\n'));
-const current = parseEnvFile(envPath);
-const example = parseEnvFile(examplePath);
-const diff = diffEnv(current, example, checkValues);
-const emptyKeys = Object.entries(current)
-    .filter(([value]) => value.trim() === '')
-    .map(([key]) => key);
-let hasWarnings = false;
-if (diff.missing.length === 0 &&
-    diff.extra.length === 0 &&
-    emptyKeys.length === 0 &&
-    diff.valueMismatches.length === 0) {
-    console.log(chalk.green('✅ All keys match! Your .env file is valid.'));
-    process.exit(0);
-}
-if (diff.missing.length > 0) {
-    console.log(chalk.red('\n❌ Missing keys in .env:'));
-    diff.missing.forEach((key) => console.log(chalk.red(`  - ${key}`)));
-}
-if (diff.extra.length > 0) {
-    console.log(chalk.yellow('\n⚠️  Extra keys in .env (not defined in .env.example):'));
-    diff.extra.forEach((key) => console.log(chalk.yellow(`  - ${key}`)));
-}
-if (emptyKeys.length > 0) {
-    hasWarnings = true;
-    console.log(chalk.yellow('\n⚠️  The following keys in .env have no value (empty):'));
-    emptyKeys.forEach((key) => console.log(chalk.yellow(`  - ${key}`)));
-}
-if (checkValues && diff.valueMismatches.length > 0) {
-    hasWarnings = true;
-    console.log(chalk.yellow('\n⚠️  The following keys have different values:'));
-    diff.valueMismatches.forEach(({ key, expected, actual }) => {
-        console.log(chalk.yellow(`  - ${key}: expected "${expected}", but got "${actual}"`));
+// Case 5: Compare all found .env* files
+let exitWithError = false;
+for (const envName of envFiles.length > 0 ? envFiles : [primaryEnv]) {
+    const suffix = envName === '.env' ? '' : envName.replace('.env', '');
+    const exampleName = suffix ? `.env.example${suffix}` : primaryExample;
+    const envPathCurrent = path.resolve(cwd, envName);
+    const examplePathCurrent = fs.existsSync(path.resolve(cwd, exampleName))
+        ? path.resolve(cwd, exampleName)
+        : examplePath;
+    if (!fs.existsSync(envPathCurrent) || !fs.existsSync(examplePathCurrent)) {
+        console.log(chalk.bold(`🔍 Comparing ${envName} ↔ ${path.basename(examplePathCurrent)}...`));
+        console.log(chalk.yellow('  ⚠️  Skipping: missing matching example file.'));
+        console.log();
+        continue;
+    }
+    console.log(chalk.bold(`🔍 Comparing ${envName} ↔ ${path.basename(examplePathCurrent)}...`));
+    warnIfEnvNotIgnored({
+        cwd,
+        envFile: envName,
+        log: (msg) => console.log(msg.replace(/^/gm, '  ')),
     });
+    const current = parseEnvFile(envPathCurrent);
+    const example = parseEnvFile(examplePathCurrent);
+    const diff = diffEnv(current, example, checkValues);
+    const emptyKeys = Object.entries(current)
+        .filter(([, value]) => (value ?? '').trim() === '')
+        .map(([key]) => key);
+    if (diff.missing.length === 0 &&
+        diff.extra.length === 0 &&
+        emptyKeys.length === 0 &&
+        diff.valueMismatches.length === 0) {
+        console.log(chalk.green('  ✅ All keys match.'));
+        console.log();
+        continue;
+    }
+    if (diff.missing.length > 0) {
+        exitWithError = true;
+        console.log(chalk.red('  ❌ Missing keys:'));
+        diff.missing.forEach((key) => console.log(chalk.red(`      - ${key}`)));
+    }
+    if (diff.extra.length > 0) {
+        console.log(chalk.yellow('  ⚠️  Extra keys (not in example):'));
+        diff.extra.forEach((key) => console.log(chalk.yellow(`      - ${key}`)));
+    }
+    if (emptyKeys.length > 0) {
+        console.log(chalk.yellow('  ⚠️  Empty values:'));
+        emptyKeys.forEach((key) => console.log(chalk.yellow(`      - ${key}`)));
+    }
+    if (checkValues && diff.valueMismatches.length > 0) {
+        console.log(chalk.yellow('  ⚠️  Value mismatches:'));
+        diff.valueMismatches.forEach(({ key, expected, actual }) => {
+            console.log(chalk.yellow(`      - ${key}: expected '${expected}', but got '${actual}'`));
+        });
+    }
+    console.log(); // blank line efter sektionen med findings
 }
-process.exit(diff.missing.length > 0 ? 1 : 0);
+process.exit(exitWithError ? 1 : 0);

package/dist/diffEnv.d.ts

@@ -0,0 +1,5 @@
+export type DiffResult = {
+    missing: string[];
+    extra: string[];
+};
+export declare function diffEnv(current: Record<string, string>, example: Record<string, string>): DiffResult;

package/dist/diffEnv.js

@@ -0,0 +1,7 @@
+export function diffEnv(current, example) {
+    const currentKeys = Object.keys(current);
+    const exampleKeys = Object.keys(example);
+    const missing = exampleKeys.filter((key) => !currentKeys.includes(key));
+    const extra = currentKeys.filter((key) => !exampleKeys.includes(key));
+    return { missing, extra };
+}

package/dist/index.d.ts

@@ -1,2 +1,2 @@
 export { parseEnvFile } from './lib/parseEnv.js';
-export { diffEnv, type DiffResult } from './lib/diffEnv.js';
+export { diffEnv, DiffResult } from './lib/diffEnv.js';

package/dist/lib/checkGitignore.d.ts

@@ -0,0 +1,23 @@
+export type GitignoreCheckOptions = {
+    /** Project root directory (default: process.cwd()) */
+    cwd?: string;
+    /** Name of the env file (default: ".env") */
+    envFile?: string;
+    /** Custom logger (default: console.log) */
+    log?: (msg: string) => void;
+};
+/** Are we in a git repo? (checks for .git directory in cwd) */
+export declare function isGitRepo(cwd?: string): boolean;
+/**
+ * Returns:
+ *  - true  → .env-matching patterns are found in .gitignore
+ *  - false → .env-matching patterns are NOT found (or a negation exists)
+ *  - null  → no .gitignore exists
+ */
+export declare function isEnvIgnoredByGit(options?: GitignoreCheckOptions): boolean | null;
+/**
+ * Logs a friendly warning if .env is not ignored by Git.
+ * - Does not hard fail: non-blocking DX.
+ * - Skips if not in a git repo or if .env does not exist.
+ */
+export declare function warnIfEnvNotIgnored(options?: GitignoreCheckOptions): void;

package/dist/lib/checkGitignore.js

@@ -0,0 +1,73 @@
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
+/** Are we in a git repo? (checks for .git directory in cwd) */
+export function isGitRepo(cwd = process.cwd()) {
+    return fs.existsSync(path.resolve(cwd, '.git'));
+}
+/**
+ * Returns:
+ *  - true  → .env-matching patterns are found in .gitignore
+ *  - false → .env-matching patterns are NOT found (or a negation exists)
+ *  - null  → no .gitignore exists
+ */
+export function isEnvIgnoredByGit(options = {}) {
+    const { cwd = process.cwd(), envFile = '.env' } = options;
+    const gitignorePath = path.resolve(cwd, '.gitignore');
+    if (!fs.existsSync(gitignorePath))
+        return null;
+    const raw = fs.readFileSync(gitignorePath, 'utf8');
+    const lines = raw
+        .split(/\r?\n/)
+        .map((l) => l.trim())
+        .filter((l) => l && !l.startsWith('#'));
+    // If there is a negation (!pattern) that matches our candidates, we consider it as "not ignored"
+    if (lines.some((l) => l.startsWith('!') && matchesCandidate(l.slice(1), envFile))) {
+        return false;
+    }
+    const candidates = getCandidatePatterns(envFile);
+    return lines.some((line) => candidates.has(line));
+}
+/** Our simple candidate patterns that typically cover env files in the root and subfolders */
+function getCandidatePatterns(envFile = '.env') {
+    const base = envFile; // ".env"
+    const star = `${base}*`; // ".env*"
+    const dotStar = `${base}.*`; // ".env.*"
+    return new Set([
+        base,
+        `/${base}`,
+        `**/${base}`,
+        star,
+        `/${star}`,
+        `**/${star}`,
+        dotStar,
+        `/${dotStar}`,
+        `**/${dotStar}`,
+    ]);
+}
+// Matches only against our own candidate patterns (intentionally simple)
+function matchesCandidate(pattern, envFile) {
+    return getCandidatePatterns(envFile).has(pattern);
+}
+/**
+ * Logs a friendly warning if .env is not ignored by Git.
+ * - Does not hard fail: non-blocking DX.
+ * - Skips if not in a git repo or if .env does not exist.
+ */
+export function warnIfEnvNotIgnored(options = {}) {
+    const { cwd = process.cwd(), envFile = '.env', log = console.log } = options;
+    const envPath = path.resolve(cwd, envFile);
+    if (!fs.existsSync(envPath))
+        return; // No .env file → nothing to warn about
+    if (!isGitRepo(cwd))
+        return; // Not a git repo → skip
+    const gitignorePath = path.resolve(cwd, '.gitignore');
+    if (!fs.existsSync(gitignorePath)) {
+        log(chalk.yellow(`⚠️  No .gitignore found – your ${envFile} may be committed.\n   Add:\n   ${envFile}\n   ${envFile}.*\n`));
+        return;
+    }
+    const ignored = isEnvIgnoredByGit({ cwd, envFile });
+    if (ignored === false || ignored === null) {
+        log(chalk.yellow(`⚠️  ${envFile} is not ignored by Git (.gitignore).\n   Consider adding:\n   ${envFile}\n   ${envFile}.*\n`));
+    }
+}

package/dist/lib/diffEnv.d.ts

@@ -0,0 +1,18 @@
+export type DiffResult = {
+    missing: string[];
+    extra: string[];
+    valueMismatches: {
+        key: string;
+        expected: string;
+        actual: string;
+    }[];
+};
+/**
+ * Compares two .env files and returns their differences.
+ *
+ * @param current - An object representing the current `.env` file (key-value pairs).
+ * @param example - An object representing the `.env.example` file (key-value pairs).
+ * @param checkValues - If true, compare values when the example has a non-empty value.
+ * @returns A `DiffResult` object containing missing, extra, and mismatched keys.
+ */
+export declare function diffEnv(current: Record<string, string>, example: Record<string, string>, checkValues?: boolean): DiffResult;

package/dist/lib/diffEnv.js

@@ -16,7 +16,7 @@ export function diffEnv(current, example, checkValues = false) {
         valueMismatches = exampleKeys
             .filter((key) => {
             return (currentKeys.includes(key) &&
-                example[key].trim() !== "" &&
+                example[key].trim() !== '' &&
                 current[key] !== example[key]);
         })
             .map((key) => ({

package/dist/lib/parseEnv.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Parses a `.env` file and returns an object with key-value pairs.
+ *
+ * @param path - The file path to the `.env` file.
+ * @returns A record object representing parsed environment variables.
+ *
+ * Lines that are empty or start with `#` (comments) are ignored.
+ * Multi-line or quoted values are not supported.
+ */
+export declare function parseEnvFile(path: string): Record<string, string>;

package/dist/parseEnv.d.ts

@@ -0,0 +1 @@
+export declare function parseEnvFile(path: string): Record<string, string>;

package/dist/parseEnv.js

@@ -0,0 +1,16 @@
+import fs from 'fs';
+export function parseEnvFile(path) {
+    const content = fs.readFileSync(path, 'utf-8');
+    const lines = content.split('\n');
+    const result = {};
+    for (const line of lines) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith('#'))
+            continue;
+        const [key, ...rest] = trimmed.split('=');
+        if (!key)
+            continue;
+        result[key.trim()] = rest.join('=').trim();
+    }
+    return result;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotenv-diff",
-  "version": "1.2.0",
+  "version": "1.4.0",
   "type": "module",
   "description": "A small CLI and library to find differences between .env and .env.example files.",
   "bin": {
@@ -9,18 +9,16 @@
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist/cli.js",
-    "dist/lib/diffEnv.js",
-    "dist/lib/parseEnv.js",
-    "dist/index.js",
-    "dist/index.d.ts",
-    "README.md"
+    "dist/",
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "build": "tsc",
     "dev": "vitest --watch",
     "test": "vitest",
     "lint": "eslint ./src --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\" \"src/*.ts\"",
     "start": "node dist/cli.js"
   },
   "author": "Chrilleweb",
@@ -51,6 +49,7 @@
     "@typescript-eslint/eslint-plugin": "^8.39.0",
     "@typescript-eslint/parser": "^8.39.0",
     "eslint": "^9.32.0",
+    "prettier": "^3.6.2",
     "typescript": "^5.2.0",
     "vitest": "^3.2.0"
   }