rubyn-code 0.1.0

data/skills/rspec/test_performance.md

@@ -0,0 +1,215 @@
+# RSpec: Test Suite Performance
+
+## Pattern
+
+A fast test suite runs in under 60 seconds for 1,000 specs. Achieve this by minimizing database hits, choosing the cheapest factory strategy per test, avoiding unnecessary setup, and profiling regularly.
+
+Core strategies ranked by impact:
+
+**1. Use `build_stubbed` wherever possible**
+
+```ruby
+# FAST: Zero database hits
+let(:user) { build_stubbed(:user) }
+let(:order) { build_stubbed(:order, user: user, total: 100) }
+
+it "calculates discount" do
+  expect(order.discounted_total).to eq(90)
+end
+```
+
+**2. Use `let` (lazy) instead of `let!` (eager)**
+
+```ruby
+# FAST: Only creates records that are actually referenced
+let(:user) { create(:user) }
+let(:order) { create(:order, user: user) }
+
+# Only the examples that call `order` pay for its creation
+```
+
+**3. Minimize factory association chains**
+
+```ruby
+# BAD: Creates user, company, plan, 3 line items, 3 products, 3 categories
+let(:order) { create(:order, :with_line_items) }
+
+# GOOD: Only what this test needs
+let(:order) { build_stubbed(:order, total: 100) }
+```
+
+**4. Use `before(:all)` / `before_all` for truly shared expensive setup**
+
+```ruby
+# With the test-prof gem's before_all (transaction-safe)
+before_all do
+  @reference_data = create(:pricing_table_with_100_rows)
+end
+
+# Standard before(:all) — use with caution, not wrapped in transaction
+before(:all) do
+  @admin = create(:user, :admin)
+end
+```
+
+**5. Profile your test suite to find the bottlenecks**
+
+```bash
+# Find the 10 slowest examples
+bundle exec rspec --profile 10
+
+# Find the slowest factories (requires test-prof gem)
+FPROF=1 bundle exec rspec
+
+# Find examples that make the most DB queries
+EVENT_PROF=sql.active_record bundle exec rspec
+```
+
+**6. Use `aggregate_failures` to reduce example count**
+
+```ruby
+# SLOW: 4 separate examples, each with their own setup
+it "has a reference" do
+  expect(order.reference).to be_present
+end
+it "has a status" do
+  expect(order.status).to eq("pending")
+end
+it "belongs to a user" do
+  expect(order.user).to eq(user)
+end
+it "has a created_at" do
+  expect(order.created_at).to be_present
+end
+
+# FAST: 1 example, same assertions, same error detail on failure
+it "has the expected attributes", :aggregate_failures do
+  expect(order.reference).to be_present
+  expect(order.status).to eq("pending")
+  expect(order.user).to eq(user)
+  expect(order.created_at).to be_present
+end
+```
+
+**7. Parallelize with `parallel_tests`**
+
+```ruby
+# Gemfile
+gem 'parallel_tests', group: :development
+
+# Run on 4 cores
+bundle exec parallel_rspec -n 4
+
+# Database setup for parallel
+rake parallel:setup
+```
+
+## Why This Is Good
+
+- **Developer productivity.** A 30-second test suite gets run after every change. A 10-minute suite gets run before commits, maybe. A 30-minute suite gets run in CI only. Fast feedback loops produce better code.
+- **CI costs.** CI minutes cost money. A test suite that runs in 60 seconds vs 10 minutes is a 10x cost difference over thousands of builds per month.
+- **Developer morale.** Nobody enjoys waiting. A slow test suite creates friction that makes developers skip tests, run subsets, or push untested code.
+- **Catch failures faster.** When tests run in 30 seconds, you run them after every change and catch bugs immediately. When they take 10 minutes, you batch changes and debugging becomes harder.
+
+## Anti-Pattern
+
+A test suite where every example creates a full object graph and runs expensive setup:
+
+```ruby
+RSpec.describe Order do
+  let!(:company) { create(:company) }
+  let!(:admin) { create(:user, :admin, company: company) }
+  let!(:user) { create(:user, company: company) }
+  let!(:product_a) { create(:product, :with_inventory, company: company) }
+  let!(:product_b) { create(:product, :with_inventory, company: company) }
+  let!(:order) { create(:order, :with_line_items, user: user, item_count: 3) }
+
+  describe "#formatted_total" do
+    it "returns a currency string" do
+      # 15+ records created for a string formatting test
+      expect(order.formatted_total).to match(/\$\d+\.\d{2}/)
+    end
+  end
+
+  describe "#pending?" do
+    it "returns true when status is pending" do
+      # 15+ records created to test a boolean comparison
+      expect(order.pending?).to be true
+    end
+  end
+end
+```
+
+## Why This Is Bad
+
+- **15+ INSERT statements per example.** With `let!`, every record is created before every example. 20 examples in this file = 300+ INSERTs.
+- **90% of the setup is irrelevant.** `formatted_total` needs a number, not a company, admin, products, and inventory records.
+- **Compounds across the suite.** If 50 spec files follow this pattern, the test suite creates 15,000+ unnecessary records per run.
+- **Factory chains hide the cost.** `create(:order, :with_line_items)` looks like one record but cascades into order + user + company + 3 line items + 3 products = 9 INSERTs.
+
+## When To Apply
+
+Always. Test performance should be a continuous concern, not an afterthought.
+
+**Before writing any spec, ask:**
+1. Does this test need the database at all? → `build_stubbed`
+2. Does it need the database but not the full object graph? → `create` with minimal attributes
+3. Does it need a complex setup? → isolate the setup, share it via traits or `before_all`
+
+**Regular maintenance:**
+- Run `--profile 10` monthly to catch slow tests
+- Install `test-prof` and run factory profiling when the suite slows down
+- Set a CI budget: if the suite exceeds 2 minutes, investigate before adding more tests
+
+## When NOT To Apply
+
+- **Don't prematurely optimize.** A 10-spec file that runs in 2 seconds doesn't need profiling or `build_stubbed` rewrites. Focus on the slow files first.
+- **Don't sacrifice readability for speed.** If using `create` makes a test dramatically clearer than a `build_stubbed` with 5 `allow` stubs, use `create`. Clarity wins when the speed difference is negligible.
+- **System/feature tests are inherently slower.** They launch a browser and interact with full pages. Optimize them by having fewer of them (test critical paths only) rather than by cutting database setup.
+
+## Edge Cases
+
+**DatabaseCleaner strategies:**
+Use `:transaction` strategy (default with RSpec Rails) for unit and request specs. Use `:truncation` or `:deletion` only for system specs that need JavaScript (and thus run outside the test transaction).
+
+```ruby
+# spec/support/database_cleaner.rb
+RSpec.configure do |config|
+  config.use_transactional_fixtures = true
+
+  config.before(:each, type: :system) do
+    DatabaseCleaner.strategy = :truncation
+  end
+
+  config.after(:each, type: :system) do
+    DatabaseCleaner.clean
+  end
+end
+```
+
+**Shared test data across a describe block:**
+`test-prof`'s `before_all` creates data once per describe block (wrapped in a transaction), not once per example. This is safe and dramatically faster than `let!` for read-only reference data.
+
+```ruby
+# Requires test-prof gem
+before_all do
+  @products = create_list(:product, 50)
+end
+
+it "searches products" do
+  results = Product.search("widget")
+  expect(results).to include(@products.first)
+end
+```
+
+**Stubbing Time:**
+Use `travel_to` instead of creating records with specific timestamps, then querying by date:
+
+```ruby
+it "returns recent orders" do
+  travel_to(2.days.ago) { create(:order) }
+  recent = create(:order)
+
+  expect(Order.recent).to eq([recent])
+end
+```

