dotenv-diff 1.6.5 → 2.1.0

package/README.md

@@ -2,6 +2,10 @@
 
 Easily compare your .env, .env.example, and other environment files (like .env.local, .env.production) to detect missing, extra, empty, or mismatched variables — and ensure they’re properly ignored by Git.
 
+Or scan your codebase to find out which environment variables are actually used in your code, and which ones are not.
+
+Optimized for JavaScript/TypeScript projects and frontend frameworks including Node.js, Next.js, Vite, SvelteKit, Nuxt, Vue, and Deno. Can also be used with other project types for basic .env file comparison.
+
 [![npm version](https://img.shields.io/npm/v/dotenv-diff.svg)](https://www.npmjs.com/package/dotenv-diff)
 [![npm downloads](https://img.shields.io/npm/dt/dotenv-diff.svg)](https://www.npmjs.com/package/dotenv-diff)
 
@@ -31,6 +35,59 @@ dotenv-diff will automatically compare all matching .env* files in your project
 - `.env.production`
 - Any other .env.* file
 
+## Scan your codebase for environment variable usage
+
+```bash
+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:
+```bash
+dotenv-diff --scan-usage --show-unused
+```
+This will show you which variables are defined in your `.env` file but not used in your codebase. This helps you clean up unnecessary environment variables.
+
+## Show scan statistics
+
+```bash
+dotenv-diff --show-stats
+```
+This will display statistics about the scan, such as the number of files scanned, variables found, and any unused variables. It provides a quick overview of your environment variable usage.
+
+## 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:
+
+```bash
+dotenv-diff --scan-usage --include-files '**/*.js,**/*.ts' --exclude-files '**/*.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.
+
 ## Optional: Check values too
 
 ```bash

package/dist/src/cli/program.js

@@ -12,5 +12,10 @@ export function createProgram() {
         .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)');
+        .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('--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

@@ -6,10 +6,28 @@ 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 { scanUsage } from '../commands/scanUsage.js';
 export async function run(program) {
     program.parse(process.argv);
     const raw = program.opts();
     const opts = normalizeOptions(raw);
+    if (opts.scanUsage) {
+        const envPath = opts.envFlag || (fs.existsSync('.env') ? '.env' : undefined);
+        const { exitWithError } = await scanUsage({
+            cwd: opts.cwd,
+            include: opts.includeFiles,
+            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);
+    }
     // Special-case: both flags → direct comparison of exactly those two files
     if (opts.envFlag && opts.exampleFlag) {
         const envExists = fs.existsSync(opts.envFlag);
@@ -38,6 +56,7 @@ export async function run(program) {
             ignore: opts.ignore,
             ignoreRegex: opts.ignoreRegex,
             only: opts.only,
+            showStats: opts.showStats,
             collect: (e) => report.push(e),
         });
         if (opts.json) {
@@ -77,6 +96,7 @@ export async function run(program) {
         ignore: opts.ignore,
         ignoreRegex: opts.ignoreRegex,
         only: opts.only,
+        showStats: opts.showStats,
         collect: (e) => report.push(e),
     });
     if (opts.json) {

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

@@ -12,6 +12,7 @@ export declare function compareMany(pairs: Array<{
     ignoreRegex: RegExp[];
     collect?: (entry: CompareJsonEntry) => void;
     only?: Category[];
+    showStats?: boolean;
 }): Promise<{
     exitWithError: boolean;
 }>;

package/dist/src/commands/compare.js

@@ -60,22 +60,22 @@ export async function compareMany(pairs, opts) {
                 !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 = {};
-            }
-            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 (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)`)));
-                }
+        }
+        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
@@ -111,6 +111,27 @@ export async function compareMany(pairs, opts) {
             opts.collect?.(entry);
             continue;
         }
