envprobe 1.0.0

package/src/scanner.js

@@ -0,0 +1,182 @@
+/**
+ * File Scanner Module
+ * 
+ * Recursively scans directories to find source files and detect environment variable references.
+ * Handles symlinks, permission errors, and integrates with ignore patterns.
+ * 
+ * Requirements: 1.4.1-1.4.5
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { shouldIgnore } from './ignore.js';
+import { normalizePath } from './utils.js';
+
+/**
+ * Get supported file extensions for scanning
+ * 
+ * @returns {string[]} Array of file extensions to scan
+ * 
+ * Requirements: 1.4.2
+ */
+export function getSupportedExtensions() {
+  return [
+    '.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs',  // JavaScript/TypeScript
+    '.py',                                          // Python
+    '.go',                                          // Go
+    '.rb',                                          // Ruby
+    '.rs',                                          // Rust
+    '.sh', '.bash', '.zsh'                          // Shell/Bash
+  ];
+}
+
+/**
+ * Check if a file has a supported extension
+ * 
+ * @param {string} filePath - Path to the file
+ * @returns {boolean} True if file extension is supported
+ * 
+ * Requirements: 1.4.2
+ */
+export function hasSupportedExtension(filePath) {
+  const ext = path.extname(filePath).toLowerCase();
+  return getSupportedExtensions().includes(ext);
+}
+
+/**
+ * Scan a directory recursively for source files
+ * 
+ * @param {string} dirPath - Directory path to scan
+ * @param {string[]} ignorePatterns - Array of ignore patterns
+ * @param {Set<string>} visitedPaths - Set of visited paths (for symlink cycle detection)
+ * @returns {Promise<string[]>} Array of file paths to scan
+ * 
+ * Preconditions:
+ * - dirPath is a valid directory path
+ * - ignorePatterns is a valid array (may be empty)
+ * 
+ * Postconditions:
+ * - Returns array of all source files found
+ * - Excludes files matching ignore patterns
+ * - Handles symlink cycles without infinite loops
+ * - Continues on permission errors
+ * 
+ * Requirements: 1.4.1, 1.4.3, 1.4.4, 1.4.5
+ */
+export async function scanDirectory(dirPath, ignorePatterns = [], visitedPaths = new Set()) {
+  const files = [];
+  const normalizedDirPath = normalizePath(path.resolve(dirPath));
+  
+  // Check if we've already visited this path (symlink cycle detection)
+  if (visitedPaths.has(normalizedDirPath)) {
+    return files;
+  }
+  
+  visitedPaths.add(normalizedDirPath);
+  
+  try {
+    const entries = await fs.promises.readdir(dirPath, { withFileTypes: true });
+    
+    for (const entry of entries) {
+      const fullPath = path.join(dirPath, entry.name);
+      const relativePath = normalizePath(path.relative(process.cwd(), fullPath));
+      
+      // Check if path should be ignored (check both full path and just the name)
+      if (shouldIgnore(relativePath, ignorePatterns) || 
+          shouldIgnore(entry.name, ignorePatterns) ||
+          shouldIgnore(relativePath + '/', ignorePatterns)) {
+        continue;
+      }
+      
+      try {
+        let stats;
+        
+        if (entry.isSymbolicLink()) {
+          // For symlinks, get stats of the target
+          try {
+            stats = await fs.promises.stat(fullPath);
+          } catch (error) {
+            // Broken symlink or permission denied - skip it
+            console.warn(`Warning: Cannot access symlink target: ${relativePath}`);
+            continue;
+          }
+        } else {
+          stats = entry;
+        }
+        
+        if (stats.isDirectory()) {
+          // Recursively scan subdirectory
+          const subFiles = await scanDirectory(fullPath, ignorePatterns, visitedPaths);
+          files.push(...subFiles);
+        } else if (stats.isFile() && hasSupportedExtension(fullPath)) {
+          // Add file to list if it has a supported extension
+          files.push(fullPath);
+        }
+      } catch (error) {
+        // Permission denied or other error - log warning and continue
+        if (error.code === 'EACCES' || error.code === 'EPERM') {
+          console.warn(`Warning: Permission denied: ${relativePath}`);
+        } else {
+          console.warn(`Warning: Error accessing ${relativePath}: ${error.message}`);
+        }
+        continue;
+      }
+    }
+  } catch (error) {
+    // Directory read error - log warning and return what we have
+    if (error.code === 'EACCES' || error.code === 'EPERM') {
+      console.warn(`Warning: Permission denied: ${normalizedDirPath}`);
+    } else if (error.code === 'ENOENT') {
+      console.warn(`Warning: Directory not found: ${normalizedDirPath}`);
+    } else {
+      console.warn(`Warning: Error reading directory ${normalizedDirPath}: ${error.message}`);
+    }
+  }
+  
+  return files;
+}
+
+/**
+ * Scan a single file or directory
+ * 
+ * @param {string} targetPath - File or directory path to scan
+ * @param {string[]} ignorePatterns - Array of ignore patterns
+ * @returns {Promise<string[]>} Array of file paths to scan
+ * 
+ * Preconditions:
+ * - targetPath exists and is readable
+ * 
+ * Postconditions:
+ * - Returns array with single file if targetPath is a file
+ * - Returns array of all source files if targetPath is a directory
+ * 
+ * Requirements: 1.4.1, 1.5.1
+ */
+export async function scan(targetPath, ignorePatterns = []) {
+  try {
+    const stats = await fs.promises.stat(targetPath);
+    
+    if (stats.isFile()) {
+      // Single file - return it if it has a supported extension
+      if (hasSupportedExtension(targetPath)) {
+        return [targetPath];
+      } else {
+        return [];
+      }
+    } else if (stats.isDirectory()) {
+      // Directory - scan recursively
+      return await scanDirectory(targetPath, ignorePatterns);
+    } else {
+      console.warn(`Warning: ${targetPath} is neither a file nor a directory`);
+      return [];
+    }
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new Error(`Path not found: ${targetPath}`);
+    } else if (error.code === 'EACCES' || error.code === 'EPERM') {
+      throw new Error(`Permission denied: ${targetPath}`);
+    } else {
+      throw new Error(`Error accessing ${targetPath}: ${error.message}`);
+    }
+  }
+}

