@hivehub/rulebook 1.2.0

package/templates/languages/RUBY.md

@@ -0,0 +1,421 @@
+<!-- RUBY:START -->
+# Ruby Project Rules
+
+## Agent Automation Commands
+
+**CRITICAL**: Execute these commands after EVERY implementation (see AGENT_AUTOMATION module for full workflow).
+
+```bash
+# Complete quality check sequence:
+bundle exec rubocop       # Linting and formatting
+bundle exec rspec         # All tests (100% pass)
+bundle exec rspec --format documentation  # Test coverage
+
+# Security audit:
+bundle audit              # Vulnerability scan
+bundle outdated           # Check outdated deps
+```
+
+## Ruby Configuration
+
+**CRITICAL**: Use Ruby 3.2+ with RuboCop and modern tooling.
+
+- **Version**: Ruby 3.2+
+- **Recommended**: Ruby 3.3+
+- **Style Guide**: Ruby Style Guide (RuboCop)
+- **Testing**: RSpec (recommended) or Minitest
+- **Type Checking**: RBS + Steep (optional but recommended)
+
+### Gemfile Requirements
+
+```ruby
+source 'https://rubygems.org'
+
+ruby '>= 3.2.0'
+
+# Production dependencies
+gem 'rake', '~> 13.0'
+
+# Development dependencies
+group :development do
+  gem 'rubocop', '~> 1.60', require: false
+  gem 'rubocop-performance', require: false
+  gem 'rubocop-rspec', require: false
+end
+
+# Test dependencies
+group :test do
+  gem 'rspec', '~> 3.12'
+  gem 'simplecov', require: false
+  gem 'simplecov-lcov', require: false
+end
+
+# Both development and test
+group :development, :test do
+  gem 'pry'
+  gem 'pry-byebug'
+end
+```
+
+### Gemspec Requirements (for gems)
+
+```ruby
+Gem::Specification.new do |spec|
+  spec.name = 'your_gem'
+  spec.version = '0.1.0'
+  spec.authors = ['Your Name']
+  spec.email = ['you@example.com']
+
+  spec.summary = 'Brief summary'
+  spec.description = 'Longer description'
+  spec.homepage = 'https://github.com/you/your_gem'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.2.0'
+
+  spec.files = Dir.glob('{lib,bin}/**/*') + %w[README.md LICENSE.txt]
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'rake', '~> 13.0'
+  
+  spec.add_development_dependency 'rspec', '~> 3.12'
+  spec.add_development_dependency 'rubocop', '~> 1.60'
+end
+```
+
+## Code Quality Standards
+
+### Mandatory Quality Checks
+
+**CRITICAL**: After implementing ANY feature, you MUST run these commands in order.
+
+**IMPORTANT**: These commands MUST match your GitHub Actions workflows to prevent CI/CD failures!
+
+```bash
+# Pre-Commit Checklist (MUST match .github/workflows/*.yml)
+
+# 1. Lint (MUST pass with no warnings - matches workflow)
+bundle exec rubocop
+
+# 2. Run all tests (MUST pass 100% - matches workflow)
+bundle exec rspec
+# or: bundle exec rake test (for Minitest)
+
+# 3. Check coverage (MUST meet threshold - matches workflow)
+COVERAGE=true bundle exec rspec
+
+# 4. Security audit (matches workflow)
+bundle exec bundler-audit check --update
+
+# 5. Build gem (if gem project - matches workflow)
+gem build *.gemspec
+
+# If ANY fails: ❌ DO NOT COMMIT - Fix first!
+```
+
+**If ANY of these fail, you MUST fix the issues before committing.**
+
+**Why This Matters:**
+- Running different commands locally than in CI causes "works on my machine" failures
+- CI/CD workflows will fail if commands don't match
+- Example: Using `rubocop -a` (auto-correct) locally but `rubocop` in CI = failure
+- Example: Missing security audit locally = CI catches vulnerabilities in dependencies
+
+### Linting with RuboCop
+
+- Configuration in `.rubocop.yml`
+- Must pass with no offenses
+- Auto-correct safe offenses only
+
+Example `.rubocop.yml`:
+```yaml
+require:
+  - rubocop-performance
+  - rubocop-rspec
+
+AllCops:
+  TargetRubyVersion: 3.2
+  NewCops: enable
+  Exclude:
+    - 'vendor/**/*'
+    - 'tmp/**/*'
+    - 'bin/**/*'
+
+Style/StringLiterals:
+  EnforcedStyle: single_quotes
+
+Metrics/MethodLength:
+  Max: 15
+  Exclude:
+    - 'spec/**/*'
+
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+```
+
+### Testing
+
+- **Framework**: RSpec (recommended) or Minitest
+- **Location**: `/spec` (RSpec) or `/test` (Minitest)
+- **Coverage**: SimpleCov (80%+ threshold)
+- **Focus**: Write descriptive specs
+
+Example RSpec test:
+```ruby
+# spec/my_class_spec.rb
+
+RSpec.describe MyClass do
+  let(:instance) { described_class.new(value: 'test') }
+  
+  describe '#process' do
+    context 'with valid input' do
+      it 'returns processed value' do
+        result = instance.process('input')
+        expect(result).to eq('PROCESSED: input')
+      end
+      
+      it 'handles empty strings' do
+        expect(instance.process('')).to be_nil
+      end
+    end
+    
+    context 'with invalid input' do
+      it 'raises ArgumentError' do
+        expect { instance.process(nil) }.to raise_error(ArgumentError)
+      end
+    end
+  end
+  
+  describe '#validate' do
+    it 'returns true for valid data' do
+      expect(instance.validate('valid')).to be true
+    end
+    
+    it 'returns false for invalid data' do
+      expect(instance.validate('')).to be false
+    end
+  end
+end
+```
+
+Example Minitest:
+```ruby
+# test/my_class_test.rb
+
+require 'test_helper'
+
+class MyClassTest < Minitest::Test
+  def setup
+    @instance = MyClass.new(value: 'test')
+  end
+  
+  def test_process_returns_expected_value
+    result = @instance.process('input')
+    assert_equal 'PROCESSED: input', result
+  end
+  
+  def test_process_handles_empty_strings
+    assert_nil @instance.process('')
+  end
+  
+  def test_process_raises_on_nil
+    assert_raises(ArgumentError) { @instance.process(nil) }
+  end
+end
+```
+
+### Coverage Configuration
+
+Create `spec/spec_helper.rb`:
+```ruby
+if ENV['COVERAGE']
+  require 'simplecov'
+  require 'simplecov-lcov'
+  
+  SimpleCov::Formatter::LcovFormatter.config.report_with_single_file = true
+  SimpleCov.formatter = SimpleCov::Formatter::MultiFormatter.new([
+    SimpleCov::Formatter::HTMLFormatter,
+    SimpleCov::Formatter::LcovFormatter
+  ])
+  
+  SimpleCov.start do
+    add_filter '/spec/'
+    add_filter '/test/'
+    
+    minimum_coverage 80
+    minimum_coverage_by_file 70
+  end
+end
+
+require 'your_gem'
+
+RSpec.configure do |config|
+  config.expect_with :rspec do |expectations|
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+  end
+
+  config.mock_with :rspec do |mocks|
+    mocks.verify_partial_doubles = true
+  end
+
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+  config.filter_run_when_matching :focus
+  config.example_status_persistence_file_path = 'spec/examples.txt'
+  config.disable_monkey_patching!
+  config.warnings = true
+  
+  config.default_formatter = 'doc' if config.files_to_run.one?
+  config.profile_examples = 10
+  config.order = :random
+  Kernel.srand config.seed
+end
+```
+
+## Dependency Management
+
+### Using Bundler
+
+```bash
+# Install dependencies
+bundle install
+
+# Update dependencies
+bundle update
+
+# Check for outdated gems
+bundle outdated
+
+# Security audit
+bundle exec bundler-audit check --update
+```
+
+### Gemfile.lock
+
+- **MUST** commit Gemfile.lock for applications
+- For gems: Add to `.gitignore`
+- Ensures reproducible builds
+
+## Best Practices
+
+### DO's ✅
+
+- **USE** meaningful variable and method names
+- **FOLLOW** Ruby naming conventions (snake_case)
+- **WRITE** descriptive tests with context blocks
+- **HANDLE** exceptions explicitly
+- **VALIDATE** inputs
+- **DOCUMENT** public APIs
+- **USE** symbols for hash keys when possible
+- **FREEZE** string literals in Ruby 3+
+
+### DON'Ts ❌
+
+- **NEVER** use global variables
+- **NEVER** monkey-patch core classes without extreme caution
+- **NEVER** skip tests
+- **NEVER** commit `.byebug_history` or debug files
+- **NEVER** use `eval` unless absolutely necessary
+- **NEVER** ignore RuboCop offenses without justification
+- **NEVER** commit with failing tests
+
+Example code style:
+```ruby
+# ✅ GOOD: Clean Ruby code
+class DataProcessor
+  def initialize(options = {})
+    @threshold = options.fetch(:threshold, 0.5)
+    @verbose = options.fetch(:verbose, false)
+  end
+  
+  def process(data)
+    validate_input!(data)
+    
+    log('Processing data...') if @verbose
+    
+    data.select { |item| item[:value] > @threshold }
+  end
+  
+  private
+  
+  def validate_input!(data)
+    raise ArgumentError, 'Data must be an array' unless data.is_a?(Array)
+    raise ArgumentError, 'Data cannot be empty' if data.empty?
+  end
+  
+  def log(message)
+    puts "[#{Time.now.iso8601}] #{message}"
+  end
+end
+
+# ❌ BAD: Poor practices
+class DataProcessor
+  def process(data)
+    $threshold = 0.5  # DON'T use globals!
+    
+    if data == nil  # Use nil? method
+      return false
+    end
+    
+    result = []
+    for item in data  # Use .each or .map
+      if item[:value] > $threshold
+        result.push(item)
+      end
+    end
+    
+    puts result  # DON'T print in library code
+    result
+  end
+end
+```
+
+## CI/CD Requirements
+
+Must include GitHub Actions workflows:
+
+1. **Testing** (`ruby-test.yml`):
+   - Test on ubuntu-latest, windows-latest, macos-latest
+   - Ruby versions: 3.2, 3.3
+   - Upload coverage to Codecov
+
+2. **Linting** (`ruby-lint.yml`):
+   - RuboCop checks
+   - Bundler audit for security
+
+3. **Build** (`ruby-build.yml`):
+   - Build gem
+   - Verify gem structure
+
+## Publishing to RubyGems
+
+### Prerequisites
+
+1. Create account at https://rubygems.org
+2. Get API key: `gem signin`
+3. Add `RUBYGEMS_API_KEY` to GitHub secrets
+
+### Publishing Workflow
+
+```bash
+# 1. Update version in gemspec or version.rb
+# 2. Update CHANGELOG.md
+# 3. Run all quality checks
+bundle exec rubocop
+bundle exec rspec
+gem build *.gemspec
+
+# 4. Create git tag
+git tag -a v1.0.0 -m "Release version 1.0.0"
+
+# 5. Push (manual if SSH password)
+# git push origin main
+# git push origin v1.0.0
+
+# 6. Publish to RubyGems (or use GitHub Actions)
+gem push your_gem-1.0.0.gem
+```
+
+<!-- RUBY:END -->