data/skills/ruby/blocks_procs_lambdas.md

@@ -0,0 +1,204 @@
+# Ruby: Blocks, Procs, and Lambdas
+
+## Pattern
+
+Blocks are Ruby's most powerful feature — closures that capture their surrounding context and can be passed to methods. Understanding blocks, procs, and lambdas is essential for writing idiomatic Ruby.
+
+### Blocks
+
+```ruby
+# A block is code between do/end or { } passed to a method
+[1, 2, 3].each { |n| puts n }
+
+[1, 2, 3].each do |n|
+  puts n
+end
+
+# Convention: { } for single-line, do/end for multi-line
+
+# yield calls the block from inside the method
+def with_logging
+  Rails.logger.info("Starting")
+  result = yield
+  Rails.logger.info("Completed")
+  result
+end
+
+with_logging { Order.create!(params) }
+
+# block_given? checks if a block was passed
+def find_or_default(collection, default: nil)
+  result = collection.find { |item| yield(item) }
+  result || default
+end
+```
+
+### Blocks for Resource Management
+
+```ruby
+# The block pattern guarantees cleanup — Ruby's most important idiom
+File.open("data.csv") do |file|
+  file.each_line { |line| process(line) }
+end
+# File is automatically closed when the block exits, even on exception
+
+# Build your own resource-managing methods
+class DatabaseConnection
+  def self.with_connection
+    conn = checkout
+    yield conn
+  ensure
+    checkin(conn)
+  end
+end
+
+DatabaseConnection.with_connection do |conn|
+  conn.execute("SELECT * FROM orders")
+end
+```
+
+### Procs and Lambdas
+
+```ruby
+# Proc: a block saved as an object
+doubler = Proc.new { |n| n * 2 }
+doubler.call(5)  # => 10
+doubler.(5)      # => 10 (shorthand)
+
+# Lambda: a stricter proc (checks arity, return scoping)
+doubler = ->(n) { n * 2 }
+doubler.call(5)  # => 10
+
+# Symbol-to-proc: converts a method name to a proc
+["alice", "bob"].map(&:upcase)  # => ["ALICE", "BOB"]
+# Equivalent to: .map { |s| s.upcase }
+
+# Method objects as procs
+def double(n) = n * 2
+[1, 2, 3].map(&method(:double))  # => [2, 4, 6]
+```
+
+### Proc vs Lambda Differences
+
+```ruby
+# 1. Arity: Lambda checks argument count, Proc doesn't
+my_lambda = ->(a, b) { a + b }
+my_lambda.call(1)      # ArgumentError: wrong number of arguments (given 1, expected 2)
+
+my_proc = Proc.new { |a, b| (a || 0) + (b || 0) }
+my_proc.call(1)        # => 1 (b is nil, no error)
+
+# 2. Return: Lambda returns to its caller, Proc returns from the enclosing method
+def test_lambda
+  l = -> { return "from lambda" }
+  l.call
+  "after lambda"  # This line executes
+end
+test_lambda  # => "after lambda"
+
+def test_proc
+  p = Proc.new { return "from proc" }
+  p.call
+  "after proc"  # This line NEVER executes
+end
+test_proc  # => "from proc"
+
+# RULE: Use lambdas. They behave predictably.
+```
+
+### Practical Patterns
+
+```ruby
+# Strategy via lambda
+PRICING = {
+  standard: ->(amount) { amount },
+  premium: ->(amount) { amount * 0.9 },
+  vip: ->(amount) { amount * 0.8 }
+}
+
+def calculate_price(amount, tier:)
+  PRICING.fetch(tier, PRICING[:standard]).call(amount)
+end
+
+# Callbacks / hooks
+class Pipeline
+  def initialize
+    @before_hooks = []
+    @after_hooks = []
+  end
+
+  def before(&block)
+    @before_hooks << block
+  end
+
+  def after(&block)
+    @after_hooks << block
+  end
+
+  def execute(data)
+    @before_hooks.each { |hook| hook.call(data) }
+    result = yield(data)
+    @after_hooks.each { |hook| hook.call(result) }
+    result
+  end
+end
+
+pipeline = Pipeline.new
+pipeline.before { |data| puts "Processing: #{data}" }
+pipeline.after { |result| puts "Done: #{result}" }
+pipeline.execute("order-123") { |data| "Processed #{data}" }
+
+# Filtering with lambdas
+active = ->(user) { user.active? }
+premium = ->(user) { user.plan == "pro" }
+recent = ->(user) { user.created_at > 30.days.ago }
+
+filters = [active, premium, recent]
+users.select { |user| filters.all? { |f| f.call(user) } }
+
+# Configuration DSLs
+class Router
+  def initialize(&block)
+    @routes = {}
+    instance_eval(&block) if block
+  end
+
+  def get(path, &handler)
+    @routes[[:get, path]] = handler
+  end
+
+  def post(path, &handler)
+    @routes[[:post, path]] = handler
+  end
+end
+
+router = Router.new do
+  get "/health" do
+    { status: "ok" }
+  end
+
+  post "/orders" do
+    Order.create!(params)
+  end
+end
+```
+
+## Why This Is Good
+
+- **Blocks enable resource safety.** `File.open { }` guarantees cleanup. `ActiveRecord::Base.transaction { }` guarantees rollback on failure. This is more reliable than try/finally patterns.
+- **Lambdas are first-class functions.** Store them in hashes, pass them as arguments, compose them. Ruby's functional programming capabilities are built on lambdas.
+- **Symbol-to-proc is concise and expressive.** `.map(&:name)` is instantly readable by any Rubyist. It's not just shorter — it's clearer.
+- **DSLs via `instance_eval`.** Blocks with `instance_eval` enable clean configuration DSLs (like Rails routes, RSpec, Sinatra).
+
+## When To Apply
+
+- **Resource management** — always use blocks for open/close, start/stop, begin/end patterns.
+- **Callbacks and hooks** — pass blocks to register behavior that runs at specific points.
+- **Strategy selection** — lambdas in a hash for lightweight strategies that don't need a full class.
+- **Iteration and transformation** — blocks with Enumerable methods are the heart of Ruby.
+
+## When NOT To Apply
+
+- **Complex logic in a block.** If a block is longer than 5-7 lines, extract it into a method or a class. Blocks should be concise.
+- **Procs for business logic.** Use lambdas, not procs. Proc's return behavior is surprising and error-prone.
+- **Deep `instance_eval` nesting.** More than one level of `instance_eval` becomes hard to reason about. Keep DSLs shallow.

