env_check 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 76261979114cfd50eff2593a9d62633313d2f4e2e3c01bb891768f3b7c535cf1
+  data.tar.gz: 2517760bfbc532e75c0508de1c12cc4a1ed382cfaa27758cfa9f4f0c36dc86e8
+SHA512:
+  metadata.gz: 34d26caaacf2100c9389c94a87ebc17b332001fc705f7051adb752b96920178f68c2e873ff401bf50045daf48b9e67df508d0c92a3f4ad7137e976c6a25b83e4
+  data.tar.gz: 13c03e66845d8afe48d1e62c400b35d89b25a6f01ce2f8b62c701a6359f91c19deceae59ebdef84e07bd8e2efc42204faa87238699e68fdbfbb9a06fd7a1a073

data/.env_check.yml

@@ -0,0 +1,15 @@
+# EnvCheck Configuration (Root Level)
+# 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 (case-insensitive)
+  PORT: integer          # numeric values only
+  API_URL: url           # must start with http:// or https://
+  ADMIN_EMAIL: email     # valid email format
+  LOG_LEVEL: string      # any string value

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,41 @@
+AllCops:
+  TargetRubyVersion: 3.0
+  NewCops: enable
+  SuggestExtensions: false
+
+Metrics/AbcSize:
+  Max: 20
+
+Metrics/MethodLength:
+  Max: 20
+
+Metrics/CyclomaticComplexity:
+  Max: 10
+
+Metrics/PerceivedComplexity:
+  Max: 10
+
+Metrics/ClassLength:
+  Max: 100
+  Exclude:
+    - "bin/*"  # CLI classes can be longer
+
+Metrics/BlockLength:
+  Exclude:
+    - "spec/**/*"
+    - "*.gemspec"
+
+Layout/LineLength:
+  Max: 120
+
+Style/Documentation:
+  Enabled: false
+
+Gemspec/DevelopmentDependencies:
+  Enabled: false
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes

data/.ruby-version

@@ -0,0 +1 @@
+3.4.5

