dotenv-diff 1.6.2 → 1.6.4

package/README.md

@@ -43,6 +43,26 @@ When using the `--check-values` option, the tool will also compare the actual va
 
 `dotenv-diff` warns when a `.env*` file contains the same key multiple times. The last occurrence wins. Suppress these warnings with `--allow-duplicates`.
 
+## Ignore specific keys
+
+Exclude certain keys from the comparison using `--ignore` for exact names or `--ignore-regex` for patterns:
+
+```bash
+dotenv-diff --ignore API_KEY,SESSION_ID
+dotenv-diff --ignore-regex '^SECRET_'
+dotenv-diff --ignore API_KEY --ignore-regex '^SECRET_'
+```
+
+Ignored keys are removed from all warnings and do not affect the exit code.
+
+## Output format in JSON
+
+You can output the results in JSON format using the `--json` option:
+
+```bash
+dotenv-diff --json
+```
+
 ## Compare specific files
 
 Override the autoscan and compare exactly two files:

package/dist/src/cli/program.js

@@ -8,5 +8,8 @@ export function createProgram() {
         .option('-y, --yes', 'Run non-interactively and answer Yes to prompts')
         .option('--env <file>', 'Path to a specific .env file')
         .option('--example <file>', 'Path to a specific .env.example file')
-        .option('--allow-duplicates', 'Do not warn about duplicate keys in .env* files');
+        .option('--allow-duplicates', 'Do not warn about duplicate keys in .env* files')
+        .option('--ignore <keys>', 'Comma-separated list of keys to ignore')
+        .option('--ignore-regex <pattern>', 'Regex pattern to ignore matching keys')
+        .option('--json', 'Output results in JSON format');
 }

package/dist/src/cli/run.js

@@ -1,16 +1,16 @@
+import fs from 'fs';
+import path from 'path';
+import chalk from 'chalk';
 import { normalizeOptions } from '../config/options.js';
 import { discoverEnvFiles } from '../services/envDiscovery.js';
 import { pairWithExample } from '../services/envPairing.js';
 import { ensureFilesOrPrompt } from '../commands/init.js';
 import { compareMany } from '../commands/compare.js';