package/src/scanners/go.js

@@ -0,0 +1,89 @@
+/**
+ * Go Scanner
+ * Detects environment variable references in Go files
+ * Supports: os.Getenv("VAR"), os.LookupEnv("VAR")
+ */
+
+/**
+ * Regex patterns for detecting environment variable references
+ * Pattern 1: os.Getenv("VAR_NAME") - standard library function for getting env vars
+ * Pattern 2: os.LookupEnv("VAR_NAME") - returns value and boolean indicating if var exists
+ */
+const PATTERNS = [
+  // os.Getenv("VAR_NAME") - standard way to get environment variables
+  /os\.Getenv\("([A-Z_][A-Z0-9_]*)"\)/g,
+  
+  // os.LookupEnv("VAR_NAME") - returns (value, exists) tuple
+  /os\.LookupEnv\("([A-Z_][A-Z0-9_]*)"\)/g,
+];
+
+/**
+ * Supported file extensions for Go
+ */
+const SUPPORTED_EXTENSIONS = ['.go'];
+
+/**
+ * Scan file content for environment variable references
+ * @param {string} content - File content to scan
+ * @param {string} filePath - Path to the file being scanned
+ * @returns {Array<{varName: string, filePath: string, lineNumber: number, pattern: string}>}
+ */
+export function scan(content, filePath) {
+  const references = [];
+  const lines = content.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    references.push(...scanLine(lines[i], filePath, i + 1));
+  }
+
+  return references;
+}
+
+export function scanLine(line, filePath, lineNumber) {
+  const references = [];
+
+  for (const pattern of PATTERNS) {
+    pattern.lastIndex = 0;
+    let match;
+    while ((match = pattern.exec(line)) !== null) {
+      const varName = match[1];
+
+      if (varName && isValidEnvVarName(varName)) {
+        references.push({
+          varName,
+          filePath,
+          lineNumber,
+          pattern: match[0],
+        });
+      }
+    }
+  }
+
+  return references;
+}
+
+/**
+ * Validate environment variable name
+ * Must start with letter or underscore, contain only uppercase letters, digits, and underscores
+ * @param {string} varName - Variable name to validate
+ * @returns {boolean}
+ */
+function isValidEnvVarName(varName) {
+  return /^[A-Z_][A-Z0-9_]*$/.test(varName);
+}
+
+/**
+ * Get supported file extensions
+ * @returns {string[]}
+ */
+export function getSupportedExtensions() {
+  return SUPPORTED_EXTENSIONS;
+}
+
+/**
+ * Get regex patterns used for scanning
+ * @returns {RegExp[]}
+ */
+export function getPatterns() {
+  return PATTERNS;
+}

