@danielszlaski/envguard 0.1.0

package/dist/scanner/codeScanner.js

@@ -0,0 +1,157 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CodeScanner = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const glob_1 = require("glob");
+const serverlessParser_1 = require("../parser/serverlessParser");
+class CodeScanner {
+    constructor(rootDir, excludePatterns = ['node_modules', 'dist', 'build', '.git']) {
+        this.rootDir = rootDir;
+        this.excludePatterns = excludePatterns;
+        this.serverlessParser = new serverlessParser_1.ServerlessParser();
+    }
+    async scan() {
+        const envVars = new Map();
+        // Scan for JavaScript/TypeScript files
+        const files = await (0, glob_1.glob)('**/*.{js,ts,jsx,tsx,mjs,cjs}', {
+            cwd: this.rootDir,
+            ignore: this.excludePatterns.map(p => `**/${p}/**`),
+            absolute: true,
+        });
+        for (const file of files) {
+            const vars = await this.scanFile(file);
+            for (const varName of vars) {
+                const relativePath = path.relative(this.rootDir, file);
+                if (!envVars.has(varName)) {
+                    envVars.set(varName, []);
+                }
+                envVars.get(varName).push(relativePath);
+            }
+        }
+        // Also scan serverless.yml files for environment variable definitions
+        const serverlessFiles = await this.findServerlessFiles();
+        for (const file of serverlessFiles) {
+            const vars = this.scanServerlessFile(file);
+            for (const [varName, entry] of vars.entries()) {
+                const relativePath = path.relative(this.rootDir, file);
+                if (!envVars.has(varName)) {
+                    envVars.set(varName, []);
+                }
+                envVars.get(varName).push(`${relativePath} (serverless config)`);
+            }
+        }
+        return envVars;
+    }
+    async scanFile(filePath) {
+        const envVars = new Set();
+        try {
+            const content = fs.readFileSync(filePath, 'utf-8');
+            // Pattern 1: process.env.VAR_NAME
+            const processEnvPattern = /process\.env\.([A-Z_][A-Z0-9_]*)/g;
+            let match;
+            while ((match = processEnvPattern.exec(content)) !== null) {
+                envVars.add(match[1]);
+            }
+            // Pattern 2: process.env['VAR_NAME'] or process.env["VAR_NAME"]
+            const processEnvBracketPattern = /process\.env\[['"]([A-Z_][A-Z0-9_]*)['"\]]/g;
+            while ((match = processEnvBracketPattern.exec(content)) !== null) {
+                envVars.add(match[1]);
+            }
+            // Pattern 3: Destructuring - const { VAR_NAME } = process.env
+            const destructuringPattern = /const\s+\{\s*([^}]+)\s*\}\s*=\s*process\.env/g;
+            while ((match = destructuringPattern.exec(content)) !== null) {
+                const vars = match[1].split(',').map(v => v.trim().split(':')[0].trim());
+                vars.forEach(v => {
+                    if (/^[A-Z_][A-Z0-9_]*$/.test(v)) {
+                        envVars.add(v);
+                    }
+                });
+            }
+        }
+        catch (error) {
+            console.error(`Error scanning file ${filePath}:`, error);
+        }
+        return envVars;
+    }
+    async findEnvFiles() {
+        const envFiles = await (0, glob_1.glob)('**/.env', {
+            cwd: this.rootDir,
+            ignore: this.excludePatterns.map(p => `**/${p}/**`),
+            absolute: true,
+        });
+        return envFiles;
+    }
+    async findServerlessFiles() {
+        const serverlessFiles = await (0, glob_1.glob)('**/serverless.{yml,yaml}', {
+            cwd: this.rootDir,
+            ignore: this.excludePatterns.map(p => `**/${p}/**`),
+            absolute: true,
+        });
+        return serverlessFiles;
+    }
+    scanServerlessFile(filePath) {
+        return this.serverlessParser.parse(filePath);
+    }
+    async scanByDirectory() {
+        // Returns a map of directory -> (varName -> file locations)
+        const dirMap = new Map();
+        // Scan for JavaScript/TypeScript files
+        const files = await (0, glob_1.glob)('**/*.{js,ts,jsx,tsx,mjs,cjs}', {
+            cwd: this.rootDir,
+            ignore: this.excludePatterns.map(p => `**/${p}/**`),
+            absolute: true,
+        });
+        for (const file of files) {
+            const vars = await this.scanFile(file);
+            const fileDir = path.dirname(file);
+            const relativePath = path.relative(this.rootDir, file);
+            for (const varName of vars) {
+                if (!dirMap.has(fileDir)) {
+                    dirMap.set(fileDir, new Map());
+                }
+                const varMap = dirMap.get(fileDir);
+                if (!varMap.has(varName)) {
+                    varMap.set(varName, []);
+                }
+                varMap.get(varName).push(relativePath);
+            }
+        }
+        return dirMap;
+    }
+}
+exports.CodeScanner = CodeScanner;
+//# sourceMappingURL=codeScanner.js.map

package/dist/scanner/codeScanner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codeScanner.js","sourceRoot":"","sources":["../../src/scanner/codeScanner.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,24 @@
+export interface EnvUsage {
+    varName: string;
+    locations: string[];
+}
+export interface EnvDefinition {
+    varName: string;
+    value?: string;
+    comment?: string;
+    source?: 'dotenv' | 'serverless' | 'both';
+    isReference?: boolean;
+}
+export interface Issue {
+    type: 'missing' | 'unused' | 'undocumented';
+    varName: string;
+    details: string;
+    locations?: string[];
+}
+export interface ScanResult {
+    issues: Issue[];
+    usedVars: Map<string, string[]>;
+    definedVars: Set<string>;
+    exampleVars: Set<string>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,QAAQ,GAAG,YAAY,GAAG,MAAM,CAAC;IAC1C,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,KAAK;IACpB,IAAI,EAAE,SAAS,GAAG,QAAQ,GAAG,cAAc,CAAC;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,EAAE,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,MAAM,EAAE,KAAK,EAAE,CAAC;IAChB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAChC,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IACzB,WAAW,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CAC1B"}

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@danielszlaski/envguard",
+  "version": "0.1.0",
+  "description": "CLI tool to keep environment variables in sync with your codebase",
+  "main": "dist/index.js",
+  "bin": {
+    "envguard": "./dist/cli.js"
+  },     
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/szlaskidaniel/envguard"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "start": "node dist/cli.js",
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "environment",
+    "env",
+    "dotenv",
+    "config",
+    "security"
+  ],
+  "author": "Daniel Szlaski",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^11.1.0",
+    "dotenv": "^16.3.1",
+    "glob": "^10.3.10",
+    "js-yaml": "^4.1.1"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.10.6",
+    "typescript": "^5.3.3"
+  }
+}

