rubyn-code 0.1.0

data/skills/gems/dry_rb.md

@@ -0,0 +1,186 @@
+# Gems: dry-rb Ecosystem
+
+## Pattern
+
+The dry-rb family provides standalone, composable libraries for validation, types, dependency injection, and functional patterns. They're popular in non-Rails Ruby projects and in Rails apps that want more rigor than ActiveModel provides.
+
+### dry-validation (Schema Validation)
+
+```ruby
+# Gemfile
+gem "dry-validation", "~> 1.10"
+
+# app/contracts/order_contract.rb
+class OrderContract < Dry::Validation::Contract
+  params do
+    required(:shipping_address).filled(:string)
+    required(:line_items).array(:hash) do
+      required(:product_id).filled(:integer)
+      required(:quantity).filled(:integer, gt?: 0)
+    end
+    optional(:notes).maybe(:string)
+    optional(:discount_code).maybe(:string, max_size?: 20)
+  end
+
+  rule(:line_items) do
+    key.failure("must have at least one item") if values[:line_items].empty?
+  end
+
+  rule(:discount_code) do
+    if values[:discount_code] && !Discount.active.exists?(code: values[:discount_code])
+      key.failure("is not a valid discount code")
+    end
+  end
+end
+
+# Usage
+contract = OrderContract.new
+result = contract.call(params)
+
+if result.success?
+  # result.to_h contains validated, coerced data
+  Orders::CreateService.call(result.to_h, current_user)
+else
+  # result.errors.to_h contains error messages by field
+  # => { line_items: ["must have at least one item"] }
+  render json: { errors: result.errors.to_h }, status: :unprocessable_entity
+end
+```
+
+### dry-types (Type System)
+
+```ruby
+# Gemfile
+gem "dry-types", "~> 1.7"
+
+# app/types.rb
+module Types
+  include Dry.Types()
+
+  Email = Types::String.constrained(format: URI::MailTo::EMAIL_REGEXP)
+  PositiveMoney = Types::Coercible::Integer.constrained(gteq: 0)
+  Status = Types::String.enum("pending", "confirmed", "shipped", "delivered", "cancelled")
+  CreditAmount = Types::Coercible::Integer.constrained(gteq: 1, lteq: 10_000)
+end
+
+# Usage — type checking and coercion
+Types::Email["alice@example.com"]  # => "alice@example.com"
+Types::Email["not-an-email"]        # => Dry::Types::ConstraintError
+
+Types::PositiveMoney[1999]          # => 1999
+Types::PositiveMoney[-5]            # => Dry::Types::ConstraintError
+
+Types::Status["pending"]            # => "pending"
+Types::Status["invalid"]            # => Dry::Types::ConstraintError
+```
+
+### dry-monads (Result Type / Railway Programming)
+
+```ruby
+# Gemfile
+gem "dry-monads", "~> 1.6"
+
+# app/services/orders/create_service.rb
+require "dry/monads"
+
+class Orders::CreateService
+  include Dry::Monads[:result, :do]
+
+  def call(params, user)
+    validated = yield validate(params)
+    order = yield create_order(validated, user)
+    yield charge_payment(order)
+    yield send_confirmation(order)
+
+    Success(order)
+  end
+
+  private
+
+  def validate(params)
+    result = OrderContract.new.call(params)
+    result.success? ? Success(result.to_h) : Failure(result.errors.to_h)
+  end
+
+  def create_order(params, user)
+    order = user.orders.create(params)
+    order.persisted? ? Success(order) : Failure(order.errors.full_messages)
+  end
+
+  def charge_payment(order)
+    result = Payments::ChargeService.call(order)
+    result.success? ? Success(result) : Failure("Payment failed: #{result.error}")
+  end
+
+  def send_confirmation(order)
+    OrderMailer.confirmation(order).deliver_later
+    Success(true)
+  end
+end
+
+# Controller — pattern match on the result
+result = Orders::CreateService.new.call(params, current_user)
+
+case result
+in Dry::Monads::Success(order)
+  redirect_to order, notice: "Order placed"
+in Dry::Monads::Failure(errors) if errors.is_a?(Hash)
+  @errors = errors
+  render :new, status: :unprocessable_entity
+in Dry::Monads::Failure(message)
+  flash.now[:alert] = message
+  render :new, status: :unprocessable_entity
+end
+```
+
+The `yield` keyword with `do` notation short-circuits on `Failure` — if `validate` returns `Failure`, the remaining steps never execute. This is the "railway" pattern: success continues down the track, failure jumps to the error track immediately.
+
+### dry-struct (Typed Data Objects)
+
+```ruby
+# Gemfile
+gem "dry-struct", "~> 1.6"
+
+class OrderRequest < Dry::Struct
+  attribute :shipping_address, Types::String
+  attribute :line_items, Types::Array.of(LineItemRequest)
+  attribute :discount_code, Types::String.optional
+  attribute :notes, Types::String.optional.default(nil)
+end
+
+class LineItemRequest < Dry::Struct
+  attribute :product_id, Types::Coercible::Integer
+  attribute :quantity, Types::Coercible::Integer.constrained(gteq: 1)
+end
+
+# Construction validates types automatically
+request = OrderRequest.new(
+  shipping_address: "123 Main St",
+  line_items: [{ product_id: "42", quantity: "2" }],  # Strings coerced to integers
+  discount_code: nil
+)
+
+request.line_items.first.product_id  # => 42 (Integer, coerced from String)
+request.line_items.first.quantity    # => 2 (Integer)
+```
+
+## Why This Is Good
+
+- **dry-validation separates validation from models.** Complex validations (cross-field, external lookups, nested structures) have a dedicated home that's not the ActiveRecord model.
+- **dry-types catch type errors at boundaries.** Instead of `NoMethodError: undefined method 'to_i' for nil` buried in a service, you get `Dry::Types::ConstraintError` at the entry point.
+- **dry-monads make error flow explicit.** Every step returns `Success` or `Failure`. The `do` notation short-circuits on failure. No hidden exception paths, no nil returns.
+- **Composable and standalone.** Each dry-rb gem works independently. Use dry-validation without dry-monads, or dry-types without dry-struct.
+
+## When To Apply
+
+- **Complex validation beyond what ActiveModel handles.** Nested params, cross-field rules, external lookups, multi-step validation.
+- **Non-Rails Ruby projects.** dry-rb is framework-agnostic. Perfect for Sinatra apps, plain Ruby services, and gems.
+- **Teams that want explicit error handling.** dry-monads forces every failure path to be handled. Nothing slips through silently.
+- **API input validation.** dry-validation is excellent for validating JSON API payloads before they touch ActiveRecord.
+
+## When NOT To Apply
+
+- **Simple Rails apps with standard validations.** `validates :name, presence: true` is fine. Don't add dry-validation for what ActiveModel already handles.
+- **The team is unfamiliar with functional patterns.** dry-monads' `Success`/`Failure`/`yield` pattern has a learning curve. If the team isn't bought in, it creates friction.
+- **Mixing dry-rb and ActiveModel validations.** Pick one approach per layer. Don't validate params with dry-validation AND re-validate in the model with ActiveModel — you'll get confused about which errors come from where.
+- **Small projects.** The dry-rb gems add dependencies and concepts. For a 10-controller Rails app, they're overkill.

