rubyn-code 0.1.0

data/skills/ruby/hashes.md

@@ -0,0 +1,195 @@
+# Ruby: Hash Patterns
+
+## Pattern
+
+Hashes are Ruby's most versatile data structure. Use the right access pattern for safety, the right transformation for clarity, and know when a Hash should become an object.
+
+### Safe Access
+
+```ruby
+config = { database: { host: "localhost", port: 5432 }, redis: { url: "redis://localhost" } }
+
+# GOOD: dig for nested access — returns nil instead of raising
+config.dig(:database, :host)        # => "localhost"
+config.dig(:database, :timeout)     # => nil (missing key)
+config.dig(:missing, :nested)       # => nil (missing parent)
+
+# GOOD: fetch for required keys — raises if missing, or uses default
+ENV.fetch("DATABASE_URL")                        # Raises KeyError if missing
+ENV.fetch("OPTIONAL_KEY", "default_value")       # Returns default if missing
+ENV.fetch("PORT") { 3000 }                       # Block for computed default
+
+config.fetch(:database)             # Raises if :database doesn't exist
+config.fetch(:timeout, 30)          # Returns 30 if :timeout doesn't exist
+
+# BAD: [] silently returns nil — hides bugs
+config[:databas][:host]             # NoMethodError: undefined method `[]' for nil
+# Typo in :databas goes undetected until runtime crash
+
+# RULE: Use fetch for required keys, dig for optional nested keys, [] only when nil is an acceptable value
+```
+
+### Transformation
+
+```ruby
+data = { "user_name" => "Alice", "user_email" => "alice@example.com", "role" => "admin" }
+
+# Symbolize keys
+data.symbolize_keys                  # => { user_name: "Alice", user_email: "alice@example.com", role: "admin" }
+# Rails method — in pure Ruby use: data.transform_keys(&:to_sym)
+
+# Transform keys
+data.transform_keys { |k| k.delete_prefix("user_") }
+# => { "name" => "Alice", "email" => "alice@example.com", "role" => "admin" }
+
+# Transform values
+prices = { widget: 10_00, gadget: 25_00, gizmo: 50_00 }
+prices.transform_values { |cents| "$#{format('%.2f', cents / 100.0)}" }
+# => { widget: "$10.00", gadget: "$25.00", gizmo: "$50.00" }
+
+# Slice — pick specific keys (Rails, or Ruby 2.5+)
+user_params = params.slice(:name, :email, :phone)
+
+# Except — remove specific keys (Rails)
+safe_params = params.except(:admin, :role, :password_digest)
+
+# Select / reject by key or value
+prices.select { |_, v| v > 20_00 }   # => { gadget: 25_00, gizmo: 50_00 }
+prices.reject { |k, _| k == :gizmo } # => { widget: 10_00, gadget: 25_00 }
+
+# Filter map (Ruby 2.7+)
+prices.filter_map { |k, v| "#{k}: $#{v / 100.0}" if v > 15_00 }
+# => ["gadget: $25.0", "gizmo: $50.0"]
+```
+
+### Merging
+
+```ruby
+defaults = { timeout: 30, retries: 3, format: :json }
+overrides = { timeout: 60, debug: true }
+
+# merge — right side wins on conflicts
+config = defaults.merge(overrides)
+# => { timeout: 60, retries: 3, format: :json, debug: true }
+
+# merge with block — resolve conflicts custom
+counts_a = { orders: 10, users: 5 }
+counts_b = { orders: 3, products: 8 }
+counts_a.merge(counts_b) { |_key, a, b| a + b }
+# => { orders: 13, users: 5, products: 8 }
+
+# Deep merge (Rails) — merges nested hashes recursively
+base = { database: { host: "localhost", pool: 5 } }
+override = { database: { pool: 10, timeout: 30 } }
+base.deep_merge(override)
+# => { database: { host: "localhost", pool: 10, timeout: 30 } }
+
+# Reverse merge (Rails) — "fill in defaults" — left side wins
+user_options = { theme: "dark" }
+user_options.reverse_merge(theme: "light", locale: "en", per_page: 25)
+# => { theme: "dark", locale: "en", per_page: 25 }
+# User's theme preserved, defaults filled in for missing keys
+
+# With duplicate keys — ** (double splat) syntax
+config = { **defaults, **overrides }  # Same as defaults.merge(overrides)
+```
+
+### Building Hashes
+
+```ruby
+users = [user_a, user_b, user_c]
+
+# index_by (Rails) — build a lookup hash
+users_by_id = users.index_by(&:id)
+# => { 1 => user_a, 2 => user_b, 3 => user_c }
+
+# group_by — group into arrays by key
+users.group_by(&:role)
+# => { "admin" => [user_a], "user" => [user_b, user_c] }
+
+# tally (Ruby 2.7+) — count occurrences
+%w[pending pending shipped delivered pending].tally
+# => { "pending" => 3, "shipped" => 1, "delivered" => 1 }
+
+# each_with_object — build a hash from iteration
+users.each_with_object({}) do |user, hash|
+  hash[user.email] = user.name
+end
+
+# to_h with block (Ruby 2.6+)
+users.to_h { |u| [u.id, u.name] }
+# => { 1 => "Alice", 2 => "Bob", 3 => "Charlie" }
+
+# zip to build from parallel arrays
+keys = [:name, :email, :role]
+values = ["Alice", "alice@example.com", "admin"]
+keys.zip(values).to_h
+# => { name: "Alice", email: "alice@example.com", role: "admin" }
+```
+
+### Pattern Matching with Hashes (Ruby 3+)
+
+```ruby
+response = { status: 200, body: { user: { name: "Alice", role: "admin" } } }
+
+case response
+in { status: 200, body: { user: { role: "admin" } } }
+  puts "Admin user response"
+in { status: 200, body: { user: { name: String => name } } }
+  puts "User: #{name}"
+in { status: (400..499) => code }
+  puts "Client error: #{code}"
+in { status: (500..) }
+  puts "Server error"
+end
+
+# Destructuring assignment
+response => { body: { user: { name: } } }
+puts name  # => "Alice"
+```
+
+### When a Hash Should Become an Object
+
+```ruby
+# SMELL: Hash with known, fixed keys passed around everywhere
+def process_order(order_data)
+  validate(order_data[:address])
+  charge(order_data[:total], order_data[:payment_token])
+  notify(order_data[:email])
+end
+
+# Accessing order_data[:adress] (typo) returns nil silently
+
+# FIX: Use a Data class or Struct
+OrderRequest = Data.define(:address, :total, :payment_token, :email)
+
+def process_order(request)
+  validate(request.address)
+  charge(request.total, request.payment_token)
+  notify(request.email)
+end
+
+# OrderRequest.new(adress: "...") → ArgumentError: unknown keyword: adress
+# Typos caught at construction time, not buried in runtime nils
+```
+
+## Why This Is Good
+
+- **`fetch` fails loudly on missing keys.** A typo in `config[:databse_url]` returns nil silently and crashes somewhere else. `config.fetch(:database_url)` raises immediately at the point of error.
+- **`dig` handles nested nils gracefully.** No more `config[:database] && config[:database][:host]` chains. One method call.
+- **Transformation methods are functional.** `transform_values`, `select`, `reject` return new hashes without mutating the original.
+- **`index_by` and `tally` replace manual loops.** Building a lookup hash or counting occurrences is one method call, not a 4-line `each_with_object`.
+- **Pattern matching makes hash destructuring readable.** Complex conditional logic on nested hashes becomes a clean `case/in`.
+
+## When To Apply
+
+- **`fetch` for ENV variables.** Always. `ENV.fetch("API_KEY")` fails at boot if the key is missing, not at runtime when a request fails.
+- **`dig` for API responses.** External API responses have unpredictable nesting. `response.dig(:data, :attributes, :name)` is safe.
+- **`transform_keys/values` for data normalization.** API responses with string keys, webhook payloads with camelCase — normalize once at the boundary.
+- **`to_h` with a block for building lookups.** Cleaner than `each_with_object` for simple key-value mappings.
+
+## When NOT To Apply
+
+- **Don't use `fetch` when nil is a valid value.** If a config key is genuinely optional, use `dig` or `[]` with a nil check.
+- **When the hash should be an object.** If you're passing the same hash shape to 3+ methods, it's a Data class or Struct waiting to happen.
+- **Don't chain too many transformations.** `hash.symbolize_keys.slice(:a, :b).transform_values(&:to_i).merge(defaults)` — if the chain exceeds 3 steps, break it into named intermediate variables.

data/skills/ruby/metaprogramming.md

@@ -0,0 +1,170 @@
+# Ruby: Metaprogramming
+
+## Pattern
+
+Metaprogramming is writing code that writes code at runtime. Ruby is famous for it — `attr_accessor`, `has_many`, `validates`, and `scope` are all metaprogramming. Use it sparingly and intentionally: to eliminate repetition in DSLs and frameworks, never to be clever.
+
+### Safe Metaprogramming: `define_method`
+
+```ruby
+# Generating similar methods from data
+class Order < ApplicationRecord
+  # Instead of writing 5 nearly identical methods:
+  %w[pending confirmed shipped delivered cancelled].each do |status|
+    define_method("#{status}?") do
+      self.status == status
+    end
+
+    define_method("mark_#{status}!") do
+      update!(status: status, "#{status}_at": Time.current)
+    end
+  end
+end
+
+# Usage — these methods exist as if hand-written
+order.pending?          # true/false
+order.mark_confirmed!   # updates status and confirmed_at
+```
+
+### Safe Metaprogramming: `class_attribute` and Class Macros
+
+```ruby
+# A class macro like Rails' has_many or validates
+module HasCreditCost
+  extend ActiveSupport::Concern
+
+  class_methods do
+    def credit_cost(amount = nil, &block)
+      if block
+        define_method(:credit_cost) { instance_exec(&block) }
+      else
+        define_method(:credit_cost) { amount }
+      end
+    end
+  end
+end
+
+class Ai::RefactorService
+  include HasCreditCost
+  credit_cost 2
+end
+
+class Ai::ReviewService
+  include HasCreditCost
+  credit_cost { file_content.length > 5000 ? 3 : 1 }  # Dynamic cost
+end
+
+# Usage
+Ai::RefactorService.new.credit_cost  # => 2
+Ai::ReviewService.new.credit_cost    # => 1 or 3 depending on content
+```
+
+### Safe Metaprogramming: `method_missing` with `respond_to_missing?`
+
+```ruby
+# Configuration object with dynamic attribute access
+class Settings
+  def initialize(hash)
+    @data = hash.transform_keys(&:to_s)
+  end
+
+  def method_missing(name, *args)
+    key = name.to_s
+    if @data.key?(key)
+      value = @data[key]
+      value.is_a?(Hash) ? Settings.new(value) : value
+    else
+      super  # CRITICAL: call super for unknown methods
+    end
+  end
+
+  def respond_to_missing?(name, include_private = false)
+    @data.key?(name.to_s) || super  # CRITICAL: implement this
+  end
+
+  def to_h
+    @data
+  end
+end
+
+settings = Settings.new(
+  database: { host: "localhost", port: 5432 },
+  redis: { url: "redis://localhost:6379" }
+)
+
+settings.database.host  # => "localhost"
+settings.database.port  # => 5432
+settings.redis.url      # => "redis://localhost:6379"
+settings.unknown_key    # => NoMethodError (falls through to super)
+```
+
+## Why This Is Good (When Used Correctly)
+
+- **Eliminates repetitive code.** 5 status methods generated from an array is DRYer and less error-prone than 5 hand-written methods.
+- **Enables clean DSLs.** `credit_cost 2` at the class level reads like configuration, not code. ActiveRecord's `validates :name, presence: true` is the same pattern.
+- **Dynamic attribute access.** `settings.database.host` is more readable than `settings.dig("database", "host")` for deeply nested configs.
+
+## Anti-Pattern
+
+Using metaprogramming to be clever, to avoid typing, or where plain Ruby would be clearer:
+
+```ruby
+# BAD: Metaprogramming where a simple method would do
+class User
+  %i[name email phone].each do |attr|
+    define_method("display_#{attr}") do
+      value = send(attr)
+      value.present? ? value : "N/A"
+    end
+  end
+end
+
+# BETTER: Just write the methods
+class User
+  def display_name = name.presence || "N/A"
+  def display_email = email.presence || "N/A"
+  def display_phone = phone.presence || "N/A"
+end
+# 3 lines, immediately readable, greppable, no metaprogramming needed
+```
+
+```ruby
+# BAD: method_missing without respond_to_missing?
+class MagicHash
+  def method_missing(name, *args)
+    @data[name.to_s]  # Everything silently returns nil for unknown keys
+  end
+  # Missing respond_to_missing? means is_a?, respond_to?, and inspect lie
+end
+
+# BAD: eval with user input (security vulnerability)
+def dynamic_call(method_name, *args)
+  eval("object.#{method_name}(#{args.join(',')})")  # NEVER do this
+end
+
+# SAFE: Use public_send instead
+def dynamic_call(object, method_name, *args)
+  object.public_send(method_name, *args)
+end
+```
+
+## Rules for Safe Metaprogramming
+
+1. **Always implement `respond_to_missing?`** when you implement `method_missing`. Otherwise `respond_to?`, `method`, and debugging tools lie.
+2. **Always call `super`** in `method_missing` for methods you don't handle. Otherwise all `NoMethodError`s are silently swallowed.
+3. **Never use `eval` with dynamic input.** Use `define_method`, `public_send`, or `const_get` instead. `eval` is a security hole.
+4. **Prefer `public_send` over `send`.** `send` bypasses `private` — use `public_send` to respect visibility.
+5. **Generate methods at load time, not call time.** `define_method` in the class body runs once. `method_missing` runs on every call and is slower.
+6. **If the generated methods would be fewer than 5, just write them by hand.** Metaprogramming for 3 methods adds complexity that's not worth the 2 lines saved.
+
+## When To Apply
+
+- **Framework/library DSLs.** If you're building a gem that others configure (`has_many`, `validates`, `scope`), metaprogramming creates clean APIs.
+- **Code generation from data.** Generating methods from a list of statuses, roles, or feature flags.
+- **When you'd otherwise write 10+ identical methods.** At that point, a loop with `define_method` is legitimately DRYer and safer.
+
+## When NOT To Apply
+
+- **Application code.** Business logic should be explicit, greppable, and debuggable. Metaprogramming makes all three harder.
+- **When plain Ruby works.** If you can write 3-5 simple methods instead of metaprogramming, do it. Readable > clever.
+- **Fewer than 5 repetitions.** The Rule of Three applies: don't abstract (or metaprogram) until you have enough examples to justify it.

data/skills/ruby/modules.md

@@ -0,0 +1,210 @@
+# Ruby: Modules
+
+## Pattern
+
+Modules serve two distinct purposes in Ruby: namespacing and behavior sharing. Use namespacing modules to organize related classes. Use mixins (`include`/`extend`/`prepend`) to share behavior across unrelated classes — but only when that behavior is truly reusable and doesn't couple the classes together.
+
+**Namespacing — grouping related classes:**
+
+```ruby
+# app/services/orders/create_service.rb
+module Orders
+  class CreateService
+    def self.call(params, user)
+      new(params, user).call
+    end
+    # ...
+  end
+end
+
+# app/services/orders/cancel_service.rb
+module Orders
+  class CancelService
+    def self.call(order, reason:)
+      new(order, reason:).call
+    end
+    # ...
+  end
+end
+
+# Usage: clear, organized, discoverable
+Orders::CreateService.call(params, user)
+Orders::CancelService.call(order, reason: "customer_request")
+```
+
+**Behavior sharing — reusable capabilities:**
+
+```ruby
+# app/models/concerns/sluggable.rb
+module Sluggable
+  extend ActiveSupport::Concern
+
+  included do
+    before_validation :generate_slug, on: :create
+    validates :slug, presence: true, uniqueness: true
+  end
+
+  def to_param
+    slug
+  end
+
+  private
+
+  def generate_slug
+    self.slug ||= name&.parameterize
+  end
+end
+
+# Used in unrelated models that share the same capability
+class Product < ApplicationRecord
+  include Sluggable
+end
+
+class Category < ApplicationRecord
+  include Sluggable
+end
+```
+
+**`include` vs `extend` vs `prepend`:**
+
+```ruby
+module Logging
+  def perform(*args)
+    Rails.logger.info("Starting #{self.class.name}")
+    result = super  # Calls the original method
+    Rails.logger.info("Completed #{self.class.name}")
+    result
+  end
+end
+
+# prepend: Inserts BEFORE the class in the method lookup chain
+# The module's method runs first, calls super to reach the class method
+class ImportJob
+  prepend Logging
+
+  def perform(file_path)
+    CSV.foreach(file_path) { |row| process(row) }
+  end
+end
+
+# include: Inserts AFTER the class in the lookup chain
+# Provides methods the class can call, but doesn't wrap existing methods
+class User < ApplicationRecord
+  include Sluggable  # Adds generate_slug, to_param to instances
+end
+
+# extend: Adds methods as CLASS methods, not instance methods
+module Findable
+  def find_by_slug(slug)
+    find_by!(slug: slug)
+  end
+end
+
+class Product < ApplicationRecord
+  extend Findable  # Product.find_by_slug("widget")
+end
+```
+
+## Why This Is Good
+
+- **Namespacing prevents collisions.** `Orders::CreateService` and `Users::CreateService` coexist cleanly. Without namespacing, you'd need `CreateOrderService` and `CreateUserService` — longer names, flatter structure.
+- **Namespacing aids discovery.** `ls app/services/orders/` shows every operation available for orders. The file system mirrors the module structure.
+- **Mixins share behavior without inheritance.** `Sluggable` can be included in Product, Category, and Article without any of them inheriting from a common base class. This avoids fragile inheritance hierarchies.
+- **`prepend` enables clean wrapping.** Adding logging, caching, or instrumentation around a method without modifying the original class. `super` calls the original implementation.
+- **`ActiveSupport::Concern` simplifies Rails mixins.** It handles `included` blocks, class methods, and dependency resolution cleanly.
+
+## Anti-Pattern
+
+Using modules as dumping grounds for loosely related methods:
+
+```ruby
+# app/models/concerns/order_helpers.rb
+module OrderHelpers
+  extend ActiveSupport::Concern
+
+  def calculate_total
+    line_items.sum { |li| li.quantity * li.unit_price }
+  end
+
+  def apply_discount(code)
+    discount = Discount.find_by(code: code)
+    self.discount_amount = discount.calculate(total)
+  end
+
+  def send_confirmation
+    OrderMailer.confirmation(self).deliver_later
+  end
+
+  def sync_to_warehouse
+    WarehouseApi.new.sync(self)
+  end
+
+  def generate_invoice_pdf
+    InvoicePdfGenerator.new(self).generate
+  end
+
+  included do
+    after_create :send_confirmation
+    after_update :sync_to_warehouse, if: :saved_change_to_status?
+  end
+end
+```
+
+## Why This Is Bad
+
+- **Junk drawer module.** Calculation, discounts, email, warehouse API, and PDF generation are unrelated responsibilities dumped into one module. The module has no cohesive purpose.
+- **Hidden the fat model problem.** Moving 50 lines from the model into a concern doesn't fix the design — it just hides the bloat in a different file. The model is still doing too much.
+- **Tight coupling.** Any class that includes `OrderHelpers` gets email sending, warehouse syncing, and PDF generation — even if it only needed `calculate_total`.
+- **Callbacks hiding in concerns.** `after_create :send_confirmation` is invisible when reading the model. The concern silently adds behavior that triggers on every create.
+- **Not reusable.** Despite being a module, `OrderHelpers` only works with orders. No other model can include it. It's not actually shared behavior.
+
+## When To Apply
+
+**Use namespacing modules when:**
+- You have multiple classes that operate on the same domain concept (`Orders::CreateService`, `Orders::CancelService`, `Orders::SearchQuery`)
+- You want to organize files in a directory structure that mirrors the module hierarchy
+- You need to avoid class name collisions
+
+**Use behavior-sharing modules when:**
+- The behavior is genuinely used by 2+ unrelated classes (Sluggable, Searchable, Auditable)
+- The behavior is self-contained — it doesn't depend on the including class having specific methods or attributes (beyond a clear, documented contract)
+- The behavior is about capability ("this object is sluggable") not identity ("this object is an order")
+
+**Use `prepend` when:**
+- You need to wrap an existing method with before/after behavior (logging, caching, instrumentation, retry logic)
+- You want `super` to call the original implementation
+
+## When NOT To Apply
+
+- **Don't use modules to split a fat model into files.** If your model is 500 lines and you split it into 5 concerns of 100 lines, you still have a 500-line model — it's just harder to read because it's scattered across files.
+- **Don't create a concern for behavior used by only one class.** A concern that's included in exactly one model is just indirection. Keep the methods in the model.
+- **Don't use `extend` when you mean `include`.** Extending adds class methods. Including adds instance methods. Confusing them causes `NoMethodError` at runtime.
+- **Don't use `module_function` in Rails concerns.** It makes methods both instance and module methods, which creates confusing dual interfaces.
+
+## Edge Cases
+
+**Concern depends on the including class having specific attributes:**
+Document the contract explicitly. Use a class method or a runtime check:
+
+```ruby
+module Publishable
+  extend ActiveSupport::Concern
+
+  included do
+    raise "#{self} must have a published_at column" unless column_names.include?("published_at")
+
+    scope :published, -> { where.not(published_at: nil) }
+    scope :draft, -> { where(published_at: nil) }
+  end
+
+  def publish!
+    update!(published_at: Time.current)
+  end
+end
+```
+
+**Multiple modules define the same method:**
+Ruby uses the method lookup chain. The last included module wins. Use `prepend` if you need explicit ordering with `super` delegation.
+
+**When to use `ActiveSupport::Concern` vs plain modules:**
+Use `Concern` in Rails apps when you need `included` blocks, class methods, or concern dependencies. Use plain modules in pure Ruby, gems, or when the module only adds instance methods.