rubyn-code 0.1.0

data/skills/ruby/pattern_matching.md

@@ -0,0 +1,177 @@
+# Ruby: Pattern Matching
+
+## Pattern
+
+Ruby 3.x introduced structural pattern matching with `case/in`. It destructures arrays, hashes, and objects, binds variables, and replaces complex conditional chains with declarative matching. Use it for API response handling, parsing, and multi-branch logic on complex data.
+
+### Basic Matching
+
+```ruby
+# Match on value
+case status
+in "pending"
+  process_pending
+in "shipped"
+  process_shipped
+in "delivered" | "completed"  # OR pattern
+  mark_complete
+in String => unknown_status   # Catch-all with binding
+  Rails.logger.warn("Unknown status: #{unknown_status}")
+end
+
+# Match on type
+case value
+in Integer => n if n.positive?
+  "Positive integer: #{n}"
+in Float
+  "A float"
+in String
+  "A string"
+in nil
+  "Nothing"
+end
+```
+
+### Hash Destructuring
+
+```ruby
+# Parse API responses
+response = { status: 200, body: { user: { name: "Alice", role: "admin", plan: "pro" } } }
+
+case response
+in { status: 200, body: { user: { role: "admin", name: String => name } } }
+  puts "Admin user: #{name}"
+in { status: 200, body: { user: { plan: "pro", name: String => name } } }
+  puts "Pro user: #{name}"
+in { status: 200, body: { user: { name: String => name } } }
+  puts "Standard user: #{name}"
+in { status: (400..499) => code }
+  puts "Client error: #{code}"
+in { status: (500..) => code }
+  puts "Server error: #{code}"
+end
+
+# One-line destructuring with =>
+response => { body: { user: { name: } } }
+puts name  # => "Alice"
+
+# Nested destructuring
+webhook = { event: "order.shipped", data: { order_id: 42, tracking: "1Z999" } }
+webhook => { event: /^order\.(.+)/ => event, data: { order_id: Integer => id } }
+puts "Order #{id}: #{event}"
+```
+
+### Array Destructuring
+
+```ruby
+# Head and tail
+case [1, 2, 3, 4, 5]
+in [first, *rest]
+  puts "First: #{first}, rest: #{rest}"
+  # First: 1, rest: [2, 3, 4, 5]
+end
+
+# Find pattern — match an element anywhere in the array
+case ["info", "warning", "error: disk full", "info"]
+in [*, /^error: (.+)/ => error_msg, *]
+  puts "Found error: #{error_msg}"
+end
+
+# Fixed structure
+case [200, "OK", { content_type: "application/json" }]
+in [200, String => msg, Hash => headers]
+  puts "Success: #{msg}"
+in [(400..499) => code, String => msg, _]
+  puts "Client error #{code}: #{msg}"
+end
+```
+
+### Pin Operator (Match Against Existing Variables)
+
+```ruby
+expected_status = "shipped"
+
+case order
+in { status: ^expected_status }  # ^ pins the variable — matches its VALUE, not a new binding
+  puts "Order is shipped!"
+in { status: String => actual }
+  puts "Expected #{expected_status}, got #{actual}"
+end
+
+# Without ^, `expected_status` would be a new binding, not a comparison
+```
+
+### Guard Conditions
+
+```ruby
+case order
+in { total: Integer => amount } if amount > 100_00
+  apply_free_shipping(order)
+in { total: Integer => amount } if amount > 50_00
+  apply_discount_shipping(order)
+in { total: Integer }
+  apply_standard_shipping(order)
+end
+```
+
+### Practical Rails Uses
+
+```ruby
+# Webhook handler — clean multi-type dispatch
+class Webhooks::StripeHandler
+  def call(event)
+    case event
+    in { type: "checkout.session.completed", data: { object: { customer: String => customer_id, amount_total: Integer => amount } } }
+      process_checkout(customer_id, amount)
+    in { type: "invoice.payment_failed", data: { object: { customer: String => customer_id } } }
+      handle_payment_failure(customer_id)
+    in { type: /^customer\.subscription\./, data: { object: { id: String => sub_id, status: String => status } } }
+      update_subscription(sub_id, status)
+    in { type: String => type }
+      Rails.logger.info("Unhandled webhook: #{type}")
+    end
+  end
+end
+
+# Service result handling
+case Orders::CreateService.call(params, user)
+in { success: true, order: Order => order }
+  redirect_to order
+in { success: false, error: String => message }
+  flash.now[:alert] = message
+  render :new, status: :unprocessable_entity
+end
+
+# Config validation at boot
+case Rails.application.credentials.config
+in { anthropic: { api_key: String }, database: { url: String } }
+  # All required config present
+in { anthropic: nil | { api_key: nil } }
+  raise "Missing Anthropic API key in credentials"
+in { database: nil | { url: nil } }
+  raise "Missing database URL in credentials"
+end
+```
+
+## Why This Is Good
+
+- **Declarative over imperative.** `case/in` says WHAT you're looking for. Nested `if/elsif` chains say HOW to check.
+- **Destructuring binds variables inline.** `{ user: { name: String => name } }` both validates the structure AND extracts the value in one expression.
+- **Exhaustive matching catches missing cases.** If no pattern matches, Ruby raises `NoMatchingPatternError`. This catches unhandled types at runtime instead of silently returning nil.
+- **Readable webhook/API handling.** Stripe webhooks have deeply nested JSON. Pattern matching handles them in 3 lines instead of 15.
+- **Pin operator enables dynamic matching.** `^expected_value` matches against a variable's value without rebinding it.
+
+## When To Apply
+
+- **Webhook handlers** — matching on event type and extracting nested data from JSON payloads.
+- **API response parsing** — matching on status codes and body structure.
+- **Multi-type dispatch** — when a method receives different shapes of input and must handle each differently.
+- **Config validation** — asserting required structure exists at boot time.
+- **Result object handling** — matching on success/failure with different payloads.
+
+## When NOT To Apply
+
+- **Simple equality checks.** `case status when "pending"` is clearer than `case status in "pending"` for flat value matching. Use `case/when` for simple equality, `case/in` for structural matching.
+- **Ruby < 3.0 projects.** Pattern matching is Ruby 3+ only. Check the project's `.ruby-version`.
+- **Performance-critical hot paths.** Pattern matching is slightly slower than direct hash access. For code that runs millions of times, use `dig` / `fetch` directly.
+- **When the team isn't familiar.** Pattern matching is powerful but unfamiliar to many Rubyists. If the team hasn't adopted it, don't introduce it in one file.

