envprobe 1.0.0

package/src/ignore.js

@@ -0,0 +1,313 @@
+/**
+ * Ignore Pattern Handler Module
+ * 
+ * Handles loading and matching of ignore patterns from .gitignore, .envcheckignore,
+ * and default patterns. Supports glob pattern syntax and negation patterns.
+ * 
+ * Requirements: 1.7.1-1.7.6
+ */
+
+import fs from 'fs';
+
+/**
+ * Load ignore patterns from .gitignore and .envcheckignore files
+ * 
+ * @param {string} basePath - Base directory path to search for ignore files
+ * @returns {string[]} Array of ignore patterns
+ * 
+ * Preconditions:
+ * - basePath is a valid directory path
+ * 
+ * Postconditions:
+ * - Returns array of patterns from .gitignore, .envcheckignore, and defaults
+ * - Returns at least default patterns if no ignore files exist
+ * 
+ * Requirements: 1.7.1, 1.7.2, 1.7.3
+ */
+export function loadIgnorePatterns(basePath) {
+  const patterns = [];
+  
+  // Add default patterns first
+  patterns.push(...getDefaultIgnores());
+  
+  // Load .gitignore patterns if exists
+  const gitignorePath = `${basePath}/.gitignore`;
+  const gitignorePatterns = parseGitignore(gitignorePath);
+  patterns.push(...gitignorePatterns);
+  
+  // Load .envcheckignore patterns if exists
+  const envcheckignorePath = `${basePath}/.envcheckignore`;
+  const envcheckignorePatterns = parseEnvcheckignore(envcheckignorePath);
+  patterns.push(...envcheckignorePatterns);
+  
+  return patterns;
+}
+
+/**
+ * Check if a file path should be ignored based on patterns
+ * 
+ * @param {string} filePath - File path to check (relative or absolute)
+ * @param {string[]} patterns - Array of glob patterns
+ * @returns {boolean} True if file should be ignored, false otherwise
+ * 
+ * Preconditions:
+ * - filePath is a non-empty string
+ * - patterns is a valid array (may be empty)
+ * 
+ * Postconditions:
+ * - Returns true if filePath matches any pattern
+ * - Returns false if no patterns match
+ * - Handles negation patterns correctly
+ * 
+ * Requirements: 1.7.5, 1.7.6
+ */
+export function shouldIgnore(filePath, patterns) {
+  if (!patterns || patterns.length === 0) {
+    return false;
+  }
+  
+  let ignored = false;
+  
+  // Process patterns in order - later patterns can override earlier ones
+  for (const pattern of patterns) {
+    if (isNegationPattern(pattern)) {
+      // Negation pattern - if it matches, un-ignore the file
+      const actualPattern = removeNegationPrefix(pattern);
+      if (matchGlob(filePath, actualPattern)) {
+        ignored = false;
+      }
+    } else {
+      // Regular pattern - if it matches, ignore the file
+      if (matchGlob(filePath, pattern)) {
+        ignored = true;
+      }
+    }
+  }
+  
+  return ignored;
+}
+
+/**
+ * Parse a .gitignore file and extract patterns
+ * 
+ * @param {string} filePath - Path to .gitignore file
+ * @returns {string[]} Array of ignore patterns
+ * 
+ * Preconditions:
+ * - filePath points to a readable file
+ * 
+ * Postconditions:
+ * - Returns array of non-empty, non-comment lines
+ * - Trims whitespace from patterns
+ * - Returns empty array if file doesn't exist or is unreadable
+ * 
+ * Requirements: 1.7.1
+ */
+export function parseGitignore(filePath) {
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    
+    return content
+      .split('\n')
+      .map(line => line.trim())
+      .filter(line => line !== '' && !line.startsWith('#'));
+  } catch (error) {
+    // Return empty array if file doesn't exist or is unreadable
+    return [];
+  }
+}
+
+/**
+ * Parse a .envcheckignore file and extract patterns
+ * 
+ * @param {string} filePath - Path to .envcheckignore file
+ * @returns {string[]} Array of ignore patterns
+ * 
+ * Preconditions:
+ * - filePath points to a readable file
+ * 
+ * Postconditions:
+ * - Returns array of non-empty, non-comment lines
+ * - Trims whitespace from patterns
+ * - Returns empty array if file doesn't exist or is unreadable
+ * 
+ * Requirements: 1.7.2
+ */
+export function parseEnvcheckignore(filePath) {
+  // Same implementation as parseGitignore - both use same format
+  try {
+    const content = fs.readFileSync(filePath, 'utf8');
+    
+    return content
+      .split('\n')
+      .map(line => line.trim())
+      .filter(line => line !== '' && !line.startsWith('#'));
+  } catch (error) {
+    // Return empty array if file doesn't exist or is unreadable
+    return [];
+  }
+}
+
+/**
+ * Get default ignore patterns
+ * 
+ * @returns {string[]} Array of default ignore patterns
+ * 
+ * Postconditions:
+ * - Returns array containing at least: node_modules, .git, dist, build
+ * 
+ * Requirements: 1.7.3
+ */
+export function getDefaultIgnores() {
+  return [
+    'node_modules/**',
+    'node_modules',
+    '.git/**',
+    '.git',
+    'dist/**',
+    'dist',
+    'build/**',
+    'build',
+    'coverage/**',
+    '.nyc_output/**',
+    '**/*.min.js',
+    '**/*.bundle.js',
+    '**/vendor/**',
+    '**/tmp/**',
+    '**/temp/**'
+  ];
+}
+
+/**
+ * Match a file path against a glob pattern
+ * 
+ * @param {string} filePath - File path to match
+ * @param {string} pattern - Glob pattern (supports *, **, ?, [])
+ * @returns {boolean} True if path matches pattern
+ * 
+ * Preconditions:
+ * - filePath is a non-empty string
+ * - pattern is a valid glob pattern
+ * 
+ * Postconditions:
+ * - Returns true if filePath matches the glob pattern
+ * - Supports * (any characters except /), ** (any characters including /), ? (single char), [] (char class)
+ * 
+ * Requirements: 1.7.5
+ */
+export function matchGlob(filePath, pattern) {
+  // Normalize paths to use forward slashes
+  const normalizedPath = filePath.replace(/\\/g, '/');
+  let normalizedPattern = pattern.replace(/\\/g, '/');
+  
+  // If pattern ends with /**, also match the directory itself
+  // e.g., node_modules/** should match both "node_modules" and "node_modules/anything"
+  if (normalizedPattern.endsWith('/**')) {
+    const dirPattern = normalizedPattern.slice(0, -3); // Remove /**
+    if (matchGlobInternal(normalizedPath, dirPattern)) {
+      return true;
+    }
+  }
+  
+  return matchGlobInternal(normalizedPath, normalizedPattern);
+}
+
+/**
+ * Validate a glob pattern for correctness
+ * 
+ * @param {string} pattern - Glob pattern to validate
+ * @returns {boolean} True if valid
+ * @throws {Error} If pattern is invalid
+ */
+export function validateGlobPattern(pattern) {
+  if (typeof pattern !== 'string' || pattern.trim() === '') {
+    throw new Error('Glob pattern cannot be empty');
+  }
+
+  let escaped = false;
+  let bracketDepth = 0;
+
+  for (const char of pattern) {
+    if (escaped) {
+      escaped = false;
+      continue;
+    }
+
+    if (char === '\\') {
+      escaped = true;
+      continue;
+    }
+
+    if (char === '[') {
+      bracketDepth += 1;
+      continue;
+    }
+
+    if (char === ']') {
+      if (bracketDepth === 0) {
+        throw new Error(`Invalid glob pattern: "${pattern}"`);
+      }
+      bracketDepth -= 1;
+    }
+  }
+
+  if (escaped || bracketDepth !== 0) {
+    throw new Error(`Invalid glob pattern: "${pattern}"`);
+  }
+
+  return true;
+}
+
+/**
+ * Internal glob matching implementation
+ * @private
+ */
+function matchGlobInternal(filePath, pattern) {
+  // Convert glob pattern to regex
+  let regexPattern = pattern
+    // Escape special regex characters except glob wildcards
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    // Replace ** with a placeholder to handle it separately
+    .replace(/\*\*/g, '___DOUBLESTAR___')
+    // Replace * with regex for any characters except /
+    .replace(/\*/g, '[^/]*')
+    // Replace ? with regex for single character
+    .replace(/\?/g, '[^/]')
+    // Replace ** placeholder with regex for any characters including /
+    // Use (.*\/)? to make the directory part optional for patterns like **/*.js
+    .replace(/___DOUBLESTAR___\//g, '(.*/)?')
+    .replace(/___DOUBLESTAR___/g, '.*');
+  
+  // Add anchors to match entire path
+  regexPattern = `^${regexPattern}$`;
+  
+  const regex = new RegExp(regexPattern);
+  return regex.test(filePath);
+}
+
+/**
+ * Check if a pattern is a negation pattern
+ * 
+ * @param {string} pattern - Pattern to check
+ * @returns {boolean} True if pattern starts with !
+ * 
+ * Requirements: 1.7.6
+ */
+export function isNegationPattern(pattern) {
+  return pattern.startsWith('!');
+}
+
+/**
+ * Remove negation prefix from pattern
+ * 
+ * @param {string} pattern - Negation pattern (e.g., "!*.test.js")
+ * @returns {string} Pattern without negation prefix (e.g., "*.test.js")
+ * 
+ * Preconditions:
+ * - pattern starts with !
+ * 
+ * Requirements: 1.7.6
+ */
+export function removeNegationPrefix(pattern) {
+  return pattern.startsWith('!') ? pattern.slice(1) : pattern;
+}

package/src/parser.js

@@ -0,0 +1,119 @@
+import { readFile } from 'fs/promises';
+
+/**
+ * Parses a .env.example file and extracts environment variable definitions.
+ * 
+ * @param {string} filePath - Path to the .env.example file
+ * @returns {Promise<Array<{varName: string, hasComment: boolean, comment: string|null, lineNumber: number}>>}
+ * @throws {Error} If file cannot be read (not found, permission denied, etc.)
+ */
+export async function parseEnvFile(filePath) {
+  let content;
+  
+  try {
+    content = await readFile(filePath, 'utf-8');
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new Error(`Environment file not found: ${filePath}`);
+    } else if (error.code === 'EACCES' || error.code === 'EPERM') {
+      throw new Error(`Permission denied reading file: ${filePath}`);
+    } else if (error.code === 'EISDIR') {
+      throw new Error(`Path is a directory, not a file: ${filePath}`);
+    } else {
+      throw new Error(`Error reading file ${filePath}: ${error.message}`);
+    }
+  }
+  
+  // Handle both Unix (\n) and Windows (\r\n) line endings
+  const lines = content.split(/\r?\n/);
+  const definitions = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    const lineNumber = i + 1;
+
+    // Skip empty lines and comment-only lines
+    const trimmed = line.trim();
+    if (trimmed === '' || trimmed.startsWith('#')) {
+      continue;
+    }
+
+    // Parse variable definition line
+    const definition = parseEnvLine(line, lineNumber);
+    if (definition) {
+      definitions.push(definition);
+    }
+  }
+
+  return definitions;
+}
+
+/**
+ * Parses a single line from a .env file.
+ * 
+ * @param {string} line - The line to parse
+ * @param {number} lineNumber - The line number (1-indexed)
+ * @returns {{varName: string, hasComment: boolean, comment: string|null, lineNumber: number}|null}
+ */
+export function parseEnvLine(line, lineNumber) {
+  // Match pattern: VAR_NAME=value # optional comment
+  // Variable names must start with letter or underscore, followed by letters, digits, or underscores
+  const match = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+
+  if (!match) {
+    // Malformed line - skip gracefully
+    return null;
+  }
+
+  const varName = match[1];
+  const remainder = match[2];
+
+  // Extract inline comment if present
+  const comment = extractComment(remainder);
+
+  return {
+    varName,
+    hasComment: comment !== null,
+    comment,
+    lineNumber
+  };
+}
+
+/**
+ * Extracts an inline comment from the value portion of an env line.
+ * 
+ * @param {string} value - The value portion after the = sign
+ * @returns {string|null} - The comment text (without # prefix) or null if no comment
+ */
+export function extractComment(value) {
+  // Find the first # that indicates a comment
+  // Note: This is a simple implementation that doesn't handle # inside quoted strings
+  const commentIndex = value.indexOf('#');
+
+  if (commentIndex === -1) {
+    return null;
+  }
+
+  // Extract and trim the comment text
+  const commentText = value.substring(commentIndex + 1).trim();
+
+  return commentText || null;
+}
+
+/**
+ * Validates if a line is a valid env variable definition.
+ * 
+ * @param {string} line - The line to validate
+ * @returns {boolean}
+ */
+export function isValidEnvLine(line) {
+  const trimmed = line.trim();
+
+  // Empty lines and comments are not valid env lines
+  if (trimmed === '' || trimmed.startsWith('#')) {
+    return false;
+  }
+
+  // Check if it matches the VAR_NAME=value pattern
+  return /^[A-Z_][A-Z0-9_]*=/.test(trimmed);
+}

