@danielszlaski/envguard 0.1.3 → 0.1.5

package/src/commands/install-hook.ts

@@ -0,0 +1,128 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { Logger } from '../utils/logger';
+
+const HOOK_TYPES = ['pre-commit', 'pre-push'] as const;
+type HookType = typeof HOOK_TYPES[number];
+
+interface InstallHookOptions {
+  type?: HookType;
+  force?: boolean;
+}
+
+/**
+ * Install a Git hook that runs envguard before commits or pushes
+ */
+export async function installHookCommand(options: InstallHookOptions = {}) {
+  const rootDir = process.cwd();
+  const gitDir = path.join(rootDir, '.git');
+  const hooksDir = path.join(gitDir, 'hooks');
+
+  // Check if this is a git repository
+  if (!fs.existsSync(gitDir)) {
+    Logger.error('Not a git repository. Please run this command in a git repository.');
+    Logger.blank();
+    process.exit(1);
+  }
+
+  // Ensure hooks directory exists
+  if (!fs.existsSync(hooksDir)) {
+    fs.mkdirSync(hooksDir, { recursive: true });
+    Logger.success('Created .git/hooks directory');
+  }
+
+  const hookType = options.type || 'pre-commit';
+  const hookPath = path.join(hooksDir, hookType);
+
+  // Check if hook already exists
+  if (fs.existsSync(hookPath) && !options.force) {
+    Logger.warning(`${hookType} hook already exists.`);
+    Logger.info('Use --force to overwrite the existing hook', true);
+    Logger.blank();
+    process.exit(1);
+  }
+
+  // Create the hook script
+  const hookContent = generateHookScript(hookType);
+
+  try {
+    fs.writeFileSync(hookPath, hookContent, { mode: 0o755 });
+    Logger.success(`Installed ${hookType} hook successfully!`);
+    Logger.blank();
+    Logger.info('The hook will run `envguard check` automatically before each ' +
+                (hookType === 'pre-commit' ? 'commit' : 'push'), true);
+    Logger.info('To bypass the hook, use: git ' +
+                (hookType === 'pre-commit' ? 'commit' : 'push') + ' --no-verify', true);
+    Logger.blank();
+  } catch (error) {
+    Logger.error(`Failed to install hook: ${error}`);
+    Logger.blank();
+    process.exit(1);
+  }
+}
+
+/**
+ * Uninstall a Git hook
+ */
+export async function uninstallHookCommand(options: { type?: HookType } = {}) {
+  const rootDir = process.cwd();
+  const hookType = options.type || 'pre-commit';
+  const hookPath = path.join(rootDir, '.git', 'hooks', hookType);
+
+  if (!fs.existsSync(hookPath)) {
+    Logger.warning(`No ${hookType} hook found.`);
+    Logger.blank();
+    return;
+  }
+
+  // Check if it's our hook
+  const hookContent = fs.readFileSync(hookPath, 'utf-8');
+  if (!hookContent.includes('envguard check')) {
+    Logger.warning(`The ${hookType} hook exists but was not created by envguard.`);
+    Logger.info('Manual removal required if you want to delete it.', true);
+    Logger.blank();
+    return;
+  }
+
+  try {
+    fs.unlinkSync(hookPath);
+    Logger.success(`Removed ${hookType} hook successfully!`);
+    Logger.blank();
+  } catch (error) {
+    Logger.error(`Failed to remove hook: ${error}`);
+    Logger.blank();
+    process.exit(1);
+  }
+}
+
+/**
+ * Generate the hook script content
+ */
+function generateHookScript(hookType: HookType): string {
+  const hookMessage = hookType === 'pre-commit' ? 'commit' : 'push';
+
+  return `#!/bin/sh
+# EnvGuard ${hookType} hook
+# This hook runs envguard to check environment variables before ${hookMessage}
+# To bypass this hook, use: git ${hookMessage} --no-verify
+
+echo "Running EnvGuard environment variable check..."
+
+# Run envguard check
+npx envguard check
+
+# Capture the exit code
+EXIT_CODE=$?
+
+if [ $EXIT_CODE -ne 0 ]; then
+  echo ""
+  echo "❌ EnvGuard check failed. Please fix the issues above before ${hookMessage}ing."
+  echo "   Or run: git ${hookMessage} --no-verify to bypass this check."
+  echo ""
+  exit 1
+fi
+
+echo "✓ EnvGuard check passed!"
+exit 0
+`;
+}