data/skills/ruby/classes.md

@@ -0,0 +1,155 @@
+# Ruby: Class Design
+
+## Pattern
+
+Design classes with a single responsibility, a clear public interface, and minimal exposure of internal state. Use `attr_reader` by default, only use `attr_accessor` when mutation is intentional, and freeze objects when immutability is desirable.
+
+```ruby
+# GOOD: Clear responsibility, minimal interface, protected internals
+class Money
+  attr_reader :amount_cents, :currency
+
+  def initialize(amount_cents, currency = "USD")
+    @amount_cents = Integer(amount_cents)
+    @currency = currency.to_s.upcase.freeze
+    freeze
+  end
+
+  def to_f
+    amount_cents / 100.0
+  end
+
+  def to_s
+    format("%.2f %s", to_f, currency)
+  end
+
+  def +(other)
+    raise ArgumentError, "Currency mismatch" unless currency == other.currency
+
+    self.class.new(amount_cents + other.amount_cents, currency)
+  end
+
+  def >(other)
+    raise ArgumentError, "Currency mismatch" unless currency == other.currency
+
+    amount_cents > other.amount_cents
+  end
+
+  def ==(other)
+    other.is_a?(self.class) &&
+      amount_cents == other.amount_cents &&
+      currency == other.currency
+  end
+  alias_method :eql?, :==
+
+  def hash
+    [amount_cents, currency].hash
+  end
+end
+```
+
+Constructor patterns:
+
+```ruby
+# Named constructor for clarity
+class Order
+  def self.from_cart(cart, user)
+    new(
+      user: user,
+      line_items: cart.items.map { |item| LineItem.new(product: item.product, quantity: item.quantity) },
+      shipping_address: user.default_address
+    )
+  end
+
+  def initialize(user:, line_items:, shipping_address:)
+    @user = user
+    @line_items = line_items
+    @shipping_address = shipping_address
+  end
+end
+
+# Usage reads like English
+order = Order.from_cart(cart, current_user)
+```
+
+## Why This Is Good
+
+- **`attr_reader` protects state.** External code can read `money.amount_cents` but can't set it. State changes only happen through explicit methods with names that communicate intent.
+- **`freeze` enforces immutability.** A frozen Money object can't be accidentally mutated. Operations like `+` return new instances. This eliminates an entire class of bugs where shared references are modified in place.
+- **Named constructors improve readability.** `Order.from_cart(cart, user)` is clearer than `Order.new(user: user, line_items: cart.items.map { ... })`. The constructor name describes the context.
+- **`==` and `hash` make objects work in collections.** Two Money objects with the same amount and currency are equal, can be used as hash keys, and work with `uniq`, `include?`, and Set operations.
+- **Keyword arguments in constructors.** `new(user:, line_items:, shipping_address:)` is self-documenting. You can't accidentally swap argument order.
+
+## Anti-Pattern
+
+Classes with `attr_accessor` on everything, no encapsulation, and public state mutation:
+
+```ruby
+class Order
+  attr_accessor :user, :items, :status, :total, :tax, :discount,
+                :shipping_address, :billing_address, :notes,
+                :created_at, :updated_at
+
+  def initialize
+    @items = []
+    @status = "pending"
+  end
+end
+
+# External code reaches in and mutates freely
+order = Order.new
+order.user = current_user
+order.items << line_item
+order.items << another_item
+order.total = order.items.sum(&:price)
+order.tax = order.total * 0.08
+order.total = order.total + order.tax
+order.status = "confirmed"
+```
+
+## Why This Is Bad
+
+- **No encapsulation.** Any code anywhere can set `order.status = "shipped"` without any validation or side-effect management. The object can't protect its own invariants.
+- **Scattered logic.** Total calculation happens outside the class. Tax calculation happens outside. The object is a passive data bag that external code manipulates.
+- **Impossible to refactor.** Renaming `@total` to `@amount` requires finding every `order.total =` call across the entire codebase. With a method, you change one place.
+- **No constructor contract.** `Order.new` creates an incomplete, invalid object. The caller must remember to set user, items, total, and tax in the correct order. Missing any step produces a broken object silently.
+
+## When To Apply
+
+- **Every class you write.** Single responsibility and minimal public interface aren't optional patterns — they're baseline class design.
+- **Value objects** (Money, DateRange, Coordinate, EmailAddress) should always be frozen and immutable.
+- **Service objects and domain objects** should use `attr_reader` for dependencies and `private` for implementation details.
+- **Use keyword arguments** when a constructor has more than 2 parameters, or when the parameters are the same type (two strings, two integers) and could be confused.
+
+## When NOT To Apply
+
+- **ActiveRecord models** follow their own conventions. `attr_accessor` for virtual attributes is normal in Rails models. Don't fight the framework.
+- **Structs and Data objects** use `attr_reader` automatically. You don't need to define them manually.
+- **Configuration objects** that are built incrementally (builder pattern) may need `attr_writer` during construction, then frozen after.
+
+## Edge Cases
+
+**You need a mutable object but want controlled mutation:**
+Use explicit setter methods with validation instead of `attr_accessor`:
+
+```ruby
+class Account
+  attr_reader :balance
+
+  def deposit(amount)
+    raise ArgumentError, "Amount must be positive" unless amount > 0
+    @balance += amount
+  end
+
+  def withdraw(amount)
+    raise InsufficientFunds if amount > @balance
+    @balance -= amount
+  end
+end
+```
+
+**Too many constructor arguments (more than 4-5):**
+Consider a parameter object, a builder, or breaking the class into smaller collaborators. A constructor with 8 keyword arguments is a sign the class has too many responsibilities.
+
+**Inheritance vs composition:**
+Default to composition. If you're inheriting just to share code, use a module instead. Inherit only when there's a genuine "is-a" relationship and you want polymorphism.