data/skills/ruby/regular_expressions.md

@@ -0,0 +1,166 @@
+# Ruby: Regular Expressions
+
+## Pattern
+
+Use regex for pattern matching, validation, and extraction — but prefer string methods when they suffice. Keep patterns readable with `x` flag for complex expressions, and use named captures for clarity.
+
+### Matching
+
+```ruby
+# match? — boolean check, fastest (no MatchData allocation)
+"ORD-12345".match?(/\AORD-\d+\z/)  # => true
+"hello@example.com".match?(URI::MailTo::EMAIL_REGEXP)  # => true
+
+# =~ — returns index of match or nil
+"hello world" =~ /world/  # => 6
+"hello world" =~ /xyz/    # => nil
+
+# match — returns MatchData object (for captures)
+md = "ORD-12345".match(/\AORD-(\d+)\z/)
+md[1]  # => "12345"
+
+# String#scan — find all matches
+"Order ORD-001 and ORD-002 shipped".scan(/ORD-\d+/)
+# => ["ORD-001", "ORD-002"]
+```
+
+### Named Captures
+
+```ruby
+# Named captures make regex self-documenting
+pattern = /\A(?<prefix>ORD|INV)-(?<number>\d{6})-(?<year>\d{4})\z/
+md = "ORD-000042-2026".match(pattern)
+md[:prefix]  # => "ORD"
+md[:number]  # => "000042"
+md[:year]    # => "2026"
+
+# Ruby 3.2+ pattern matching with regex
+case "ORD-000042-2026"
+in /\AORD-(?<number>\d+)/ => ref
+  puts "Order #{ref}"
+end
+
+# Named captures assigned to local variables (magic behavior)
+if /\A(?<name>\w+)@(?<domain>\w+\.\w+)\z/ =~ "alice@example.com"
+  puts name    # => "alice"
+  puts domain  # => "example.com"
+end
+```
+
+### Common Patterns
+
+```ruby
+# Email (use URI::MailTo::EMAIL_REGEXP instead of writing your own)
+URI::MailTo::EMAIL_REGEXP
+
+# UUID
+/\A[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}\z/i
+
+# Phone (loose US format)
+/\A\+?1?\d{10}\z/
+
+# Semantic version
+/\A(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)(?:-(?<pre>[a-zA-Z0-9.]+))?\z/
+
+# IP address (v4, loose)
+/\A\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}\z/
+# Better: Use IPAddr.new(str) and rescue — regex doesn't validate 0-255 range
+
+# Slug (URL-safe)
+/\A[a-z0-9]+(?:-[a-z0-9]+)*\z/
+```
+
+### Verbose Mode for Complex Patterns
+
+```ruby
+# x flag — whitespace and comments ignored, dramatically more readable
+CREDIT_CARD = /\A
+  (?<type>
+    4\d{12}(?:\d{3})?        # Visa: starts with 4, 13 or 16 digits
+    | 5[1-5]\d{14}           # Mastercard: starts with 51-55, 16 digits
+    | 3[47]\d{13}            # Amex: starts with 34 or 37, 15 digits
+    | 6(?:011|5\d{2})\d{12}  # Discover: starts with 6011 or 65, 16 digits
+  )
+\z/x
+
+# Without x flag — unreadable
+CREDIT_CARD_UGLY = /\A(?:4\d{12}(?:\d{3})?|5[1-5]\d{14}|3[47]\d{13}|6(?:011|5\d{2})\d{12})\z/
+```
+
+### Substitution
+
+```ruby
+# sub — first occurrence
+"hello world world".sub(/world/, "Ruby")  # => "hello Ruby world"
+
+# gsub — all occurrences
+"hello world world".gsub(/world/, "Ruby")  # => "hello Ruby Ruby"
+
+# gsub with block
+"ORD-001 and ORD-002".gsub(/ORD-(\d+)/) { |match| "Order ##{$1}" }
+# => "Order #001 and Order #002"
+
+# gsub with hash
+"cat and dog".gsub(/cat|dog/, "cat" => "feline", "dog" => "canine")
+# => "feline and canine"
+
+# Remove matching content
+"Hello, World!".gsub(/[^a-zA-Z ]/, "")  # => "Hello World"
+```
+
+### Performance
+
+```ruby
+# Compile regex once with a constant — don't rebuild per call
+EMAIL_PATTERN = /\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i.freeze
+
+# BAD: Regex rebuilt on every call
+def valid_email?(email)
+  email.match?(/\A[\w+\-.]+@[a-z\d\-]+(\.[a-z\d\-]+)*\.[a-z]+\z/i)
+end
+
+# GOOD: Regex compiled once
+def valid_email?(email)
+  email.match?(EMAIL_PATTERN)
+end
+
+# Prefer match? over =~ when you don't need captures
+"test".match?(/\d/)  # Fastest — no MatchData allocated
+"test" =~ /\d/       # Slower — allocates MatchData
+"test".match(/\d/)   # Slowest — allocates MatchData object
+```
+
+## Why This Is Good
+
+- **`match?` is fastest.** When you only need true/false, `match?` avoids allocating a MatchData object — 2-3x faster than `=~`.
+- **Named captures are self-documenting.** `md[:year]` is clearer than `md[3]`. The reader doesn't need to count capture groups.
+- **Verbose mode (`x`) makes complex patterns readable.** Comments explain each part. Whitespace groups related sections.
+- **Constants avoid recompilation.** A regex literal in a method body is recompiled on every call. A frozen constant is compiled once.
+
+## Anti-Pattern
+
+```ruby
+# BAD: Regex where a string method would do
+email.match?(/example\.com/) 
+email.include?("example.com")   # Simpler, faster, clearer
+
+"hello world".match?(/\Ahello/)
+"hello world".start_with?("hello")  # No regex needed
+
+name.gsub(/\s+/, " ")
+name.squeeze(" ")  # Collapses repeated spaces without regex
+```
+
+## When To Apply
+
+- **Pattern validation** — emails, phone numbers, UUIDs, reference formats.
+- **Extraction** — pulling structured data from strings (log parsing, URL matching).
+- **Complex substitution** — replacing patterns with computed values.
+- **Named captures** — whenever you have 2+ capture groups.
+
+## When NOT To Apply
+
+- **Simple string checks.** `include?`, `start_with?`, `end_with?`, `==` are clearer and faster than regex for exact matches.
+- **HTML/XML parsing.** Use Nokogiri, not regex. Regex can't handle nested structures.
+- **Email validation in production.** Use `URI::MailTo::EMAIL_REGEXP` or better yet, just send a confirmation email — that's the real validation.
+- **Complex parsing.** If the regex exceeds 3 lines even in verbose mode, consider a proper parser (StringScanner, Parslet, or a state machine).

