dotenv-diff 2.0.0 → 2.1.1

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:
@@ -59,13 +80,22 @@ This will display statistics about the scan, such as the number of files scanned
 
 ## include or exclude specific files for scanning
 
-You can specify which files to include or exclude from the scan using the `--include-files` and `--exclude-files` options:
+You can specify which files to include or exclude from the scan using the `--include` and `--exclude` options:
 
 ```bash
-dotenv-diff --scan-usage --include-files '**/*.js,**/*.ts' --exclude-files '**/*.spec.ts'
+dotenv-diff --scan-usage --include '**/*.js,**/*.ts' --exclude '**/*.spec.ts'
 ```
 
-This allows you to focus the scan on specific file types or directories, making it more efficient and tailored to your project structure.
+By default, the scanner looks at JavaScript, TypeScript, Vue, and Svelte files.
+The --include and --exclude options let you refine this list to focus on specific file types or directories.
+
+### Override with `--files`
+
+If you want to completely override the default include/exclude logic (for example, to also include test files), you can use --files:
+```bash
+dotenv-diff --scan-usage --files '**/*.js'
+```
+This will only scan the files matching the given patterns, even if they would normally be excluded.
 
 ## Optional: Check values too
 

package/dist/src/cli/program.js

@@ -14,7 +14,8 @@ export function createProgram() {
         .option('--json', 'Output results in JSON format')
         .option('--only <list>', 'Comma-separated categories to only run (missing,extra,empty,mismatch,duplicate,gitignore)')
         .option('--scan-usage', 'Scan codebase for environment variable usage')
-        .option('--include-files <patterns>', '[requires --scan-usage] Comma-separated file patterns to include in scan (default: **/*.{js,ts,jsx,tsx,vue,svelte})')
+        .option('--include-files <patterns>', '[requires --scan-usage] Comma-separated file patterns to ADD to default scan patterns (extends default)')
+        .option('--files <patterns>', '[requires --scan-usage] Comma-separated file patterns to scan (completely replaces default patterns)')
         .option('--exclude-files <patterns>', '[requires --scan-usage] Comma-separated file patterns to exclude from scan')
         .option('--show-unused', '[requires --scan-usage] Show variables defined in .env but not used in code')
         .option('--show-stats', 'Show statistics (in scan-usage mode: scan stats, in compare mode: env compare stats)');

package/dist/src/cli/run.js

@@ -19,10 +19,13 @@ 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,
+            files: opts.files,
         });
         process.exit(exitWithError ? 1 : 0);
     }

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