-import fs from 'fs';
-import path from 'path';
-import chalk from 'chalk';
 export async function run(program) {
     program.parse(process.argv);
     const raw = program.opts();
     const opts = normalizeOptions(raw);
-    // Special-case: both flags → direct comparison
+    // Special-case: both flags → direct comparison of exactly those two files
     if (opts.envFlag && opts.exampleFlag) {
         const envExists = fs.existsSync(opts.envFlag);
         const exExists = fs.existsSync(opts.exampleFlag);
@@ -23,6 +23,7 @@ export async function run(program) {
             }
             process.exit(1);
         }
+        const report = [];
         const { exitWithError } = await compareMany([
             {
                 envName: path.basename(opts.envFlag),
@@ -33,14 +34,23 @@ export async function run(program) {
             checkValues: opts.checkValues,
             cwd: opts.cwd,
             allowDuplicates: opts.allowDuplicates,
+            json: opts.json,
+            ignore: opts.ignore,
+            ignoreRegex: opts.ignoreRegex,
+            collect: (e) => report.push(e),
         });
+        if (opts.json) {
+            console.log(JSON.stringify(report, null, 2));
+        }
         process.exit(exitWithError ? 1 : 0);
     }
+    // Auto-discovery flow
     const d = discoverEnvFiles({
         cwd: opts.cwd,
         envFlag: opts.envFlag,
         exampleFlag: opts.exampleFlag,
     });
+    // Init cases (may create files or early-exit)
     const res = await ensureFilesOrPrompt({
         cwd: d.cwd,
         primaryEnv: d.primaryEnv,
@@ -49,14 +59,26 @@ export async function run(program) {
         isYesMode: opts.isYesMode,
         isCiMode: opts.isCiMode,
     });
-    if (res.shouldExit)
+    if (res.shouldExit) {
+        // For JSON mode, emit an empty report to keep output machine-friendly (optional; safe).
+        if (opts.json)
+            console.log(JSON.stringify([], null, 2));
         process.exit(res.exitCode);
-    // compare all pairs
+    }
+    // Compare all discovered pairs
     const pairs = pairWithExample(d);
+    const report = [];
     const { exitWithError } = await compareMany(pairs, {
         checkValues: opts.checkValues,
         cwd: opts.cwd,
         allowDuplicates: opts.allowDuplicates,
+        json: opts.json,
+        ignore: opts.ignore,
+        ignoreRegex: opts.ignoreRegex,
+        collect: (e) => report.push(e),
     });
+    if (opts.json) {
+        console.log(JSON.stringify(report, null, 2));
+    }
     process.exit(exitWithError ? 1 : 0);
 }

package/dist/src/commands/compare.d.ts

@@ -1,3 +1,29 @@
+export type CompareJsonEntry = {
+    env: string;
+    example: string;
+    skipped?: {
+        reason: string;
+    };
+    duplicates?: {
+        env?: Array<{
+            key: string;
+            count: number;
+        }>;
+        example?: Array<{
+            key: string;
+            count: number;
+        }>;
+    };
+    missing?: string[];
+    extra?: string[];
+    empty?: string[];
+    valueMismatches?: Array<{
+        key: string;
+        expected: string;
+        actual: string;
+    }>;
+    ok?: boolean;
+};
 export declare function compareMany(pairs: Array<{
     envName: string;
     envPath: string;
@@ -6,6 +32,10 @@ export declare function compareMany(pairs: Array<{
     checkValues: boolean;
     cwd: string;
     allowDuplicates?: boolean;
+    json?: boolean;
+    ignore: string[];
+    ignoreRegex: RegExp[];
+    collect?: (entry: CompareJsonEntry) => void;
 }): Promise<{
     exitWithError: boolean;
 }>;

package/dist/src/commands/compare.js

@@ -5,68 +5,113 @@ import { parseEnvFile } from '../lib/parseEnv.js';
 import { diffEnv } from '../lib/diffEnv.js';
 import { warnIfEnvNotIgnored } from '../services/git.js';
 import { findDuplicateKeys } from '../services/duplicates.js';
+import { filterIgnoredKeys } from '../core/filterIgnoredKeys.js';
 export async function compareMany(pairs, opts) {
     let exitWithError = false;
     for (const { envName, envPath, examplePath } of pairs) {
+        const exampleName = path.basename(examplePath);
+        const entry = { env: envName, example: exampleName };
         if (!fs.existsSync(envPath) || !fs.existsSync(examplePath)) {
-            console.log(chalk.bold(`🔍 Comparing ${envName} ↔ ${path.basename(examplePath)}...`));
-            console.log(chalk.yellow('  ⚠️  Skipping: missing matching example file.'));
-            console.log();
+            if (!opts.json) {
+                console.log(chalk.bold(`🔍 Comparing ${envName} ↔ ${exampleName}...`));
+                console.log(chalk.yellow('  ⚠️  Skipping: missing matching example file.'));
+                console.log();
+            }
+            entry.skipped = { reason: 'missing file' };
+            opts.collect?.(entry);
             continue;
         }
-        console.log(chalk.bold(`🔍 Comparing ${envName} ↔ ${path.basename(examplePath)}...`));
+        if (!opts.json) {
+            console.log(chalk.bold(`🔍 Comparing ${envName} ↔ ${exampleName}...`));
+        }
+        // Git ignore hint (only when not JSON)
         warnIfEnvNotIgnored({
             cwd: opts.cwd,
             envFile: envName,
-            log: (msg) => console.log(msg.replace(/^/gm, '  ')),
+            log: (msg) => {
+                if (!opts.json)
+                    console.log(msg.replace(/^/gm, '  '));
+            },
         });
+        // Duplicate detection
         if (!opts.allowDuplicates) {
-            const dupsEnv = findDuplicateKeys(envPath);
-            if (dupsEnv.length > 0) {
-                console.log(chalk.yellow(`  ⚠️  Duplicate keys in ${envName} (last occurrence wins):`));
-                dupsEnv.forEach(({ key, count }) => console.log(chalk.yellow(`      - ${key} (${count} occurrences)`)));
+            const dupsEnv = findDuplicateKeys(envPath).filter(({ key }) => !opts.ignore.includes(key) &&
+                !opts.ignoreRegex.some((rx) => rx.test(key)));
+            const dupsEx = findDuplicateKeys(examplePath).filter(({ key }) => !opts.ignore.includes(key) &&
+                !opts.ignoreRegex.some((rx) => rx.test(key)));
+            if (dupsEnv.length || dupsEx.length) {
+                entry.duplicates = {};
             }
-            const exName = path.basename(examplePath);
-            const dupsEx = findDuplicateKeys(examplePath);
-            if (dupsEx.length > 0) {
-                console.log(chalk.yellow(`  ⚠️  Duplicate keys in ${exName} (last occurrence wins):`));
-                dupsEx.forEach(({ key, count }) => console.log(chalk.yellow(`      - ${key} (${count} occurrences)`)));
+            if (dupsEnv.length) {
+                entry.duplicates.env = dupsEnv;
+                if (!opts.json) {
+                    console.log(chalk.yellow(`  ⚠️  Duplicate keys in ${envName} (last occurrence wins):`));
+                    dupsEnv.forEach(({ key, count }) => console.log(chalk.yellow(`      - ${key} (${count} occurrences)`)));
+                }
+            }
+            if (dupsEx.length) {
+                entry.duplicates.example = dupsEx;
+                if (!opts.json) {
+                    console.log(chalk.yellow(`  ⚠️  Duplicate keys in ${exampleName} (last occurrence wins):`));
+                    dupsEx.forEach(({ key, count }) => console.log(chalk.yellow(`      - ${key} (${count} occurrences)`)));
+                }
             }
         }
-        const current = parseEnvFile(envPath);
-        const example = parseEnvFile(examplePath);
+        // Diff + empty
+        const currentFull = parseEnvFile(envPath);
+        const exampleFull = parseEnvFile(examplePath);
+        const currentKeys = filterIgnoredKeys(Object.keys(currentFull), opts.ignore, opts.ignoreRegex);
+        const exampleKeys = filterIgnoredKeys(Object.keys(exampleFull), opts.ignore, opts.ignoreRegex);
+        const current = Object.fromEntries(currentKeys.map((k) => [k, currentFull[k]]));
+        const example = Object.fromEntries(exampleKeys.map((k) => [k, exampleFull[k]]));
         const diff = diffEnv(current, example, opts.checkValues);
         const emptyKeys = Object.entries(current)
             .filter(([, v]) => (v ?? '').trim() === '')
             .map(([k]) => k);
-        if (diff.missing.length === 0 &&
+        const allOk = diff.missing.length === 0 &&
             diff.extra.length === 0 &&
             emptyKeys.length === 0 &&
-            diff.valueMismatches.length === 0) {
-            console.log(chalk.green('  ✅ All keys match.'));
-            console.log();
+            diff.valueMismatches.length === 0;
+        if (allOk) {
+            entry.ok = true;
+            if (!opts.json) {
+                console.log(chalk.green('  ✅ All keys match.'));
+                console.log();
+            }
+            opts.collect?.(entry);
             continue;
         }
-        if (diff.missing.length > 0) {
+        if (diff.missing.length) {
+            entry.missing = diff.missing;
             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 (diff.extra.length)
+            entry.extra = diff.extra;
+        if (emptyKeys.length)
+            entry.empty = emptyKeys;
+        if (opts.checkValues && diff.valueMismatches.length) {
+            entry.valueMismatches = diff.valueMismatches;
         }
-        if (emptyKeys.length > 0) {
-            console.log(chalk.yellow('  ⚠️  Empty values:'));
-            emptyKeys.forEach((key) => console.log(chalk.yellow(`      - ${key}`)));
-        }
-        if (opts.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}'`));
-            });
+        if (!opts.json) {
+            if (diff.missing.length) {
+                console.log(chalk.red('  ❌ Missing keys:'));
+                diff.missing.forEach((key) => console.log(chalk.red(`      - ${key}`)));
+            }
+            if (diff.extra.length) {
+                console.log(chalk.yellow('  ⚠️  Extra keys (not in example):'));
+                diff.extra.forEach((key) => console.log(chalk.yellow(`      - ${key}`)));
+            }
+            if (emptyKeys.length) {
+                console.log(chalk.yellow('  ⚠️  Empty values:'));
+                emptyKeys.forEach((key) => console.log(chalk.yellow(`      - ${key}`)));
+            }
+            if (opts.checkValues && diff.valueMismatches.length) {
+                console.log(chalk.yellow('  ⚠️  Value mismatches:'));
+                diff.valueMismatches.forEach(({ key, expected, actual }) => console.log(chalk.yellow(`      - ${key}: expected '${expected}', but got '${actual}'`)));
+            }
+            console.log();
         }
-        console.log();
+        opts.collect?.(entry);
     }
     return { exitWithError };
 }

package/dist/src/config/options.d.ts

@@ -3,8 +3,11 @@ export type Options = {
     isCiMode: boolean;
     isYesMode: boolean;
     allowDuplicates: boolean;
+    json: boolean;
     envFlag: string | null;
     exampleFlag: string | null;
+    ignore: string[];
+    ignoreRegex: RegExp[];
     cwd: string;
 };
 type RawOptions = {
@@ -12,8 +15,11 @@ type RawOptions = {
     ci?: boolean;
     yes?: boolean;
     allowDuplicates?: boolean;
+    json?: boolean;
     env?: string;
     example?: string;
+    ignore?: string | string[];
+    ignoreRegex?: string | string[];
 };
 export declare function normalizeOptions(raw: RawOptions): Options;
 export {};

package/dist/src/config/options.js

@@ -5,6 +5,25 @@ export function normalizeOptions(raw) {
     const isCiMode = Boolean(raw.ci);
     const isYesMode = Boolean(raw.yes);
     const allowDuplicates = Boolean(raw.allowDuplicates);
+    const json = Boolean(raw.json);
+    const parseList = (val) => {
+        const arr = Array.isArray(val) ? val : val ? [val] : [];
+        return arr
+            .flatMap((s) => s.split(','))
+            .map((s) => s.trim())
+            .filter(Boolean);
+    };
+    const ignore = parseList(raw.ignore);
+    const ignoreRegex = [];
+    for (const pattern of parseList(raw.ignoreRegex)) {
+        try {
+            ignoreRegex.push(new RegExp(pattern));
+        }
+        catch {
+            console.error(chalk.red(`❌ Error: invalid --ignore-regex pattern: ${pattern}`));
+            process.exit(1);
+        }
+    }
     if (isCiMode && isYesMode) {
         console.log(chalk.yellow('⚠️  Both --ci and --yes provided; proceeding with --yes.'));
     }
@@ -16,8 +35,11 @@ export function normalizeOptions(raw) {
         isCiMode,
         isYesMode,
         allowDuplicates,
+        json,
         envFlag,
         exampleFlag,
+        ignore,
+        ignoreRegex,
         cwd,
     };
 }

package/dist/src/core/filterIgnoredKeys.d.ts

@@ -0,0 +1 @@
+export declare function filterIgnoredKeys(keys: string[], ignore: string[], ignoreRegex: RegExp[]): string[];

package/dist/src/core/filterIgnoredKeys.js

@@ -0,0 +1,3 @@
+export function filterIgnoredKeys(keys, ignore, ignoreRegex) {
+    return keys.filter((k) => !ignore.includes(k) && !ignoreRegex.some((rx) => rx.test(k)));
+}

package/package.json

@@ -1,25 +1,36 @@
 {
   "name": "dotenv-diff",
-  "version": "1.6.2",
+  "version": "1.6.4",
   "type": "module",
-  "description": "A small CLI and library to find differences between .env and .env.example files.",
+  "description": "A CLI tool to find differences between .env and .env.example / .env.* files.",
   "bin": {
     "dotenv-diff": "dist/bin/dotenv-diff.js"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
   "files": [
     "dist/",
     "README.md",
     "LICENSE"
   ],
+  "sideEffects": false,
   "scripts": {
     "build": "tsc",
     "dev": "vitest --watch",
-    "test": "vitest",
+    "test": "vitest run",
+    "test:unit": "vitest run test/unit",
+    "test:e2e": "vitest run test/e2e",
     "lint": "eslint ./src --ext .ts",
     "format": "prettier --write \"src/**/*.ts\" \"src/*.ts\"",
-    "start": "node dist/bin/dotenv-diff.js"
+    "start": "node dist/bin/dotenv-diff.js",
+    "prepublishOnly": "npm run lint && npm test && npm run build"
   },
   "author": "Chrilleweb",
   "license": "MIT",
@@ -36,8 +47,12 @@
     "type": "git",
     "url": "https://github.com/Chrilleweb/dotenv-diff.git"
   },
+  "homepage": "https://github.com/Chrilleweb/dotenv-diff#readme",
+  "bugs": {
+    "url": "https://github.com/Chrilleweb/dotenv-diff/issues"
+  },
   "engines": {
-    "node": ">=14.0.0"
+    "node": ">=20.0.0"
   },
   "dependencies": {
     "chalk": "^5.4.1",