data/skills/ruby/result_objects.md

@@ -0,0 +1,200 @@
+# Ruby: Result Objects
+
+## Pattern
+
+Instead of returning mixed types (record or nil, true or false) or raising exceptions for expected failures, return a Result object that explicitly represents success or failure. The caller inspects the result instead of rescuing exceptions.
+
+```ruby
+# Simple Result using Data.define (Ruby 3.2+)
+Result = Data.define(:success, :value, :error) do
+  def success? = success
+  def failure? = !success
+
+  def self.success(value)
+    new(success: true, value: value, error: nil)
+  end
+
+  def self.failure(error)
+    new(success: false, value: nil, error: error)
+  end
+end
+```
+
+```ruby
+# Service object using Result
+class Orders::CreateService
+  def self.call(params, user)
+    order = user.orders.build(params)
+
+    unless order.valid?
+      return Result.failure(order.errors.full_messages.join(", "))
+    end
+
+    ActiveRecord::Base.transaction do
+      order.save!
+      OrderConfirmationJob.perform_later(order.id)
+    end
+
+    Result.success(order)
+  rescue ActiveRecord::RecordInvalid => e
+    Result.failure(e.message)
+  end
+end
+
+# The caller handles both cases explicitly — no rescue needed
+result = Orders::CreateService.call(params, current_user)
+
+if result.success?
+  redirect_to result.value, notice: "Order created."
+else
+  flash.now[:alert] = result.error
+  render :new, status: :unprocessable_entity
+end
+```
+
+### Result with Error Codes
+
+```ruby
+# More structured for API responses
+Result = Data.define(:success, :value, :error, :error_code) do
+  def success? = success
+  def failure? = !success
+
+  def self.success(value)
+    new(success: true, value: value, error: nil, error_code: nil)
+  end
+
+  def self.failure(error, code: :unknown)
+    new(success: false, value: nil, error: error, error_code: code)
+  end
+end
+
+class Credits::DeductionService
+  def self.call(user, amount)
+    if user.credit_balance < amount
+      return Result.failure("Insufficient credits. Balance: #{user.credit_balance}, needed: #{amount}",
+                            code: :insufficient_credits)
+    end
+
+    if user.suspended?
+      return Result.failure("Account suspended", code: :account_suspended)
+    end
+
+    user.deduct_credits!(amount)
+    Result.success(user.credit_balance)
+  end
+end
+
+# API controller maps error codes to HTTP statuses
+result = Credits::DeductionService.call(current_user, credits_needed)
+
+unless result.success?
+  status = case result.error_code
+           when :insufficient_credits then :payment_required
+           when :account_suspended then :forbidden
+           else :unprocessable_entity
+           end
+  render json: { error: result.error }, status: status
+  return
+end
+```
+
+### Result with Struct (Pre-Ruby 3.2)
+
+```ruby
+Result = Struct.new(:success, :value, :error, keyword_init: true) do
+  def success? = success
+  def failure? = !success
+
+  def self.success(value)
+    new(success: true, value: value)
+  end
+
+  def self.failure(error)
+    new(success: false, error: error)
+  end
+end
+```
+
+### Chaining Results (Railway-Oriented Programming)
+
+```ruby
+class Orders::CheckoutPipeline
+  def self.call(params, user)
+    validate(params)
+      .then { |p| reserve_inventory(p) }
+      .then { |reservation| charge_payment(user, reservation) }
+      .then { |charge| create_order(user, params, charge) }
+      .then { |order| send_notifications(order) }
+  end
+
+  private
+
+  def self.validate(params)
+    return Result.failure("Missing address") if params[:address].blank?
+    Result.success(params)
+  end
+
+  def self.reserve_inventory(params)
+    reservation = Inventory::Reserve.call(params[:items])
+    reservation.success? ? Result.success(reservation) : Result.failure(reservation.error)
+  end
+
+  # Each step returns Result.success or Result.failure
+  # .then only executes if the previous result was success
+end
+
+# Add .then to Result
+Result = Data.define(:success, :value, :error) do
+  def success? = success
+  def failure? = !success
+
+  def then
+    return self if failure?
+    yield(value)
+  end
+
+  def self.success(value) = new(success: true, value: value, error: nil)
+  def self.failure(error) = new(success: false, value: nil, error: error)
+end
+```
+
+## Why This Is Good
+
+- **Explicit over implicit.** The return type tells you both success and failure are possible. No surprise `nil` returns or unexpected exceptions.
+- **The caller decides how to handle failure.** A controller renders an error page. A background job retries. A CLI prints a message. The service doesn't dictate error handling.
+- **No exceptions for expected failures.** "Insufficient credits" is not exceptional — it's a normal business outcome. Exceptions should be for unexpected failures (database down, network timeout).
+- **Chainable.** `.then` enables railway-oriented programming where the pipeline short-circuits on the first failure.
+- **Testable.** Assert `result.success?` and `result.value` — clean, specific, no `assert_raises` for business logic failures.
+
+## Anti-Pattern
+
+Mixed return types or exceptions for flow control:
+
+```ruby
+# BAD: Returns an Order on success, a String on failure
+def create_order(params)
+  order = Order.create!(params)
+  order
+rescue ActiveRecord::RecordInvalid => e
+  e.message  # Returns a String — caller must check type
+end
+
+# BAD: Raises for expected business failures
+def deduct_credits(user, amount)
+  raise InsufficientCredits if user.balance < amount  # Expected outcome, not exceptional
+  user.deduct!(amount)
+end
+```
+
+## When To Apply
+
+- **Every service object.** Services should return Results, not raise or return mixed types.
+- **Operations with known failure modes.** Payment declined, insufficient credits, validation failed, rate limited — all expected outcomes.
+- **Multi-step workflows.** Each step returns a Result. The pipeline short-circuits on failure.
+
+## When NOT To Apply
+
+- **Simple model methods.** `order.total` returns a number. It doesn't need a Result wrapper.
+- **Truly exceptional failures.** Database connection lost, out of memory, unexpected nil — these should raise exceptions. They're not business outcomes.
+- **Single-line lookups.** `User.find(id)` raising `RecordNotFound` is fine — it's the Rails convention and rescued at the controller level.