dotenv-diff 1.6.4 → 2.0.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,38 @@ 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).
+
+## 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
@@ -43,6 +79,15 @@ 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:

package/dist/src/cli/program.js

@@ -11,5 +11,11 @@ export function createProgram() {
         .option('--allow-duplicates', 'Do not warn about duplicate keys in .env* files')
         .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('--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('--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,26 @@ 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,
+            envPath,
+            json: opts.json,
+            showUnused: opts.showUnused,
+            showStats: opts.showStats,
+        });
+        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);
@@ -37,6 +53,8 @@ export async function run(program) {
             json: opts.json,
             ignore: opts.ignore,
             ignoreRegex: opts.ignoreRegex,
+            only: opts.only,
+            showStats: opts.showStats,
             collect: (e) => report.push(e),
         });
         if (opts.json) {
@@ -75,6 +93,8 @@ export async function run(program) {
         json: opts.json,
         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

@@ -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;
@@ -36,6 +11,8 @@ export declare function compareMany(pairs: Array<{
     ignore: string[];
     ignoreRegex: RegExp[];
     collect?: (entry: CompareJsonEntry) => void;
+    only?: Category[];
+    showStats?: boolean;
 }): Promise<{
     exitWithError: boolean;
 }>;

package/dist/src/commands/compare.js

@@ -8,6 +8,18 @@ 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 };
@@ -25,36 +37,45 @@ 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).filter(({ key }) => !opts.ignore.includes(key) &&
+        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)));
-            const dupsEx = findDuplicateKeys(examplePath).filter(({ key }) => !opts.ignore.includes(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
@@ -68,10 +89,19 @@ export async function compareMany(pairs, opts) {
         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) {
@@ -81,33 +111,72 @@ export async function compareMany(pairs, opts) {
             opts.collect?.(entry);
             continue;
         }
-        if (diff.missing.length) {
-            entry.missing = diff.missing;
+        // --- 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;
+            totals.missing += filtered.missing.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.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 (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/commands/scanUsage.d.ts

@@ -0,0 +1,43 @@
+import { type ScanOptions } from '../services/codeBaseScanner.js';
+export interface ScanUsageOptions extends ScanOptions {
+    envPath?: string;
+    json: boolean;
+    showUnused: boolean;
+    showStats: 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;
+    }>;
+}
+/**
+ * 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 {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
+ * @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,154 @@
+import chalk from 'chalk';
+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 {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
+ * @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);
+    // If we have an env file, compare with it
+    let envVariables = {};
+    if (opts.envPath) {
+        try {
+            const envFull = parseEnvFile(opts.envPath);
+            const envKeys = filterIgnoredKeys(Object.keys(envFull), opts.ignore, opts.ignoreRegex);
+            envVariables = Object.fromEntries(envKeys.map((k) => [k, envFull[k]]));
+            scanResult = compareWithEnvFiles(scanResult, envVariables);
+        }
+        catch (error) {
+            if (!opts.json) {
+                console.log(chalk.yellow(`⚠️  Could not read env file: ${opts.envPath} - ${error}`));
+            }
+        }
+    }
+    // Prepare JSON output
+    if (opts.json) {
+        const jsonOutput = createJsonOutput(scanResult, opts);
+        console.log(JSON.stringify(jsonOutput, null, 2));
+        return { exitWithError: scanResult.missing.length > 0 };
+    }
+    // Console output
+    return outputToConsole(scanResult, opts);
+}
+function createJsonOutput(scanResult, opts) {
+    // 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,
+    };
+    // 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) {
+    let exitWithError = false;
+    // 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 in .env comparison mode
+    if (!opts.envPath || 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)
+    if (scanResult.missing.length > 0) {
+        exitWithError = true;
+        console.log(chalk.red('❌ Missing in .env:'));
+        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();
+    }
+    // Unused variables (in .env but not used in code)
+    if (opts.showUnused && scanResult.unused.length > 0) {
+        console.log(chalk.yellow('⚠️  Unused in codebase:'));
+        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'));
+        if (opts.showUnused && scanResult.unused.length === 0) {
+            console.log(chalk.green('✅ No unused environment variables found'));
+        }
+    }
+    return { exitWithError };
+}

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

@@ -1,25 +1,2 @@
-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;
-};
-type RawOptions = {
-    checkValues?: boolean;
-    ci?: boolean;
-    yes?: boolean;
-    allowDuplicates?: boolean;
-    json?: boolean;
-    env?: string;
-    example?: string;
-    ignore?: string | string[];
-    ignoreRegex?: string | string[];
-};
+import { Options, RawOptions } from './types.js';
 export declare function normalizeOptions(raw: RawOptions): Options;
-export {};

package/dist/src/config/options.js

@@ -1,18 +1,35 @@
 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 parseList = (val) => {
-        const arr = Array.isArray(val) ? val : val ? [val] : [];
-        return arr
-            .flatMap((s) => s.split(','))
-            .map((s) => s.trim())
-            .filter(Boolean);
-    };
+    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)) {
@@ -41,5 +58,11 @@ export function normalizeOptions(raw) {
         ignore,
         ignoreRegex,
         cwd,
+        only,
+        scanUsage,
+        includeFiles,
+        excludeFiles,
+        showUnused,
+        showStats,
     };
 }

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

@@ -0,0 +1,63 @@
+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[];
+    scanUsage: boolean;
+    includeFiles: string[];
+    excludeFiles: string[];
+    showUnused: boolean;
+    showStats: boolean;
+};
+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[];
+    scanUsage?: boolean;
+    includeFiles?: string | string[];
+    excludeFiles?: string | string[];
+    showUnused?: boolean;
+    showStats?: boolean;
+};
+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/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.4",
+  "version": "2.0.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"
   },