data/skills/gems/factory_bot.md

@@ -0,0 +1,268 @@
+# Gem: FactoryBot
+
+## What It Is
+
+FactoryBot creates test data for RSpec and Minitest. It replaces fixtures with programmatic factories that produce valid ActiveRecord objects with minimal boilerplate. It's the most widely used test data library in Rails.
+
+## Setup Done Right
+
+```ruby
+# Gemfile (test group)
+gem 'factory_bot_rails'
+
+# spec/support/factory_bot.rb
+RSpec.configure do |config|
+  config.include FactoryBot::Syntax::Methods
+end
+```
+
+## Gotcha #1: Factory Chains Create Way More Records Than You Think
+
+Every `belongs_to` association in a factory triggers a `create` of the associated record. A deeply nested factory can create 10+ records when you only asked for 1.
+
+```ruby
+# These factories look innocent...
+FactoryBot.define do
+  factory :line_item do
+    order           # Creates an order
+    product         # Creates a product
+    quantity { 1 }
+  end
+
+  factory :order do
+    user            # Creates a user
+    shipping_address { "123 Main St" }
+  end
+
+  factory :user do
+    company         # Creates a company
+    email { "user@example.com" }
+  end
+
+  factory :company do
+    name { "Acme Inc" }
+    plan            # Creates a plan
+  end
+end
+
+# This single line...
+create(:line_item)
+# Actually creates: plan → company → user → order → product → line_item
+# That's 6 INSERT statements for ONE line item!
+```
+
+**Fix: Use `build_stubbed` when you don't need the DB, and be deliberate about associations:**
+
+```ruby
+# For unit tests — zero database hits
+line_item = build_stubbed(:line_item)
+
+# When you need a real record but want to control associations
+user = create(:user, company: nil)  # Skip company creation
+order = create(:order, user: user)  # Reuse the user
+create(:line_item, order: order)    # Only creates product + line_item
+```
+
+## Gotcha #2: Sequences vs Hardcoded Values
+
+Unique fields without sequences cause test failures that depend on execution order.
+
+```ruby
+# WRONG: Hardcoded unique field — second create fails
+factory :user do
+  email { "test@example.com" }  # Duplicate on second create!
+end
+
+create(:user)  # Works
+create(:user)  # ActiveRecord::RecordNotUnique: email already taken
+
+# RIGHT: Use sequences for any unique field
+factory :user do
+  sequence(:email) { |n| "user#{n}@example.com" }
+  name { "Jane Doe" }
+end
+
+create(:user).email  # "user1@example.com"
+create(:user).email  # "user2@example.com"
+```
+
+**The trap:** Tests pass when run individually but fail when run together. The first test creates `test@example.com`, the second tries to create it again. Sequences prevent this.
+
+## Gotcha #3: `create` vs `build` vs `build_stubbed` — Wrong Choice Wastes Time
+
+```ruby
+# WRONG: Using create when build_stubbed would work
+RSpec.describe Order do
+  let(:order) { create(:order) }  # Writes to DB unnecessarily
+
+  it "calculates total" do
+    # This test only calls order.total — it never queries the DB
+    expect(order.total).to eq(0)
+  end
+end
+
+# RIGHT: Match the factory strategy to the test's needs
+RSpec.describe Order do
+  let(:order) { build_stubbed(:order, total: 100) }  # No DB hit
+
+  it "calculates total" do
+    expect(order.total).to eq(100)
+  end
+end
+```
+
+Decision tree:
+- **Does the test query the DB (scopes, joins, reload)?** → `create`
+- **Does the test call `.valid?`, `.save`, or `.errors`?** → `build`
+- **Does the test only call instance methods?** → `build_stubbed`
+
+## Gotcha #4: Traits — Compose, Don't Create New Factories
+
+```ruby
+# WRONG: Separate factories for every variation
+factory :pending_order do
+  status { :pending }
+  user
+end
+
+factory :shipped_order do
+  status { :shipped }
+  shipped_at { 1.day.ago }
+  user
+end
+
+factory :high_value_shipped_order do
+  status { :shipped }
+  shipped_at { 1.day.ago }
+  total { 500 }
+  user
+end
+
+# RIGHT: One factory with composable traits
+factory :order do
+  user
+  sequence(:reference) { |n| "ORD-#{n.to_s.rjust(6, '0')}" }
+  status { :pending }
+  total { 100 }
+
+  trait :shipped do
+    status { :shipped }
+    shipped_at { 1.day.ago }
+  end
+
+  trait :cancelled do
+    status { :cancelled }
+    cancelled_at { 1.hour.ago }
+  end
+
+  trait :high_value do
+    total { 500 }
+  end
+
+  trait :with_line_items do
+    transient do
+      item_count { 2 }
+    end
+
+    after(:create) do |order, ctx|
+      create_list(:line_item, ctx.item_count, order: order)
+    end
+  end
+end
+
+# Compose traits as needed
+create(:order, :shipped)
+create(:order, :shipped, :high_value)
+create(:order, :with_line_items, item_count: 5)
+create(:order, :cancelled, total: 0)
+```
+
+## Gotcha #5: `after(:create)` Blocks Break `build_stubbed`
+
+```ruby
+# WRONG: after(:create) prevents build_stubbed from working
+factory :order do
+  after(:create) do |order|
+    create(:line_item, order: order)  # Only runs on create, not build_stubbed
+  end
+end
+
+build_stubbed(:order)
+# Works — but has no line items (after(:create) didn't run)
+# Tests that expect line items fail silently
+
+# RIGHT: Use traits for optional associations
+factory :order do
+  # Base factory has no line items
+
+  trait :with_line_items do
+    after(:create) do |order|
+      create_list(:line_item, 2, order: order)
+    end
+  end
+end
+
+create(:order, :with_line_items)  # Has line items
+build_stubbed(:order)              # No line items, but that's expected
+```
+
+## Gotcha #6: Faker Slows Tests and Creates Flaky Failures
+
+```ruby
+# WRONG: Faker for every attribute
+factory :user do
+  name { Faker::Name.name }         # Random every test run
+  email { Faker::Internet.email }    # Can generate duplicates!
+  bio { Faker::Lorem.paragraph(sentence_count: 10) }  # Slow, nobody reads it
+end
+
+# RIGHT: Static defaults, sequences for unique fields
+factory :user do
+  name { "Jane Doe" }
+  sequence(:email) { |n| "user#{n}@example.com" }
+  # No bio — keep it nil unless a test specifically needs it
+end
+```
+
+**The traps:**
+- Faker generates random data. Your test passes 99% of the time but fails when Faker generates a name over 100 characters (your validation limit).
+- Faker::Internet.email can generate the same email twice. Unlike sequences, it doesn't guarantee uniqueness.
+- Faker is slow — it generates random data on every call. Across 2,000 factory calls, this adds seconds.
+
+## Gotcha #7: Lint Your Factories
+
+```ruby
+# spec/factories_spec.rb — catches broken factories early
+RSpec.describe "FactoryBot factories" do
+  it "has valid factories" do
+    FactoryBot.lint(traits: true)
+  end
+end
+```
+
+This creates every factory with every trait and calls `.valid?` on each. It catches:
+- Missing required fields
+- Broken associations
+- Invalid trait combinations
+- Sequences that produce invalid data
+
+Run it in CI — it's the first test to fail when someone adds a model validation without updating the factory.
+
+## Do's and Don'ts Summary
+
+**DO:**
+- Use `build_stubbed` by default, `build` for validation tests, `create` only when the DB is needed
+- Use sequences for every unique field (email, reference, slug)
+- Use traits for variations — compose them, don't create separate factories
+- Use transient attributes for configurable association creation
+- Use static values for non-unique fields
+- Lint your factories in CI
+- Keep base factories minimal — only required fields
+
+**DON'T:**
+- Don't use `create` when `build_stubbed` would work
+- Don't use Faker for factory defaults (slow, flaky, non-unique)
+- Don't put `after(:create)` in the base factory — use traits
+- Don't create separate factories for variations — use traits
+- Don't forget to update factories when you add model validations
+- Don't let factories silently create 10+ records via association chains