dotenv-diff 1.6.2 → 1.6.3

package/README.md

@@ -43,6 +43,14 @@ 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`.
 
+## 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,6 @@ 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('--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,24 +23,26 @@ export async function run(program) {
             }
             process.exit(1);
         }
-        const { exitWithError } = await compareMany([
-            {
-                envName: path.basename(opts.envFlag),
-                envPath: opts.envFlag,
-                examplePath: opts.exampleFlag,
-            },
-        ], {
+        const report = [];
+        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,
+            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 +51,24 @@ 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,
+        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,8 @@ export declare function compareMany(pairs: Array<{
     checkValues: boolean;
     cwd: string;
     allowDuplicates?: boolean;
+    json?: boolean;
+    collect?: (entry: CompareJsonEntry) => void;
 }): Promise<{
     exitWithError: boolean;
 }>;

package/dist/src/commands/compare.js

@@ -8,65 +8,103 @@ import { findDuplicateKeys } from '../services/duplicates.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 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 || dupsEx.length) {
+                entry.duplicates = {};
+            }
+            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)`)));
+                }
             }
         }
+        // Diff + empty
         const current = parseEnvFile(envPath);
         const example = parseEnvFile(examplePath);
         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 (emptyKeys.length > 0) {
-            console.log(chalk.yellow('  ⚠️  Empty values:'));
-            emptyKeys.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 (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,6 +3,7 @@ export type Options = {
     isCiMode: boolean;
     isYesMode: boolean;
     allowDuplicates: boolean;
+    json: boolean;
     envFlag: string | null;
     exampleFlag: string | null;
     cwd: string;
@@ -12,6 +13,7 @@ type RawOptions = {
     ci?: boolean;
     yes?: boolean;
     allowDuplicates?: boolean;
+    json?: boolean;
     env?: string;
     example?: string;
 };

package/dist/src/config/options.js

@@ -5,6 +5,7 @@ export function normalizeOptions(raw) {
     const isCiMode = Boolean(raw.ci);
     const isYesMode = Boolean(raw.yes);
     const allowDuplicates = Boolean(raw.allowDuplicates);
+    const json = Boolean(raw.json);
     if (isCiMode && isYesMode) {
         console.log(chalk.yellow('⚠️  Both --ci and --yes provided; proceeding with --yes.'));
     }
@@ -16,6 +17,7 @@ export function normalizeOptions(raw) {
         isCiMode,
         isYesMode,
         allowDuplicates,
+        json,
         envFlag,
         exampleFlag,
         cwd,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotenv-diff",
-  "version": "1.6.2",
+  "version": "1.6.3",
   "type": "module",
   "description": "A small CLI and library to find differences between .env and .env.example files.",
   "bin": {