rubyn-code 0.1.0

data/skills/refactoring/code_smells.md

@@ -0,0 +1,251 @@
+# Code Smells: Recognition and Remedies
+
+## What Are Code Smells?
+
+Code smells are surface indicators that usually correspond to deeper design problems. They're not bugs — the code works — but they signal that the code will be increasingly painful to maintain, extend, and test. Recognizing smells is the first step; the refactoring that fixes them is the second.
+
+## Bloaters
+
+Smells where code has grown too large to work with effectively.
+
+### Long Method
+
+**Smell:** A method longer than ~10 lines, especially if it has comments explaining sections.
+
+```ruby
+# SMELL: 30+ lines doing multiple things
+def process_order(params)
+  # Validate
+  return error("Missing address") if params[:address].blank?
+  return error("No items") if params[:items].empty?
+
+  # Create order
+  order = Order.new(address: params[:address], user: current_user)
+  params[:items].each do |item|
+    product = Product.find(item[:id])
+    order.line_items.build(product: product, quantity: item[:qty], price: product.price)
+  end
+
+  # Calculate totals
+  order.subtotal = order.line_items.sum { |li| li.quantity * li.price }
+  order.tax = order.subtotal * 0.08
+  order.total = order.subtotal + order.tax
+
+  # Save and notify
+  order.save!
+  OrderMailer.confirmation(order).deliver_later
+  WarehouseService.notify(order)
+  order
+end
+```
+
+**Fix:** Extract Method. Each comment-delimited section becomes a named method. Or better — each section becomes a service object.
+
+### Large Class
+
+**Smell:** A class with 200+ lines, 15+ methods, or 7+ instance variables. In Rails, models that include 5+ concerns.
+
+**Fix:** Extract Class. Identify clusters of methods that work together and move them into collaborator objects (service objects, value objects, query objects).
+
+### Long Parameter List
+
+**Smell:** A method with 4+ parameters, especially positional ones.
+
+```ruby
+# SMELL
+def create_user(email, name, role, company_name, plan, referral_code, notify)
+
+# FIX: Introduce Parameter Object or use keyword arguments
+def create_user(email:, name:, role:, company_name:, plan:, referral_code: nil, notify: true)
+
+# BETTER FIX: If parameters are always passed together, create a value object
+RegistrationParams = Data.define(:email, :name, :role, :company_name, :plan, :referral_code)
+def create_user(params, notify: true)
+```
+
+### Primitive Obsession
+
+**Smell:** Using strings, integers, or hashes where a domain object would be clearer.
+
+```ruby
+# SMELL: Money as a float, address as a hash
+order.total = 19.99
+order.address = { street: "123 Main", city: "Austin", state: "TX", zip: "78701" }
+
+# FIX: Replace Data Value with Object
+order.total = Money.new(19_99, "USD")
+order.address = Address.new(street: "123 Main", city: "Austin", state: "TX", zip: "78701")
+```
+
+Value objects have behavior — `money.to_s`, `address.full`, `money + other_money` — that primitives don't.
+
+## Couplers
+
+Smells where classes are too intertwined.
+
+### Feature Envy
+
+**Smell:** A method that uses more data from another object than from its own.
+
+```ruby
+# SMELL: This method on OrderPresenter mostly accesses user attributes
+class OrderPresenter
+  def shipping_label(order)
+    "#{order.user.name}\n#{order.user.address.street}\n#{order.user.address.city}, #{order.user.address.state} #{order.user.address.zip}"
+  end
+end
+
+# FIX: Move Method — the method belongs on Address or User
+class Address
+  def to_label(name)
+    "#{name}\n#{street}\n#{city}, #{state} #{zip}"
+  end
+end
+
+# Usage
+order.user.address.to_label(order.user.name)
+```
+
+### Message Chains (Law of Demeter Violation)
+
+**Smell:** `order.user.company.billing_address.country.tax_rate` — a long chain of navigating object relationships.
+
+```ruby
+# SMELL: Caller knows the entire object graph
+tax_rate = order.user.company.billing_address.country.tax_rate
+
+# FIX: Hide Delegate — each object only talks to its immediate neighbors
+class Order
+  delegate :tax_rate, to: :user, prefix: false
+
+  # Or a dedicated method
+  def applicable_tax_rate
+    user.billing_tax_rate
+  end
+end
+
+class User
+  def billing_tax_rate
+    company.billing_tax_rate
+  end
+end
+
+class Company
+  def billing_tax_rate
+    billing_address.country_tax_rate
+  end
+end
+
+# Usage
+order.applicable_tax_rate
+```
+
+### Inappropriate Intimacy
+
+**Smell:** Two classes that access each other's internal details excessively.
+
+```ruby
+# SMELL: Service reaches into order's internals
+class ShippingCalculator
+  def calculate(order)
+    weight = order.instance_variable_get(:@total_weight)  # Accessing internals!
+    order.line_items.each { |li| li.instance_variable_set(:@shipping_cost, weight * 0.5) }
+  end
+end
+
+# FIX: Use public interfaces
+class ShippingCalculator
+  def calculate(order)
+    weight = order.total_weight  # Public method
+    weight * shipping_rate_per_kg
+  end
+end
+```
+
+## Dispensables
+
+Smells where something isn't needed.
+
+### Dead Code
+
+**Smell:** Methods, variables, classes, or branches that are never executed.
+
+```ruby
+# SMELL: Method hasn't been called since 2023
+def legacy_import(csv_path)
+  # 40 lines of import logic
+end
+
+# SMELL: Unreachable branch
+def status_label
+  case status
+  when "active" then "Active"
+  when "inactive" then "Inactive"
+  when "deleted" then "Deleted"  # status is never "deleted" — soft delete uses discarded_at
+  end
+end
+```
+
+**Fix:** Delete it. Version control has the history if you ever need it. Dead code creates confusion ("is this still used?"), false grep results, and maintenance burden.
+
+### Speculative Generality
+
+**Smell:** Abstractions, hooks, parameters, or classes that exist "in case we need them later" but have no current use.
+
+```ruby
+# SMELL: AbstractNotificationFactory that only has one subclass
+class AbstractNotificationFactory
+  def build(type, **opts)
+    raise NotImplementedError
+  end
+end
+
+class EmailNotificationFactory < AbstractNotificationFactory
+  def build(type, **opts)
+    # ... this is the only implementation
+  end
+end
+```
+
+**Fix:** Delete the abstraction. When you actually need a second factory, extract the interface then. YAGNI (You Ain't Gonna Need It).
+
+### Duplicate Code
+
+**Smell:** The same code structure in two or more places.
+
+```ruby
+# SMELL: Same pattern in two controllers
+class OrdersController < ApplicationController
+  def index
+    @orders = current_user.orders
+    @orders = @orders.where(status: params[:status]) if params[:status].present?
+    @orders = @orders.where("created_at >= ?", params[:from]) if params[:from].present?
+    @orders = @orders.page(params[:page])
+  end
+end
+
+class InvoicesController < ApplicationController
+  def index
+    @invoices = current_user.invoices
+    @invoices = @invoices.where(status: params[:status]) if params[:status].present?
+    @invoices = @invoices.where("created_at >= ?", params[:from]) if params[:from].present?
+    @invoices = @invoices.page(params[:page])
+  end
+end
+```
+
+**Fix:** Extract the filtering logic into a query object or a concern that both controllers use:
+
+```ruby
+class FilteredQuery
+  def self.call(scope, params)
+    scope = scope.where(status: params[:status]) if params[:status].present?
+    scope = scope.where("created_at >= ?", params[:from]) if params[:from].present?
+    scope.page(params[:page])
+  end
+end
+```
+
+## How Rubyn Uses This
+
+When analyzing code, Rubyn identifies these smells and suggests the specific refactoring to fix them. The recommendation always includes the smell name, why it matters, and the concrete transformation — not just "this method is too long."

data/skills/refactoring/command_query_separation.md

@@ -0,0 +1,166 @@
+# Refactoring: Separate Query from Modifier (CQS)
+
+## Pattern
+
+A method should either return a value (query) or change state (command), but not both. When a method does both — returns data AND has side effects — split it into two methods. This is the Command-Query Separation (CQS) principle.
+
+```ruby
+# BEFORE: Method both modifies state AND returns a value
+class ShoppingCart
+  def add_item(product, quantity: 1)
+    item = @items.find { |i| i.product == product }
+    if item
+      item.quantity += quantity
+    else
+      @items << CartItem.new(product: product, quantity: quantity)
+    end
+    calculate_total  # Returns the new total — side effect + return value mixed
+  end
+
+  def remove_expired_items
+    expired = @items.select { |item| item.product.expired? }
+    @items -= expired
+    expired  # Returns removed items AND modifies the cart
+  end
+end
+
+# Usage is confusing — does this return something? Change something? Both?
+total = cart.add_item(widget)
+removed = cart.remove_expired_items
+```
+
+```ruby
+# AFTER: Commands modify state. Queries return data. They don't overlap.
+class ShoppingCart
+  # COMMANDS: modify state, return nothing meaningful (or self for chaining)
+  def add_item(product, quantity: 1)
+    item = @items.find { |i| i.product == product }
+    if item
+      item.quantity += quantity
+    else
+      @items << CartItem.new(product: product, quantity: quantity)
+    end
+    nil  # Or `self` for chaining
+  end
+
+  def remove_expired_items
+    @items.reject! { |item| item.product.expired? }
+    nil
+  end
+
+  # QUERIES: return data, never modify state
+  def total
+    @items.sum { |item| item.quantity * item.product.price }
+  end
+
+  def expired_items
+    @items.select { |item| item.product.expired? }
+  end
+
+  def item_count
+    @items.sum(&:quantity)
+  end
+
+  def empty?
+    @items.empty?
+  end
+end
+
+# Usage is clear — commands do, queries ask
+cart.add_item(widget, quantity: 2)
+cart.remove_expired_items
+puts cart.total
+puts cart.expired_items.map(&:product_name)
+```
+
+### CQS in Rails
+
+```ruby
+# BEFORE: Scope that modifies data (violates CQS)
+class Order < ApplicationRecord
+  scope :archive_old, -> {
+    where(created_at: ...90.days.ago).update_all(archived: true)
+    # This is a command disguised as a scope — scopes should be queries
+  }
+end
+
+# AFTER: Scope queries, service commands
+class Order < ApplicationRecord
+  scope :archivable, -> { where(created_at: ...90.days.ago, archived: false) }
+end
+
+class Orders::ArchiveService
+  def self.call
+    count = Order.archivable.update_all(archived: true, archived_at: Time.current)
+    Result.new(success: true, count: count)
+  end
+end
+
+# Usage
+puts "#{Order.archivable.count} orders to archive"  # Query
+Orders::ArchiveService.call                           # Command
+```
+
+```ruby
+# BEFORE: Method that checks permission AND logs the attempt
+class Authorization
+  def authorized?(user, action)
+    allowed = user.permissions.include?(action)
+    AuditLog.create!(user: user, action: action, allowed: allowed)  # Side effect!
+    allowed
+  end
+end
+
+# Calling code doesn't expect a query to write to the database
+if auth.authorized?(user, :delete_order)  # Surprise! This created an audit record
+  order.destroy!
+end
+
+# AFTER: Separated
+class Authorization
+  def authorized?(user, action)
+    user.permissions.include?(action)
+  end
+
+  def check_and_log(user, action)
+    allowed = authorized?(user, action)
+    AuditLog.create!(user: user, action: action, allowed: allowed)
+    allowed
+  end
+end
+```
+
+## Why This Is Good
+
+- **Queries are safe to call anywhere.** If `total` only reads data, calling it in a view, a test, or a debug session never changes state. No surprises.
+- **Commands are explicit about mutation.** When you see `cart.add_item(widget)`, you know state is changing. When you see `cart.total`, you know it's read-only.
+- **Easier to test.** Queries are tested with simple assertions on return values. Commands are tested by checking state before and after. When they're mixed, you have to assert both.
+- **Easier to reason about.** In concurrent systems, queries are safe to parallelize. Commands need synchronization. Knowing which is which matters.
+- **Caching is safe for queries.** You can cache `cart.total` because calling it doesn't change anything. If `total` also triggered a recalculation and saved to the database, caching it would be dangerous.
+
+## When To Apply
+
+- **Methods that both return a value AND modify state.** These are CQS violations. Split them.
+- **ActiveRecord scopes that modify data.** Scopes should query. Services should command.
+- **Methods named like queries that have side effects.** `user.authorized?` shouldn't write to an audit log. `user.full_name` shouldn't trigger a name parsing service.
+- **APIs where calling a "getter" triggers unexpected behavior.** If reading a property sends an HTTP request, logs to a database, or increments a counter — separate the read from the write.
+
+## When NOT To Apply
+
+- **`save` and `update` return a boolean.** Rails' `order.save` both modifies state and returns true/false. This is a pragmatic CQS violation that Rails developers expect. Don't fight it.
+- **`pop` and `shift` on arrays.** These both modify the array and return the removed element. They're standard Ruby and universally understood.
+- **Idempotent cache operations.** `Rails.cache.fetch(key) { compute }` both reads and writes, but it's idempotent and universally expected. Don't split it.
+- **The split would make code significantly harder to use.** CQS is a guideline for clarity. If separating a method makes the API confusing, keep them together and document the behavior.
+
+## Edge Cases
+
+**`find_or_create_by` is a deliberate CQS violation:**
+```ruby
+user = User.find_or_create_by(email: "alice@example.com") do |u|
+  u.name = "Alice"
+end
+```
+This queries and potentially creates. It's a Rails convention that everyone understands. Don't wrap it in a service object for CQS purity.
+
+**The "Tell, Don't Ask" tension:**
+CQS says "separate queries from commands." Tell Don't Ask says "don't query an object then act on the result — tell the object to act." These can conflict. In practice, CQS applies to individual methods, and Tell Don't Ask applies to object interactions. Both are guidelines, not laws.

data/skills/refactoring/encapsulate_collection.md

@@ -0,0 +1,125 @@
+# Refactoring: Encapsulate Collection
+
+## Pattern
+
+When a class exposes a raw collection (array, hash) through a getter, external code can modify it without the owning class knowing. Encapsulate the collection by providing specific methods for adding, removing, and querying — never exposing the raw collection.
+
+```ruby
+# BEFORE: Exposed collection — anyone can mutate it
+class Order
+  attr_accessor :line_items
+
+  def initialize
+    @line_items = []
+  end
+
+  def total
+    @line_items.sum { |item| item.quantity * item.unit_price }
+  end
+end
+
+order = Order.new
+order.line_items << LineItem.new(quantity: 2, unit_price: 10_00)
+order.line_items.delete_at(0)  # External code mutates the collection
+order.line_items = []           # External code replaces the entire collection
+order.line_items.clear          # External code empties it
+# The Order has no control over its own state
+```
+
+```ruby
+# AFTER: Encapsulated — Order controls all access
+class Order
+  def initialize
+    @line_items = []
+  end
+
+  def add_item(product:, quantity:)
+    raise ArgumentError, "Quantity must be positive" unless quantity > 0
+
+    existing = @line_items.find { |li| li.product == product }
+    if existing
+      existing.quantity += quantity
+    else
+      @line_items << LineItem.new(product: product, quantity: quantity, unit_price: product.price)
+    end
+  end
+
+  def remove_item(product)
+    @line_items.reject! { |li| li.product == product }
+  end
+
+  def line_items
+    @line_items.dup.freeze  # Return a frozen copy — mutations don't affect the original
+  end
+
+  def item_count
+    @line_items.sum(&:quantity)
+  end
+
+  def empty?
+    @line_items.empty?
+  end
+
+  def total
+    @line_items.sum { |li| li.quantity * li.unit_price }
+  end
+end
+
+order = Order.new
+order.add_item(product: widget, quantity: 2)   # Controlled: validates, merges duplicates
+order.remove_item(widget)                       # Controlled: uses Order's own method
+order.line_items                                # Returns frozen copy — can read but not mutate
+order.line_items << something                   # FrozenError — can't modify the copy
+```
+
+## Why This Is Good
+
+- **Invariants are enforced.** `add_item` validates quantity, merges duplicates, and sets unit price from the product. Raw `<<` skips all of this.
+- **Change notification is possible.** If `add_item` needs to recalculate totals, trigger events, or update caches, it can. Raw mutation bypasses all hooks.
+- **The collection can't be replaced.** No `order.line_items = []` wiping the data. The only way to modify is through the Order's intentional interface.
+- **Frozen copies enable safe reads.** Callers can iterate, map, and filter the returned collection without accidentally modifying the Order's state.
+
+## When To Apply
+
+- **Any class that owns a collection.** If a class has an `attr_accessor` or `attr_reader` for an Array or Hash, encapsulate it.
+- **When the collection has rules.** No duplicates, maximum size, items must be valid, items must belong to the parent — these rules belong in the owning class, not scattered across callers.
+- **Domain objects and value objects.** `Cart`, `Order`, `Playlist`, `Team` — anything with a "contains items" relationship.
+
+## When NOT To Apply
+
+- **ActiveRecord associations.** `has_many :line_items` is already encapsulated by Rails with callbacks, validations, and scoping. Don't wrap it in another layer.
+- **Simple data transfer objects.** A Struct or Data class that just carries data doesn't need encapsulation — it's intentionally transparent.
+- **Internal implementation details.** If the collection is only used inside the class and never exposed, encapsulation isn't needed.
+
+## Edge Cases
+
+**Exposing an iterator instead of the collection:**
+
+```ruby
+def each_item(&block)
+  @line_items.each(&block)
+end
+include Enumerable  # Now Order is iterable but the array isn't exposed
+```
+
+**Hash encapsulation:**
+
+```ruby
+class Configuration
+  def initialize
+    @settings = {}
+  end
+
+  def set(key, value)
+    @settings[key.to_sym] = value
+  end
+
+  def get(key, default: nil)
+    @settings.fetch(key.to_sym, default)
+  end
+
+  def to_h
+    @settings.dup.freeze
+  end
+end
+```

data/skills/refactoring/extract_class.md

@@ -0,0 +1,138 @@
+# Refactoring: Extract Class
+
+## Pattern
+
+When a class has too many responsibilities — groups of data and methods that logically belong together — extract them into a new class. The original class delegates to the extracted class.
+
+```ruby
+# BEFORE: User model handles profile, settings, AND billing
+class User < ApplicationRecord
+  # Profile concern
+  def full_name = "#{first_name} #{last_name}"
+  def initials = "#{first_name[0]}#{last_name[0]}".upcase
+  def display_name = nickname.presence || full_name
+  def avatar_url = avatar.attached? ? avatar.url : gravatar_url
+  def gravatar_url = "https://gravatar.com/avatar/#{Digest::MD5.hexdigest(email)}"
+
+  # Billing concern
+  def active_subscription = subscriptions.active.last
+  def plan_name = active_subscription&.plan || "free"
+  def credit_balance = credit_ledger_entries.sum(:amount)
+  def can_afford?(credits) = credit_balance >= credits
+  def deduct_credits!(amount)
+    credit_ledger_entries.create!(amount: -amount, description: "Usage")
+  end
+  def billing_email = billing_email_override.presence || email
+  def billing_address = addresses.find_by(type: "billing")
+
+  # Settings concern
+  def notification_preferences = settings.dig("notifications") || {}
+  def email_notifications? = notification_preferences.fetch("email", true)
+  def theme = settings.dig("appearance", "theme") || "system"
+  def timezone = settings.dig("timezone") || "UTC"
+  def locale = settings.dig("locale") || "en"
+end
+```
+
+```ruby
+# AFTER: Extracted into focused collaborators
+
+class User < ApplicationRecord
+  has_one :profile, dependent: :destroy
+  has_one :billing_account, dependent: :destroy
+  has_one :user_settings, dependent: :destroy
+
+  delegate :full_name, :initials, :display_name, :avatar_url, to: :profile
+  delegate :credit_balance, :can_afford?, :deduct_credits!, :plan_name, to: :billing_account
+  delegate :email_notifications?, :theme, :timezone, :locale, to: :user_settings
+end
+
+class Profile < ApplicationRecord
+  belongs_to :user
+
+  def full_name = "#{user.first_name} #{user.last_name}"
+  def initials = "#{user.first_name[0]}#{user.last_name[0]}".upcase
+  def display_name = nickname.presence || full_name
+  def avatar_url = avatar.attached? ? avatar.url : gravatar_url
+
+  private
+
+  def gravatar_url = "https://gravatar.com/avatar/#{Digest::MD5.hexdigest(user.email)}"
+end
+
+class BillingAccount < ApplicationRecord
+  belongs_to :user
+  has_many :credit_ledger_entries
+  has_many :subscriptions
+
+  def active_subscription = subscriptions.active.last
+  def plan_name = active_subscription&.plan || "free"
+  def credit_balance = credit_ledger_entries.sum(:amount)
+  def can_afford?(credits) = credit_balance >= credits
+
+  def deduct_credits!(amount)
+    credit_ledger_entries.create!(amount: -amount, description: "Usage")
+  end
+end
+
+class UserSettings < ApplicationRecord
+  belongs_to :user
+
+  def email_notifications? = preferences.dig("notifications", "email") != false
+  def theme = preferences.dig("appearance", "theme") || "system"
+  def timezone = preferences.dig("timezone") || "UTC"
+  def locale = preferences.dig("locale") || "en"
+end
+```
+
+## Why This Is Good
+
+- **Each class has one reason to change.** Billing rule changes touch `BillingAccount`. Display changes touch `Profile`. Notification settings touch `UserSettings`. The `User` model stays stable.
+- **Smaller classes are easier to understand.** `BillingAccount` has 5 methods about billing. Reading it, you grasp the entire billing interface in 30 seconds.
+- **Better testing.** Test `BillingAccount#deduct_credits!` without loading profile logic, settings, or 20 other user methods.
+- **`delegate` maintains the interface.** Callers still call `user.credit_balance`. The extraction is invisible to external code.
+
+# Refactoring: Move Method
+
+## Pattern
+
+When a method uses more features of another class than the class it's defined on, move it to where the data lives.
+
+```ruby
+# BEFORE: Method on Order that mostly accesses User data
+class Order < ApplicationRecord
+  def customer_summary
+    "#{user.name} (#{user.email}) — #{user.plan_name} plan, #{user.orders.count} orders, " \
+      "member since #{user.created_at.year}"
+  end
+end
+
+# AFTER: Method moved to User where the data lives
+class User < ApplicationRecord
+  def customer_summary
+    "#{name} (#{email}) — #{plan_name} plan, #{orders.count} orders, member since #{created_at.year}"
+  end
+end
+
+# Order delegates or the caller accesses directly
+order.user.customer_summary
+```
+
+## When To Apply Extract Class
+
+- **A class has 200+ lines.** Look for clusters of related methods to extract.
+- **You can describe the class with "and."** "User handles authentication AND billing AND settings" → extract billing and settings.
+- **Multiple developers frequently edit the same file.** Different teams own different responsibilities → different classes.
+- **A group of methods share the same instance variables.** Methods that all use `@subscription` and `@credit_entries` are a billing class waiting to be extracted.
+
+## When To Apply Move Method
+
+- **Feature Envy.** A method references another object 3+ times and its own object 0-1 times.
+- **After Extract Class.** Once you identify a cluster, move the methods to the new class.
+- **When adding `delegate` chains.** If `User` delegates 5 methods to `BillingAccount` and then adds `billing_` prefix methods, maybe those callers should reference `BillingAccount` directly.
+
+## When NOT To Apply
+
+- **Don't extract prematurely.** A User model with 80 lines and 8 methods is fine. Extract when it grows past 150-200 lines or when the clusters become obvious.
+- **Don't create single-method classes.** A `UserGreeter` with just `def greet` is over-extraction. The method can live on User.
+- **Delegate is fine for 3-5 methods.** If User delegates 15 methods to a single collaborator, callers should reference the collaborator directly.