package/src/analyzer/envAnalyzer.ts

@@ -0,0 +1,133 @@
+import { Issue, ScanResult } from '../types';
+import { EnvEntry } from '../parser/envParser';
+
+export class EnvAnalyzer {
+  analyze(
+    usedVars: Map<string, string[]>,
+    definedVars: Map<string, EnvEntry>,
+    exampleVars: Set<string>
+  ): ScanResult {
+    const issues: Issue[] = [];
+
+    // Issue 1: Variables used in code but missing from .env
+    for (const [varName, locations] of usedVars.entries()) {
+      if (!definedVars.has(varName)) {
+        issues.push({
+          type: 'missing',
+          varName,
+          details: `Used in code but not defined in .env`,
+          locations,
+        });
+      }
+    }
+
+    // Issue 2: Variables defined in .env but never used
+    for (const [varName] of definedVars.entries()) {
+      if (!usedVars.has(varName)) {
+        issues.push({
+          type: 'unused',
+          varName,
+          details: `Defined in .env but never used in code`,
+        });
+      }
+    }
+
+    // Issue 3: Variables used in code but not in .env.example
+    for (const [varName, locations] of usedVars.entries()) {
+      if (!exampleVars.has(varName)) {
+        issues.push({
+          type: 'undocumented',
+          varName,
+          details: `Used in code but missing from .env.example`,
+          locations,
+        });
+      }
+    }
+
+    return {
+      issues,
+      usedVars,
+      definedVars: new Set(definedVars.keys()),
+      exampleVars,
+    };
+  }
+
+  generateExampleContent(
+    usedVars: Map<string, string[]>,
+    existingEntries: Map<string, EnvEntry>
+  ): string {
+    let content = '# Auto-generated by envguard\n';
+    content += '# Do not put actual secrets in this file - use .env instead\n\n';
+
+    const sortedVars = Array.from(usedVars.keys()).sort();
+
+    for (const varName of sortedVars) {
+      const locations = usedVars.get(varName)!;
+      const existingEntry = existingEntries.get(varName);
+
+      // Add location comments
+      content += `# Used in: ${locations.slice(0, 3).join(', ')}`;
+      if (locations.length > 3) {
+        content += ` (+${locations.length - 3} more)`;
+      }
+      content += '\n';
+
+      // Add existing comment if available
+      if (existingEntry?.comment) {
+        content += `# ${existingEntry.comment}\n`;
+      } else {
+        // Add a format hint based on common patterns
+        const hint = this.getFormatHint(varName);
+        if (hint) {
+          content += `# Format: ${hint}\n`;
+        }
+      }
+
+      // Add the variable with empty value or existing value
+      if (existingEntry) {
+        content += `${varName}=${existingEntry.value}\n`;
+      } else {
+        content += `${varName}=\n`;
+      }
+
+      content += '\n';
+    }
+
+    return content;
+  }
+
+  private getFormatHint(varName: string): string | null {
+    const patterns: { [key: string]: string } = {
+      'DATABASE_URL': 'postgresql://user:pass@host:5432/db',
+      'MONGODB_URI': 'mongodb://localhost:27017/dbname',
+      'REDIS_URL': 'redis://localhost:6379',
+      'PORT': '3000',
+      'NODE_ENV': 'development|production|test',
+      'API_KEY': 'your-api-key-here',
+      'SECRET': 'your-secret-here',
+      'JWT_SECRET': 'your-jwt-secret',
+      'STRIPE_': 'sk_test_...',
+      'AWS_': 'aws-credentials',
+    };
+
+    for (const [pattern, hint] of Object.entries(patterns)) {
+      if (varName.includes(pattern)) {
+        return hint;
+      }
+    }
+
+    if (varName.endsWith('_URL') || varName.endsWith('_URI')) {
+      return 'https://example.com';
+    }
+
+    if (varName.endsWith('_PORT')) {
+      return '8080';
+    }
+
+    if (varName.endsWith('_KEY') || varName.endsWith('_SECRET') || varName.endsWith('_TOKEN')) {
+      return 'your-secret-here';
+    }
+
+    return null;
+  }
+}

