rubyn-code 0.1.0

data/skills/refactoring/extract_method.md

@@ -0,0 +1,185 @@
+# Refactoring: Extract Method
+
+## Pattern
+
+When a method is too long or a code fragment needs a comment to explain what it does, extract that fragment into a method whose name explains the intent. The extracted method replaces the comment.
+
+```ruby
+# BEFORE: Long method with inline comments explaining sections
+class Orders::InvoiceGenerator
+  def generate(order)
+    # Calculate line item totals
+    line_totals = order.line_items.map do |item|
+      {
+        name: item.product.name,
+        quantity: item.quantity,
+        unit_price: item.unit_price,
+        total: item.quantity * item.unit_price
+      }
+    end
+
+    # Calculate subtotal
+    subtotal = line_totals.sum { |lt| lt[:total] }
+
+    # Apply discount if applicable
+    discount = 0
+    if order.discount_code.present?
+      discount_record = Discount.find_by(code: order.discount_code)
+      if discount_record&.active?
+        discount = case discount_record.discount_type
+                   when "percentage" then subtotal * (discount_record.value / 100.0)
+                   when "fixed" then discount_record.value
+                   else 0
+                   end
+      end
+    end
+
+    # Calculate tax
+    tax_rate = TaxRate.for(order.shipping_address.state)
+    tax = (subtotal - discount) * tax_rate
+
+    # Build invoice
+    {
+      order_reference: order.reference,
+      line_items: line_totals,
+      subtotal: subtotal,
+      discount: discount,
+      tax: tax,
+      total: subtotal - discount + tax,
+      generated_at: Time.current
+    }
+  end
+end
+```
+
+```ruby
+# AFTER: Each section extracted into a named method
+class Orders::InvoiceGenerator
+  def generate(order)
+    line_totals = itemize(order.line_items)
+    subtotal = sum_totals(line_totals)
+    discount = calculate_discount(order.discount_code, subtotal)
+    tax = calculate_tax(order.shipping_address, subtotal - discount)
+
+    build_invoice(order, line_totals:, subtotal:, discount:, tax:)
+  end
+
+  private
+
+  def itemize(line_items)
+    line_items.map do |item|
+      {
+        name: item.product.name,
+        quantity: item.quantity,
+        unit_price: item.unit_price,
+        total: item.quantity * item.unit_price
+      }
+    end
+  end
+
+  def sum_totals(line_totals)
+    line_totals.sum { |lt| lt[:total] }
+  end
+
+  def calculate_discount(code, subtotal)
+    return 0 if code.blank?
+
+    discount = Discount.active.find_by(code: code)
+    return 0 unless discount
+
+    case discount.discount_type
+    when "percentage" then subtotal * (discount.value / 100.0)
+    when "fixed" then discount.value
+    else 0
+    end
+  end
+
+  def calculate_tax(address, taxable_amount)
+    rate = TaxRate.for(address.state)
+    taxable_amount * rate
+  end
+
+  def build_invoice(order, line_totals:, subtotal:, discount:, tax:)
+    {
+      order_reference: order.reference,
+      line_items: line_totals,
+      subtotal: subtotal,
+      discount: discount,
+      tax: tax,
+      total: subtotal - discount + tax,
+      generated_at: Time.current
+    }
+  end
+end
+```
+
+## Why This Is Good
+
+- **The public method reads like a summary.** `generate` is 5 lines that describe the algorithm at a high level: itemize, sum, discount, tax, build. You can understand the entire flow without reading implementation details.
+- **Each private method has one purpose and a descriptive name.** `calculate_discount` replaces 8 lines and a comment. The method name IS the comment — and it can't go stale.
+- **Independently testable.** You can test `calculate_discount` with various codes, types, and amounts without generating an entire invoice.
+- **Reusable.** If another part of the app needs discount calculation, `calculate_discount` is available. Inline code in a long method is not.
+- **Safe to refactor further.** `calculate_discount` is now isolated. Replacing the case statement with polymorphism is straightforward.
+
+## Related Refactoring: Replace Temp with Query
+
+When a temporary variable holds a computed value that could be a method call, replace the variable with a method. This makes the computation reusable and the code more readable.
+
+```ruby
+# BEFORE: Temporary variables
+def price
+  base_price = quantity * unit_price
+  discount_factor = if base_price > 1000
+                      0.95
+                    elsif base_price > 500
+                      0.98
+                    else
+                      1.0
+                    end
+  base_price * discount_factor
+end
+
+# AFTER: Replace temps with query methods
+def price
+  base_price * discount_factor
+end
+
+private
+
+def base_price
+  quantity * unit_price
+end
+
+def discount_factor
+  if base_price > 1000
+    0.95
+  elsif base_price > 500
+    0.98
+  else
+    1.0
+  end
+end
+```
+
+## When To Apply
+
+- **A method is longer than 10 lines.** Extract until the public method is a readable summary.
+- **You write a comment to explain a section.** The comment is the method name. Extract the section and delete the comment.
+- **The same code fragment appears in multiple methods.** Extract once, call from both places.
+- **A conditional body is more than 2-3 lines.** Extract the body into a method named for what it does, not how:
+
+```ruby
+# Before
+if order.total > 500 && order.user.loyalty_tier == :gold && !order.used_promo?
+  # ... 5 lines applying VIP discount
+end
+
+# After
+apply_vip_discount(order) if eligible_for_vip_discount?(order)
+```
+
+## When NOT To Apply
+
+- **The method is already 3-5 clear lines.** Don't extract a 2-line block into a method for purity. Extract for clarity, not for line count.
+- **The extracted method would need 5+ parameters.** Too many parameters suggest the method needs an object, not an extraction. Consider an Introduce Parameter Object refactoring first.
+- **The code is only used once and is already clear.** Extraction adds a level of indirection. If the inline code reads naturally, leave it.