data/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+This project adheres to [Semantic Versioning](https://semver.org).
+
+---
+
+## [0.1.0] - 2025-01-29
+
+### Added
+
+- ✨ **Smart Config Discovery** - Auto-detects `.env_check.yml` (root) or `config/env_check.yml` (Rails)
+- ✨ **Enhanced Validator Suite** - Comprehensive validation types:
+  - `boolean` - Validates boolean values including `true/false`, `1/0`, `yes/no`, `on/off` 
+  - `integer` - Validates integer numbers (including negative)
+  - `float` - Validates floating point numbers
+  - `string` - Validates any string value
+  - `url` - Validates URLs starting with `http://` or `https://`
+  - `email` - Validates email format
+  - `port` - Validates port numbers (1-65535)
+  - `path` - Validates file/directory paths
+  - `json` - Validates JSON strings
+- 🎯 **Result Object** - `EnvCheck.verify` returns a `Result` object with `success?`, `errors`, `warnings`, and `valid_vars` properties
+- � **Enhanced CLI** with `check`, `version`, and `init` commands with professional UX
+- 🏗️ **Environment-specific Configuration** - Support for development, test, production sections
+- 🧪 **Comprehensive Test Suite** - 21 test cases covering all functionality
+- � **Flexible YAML Configuration** - Supports both hash and array formats for optional variables
+- 📝 **Rake Task Integration** - `rake env:check` for CI usage
+- 📖 **Comprehensive Documentation** and examples
+
+### Features
+
+- **Smart Configuration Discovery**: Prioritizes `.env_check.yml` (simple projects) over `config/env_check.yml` (Rails)
+- **Type Validation**: Robust validation with helpful error messages for all supported types
+- **Environment-specific Settings**: Different validation rules for development, test, and production
+- **Flexible YAML Formats**: Supports both `optional: { VAR: type }` and `optional: [{ VAR: type }]` formats
+- **CLI Tools**: Professional command-line interface for initialization and validation
+- **Rails Integration**: Seamless integration with Rails 7.1+ applications
+- **Dotenv Support**: Automatic `.env` file loading when available
+- **Null/Empty Handling**: Graceful handling of missing and empty environment variables
+
+### Technical Implementation
+
+- **Modular Architecture**: Separate `Config`, `Validators`, and `Result` classes
+- **Error Handling**: Structured result objects with detailed error reporting
+- **Code Quality**: Zero RuboCop offenses, comprehensive test coverage
+- **Thread-safe**: Safe for concurrent usage
+- **Framework Agnostic**: Works with any Ruby application, optimized for Rails
+
+### Compatibility
+
+- **Ruby**: 3.0+
+- **Rails**: 7.1+ through 8.0+ (framework-agnostic design)
+- **CI/CD**: Comprehensive GitHub Actions integration
+
+---

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+[INSERT CONTACT METHOD].
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Mohammad Nadeem
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/RAILS_COMPATIBILITY.md

@@ -0,0 +1,36 @@
+## Rails Version Support Summary
+
+Based on the Rails upgrade guide analysis and Ruby version compatibility, this gem supports:
+
+### Currently Supported Rails Versions
+
+| Rails Version | Ruby Requirement | env_check Support | Status |
+|---------------|------------------|-------------------|---------|
+| **Rails 8.0** | Ruby 3.0+ | ✅ Full | Latest |
+| **Rails 7.2** | Ruby 3.0+ | ✅ Full | LTS |
+| **Rails 7.1** | Ruby 3.0+ | ✅ Full | Maintenance |
+
+### Why This Gem Works Across Rails Versions
+
+1. **Framework Agnostic**: env_check doesn't depend on Rails directly
+2. **Pure Ruby**: Uses only standard Ruby libraries (YAML, ENV)
+3. **Simple API**: No reliance on Rails-specific methods or constants
+4. **Minimal Dependencies**: Only depends on dotenv and yaml gems
+
+### Rails Integration Features
+
+- **Rake Tasks**: Works with all Rails versions that support custom Rake tasks
+- **Initializers**: Compatible with Rails initialization process
+- **Environment Variables**: Follows Rails conventions for env var naming
+- **Configuration**: YAML configuration files work identically across versions
+
+### Testing Matrix
+
+The gem is automatically tested against:
+- Ruby 3.0, 3.1, 3.2, 3.3, 3.4  
+- Rails 7.1, 7.2, 8.0 (in CI)
+- Ubuntu, macOS, Windows platforms
+
+### Migration Notes
+
+When upgrading Rails versions, env_check configurations remain compatible. The gem follows semantic versioning and maintains backward compatibility.

data/README.md

@@ -0,0 +1,384 @@
+# 🔍 EnvCheck
+
+[![Ruby](https://img.shields.io/badge/ruby-%3E%3D%203.0-red.svg)](https://ruby-lang.org)
+[![Gem Version](https://badge.fury.io/rb/env_check.svg)](https://badge.fury.io/rb/env_check)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+`env_check` is a lightweight Ruby gem to validate and document your environment variables.  
+It ensures critical env vars are present and properly formatted before your app boots or deploys.
+
+---
+
+## 🚀 Features
+
+- ✅ Validate required environment variables
+- ⚠️ Warn on missing or invalid optional variables
+- 🔒 Type checking (boolean, integer, URL, email)
+- 📁 YAML-based configuration
+- 🔧 Works with any Ruby or Rails app
+- 🌱 Supports `.env` file via `dotenv` (optional)
+- 🎯 Programmatic API for custom integrations
+- 📊 Detailed validation results
+
+---
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'env_check'
+```
+
+And then execute:
+
+    $ bundle install
+
+## Ruby and Rails Compatibility
+
+### Ruby Version Support
+- **Ruby 3.0+** - Fully supported
+- **Ruby 3.1+** - Fully supported  
+- **Ruby 3.2+** - Fully supported
+- **Ruby 3.3+** - Fully supported
+- **Ruby 3.4+** - Fully supported
+
+### Rails Version Support
+
+This gem is framework-agnostic and works with any Ruby application. For Rails applications, it supports:
+
+| Rails Version | Ruby Version | Support Status |
+|---------------|--------------|----------------|
+| Rails 8.0+    | Ruby 3.2+    | ✅ Supported   |
+| Rails 7.2+    | Ruby 3.1+    | ✅ Supported   |
+| Rails 7.1+    | Ruby 3.1+    | ✅ Supported   |
+| Rails 7.0+    | Ruby 2.7+    | ✅ Supported   |
+| Rails 6.1+    | Ruby 2.5+    | ✅ Supported   |
+| Rails 6.0+    | Ruby 2.5+    | ✅ Supported   |
+| Rails 5.x     | Ruby 2.2+    | ⚠️ Should work but not actively tested |
+
+**Note**: While the gem doesn't directly depend on Rails, it's been designed to work seamlessly in Rails environments and integrates well with Rails' environment variable patterns.
+
+Or install manually:
+```bash
+gem install env_check
+```
+
+---
+
+## ⚡ Quick Start
+
+### 1. Generate Configuration
+
+```bash
+env_check init
+```
+
+This creates a configuration file using smart defaults:
+- **Simple projects**: `.env_check.yml` (root level, pairs with `.env`)  
+- **Rails projects**: `config/env_check.yml` (Rails convention)
+
+**Example configuration:**
+
+```yaml
+# EnvCheck Configuration
+# 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
+  PORT: integer          # numeric values only
+  API_URL: url           # must start with http:// or https://
+  ADMIN_EMAIL: email     # valid email format
+```
+
+### 2. Validate Environment
+
+```bash
+env_check check
+```
+
+Output:
+```
+✅ DATABASE_URL is set
+✅ SECRET_KEY_BASE is set
+⚠️  DEBUG should be a boolean, got 'maybe'
+❌ Missing required ENV: API_KEY
+```
+
+---
+
+## 🛠 Usage
+
+### Command Line Interface
+
+```bash
+# Create configuration file
+env_check init
+
+# Validate environment variables
+env_check check
+
+# Show version
+env_check version
+```
+
+### Programmatic Usage
+
+```ruby
+require 'env_check'
+
+# Basic validation (returns Result object)
+result = EnvCheck.verify
+
+if result.success?
+  puts "✅ All environment variables are valid!"
+  puts "Valid vars: #{result.valid_vars.join(', ')}"
+else
+  puts "❌ Validation failed!"
+  puts "Errors: #{result.errors.join(', ')}"
+  puts "Warnings: #{result.warnings.join(', ')}"
+end
+
+# Validate with custom config file
+result = EnvCheck.verify("path/to/custom.yml")
+
+# Validate with inline configuration
+result = EnvCheck.verify_with_config({
+  "required" => ["API_KEY", "DATABASE_URL"],
+  "optional" => { "DEBUG" => "boolean" }
+})
+
+# Legacy method (raises exception on failure)
+begin
+  EnvCheck.verify!
+  puts "✅ Validation passed!"
+rescue EnvCheck::Error => e
+  puts "❌ #{e.message}"
+  exit 1
+end
+```
+
+### Rails Integration
+
+Add to your `config/application.rb` or initializer:
+
+```ruby
+# config/initializers/env_check.rb
+EnvCheck.verify! if Rails.env.production?
+```
+
+#### Advanced Rails Integration Patterns
+
+**1. Environment-Specific Validation**
+
+```ruby
+# config/initializers/env_check.rb
+Rails.application.config.after_initialize do
+  # Load Rails-specific config
+  config_file = Rails.root.join('config', 'env_check.yml')
+  
+  if config_file.exist?
+    result = EnvCheck.verify(config_file)
+    unless result.success?
+      Rails.logger.error "Environment validation failed: #{result.errors.join(', ')}"
+      
+      # Only raise in production
+      raise EnvCheck::Error, result.errors.join(', ') if Rails.env.production?
+    end
+  end
+end
+```
+
+**2. Controller Integration**
+
+```ruby
+class ApplicationController < ActionController::Base
+  before_action :validate_critical_env_vars, if: -> { Rails.env.production? }
+  
+  private
+  
+  def validate_critical_env_vars
+    result = EnvCheck.verify_with_config({
+      "required" => ["DATABASE_URL", "SECRET_KEY_BASE", "RAILS_MASTER_KEY"]
+    })
+    
+    unless result.success?
+      render json: { error: 'Service temporarily unavailable' }, status: 503
+    end
+  end
+end
+```
+
+**3. Health Check Endpoint**
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  get '/health/env', to: 'health#env_check'
+end
+
+# app/controllers/health_controller.rb
+class HealthController < ApplicationController
+  def env_check
+    result = EnvCheck.verify
+    
+    if result.success?
+      render json: { 
+        status: 'ok', 
+        valid_vars: result.valid_vars.count,
+        warnings: result.warnings
+      }
+    else
+      render json: { 
+        status: 'error', 
+        errors: result.errors 
+      }, status: 422
+    end
+  end
+end
+```
+
+**4. Environment-Specific Configuration**
+
+Create your config file (`.env_check.yml` or `config/env_check.yml`):
+
+```yaml
+default: &default
+  optional:
+    DEBUG: boolean
+    LOG_LEVEL: string
+
+development:
+  <<: *default
+  required:
+    - DATABASE_URL
+    - SECRET_KEY_BASE
+
+test:
+  <<: *default  
+  required:
+    - SECRET_KEY_BASE
+  optional:
+    DATABASE_URL: url
+
+production:
+  <<: *default
+  required:
+    - DATABASE_URL
+    - SECRET_KEY_BASE  
+    - RAILS_MASTER_KEY
+    - REDIS_URL
+  optional:
+    MEMCACHED_URL: url
+    CDN_HOST: url
+    SMTP_HOST: string
+```
+
+### Rake Integration
+
+```ruby
+# In your Rakefile or Rails app
+require 'env_check'
+
+# Use the built-in rake task
+rake env:check
+```
+
+---
+
+## 🔧 Configuration
+
+### Supported Types
+
+- **`boolean`**: `true`, `false`, `1`, `0`, `yes`, `no` (case-insensitive)
+- **`integer`**: Positive or negative integers (`123`, `-456`)
+- **`url`**: URLs starting with `http://` or `https://`
+- **`email`**: Valid email addresses
+- **`string`**: Any value (default, no validation)
+
+### Configuration File
+
+```yaml
+# config/env_check.yml
+required:
+  - DATABASE_URL
+  - SECRET_KEY_BASE
+  - API_KEY
+
+optional:
+  # Type validations
+  DEBUG: boolean
+  PORT: integer
+  API_URL: url
+  ADMIN_EMAIL: email
+  
+  # Environment-specific
+  RAILS_ENV: string
+  RACK_ENV: string
+```
+
+### Smart Configuration Discovery
+
+EnvCheck automatically discovers your configuration file using this priority:
+
+1. **`.env_check.yml`** (root level - simple projects, pairs with `.env`)
+2. **`config/env_check.yml`** (Rails convention - if `config/` directory exists)
+3. **Custom path** via `--config` flag or `ENV_CHECK_CONFIG` environment variable
+
+```bash
+# Auto-discovery (checks .env_check.yml, then config/env_check.yml)
+env_check check
+
+# Explicit path
+env_check check --config custom/path.yml
+
+# Via environment variable
+ENV_CHECK_CONFIG=custom/path.yml env_check check
+
+# Via Ruby API
+EnvCheck.verify("custom/path.yml")
+```
+
+---
+
+## 🧪 Testing
+
+Run the test suite:
+
+```bash
+bundle exec rspec
+```
+
+Run linting:
+
+```bash
+bundle exec rubocop
+```
+
+---
+
+## 🤝 Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new Pull Request
+
+Please make sure to update tests and run the linter before submitting.
+
+---
+
+## 📄 License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+---
+
+## 🙏 Changelog
+
+See [CHANGELOG.md](CHANGELOG.md) for version history and changes.