rubyn-code 0.1.0

data/skills/solid/interface_segregation.md

@@ -0,0 +1,237 @@
+# SOLID: Interface Segregation Principle (ISP)
+
+## Pattern
+
+No client should be forced to depend on methods it doesn't use. In Ruby — where interfaces are implicit (duck typing) — ISP means: keep your modules, mixins, and object contracts small and focused. Don't force an object to implement capabilities it doesn't need.
+
+```ruby
+# GOOD: Focused, small interfaces via separate modules
+
+module Printable
+  def to_pdf
+    raise NotImplementedError
+  end
+end
+
+module Exportable
+  def to_csv
+    raise NotImplementedError
+  end
+
+  def to_json(*)
+    raise NotImplementedError
+  end
+end
+
+module Notifiable
+  def send_notification
+    raise NotImplementedError
+  end
+end
+
+# Order needs all three
+class Order < ApplicationRecord
+  include Printable
+  include Exportable
+  include Notifiable
+
+  def to_pdf
+    OrderPdfGenerator.new(self).generate
+  end
+
+  def to_csv
+    [reference, user.email, total, status].join(",")
+  end
+
+  def to_json(*)
+    { reference: reference, total: total, status: status }.to_json
+  end
+
+  def send_notification
+    OrderMailer.confirmation(self).deliver_later
+  end
+end
+
+# Receipt only needs printing — not forced to implement export or notifications
+class Receipt < ApplicationRecord
+  include Printable
+
+  def to_pdf
+    ReceiptPdfGenerator.new(self).generate
+  end
+end
+
+# Report only needs export — not forced to implement printing or notifications
+class MonthlyReport
+  include Exportable
+
+  def to_csv
+    # ... generate CSV
+  end
+
+  def to_json(*)
+    # ... generate JSON
+  end
+end
+```
+
+ISP applied to service dependencies:
+
+```ruby
+# GOOD: Service depends only on what it needs
+
+# Instead of depending on the entire User model:
+class WelcomeEmailService
+  # Only needs an email address and a name — not 30 User methods
+  def call(email:, name:)
+    WelcomeMailer.send(email: email, name: name).deliver_later
+  end
+end
+
+# Caller provides only what's needed
+WelcomeEmailService.new.call(email: user.email, name: user.name)
+
+# The service can also be called with non-User data:
+WelcomeEmailService.new.call(email: "invite@example.com", name: "New Friend")
+```
+
+ISP with dependency injection — narrow interfaces:
+
+```ruby
+# GOOD: The indexer only needs objects that respond to #embed
+# It doesn't care if the client also has #health, #version, #warm_up
+
+class Codebase::Indexer
+  def initialize(embedder:)
+    @embedder = embedder  # Only needs: embedder.embed(texts) → Array<Array<Float>>
+  end
+
+  def index(project, files)
+    files.each do |path, content|
+      chunks = Chunker.split(content)
+      vectors = @embedder.embed(chunks.map(&:text))  # The only method we call
+      chunks.zip(vectors).each do |chunk, vector|
+        project.code_embeddings.create!(
+          file_path: path,
+          chunk_content: chunk.text,
+          embedding: vector
+        )
+      end
+    end
+  end
+end
+
+# Any of these work — they all respond to #embed
+Codebase::Indexer.new(embedder: EmbeddingClient.new)        # Real client
+Codebase::Indexer.new(embedder: FakeEmbedder.new)           # Test double
+Codebase::Indexer.new(embedder: CachedEmbedder.new(client)) # Decorator
+```
+
+## Why This Is Good
+
+- **Models include only what they need.** `Receipt` includes `Printable` but not `Exportable`. It's never forced to stub out `to_csv` or `to_json` with `raise NotImplementedError`.
+- **Services depend on narrow interfaces.** `WelcomeEmailService` needs an email and a name — not a 30-method User object. It works with any data source that provides those two values.
+- **Testing is simpler.** To test `Codebase::Indexer`, you provide an object that responds to `embed`. You don't need to mock the 5 other methods on `EmbeddingClient`.
+- **Changes are isolated.** If `Exportable` adds a `to_xml` method, only classes that include `Exportable` are affected. `Receipt` (which only includes `Printable`) is untouched.
+
+## Anti-Pattern
+
+A fat module that forces every includer to implement everything:
+
+```ruby
+# BAD: One massive module forces all methods on every includer
+module DocumentCapabilities
+  def to_pdf
+    raise NotImplementedError
+  end
+
+  def to_csv
+    raise NotImplementedError
+  end
+
+  def to_json(*)
+    raise NotImplementedError
+  end
+
+  def to_xml
+    raise NotImplementedError
+  end
+
+  def send_email
+    raise NotImplementedError
+  end
+
+  def send_sms
+    raise NotImplementedError
+  end
+
+  def archive
+    raise NotImplementedError
+  end
+
+  def encrypt
+    raise NotImplementedError
+  end
+end
+
+# Receipt only needs PDF but is forced to "implement" everything
+class Receipt < ApplicationRecord
+  include DocumentCapabilities
+
+  def to_pdf
+    ReceiptPdfGenerator.new(self).generate
+  end
+
+  # These all raise NotImplementedError — they shouldn't exist on Receipt at all
+  # But the module forced them in
+end
+```
+
+## Why This Is Bad
+
+- **Receipt responds to 8 methods it can't do.** `receipt.respond_to?(:send_sms)` returns `true`, but calling it raises `NotImplementedError`. The interface lies about the object's capabilities.
+- **Forced implementation of irrelevant methods.** A developer including `DocumentCapabilities` must consider all 8 methods. They waste time figuring out which ones their class needs and stub the rest.
+- **Brittle to change.** Adding a new method to `DocumentCapabilities` (say, `to_parquet`) requires every includer to either implement it or get a `NotImplementedError`. One module change ripples across all including classes.
+- **Violates LSP.** If code calls `.send_sms` on any object including `DocumentCapabilities`, some objects work and others raise. The contract is unreliable.
+
+## When To Apply
+
+- **When a module/mixin has more than 4-5 methods and not all includers need all of them.** Split it into focused sub-modules.
+- **When a service or method accepts a complex object but only uses 1-2 attributes.** Accept those attributes directly instead of the whole object.
+- **When you inject dependencies.** Define the narrowest interface the consumer needs. Document what methods are required. Don't pass the kitchen sink.
+- **In gems and libraries.** Public interfaces should be minimal. Don't force gem users to configure 10 options when they only need 2.
+
+## When NOT To Apply
+
+- **Don't split a 3-method module into 3 single-method modules.** ISP is about avoiding *fat* interfaces, not achieving one-method-per-module granularity.
+- **ActiveRecord models inherently have many methods.** That's the framework's design. Don't fight it by wrapping every model in a narrow interface object for internal use.
+- **Small, cohesive modules are already ISP-compliant.** A `Sluggable` module with `generate_slug` and `to_param` is fine — both methods are part of the same concept.
+
+## Edge Cases
+
+**Ruby's duck typing IS interface segregation:**
+When you write a method that calls `object.each`, you've defined a one-method interface. Any Enumerable works. Ruby's duck typing naturally encourages narrow interfaces — lean into it.
+
+```ruby
+# This method's "interface" is: responds to .each and yields items with .email
+def collect_emails(collection)
+  collection.each_with_object([]) { |item, emails| emails << item.email }
+end
+
+# Works with any collection of objects that have .email
+collect_emails(User.active)
+collect_emails([subscriber_a, subscriber_b])
+collect_emails(team.members)
+```
+
+**Frozen value objects as narrow interfaces:**
+Instead of passing a User model to a service, pass a data object with only the needed attributes:
+
+```ruby
+NotificationPayload = Data.define(:email, :name, :phone)
+
+payload = NotificationPayload.new(email: user.email, name: user.name, phone: user.phone)
+NotificationService.call(payload)
+```
+
+This makes the dependency explicit and narrow.

