@danielszlaski/envguard 0.1.0

package/src/commands/scan.ts

@@ -0,0 +1,289 @@
+import * as path from 'path';
+import * as fs from 'fs';
+import chalk from 'chalk';
+import { glob } from 'glob';
+import { CodeScanner } from '../scanner/codeScanner';
+import { EnvParser, EnvEntry } from '../parser/envParser';
+import { ServerlessParser } from '../parser/serverlessParser';
+import { EnvAnalyzer } from '../analyzer/envAnalyzer';
+import { Issue } from '../types';
+import { isKnownRuntimeVar, getRuntimeVarCategory } from '../constants/knownEnvVars';
+import { ConfigLoader } from '../config/configLoader';
+
+export async function scanCommand(options: { ci?: boolean; strict?: boolean }) {
+  const rootDir = process.cwd();
+
+  // Load configuration
+  const config = ConfigLoader.loadConfig(rootDir);
+
+  // CLI options override config file
+  const strictMode = options.strict !== undefined ? options.strict : config.strict;
+
+  console.log(chalk.blue('🔍 Scanning codebase for environment variables...\n'));
+
+  // Step 1: Find all .env files and serverless.yml files
+  const scanner = new CodeScanner(rootDir);
+  const envFiles = await scanner.findEnvFiles();
+  const serverlessFiles = await scanner.findServerlessFiles();
+
+  if (envFiles.length === 0 && serverlessFiles.length === 0) {
+    console.log(chalk.yellow('⚠️  No .env or serverless.yml files found in the project\n'));
+    return { success: false, issues: [] };
+  }
+
+  console.log(chalk.green(`✓ Found ${envFiles.length} .env file(s) and ${serverlessFiles.length} serverless.yml file(s)\n`));
+
+  const parser = new EnvParser();
+  const serverlessParser = new ServerlessParser();
+  const analyzer = new EnvAnalyzer();
+  const allIssues: Issue[] = [];
+
+  // Step 2a: Process serverless.yml files independently
+  for (const serverlessFilePath of serverlessFiles) {
+    const serverlessDir = path.dirname(serverlessFilePath);
+    const relativePath = path.relative(rootDir, serverlessFilePath);
+
+    console.log(chalk.cyan(`📂 Checking ${relativePath}\n`));
+
+    // Parse serverless.yml
+    const serverlessVars = serverlessParser.parse(serverlessFilePath);
+    console.log(chalk.gray(`   Found ${serverlessVars.size} variable(s) in serverless.yml`));
+
+    // Scan code files in this directory to see what's actually used
+    const usedVars = await scanDirectoryForCodeVars(rootDir, serverlessDir, scanner);
+    console.log(chalk.gray(`   Found ${usedVars.size} variable(s) used in code\n`));
+
+    // Check for unused variables in serverless.yml
+    const unusedServerlessVars: string[] = [];
+    for (const [varName] of serverlessVars.entries()) {
+      if (!usedVars.has(varName)) {
+        // In non-strict mode, skip known runtime variables and custom ignore vars from "unused" warnings
+        const isIgnored = isKnownRuntimeVar(varName) || ConfigLoader.shouldIgnoreVar(varName, config);
+        if (strictMode || !isIgnored) {
+          unusedServerlessVars.push(varName);
+        }
+      }
+    }
+
+    // Check for variables used in code but not defined in serverless.yml
+    const missingFromServerless: Array<{ varName: string; locations: string[]; category?: string }> = [];
+    const skippedRuntimeVars: Array<{ varName: string; category: string }> = [];
+
+    for (const [varName, locations] of usedVars.entries()) {
+      if (!serverlessVars.has(varName)) {
+        // In non-strict mode, skip known runtime variables and custom ignore vars
+        const isCustomIgnored = ConfigLoader.shouldIgnoreVar(varName, config);
+        const isRuntimeVar = isKnownRuntimeVar(varName);
+
+        if (!strictMode && (isRuntimeVar || isCustomIgnored)) {
+          const category = isCustomIgnored ? 'Custom (from config)' : getRuntimeVarCategory(varName);
+          if (category) {
+            skippedRuntimeVars.push({ varName, category });
+          }
+        } else {
+          missingFromServerless.push({ varName, locations });
+        }
+      }
+    }
+
+    if (unusedServerlessVars.length > 0) {
+      console.log(chalk.yellow.bold('   ⚠️  Unused variables in serverless.yml:'));
+      unusedServerlessVars.forEach((varName, index) => {
+        console.log(chalk.yellow(`      ${index + 1}. ${varName}`));
+        allIssues.push({
+          type: 'unused',
+          varName,
+          details: `Defined in serverless.yml but never used in code`,
+        });
+      });
+      console.log();
+    }
+
+    if (missingFromServerless.length > 0) {
+      console.log(chalk.red.bold('   🚨 Missing from serverless.yml:'));
+      missingFromServerless.forEach((item, index) => {
+        console.log(chalk.red(`      ${index + 1}. ${item.varName}`));
+        if (item.locations && item.locations.length > 0) {
+          console.log(chalk.gray(`         Used in: ${item.locations.slice(0, 2).join(', ')}`));
+        }
+        allIssues.push({
+          type: 'missing',
+          varName: item.varName,
+          details: `Used in code but not defined in serverless.yml`,
+          locations: item.locations,
+        });
+      });
+      console.log();
+    }
+
+    if (unusedServerlessVars.length === 0 && missingFromServerless.length === 0) {
+      console.log(chalk.green('   ✅ No issues in this serverless.yml\n'));
+    }
+
+    // Show skipped runtime variables in non-strict mode
+    if (!strictMode && skippedRuntimeVars.length > 0) {
+      console.log(chalk.gray('   ℹ️  Skipped known runtime variables (use --strict to show):'));
+      // Group by category
+      const grouped = new Map<string, string[]>();
+      for (const { varName, category } of skippedRuntimeVars) {
+        if (!grouped.has(category)) {
+          grouped.set(category, []);
+        }
+        grouped.get(category)!.push(varName);
+      }
+      for (const [category, vars] of grouped.entries()) {
+        console.log(chalk.gray(`      ${category}: ${vars.join(', ')}`));
+      }
+      console.log();
+    }
+  }
+
+  // Step 2b: Process each .env file (including directories that also have serverless.yml)
+  for (const envFilePath of envFiles) {
+    const envDir = path.dirname(envFilePath);
+    const relativePath = path.relative(rootDir, envDir);
+    const displayPath = relativePath || '.';
+
+    console.log(chalk.cyan(`📂 Checking ${displayPath}/\n`));
+
+    // Step 3: Scan code files in this directory and subdirectories
+    const usedVars = await scanDirectoryForVars(rootDir, envDir, scanner);
+
+    console.log(chalk.gray(`   Found ${usedVars.size} variable(s) used in this scope`));
+
+    // Step 4: Parse .env file
+    const definedVars = parser.parse(envFilePath);
+    console.log(chalk.gray(`   Found ${definedVars.size} variable(s) in .env`));
+
+    // Step 5: Parse .env.example
+    const examplePath = path.join(envDir, '.env.example');
+    const exampleVars = parser.parseExample(examplePath);
+    console.log(chalk.gray(`   Found ${exampleVars.size} variable(s) in .env.example\n`));
+
+    // Step 6: Analyze and find issues
+    const result = analyzer.analyze(usedVars, definedVars, exampleVars);
+
+    if (result.issues.length > 0) {
+      // Group issues by type
+      const missingIssues = result.issues.filter(i => i.type === 'missing');
+      const unusedIssues = result.issues.filter(i => i.type === 'unused');
+      const undocumentedIssues = result.issues.filter(i => i.type === 'undocumented');
+
+      if (missingIssues.length > 0) {
+        console.log(chalk.red.bold('   🚨 Missing from .env:'));
+        missingIssues.forEach((issue, index) => {
+          console.log(chalk.red(`      ${index + 1}. ${issue.varName}`));
+          if (issue.locations && issue.locations.length > 0) {
+            console.log(chalk.gray(`         Used in: ${issue.locations.slice(0, 2).join(', ')}`));
+          }
+        });
+        console.log();
+      }
+
+      if (unusedIssues.length > 0) {
+        console.log(chalk.yellow.bold('   ⚠️  Unused variables:'));
+        unusedIssues.forEach((issue, index) => {
+          console.log(chalk.yellow(`      ${index + 1}. ${issue.varName}`));
+        });
+        console.log();
+      }
+
+      if (undocumentedIssues.length > 0) {
+        console.log(chalk.blue.bold('   📝 Missing from .env.example:'));
+        undocumentedIssues.forEach((issue, index) => {
+          console.log(chalk.blue(`      ${index + 1}. ${issue.varName}`));
+        });
+        console.log();
+      }
+
+      allIssues.push(...result.issues);
+    } else {
+      console.log(chalk.green('   ✅ No issues in this directory\n'));
+    }
+  }
+
+  // Display summary
+  console.log(chalk.bold('─'.repeat(50)));
+  if (allIssues.length === 0) {
+    console.log(chalk.green('\n✅ No issues found! All environment variables are in sync.\n'));
+    return { success: true, issues: [] };
+  }
+
+  console.log(chalk.yellow(`\n⚠️  Total: ${allIssues.length} issue(s) across ${envFiles.length} location(s)\n`));
+
+  // Suggest fix
+  if (!options.ci) {
+    console.log(chalk.cyan('💡 Run `envguard fix` to auto-generate .env.example files\n'));
+  }
+
+  // Exit with error code in CI mode
+  if (options.ci) {
+    console.log(chalk.red('❌ Issues found. Exiting with error code 1.\n'));
+    process.exit(1);
+  }
+
+  return { success: false, issues: allIssues };
+}
+
+async function scanDirectoryForVars(
+  rootDir: string,
+  targetDir: string,
+  scanner: CodeScanner
+): Promise<Map<string, string[]>> {
+  const envVars = new Map<string, string[]>();
+
+  // 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.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;
+}
+
+// Scan only code files (JS/TS), not including serverless.yml as a source
+async function scanDirectoryForCodeVars(
+  rootDir: string,
+  targetDir: string,
+  scanner: CodeScanner
+): Promise<Map<string, string[]>> {
+  const envVars = new Map<string, string[]>();
+
+  // Find all code files in this directory only (not subdirectories for serverless)
+  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.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;
+}