data/skills/refactoring/replace_conditional.md

@@ -0,0 +1,211 @@
+# Refactoring: Replace Conditional with Polymorphism
+
+## Pattern
+
+When a `case/when` or `if/elsif` chain switches on a type to determine behavior, replace it with polymorphic objects. Each branch becomes a class that implements the same interface.
+
+```ruby
+# BEFORE: case/when switches on type to determine pricing
+class SubscriptionBiller
+  def monthly_charge(subscription)
+    case subscription.plan
+    when "free"
+      0
+    when "pro"
+      19_00
+    when "team"
+      base = 49_00
+      extra_seats = [subscription.seats - 5, 0].max
+      base + (extra_seats * 10_00)
+    when "enterprise"
+      custom_price = subscription.negotiated_price
+      custom_price || 199_00
+    end
+  end
+
+  def usage_limit(subscription)
+    case subscription.plan
+    when "free" then 30
+    when "pro" then 1_000
+    when "team" then 5_000
+    when "enterprise" then Float::INFINITY
+    end
+  end
+
+  def features(subscription)
+    case subscription.plan
+    when "free" then [:basic_ai]
+    when "pro" then [:basic_ai, :pro_mode, :export]
+    when "team" then [:basic_ai, :pro_mode, :export, :team_sharing, :admin_panel]
+    when "enterprise" then [:basic_ai, :pro_mode, :export, :team_sharing, :admin_panel, :sso, :audit_log]
+    end
+  end
+end
+```
+
+```ruby
+# AFTER: Each plan is a class with its own behavior
+module Plans
+  class Free
+    def monthly_charge(_subscription) = 0
+    def usage_limit = 30
+    def features = [:basic_ai]
+  end
+
+  class Pro
+    def monthly_charge(_subscription) = 19_00
+    def usage_limit = 1_000
+    def features = [:basic_ai, :pro_mode, :export]
+  end
+
+  class Team
+    def monthly_charge(subscription)
+      base = 49_00
+      extra_seats = [subscription.seats - 5, 0].max
+      base + (extra_seats * 10_00)
+    end
+
+    def usage_limit = 5_000
+    def features = [:basic_ai, :pro_mode, :export, :team_sharing, :admin_panel]
+  end
+
+  class Enterprise
+    def monthly_charge(subscription)
+      subscription.negotiated_price || 199_00
+    end
+
+    def usage_limit = Float::INFINITY
+    def features = [:basic_ai, :pro_mode, :export, :team_sharing, :admin_panel, :sso, :audit_log]
+  end
+
+  REGISTRY = {
+    "free" => Free.new,
+    "pro" => Pro.new,
+    "team" => Team.new,
+    "enterprise" => Enterprise.new
+  }.freeze
+
+  def self.for(plan_name)
+    REGISTRY.fetch(plan_name)
+  end
+end
+
+# Subscription delegates to its plan
+class Subscription < ApplicationRecord
+  def plan_object
+    Plans.for(plan)
+  end
+
+  def monthly_charge
+    plan_object.monthly_charge(self)
+  end
+
+  def usage_limit
+    plan_object.usage_limit
+  end
+
+  def features
+    plan_object.features
+  end
+end
+```
+
+## Why This Is Good
+
+- **Adding a new plan doesn't modify existing code.** A "Starter" plan means one new class. `Free`, `Pro`, `Team`, and `Enterprise` are untouched.
+- **All behavior for one plan is in one place.** Open `Plans::Team` to see pricing, limits, and features together. No scanning across three `case` statements.
+- **Each plan is independently testable.** `Plans::Team.new.monthly_charge(sub_with_10_seats)` — no branching, no other plans involved.
+- **Eliminates the "parallel case statements" code smell.** Three methods all switching on `subscription.plan` is a sign that `plan` wants to be an object.
+
+# Refactoring: Replace Nested Conditional with Guard Clauses
+
+## Pattern
+
+When a method has deep nesting or complex conditional logic, use guard clauses to handle edge cases and error conditions early, leaving the main logic un-nested.
+
+```ruby
+# BEFORE: Deep nesting
+def process_payment(order)
+  if order.present?
+    if order.total > 0
+      if order.user.payment_method.present?
+        if order.user.payment_method.valid?
+          result = PaymentGateway.charge(order.user.payment_method, order.total)
+          if result.success?
+            order.update!(paid: true)
+            { success: true, transaction_id: result.id }
+          else
+            { success: false, error: result.error_message }
+          end
+        else
+          { success: false, error: "Invalid payment method" }
+        end
+      else
+        { success: false, error: "No payment method on file" }
+      end
+    else
+      { success: false, error: "Order total must be positive" }
+    end
+  else
+    { success: false, error: "Order not found" }
+  end
+end
+```
+
+```ruby
+# AFTER: Guard clauses handle edge cases first
+def process_payment(order)
+  return { success: false, error: "Order not found" } unless order
+  return { success: false, error: "Order total must be positive" } unless order.total > 0
+  return { success: false, error: "No payment method on file" } unless order.user.payment_method
+  return { success: false, error: "Invalid payment method" } unless order.user.payment_method.valid?
+
+  result = PaymentGateway.charge(order.user.payment_method, order.total)
+
+  return { success: false, error: result.error_message } unless result.success?
+
+  order.update!(paid: true)
+  { success: true, transaction_id: result.id }
+end
+```
+
+## Why This Is Good
+
+- **Linear reading.** Each guard clause handles one error and returns. After all guards pass, the happy path runs with no nesting. You read top to bottom, not inside-out.
+- **The happy path is at the natural indentation level.** No 5-level-deep nesting to find the actual business logic. The important code stands out visually.
+- **Each guard is independent.** Adding a new validation (e.g., "order not already paid") means adding one `return unless` line, not wrapping another `if` around everything.
+- **Easier to test.** Each guard clause corresponds to one test case. The tests mirror the guard order.
+
+## When To Apply
+
+- **Nested conditionals deeper than 2 levels.** If you're at 3+ levels of `if`, guards will flatten it.
+- **Multiple preconditions before the main logic.** Auth checks, validation, null checks — these are guards.
+- **The "else" branches are error handling.** If every `else` returns an error, those are guard clauses waiting to be extracted.
+- **Case statements that switch on a type.** 3+ branches with distinct behavior → polymorphism. 2 branches → maybe keep the conditional.
+
+## When NOT To Apply
+
+- **Simple if/else with balanced branches.** `if premium? then charge(19) else charge(0) end` — both branches are the "main logic," not guards.
+- **Two types that will never grow.** Boolean branching (`if active?`) rarely benefits from polymorphism.
+- **The conditional is already clear at one level of nesting.** Don't refactor for refactoring's sake.
+
+## Edge Cases
+
+**Guard clauses in Rails controllers:**
+
+```ruby
+def update
+  @order = current_user.orders.find_by(id: params[:id])
+  return head :not_found unless @order
+  return head :forbidden unless @order.editable?
+
+  if @order.update(order_params)
+    redirect_to @order
+  else
+    render :edit, status: :unprocessable_entity
+  end
+end
+```
+
+**Combining both refactorings:**
+First flatten with guard clauses, then extract polymorphism for the remaining branching logic. Guard clauses handle preconditions; polymorphism handles type-based behavior.

