env_check 0.1.0

data/bin/console

@@ -0,0 +1,44 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "bundler/setup"
+require "env_check"
+
+# Load development environment if available
+if File.exist?(".env")
+  require "dotenv"
+  Dotenv.load
+end
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+puts "🔍 EnvCheck Console v#{EnvCheck::VERSION}"
+puts "Available methods:"
+puts "  EnvCheck.verify         # Verify default config"
+puts "  EnvCheck.verify!        # Verify with exception on failure"
+puts "  EnvCheck.verify(file)   # Verify custom config file"
+puts ""
+
+# Set up some useful variables for console testing
+config_path = EnvCheck::Config.discover_config_path
+if File.exist?(config_path)
+  puts "📁 Found #{config_path}"
+  config_result = begin
+    EnvCheck.verify
+  rescue StandardError
+    nil
+  end
+  if config_result
+    puts "✅ Config loaded successfully"
+  else
+    puts "⚠️  Config has issues"
+  end
+else
+  puts "📝 No config file found. Run EnvCheck init first."
+end
+
+puts ""
+
+require "irb"
+IRB.start(__FILE__)

data/bin/env_check

@@ -0,0 +1,265 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# bin/env_check - CLI for EnvCheck gem
+
+require "optparse"
+require "fileutils"
+require_relative "../lib/env_check"
+
+# Module for CLI output helpers
+module CLIHelpers
+  def success(message)
+    puts message unless @options[:quiet]
+  end
+
+  def info(message)
+    puts message unless @options[:quiet]
+  end
+
+  def warning(message)
+    puts "⚠️  #{message}" unless @options[:quiet]
+  end
+
+  def error(message)
+    warn message
+  end
+
+  def error_exit(message, code = 1)
+    warn "Error: #{message}"
+    exit code
+  end
+
+  def default_config_path
+    Dir.exist?("config") ? "config/env_check.yml" : ".env_check.yml"
+  end
+end
+
+# CLI class for better organization
+class EnvCheckCLI
+  include CLIHelpers
+  def initialize(args = ARGV)
+    @args = args
+    @options = {
+      config: nil, # Will be auto-discovered if not specified
+      quiet: false,
+      verbose: false
+    }
+    @command = nil
+  end
+
+  def run
+    parse_arguments
+    execute_command
+  rescue StandardError => e
+    error_exit(e.message.to_s)
+  end
+
+  private
+
+  def parse_arguments
+    parser = create_option_parser
+    parser.parse!(@args)
+    @command = @args.shift
+  end
+
+  def create_option_parser
+    OptionParser.new do |opts|
+      configure_banner_and_commands(opts)
+      configure_options(opts)
+    end
+  end
+
+  def configure_banner_and_commands(opts)
+    opts.banner = "Usage: env_check [options] <command>"
+    opts.separator ""
+    opts.separator "Commands:"
+    opts.separator "  init     Create a new env_check.yml configuration file"
+    opts.separator "  check    Validate environment variables against configuration"
+    opts.separator "  version  Show version number"
+    opts.separator ""
+    opts.separator "Options:"
+  end
+
+  def configure_options(opts)
+    opts.on("-c", "--config PATH",
+            "Configuration file path (auto-discovered: .env_check.yml or config/env_check.yml)") do |path|
+      @options[:config] = path
+    end
+
+    opts.on("-q", "--quiet", "Suppress output (only show errors)") do
+      @options[:quiet] = true
+    end
+
+    opts.on("-v", "--verbose", "Show detailed output") do
+      @options[:verbose] = true
+    end
+
+    opts.on("-h", "--help", "Show this help message") do
+      puts opts
+      exit 0
+    end
+  end
+
+  def execute_command
+    case @command
+    when "init"
+      init_command
+    when "check"
+      check_command
+    when "version"
+      version_command
+    when nil
+      show_help_and_exit
+    else
+      error_exit("Unknown command: #{@command}")
+    end
+  end
+
+  def init_command
+    path = @options[:config] || determine_init_path
+
+    begin
+      # Create directory if it doesn't exist
+      dir = File.dirname(path)
+      FileUtils.mkdir_p(dir) unless dir == "."
+
+      if File.exist?(path)
+        warning("Configuration file already exists: #{path}")
+        return
+      end
+
+      create_config_file(path)
+      success("Created configuration file: #{path}")
+
+      unless @options[:quiet]
+        puts "\nNext steps:"
+        puts "1. Edit #{path} to define your required environment variables"
+        puts "2. Run 'env_check check' to validate your environment"
+      end
+    rescue StandardError => e
+      error_exit("Failed to create configuration file: #{e.message}")
+    end
+  end
+
+  def check_command
+    path = @options[:config] || EnvCheck::Config.discover_config_path
+    validate_config_exists(path)
+
+    info("Checking environment variables using: #{path}") if @options[:verbose]
+
+    result = perform_validation(path)
+    handle_validation_result(result)
+  end
+
+  def validate_config_exists(path)
+    return if File.exist?(path)
+
+    error_exit("Configuration file not found: #{path}. Run 'env_check init' first.")
+  end
+
+  def perform_validation(path)
+    EnvCheck.verify(path)
+  rescue EnvCheck::Error => e
+    error_exit("Validation failed: #{e.message}")
+  rescue StandardError => e
+    error_exit("Unexpected error: #{e.message}")
+  end
+
+  def handle_validation_result(result)
+    if result.success?
+      handle_success_result(result)
+    else
+      handle_failure_result(result)
+    end
+  end
+
+  def handle_success_result(result)
+    success("✅ All environment variables are valid!")
+
+    if @options[:verbose] && !result.valid_vars.empty?
+      puts "\nValid variables:"
+      result.valid_vars.each { |var| puts "  ✅ #{var}" }
+    end
+
+    display_warnings(result.warnings) unless result.warnings.empty?
+  end
+
+  def handle_failure_result(result)
+    error("❌ Environment validation failed!")
+
+    display_errors(result.errors) unless result.errors.empty?
+    display_warnings(result.warnings) unless result.warnings.empty?
+
+    exit 1
+  end
+
+  def display_errors(errors)
+    puts "\nErrors:"
+    errors.each { |error| puts "  ❌ #{error}" }
+  end
+
+  def display_warnings(warnings)
+    puts "\nWarnings:"
+    warnings.each { |warning| puts "  ⚠️  #{warning}" }
+  end
+
+  def version_command
+    puts EnvCheck::VERSION
+  end
+
+  def create_config_file(path)
+    File.write(path, config_template)
+  end
+
+  def config_template
+    <<~YAML
+      # EnvCheck Configuration
+      # Configure required and optional environment variables for your application
+
+      # Required environment variables (must be present and non-empty)
+      required:
+        - DATABASE_URL
+        - SECRET_KEY_BASE
+
+      # Optional environment variables with type validation
+      optional:
+        DEBUG: boolean          # true, false, 1, 0, yes, no, on, off (case-insensitive)
+        PORT: port             # valid port number (1-65535)
+        API_URL: url           # must start with http:// or https://
+        ADMIN_EMAIL: email     # valid email format
+        LOG_LEVEL: string      # any string value
+        RATE_LIMIT: float      # floating point number
+        CONFIG_PATH: path      # file or directory path
+        SETTINGS: json         # valid JSON string
+      #{"  "}
+      # You can also configure per-environment settings:
+      # development:
+      #   required:
+      #     - DATABASE_URL
+      #   optional:
+      #     DEBUG: boolean
+      ##{" "}
+      # production:
+      #   required:
+      #     - DATABASE_URL
+      #     - SECRET_KEY_BASE
+      #     - RAILS_MASTER_KEY
+      #   optional:
+      #     REDIS_URL: url
+    YAML
+  end
+
+  def show_help_and_exit
+    puts create_option_parser.help
+    exit 1
+  end
+
+  # Determine the best path for init command
+  def determine_init_path
+    default_config_path
+  end
+end
+
+# Run the CLI
+EnvCheckCLI.new.run if __FILE__ == $PROGRAM_NAME

