envprobe 1.0.0

package/src/config.js

@@ -0,0 +1,118 @@
+/**
+ * Configuration file management
+ * Supports .envcheckrc, .envcheckrc.json, envcheck.config.js
+ */
+
+import { readFileSync, existsSync, writeFileSync } from 'fs';
+import { join } from 'path';
+
+/**
+ * Load configuration from file
+ */
+export function loadConfig(cwd = '.') {
+  const configFiles = [
+    '.envcheckrc',
+    '.envcheckrc.json',
+    'envcheck.config.json',
+    '.envcheckrc.js',
+    'envcheck.config.js',
+  ];
+
+  for (const file of configFiles) {
+    const configPath = join(cwd, file);
+    
+    if (existsSync(configPath)) {
+      try {
+        if (file.endsWith('.js')) {
+          // Dynamic import for JS config files
+          return loadJSConfig(configPath);
+        } else {
+          // JSON config
+          const content = readFileSync(configPath, 'utf-8');
+          return JSON.parse(content);
+        }
+      } catch (error) {
+        console.warn(`Warning: Failed to load config from ${file}: ${error.message}`);
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Load JavaScript config file
+ */
+async function loadJSConfig(configPath) {
+  try {
+    const module = await import(configPath);
+    return module.default || module;
+  } catch (error) {
+    throw new Error(`Failed to load JS config: ${error.message}`);
+  }
+}
+
+/**
+ * Save configuration to file
+ */
+export function saveConfig(config, cwd = '.', filename = '.envcheckrc.json') {
+  const configPath = join(cwd, filename);
+  
+  try {
+    const content = JSON.stringify(config, null, 2);
+    writeFileSync(configPath, content, 'utf-8');
+    return configPath;
+  } catch (error) {
+    throw new Error(`Failed to save config: ${error.message}`);
+  }
+}
+
+/**
+ * Merge CLI options with config file
+ */
+export function mergeConfig(cliOptions, fileConfig) {
+  if (!fileConfig) return cliOptions;
+
+  return {
+    ...fileConfig,
+    ...cliOptions,
+    // Merge arrays
+    ignore: [...(fileConfig.ignore || []), ...(cliOptions.ignore || [])],
+  };
+}
+
+/**
+ * Validate configuration
+ */
+export function validateConfig(config) {
+  const errors = [];
+
+  if (config.format && !['text', 'json', 'github'].includes(config.format)) {
+    errors.push(`Invalid format: ${config.format}`);
+  }
+
+  if (config.failOn && !['missing', 'unused', 'undocumented', 'all', 'none'].includes(config.failOn)) {
+    errors.push(`Invalid failOn: ${config.failOn}`);
+  }
+
+  if (config.ignore && !Array.isArray(config.ignore)) {
+    errors.push('ignore must be an array');
+  }
+
+  return errors;
+}
+
+/**
+ * Get default configuration
+ */
+export function getDefaultConfig() {
+  return {
+    path: '.',
+    envFile: '.env.example',
+    format: 'text',
+    failOn: 'none',
+    ignore: ['node_modules/**', 'dist/**', 'build/**', '.git/**'],
+    noColor: false,
+    quiet: false,
+  };
+}

package/src/formatters/github.js

@@ -0,0 +1,164 @@
+/**
+ * GitHub Actions Formatter Module
+ * 
+ * Formats analysis results as GitHub Actions workflow commands for CI/CD integration.
+ * Produces ::error and ::warning annotations that appear in GitHub's UI.
+ * 
+ * @see https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions
+ */
+
+/**
+ * Formats analysis results as GitHub Actions annotations
+ * 
+ * @param {Object} result - Analysis result from analyzer
+ * @param {Array} result.missing - Missing variable issues
+ * @param {Array} result.unused - Unused variable issues
+ * @param {Array} result.undocumented - Undocumented variable issues
+ * @param {Object} result.summary - Summary statistics
+ * @returns {string} GitHub Actions formatted output
+ */
+export function formatGitHub(result) {
+  const annotations = [];
+  
+  // Format missing variables as errors
+  for (const issue of result.missing) {
+    annotations.push(...formatMissingAnnotations(issue));
+  }
+  
+  // Format unused variables as warnings
+  for (const issue of result.unused) {
+    annotations.push(formatUnusedAnnotation(issue));
+  }
+  
+  // Format undocumented variables as warnings
+  for (const issue of result.undocumented) {
+    annotations.push(formatUndocumentedAnnotation(issue));
+  }
+  
+  // Add summary notice
+  annotations.push(formatSummaryNotice(result.summary));
+  
+  return annotations.join('\n');
+}
+
+/**
+ * Formats missing variable issue as GitHub error annotations
+ * Creates one error annotation per file reference
+ * 
+ * @param {Object} issue - Missing variable issue
+ * @param {string} issue.varName - Variable name
+ * @param {Array} issue.references - File references where variable is used
+ * @returns {Array<string>} Array of error annotations
+ */
+export function formatMissingAnnotations(issue) {
+  return issue.references.map(ref => {
+    const message = `Missing environment variable: ${issue.varName} is used but not defined in .env.example`;
+    return formatErrorAnnotation(ref.filePath, ref.lineNumber, message);
+  });
+}
+
+/**
+ * Formats unused variable issue as GitHub warning annotation
+ * 
+ * @param {Object} issue - Unused variable issue
+ * @param {string} issue.varName - Variable name
+ * @param {Object} issue.definition - Definition location
+ * @returns {string} Warning annotation
+ */
+export function formatUnusedAnnotation(issue) {
+  const message = `Unused environment variable: ${issue.varName} is defined in .env.example but never used`;
+  return formatWarningAnnotation('.env.example', issue.definition.lineNumber, message);
+}
+
+/**
+ * Formats undocumented variable issue as GitHub warning annotation
+ * 
+ * @param {Object} issue - Undocumented variable issue
+ * @param {string} issue.varName - Variable name
+ * @param {Object} issue.definition - Definition location
+ * @returns {string} Warning annotation
+ */
+export function formatUndocumentedAnnotation(issue) {
+  const message = `Undocumented environment variable: ${issue.varName} is missing a comment in .env.example`;
+  return formatWarningAnnotation('.env.example', issue.definition.lineNumber, message);
+}
+
+/**
+ * Formats summary as GitHub notice annotation
+ * 
+ * @param {Object} summary - Summary statistics
+ * @returns {string} Notice annotation
+ */
+export function formatSummaryNotice(summary) {
+  const parts = [];
+  
+  if (summary.totalMissing > 0) {
+    parts.push(`${summary.totalMissing} missing`);
+  }
+  
+  if (summary.totalUnused > 0) {
+    parts.push(`${summary.totalUnused} unused`);
+  }
+  
+  if (summary.totalUndocumented > 0) {
+    parts.push(`${summary.totalUndocumented} undocumented`);
+  }
+  
+  if (parts.length === 0) {
+    return '::notice::Environment check passed - no issues found';
+  }
+  
+  return `::notice::Environment check completed - ${parts.join(', ')}`;
+}
+
+/**
+ * Formats a GitHub Actions error annotation
+ * 
+ * @param {string} file - File path
+ * @param {number} line - Line number
+ * @param {string} message - Error message
+ * @returns {string} Formatted error annotation
+ */
+export function formatErrorAnnotation(file, line, message) {
+  return `::error file=${escapeProperty(file)},line=${line}::${escapeMessage(message)}`;
+}
+
+/**
+ * Formats a GitHub Actions warning annotation
+ * 
+ * @param {string} file - File path
+ * @param {number} line - Line number
+ * @param {string} message - Warning message
+ * @returns {string} Formatted warning annotation
+ */
+export function formatWarningAnnotation(file, line, message) {
+  return `::warning file=${escapeProperty(file)},line=${line}::${escapeMessage(message)}`;
+}
+
+/**
+ * Escapes special characters in annotation properties (file, line, col)
+ * 
+ * @param {string} value - Property value to escape
+ * @returns {string} Escaped value
+ */
+export function escapeProperty(value) {
+  return value
+    .replace(/%/g, '%25')
+    .replace(/\r/g, '%0D')
+    .replace(/\n/g, '%0A')
+    .replace(/:/g, '%3A')
+    .replace(/,/g, '%2C');
+}
+
+/**
+ * Escapes special characters in annotation messages
+ * 
+ * @param {string} message - Message to escape
+ * @returns {string} Escaped message
+ */
+export function escapeMessage(message) {
+  return message
+    .replace(/%/g, '%25')
+    .replace(/\r/g, '%0D')
+    .replace(/\n/g, '%0A');
+}

package/src/formatters/json.js

@@ -0,0 +1,114 @@
+/**
+ * JSON Formatter Module
+ * 
+ * Formats analysis results as valid JSON for machine parsing and CI/CD integration.
+ * Produces structured output with all issue categories and summary statistics.
+ */
+
+/**
+ * Formats analysis results as JSON
+ * 
+ * @param {Object} result - Analysis result from analyzer
+ * @param {Array} result.missing - Missing variable issues
+ * @param {Array} result.unused - Unused variable issues
+ * @param {Array} result.undocumented - Undocumented variable issues
+ * @param {Object} result.summary - Summary statistics
+ * @returns {string} JSON-formatted string
+ */
+export function formatJSON(result) {
+  const output = {
+    missing: formatMissingIssues(result.missing),
+    unused: formatUnusedIssues(result.unused),
+    undocumented: formatUndocumentedIssues(result.undocumented),
+    summary: formatSummary(result.summary)
+  };
+
+  return JSON.stringify(output, null, 2);
+}
+
+/**
+ * Formats missing variable issues for JSON output
+ * 
+ * @param {Array} missing - Array of missing variable issues
+ * @returns {Array} Formatted missing issues
+ */
+export function formatMissingIssues(missing) {
+  return missing.map(issue => ({
+    varName: issue.varName,
+    references: issue.references.map(ref => ({
+      filePath: ref.filePath,
+      lineNumber: ref.lineNumber,
+      pattern: ref.pattern
+    }))
+  }));
+}
+
+/**
+ * Formats unused variable issues for JSON output
+ * 
+ * @param {Array} unused - Array of unused variable issues
+ * @returns {Array} Formatted unused issues
+ */
+export function formatUnusedIssues(unused) {
+  return unused.map(issue => ({
+    varName: issue.varName,
+    definition: {
+      lineNumber: issue.definition.lineNumber,
+      hasComment: issue.definition.hasComment,
+      comment: issue.definition.comment
+    }
+  }));
+}
+
+/**
+ * Formats undocumented variable issues for JSON output
+ * 
+ * @param {Array} undocumented - Array of undocumented variable issues
+ * @returns {Array} Formatted undocumented issues
+ */
+export function formatUndocumentedIssues(undocumented) {
+  return undocumented.map(issue => ({
+    varName: issue.varName,
+    references: issue.references.map(ref => ({
+      filePath: ref.filePath,
+      lineNumber: ref.lineNumber,
+      pattern: ref.pattern
+    })),
+    definition: {
+      lineNumber: issue.definition.lineNumber,
+      hasComment: issue.definition.hasComment,
+      comment: issue.definition.comment
+    }
+  }));
+}
+
+/**
+ * Formats summary statistics for JSON output
+ * 
+ * @param {Object} summary - Summary statistics object
+ * @returns {Object} Formatted summary
+ */
+export function formatSummary(summary) {
+  return {
+    totalMissing: summary.totalMissing,
+    totalUnused: summary.totalUnused,
+    totalUndocumented: summary.totalUndocumented,
+    totalReferences: summary.totalReferences,
+    totalDefinitions: summary.totalDefinitions
+  };
+}
+
+/**
+ * Validates that a string is valid JSON
+ * 
+ * @param {string} jsonString - String to validate
+ * @returns {boolean} True if valid JSON, false otherwise
+ */
+export function isValidJSON(jsonString) {
+  try {
+    JSON.parse(jsonString);
+    return true;
+  } catch (error) {
+    return false;
+  }
+}

package/src/formatters/table.js

@@ -0,0 +1,92 @@
+/**
+ * Table formatter for better visual output
+ */
+
+/**
+ * Format data as a table
+ */
+export function formatTable(headers, rows, options = {}) {
+  const { maxWidth = 100, padding = 2 } = options;
+  
+  if (rows.length === 0) {
+    return '';
+  }
+
+  // Calculate column widths
+  const columnWidths = headers.map((header, i) => {
+    const headerWidth = header.length;
+    const maxRowWidth = Math.max(
+      ...rows.map(row => String(row[i] || '').length)
+    );
+    return Math.min(Math.max(headerWidth, maxRowWidth) + padding, maxWidth);
+  });
+
+  // Create separator
+  const separator = '─'.repeat(columnWidths.reduce((a, b) => a + b, 0) + columnWidths.length + 1);
+
+  // Format header
+  const headerRow = '│ ' + headers.map((header, i) => 
+    header.padEnd(columnWidths[i])
+  ).join('│ ') + '│';
+
+  // Format rows
+  const dataRows = rows.map(row => 
+    '│ ' + row.map((cell, i) => 
+      String(cell || '').padEnd(columnWidths[i])
+    ).join('│ ') + '│'
+  );
+
+  return [
+    '┌' + separator + '┐',
+    headerRow,
+    '├' + separator + '┤',
+    ...dataRows,
+    '└' + separator + '┘',
+  ].join('\n');
+}
+
+/**
+ * Format summary statistics
+ */
+export function formatSummary(result) {
+  const total = result.missing.length + result.unused.length + result.undocumented.length;
+  
+  const stats = [
+    ['Category', 'Count', 'Status'],
+    ['Missing', result.missing.length, result.missing.length > 0 ? '❌' : '✅'],
+    ['Unused', result.unused.length, result.unused.length > 0 ? '⚠️' : '✅'],
+    ['Undocumented', result.undocumented.length, result.undocumented.length > 0 ? 'ℹ️' : '✅'],
+    ['Total Issues', total, total > 0 ? '⚠️' : '✅'],
+  ];
+
+  return formatTable(stats[0], stats.slice(1));
+}
+
+/**
+ * Format issues as a tree structure
+ */
+export function formatTree(issues, title) {
+  if (issues.length === 0) {
+    return '';
+  }
+
+  const lines = [`\n${title}:`];
+  
+  issues.forEach((issue, index) => {
+    const isLast = index === issues.length - 1;
+    const prefix = isLast ? '└─' : '├─';
+    const childPrefix = isLast ? '  ' : '│ ';
+    
+    lines.push(`${prefix} ${issue.varName}`);
+    
+    if (issue.locations) {
+      issue.locations.forEach((loc, locIndex) => {
+        const isLastLoc = locIndex === issue.locations.length - 1;
+        const locPrefix = isLastLoc ? '└─' : '├─';
+        lines.push(`${childPrefix}${locPrefix} ${loc.filePath}:${loc.lineNumber}`);
+      });
+    }
+  });
+
+  return lines.join('\n');
+}

package/src/formatters/text.js

@@ -0,0 +1,198 @@
+/**
+ * Text Formatter Module
+ * 
+ * Formats analysis results as human-readable text output with:
+ * - Colored categories (red, yellow, green)
+ * - Emoji icons for visual clarity
+ * - File reference listings with line numbers
+ * - Summary statistics
+ * - Support for --no-color flag
+ */
+
+/**
+ * ANSI color codes for terminal output
+ */
+const COLORS = {
+  RED: '\x1b[31m',
+  YELLOW: '\x1b[33m',
+  GREEN: '\x1b[32m',
+  RESET: '\x1b[0m',
+  BOLD: '\x1b[1m',
+  DIM: '\x1b[2m'
+};
+
+/**
+ * Emoji icons for issue categories
+ */
+const ICONS = {
+  MISSING: '🔴',
+  UNUSED: '🟡',
+  UNDOCUMENTED: '🟢'
+};
+
+/**
+ * Formats analysis results as colored text output
+ * 
+ * @param {{missing: Array, unused: Array, undocumented: Array, summary: Object}} result - Analysis result
+ * @param {{noColor: boolean, quiet: boolean}} options - Formatting options
+ * @returns {string} Formatted text output
+ */
+export function formatText(result, options = {}) {
+  const { noColor = false, quiet = false } = options;
+  
+  // If quiet mode and no issues, return empty string
+  if (quiet && hasNoIssues(result)) {
+    return '';
+  }
+  
+  const sections = [];
+  
+  // Format MISSING section
+  if (result.missing.length > 0) {
+    sections.push(formatMissingSection(result.missing, noColor));
+  }
+  
+  // Format UNUSED section
+  if (result.unused.length > 0) {
+    sections.push(formatUnusedSection(result.unused, noColor));
+  }
+  
+  // Format UNDOCUMENTED section
+  if (result.undocumented.length > 0) {
+    sections.push(formatUndocumentedSection(result.undocumented, noColor));
+  }
+  
+  // Add summary line
+  sections.push(formatSummary(result.summary, noColor));
+  
+  return sections.join('\n\n');
+}
+
+/**
+ * Checks if analysis result has no issues
+ * 
+ * @param {{missing: Array, unused: Array, undocumented: Array}} result
+ * @returns {boolean} True if no issues found
+ */
+export function hasNoIssues(result) {
+  return result.missing.length === 0 && 
+         result.unused.length === 0 && 
+         result.undocumented.length === 0;
+}
+
+/**
+ * Formats MISSING variables section
+ * 
+ * @param {Array<{varName: string, references: Array}>} missing - Missing variable issues
+ * @param {boolean} noColor - Disable colored output
+ * @returns {string} Formatted section
+ */
+export function formatMissingSection(missing, noColor) {
+  const icon = ICONS.MISSING;
+  const title = colorize('MISSING', COLORS.RED, noColor);
+  const count = missing.length;
+  
+  let output = `${icon} ${title} (${count})\n`;
+  output += 'Variables used in code but not in .env.example:\n';
+  
+  for (const issue of missing) {
+    output += `  - ${colorize(issue.varName, COLORS.BOLD, noColor)}\n`;
+    
+    // List all file references
+    for (const ref of issue.references) {
+      output += `    ${colorize('→', COLORS.DIM, noColor)} ${ref.filePath}:${ref.lineNumber}\n`;
+    }
+  }
+  
+  return output.trimEnd();
+}
+
+/**
+ * Formats UNUSED variables section
+ * 
+ * @param {Array<{varName: string, definition: Object}>} unused - Unused variable issues
+ * @param {boolean} noColor - Disable colored output
+ * @returns {string} Formatted section
+ */
+export function formatUnusedSection(unused, noColor) {
+  const icon = ICONS.UNUSED;
+  const title = colorize('UNUSED', COLORS.YELLOW, noColor);
+  const count = unused.length;
+  
+  let output = `${icon} ${title} (${count})\n`;
+  output += 'Variables in .env.example but never used:\n';
+  
+  for (const issue of unused) {
+    output += `  - ${colorize(issue.varName, COLORS.BOLD, noColor)}`;
+    output += ` ${colorize(`(.env.example:${issue.definition.lineNumber})`, COLORS.DIM, noColor)}\n`;
+  }
+  
+  return output.trimEnd();
+}
+
+/**
+ * Formats UNDOCUMENTED variables section
+ * 
+ * @param {Array<{varName: string, references: Array, definition: Object}>} undocumented - Undocumented variable issues
+ * @param {boolean} noColor - Disable colored output
+ * @returns {string} Formatted section
+ */
+export function formatUndocumentedSection(undocumented, noColor) {
+  const icon = ICONS.UNDOCUMENTED;
+  const title = colorize('UNDOCUMENTED', COLORS.GREEN, noColor);
+  const count = undocumented.length;
+  
+  let output = `${icon} ${title} (${count})\n`;
+  output += 'Variables used and defined but missing comments:\n';
+  
+  for (const issue of undocumented) {
+    output += `  - ${colorize(issue.varName, COLORS.BOLD, noColor)}`;
+    output += ` ${colorize(`(.env.example:${issue.definition.lineNumber})`, COLORS.DIM, noColor)}\n`;
+  }
+  
+  return output.trimEnd();
+}
+
+/**
+ * Formats summary statistics line
+ * 
+ * @param {{totalMissing: number, totalUnused: number, totalUndocumented: number}} summary - Summary statistics
+ * @param {boolean} noColor - Disable colored output
+ * @returns {string} Formatted summary
+ */
+export function formatSummary(summary, noColor) {
+  const parts = [];
+  
+  if (summary.totalMissing > 0) {
+    parts.push(colorize(`${summary.totalMissing} missing`, COLORS.RED, noColor));
+  }
+  
+  if (summary.totalUnused > 0) {
+    parts.push(colorize(`${summary.totalUnused} unused`, COLORS.YELLOW, noColor));
+  }
+  
+  if (summary.totalUndocumented > 0) {
+    parts.push(colorize(`${summary.totalUndocumented} undocumented`, COLORS.GREEN, noColor));
+  }
+  
+  if (parts.length === 0) {
+    return colorize('✓ No issues found', COLORS.GREEN, noColor);
+  }
+  
+  return `Summary: ${parts.join(', ')}`;
+}
+
+/**
+ * Applies ANSI color codes to text
+ * 
+ * @param {string} text - Text to colorize
+ * @param {string} color - ANSI color code
+ * @param {boolean} noColor - Disable colored output
+ * @returns {string} Colorized text or plain text if noColor is true
+ */
+export function colorize(text, color, noColor) {
+  if (noColor) {
+    return text;
+  }
+  return `${color}${text}${COLORS.RESET}`;
+}