@@ -1,9 +1,12 @@
 import { type ScanOptions } from '../services/codeBaseScanner.js';
 export interface ScanUsageOptions extends ScanOptions {
     envPath?: string;
+    examplePath?: string;
     json: boolean;
     showUnused: boolean;
     showStats: boolean;
+    isCiMode?: boolean;
+    files?: string[];
 }
 export interface ScanJsonEntry {
     stats: {
@@ -28,14 +31,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,14 +1,19 @@
 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';
+const resolveFromCwd = (cwd, p) => path.isAbsolute(p) ? p : path.resolve(cwd, p);
 /**
  * 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 +23,84 @@ export async function scanUsage(opts) {
     }
     // Scan the codebase
     let scanResult = await scanCodebase(opts);
-    // If we have an env file, compare with it
+    // If user explicitly passed --example but the file doesn't exist:
+    if (opts.examplePath) {
+        const exampleAbs = resolveFromCwd(opts.cwd, opts.examplePath);
+        const missing = !fs.existsSync(exampleAbs);
+        if (missing) {
+            const msg = `❌ Missing specified example file: ${opts.examplePath}`;
+            if (opts.isCiMode) {
+                // IMPORTANT: stdout (console.log), not stderr, to satisfy the test
+                console.log(chalk.red(msg));
+                return { exitWithError: true };
+            }
+            else if (!opts.json) {
+                console.log(chalk.yellow(msg.replace('❌', '⚠️')));
+            }
+            // Non-CI: continue without comparison
+        }
+    }
+    // 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.log(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) {
+        const p = resolveFromCwd(opts.cwd, opts.examplePath);
+        if (fs.existsSync(p)) {
+            return { path: p, name: path.basename(opts.examplePath) };
+        }
+    }
+    if (opts.envPath) {
+        const p = resolveFromCwd(opts.cwd, opts.envPath);
+        if (fs.existsSync(p)) {
+            return { path: p, name: path.basename(opts.envPath) };
+        }
+    }
+    // Auto-discovery: look for common env files relative to cwd
+    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 +118,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 +135,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 +150,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 +181,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 +203,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/dist/src/config/options.js

@@ -30,6 +30,7 @@ export function normalizeOptions(raw) {
     const excludeFiles = parseList(raw.excludeFiles);
     const showUnused = Boolean(raw.showUnused);
     const showStats = Boolean(raw.showStats);
+    const files = parseList(raw.files);
     const ignore = parseList(raw.ignore);
     const ignoreRegex = [];
     for (const pattern of parseList(raw.ignoreRegex)) {
@@ -64,5 +65,6 @@ export function normalizeOptions(raw) {
         excludeFiles,
         showUnused,
         showStats,
+        files,
     };
 }

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

@@ -17,6 +17,7 @@ export type Options = {
     excludeFiles: string[];
     showUnused: boolean;
     showStats: boolean;
+    files?: string[];
 };
 export type RawOptions = {
     checkValues?: boolean;
@@ -34,6 +35,7 @@ export type RawOptions = {
     excludeFiles?: string | string[];
     showUnused?: boolean;
     showStats?: boolean;
+    files?: string | string[];
 };
 export type CompareJsonEntry = {
     env: string;

package/dist/src/services/codeBaseScanner.d.ts

@@ -12,6 +12,7 @@ export interface ScanOptions {
     exclude: string[];
     ignore: string[];
     ignoreRegex: RegExp[];
+    files?: string[];
 }
 export interface ScanResult {
     used: EnvUsage[];

package/dist/src/services/codeBaseScanner.js

@@ -1,5 +1,6 @@
 import fs from 'fs/promises';
 import path from 'path';
+import fsSync from 'fs';
 // Framework-specific patterns for finding environment variable usage
 const ENV_PATTERNS = [
     {
@@ -67,6 +68,7 @@ export async function scanCodebase(opts) {
     const files = await findFiles(opts.cwd, {
         include: opts.include,
         exclude: [...DEFAULT_EXCLUDE_PATTERNS, ...opts.exclude],
+        files: opts.files, // Pass files option
     });
     const allUsages = [];
     let filesScanned = 0;
@@ -97,14 +99,117 @@ export async function scanCodebase(opts) {
         },
     };
 }
+function expandBraceSets(pattern) {
+    // Single-level brace expansion: **/*.{js,ts,svelte} -> [**/*.js, **/*.ts, **/*.svelte]
+    const m = pattern.match(/\{([^}]+)\}/);
+    if (!m)
+        return [pattern];
+    const variants = m[1]
+        .split(',')
+        .map((p) => p.trim())
+        .filter(Boolean);
+    const prefix = pattern.slice(0, m.index);
+    const suffix = pattern.slice(m.index + m[0].length);
+    return variants.flatMap((v) => expandBraceSets(`${prefix}${v}${suffix}`));
+}
 /**
  * Recursively finds all files in the given directory matching the include patterns,
  * while excluding files and directories that match the exclude patterns.
  * @param rootDir The root directory to start searching from.
- * @param opts Options for include and exclude patterns.
+ * @param opts Options for include, exclude patterns and files override.
  * @returns A promise that resolves to an array of file paths.
  */
 async function findFiles(rootDir, opts) {
+    // If --files provided, keep existing replacement behavior
+    if (opts.files && opts.files.length > 0) {
+        return findFilesByPatterns(rootDir, opts.files);
+    }
+    const defaultPatterns = getDefaultPatterns();
+    const rawInclude = opts.include.length > 0
+        ? [...defaultPatterns, ...opts.include]
+        : defaultPatterns;
+    const includePatterns = rawInclude.flatMap(expandBraceSets);
+    const files = [];
+    const walked = new Set();
+    // Compute additional roots for include patterns that point outside cwd or are absolute
+    const extraRoots = new Set();
+    for (const p of includePatterns) {
+        const hasParentEscape = p.includes('..') || path.isAbsolute(p);
+        if (!hasParentEscape)
+            continue;
+        const dir = getPatternBaseDir(rootDir, p);
+        if (dir && !dir.startsWith(rootDir)) {
+            extraRoots.add(dir);
+        }
+    }
+    async function walk(startDir) {
+        // prevent duplicate subtree walks
+        const key = path.resolve(startDir);
+        if (walked.has(key))
+            return;
+        walked.add(key);
+        let entries;
+        try {
+            entries = await fs.readdir(startDir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            const fullPath = path.join(startDir, entry.name);
+            const relativeToRoot = path.relative(rootDir, fullPath);
+            // Exclude checks should use path relative to *rootDir* (keeps existing semantics)
+            if (shouldExclude(entry.name, relativeToRoot, [
+                ...DEFAULT_EXCLUDE_PATTERNS,
+                ...opts.exclude,
+            ])) {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                await walk(fullPath);
+            }
+            else if (entry.isFile() &&
+                shouldInclude(entry.name, relativeToRoot, includePatterns)) {
+                files.push(fullPath);
+            }
+        }
+    }
+    // Walk root first (current behavior)
+    await walk(rootDir);
+    // Walk any extra roots (e.g., ../../packages/…)
+    for (const r of extraRoots) {
+        await walk(r);
+    }
+    return files;
+}
+function getPatternBaseDir(rootDir, pattern) {
+    // Stop at first glob char — DO NOT include '/' here
+    const idx = pattern.search(/[*?\[\]{}]/); // <— removed '/'
+    const raw = idx === -1 ? pattern : pattern.slice(0, idx);
+    const base = path.isAbsolute(raw) ? raw : path.resolve(rootDir, raw);
+    try {
+        const st = fsSync.statSync(base);
+        if (st.isDirectory())
+            return base;
+        if (st.isFile())
+            return path.dirname(base);
+    }
+    catch {
+        const dir = path.dirname(base);
+        try {
+            const st2 = fsSync.statSync(dir);
+            if (st2.isDirectory())
+                return dir;
+        }
+        catch { }
+    }
+    return null;
+}
+/**
+ * Find files using the --files patterns (complete replacement mode)
+ */
+async function findFilesByPatterns(rootDir, patterns) {
+    const expanded = patterns.flatMap(expandBraceSets);
     const files = [];
     async function walk(currentDir) {
         let entries;
@@ -112,21 +217,16 @@ async function findFiles(rootDir, opts) {
             entries = await fs.readdir(currentDir, { withFileTypes: true });
         }
         catch {
-            // Skip directories we can't read (permissions, etc.)
             return;
         }
         for (const entry of entries) {
             const fullPath = path.join(currentDir, entry.name);
             const relativePath = path.relative(rootDir, fullPath);
-            // Check if should be excluded (directory or file)
-            if (shouldExclude(entry.name, relativePath, opts.exclude)) {
-                continue;
-            }
             if (entry.isDirectory()) {
                 await walk(fullPath);
             }
             else if (entry.isFile() &&
-                shouldInclude(entry.name, relativePath, opts.include)) {
+                shouldInclude(entry.name, relativePath, expanded)) {
                 files.push(fullPath);
             }
         }
@@ -134,6 +234,12 @@ async function findFiles(rootDir, opts) {
     await walk(rootDir);
     return files;
 }
+/**
+ * Generate default patterns from extensions
+ */
+function getDefaultPatterns() {
+    return DEFAULT_INCLUDE_EXTENSIONS.map((ext) => `**/*${ext}`);
+}
 /**
  * Check if a file should be included based on its name, path, and include patterns.
  * @param fileName The name of the file.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotenv-diff",
-  "version": "2.0.0",
+  "version": "2.1.1",
   "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": {