package/src/commands/scan.ts

@@ -10,7 +10,7 @@ import { isKnownRuntimeVar, getRuntimeVarCategory } from '../constants/knownEnvV
 import { ConfigLoader } from '../config/configLoader';
 import { Logger } from '../utils/logger';
 
-export async function scanCommand(options: { ci?: boolean; strict?: boolean }) {
+export async function scanCommand(options: { ci?: boolean; strict?: boolean; detectFallbacks?: boolean }) {
   const rootDir = process.cwd();
 
   // Load configuration
@@ -18,11 +18,19 @@ export async function scanCommand(options: { ci?: boolean; strict?: boolean }) {
 
   // CLI options override config file
   const strictMode = options.strict !== undefined ? options.strict : config.strict;
+  const detectFallbacks = options.detectFallbacks !== undefined ? options.detectFallbacks : (config.detectFallbacks !== undefined ? config.detectFallbacks : true);
 
   Logger.startSpinner('Scanning codebase for environment variables...');
 
   // Step 1: Find all .env files and serverless.yml files
-  const scanner = new CodeScanner(rootDir);
+  const excludePatterns = [
+    'node_modules',
+    'dist',
+    'build',
+    '.git',
+    ...(config.exclude || []),
+  ];
+  const scanner = new CodeScanner(rootDir, excludePatterns);
   const envFiles = await scanner.findEnvFiles();
   const serverlessFiles = await scanner.findServerlessFiles();
 
@@ -55,7 +63,7 @@ export async function scanCommand(options: { ci?: boolean; strict?: boolean }) {
     Logger.info(`Found ${serverlessVars.size} variable(s) in serverless.yml`, true);
 
     // Scan code files in this directory to see what's actually used
-    const usedVars = await scanDirectoryForCodeVars(rootDir, serverlessDir, scanner);
+    const usedVars = await scanDirectoryForCodeVars(rootDir, serverlessDir, scanner, config.exclude);
     Logger.info(`Found ${usedVars.size} variable(s) used in code`, true);
     Logger.blank();
 
@@ -72,10 +80,10 @@ export async function scanCommand(options: { ci?: boolean; strict?: boolean }) {
     }
 
     // Check for variables used in code but not defined in serverless.yml
-    const missingFromServerless: Array<{ varName: string; locations: string[]; category?: string }> = [];
+    const missingFromServerless: Array<{ varName: string; locations: string[]; hasFallback: boolean; category?: string }> = [];
     const skippedRuntimeVars: Array<{ varName: string; category: string }> = [];
 
-    for (const [varName, locations] of usedVars.entries()) {
+    for (const [varName, usage] 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);
@@ -87,17 +95,18 @@ export async function scanCommand(options: { ci?: boolean; strict?: boolean }) {
             skippedRuntimeVars.push({ varName, category });
           }
         } else {
-          missingFromServerless.push({ varName, locations });
+          missingFromServerless.push({ varName, locations: usage.locations, hasFallback: usage.hasFallback });
         }
       }
     }
 
     if (unusedServerlessVars.length > 0) {
-      Logger.warning('Unused variables in serverless.yml:', true);
+      Logger.info('Unused variables in serverless.yml:', true);
       unusedServerlessVars.forEach((varName) => {
-        Logger.warningItem(varName, 2);
+        Logger.infoItem(varName, 2);
         allIssues.push({
           type: 'unused',
+          severity: 'info',
           varName,
           details: `Defined in serverless.yml but never used in code`,
         });
@@ -106,20 +115,48 @@ export async function scanCommand(options: { ci?: boolean; strict?: boolean }) {
     }
 
     if (missingFromServerless.length > 0) {
-      Logger.error('Missing from serverless.yml:', true);
-      missingFromServerless.forEach((item) => {
-        Logger.errorItem(item.varName, 2);
-        if (item.locations && item.locations.length > 0) {
-          Logger.info(`Used in: ${item.locations.slice(0, 2).join(', ')}`, true);
-        }
-        allIssues.push({
-          type: 'missing',
-          varName: item.varName,
-          details: `Used in code but not defined in serverless.yml`,
-          locations: item.locations,
+      // Group by severity (respect detectFallbacks config)
+      const errors = missingFromServerless.filter(item => !detectFallbacks || !item.hasFallback);
+      const warnings = missingFromServerless.filter(item => detectFallbacks && item.hasFallback);
+
+      if (errors.length > 0) {
+        Logger.error('Missing from serverless.yml:', true);
+        errors.forEach((item) => {
+          Logger.errorItem(item.varName, 2);
+          if (item.locations && item.locations.length > 0) {
+            Logger.info(`Used in: ${item.locations.slice(0, 2).join(', ')}`, true);
+          }
+          const details = (detectFallbacks && item.hasFallback)
+            ? `Used in code with fallback but not defined in serverless.yml`
+            : `Used in code but not defined in serverless.yml`;
+          allIssues.push({
+            type: 'missing',
+            severity: 'error',
+            varName: item.varName,
+            details,
+            locations: item.locations,
+          });
         });
-      });
-      Logger.blank();
+        Logger.blank();
+      }
+
+      if (warnings.length > 0) {
+        Logger.warning('Missing from serverless.yml (with fallback):', true);
+        warnings.forEach((item) => {
+          Logger.warningItem(item.varName, 2);
+          if (item.locations && item.locations.length > 0) {
+            Logger.info(`Used in: ${item.locations.slice(0, 2).join(', ')}`, true);
+          }
+          allIssues.push({
+            type: 'missing',
+            severity: 'warning',
+            varName: item.varName,
+            details: `Used in code with fallback but not defined in serverless.yml`,
+            locations: item.locations,
+          });
+        });
+        Logger.blank();
+      }
     }
 
     if (unusedServerlessVars.length === 0 && missingFromServerless.length === 0) {
@@ -155,7 +192,26 @@ export async function scanCommand(options: { ci?: boolean; strict?: boolean }) {
     Logger.blank();
 
     // Step 3: Scan code files in this directory and subdirectories
-    const usedVars = await scanDirectoryForVars(rootDir, envDir, scanner);
+    const allUsedVars = await scanDirectoryForVars(rootDir, envDir, scanner, config.exclude);
+
+    // Filter out ignored variables based on config
+    const usedVars = new Map<string, { locations: string[], hasFallback: boolean }>();
+    const skippedVarsInScope: Array<{ varName: string; category: string }> = [];
+
+    for (const [varName, usage] of allUsedVars.entries()) {
+      const isCustomIgnored = ConfigLoader.shouldIgnoreVar(varName, config);
+      const isRuntimeVar = isKnownRuntimeVar(varName);
+
+      // In non-strict mode, skip known runtime variables and custom ignore vars
+      if (strictMode || (!isRuntimeVar && !isCustomIgnored)) {
+        usedVars.set(varName, usage);
+      } else {
+        const category = isCustomIgnored ? 'Custom (from config)' : getRuntimeVarCategory(varName);
+        if (category) {
+          skippedVarsInScope.push({ varName, category });
+        }
+      }
+    }
 
     Logger.info(`Found ${usedVars.size} variable(s) used in this scope`, true);
 
@@ -170,17 +226,19 @@ export async function scanCommand(options: { ci?: boolean; strict?: boolean }) {
     Logger.blank();
 
     // Step 6: Analyze and find issues
-    const result = analyzer.analyze(usedVars, definedVars, exampleVars);
+    const result = analyzer.analyze(usedVars, definedVars, exampleVars, detectFallbacks);
 
     if (result.issues.length > 0) {
-      // Group issues by type
-      const missingIssues = result.issues.filter(i => i.type === 'missing');
+      // Group issues by type and severity
+      const missingErrors = result.issues.filter(i => i.type === 'missing' && i.severity === 'error');
+      const missingWarnings = result.issues.filter(i => i.type === 'missing' && i.severity === 'warning');
       const unusedIssues = result.issues.filter(i => i.type === 'unused');
-      const undocumentedIssues = result.issues.filter(i => i.type === 'undocumented');
+      const undocumentedWarnings = result.issues.filter(i => i.type === 'undocumented' && i.severity === 'warning');
+      const undocumentedInfo = result.issues.filter(i => i.type === 'undocumented' && i.severity === 'info');
 
-      if (missingIssues.length > 0) {
+      if (missingErrors.length > 0) {
         Logger.error('Missing from .env:', true);
-        missingIssues.forEach((issue) => {
+        missingErrors.forEach((issue) => {
           Logger.errorItem(issue.varName, 2);
           if (issue.locations && issue.locations.length > 0) {
             Logger.info(`Used in: ${issue.locations.slice(0, 2).join(', ')}`, true);
@@ -189,17 +247,36 @@ export async function scanCommand(options: { ci?: boolean; strict?: boolean }) {
         Logger.blank();
       }
 
+      if (missingWarnings.length > 0) {
+        Logger.warning('Missing from .env (with fallback):', true);
+        missingWarnings.forEach((issue) => {
+          Logger.warningItem(issue.varName, 2);
+          if (issue.locations && issue.locations.length > 0) {
+            Logger.info(`Used in: ${issue.locations.slice(0, 2).join(', ')}`, true);
+          }
+        });
+        Logger.blank();
+      }
+
       if (unusedIssues.length > 0) {
-        Logger.warning('Unused variables:', true);
+        Logger.info('Unused variables:', true);
         unusedIssues.forEach((issue) => {
+          Logger.infoItem(issue.varName, 2);
+        });
+        Logger.blank();
+      }
+
+      if (undocumentedWarnings.length > 0) {
+        Logger.warning('Missing from .env.example:', true);
+        undocumentedWarnings.forEach((issue) => {
           Logger.warningItem(issue.varName, 2);
         });
         Logger.blank();
       }
 
-      if (undocumentedIssues.length > 0) {
-        Logger.info('Missing from .env.example:', true);
-        undocumentedIssues.forEach((issue) => {
+      if (undocumentedInfo.length > 0) {
+        Logger.info('Missing from .env.example (with fallback):', true);
+        undocumentedInfo.forEach((issue) => {
           Logger.infoItem(issue.varName, 2);
         });
         Logger.blank();
@@ -210,6 +287,23 @@ export async function scanCommand(options: { ci?: boolean; strict?: boolean }) {
       Logger.success('No issues in this directory', true);
       Logger.blank();
     }
+
+    // Show skipped variables in non-strict mode
+    if (!strictMode && skippedVarsInScope.length > 0) {
+      Logger.info('Skipped known runtime/ignored variables (use --strict to show):', true);
+      // Group by category
+      const grouped = new Map<string, string[]>();
+      for (const { varName, category } of skippedVarsInScope) {
+        if (!grouped.has(category)) {
+          grouped.set(category, []);
+        }
+        grouped.get(category)!.push(varName);
+      }
+      for (const [category, vars] of grouped.entries()) {
+        Logger.info(`${category}: ${vars.join(', ')}`, true);
+      }
+      Logger.blank();
+    }
   }
 
   // Display summary
@@ -219,8 +313,23 @@ export async function scanCommand(options: { ci?: boolean; strict?: boolean }) {
     return { success: true, issues: [] };
   }
 
+  // Count issues by severity
+  const errorCount = allIssues.filter(i => i.severity === 'error').length;
+  const warningCount = allIssues.filter(i => i.severity === 'warning').length;
+  const infoCount = allIssues.filter(i => i.severity === 'info').length;
+
   Logger.blank();
-  Logger.warning(`Total: ${allIssues.length} issue(s) across ${envFiles.length} location(s)`);
+  if (errorCount > 0) {
+    Logger.error(`Errors: ${errorCount}`, false);
+  }
+  if (warningCount > 0) {
+    Logger.warning(`Warnings: ${warningCount}`, false);
+  }
+  if (infoCount > 0) {
+    Logger.info(`Info: ${infoCount}`, false);
+  }
+  Logger.blank();
+  Logger.warning(`Total: ${allIssues.length} issue(s) across ${envFiles.length + serverlessFiles.length} location(s)`);
   Logger.blank();
 
   // Suggest fix
@@ -242,28 +351,34 @@ export async function scanCommand(options: { ci?: boolean; strict?: boolean }) {
 async function scanDirectoryForVars(
   rootDir: string,
   targetDir: string,
-  scanner: CodeScanner
-): Promise<Map<string, string[]>> {
-  const envVars = new Map<string, string[]>();
+  scanner: CodeScanner,
+  excludePatterns: string[] = []
+): Promise<Map<string, { locations: string[], hasFallback: boolean }>> {
+  const envVars = new Map<string, { locations: string[], hasFallback: boolean }>();
 
   // 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 defaultIgnore = ['**/node_modules/**', '**/dist/**', '**/build/**', '**/.git/**'];
+  const customIgnore = excludePatterns.map(p => p.includes('*') ? p : `**/${p}/**`);
+
   const files = await glob(pattern, {
     cwd: rootDir,
-    ignore: ['**/node_modules/**', '**/dist/**', '**/build/**', '**/.git/**'],
+    ignore: [...defaultIgnore, ...customIgnore],
     absolute: true,
   });
 
   for (const file of files) {
     const vars = await scanner.scanFile(file);
-    for (const varName of vars) {
+    for (const [varName, hasFallback] of vars.entries()) {
       const relativePath = path.relative(rootDir, file);
       if (!envVars.has(varName)) {
-        envVars.set(varName, []);
+        envVars.set(varName, { locations: [], hasFallback: false });
       }
-      envVars.get(varName)!.push(relativePath);
+      const entry = envVars.get(varName)!;
+      entry.locations.push(relativePath);
+      entry.hasFallback = entry.hasFallback || hasFallback;
     }
   }
 
@@ -274,28 +389,34 @@ async function scanDirectoryForVars(
 async function scanDirectoryForCodeVars(
   rootDir: string,
   targetDir: string,
-  scanner: CodeScanner
-): Promise<Map<string, string[]>> {
-  const envVars = new Map<string, string[]>();
+  scanner: CodeScanner,
+  excludePatterns: string[] = []
+): Promise<Map<string, { locations: string[], hasFallback: boolean }>> {
+  const envVars = new Map<string, { locations: string[], hasFallback: boolean }>();
 
   // 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 defaultIgnore = ['**/node_modules/**', '**/dist/**', '**/build/**', '**/.git/**'];
+  const customIgnore = excludePatterns.map(p => p.includes('*') ? p : `**/${p}/**`);
+
   const files = await glob(pattern, {
     cwd: rootDir,
-    ignore: ['**/node_modules/**', '**/dist/**', '**/build/**', '**/.git/**'],
+    ignore: [...defaultIgnore, ...customIgnore],
     absolute: true,
   });
 
   for (const file of files) {
     const vars = await scanner.scanFile(file);
-    for (const varName of vars) {
+    for (const [varName, hasFallback] of vars.entries()) {
       const relativePath = path.relative(rootDir, file);
       if (!envVars.has(varName)) {
-        envVars.set(varName, []);
+        envVars.set(varName, { locations: [], hasFallback: false });
       }
-      envVars.get(varName)!.push(relativePath);
+      const entry = envVars.get(varName)!;
+      entry.locations.push(relativePath);
+      entry.hasFallback = entry.hasFallback || hasFallback;
     }
   }
 

package/src/config/configLoader.ts

@@ -17,12 +17,20 @@ export interface EnvGuardConfig {
    * Enable strict mode by default
    */
   strict?: boolean;
+
+  /**
+   * Detect fallback patterns in code (||, ??, conditionals, etc.)
+   * When enabled, variables with fallbacks are treated as warnings instead of errors
+   * Default: true
+   */
+  detectFallbacks?: boolean;
 }
 
 const DEFAULT_CONFIG: EnvGuardConfig = {
   ignoreVars: [],
   exclude: [],
   strict: false,
+  detectFallbacks: true,
 };
 
 const CONFIG_FILE_NAMES = [