data/skills/solid/liskov_substitution.md

@@ -0,0 +1,263 @@
+# SOLID: Liskov Substitution Principle (LSP)
+
+## Pattern
+
+If code works with a parent type, it must also work with any subtype without knowing the difference. Subtypes must honor the parent's contract — same method signatures, compatible return types, no strengthened preconditions, no weakened postconditions.
+
+In Ruby, LSP applies to duck typing: any object that claims to implement an interface must behave consistently with other objects that implement that interface.
+
+```ruby
+# GOOD: Both notifiers honor the same contract
+# Contract: #deliver(user, message) → sends a notification, returns a Result
+
+class Notifications::EmailNotifier
+  def deliver(user, message)
+    NotificationMailer.notify(user.email, message).deliver_later
+    Result.new(success: true, channel: :email)
+  rescue Net::SMTPError => e
+    Result.new(success: false, channel: :email, error: e.message)
+  end
+end
+
+class Notifications::SmsNotifier
+  def deliver(user, message)
+    truncated = message.truncate(160)
+    SmsClient.send(user.phone, truncated)
+    Result.new(success: true, channel: :sms)
+  rescue SmsClient::DeliveryError => e
+    Result.new(success: false, channel: :sms, error: e.message)
+  end
+end
+
+class Notifications::SlackNotifier
+  def deliver(user, message)
+    SlackClient.post(channel: user.slack_channel, text: message)
+    Result.new(success: true, channel: :slack)
+  rescue Slack::Web::Api::Errors::ChannelNotFound => e
+    Result.new(success: false, channel: :slack, error: e.message)
+  end
+end
+
+# The dispatcher doesn't know or care which notifier it's using
+# Any notifier is substitutable for any other — LSP satisfied
+class Notifications::Dispatcher
+  def initialize(notifiers:)
+    @notifiers = notifiers
+  end
+
+  def broadcast(user, message)
+    @notifiers.map { |notifier| notifier.deliver(user, message) }
+  end
+end
+
+# All substitutable
+dispatcher = Notifications::Dispatcher.new(notifiers: [
+  Notifications::EmailNotifier.new,
+  Notifications::SmsNotifier.new,
+  Notifications::SlackNotifier.new
+])
+results = dispatcher.broadcast(user, "Your order shipped!")
+```
+
+LSP with inheritance:
+
+```ruby
+# GOOD: Subclasses extend, they don't contradict
+class Report
+  def generate(start_date, end_date)
+    data = fetch_data(start_date, end_date)
+    format(data)
+  end
+
+  private
+
+  def fetch_data(start_date, end_date)
+    raise NotImplementedError
+  end
+
+  def format(data)
+    raise NotImplementedError
+  end
+end
+
+class RevenueReport < Report
+  private
+
+  def fetch_data(start_date, end_date)
+    Order.where(created_at: start_date..end_date).group(:status).sum(:total)
+  end
+
+  def format(data)
+    data.map { |status, total| "#{status}: $#{total}" }.join("\n")
+  end
+end
+
+class UserActivityReport < Report
+  private
+
+  def fetch_data(start_date, end_date)
+    User.where(last_active_at: start_date..end_date).group_by_day(:last_active_at).count
+  end
+
+  def format(data)
+    data.map { |date, count| "#{date}: #{count} active users" }.join("\n")
+  end
+end
+
+# Any Report subclass can be used anywhere a Report is expected
+def email_report(report, recipient, start_date, end_date)
+  content = report.generate(start_date, end_date)  # Works for any subclass
+  ReportMailer.send(recipient, content).deliver_later
+end
+
+email_report(RevenueReport.new, "cfo@company.com", 30.days.ago, Date.today)
+email_report(UserActivityReport.new, "pm@company.com", 7.days.ago, Date.today)
+```
+
+## Why This Is Good
+
+- **Substitutable objects enable polymorphism.** The `Dispatcher` works with any notifier. `email_report` works with any report. Code that depends on the interface is decoupled from specific implementations.
+- **Consistent contracts prevent surprises.** Every notifier returns a `Result` with `success?`, `channel`, and `error`. Code that processes results doesn't need special handling for each notifier type.
+- **Error handling is uniform.** Each notifier catches its own exceptions and returns a `Result`. The dispatcher never sees a raw `Net::SMTPError` or `Slack::Web::Api::Errors::ChannelNotFound` — the notifiers normalize errors into the shared contract.
+- **New types are safe.** Adding a `PushNotifier` is safe as long as it returns a `Result` from `deliver`. No existing code needs to know about push notifications.
+
+## Anti-Pattern
+
+A subtype that violates the parent's contract:
+
+```ruby
+class FileStorage
+  def save(key, content)
+    File.write(storage_path(key), content)
+    true
+  end
+
+  def read(key)
+    File.read(storage_path(key))
+  end
+
+  def delete(key)
+    File.delete(storage_path(key))
+    true
+  end
+end
+
+class ReadOnlyStorage < FileStorage
+  def save(key, content)
+    raise NotImplementedError, "ReadOnlyStorage cannot save"
+  end
+
+  def delete(key)
+    raise NotImplementedError, "ReadOnlyStorage cannot delete"
+  end
+end
+
+# This breaks LSP:
+def backup(storage, data)
+  storage.save("backup-#{Date.today}", data)  # BOOM for ReadOnlyStorage
+end
+
+backup(FileStorage.new, data)       # Works
+backup(ReadOnlyStorage.new, data)   # Raises NotImplementedError
+```
+
+```ruby
+# Another violation: changing return types
+class UserFinder
+  def find(id)
+    User.find(id)  # Returns a User or raises RecordNotFound
+  end
+end
+
+class CachedUserFinder < UserFinder
+  def find(id)
+    Rails.cache.fetch("user:#{id}") do
+      User.find_by(id: id)  # Returns nil instead of raising! Contract broken.
+    end
+  end
+end
+```
+
+## Why This Is Bad
+
+- **`ReadOnlyStorage` can't substitute for `FileStorage`.** Any code expecting a `FileStorage` that calls `save` will crash. The subclass has *strengthened the precondition* (you can't call save) — a direct LSP violation.
+- **`CachedUserFinder` changes the contract.** `UserFinder#find` raises on missing records. `CachedUserFinder#find` returns `nil`. Code that relies on the exception for flow control will silently get `nil` and crash later with a `NoMethodError` on `nil`.
+- **Type checks appear.** When subtypes are unreliable, callers start adding `is_a?` checks: `if storage.is_a?(ReadOnlyStorage)`. This defeats the purpose of polymorphism and creates brittle, coupled code.
+
+## When To Apply
+
+- **Whenever you use duck typing.** If two objects respond to the same method, they must behave the same way — same parameters accepted, same return type, same error behavior.
+- **Whenever you inherit.** Subclasses must not remove capabilities, change return types, or raise unexpected exceptions. If a subclass needs to behave differently, it probably shouldn't be a subclass.
+- **When designing interfaces for plugins or strategies.** Document the contract: what methods, what parameters, what return types, what errors. Every implementation must honor the contract.
+
+## When NOT To Apply
+
+- **Template Method pattern legitimately varies behavior.** `Report#fetch_data` raises `NotImplementedError` in the base class — subclasses are *expected* to override it. This isn't an LSP violation because the base class is abstract; no code calls `Report.new.generate` directly.
+- **Ruby doesn't have formal interfaces.** LSP in Ruby is about behavioral contracts, not type signatures. Two objects can have different class hierarchies and still be LSP-compliant if they honor the same duck-type contract.
+
+## Edge Cases
+
+**How to fix the ReadOnlyStorage problem:**
+Don't inherit. Use separate interfaces:
+
+```ruby
+module Readable
+  def read(key)
+    raise NotImplementedError
+  end
+end
+
+module Writable
+  def save(key, content)
+    raise NotImplementedError
+  end
+
+  def delete(key)
+    raise NotImplementedError
+  end
+end
+
+class FileStorage
+  include Readable
+  include Writable
+  # ... implements all methods
+end
+
+class ReadOnlyStorage
+  include Readable
+  # Only read, never promises write
+end
+
+# Code that needs to write asks for Writable:
+def backup(storage, data)
+  # storage must include Writable — ReadOnlyStorage won't be passed here
+  storage.save("backup", data)
+end
+```
+
+**Testing LSP compliance:**
+Shared examples enforce the contract across all implementations:
+
+```ruby
+RSpec.shared_examples "a notifier" do
+  it "returns a Result from deliver" do
+    result = subject.deliver(user, "test message")
+    expect(result).to respond_to(:success?, :channel, :error)
+  end
+
+  it "returns success: true or false, never nil" do
+    result = subject.deliver(user, "test")
+    expect(result.success?).to be(true).or be(false)
+  end
+end
+
+RSpec.describe Notifications::EmailNotifier do
+  subject { described_class.new }
+  it_behaves_like "a notifier"
+end
+
+RSpec.describe Notifications::SmsNotifier do
+  subject { described_class.new }
+  it_behaves_like "a notifier"
+end
+```

