dotenv-diff 2.0.0 → 2.1.0

package/README.md

@@ -42,6 +42,27 @@ dotenv-diff --scan-usage
 ``` 
 This scans your entire codebase to detect which environment variables are actually used in the code — and compare them against your `.env` file(s).
 
+## CI/CD integration with `--ci` option
+You can scan and compare against specific environment file, eg. `.env.example`
+This is useful for CI/CD pipelines to ensure that the environment variables used in your code match those defined in your `.env.example` file.
+
+Use the `--ci` flag for automated environments. This enables strict mode where the tool exits with code 1 on any issues, making it perfect for CI/CD pipelines.
+
+And the `--example` option allows you to specify which `.env.example` file to compare against.
+
+### Use it in Github Actions:
+
+```yaml
+- name: Check environment variables
+  run: dotenv-diff --scan-usage --example .env.example --ci
+```
+
+You can also change the comparison file by using the `--example` flag to point to a different `.env.example` file. 
+
+```bash
+dotenv-diff --scan-usage --example .env.example.staging --ci
+```
+
 ## Show unused variables
 
 Use `--show-unused` together with `--scan-usage` to list variables that are defined in `.env` but never used in your codebase:

package/dist/src/cli/run.js

@@ -19,10 +19,12 @@ export async function run(program) {
             exclude: opts.excludeFiles,
             ignore: opts.ignore,
             ignoreRegex: opts.ignoreRegex,
+            examplePath: opts.exampleFlag || undefined,
             envPath,
             json: opts.json,
             showUnused: opts.showUnused,
             showStats: opts.showStats,
+            isCiMode: opts.isCiMode,
         });
         process.exit(exitWithError ? 1 : 0);
     }

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

@@ -1,9 +1,11 @@
 import { type ScanOptions } from '../services/codeBaseScanner.js';
 export interface ScanUsageOptions extends ScanOptions {
     envPath?: string;
+    examplePath?: string;
     json: boolean;
     showUnused: boolean;
     showStats: boolean;
+    isCiMode?: boolean;
 }
 export interface ScanJsonEntry {
     stats: {
@@ -28,14 +30,18 @@ export interface ScanJsonEntry {
         pattern: string;
         context: string;
     }>;
+    comparedAgainst?: string;
+    totalEnvVariables?: number;
 }
 /**
  * Scans codebase for environment variable usage and compares with .env file
  * @param {ScanUsageOptions} opts - Scan configuration options
  * @param {string} [opts.envPath] - Path to .env file for comparison
+ * @param {string} [opts.examplePath] - Path to .env.example file for comparison
  * @param {boolean} opts.json - Output as JSON instead of console
  * @param {boolean} opts.showUnused - Show unused variables from .env
  * @param {boolean} opts.showStats - Show detailed statistics
+ * @param {boolean} [opts.isCiMode] - Run in CI mode (exit with error code)
  * @returns {Promise<{exitWithError: boolean}>} Returns true if missing variables found
  */
 export declare function scanUsage(opts: ScanUsageOptions): Promise<{

package/dist/src/commands/scanUsage.js

@@ -1,4 +1,6 @@
 import chalk from 'chalk';
+import fs from 'fs';
+import path from 'path';
 import { parseEnvFile } from '../lib/parseEnv.js';
 import { scanCodebase, compareWithEnvFiles, } from '../services/codeBaseScanner.js';
 import { filterIgnoredKeys } from '../core/filterIgnoredKeys.js';
@@ -6,9 +8,11 @@ import { filterIgnoredKeys } from '../core/filterIgnoredKeys.js';
  * Scans codebase for environment variable usage and compares with .env file
  * @param {ScanUsageOptions} opts - Scan configuration options
  * @param {string} [opts.envPath] - Path to .env file for comparison
+ * @param {string} [opts.examplePath] - Path to .env.example file for comparison
  * @param {boolean} opts.json - Output as JSON instead of console
  * @param {boolean} opts.showUnused - Show unused variables from .env
  * @param {boolean} opts.showStats - Show detailed statistics
+ * @param {boolean} [opts.isCiMode] - Run in CI mode (exit with error code)
  * @returns {Promise<{exitWithError: boolean}>} Returns true if missing variables found
  */
 export async function scanUsage(opts) {
@@ -18,31 +22,61 @@ export async function scanUsage(opts) {
     }
     // Scan the codebase
     let scanResult = await scanCodebase(opts);
-    // If we have an env file, compare with it
+    // Determine which file to compare against
+    const compareFile = determineComparisonFile(opts);
     let envVariables = {};
-    if (opts.envPath) {
+    let comparedAgainst = '';
+    if (compareFile) {
         try {
-            const envFull = parseEnvFile(opts.envPath);
+            const envFull = parseEnvFile(compareFile.path);
             const envKeys = filterIgnoredKeys(Object.keys(envFull), opts.ignore, opts.ignoreRegex);
             envVariables = Object.fromEntries(envKeys.map((k) => [k, envFull[k]]));
             scanResult = compareWithEnvFiles(scanResult, envVariables);
+            comparedAgainst = compareFile.name;
         }
         catch (error) {
+            const errorMessage = `⚠️  Could not read ${compareFile.name}: ${compareFile.path} - ${error}`;
+            if (opts.isCiMode) {
+                // In CI mode, exit with error if file doesn't exist
+                console.error(chalk.red(`❌ ${errorMessage}`));
+                return { exitWithError: true };
+            }
             if (!opts.json) {
-                console.log(chalk.yellow(`⚠️  Could not read env file: ${opts.envPath} - ${error}`));
+                console.log(chalk.yellow(errorMessage));
             }
         }
     }
     // Prepare JSON output
     if (opts.json) {
-        const jsonOutput = createJsonOutput(scanResult, opts);
+        const jsonOutput = createJsonOutput(scanResult, opts, comparedAgainst, Object.keys(envVariables).length);
         console.log(JSON.stringify(jsonOutput, null, 2));
         return { exitWithError: scanResult.missing.length > 0 };
     }
     // Console output
-    return outputToConsole(scanResult, opts);
+    return outputToConsole(scanResult, opts, comparedAgainst);
+}
+/**
+ * Determines which file to use for comparison based on provided options
+ */
+function determineComparisonFile(opts) {
+    // Priority: explicit flags first, then auto-discovery
+    if (opts.examplePath && fs.existsSync(opts.examplePath)) {
+        return { path: opts.examplePath, name: path.basename(opts.examplePath) };
+    }
+    if (opts.envPath && fs.existsSync(opts.envPath)) {
+        return { path: opts.envPath, name: path.basename(opts.envPath) };
+    }
+    // Auto-discovery: look for common env files
+    const candidates = ['.env', '.env.example', '.env.local', '.env.production'];
+    for (const candidate of candidates) {
+        const fullPath = path.resolve(opts.cwd, candidate);
+        if (fs.existsSync(fullPath)) {
+            return { path: fullPath, name: candidate };
+        }
+    }
+    return null;
 }
-function createJsonOutput(scanResult, opts) {
+function createJsonOutput(scanResult, opts, comparedAgainst, totalEnvVariables) {
     // Group usages by variable for missing variables
     const missingGrouped = scanResult.missing.map((variable) => ({
         variable,
@@ -60,6 +94,11 @@ function createJsonOutput(scanResult, opts) {
         missing: missingGrouped,
         unused: scanResult.unused,
     };
+    // Add comparison info if we compared against a file
+    if (comparedAgainst) {
+        output.comparedAgainst = comparedAgainst;
+        output.totalEnvVariables = totalEnvVariables;
+    }
     // Optionally include all usages
     if (opts.showStats) {
         output.allUsages = scanResult.used.map((u) => ({
@@ -72,8 +111,13 @@ function createJsonOutput(scanResult, opts) {
     }
     return output;
 }
-function outputToConsole(scanResult, opts) {
+function outputToConsole(scanResult, opts, comparedAgainst) {
     let exitWithError = false;
+    // Show what we're comparing against
+    if (comparedAgainst) {
+        console.log(chalk.gray(`📋 Comparing codebase usage against: ${comparedAgainst}`));
+        console.log();
+    }
     // Show stats if requested
     if (opts.showStats) {
         console.log(chalk.bold('📊 Scan Statistics:'));
@@ -82,8 +126,8 @@ function outputToConsole(scanResult, opts) {
         console.log(chalk.gray(`   Unique variables: ${scanResult.stats.uniqueVariables}`));
         console.log();
     }
-    // Always show found variables when not in .env comparison mode
-    if (!opts.envPath || scanResult.missing.length === 0) {
+    // Always show found variables when not comparing or when no missing variables
+    if (!comparedAgainst || scanResult.missing.length === 0) {
         console.log(chalk.green(`✅ Found ${scanResult.stats.uniqueVariables} unique environment variables in use`));
         console.log();
         // List all variables found (if any)
@@ -113,10 +157,11 @@ function outputToConsole(scanResult, opts) {
             console.log();
         }
     }
-    // Missing variables (used in code but not in .env)
+    // Missing variables (used in code but not in env file)
     if (scanResult.missing.length > 0) {
         exitWithError = true;
-        console.log(chalk.red('❌ Missing in .env:'));
+        const fileType = comparedAgainst || 'environment file';
+        console.log(chalk.red(`❌ Missing in ${fileType}:`));
         const grouped = scanResult.missing.reduce((acc, variable) => {
             const usages = scanResult.used.filter((u) => u.variable === variable);
             acc[variable] = usages;
@@ -134,21 +179,29 @@ function outputToConsole(scanResult, opts) {
             }
         }
         console.log();
+        // CI mode specific message
+        if (opts.isCiMode) {
+            console.log(chalk.red(`💥 Found ${scanResult.missing.length} missing environment variable(s).`));
+            console.log(chalk.red(`   Add these variables to ${comparedAgainst || 'your environment file'} to fix this error.`));
+            console.log();
+        }
     }
-    // Unused variables (in .env but not used in code)
+    // Unused variables (in env file but not used in code)
     if (opts.showUnused && scanResult.unused.length > 0) {
-        console.log(chalk.yellow('⚠️  Unused in codebase:'));
+        const fileType = comparedAgainst || 'environment file';
+        console.log(chalk.yellow(`⚠️  Unused in codebase (defined in ${fileType}):`));
         scanResult.unused.forEach((variable) => {
             console.log(chalk.yellow(`   - ${variable}`));
         });
         console.log();
     }
-    // Success message for .env comparison
-    if (opts.envPath && scanResult.missing.length === 0) {
-        console.log(chalk.green('✅ All used environment variables are defined in .env'));
+    // Success message for env file comparison
+    if (comparedAgainst && scanResult.missing.length === 0) {
+        console.log(chalk.green(`✅ All used environment variables are defined in ${comparedAgainst}`));
         if (opts.showUnused && scanResult.unused.length === 0) {
             console.log(chalk.green('✅ No unused environment variables found'));
         }
+        console.log();
     }
     return { exitWithError };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotenv-diff",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "type": "module",
   "description": "A CLI tool to find differences between .env and .env.example / .env.* files. And optionally scan your codebase to find out which environment variables are actually used in your code.",
   "bin": {