package/src/config/configLoader.ts

@@ -0,0 +1,131 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface EnvGuardConfig {
+  /**
+   * Custom environment variables to ignore in non-strict mode
+   * These will be treated like AWS_REGION, NODE_ENV, etc.
+   */
+  ignoreVars?: string[];
+
+  /**
+   * File patterns to exclude from scanning (in addition to defaults)
+   */
+  exclude?: string[];
+
+  /**
+   * Enable strict mode by default
+   */
+  strict?: boolean;
+}
+
+const DEFAULT_CONFIG: EnvGuardConfig = {
+  ignoreVars: [],
+  exclude: [],
+  strict: false,
+};
+
+const CONFIG_FILE_NAMES = [
+  '.envguardrc.json',
+  '.envguardrc',
+  'envguard.config.json',
+];
+
+/**
+ * Load EnvGuard configuration from various sources
+ * Priority: CLI args > .envguardrc.json > package.json > defaults
+ */
+export class ConfigLoader {
+  /**
+   * Load config from the project root directory
+   */
+  static loadConfig(rootDir: string): EnvGuardConfig {
+    // Try to find config file
+    const configPath = this.findConfigFile(rootDir);
+
+    if (configPath) {
+      try {
+        const fileContent = fs.readFileSync(configPath, 'utf-8');
+        const userConfig = JSON.parse(fileContent) as EnvGuardConfig;
+
+        return {
+          ...DEFAULT_CONFIG,
+          ...userConfig,
+          ignoreVars: [
+            ...(DEFAULT_CONFIG.ignoreVars || []),
+            ...(userConfig.ignoreVars || []),
+          ],
+          exclude: [
+            ...(DEFAULT_CONFIG.exclude || []),
+            ...(userConfig.exclude || []),
+          ],
+        };
+      } catch (error) {
+        console.warn(`Warning: Failed to parse config file ${configPath}:`, error);
+        return DEFAULT_CONFIG;
+      }
+    }
+
+    // Try to load from package.json
+    const packageJsonPath = path.join(rootDir, 'package.json');
+    if (fs.existsSync(packageJsonPath)) {
+      try {
+        const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf-8'));
+        if (packageJson.envguard) {
+          const userConfig = packageJson.envguard as EnvGuardConfig;
+          return {
+            ...DEFAULT_CONFIG,
+            ...userConfig,
+            ignoreVars: [
+              ...(DEFAULT_CONFIG.ignoreVars || []),
+              ...(userConfig.ignoreVars || []),
+            ],
+            exclude: [
+              ...(DEFAULT_CONFIG.exclude || []),
+              ...(userConfig.exclude || []),
+            ],
+          };
+        }
+      } catch (error) {
+        // Silently fail if package.json doesn't have envguard config
+      }
+    }
+
+    return DEFAULT_CONFIG;
+  }
+
+  /**
+   * Find the config file by searching up the directory tree
+   * This allows placing config at repo root and using it in subdirectories
+   */
+  private static findConfigFile(startDir: string): string | null {
+    let currentDir = startDir;
+    const root = path.parse(currentDir).root;
+
+    // Search up the directory tree until we hit the filesystem root
+    while (currentDir !== root) {
+      for (const fileName of CONFIG_FILE_NAMES) {
+        const configPath = path.join(currentDir, fileName);
+        if (fs.existsSync(configPath)) {
+          return configPath;
+        }
+      }
+
+      // Move up one directory
+      const parentDir = path.dirname(currentDir);
+      if (parentDir === currentDir) {
+        break; // Reached the root
+      }
+      currentDir = parentDir;
+    }
+
+    return null;
+  }
+
+  /**
+   * Check if a variable should be ignored based on config
+   */
+  static shouldIgnoreVar(varName: string, config: EnvGuardConfig): boolean {
+    return config.ignoreVars?.includes(varName) || false;
+  }
+}

