rubyn-code 0.1.0

data/skills/code_quality/null_object.md

@@ -0,0 +1,205 @@
+# Code Quality: Null Object Pattern
+
+## Pattern
+
+Instead of returning `nil` and forcing callers to check for it, return a special Null Object that implements the same interface with safe, neutral behavior. Eliminates `nil` checks scattered throughout the codebase.
+
+```ruby
+# The real object
+class User < ApplicationRecord
+  def display_name = name.presence || email
+  def plan_name = active_subscription&.plan || "free"
+  def credit_balance = credit_ledger_entries.sum(:amount)
+  def can_use_feature?(feature) = plan_features.include?(feature)
+end
+
+# The Null Object — same interface, safe defaults
+class GuestUser
+  def id = nil
+  def display_name = "Guest"
+  def email = nil
+  def plan_name = "none"
+  def credit_balance = 0
+  def can_use_feature?(_feature) = false
+  def admin? = false
+  def persisted? = false
+  def orders = Order.none  # Returns an empty ActiveRecord relation
+  def projects = Project.none
+end
+
+# Controller — no nil checks anywhere
+class ApplicationController < ActionController::Base
+  def current_user
+    @current_user ||= User.find_by(id: session[:user_id]) || GuestUser.new
+  end
+end
+
+# Views work without nil checks
+<%= current_user.display_name %>  <!-- "Guest" for non-logged-in users -->
+<% if current_user.can_use_feature?(:export) %>
+  <%= link_to "Export", export_path %>
+<% end %>
+
+# Services work without nil checks
+class Orders::ListService
+  def call(user)
+    user.orders.recent.page(1)  # GuestUser returns Order.none — empty relation
+  end
+end
+```
+
+Another example — missing configuration:
+
+```ruby
+# Instead of nil for missing config
+class AppConfig
+  def self.feature_flags
+    @feature_flags ||= load_flags || NullFeatureFlags.new
+  end
+end
+
+class NullFeatureFlags
+  def enabled?(_flag) = false
+  def percentage(_flag) = 0
+  def variant(_flag) = "control"
+  def to_h = {}
+end
+
+# Callers never check for nil
+if AppConfig.feature_flags.enabled?(:new_dashboard)
+  render_new_dashboard
+end
+```
+
+Null Object for associations:
+
+```ruby
+class Order < ApplicationRecord
+  belongs_to :discount, optional: true
+
+  def effective_discount
+    discount || NullDiscount.new
+  end
+end
+
+class NullDiscount
+  def code = "none"
+  def percentage = 0
+  def calculate(subtotal) = 0
+  def active? = false
+  def to_s = "No discount"
+end
+
+# No nil checks in calculation
+class Orders::TotalCalculator
+  def call(order)
+    subtotal = order.line_items.sum(&:total)
+    discount_amount = order.effective_discount.calculate(subtotal)
+    subtotal - discount_amount
+  end
+end
+```
+
+## Why This Is Good
+
+- **Eliminates nil checks.** No more `if current_user.present?`, `user&.name`, or `user.try(:email)`. Every method call is safe because the Null Object responds to everything.
+- **Views are cleaner.** No `<% if current_user %>` guards wrapping every personalized element. The GuestUser provides sensible defaults.
+- **Polymorphic behavior.** The code treats real users and guest users identically. The difference is in the object, not in every caller.
+- **Prevents NoMethodError on nil.** The #1 runtime error in Ruby apps is calling a method on `nil`. Null Objects make this impossible for the wrapped concept.
+
+## Anti-Pattern
+
+Nil checks scattered throughout the codebase:
+
+```ruby
+# Controller
+def show
+  @order = current_user&.orders&.find_by(id: params[:id])
+  redirect_to root_path unless @order
+end
+
+# View
+<% if current_user %>
+  Welcome, <%= current_user.name || "User" %>
+  <% if current_user.active_subscription %>
+    Plan: <%= current_user.active_subscription.plan %>
+  <% else %>
+    Plan: Free
+  <% end %>
+<% else %>
+  Welcome, Guest
+<% end %>
+
+# Service
+def calculate_discount(order)
+  return 0 unless order.discount
+  return 0 unless order.discount.active?
+  order.discount.calculate(order.subtotal)
+end
+```
+
+## Why This Is Bad
+
+- **Nil checks multiply.** Every new feature that touches `current_user` needs its own nil guard. Across 50 views and 20 services, that's hundreds of `if present?` checks.
+- **Forgetting one check causes a crash.** One missed `&.` or `if present?` and you get `NoMethodError: undefined method 'name' for nil:NilClass` in production.
+- **Duplicated default logic.** `"Guest"` as a fallback appears in the view. `"Free"` as a default plan appears in both the view and a service. Change one, forget the others.
+
+## When To Apply
+
+- **Optional associations.** `belongs_to :discount, optional: true` → return a `NullDiscount` instead of nil.
+- **Current user / authentication.** Non-logged-in users → `GuestUser` instead of nil.
+- **Configuration that might not exist.** Missing feature flags, missing settings, missing integrations → Null Object with safe defaults.
+- **Any method that currently returns nil and forces callers to check.** If 3+ callers check for nil from the same source, introduce a Null Object.
+
+## When NOT To Apply
+
+- **When nil is meaningful.** `User.find_by(email: email)` returning nil means "not found" — the caller needs to know this to show an error or create the user. A Null Object would hide the absence.
+- **When the absence should be an error.** `Order.find(params[:id])` should raise `RecordNotFound`, not return a NullOrder. The request is invalid.
+- **One or two nil checks.** If only one caller checks for nil, a simple `|| default` is clearer than a Null Object class.
+- **Don't create Null Objects for every model.** Focus on the 2-3 concepts where nil checks are pervasive (current_user, optional associations used in calculations).
+
+## Edge Cases
+
+**Null Object with ActiveRecord::Relation behavior:**
+Use `.none` to return an empty-but-chainable relation:
+
+```ruby
+class GuestUser
+  def orders
+    Order.none  # Returns an ActiveRecord relation that's always empty
+    # .where, .count, .page all work — they just return 0/empty
+  end
+end
+
+# This works: GuestUser.new.orders.recent.page(1).count => 0
+```
+
+**Testing with Null Objects:**
+
+```ruby
+RSpec.describe GuestUser do
+  subject { described_class.new }
+
+  it "responds to the same interface as User" do
+    user_methods = %i[display_name email plan_name credit_balance can_use_feature? admin?]
+    user_methods.each do |method|
+      expect(subject).to respond_to(method)
+    end
+  end
+
+  it "returns safe defaults" do
+    expect(subject.display_name).to eq("Guest")
+    expect(subject.credit_balance).to eq(0)
+    expect(subject.can_use_feature?(:anything)).to be false
+  end
+end
+```
+
+**Combine with `#presence` for simple cases:**
+For one-off nil handling, Ruby's `#presence` and `||` are sufficient:
+
+```ruby
+name = user.name.presence || "Anonymous"
+```
+
+Reserve the full Null Object pattern for when nil checks are pervasive.