data/bin/setup

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+echo "🔧 Setting up env_check development environment..."
+
+# Install dependencies
+bundle install
+
+# Run any other automated setup that you need to do here
+echo "✅ Running initial tests to verify setup..."
+bundle exec rspec --format documentation
+
+echo "🎯 Running RuboCop to check code style..."
+bundle exec rubocop
+
+echo ""
+echo "🎉 Setup complete!"
+echo ""
+echo "Available commands:"
+echo "  ./bin/console     # Start interactive console"
+echo "  ./bin/env_check   # Run CLI tool"
+echo "  bundle exec rspec # Run tests"
+echo "  bundle exec rubocop # Check code style"
+echo ""

data/lib/env_check/config.rb

@@ -0,0 +1,85 @@
+# frozen_string_literal: true
+
+module EnvCheck
+  # Configuration management for EnvCheck
+  class Config
+    # Priority order for auto-discovery
+    DEFAULT_PATHS = [
+      ".env_check.yml",        # Root level (simple/tool-focused projects)
+      "config/env_check.yml"   # Rails convention (if config/ exists)
+    ].freeze
+
+    attr_reader :required_vars, :optional_vars, :config_path
+
+    def initialize(config_path = nil, environment = nil)
+      @config_path = config_path || ENV["ENV_CHECK_CONFIG"] || discover_config_path
+      @environment = environment || ENV["RAILS_ENV"] || ENV["RACK_ENV"] || "development"
+      load_config
+    end
+
+    def self.from_hash(config_hash)
+      instance = allocate
+      instance.instance_variable_set(:@required_vars, config_hash["required"] || [])
+      instance.instance_variable_set(:@optional_vars,
+                                     instance.send(:normalize_optional_vars, config_hash["optional"] || {}))
+      instance.instance_variable_set(:@config_path, "inline")
+      instance
+    end
+
+    def valid?
+      File.exist?(@config_path)
+    end
+
+    # Discover config file using priority order
+    def self.discover_config_path
+      DEFAULT_PATHS.find { |path| File.exist?(path) } || DEFAULT_PATHS.first
+    end
+
+    private
+
+    def discover_config_path
+      self.class.discover_config_path
+    end
+
+    def load_config
+      if File.exist?(@config_path)
+        config = YAML.load_file(@config_path)
+
+        # Support environment-specific configurations
+        env_config = config[@environment] || config
+
+        @required_vars = env_config["required"] || []
+
+        # Handle optional vars - support both hash and array formats
+        optional_config = env_config["optional"] || {}
+        @optional_vars = normalize_optional_vars(optional_config)
+      else
+        @required_vars = []
+        @optional_vars = {}
+      end
+    end
+
+    # Normalize optional vars to support both hash and array formats
+    # Hash format: { "VAR" => "type" }
+    # Array format: [{ "VAR" => "type" }, "SIMPLE_VAR"]
+    def normalize_optional_vars(optional_config)
+      case optional_config
+      when Hash
+        optional_config
+      when Array
+        result = {}
+        optional_config.each do |item|
+          case item
+          when Hash
+            result.merge!(item)
+          when String
+            result[item] = nil
+          end
+        end
+        result
+      else
+        {}
+      end
+    end
+  end
+end