+        // --- Stats block for compare mode when --show-stats is active ---
+        if (opts.showStats && !opts.json) {
+            const envCount = currentKeys.length;
+            const exampleCount = exampleKeys.length;
+            const sharedCount = new Set(currentKeys.filter((k) => exampleKeys.includes(k))).size;
+            // Duplicate "occurrences beyond the first", summed across both files
+            const duplicateCount = [...dupsEnv, ...dupsEx].reduce((acc, { count }) => acc + Math.max(0, count - 1), 0);
+            const valueMismatchCount = opts.checkValues
+                ? filtered.mismatches.length
+                : 0;
+            console.log(chalk.bold('  📊 Compare Statistics:'));
+            console.log(chalk.gray(`     Keys in ${envName}: ${envCount}`));
+            console.log(chalk.gray(`     Keys in ${exampleName}: ${exampleCount}`));
+            console.log(chalk.gray(`     Shared keys: ${sharedCount}`));
+            console.log(chalk.gray(`     Missing (in ${envName}): ${filtered.missing.length}`));
+            console.log(chalk.gray(`     Extra (not in ${exampleName}): ${filtered.extra.length}`));
+            console.log(chalk.gray(`     Empty values: ${filtered.empty.length}`));
+            console.log(chalk.gray(`     Duplicate keys: ${duplicateCount}`));
+            console.log(chalk.gray(`     Value mismatches: ${valueMismatchCount}`));
+            console.log();
+        }
         if (filtered.missing.length) {
             entry.missing = filtered.missing;
             exitWithError = true;

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

@@ -0,0 +1,49 @@
+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: {
+        filesScanned: number;
+        totalUsages: number;
+        uniqueVariables: number;
+    };
+    missing: Array<{
+        variable: string;
+        usages: Array<{
+            file: string;
+            line: number;
+            pattern: string;
+            context: string;
+        }>;
+    }>;
+    unused: string[];
+    allUsages?: Array<{
+        variable: string;
+        file: string;
+        line: number;
+        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<{
+    exitWithError: boolean;
+}>;

package/dist/src/commands/scanUsage.js

@@ -0,0 +1,207 @@
+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';
+/**
+ * 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) {
+    if (!opts.json) {
+        console.log(chalk.bold('🔍 Scanning codebase for environment variable usage...'));
+        console.log();
+    }
+    // Scan the codebase
+    let scanResult = await scanCodebase(opts);
+    // Determine which file to compare against
+    const compareFile = determineComparisonFile(opts);
+    let envVariables = {};
+    let comparedAgainst = '';
+    if (compareFile) {
+        try {
+            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(errorMessage));
+            }
+        }
+    }
+    // Prepare JSON output
+    if (opts.json) {
+        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, 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, comparedAgainst, totalEnvVariables) {
+    // Group usages by variable for missing variables
+    const missingGrouped = scanResult.missing.map((variable) => ({
+        variable,
+        usages: scanResult.used
+            .filter((u) => u.variable === variable)
+            .map((u) => ({
+            file: u.file,
+            line: u.line,
+            pattern: u.pattern,
+            context: u.context,
+        })),
+    }));
+    const output = {
+        stats: scanResult.stats,
+        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) => ({
+            variable: u.variable,
+            file: u.file,
+            line: u.line,
+            pattern: u.pattern,
+            context: u.context,
+        }));
+    }
+    return output;
+}
+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:'));
+        console.log(chalk.gray(`   Files scanned: ${scanResult.stats.filesScanned}`));
+        console.log(chalk.gray(`   Total usages found: ${scanResult.stats.totalUsages}`));
+        console.log(chalk.gray(`   Unique variables: ${scanResult.stats.uniqueVariables}`));
+        console.log();
+    }
+    // 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)
+        if (scanResult.stats.uniqueVariables > 0) {
+            // Group by variable to get unique list
+            const variableUsages = scanResult.used.reduce((acc, usage) => {
+                if (!acc[usage.variable]) {
+                    acc[usage.variable] = [];
+                }
+                acc[usage.variable].push(usage);
+                return acc;
+            }, {});
+            // Display each unique variable
+            for (const [variable, usages] of Object.entries(variableUsages)) {
+                console.log(chalk.blue(`   ${variable}`));
+                // Show usage details if stats are enabled
+                if (opts.showStats) {
+                    const displayUsages = usages.slice(0, 2);
+                    displayUsages.forEach((usage) => {
+                        console.log(chalk.gray(`     Used in: ${usage.file}:${usage.line} (${usage.pattern})`));
+                    });
+                    if (usages.length > 2) {
+                        console.log(chalk.gray(`     ... and ${usages.length - 2} more locations`));
+                    }
+                }
+            }
+            console.log();
+        }
+    }
+    // Missing variables (used in code but not in env file)
+    if (scanResult.missing.length > 0) {
+        exitWithError = true;
+        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;
+            return acc;
+        }, {});
+        for (const [variable, usages] of Object.entries(grouped)) {
+            console.log(chalk.red(`   - ${variable}`));
+            // Show first few usages
+            const maxShow = 3;
+            usages.slice(0, maxShow).forEach((usage) => {
+                console.log(chalk.gray(`     Used in: ${usage.file}:${usage.line} (${usage.pattern})`));
+            });
+            if (usages.length > maxShow) {
+                console.log(chalk.gray(`     ... and ${usages.length - maxShow} more locations`));
+            }
+        }
+        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 file but not used in code)
+    if (opts.showUnused && scanResult.unused.length > 0) {
+        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 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

@@ -25,6 +25,11 @@ export function normalizeOptions(raw) {
     const json = Boolean(raw.json);
     const onlyParsed = parseCategories(raw.only, '--only');
     const only = onlyParsed.length ? onlyParsed : undefined;
+    const scanUsage = Boolean(raw.scanUsage);
+    const includeFiles = parseList(raw.includeFiles);
+    const excludeFiles = parseList(raw.excludeFiles);
+    const showUnused = Boolean(raw.showUnused);
+    const showStats = Boolean(raw.showStats);
     const ignore = parseList(raw.ignore);
     const ignoreRegex = [];
     for (const pattern of parseList(raw.ignoreRegex)) {
@@ -54,5 +59,10 @@ export function normalizeOptions(raw) {
         ignoreRegex,
         cwd,
         only,
+        scanUsage,
+        includeFiles,
+        excludeFiles,
+        showUnused,
+        showStats,
     };
 }

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

@@ -12,6 +12,11 @@ export type Options = {
     ignoreRegex: RegExp[];
     cwd: string;
     only?: Category[];
+    scanUsage: boolean;
+    includeFiles: string[];
+    excludeFiles: string[];
+    showUnused: boolean;
+    showStats: boolean;
 };
 export type RawOptions = {
     checkValues?: boolean;
@@ -24,6 +29,11 @@ export type RawOptions = {
     ignore?: string | string[];
     ignoreRegex?: string | string[];
     only?: string | string[];
+    scanUsage?: boolean;
+    includeFiles?: string | string[];
+    excludeFiles?: string | string[];
+    showUnused?: boolean;
+    showStats?: boolean;
 };
 export type CompareJsonEntry = {
     env: string;

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

@@ -0,0 +1,32 @@
+export interface EnvUsage {
+    variable: string;
+    file: string;
+    line: number;
+    column: number;
+    pattern: 'process.env' | 'import.meta.env' | 'sveltekit' | 'deno' | 'next' | 'nuxt';
+    context: string;
+}
+export interface ScanOptions {
+    cwd: string;
+    include: string[];
+    exclude: string[];
+    ignore: string[];
+    ignoreRegex: RegExp[];
+}
+export interface ScanResult {
+    used: EnvUsage[];
+    missing: string[];
+    unused: string[];
+    stats: {
+        filesScanned: number;
+        totalUsages: number;
+        uniqueVariables: number;
+    };
+}
+/**
+ * Scans the codebase for environment variable usage based on the provided options.
+ * @param opts - Options for scanning the codebase.
+ * @returns A promise that resolves to the scan result containing used, missing, and unused variables.
+ */
+export declare function scanCodebase(opts: ScanOptions): Promise<ScanResult>;
+export declare function compareWithEnvFiles(scanResult: ScanResult, envVariables: Record<string, string | undefined>): ScanResult;

package/dist/src/services/codeBaseScanner.js

@@ -0,0 +1,236 @@
+import fs from 'fs/promises';
+import path from 'path';
+// Framework-specific patterns for finding environment variable usage
+const ENV_PATTERNS = [
+    {
+        name: 'process.env',
+        regex: /process\.env\.([A-Z_][A-Z0-9_]*)/g,
+        frameworks: ['node', 'next', 'general'],
+    },
+    {
+        name: 'import.meta.env',
+        regex: /import\.meta\.env\.([A-Z_][A-Z0-9_]*)/g,
+        frameworks: ['vite', 'svelte', 'vue'],
+    },
+    {
+        name: 'sveltekit',
+        regex: /\$env\/(?:static|dynamic)\/(?:private|public)\/([A-Z_][A-Z0-9_]*)/g,
+        frameworks: ['sveltekit'],
+    },
+    {
+        name: 'deno',
+        regex: /Deno\.env\.get\(['"`]([A-Z_][A-Z0-9_]*)['"`]\)/g,
+        frameworks: ['deno'],
+    },
+    {
+        name: 'next',
+        regex: /process\.env\.(NEXT_PUBLIC_[A-Z_][A-Z0-9_]*)/g,
+        frameworks: ['next'],
+    },
+    {
+        name: 'nuxt',
+        regex: /(?:\$config|useRuntimeConfig\(\))\.([A-Z_][A-Z0-9_]*)/g,
+        frameworks: ['nuxt'],
+    },
+];
+const DEFAULT_INCLUDE_EXTENSIONS = [
+    '.js',
+    '.ts',
+    '.jsx',
+    '.tsx',
+    '.vue',
+    '.svelte',
+    '.mjs',
+    '.cjs',
+];
+const DEFAULT_EXCLUDE_PATTERNS = [
+    'node_modules',
+    'dist',
+    'build',
+    '.next',
+    '.nuxt',
+    'coverage',
+    '.git',
+    '.vscode',
+    '.idea',
+    '.test.',
+    '.spec.',
+    '__tests__',
+    '__mocks__',
+];
+/**
+ * Scans the codebase for environment variable usage based on the provided options.
+ * @param opts - Options for scanning the codebase.
+ * @returns A promise that resolves to the scan result containing used, missing, and unused variables.
+ */
+export async function scanCodebase(opts) {
+    const files = await findFiles(opts.cwd, {
+        include: opts.include,
+        exclude: [...DEFAULT_EXCLUDE_PATTERNS, ...opts.exclude],
+    });
+    const allUsages = [];
+    let filesScanned = 0;
+    for (const filePath of files) {
+        try {
+            const content = await fs.readFile(filePath, 'utf-8');
+            const fileUsages = await scanFile(filePath, content, opts);
+            allUsages.push(...fileUsages);
+            filesScanned++;
+        }
+        catch {
+            // Skip files we can't read (binary, permissions, etc.)
+            continue;
+        }
+    }
+    // Filter out ignored variables
+    const filteredUsages = allUsages.filter((usage) => !opts.ignore.includes(usage.variable) &&
+        !opts.ignoreRegex.some((regex) => regex.test(usage.variable)));
+    const uniqueVariables = [...new Set(filteredUsages.map((u) => u.variable))];
+    return {
+        used: filteredUsages,
+        missing: [],
+        unused: [],
+        stats: {
+            filesScanned,
+            totalUsages: filteredUsages.length,
+            uniqueVariables: uniqueVariables.length,
+        },
+    };
+}
+/**
+ * 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.
+ * @returns A promise that resolves to an array of file paths.
+ */
+async function findFiles(rootDir, opts) {
+    const files = [];
+    async function walk(currentDir) {
+        let entries;
+        try {
+            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)) {
+                files.push(fullPath);
+            }
+        }
+    }
+    await walk(rootDir);
+    return files;
+}
+/**
+ * Check if a file should be included based on its name, path, and include patterns.
+ * @param fileName The name of the file.
+ * @param relativePath The relative path of the file.
+ * @param patterns The include patterns to match against.
+ * @returns True if the file should be included, false otherwise.
+ */
+function shouldInclude(fileName, relativePath, patterns) {
+    // If no include patterns specified, use default extensions
+    if (!patterns.length) {
+        return DEFAULT_INCLUDE_EXTENSIONS.some((ext) => fileName.endsWith(ext));
+    }
+    return patterns.some((pattern) => {
+        if (pattern.startsWith('**')) {
+            // Handle **/*.ext patterns
+            const ext = pattern.substring(pattern.lastIndexOf('.'));
+            return fileName.endsWith(ext);
+        }
+        else if (pattern.includes('*')) {
+            // Simple glob pattern matching
+            return matchesGlobPattern(relativePath, pattern);
+        }
+        else {
+            // Exact match or extension
+            return relativePath.includes(pattern) || fileName.endsWith(pattern);
+        }
+    });
+}
+function shouldExclude(fileName, relativePath, patterns) {
+    // Check if filename or any part of the path should be excluded
+    return patterns.some((pattern) => {
+        // Direct name match (like 'node_modules')
+        if (fileName === pattern)
+            return true;
+        // Path contains pattern
+        if (relativePath.includes(pattern))
+            return true;
+        // Pattern matching for extensions and wildcards
+        if (pattern.includes('*')) {
+            return matchesGlobPattern(relativePath, pattern);
+        }
+        // Special case for test files
+        if (pattern.includes('.test.') && fileName.includes('.test.'))
+            return true;
+        if (pattern.includes('.spec.') && fileName.includes('.spec.'))
+            return true;
+        return false;
+    });
+}
+function matchesGlobPattern(filePath, pattern) {
+    // Convert simple glob patterns to regex
+    // This handles basic cases like *.js, **/*.ts, etc.
+    const regexPattern = pattern
+        .replace(/\*\*/g, '.*') // ** matches any path
+        .replace(/\*/g, '[^/]*') // * matches any filename chars (not path separators)
+        .replace(/\./g, '\\.') // Escape dots
+        .replace(/\//g, '[/\\\\]'); // Handle both forward and back slashes
+    const regex = new RegExp(`^${regexPattern}$`, 'i'); // Case insensitive
+    return regex.test(filePath.replace(/\\/g, '/')); // Normalize path separators
+}
+async function scanFile(filePath, content, opts) {
+    const usages = [];
+    const lines = content.split('\n');
+    const relativePath = path.relative(opts.cwd, filePath);
+    for (const pattern of ENV_PATTERNS) {
+        let match;
+        const regex = new RegExp(pattern.regex.source, pattern.regex.flags);
+        while ((match = regex.exec(content)) !== null) {
+            const variable = match[1];
+            const matchIndex = match.index;
+            // Find line and column
+            const beforeMatch = content.substring(0, matchIndex);
+            const lineNumber = beforeMatch.split('\n').length;
+            const lastNewlineIndex = beforeMatch.lastIndexOf('\n');
+            const column = matchIndex - lastNewlineIndex;
+            // Get the context (the actual line)
+            const contextLine = lines[lineNumber - 1]?.trim() || '';
+            usages.push({
+                variable,
+                file: relativePath,
+                line: lineNumber,
+                column,
+                pattern: pattern.name,
+                context: contextLine,
+            });
+        }
+    }
+    return usages;
+}
+export function compareWithEnvFiles(scanResult, envVariables) {
+    const usedVariables = new Set(scanResult.used.map((u) => u.variable));
+    const envKeys = new Set(Object.keys(envVariables));
+    const missing = [...usedVariables].filter((v) => !envKeys.has(v));
+    const unused = [...envKeys].filter((v) => !usedVariables.has(v));
+    return {
+        ...scanResult,
+        missing,
+        unused,
+    };
+}

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "dotenv-diff",
-  "version": "1.6.5",
+  "version": "2.1.0",
   "type": "module",
-  "description": "A CLI tool to find differences between .env and .env.example / .env.* files.",
+  "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": {
     "dotenv-diff": "dist/bin/dotenv-diff.js"
   },