data/skills/code_quality/technical_debt.md

@@ -0,0 +1,135 @@
+# Code Quality: Technical Debt
+
+## Core Principle
+
+Technical debt is the gap between the code you have and the code you'd write if you had unlimited time. Like financial debt, it accrues interest — every feature built on top of debt takes longer and introduces more bugs. The goal isn't zero debt (that's impossible) — it's managing it deliberately.
+
+## Types of Technical Debt
+
+### Deliberate, Prudent ("We'll ship this shortcut and clean it up next sprint")
+```ruby
+# We know this should be a service object, but shipping the feature matters more today
+def create
+  @order = current_user.orders.build(order_params)
+  @order.total = @order.line_items.sum { |li| li.quantity * li.unit_price }
+  # TODO: Extract to Orders::CreateService — ticket PROJ-123
+  if @order.save
+    OrderMailer.confirmation(@order).deliver_later
+    redirect_to @order
+  else
+    render :new, status: :unprocessable_entity
+  end
+end
+```
+This is fine IF you track it and pay it back. The TODO references a real ticket. The code works. The shortcut is documented.
+
+### Deliberate, Reckless ("We don't have time for tests")
+```ruby
+# No tests, no error handling, bare rescue, hardcoded values
+def process_payment
+  Stripe::Charge.create(amount: params[:amount], source: params[:token])
+  redirect_to success_path
+rescue
+  redirect_to failure_path
+end
+```
+This debt compounds fast. The bare rescue hides bugs. No tests means no safety net for changes. Hardcoded Stripe calls can't be tested.
+
+### Inadvertent ("We didn't know better at the time")
+```ruby
+# Written before the team learned about service objects
+# 200-line controller that grew organically
+class OrdersController < ApplicationController
+  def create
+    # 50 lines of business logic
+  end
+
+  def update
+    # 40 lines of business logic
+  end
+  # ...
+end
+```
+This isn't bad intent — it's a natural consequence of learning. The team knows better now. Refactoring it is an investment, not a punishment.
+
+## When to Pay Down Debt
+
+### Pay now (before the next feature):
+- **You're about to modify the same code.** If the next ticket touches `OrdersController#create`, refactor it first. The boy scout rule: leave the code better than you found it.
+- **The debt blocks the feature.** If you can't add pagination because the query is a mess, fix the query.
+- **It's causing production incidents.** The bare rescue silently swallowing errors? Fix it before the next outage.
+- **It's slowing down every developer.** A 500-line model that everyone edits — refactoring it saves cumulative hours across the team.
+
+### Pay later (track it, don't fix it now):
+- **The code works and isn't being modified.** A messy module that nobody touches doesn't accrue interest.
+- **The refactoring is large and risky.** Rewriting the authentication system requires planning, not a drive-by fix.
+- **You're about to delete the feature.** Don't polish code that's being removed next month.
+
+### Don't pay at all:
+- **Speculative generality.** "We should make this more flexible" — but nobody has asked for flexibility. Don't refactor toward imagined future requirements.
+- **Style preferences.** Rewriting working code because "I'd write it differently" isn't paying debt — it's churn.
+
+## Tracking Debt
+
+```ruby
+# In code: TODO with a ticket reference
+# TODO: Extract discount calculation to DiscountService — PROJ-456
+# TODO: Replace N+1 query with includes — PROJ-789
+
+# NOT useful: TODOs without context
+# TODO: Fix this
+# TODO: Refactor later
+# TODO: This is bad
+```
+
+### Debt Inventory (for the team)
+
+| Location | Smell | Impact | Effort | Priority |
+|---|---|---|---|---|
+| `OrdersController#create` | Fat controller (50 lines) | Medium — every order change touches this | Small — extract to service | **Next sprint** |
+| `User` model | 300 lines, 5 concerns | High — every dev edits this daily | Large — needs planning | **Schedule** |
+| `spec/` | 40% use `create` where `build_stubbed` works | Medium — slow CI | Medium — incremental | **Boy scout** |
+| `Legacy::Importer` | No tests, bare rescue | Low — runs once per month | Medium | **Track, don't fix** |
+
+## Refactoring Strategies
+
+### Boy Scout Rule (Incremental)
+Every PR that touches a file leaves it slightly better. Rename a variable, extract a method, add a missing test. Small improvements compound.
+
+### Strangler Fig (Gradual Replacement)
+Build the new system alongside the old one. Route new traffic to the new system. Eventually shut off the old one. Works for large rewrites (new API version, new auth system).
+
+```ruby
+# Old: everything in the controller
+class OrdersController
+  def create
+    # 50 lines of legacy code
+  end
+end
+
+# New: service object handles new code paths
+class OrdersController
+  def create
+    if Feature.enabled?(:new_order_flow, current_user)
+      result = Orders::CreateService.call(order_params, current_user)
+      # ...
+    else
+      # Legacy path — will be removed once new flow is stable
+      # ...
+    end
+  end
+end
+```
+
+### Dedicated Refactoring Sprint
+Reserve 10-20% of sprint capacity for debt reduction. Pick the highest-impact items from the debt inventory. This works for teams that can't justify "refactoring PRs" individually but can justify a planned investment.
+
+## Rubyn's Role in Debt Management
+
+When Rubyn reviews code, it identifies debt using the code smells vocabulary (Long Method, Feature Envy, Shotgun Surgery, etc.) and gives each finding a severity. This turns vague "this code is messy" feelings into specific, actionable items that can be tracked and prioritized.
+
+When Rubyn refactors, it pays down the specific debt you point it at — extracting the service object, fixing the N+1, replacing the bare rescue — while preserving behavior. It's a tool for incremental improvement, not a magic "fix everything" button.
+
+## The Key Insight
+
+The most expensive code isn't code with debt — it's code with *untracked* debt. A TODO with a ticket is managed. A 500-line controller that everyone complains about but nobody documents is a slowly growing crisis. Track it, prioritize it, pay it down incrementally.

data/skills/code_quality/value_objects.md

@@ -0,0 +1,216 @@
+# Code Quality: Value Objects
+
+## Pattern
+
+Replace primitive values (strings, integers, floats) that carry domain meaning with small, immutable objects that encapsulate the value AND its behavior. Value objects are equal by their attributes, not by identity.
+
+```ruby
+# Ruby 3.2+ Data class — the easiest way to create value objects
+Money = Data.define(:amount_cents, :currency) do
+  def initialize(amount_cents:, currency: "USD")
+    super(amount_cents: Integer(amount_cents), currency: currency.to_s.upcase.freeze)
+  end
+
+  def to_f = amount_cents / 100.0
+  def to_s = format("$%.2f %s", to_f, currency)
+  def zero? = amount_cents.zero?
+
+  def +(other)
+    raise ArgumentError, "Currency mismatch: #{currency} vs #{other.currency}" unless currency == other.currency
+    self.class.new(amount_cents: amount_cents + other.amount_cents, currency: currency)
+  end
+
+  def -(other)
+    raise ArgumentError, "Currency mismatch" unless currency == other.currency
+    self.class.new(amount_cents: amount_cents - other.amount_cents, currency: currency)
+  end
+
+  def *(factor)
+    self.class.new(amount_cents: (amount_cents * factor).round, currency: currency)
+  end
+
+  def >(other) = amount_cents > other.amount_cents
+  def <(other) = amount_cents < other.amount_cents
+end
+
+# Usage
+price = Money.new(amount_cents: 19_99)
+tax = price * 0.08
+total = price + tax
+puts total          # => "$21.59 USD"
+puts total > price  # => true
+
+# Equality by value, not identity
+Money.new(amount_cents: 100) == Money.new(amount_cents: 100)  # => true
+```
+
+```ruby
+# Email value object — validates and normalizes
+Email = Data.define(:address) do
+  EMAIL_REGEX = URI::MailTo::EMAIL_REGEXP
+
+  def initialize(address:)
+    normalized = address.to_s.downcase.strip
+    raise ArgumentError, "Invalid email: #{address}" unless normalized.match?(EMAIL_REGEX)
+    super(address: normalized.freeze)
+  end
+
+  def domain = address.split("@").last
+  def local_part = address.split("@").first
+  def to_s = address
+  def personal? = !corporate?
+  def corporate? = !domain.match?(/gmail|yahoo|hotmail|outlook/i)
+end
+
+email = Email.new(address: "  Alice@Example.COM  ")
+email.address    # => "alice@example.com" (normalized)
+email.domain     # => "example.com"
+email.corporate? # => true
+```
+
+```ruby
+# DateRange value object — common in reporting
+DateRange = Data.define(:start_date, :end_date) do
+  def initialize(start_date:, end_date:)
+    start_date = Date.parse(start_date.to_s) unless start_date.is_a?(Date)
+    end_date = Date.parse(end_date.to_s) unless end_date.is_a?(Date)
+    raise ArgumentError, "start_date must be before end_date" if start_date > end_date
+    super(start_date: start_date, end_date: end_date)
+  end
+
+  def days = (end_date - start_date).to_i
+  def include?(date) = (start_date..end_date).cover?(date)
+  def to_range = start_date..end_date
+  def overlap?(other) = start_date <= other.end_date && end_date >= other.start_date
+  def to_s = "#{start_date.iso8601} to #{end_date.iso8601}"
+
+  def self.last_n_days(n) = new(start_date: n.days.ago.to_date, end_date: Date.today)
+  def self.this_month = new(start_date: Date.today.beginning_of_month, end_date: Date.today)
+end
+
+period = DateRange.last_n_days(30)
+orders = Order.where(created_at: period.to_range)
+puts "#{period.days} days: #{orders.count} orders"
+```
+
+```ruby
+# FileHash — wraps a checksum with comparison behavior
+FileHash = Data.define(:digest) do
+  def self.from_content(content)
+    new(digest: Digest::SHA256.hexdigest(content))
+  end
+
+  def changed_from?(other)
+    digest != other.digest
+  end
+
+  def to_s = digest[0..7]  # Short display
+end
+
+current = FileHash.from_content(file_content)
+stored = FileHash.new(digest: embedding.file_hash)
+reindex_file if current.changed_from?(stored)
+```
+
+## Why This Is Good
+
+- **Impossible to have invalid values.** `Email.new(address: "not-an-email")` raises immediately. You can't pass an invalid email deeper into the system. Validation is at construction, not scattered across consumers.
+- **Behavior lives with the data.** `money + other_money` handles currency matching. `email.domain` extracts the domain. Without value objects, this logic is duplicated wherever the primitive is used.
+- **Self-documenting types.** `def charge(amount:)` accepting a `Money` is clearer than accepting an `Integer` (is it cents? dollars? what currency?). The type IS the documentation.
+- **Immutable by default.** `Data.define` produces frozen objects. No accidental mutation, no defensive copying, no shared-state bugs.
+- **Equality by value.** Two `Money` objects with the same amount and currency are equal. This makes them work correctly in Sets, as Hash keys, and with `==`.
+
+## Anti-Pattern
+
+Using primitives with scattered validation and formatting:
+
+```ruby
+class Order < ApplicationRecord
+  validates :total, numericality: { greater_than: 0 }
+
+  def formatted_total
+    "$#{'%.2f' % (total / 100.0)}"
+  end
+end
+
+class Invoice < ApplicationRecord
+  validates :amount, numericality: { greater_than: 0 }
+
+  def formatted_amount
+    "$#{'%.2f' % (amount / 100.0)}"
+  end
+end
+
+# In a service
+def apply_discount(total_cents, discount_percentage)
+  discount = (total_cents * discount_percentage / 100.0).round
+  total_cents - discount
+  # Wait — is total_cents in cents or dollars? The variable name says cents
+  # but the discount_percentage calculation suggests... ?
+end
+```
+
+## Why This Is Bad
+
+- **Duplicated formatting.** `"$#{'%.2f' % (total / 100.0)}"` appears in Order, Invoice, and probably 5 other places. Change the format in one place, forget the others.
+- **No currency safety.** Adding USD and EUR produces a meaningless number. With `Money`, it raises `ArgumentError`.
+- **Ambiguous units.** Is `total` in cents or dollars? Is `discount_percentage` 10 or 0.10? Primitives don't communicate their units.
+- **Validation scattered.** Every model independently validates numericality. With `Money`, the value object enforces validity at construction.
+
+## When To Apply
+
+- **Whenever a primitive carries domain meaning.** Money, email, phone number, URL, date range, coordinates, file hash, API key, color code.
+- **When the same formatting/parsing appears in 2+ places.** That's behavior that belongs on a value object.
+- **When you find yourself naming variables with units.** `amount_cents`, `distance_km`, `duration_seconds` — these are value objects screaming to be born.
+- **When invalid values cause bugs.** If a negative amount, empty email, or swapped date range would cause downstream problems, make it impossible to construct.
+
+## When NOT To Apply
+
+- **Simple strings with no behavior.** A user's `first_name` is just a string — no formatting, validation, or arithmetic needed.
+- **IDs and foreign keys.** These are database primitives. Wrapping `user_id` in a `UserId` value object is over-engineering.
+- **Ephemeral values in a single method.** A loop counter or a temporary sum doesn't need a value object.
+
+## Edge Cases
+
+**Value objects in ActiveRecord:**
+Store as a primitive in the DB, cast to a value object in Ruby:
+
+```ruby
+class Order < ApplicationRecord
+  def total_money
+    Money.new(amount_cents: total_cents, currency: currency)
+  end
+
+  def total_money=(money)
+    self.total_cents = money.amount_cents
+    self.currency = money.currency
+  end
+end
+
+# Or use ActiveRecord::Attributes for automatic casting
+class MoneyType < ActiveRecord::Type::Value
+  def cast(value)
+    case value
+    when Money then value
+    when Hash then Money.new(**value.symbolize_keys)
+    when Integer then Money.new(amount_cents: value)
+    end
+  end
+
+  def serialize(value)
+    value&.amount_cents
+  end
+end
+```
+
+**Pre-Ruby 3.2 (no Data class):**
+Use `Struct` with freeze:
+
+```ruby
+Money = Struct.new(:amount_cents, :currency, keyword_init: true) do
+  def initialize(amount_cents:, currency: "USD")
+    super
+    freeze
+  end
+end
+```