data/lib/env_check/rake_task.rb

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+# lib/env_check/rake_task.rb
+require "rake"
+require_relative "../env_check"
+
+namespace :env do
+  desc "Check environment variable configuration"
+  task :check do
+    EnvCheck.verify!
+  end
+end

data/lib/env_check/validators.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+module EnvCheck
+  # Custom validator classes for different environment variable types
+  module Validators
+    class Base
+      def self.valid?(value)
+        raise NotImplementedError, "Subclasses must implement #valid?"
+      end
+    end
+
+    class Boolean < Base
+      VALID_VALUES = %w[true false 1 0 yes no on off].freeze
+
+      def self.valid?(value)
+        return false if value.nil? || value.strip.empty?
+
+        VALID_VALUES.include?(value.strip.downcase)
+      end
+    end
+
+    class Integer < Base
+      def self.valid?(value)
+        return false if value.nil? || value.strip.empty?
+
+        value.strip.match?(/\A-?\d+\z/)
+      end
+    end
+
+    class Float < Base
+      def self.valid?(value)
+        return false if value.nil? || value.strip.empty?
+
+        begin
+          Float(value.strip)
+          true
+        rescue ArgumentError
+          false
+        end
+      end
+    end
+
+    class Url < Base
+      def self.valid?(value)
+        return false if value.nil? || value.strip.empty?
+
+        value.strip.match?(%r{\Ahttps?://\S+\z})
+      end
+    end
+
+    class Email < Base
+      def self.valid?(value)
+        return false if value.nil? || value.strip.empty?
+
+        value.strip.match?(/\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i)
+      end
+    end
+
+    class Path < Base
+      def self.valid?(value)
+        return false if value.nil? || value.strip.empty?
+
+        # Basic path validation - should not contain null bytes and be reasonable length
+        path = value.strip
+        !path.include?("\0") && path.length.positive? && path.length < 1000
+      end
+    end
+
+    class Port < Base
+      def self.valid?(value)
+        return false if value.nil? || value.strip.empty?
+
+        port = value.strip.to_i
+        port.positive? && port <= 65_535
+      end
+    end
+
+    class Enum < Base
+      def self.valid?(value, allowed_values = [])
+        return false if value.nil? || value.strip.empty?
+        return false if allowed_values.empty?
+
+        allowed_values.include?(value.strip)
+      end
+    end
+
+    class JsonString < Base
+      def self.valid?(value)
+        return false if value.nil? || value.strip.empty?
+
+        begin
+          require "json"
+          JSON.parse(value.strip)
+          true
+        rescue JSON::ParserError
+          false
+        end
+      end
+    end
+  end
+end

data/lib/env_check/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module EnvCheck
+  VERSION = "0.1.0"
+end

data/lib/env_check.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+# EnvCheck is a Ruby gem to validate presence and format of environment variables
+# before your application boots or runs. Supports YAML configuration and type checking.
+#
+# Features:
+# - Checks for required and optional environment variables
+# - Validates types: boolean, integer, url, string (default)
+# - Supports config via `ENV["ENV_CHECK_CONFIG"]`
+# - Auto-loads `.env` file if present
+
+require "yaml"
+
+# Load version and rake task
+require_relative "env_check/version"
+require_relative "env_check/config"
+require_relative "env_check/validators"
+require_relative "env_check/rake_task" if defined?(Rake)
+
+# Load .env automatically (if present)
+if File.exist?(".env")
+  begin
+    require "dotenv"
+    Dotenv.load
+  rescue LoadError
+    warn "🔍 dotenv not installed — skipping .env loading"
+  end
+end
+
+# EnvCheck provides validation for environment variables using a YAML config file.
+module EnvCheck
+  class Error < StandardError; end
+
+  class Result
+    attr_reader :errors, :warnings, :valid_vars
+
+    def initialize
+      @errors = []
+      @warnings = []
+      @valid_vars = []
+    end
+
+    def add_error(message)
+      @errors << message
+    end
+
+    def add_warning(message)
+      @warnings << message
+    end
+
+    def add_valid(var_name)
+      @valid_vars << var_name
+    end
+
+    def success?
+      @errors.empty?
+    end
+
+    def display_results
+      @valid_vars.each { |var| puts "✅ #{var} is set" }
+      @errors.each { |error| puts "❌ #{error}" }
+      @warnings.each { |warning| puts "⚠️  #{warning}" }
+    end
+  end
+
+  # Verifies environment variables against a YAML config file.
+  #
+  # @param config_path [String] path to the config file (auto-discovered: .env_check.yml or config/env_check.yml)
+  # @param environment [String] environment to use for environment-specific configuration
+  # @return [Result] validation result object
+  def self.verify(config_path = nil, environment = nil)
+    config = Config.new(config_path, environment)
+    result = Result.new
+
+    unless config.valid?
+      puts "⚠️  Config file not found: #{config.config_path}"
+      return result
+    end
+
+    validate_required_vars(config.required_vars, result)
+    validate_optional_vars(config.optional_vars, result)
+
+    result.display_results
+    result
+  end
+
+  # Verify with inline configuration (useful for testing or programmatic use)
+  def self.verify_with_config(config_hash)
+    config = Config.from_hash(config_hash)
+    result = Result.new
+
+    validate_required_vars(config.required_vars, result)
+    validate_optional_vars(config.optional_vars, result)
+
+    result.display_results
+    result
+  end
+
+  # Legacy method for backward compatibility - raises on error
+  def self.verify!(config_path = nil, environment = nil)
+    result = verify(config_path, environment)
+    raise Error, "Environment validation failed" unless result.success?
+
+    result
+  end
+
+  private_class_method def self.validate_required_vars(required_vars, result)
+    required_vars.each do |var|
+      if ENV[var].nil? || ENV[var].strip.empty?
+        result.add_error("Missing required ENV: #{var}")
+      else
+        result.add_valid(var)
+      end
+    end
+  end
+
+  private_class_method def self.validate_optional_vars(optional_vars, result)
+    optional_vars.each do |var, type|
+      value = ENV.fetch(var, nil)
+      next unless value
+
+      if valid_type?(value, type)
+        result.add_valid(var)
+      else
+        result.add_warning("#{var} should be a #{type}, got '#{value}'")
+      end
+    end
+  end
+
+  private_class_method def self.valid_type?(value, type)
+    case type.to_s.downcase
+    when "boolean"
+      Validators::Boolean.valid?(value)
+    when "integer"
+      Validators::Integer.valid?(value)
+    when "float"
+      Validators::Float.valid?(value)
+    when "url"
+      Validators::Url.valid?(value)
+    when "email"
+      Validators::Email.valid?(value)
+    when "path"
+      Validators::Path.valid?(value)
+    when "port"
+      Validators::Port.valid?(value)
+    when "json"
+      Validators::JsonString.valid?(value)
+    else
+      true # Default to valid for unknown types
+    end
+  end
+end

data/lib/tasks/env_check.rake

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+# lib/tasks/env_check.rake
+
+require_relative "../../lib/env_check"
+if File.exist?(".env")
+  require "dotenv"
+  Dotenv.load
+end
+
+namespace :env do
+  desc "Check environment variable configuration"
+  task :check do
+    EnvCheck.verify!
+  end
+end