data/skills/refactoring/value_objects.md

@@ -0,0 +1,246 @@
+# Refactoring: Replace Primitive with Value Object
+
+## Pattern
+
+When primitives (strings, integers, floats) carry domain meaning, replace them with value objects that encapsulate the value, its validation, and its behavior. This eliminates scattered validation logic and gives you a natural place for formatting, comparison, and conversion methods.
+
+```ruby
+# BEFORE: Money as cents integer, scattered formatting
+class Order < ApplicationRecord
+  def formatted_total
+    "$#{format('%.2f', total / 100.0)}"
+  end
+
+  def total_with_tax
+    total + (total * 0.08).round
+  end
+end
+
+class Invoice
+  def formatted_amount
+    "$#{format('%.2f', amount_cents / 100.0)}"  # Same logic, different variable name
+  end
+end
+
+# AFTER: Money value object
+class Money
+  include Comparable
+  attr_reader :cents, :currency
+
+  def initialize(cents, currency = "USD")
+    @cents = Integer(cents)
+    @currency = currency.to_s.upcase.freeze
+    freeze
+  end
+
+  def self.from_dollars(dollars, currency = "USD")
+    new((Float(dollars) * 100).round, currency)
+  end
+
+  def to_f
+    cents / 100.0
+  end
+
+  def to_s
+    "$#{format('%.2f', to_f)}"
+  end
+
+  def +(other)
+    assert_same_currency!(other)
+    self.class.new(cents + other.cents, currency)
+  end
+
+  def -(other)
+    assert_same_currency!(other)
+    self.class.new(cents - other.cents, currency)
+  end
+
+  def *(multiplier)
+    self.class.new((cents * multiplier).round, currency)
+  end
+
+  def <=>(other)
+    return nil unless other.is_a?(Money) && currency == other.currency
+    cents <=> other.cents
+  end
+
+  def zero?
+    cents.zero?
+  end
+
+  def positive?
+    cents.positive?
+  end
+
+  private
+
+  def assert_same_currency!(other)
+    raise ArgumentError, "Currency mismatch: #{currency} vs #{other.currency}" unless currency == other.currency
+  end
+end
+
+# Usage — clean, safe, reusable
+price = Money.new(19_99)
+tax = price * 0.08
+total = price + tax
+total.to_s  # => "$21.59"
+total > Money.new(20_00)  # => true
+```
+
+```ruby
+# BEFORE: Email as a string, validated in multiple places
+class User < ApplicationRecord
+  validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
+  before_validation { self.email = email&.downcase&.strip }
+end
+
+class Invite < ApplicationRecord
+  validates :recipient_email, format: { with: URI::MailTo::EMAIL_REGEXP }
+  before_validation { self.recipient_email = recipient_email&.downcase&.strip }
+end
+
+# AFTER: Email value object
+class Email
+  REGEXP = URI::MailTo::EMAIL_REGEXP
+
+  attr_reader :address
+
+  def initialize(raw)
+    @address = raw.to_s.downcase.strip.freeze
+    raise ArgumentError, "Invalid email: #{raw}" unless valid?
+    freeze
+  end
+
+  def valid?
+    REGEXP.match?(@address)
+  end
+
+  def domain
+    @address.split("@").last
+  end
+
+  def to_s = @address
+  def ==(other) = other.is_a?(Email) && address == other.address
+  alias_method :eql?, :==
+  def hash = address.hash
+end
+
+# Usage
+email = Email.new("  Alice@Example.COM  ")
+email.to_s     # => "alice@example.com"
+email.domain   # => "example.com"
+```
+
+# Refactoring: Introduce Parameter Object
+
+## Pattern
+
+When the same group of parameters is passed together to multiple methods, bundle them into an object.
+
+```ruby
+# BEFORE: Same 3 params passed everywhere
+def search_orders(start_date, end_date, status)
+  Order.where(created_at: start_date..end_date, status: status)
+end
+
+def export_orders(start_date, end_date, status, format)
+  orders = search_orders(start_date, end_date, status)
+  # ...
+end
+
+def count_orders(start_date, end_date, status)
+  search_orders(start_date, end_date, status).count
+end
+```
+
+```ruby
+# AFTER: Parameter object bundles related params
+class DateRange
+  attr_reader :start_date, :end_date
+
+  def initialize(start_date:, end_date:)
+    @start_date = start_date.to_date
+    @end_date = end_date.to_date
+    raise ArgumentError, "start must be before end" if @start_date > @end_date
+    freeze
+  end
+
+  def to_range
+    start_date..end_date
+  end
+
+  def days
+    (end_date - start_date).to_i
+  end
+
+  def include?(date)
+    to_range.include?(date)
+  end
+end
+
+OrderFilter = Data.define(:date_range, :status) do
+  def to_scope(base = Order.all)
+    scope = base.where(created_at: date_range.to_range)
+    scope = scope.where(status: status) if status.present?
+    scope
+  end
+end
+
+# Usage — clean, validated, reusable
+filter = OrderFilter.new(
+  date_range: DateRange.new(start_date: 30.days.ago, end_date: Date.today),
+  status: "pending"
+)
+
+orders = filter.to_scope
+count = filter.to_scope.count
+export = Orders::Exporter.call(filter.to_scope, format: :csv)
+```
+
+## Why This Is Good
+
+- **Validation in one place.** `Money.new(-100)` is valid (a refund). `Email.new("not-valid")` raises immediately. No scattered regex checks.
+- **Behavior on the object.** `money + other_money` handles currency matching. `email.domain` extracts the domain. Primitives have none of this.
+- **Type safety through construction.** If a method accepts a `Money`, you know it's a valid integer of cents with a currency. If it accepts an `Integer`, it could be anything.
+- **Eliminates duplicated formatting.** `money.to_s` always returns `"$19.99"`. No more `"$#{format('%.2f', cents / 100.0)}"` repeated in 12 views.
+- **Comparable, hashable, freezable.** Value objects work as hash keys, in Sets, and in sorted collections. Primitives require manual comparison logic.
+
+## When To Apply
+
+- **The same primitive has validation logic in 2+ places.** Email format, money formatting, phone number parsing — extract once.
+- **The same group of parameters travels together.** `start_date, end_date` → `DateRange`. `street, city, state, zip` → `Address`.
+- **Arithmetic or comparison on the primitive.** If you add, subtract, or compare cents in 5 places, a Money object centralizes the logic.
+- **A method has 4+ parameters.** Look for parameter groups to bundle.
+
+## When NOT To Apply
+
+- **A string that's just a string.** A user's `name` field doesn't need a `Name` value object unless you need parsing (first/last) or validation logic.
+- **One-off usage.** If a date range is used in exactly one query, inlining `where(created_at: start..end)` is fine.
+- **Don't create value objects for configuration.** `timeout: 30` doesn't need a `Timeout` value object.
+
+## Edge Cases
+
+**Value objects as ActiveRecord attributes:**
+Use `composed_of` or custom attribute types:
+
+```ruby
+class Order < ApplicationRecord
+  composed_of :total_money,
+    class_name: "Money",
+    mapping: [%w[total_cents cents], %w[currency currency]]
+end
+
+order.total_money  # => Money(1999, "USD")
+order.total_money.to_s  # => "$19.99"
+```
+
+**Ruby 3.2+ `Data` class for simple value objects:**
+
+```ruby
+Point = Data.define(:x, :y)
+point = Point.new(x: 1, y: 2)
+point.x  # => 1
+point.frozen?  # => true
+```
+
+`Data.define` is perfect for simple value objects that don't need custom behavior beyond attribute access.