package/src/constants/knownEnvVars.ts

@@ -0,0 +1,108 @@
+/**
+ * Well-known environment variables that are provided by runtimes and don't need
+ * to be explicitly defined in .env or serverless.yml
+ */
+
+/**
+ * AWS Lambda automatically provides these environment variables
+ * https://docs.aws.amazon.com/lambda/latest/dg/configuration-envvars.html
+ */
+export const AWS_PROVIDED_VARS = new Set([
+  'AWS_REGION',
+  'AWS_DEFAULT_REGION',
+  'AWS_EXECUTION_ENV',
+  'AWS_LAMBDA_FUNCTION_NAME',
+  'AWS_LAMBDA_FUNCTION_VERSION',
+  'AWS_LAMBDA_FUNCTION_MEMORY_SIZE',
+  'AWS_LAMBDA_LOG_GROUP_NAME',
+  'AWS_LAMBDA_LOG_STREAM_NAME',
+  'AWS_ACCESS_KEY_ID',
+  'AWS_SECRET_ACCESS_KEY',
+  'AWS_SESSION_TOKEN',
+  'AWS_LAMBDA_RUNTIME_API',
+  '_HANDLER',
+  '_X_AMZN_TRACE_ID',
+  'LAMBDA_TASK_ROOT',
+  'LAMBDA_RUNTIME_DIR',
+  'TZ', // Timezone
+]);
+
+/**
+ * Common Node.js and development environment variables
+ */
+export const NODEJS_RUNTIME_VARS = new Set([
+  'NODE_ENV',
+  'NODE_OPTIONS',
+  'PATH',
+  'HOME',
+  'USER',
+  'LANG',
+  'LC_ALL',
+  'PWD',
+  'OLDPWD',
+  'SHELL',
+  'TERM',
+]);
+
+/**
+ * CI/CD and testing environment variables
+ */
+export const CI_CD_VARS = new Set([
+  'CI',
+  'CONTINUOUS_INTEGRATION',
+  'GITHUB_ACTIONS',
+  'GITLAB_CI',
+  'CIRCLECI',
+  'TRAVIS',
+  'JENKINS_URL',
+  'BUILDKITE',
+]);
+
+/**
+ * Serverless Framework and local development
+ */
+export const SERVERLESS_FRAMEWORK_VARS = new Set([
+  'IS_OFFLINE',
+  'SLS_OFFLINE',
+  'SERVERLESS_STAGE',
+  'SERVERLESS_REGION',
+]);
+
+/**
+ * Testing framework variables
+ */
+export const TEST_VARS = new Set([
+  'JEST_WORKER_ID',
+  'VITEST_WORKER_ID',
+  'MOCHA_COLORS',
+]);
+
+/**
+ * Combine all known runtime variables that don't need to be explicitly defined
+ */
+export const KNOWN_RUNTIME_VARS = new Set([
+  ...AWS_PROVIDED_VARS,
+  ...NODEJS_RUNTIME_VARS,
+  ...CI_CD_VARS,
+  ...SERVERLESS_FRAMEWORK_VARS,
+  ...TEST_VARS,
+]);
+
+/**
+ * Check if a variable is a known runtime variable
+ */
+export function isKnownRuntimeVar(varName: string): boolean {
+  return KNOWN_RUNTIME_VARS.has(varName);
+}
+
+/**
+ * Get a human-readable category for a known runtime variable
+ */
+export function getRuntimeVarCategory(varName: string): string | null {
+  if (AWS_PROVIDED_VARS.has(varName)) return 'AWS Lambda';
+  if (NODEJS_RUNTIME_VARS.has(varName)) return 'Node.js Runtime';
+  if (CI_CD_VARS.has(varName)) return 'CI/CD';
+  if (SERVERLESS_FRAMEWORK_VARS.has(varName)) return 'Serverless Framework';
+  if (TEST_VARS.has(varName)) return 'Testing';
+  return null;
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { CodeScanner } from './scanner/codeScanner';
+export { EnvParser } from './parser/envParser';
+export { EnvAnalyzer } from './analyzer/envAnalyzer';
+export * from './types';

package/src/parser/envParser.ts

@@ -0,0 +1,114 @@
+import * as fs from 'fs';
+import * as path from 'path';
+
+export interface EnvEntry {
+  key: string;
+  value: string;
+  comment?: string;
+  lineNumber: number;
+}
+
+export class EnvParser {
+  parse(filePath: string): Map<string, EnvEntry> {
+    const envVars = new Map<string, EnvEntry>();
+
+    if (!fs.existsSync(filePath)) {
+      return envVars;
+    }
+
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const lines = content.split('\n');
+      let currentComment = '';
+
+      lines.forEach((line, index) => {
+        const trimmed = line.trim();
+
+        // Skip empty lines
+        if (!trimmed) {
+          currentComment = '';
+          return;
+        }
+
+        // Capture comments
+        if (trimmed.startsWith('#')) {
+          currentComment = trimmed.substring(1).trim();
+          return;
+        }
+
+        // Parse key=value
+        const match = trimmed.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+        if (match) {
+          const key = match[1];
+          let value = match[2];
+
+          // Remove quotes if present
+          if ((value.startsWith('"') && value.endsWith('"')) ||
+              (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+          }
+
+          envVars.set(key, {
+            key,
+            value,
+            comment: this.isUserComment(currentComment) ? currentComment : undefined,
+            lineNumber: index + 1,
+          });
+
+          currentComment = '';
+        }
+      });
+    } catch (error) {
+      console.error(`Error parsing ${filePath}:`, error);
+    }
+
+    return envVars;
+  }
+
+  private isUserComment(comment: string): boolean {
+    if (!comment) return false;
+
+    // Filter out auto-generated comments to prevent duplicates when running fix multiple times
+    const autoGeneratedPrefixes = ['Used in:', 'Format:', 'Auto-generated by'];
+    return !autoGeneratedPrefixes.some(prefix => comment.startsWith(prefix));
+  }
+
+  parseExample(filePath: string): Set<string> {
+    const envVars = new Set<string>();
+
+    if (!fs.existsSync(filePath)) {
+      return envVars;
+    }
+
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const lines = content.split('\n');
+
+      lines.forEach(line => {
+        const trimmed = line.trim();
+
+        // Skip comments and empty lines
+        if (!trimmed || trimmed.startsWith('#')) {
+          return;
+        }
+
+        // Parse key=value
+        const match = trimmed.match(/^([A-Z_][A-Z0-9_]*)=/);
+        if (match) {
+          envVars.add(match[1]);
+        }
+      });
+    } catch (error) {
+      console.error(`Error parsing ${filePath}:`, error);
+    }
+
+    return envVars;
+  }
+
+  getExistingContent(filePath: string): string {
+    if (!fs.existsSync(filePath)) {
+      return '';
+    }
+    return fs.readFileSync(filePath, 'utf-8');
+  }
+}