package/src/plugins.js

@@ -0,0 +1,138 @@
+/**
+ * Plugin system for extensibility
+ * Allows users to add custom scanners, formatters, and validators
+ */
+
+import { existsSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Plugin manager
+ */
+export class PluginManager {
+  constructor() {
+    this.plugins = new Map();
+    this.hooks = new Map();
+  }
+
+  /**
+   * Register a plugin
+   */
+  register(name, plugin) {
+    if (this.plugins.has(name)) {
+      throw new Error(`Plugin ${name} is already registered`);
+    }
+
+    this.plugins.set(name, plugin);
+
+    // Initialize plugin
+    if (plugin.init) {
+      plugin.init(this);
+    }
+
+    return this;
+  }
+
+  /**
+   * Get a plugin by name
+   */
+  get(name) {
+    return this.plugins.get(name);
+  }
+
+  /**
+   * Check if a plugin is registered
+   */
+  has(name) {
+    return this.plugins.has(name);
+  }
+
+  /**
+   * Register a hook
+   */
+  hook(event, callback) {
+    if (!this.hooks.has(event)) {
+      this.hooks.set(event, []);
+    }
+
+    this.hooks.get(event).push(callback);
+    return this;
+  }
+
+  /**
+   * Trigger a hook
+   */
+  async trigger(event, data) {
+    const callbacks = this.hooks.get(event) || [];
+    
+    for (const callback of callbacks) {
+      try {
+        await callback(data);
+      } catch (error) {
+        console.warn(`Hook ${event} failed: ${error.message}`);
+      }
+    }
+  }
+
+  /**
+   * Load plugins from directory
+   */
+  async loadFromDirectory(dir) {
+    if (!existsSync(dir)) {
+      return;
+    }
+
+    try {
+      const { readdirSync } = await import('fs');
+      const files = readdirSync(dir);
+
+      for (const file of files) {
+        if (file.endsWith('.js')) {
+          const pluginPath = join(dir, file);
+          const plugin = await import(pluginPath);
+          const name = file.replace('.js', '');
+          
+          this.register(name, plugin.default || plugin);
+        }
+      }
+    } catch (error) {
+      console.warn(`Failed to load plugins from ${dir}: ${error.message}`);
+    }
+  }
+}
+
+/**
+ * Example plugin structure
+ */
+export const examplePlugin = {
+  name: 'example',
+  version: '1.0.0',
+  
+  init(manager) {
+    // Register hooks
+    manager.hook('beforeScan', async (data) => {
+      console.log('Before scan hook');
+    });
+
+    manager.hook('afterAnalysis', async (data) => {
+      console.log('After analysis hook');
+    });
+  },
+
+  // Custom scanner
+  scanner: {
+    extensions: ['.custom'],
+    scanLine(line, filePath, lineNumber) {
+      // Custom scanning logic
+      return [];
+    },
+  },
+
+  // Custom formatter
+  formatter: {
+    format(result, options) {
+      // Custom formatting logic
+      return '';
+    },
+  },
+};