package/src/cli.ts

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+
+import { Command } from 'commander';
+import { scanCommand } from './commands/scan';
+import { fixCommand } from './commands/fix';
+import { checkCommand } from './commands/check';
+
+const program = new Command();
+
+program
+  .name('envguard')
+  .description('Keep your environment variables in sync with your codebase')
+  .version('0.1.0');
+
+program
+  .command('scan')
+  .description('Scan codebase and compare with .env files')
+  .option('--ci', 'Exit with error code if issues found (for CI/CD)')
+  .option('--strict', 'Report all variables including known runtime variables (AWS_REGION, NODE_ENV, etc.)')
+  .action(async (options) => {
+    try {
+      await scanCommand(options);
+    } catch (error) {
+      console.error('Error:', error);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('fix')
+  .description('Auto-generate .env.example from codebase')
+  .action(async () => {
+    try {
+      await fixCommand();
+    } catch (error) {
+      console.error('Error:', error);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('check')
+  .description('Check for issues (alias for scan --ci)')
+  .option('--strict', 'Report all variables including known runtime variables (AWS_REGION, NODE_ENV, etc.)')
+  .action(async (options) => {
+    try {
+      await scanCommand({ ci: true, strict: options.strict });
+    } catch (error) {
+      console.error('Error:', error);
+      process.exit(1);
+    }
+  });
+
+program.parse();

package/src/commands/check.ts

@@ -0,0 +1,6 @@
+import { scanCommand } from './scan';
+
+export async function checkCommand() {
+  // Check command is the same as scan but with --ci flag
+  return scanCommand({ ci: true });
+}

package/src/commands/fix.ts

@@ -0,0 +1,104 @@
+import * as path from 'path';
+import * as fs from 'fs';
+import chalk from 'chalk';
+import { CodeScanner } from '../scanner/codeScanner';
+import { EnvParser } from '../parser/envParser';
+import { EnvAnalyzer } from '../analyzer/envAnalyzer';
+
+export async function fixCommand() {
+  const rootDir = process.cwd();
+
+  console.log(chalk.blue('🔧 Generating .env.example files...\n'));
+
+  // Step 1: Find all .env files
+  const scanner = new CodeScanner(rootDir);
+  const envFiles = await scanner.findEnvFiles();
+
+  if (envFiles.length === 0) {
+    console.log(chalk.yellow('⚠️  No .env files found in the project\n'));
+    return { success: false };
+  }
+
+  console.log(chalk.green(`✓ Found ${envFiles.length} .env file(s)\n`));
+
+  const parser = new EnvParser();
+  const analyzer = new EnvAnalyzer();
+  let totalVars = 0;
+
+  // Step 2: Process each .env file
+  for (const envFilePath of envFiles) {
+    const envDir = path.dirname(envFilePath);
+    const relativePath = path.relative(rootDir, envDir);
+    const displayPath = relativePath || '.';
+
+    console.log(chalk.cyan(`📂 Processing ${displayPath}/`));
+
+    // Step 3: Scan code files in this directory and subdirectories
+    const usedVars = await scanDirectoryForVars(rootDir, envDir, scanner);
+
+    if (usedVars.size === 0) {
+      console.log(chalk.gray(`   No environment variables found in code\n`));
+      continue;
+    }
+
+    console.log(chalk.green(`   ✓ Found ${usedVars.size} variable(s) used in this directory\n`));
+
+    // Step 4: Parse existing .env.example to preserve comments
+    const examplePath = path.join(envDir, '.env.example');
+    const existingEntries = parser.parse(examplePath);
+
+    // Step 5: Generate new .env.example content
+    const newContent = analyzer.generateExampleContent(usedVars, existingEntries);
+
+    // Step 6: Write to .env.example
+    fs.writeFileSync(examplePath, newContent, 'utf-8');
+
+    console.log(chalk.green(`   ✅ Generated ${path.relative(rootDir, examplePath)}\n`));
+
+    totalVars += usedVars.size;
+
+    // Step 7: Show summary for this directory
+    const definedVars = parser.parse(envFilePath);
+    const missingFromEnv = Array.from(usedVars.keys()).filter(v => !definedVars.has(v));
+
+    if (missingFromEnv.length > 0) {
+      console.log(chalk.yellow(`   ⚠️  Missing from .env: ${missingFromEnv.join(', ')}\n`));
+    }
+  }
+
+  console.log(chalk.green(`🎉 Done! Generated ${envFiles.length} .env.example file(s) with ${totalVars} total variables\n`));
+
+  return { success: true };
+}
+
+async function scanDirectoryForVars(
+  rootDir: string,
+  targetDir: string,
+  scanner: CodeScanner
+): Promise<Map<string, string[]>> {
+  const envVars = new Map<string, string[]>();
+  const { glob } = require('glob');
+
+  // Find all code files in this directory and subdirectories
+  const relativeDir = path.relative(rootDir, targetDir);
+  const pattern = relativeDir ? `${relativeDir}/**/*.{js,ts,jsx,tsx,mjs,cjs}` : '**/*.{js,ts,jsx,tsx,mjs,cjs}';
+
+  const files = await glob(pattern, {
+    cwd: rootDir,
+    ignore: ['**/node_modules/**', '**/dist/**', '**/build/**', '**/.git/**'],
+    absolute: true,
+  });
+
+  for (const file of files) {
+    const vars = await (scanner as any).scanFile(file);
+    for (const varName of vars) {
+      const relativePath = path.relative(rootDir, file);
+      if (!envVars.has(varName)) {
+        envVars.set(varName, []);
+      }
+      envVars.get(varName)!.push(relativePath);
+    }
+  }
+
+  return envVars;
+}