dotenv-diff 1.6.3 → 1.6.5

package/README.md

@@ -43,6 +43,27 @@ 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`.
 
+## Only show specific categories
+
+Use the `--only` flag to restrict the comparison to specific categories. For example:
+
+```bash
+dotenv-diff --only missing,extra
+```
+This will only show missing and extra keys, ignoring empty, mismatched, duplicate keys and so on.
+
+## 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:

package/dist/src/cli/program.js

@@ -9,5 +9,8 @@ export function createProgram() {
         .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('--json', 'Output results in JSON format');
+        .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')
+        .option('--only <list>', 'Comma-separated categories to only run (missing,extra,empty,mismatch,duplicate,gitignore)');
 }

package/dist/src/cli/run.js

@@ -24,11 +24,20 @@ export async function run(program) {
             process.exit(1);
         }
         const report = [];
-        const { exitWithError } = await compareMany([{ envName: path.basename(opts.envFlag), envPath: opts.envFlag, examplePath: opts.exampleFlag }], {
+        const { exitWithError } = await compareMany([
+            {
+                envName: path.basename(opts.envFlag),
+                envPath: opts.envFlag,
+                examplePath: opts.exampleFlag,
+            },
+        ], {
             checkValues: opts.checkValues,
             cwd: opts.cwd,
             allowDuplicates: opts.allowDuplicates,
             json: opts.json,
+            ignore: opts.ignore,
+            ignoreRegex: opts.ignoreRegex,
+            only: opts.only,
             collect: (e) => report.push(e),
         });
         if (opts.json) {
@@ -65,6 +74,9 @@ export async function run(program) {
         cwd: opts.cwd,
         allowDuplicates: opts.allowDuplicates,
         json: opts.json,
+        ignore: opts.ignore,
+        ignoreRegex: opts.ignoreRegex,
+        only: opts.only,
         collect: (e) => report.push(e),
     });
     if (opts.json) {

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

@@ -1,29 +1,4 @@
-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;
-};
+import type { Category, CompareJsonEntry } from '../config/types.js';
 export declare function compareMany(pairs: Array<{
     envName: string;
     envPath: string;
@@ -33,7 +8,10 @@ export declare function compareMany(pairs: Array<{
     cwd: string;
     allowDuplicates?: boolean;
     json?: boolean;
+    ignore: string[];
+    ignoreRegex: RegExp[];
     collect?: (entry: CompareJsonEntry) => void;
+    only?: Category[];
 }): Promise<{
     exitWithError: boolean;
 }>;

package/dist/src/commands/compare.js

@@ -5,8 +5,21 @@ 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;
+    const onlySet = opts.only?.length
+        ? new Set(opts.only)
+        : undefined;
+    const run = (cat) => !onlySet || onlySet.has(cat);
+    const totals = {
+        missing: 0,
+        extra: 0,
+        empty: 0,
+        mismatch: 0,
+        duplicate: 0,
+        gitignore: 0,
+    };
     for (const { envName, envPath, examplePath } of pairs) {
         const exampleName = path.basename(examplePath);
         const entry = { env: envName, example: exampleName };
@@ -24,18 +37,29 @@ export async function compareMany(pairs, opts) {
             console.log(chalk.bold(`🔍 Comparing ${envName} ↔ ${exampleName}...`));
         }
         // Git ignore hint (only when not JSON)
-        warnIfEnvNotIgnored({
-            cwd: opts.cwd,
-            envFile: envName,
-            log: (msg) => {
-                if (!opts.json)
-                    console.log(msg.replace(/^/gm, '  '));
-            },
-        });
-        // Duplicate detection
-        if (!opts.allowDuplicates) {
-            const dupsEnv = findDuplicateKeys(envPath);
-            const dupsEx = findDuplicateKeys(examplePath);
+        let gitignoreUnsafe = false;
+        if (run('gitignore')) {
+            warnIfEnvNotIgnored({
+                cwd: opts.cwd,
+                envFile: envName,
+                log: (msg) => {
+                    gitignoreUnsafe = true;
+                    if (!opts.json)
+                        console.log(msg.replace(/^/gm, '  '));
+                },
+            });
+        }
+        else {
+            // still call to keep previous hints? No—masked by --only.
+        }
+        // Duplicate detection (skip entirely if --only excludes it)
+        let dupsEnv = [];
+        let dupsEx = [];
+        if (!opts.allowDuplicates && run('duplicate')) {
+            dupsEnv = findDuplicateKeys(envPath).filter(({ key }) => !opts.ignore.includes(key) &&
+                !opts.ignoreRegex.some((rx) => rx.test(key)));
+            dupsEx = findDuplicateKeys(examplePath).filter(({ key }) => !opts.ignore.includes(key) &&
+                !opts.ignoreRegex.some((rx) => rx.test(key)));
             if (dupsEnv.length || dupsEx.length) {
                 entry.duplicates = {};
             }
@@ -55,16 +79,29 @@ export async function compareMany(pairs, opts) {
             }
         }
         // Diff + empty
-        const current = parseEnvFile(envPath);
-        const example = parseEnvFile(examplePath);
+        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);
-        const allOk = diff.missing.length === 0 &&
-            diff.extra.length === 0 &&
-            emptyKeys.length === 0 &&
-            diff.valueMismatches.length === 0;
+        const filtered = {
+            missing: run('missing') ? diff.missing : [],
+            extra: run('extra') ? diff.extra : [],
+            empty: run('empty') ? emptyKeys : [],
+            mismatches: run('mismatch') && opts.checkValues ? diff.valueMismatches : [],
+            duplicatesEnv: run('duplicate') ? dupsEnv : [],
+            duplicatesEx: run('duplicate') ? dupsEx : [],
+            gitignoreUnsafe: run('gitignore') ? gitignoreUnsafe : false,
+        };
+        const allOk = filtered.missing.length === 0 &&
+            filtered.extra.length === 0 &&
+            filtered.empty.length === 0 &&
+            filtered.mismatches.length === 0;
         if (allOk) {
             entry.ok = true;
             if (!opts.json) {
@@ -74,33 +111,51 @@ export async function compareMany(pairs, opts) {
             opts.collect?.(entry);
             continue;
         }
-        if (diff.missing.length) {
-            entry.missing = diff.missing;
+        if (filtered.missing.length) {
+            entry.missing = filtered.missing;
+            exitWithError = true;
+            totals.missing += filtered.missing.length;
+        }
+        if (filtered.extra.length) {
+            entry.extra = filtered.extra;
+            exitWithError = true;
+            totals.extra += filtered.extra.length;
+        }
+        if (filtered.empty.length) {
+            entry.empty = filtered.empty;
             exitWithError = true;
+            totals.empty += filtered.empty.length;
         }
-        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 (filtered.mismatches.length) {
+            entry.valueMismatches = filtered.mismatches;
+            totals.mismatch += filtered.mismatches.length;
+            exitWithError = true;
+        }
+        if (filtered.duplicatesEnv.length || filtered.duplicatesEx.length) {
+            totals.duplicate +=
+                filtered.duplicatesEnv.length + filtered.duplicatesEx.length;
+            exitWithError = true;
+        }
+        if (filtered.gitignoreUnsafe) {
+            totals.gitignore += 1;
+            exitWithError = true;
         }
         if (!opts.json) {
-            if (diff.missing.length) {
+            if (filtered.missing.length) {
                 console.log(chalk.red('  ❌ Missing keys:'));
-                diff.missing.forEach((key) => console.log(chalk.red(`      - ${key}`)));
+                filtered.missing.forEach((key) => console.log(chalk.red(`      - ${key}`)));
             }
-            if (diff.extra.length) {
+            if (filtered.extra.length) {
                 console.log(chalk.yellow('  ⚠️  Extra keys (not in example):'));
-                diff.extra.forEach((key) => console.log(chalk.yellow(`      - ${key}`)));
+                filtered.extra.forEach((key) => console.log(chalk.yellow(`      - ${key}`)));
             }
-            if (emptyKeys.length) {
+            if (filtered.empty.length) {
                 console.log(chalk.yellow('  ⚠️  Empty values:'));
-                emptyKeys.forEach((key) => console.log(chalk.yellow(`      - ${key}`)));
+                filtered.empty.forEach((key) => console.log(chalk.yellow(`      - ${key}`)));
             }
-            if (opts.checkValues && diff.valueMismatches.length) {
+            if (filtered.mismatches.length) {
                 console.log(chalk.yellow('  ⚠️  Value mismatches:'));
-                diff.valueMismatches.forEach(({ key, expected, actual }) => console.log(chalk.yellow(`      - ${key}: expected '${expected}', but got '${actual}'`)));
+                filtered.mismatches.forEach(({ key, expected, actual }) => console.log(chalk.yellow(`      - ${key}: expected '${expected}', but got '${actual}'`)));
             }
             console.log();
         }

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

@@ -1,21 +1,2 @@
-export type Options = {
-    checkValues: boolean;
-    isCiMode: boolean;
-    isYesMode: boolean;
-    allowDuplicates: boolean;
-    json: boolean;
-    envFlag: string | null;
-    exampleFlag: string | null;
-    cwd: string;
-};
-type RawOptions = {
-    checkValues?: boolean;
-    ci?: boolean;
-    yes?: boolean;
-    allowDuplicates?: boolean;
-    json?: boolean;
-    env?: string;
-    example?: string;
-};
+import { Options, RawOptions } from './types.js';
 export declare function normalizeOptions(raw: RawOptions): Options;
-export {};

package/dist/src/config/options.js

@@ -1,11 +1,41 @@
 import chalk from 'chalk';
 import path from 'path';
+import { ALLOWED_CATEGORIES } from './types.js';
+function parseList(val) {
+    const arr = Array.isArray(val) ? val : val ? [val] : [];
+    return arr
+        .flatMap((s) => String(s).split(','))
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+function parseCategories(val, flagName = '') {
+    const raw = parseList(val);
+    const bad = raw.filter((c) => !ALLOWED_CATEGORIES.includes(c));
+    if (bad.length) {
+        console.error(chalk.red(`❌ Error: invalid ${flagName} value(s): ${bad.join(', ')}. Allowed: ${ALLOWED_CATEGORIES.join(', ')}`));
+        process.exit(1);
+    }
+    return raw;
+}
 export function normalizeOptions(raw) {
     const checkValues = raw.checkValues ?? false;
     const isCiMode = Boolean(raw.ci);
     const isYesMode = Boolean(raw.yes);
     const allowDuplicates = Boolean(raw.allowDuplicates);
     const json = Boolean(raw.json);
+    const onlyParsed = parseCategories(raw.only, '--only');
+    const only = onlyParsed.length ? onlyParsed : undefined;
+    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.'));
     }
@@ -20,6 +50,9 @@ export function normalizeOptions(raw) {
         json,
         envFlag,
         exampleFlag,
+        ignore,
+        ignoreRegex,
         cwd,
+        only,
     };
 }

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

@@ -0,0 +1,53 @@
+export declare const ALLOWED_CATEGORIES: readonly ["missing", "extra", "empty", "mismatch", "duplicate", "gitignore"];
+export type Category = (typeof ALLOWED_CATEGORIES)[number];
+export type Options = {
+    checkValues: boolean;
+    isCiMode: boolean;
+    isYesMode: boolean;
+    allowDuplicates: boolean;
+    json: boolean;
+    envFlag: string | null;
+    exampleFlag: string | null;
+    ignore: string[];
+    ignoreRegex: RegExp[];
+    cwd: string;
+    only?: Category[];
+};
+export type RawOptions = {
+    checkValues?: boolean;
+    ci?: boolean;
+    yes?: boolean;
+    allowDuplicates?: boolean;
+    json?: boolean;
+    env?: string;
+    example?: string;
+    ignore?: string | string[];
+    ignoreRegex?: string | string[];
+    only?: string | string[];
+};
+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;
+};

package/dist/src/config/types.js

@@ -0,0 +1,8 @@
+export const ALLOWED_CATEGORIES = [
+    'missing',
+    'extra',
+    'empty',
+    'mismatch',
+    'duplicate',
+    'gitignore',
+];

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.3",
+  "version": "1.6.5",
   "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",