data/skills/solid/open_closed.md

@@ -0,0 +1,212 @@
+# SOLID: Open/Closed Principle (OCP)
+
+## Pattern
+
+Software entities should be open for extension but closed for modification. Add new behavior by writing new code (new classes, modules, or configurations) — not by editing existing, working code.
+
+In Ruby, OCP is achieved through polymorphism, duck typing, dependency injection, and the Strategy pattern — not through inheritance hierarchies.
+
+```ruby
+# GOOD: New payment methods added without modifying existing code
+
+# Each payment processor implements the same interface
+class Payments::StripeProcessor
+  def charge(amount_cents, payment_method_token)
+    Stripe::Charge.create(
+      amount: amount_cents,
+      currency: "usd",
+      source: payment_method_token
+    )
+    Result.new(success: true)
+  rescue Stripe::CardError => e
+    Result.new(success: false, error: e.message)
+  end
+end
+
+class Payments::PaypalProcessor
+  def charge(amount_cents, payment_method_token)
+    PayPal::SDK::REST::Payment.new(
+      intent: "sale",
+      payer: { payment_method: "paypal" },
+      transactions: [{ amount: { total: (amount_cents / 100.0).to_s, currency: "USD" } }]
+    ).create
+    Result.new(success: true)
+  rescue PayPal::SDK::Core::Exceptions::ServerError => e
+    Result.new(success: false, error: e.message)
+  end
+end
+
+# Adding Braintree? Write a new class. Don't touch Stripe or PayPal.
+class Payments::BraintreeProcessor
+  def charge(amount_cents, payment_method_token)
+    result = Braintree::Transaction.sale(
+      amount: (amount_cents / 100.0).round(2),
+      payment_method_nonce: payment_method_token
+    )
+    Result.new(success: result.success?, error: result.message)
+  end
+end
+
+# The service accepts any processor — open for extension via injection
+class Orders::ChargeService
+  def initialize(processor:)
+    @processor = processor
+  end
+
+  def call(order)
+    result = @processor.charge(order.total_cents, order.payment_token)
+
+    if result.success?
+      order.update!(status: :paid, paid_at: Time.current)
+    else
+      order.update!(status: :payment_failed)
+    end
+
+    result
+  end
+end
+
+# Usage — new processors slot in without touching ChargeService
+processor = Payments::StripeProcessor.new
+Orders::ChargeService.new(processor: processor).call(order)
+```
+
+Another common Ruby OCP pattern — registry/plugin architecture:
+
+```ruby
+# Notification channels — add new ones without modifying the dispatcher
+class Notifications::Dispatcher
+  REGISTRY = {}
+
+  def self.register(channel_name, handler_class)
+    REGISTRY[channel_name] = handler_class
+  end
+
+  def self.dispatch(user, message)
+    user.notification_preferences.each do |channel|
+      handler = REGISTRY[channel]
+      handler&.new&.deliver(user, message)
+    end
+  end
+end
+
+# Each channel registers itself — no switch statements, no modification to Dispatcher
+class Notifications::EmailHandler
+  def deliver(user, message)
+    NotificationMailer.notify(user, message).deliver_later
+  end
+end
+Notifications::Dispatcher.register(:email, Notifications::EmailHandler)
+
+class Notifications::SmsHandler
+  def deliver(user, message)
+    SmsClient.send(user.phone, message)
+  end
+end
+Notifications::Dispatcher.register(:sms, Notifications::SmsHandler)
+
+# Adding push notifications? New file, new class, one register call.
+class Notifications::PushHandler
+  def deliver(user, message)
+    PushService.send(user.device_token, message)
+  end
+end
+Notifications::Dispatcher.register(:push, Notifications::PushHandler)
+```
+
+## Why This Is Good
+
+- **Existing code stays untouched.** Adding a new payment processor doesn't require editing `ChargeService`, `StripeProcessor`, or `PaypalProcessor`. Tested, deployed code remains stable.
+- **Reduced regression risk.** When you don't modify existing code, you can't break existing behavior. The new `BraintreeProcessor` can only break Braintree payments.
+- **Ruby duck typing makes this natural.** No need for explicit interfaces or abstract base classes. Any object that responds to `charge(amount_cents, token)` works as a processor. Ruby's flexibility makes OCP lightweight.
+- **Dependency injection is the mechanism.** `ChargeService.new(processor: processor)` accepts any processor at runtime. The service doesn't know or care which processor it gets — it just calls `charge`.
+
+## Anti-Pattern
+
+A case/when statement that grows every time a new type is added:
+
+```ruby
+class Orders::ChargeService
+  def call(order)
+    case order.payment_method
+    when "stripe"
+      charge_with_stripe(order)
+    when "paypal"
+      charge_with_paypal(order)
+    when "braintree"
+      charge_with_braintree(order)
+    when "apple_pay"
+      charge_with_apple_pay(order)
+    # Every new payment method adds another branch HERE
+    end
+  end
+
+  private
+
+  def charge_with_stripe(order)
+    # 20 lines of Stripe-specific code
+  end
+
+  def charge_with_paypal(order)
+    # 20 lines of PayPal-specific code
+  end
+
+  def charge_with_braintree(order)
+    # 20 lines of Braintree-specific code
+  end
+
+  def charge_with_apple_pay(order)
+    # 20 lines of Apple Pay-specific code
+  end
+end
+```
+
+## Why This Is Bad
+
+- **Every new type modifies existing code.** Adding Apple Pay means opening `ChargeService` and adding a new `when` branch and a new private method. The class is modified, not extended.
+- **Growing case statements.** With 10 payment methods, this class has 10 branches and 10 private methods. It's 200+ lines of unrelated payment logic in one file.
+- **Impossible to test in isolation.** Testing Stripe logic means loading the entire `ChargeService` with all its payment method dependencies. You can't test one processor without the others being present.
+- **Violates SRP too.** `ChargeService` now has 4 reasons to change — one for each payment provider's API changes.
+
+## When To Apply
+
+- **You see a `case` or `if/elsif` that switches on a type.** `case record.type`, `if method == :stripe`, `when "csv"` — these are branching on type, which is polymorphism waiting to happen.
+- **You expect more variants in the future.** If you have 2 payment methods and expect 5, design for extension now. If you have 2 and will only ever have 2, a simple `if` is fine.
+- **Multiple team members add different variants.** If one developer adds Stripe while another adds PayPal, separate classes prevent merge conflicts and enable parallel work.
+
+## When NOT To Apply
+
+- **Stable, finite branching.** A method that handles `success` and `failure` doesn't need polymorphism. Two branches that will never grow are fine as an `if/else`.
+- **Don't create abstract factories for 2 classes.** OCP is about enabling future extension, not building frameworks. If you have 2 processors and no plans for a third, injecting a concrete processor is sufficient.
+- **Rails conventions already handle this.** STI, enums with methods, and ActiveSupport::Concern are Rails' way of achieving OCP. Don't reinvent a plugin architecture when Rails patterns suffice.
+
+## Edge Cases
+
+**Ruby blocks as the ultimate OCP mechanism:**
+Blocks let you inject behavior without any class:
+
+```ruby
+def process_items(items, &formatter)
+  items.each { |item| puts formatter.call(item) }
+end
+
+process_items(orders) { |o| "#{o.reference}: $#{o.total}" }
+process_items(orders) { |o| o.to_json }
+```
+
+**When the switch is on YOUR domain types (enums):**
+Rails enums with methods on the model can be a pragmatic alternative to full polymorphism:
+
+```ruby
+class Order < ApplicationRecord
+  enum :status, { pending: 0, confirmed: 1, shipped: 2 }
+
+  def status_label
+    { "pending" => "Awaiting Confirmation",
+      "confirmed" => "Processing",
+      "shipped" => "On Its Way" }[status]
+  end
+end
+```
+
+This is fine for display logic. For complex behavior that differs by status (different validations, different transitions, different side effects), use the State pattern instead.