package/src/scanners/javascript.js

@@ -0,0 +1,93 @@
+/**
+ * JavaScript/TypeScript Scanner
+ * Detects environment variable references in JS/TS files
+ * Supports: process.env.VAR, process.env['VAR'], import.meta.env.VAR
+ */
+
+/**
+ * Regex patterns for detecting environment variable references
+ * Pattern 1: process.env.VAR_NAME (dot notation)
+ * Pattern 2: process.env['VAR_NAME'] or process.env["VAR_NAME"] (bracket notation)
+ * Pattern 3: import.meta.env.VAR_NAME (Vite/modern bundlers)
+ */
+const PATTERNS = [
+  // Dot notation: process.env.VAR_NAME
+  /process\.env\.([A-Z_][A-Z0-9_]*)/g,
+  
+  // Bracket notation: process.env['VAR_NAME'] or process.env["VAR_NAME"]
+  /process\.env\[['"]([A-Z_][A-Z0-9_]*)['"]]/g,
+  
+  // Vite/modern bundlers: import.meta.env.VAR_NAME
+  /import\.meta\.env\.([A-Z_][A-Z0-9_]*)/g,
+];
+
+/**
+ * Supported file extensions for JavaScript/TypeScript
+ */
+const SUPPORTED_EXTENSIONS = ['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs'];
+
+/**
+ * Scan file content for environment variable references
+ * @param {string} content - File content to scan
+ * @param {string} filePath - Path to the file being scanned
+ * @returns {Array<{varName: string, filePath: string, lineNumber: number, pattern: string}>}
+ */
+export function scan(content, filePath) {
+  const references = [];
+  const lines = content.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    references.push(...scanLine(lines[i], filePath, i + 1));
+  }
+
+  return references;
+}
+
+export function scanLine(line, filePath, lineNumber) {
+  const references = [];
+
+  for (const pattern of PATTERNS) {
+    pattern.lastIndex = 0;
+    let match;
+    while ((match = pattern.exec(line)) !== null) {
+      const varName = match[1];
+
+      if (varName && isValidEnvVarName(varName)) {
+        references.push({
+          varName,
+          filePath,
+          lineNumber,
+          pattern: match[0],
+        });
+      }
+    }
+  }
+
+  return references;
+}
+
+/**
+ * Validate environment variable name
+ * Must start with letter or underscore, contain only uppercase letters, digits, and underscores
+ * @param {string} varName - Variable name to validate
+ * @returns {boolean}
+ */
+function isValidEnvVarName(varName) {
+  return /^[A-Z_][A-Z0-9_]*$/.test(varName);
+}
+
+/**
+ * Get supported file extensions
+ * @returns {string[]}
+ */
+export function getSupportedExtensions() {
+  return SUPPORTED_EXTENSIONS;
+}
+
+/**
+ * Get regex patterns used for scanning
+ * @returns {RegExp[]}
+ */
+export function getPatterns() {
+  return PATTERNS;
+}

package/src/scanners/python.js

@@ -0,0 +1,97 @@
+/**
+ * Python Scanner
+ * Detects environment variable references in Python files
+ * Supports: os.environ['VAR'], os.environ.get('VAR'), os.getenv('VAR')
+ */
+
+/**
+ * Regex patterns for detecting environment variable references
+ * Pattern 1: os.environ['VAR_NAME'] or os.environ["VAR_NAME"] (bracket notation)
+ * Pattern 2: os.environ.get('VAR_NAME') or os.environ.get("VAR_NAME") (get method)
+ * Pattern 3: os.getenv('VAR_NAME') or os.getenv("VAR_NAME") (getenv function)
+ */
+const PATTERNS = [
+  // Bracket notation: os.environ['VAR_NAME'] or os.environ["VAR_NAME"]
+  /os\.environ\[['"]([A-Z_][A-Z0-9_]*)['"]]/g,
+  
+  // Get method: os.environ.get('VAR_NAME') or os.environ.get("VAR_NAME")
+  // Matches with or without default values: os.environ.get('VAR', 'default')
+  // The pattern captures up to and including the closing paren if no comma follows
+  /os\.environ\.get\(['"]([A-Z_][A-Z0-9_]*)['"](?:,.*?)?\)/g,
+  
+  // Getenv function: os.getenv('VAR_NAME') or os.getenv("VAR_NAME")
+  // Matches with or without default values: os.getenv('VAR', 'default')
+  // The pattern captures up to and including the closing paren if no comma follows
+  /os\.getenv\(['"]([A-Z_][A-Z0-9_]*)['"](?:,.*?)?\)/g,
+];
+
+/**
+ * Supported file extensions for Python
+ */
+const SUPPORTED_EXTENSIONS = ['.py'];
+
+/**
+ * Scan file content for environment variable references
+ * @param {string} content - File content to scan
+ * @param {string} filePath - Path to the file being scanned
+ * @returns {Array<{varName: string, filePath: string, lineNumber: number, pattern: string}>}
+ */
+export function scan(content, filePath) {
+  const references = [];
+  const lines = content.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    references.push(...scanLine(lines[i], filePath, i + 1));
+  }
+
+  return references;
+}
+
+export function scanLine(line, filePath, lineNumber) {
+  const references = [];
+
+  for (const pattern of PATTERNS) {
+    pattern.lastIndex = 0;
+    let match;
+    while ((match = pattern.exec(line)) !== null) {
+      const varName = match[1];
+
+      if (varName && isValidEnvVarName(varName)) {
+        references.push({
+          varName,
+          filePath,
+          lineNumber,
+          pattern: match[0],
+        });
+      }
+    }
+  }
+
+  return references;
+}
+
+/**
+ * Validate environment variable name
+ * Must start with letter or underscore, contain only uppercase letters, digits, and underscores
+ * @param {string} varName - Variable name to validate
+ * @returns {boolean}
+ */
+function isValidEnvVarName(varName) {
+  return /^[A-Z_][A-Z0-9_]*$/.test(varName);
+}
+
+/**
+ * Get supported file extensions
+ * @returns {string[]}
+ */
+export function getSupportedExtensions() {
+  return SUPPORTED_EXTENSIONS;
+}
+
+/**
+ * Get regex patterns used for scanning
+ * @returns {RegExp[]}
+ */
+export function getPatterns() {
+  return PATTERNS;
+}

package/src/scanners/ruby.js

@@ -0,0 +1,90 @@
+/**
+ * Ruby Scanner
+ * Detects environment variable references in Ruby files
+ * Supports: ENV['VAR'], ENV.fetch('VAR')
+ */
+
+/**
+ * Regex patterns for detecting environment variable references
+ * Pattern 1: ENV['VAR_NAME'] or ENV["VAR_NAME"] (bracket notation)
+ * Pattern 2: ENV.fetch('VAR_NAME') or ENV.fetch("VAR_NAME") (fetch method)
+ */
+const PATTERNS = [
+  // Bracket notation: ENV['VAR_NAME'] or ENV["VAR_NAME"]
+  /ENV\[['"]([A-Z_][A-Z0-9_]*)['"]]/g,
+  
+  // Fetch method: ENV.fetch('VAR_NAME') or ENV.fetch("VAR_NAME")
+  // Matches with or without default values: ENV.fetch('VAR', 'default')
+  /ENV\.fetch\(['"]([A-Z_][A-Z0-9_]*)['"](?:,.*?)?\)/g,
+];
+
+/**
+ * Supported file extensions for Ruby
+ */
+const SUPPORTED_EXTENSIONS = ['.rb'];
+
+/**
+ * Scan file content for environment variable references
+ * @param {string} content - File content to scan
+ * @param {string} filePath - Path to the file being scanned
+ * @returns {Array<{varName: string, filePath: string, lineNumber: number, pattern: string}>}
+ */
+export function scan(content, filePath) {
+  const references = [];
+  const lines = content.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    references.push(...scanLine(lines[i], filePath, i + 1));
+  }
+
+  return references;
+}
+
+export function scanLine(line, filePath, lineNumber) {
+  const references = [];
+
+  for (const pattern of PATTERNS) {
+    pattern.lastIndex = 0;
+    let match;
+    while ((match = pattern.exec(line)) !== null) {
+      const varName = match[1];
+
+      if (varName && isValidEnvVarName(varName)) {
+        references.push({
+          varName,
+          filePath,
+          lineNumber,
+          pattern: match[0],
+        });
+      }
+    }
+  }
+
+  return references;
+}
+
+/**
+ * Validate environment variable name
+ * Must start with letter or underscore, contain only uppercase letters, digits, and underscores
+ * @param {string} varName - Variable name to validate
+ * @returns {boolean}
+ */
+function isValidEnvVarName(varName) {
+  return /^[A-Z_][A-Z0-9_]*$/.test(varName);
+}
+
+/**
+ * Get supported file extensions
+ * @returns {string[]}
+ */
+export function getSupportedExtensions() {
+  return SUPPORTED_EXTENSIONS;
+}
+
+/**
+ * Get regex patterns used for scanning
+ * @returns {RegExp[]}
+ */
+export function getPatterns() {
+  return PATTERNS;
+}

package/src/scanners/rust.js

@@ -0,0 +1,103 @@
+/**
+ * Rust Scanner
+ * Detects environment variable references in Rust files
+ * Supports: env::var("VAR"), std::env::var("VAR"), env::var_os("VAR"), std::env::var_os("VAR")
+ */
+
+/**
+ * Regex patterns for detecting environment variable references
+ * Pattern 1: std::env::var("VAR_NAME") - full path form (returns Result<String>)
+ * Pattern 2: std::env::var_os("VAR_NAME") - full path form returning OsString (returns Option<OsString>)
+ * Pattern 3: env::var("VAR_NAME") - short form for getting env vars (returns Result<String>)
+ * Pattern 4: env::var_os("VAR_NAME") - short form returning OsString (returns Option<OsString>)
+ * 
+ * Note: Order matters! We check std::env:: patterns first to avoid double-matching
+ * (since "env::var" would match within "std::env::var")
+ */
+const PATTERNS = [
+  // std::env::var("VAR_NAME") - full path form, returns Result<String, VarError>
+  // Use negative lookbehind to ensure we don't match if preceded by non-whitespace (avoids matching "std::env::var")
+  /std::env::var\("([A-Z_][A-Z0-9_]*)"\)/g,
+  
+  // std::env::var_os("VAR_NAME") - full path form, returns Option<OsString>
+  /std::env::var_os\("([A-Z_][A-Z0-9_]*)"\)/g,
+  
+  // env::var("VAR_NAME") - short form, returns Result<String, VarError>
+  // Use negative lookbehind to ensure not preceded by "std::" to avoid double-matching
+  /(?<!std::)env::var\("([A-Z_][A-Z0-9_]*)"\)/g,
+  
+  // env::var_os("VAR_NAME") - short form, returns Option<OsString>
+  // Use negative lookbehind to ensure not preceded by "std::" to avoid double-matching
+  /(?<!std::)env::var_os\("([A-Z_][A-Z0-9_]*)"\)/g,
+];
+
+/**
+ * Supported file extensions for Rust
+ */
+const SUPPORTED_EXTENSIONS = ['.rs'];
+
+/**
+ * Scan file content for environment variable references
+ * @param {string} content - File content to scan
+ * @param {string} filePath - Path to the file being scanned
+ * @returns {Array<{varName: string, filePath: string, lineNumber: number, pattern: string}>}
+ */
+export function scan(content, filePath) {
+  const references = [];
+  const lines = content.split('\n');
+
+  for (let i = 0; i < lines.length; i++) {
+    references.push(...scanLine(lines[i], filePath, i + 1));
+  }
+
+  return references;
+}
+
+export function scanLine(line, filePath, lineNumber) {
+  const references = [];
+
+  for (const pattern of PATTERNS) {
+    pattern.lastIndex = 0;
+    let match;
+    while ((match = pattern.exec(line)) !== null) {
+      const varName = match[1];
+
+      if (varName && isValidEnvVarName(varName)) {
+        references.push({
+          varName,
+          filePath,
+          lineNumber,
+          pattern: match[0],
+        });
+      }
+    }
+  }
+
+  return references;
+}
+
+/**
+ * Validate environment variable name
+ * Must start with letter or underscore, contain only uppercase letters, digits, and underscores
+ * @param {string} varName - Variable name to validate
+ * @returns {boolean}
+ */
+function isValidEnvVarName(varName) {
+  return /^[A-Z_][A-Z0-9_]*$/.test(varName);
+}
+
+/**
+ * Get supported file extensions
+ * @returns {string[]}
+ */
+export function getSupportedExtensions() {
+  return SUPPORTED_EXTENSIONS;
+}
+
+/**
+ * Get regex patterns used for scanning
+ * @returns {RegExp[]}
+ */
+export function getPatterns() {
+  return PATTERNS;
+}