rubyn-code 0.1.0

data/skills/code_quality/yagni.md

@@ -0,0 +1,176 @@
+# Code Quality: YAGNI — You Ain't Gonna Need It
+
+## Core Principle
+
+Don't build it until you need it. Every line of code is a liability — it must be tested, maintained, and understood. Code that exists "in case we need it later" is code that costs you now and may never pay off.
+
+## The Three Questions
+
+Before adding abstraction, ask:
+
+1. **Do I need this right now, or might I need it later?** If "later," don't build it.
+2. **Am I building for the problem I have, or the problem I imagine?** Solve the real problem.
+3. **What's the cost of adding this later when I actually need it?** Usually low. Build then.
+
+## Premature Abstraction
+
+```ruby
+# YAGNI VIOLATION: Building a plugin system for 1 payment provider
+class PaymentProcessorFactory
+  REGISTRY = {}
+
+  def self.register(name, klass)
+    REGISTRY[name] = klass
+  end
+
+  def self.build(name, **config)
+    klass = REGISTRY.fetch(name)
+    klass.new(**config)
+  end
+end
+
+class PaymentProcessor
+  def charge(amount, token) = raise NotImplementedError
+  def refund(transaction_id, amount) = raise NotImplementedError
+  def void(transaction_id) = raise NotImplementedError
+end
+
+class StripeProcessor < PaymentProcessor
+  def charge(amount, token)
+    # Stripe-specific code
+  end
+
+  def refund(transaction_id, amount)
+    # Stripe-specific code
+  end
+
+  def void(transaction_id)
+    # Stripe-specific code
+  end
+end
+
+PaymentProcessorFactory.register(:stripe, StripeProcessor)
+```
+
+You have ONE payment provider. The factory, the abstract base class, and the registration mechanism add ~40 lines of code that provide zero value today. When you actually need a second provider (if you ever do), adding the abstraction takes 30 minutes.
+
+```ruby
+# RIGHT-SIZED: Direct implementation for the one provider you have
+class Payments::StripeService
+  def charge(amount_cents, token)
+    charge = Stripe::Charge.create(amount: amount_cents, currency: "usd", source: token)
+    Result.new(success: true, transaction_id: charge.id)
+  rescue Stripe::CardError => e
+    Result.new(success: false, error: e.message)
+  end
+
+  def refund(charge_id, amount_cents)
+    Stripe::Refund.create(charge: charge_id, amount: amount_cents)
+    Result.new(success: true)
+  rescue Stripe::InvalidRequestError => e
+    Result.new(success: false, error: e.message)
+  end
+end
+```
+
+## Speculative Generality Examples
+
+```ruby
+# YAGNI: Config class for 2 settings
+class Configuration
+  include Singleton
+  attr_accessor :settings
+
+  def initialize
+    @settings = {}
+  end
+
+  def get(key, default: nil)
+    settings.dig(*key.to_s.split(".")) || default
+  end
+
+  def set(key, value)
+    keys = key.to_s.split(".")
+    hash = keys[0..-2].reduce(settings) { |h, k| h[k] ||= {} }
+    hash[keys.last] = value
+  end
+end
+
+# You only have: API key and model name. Just use ENV.
+# ENV["ANTHROPIC_API_KEY"] and ENV["MODEL_NAME"] are simpler.
+```
+
+```ruby
+# YAGNI: Abstract base class with one subclass
+class BaseExporter
+  def export(data)
+    header + body(data) + footer
+  end
+
+  def header = raise NotImplementedError
+  def body(data) = raise NotImplementedError
+  def footer = raise NotImplementedError
+end
+
+class CsvExporter < BaseExporter
+  def header = "id,name,total\n"
+  def body(data) = data.map { |r| "#{r.id},#{r.name},#{r.total}" }.join("\n")
+  def footer = ""
+end
+
+# One exporter doesn't need a base class. Just write CsvExporter directly.
+# When you need PdfExporter, THEN extract the common interface.
+```
+
+## The Rule of Three
+
+Don't abstract until you have three concrete examples:
+1. **First time:** Just write the code.
+2. **Second time:** Notice the duplication but tolerate it. Maybe add a comment "similar to X."
+3. **Third time:** Now extract. You have three examples to inform the right abstraction.
+
+```ruby
+# First time: inline
+class OrdersController
+  def export
+    csv = orders.map { |o| [o.reference, o.total].join(",") }.join("\n")
+    send_data csv, filename: "orders.csv"
+  end
+end
+
+# Second time: notice similarity, tolerate it
+class InvoicesController
+  def export
+    csv = invoices.map { |i| [i.number, i.amount].join(",") }.join("\n")
+    send_data csv, filename: "invoices.csv"
+  end
+end
+
+# Third time: NOW extract
+class CsvExporter
+  def self.call(records, columns:, filename:)
+    csv = records.map { |r| columns.map { |c| r.public_send(c) }.join(",") }.join("\n")
+    { data: csv, filename: filename }
+  end
+end
+```
+
+## When YAGNI Doesn't Apply
+
+- **Known requirements.** If the spec says "support Stripe and PayPal at launch," build the abstraction. That's not speculative — it's a stated requirement.
+- **Architecture boundaries.** Even with one provider, wrapping external APIs behind an adapter is good practice. The adapter isn't speculative — it isolates you from API changes.
+- **Security and data integrity.** Don't skip input validation because "we'll add it later." Security isn't optional.
+- **Testing infrastructure.** Investing in test helpers, factories, and shared examples pays off immediately — not speculatively.
+
+## The Cost of Abstraction
+
+Every abstraction has a cost:
+- **Indirection:** Readers must navigate to another file to understand behavior.
+- **Maintenance:** The abstract interface must be kept in sync with all implementations.
+- **Constraint:** Future implementations are shaped by the abstraction, which was designed without knowledge of their needs.
+
+Premature abstraction is worse than no abstraction because it constrains future design based on incomplete information. The right abstraction, built with knowledge of 3+ concrete cases, enables extension. The wrong abstraction, built speculatively, requires fighting against it.
+
+## Practical Test
+
+Ask: "If I delete this abstraction and inline the code, does anything get worse?" If no — the abstraction isn't earning its keep. Delete it.

data/skills/design_patterns/adapter.md

@@ -0,0 +1,191 @@
+# Design Pattern: Adapter
+
+## Pattern
+
+Convert the interface of one class into another interface that clients expect. Adapters let classes work together that couldn't otherwise because of incompatible interfaces. In Rails, adapters are essential at system boundaries — wrapping external APIs, gems, and services behind a consistent internal interface.
+
+```ruby
+# Your app's internal interface — what your code expects
+# Contract: .embed(texts) → Array<Array<Float>>
+
+# Adapter for the Rubyn embedding service (FastAPI sidecar)
+class Embeddings::RubynAdapter
+  def initialize(base_url:)
+    @base_url = base_url
+    @conn = Faraday.new(url: base_url) do |f|
+      f.request :json
+      f.response :json
+      f.adapter Faraday.default_adapter
+    end
+  end
+
+  def embed(texts)
+    response = @conn.post("/embed", { texts: texts, prefix: "passage" })
+    response.body["embeddings"]
+  end
+end
+
+# Adapter for OpenAI's embedding API (different URL, auth, response format)
+class Embeddings::OpenAiAdapter
+  def initialize(api_key:)
+    @conn = Faraday.new(url: "https://api.openai.com") do |f|
+      f.request :json
+      f.response :json
+      f.headers["Authorization"] = "Bearer #{api_key}"
+    end
+  end
+
+  def embed(texts)
+    response = @conn.post("/v1/embeddings", {
+      model: "text-embedding-3-small",
+      input: texts
+    })
+    # OpenAI returns { data: [{ embedding: [...] }, ...] }
+    # We normalize to Array<Array<Float>> to match our interface
+    response.body["data"]
+      .sort_by { |d| d["index"] }
+      .map { |d| d["embedding"] }
+  end
+end
+
+# Adapter for a local model via ONNX Runtime (completely different mechanism)
+class Embeddings::LocalOnnxAdapter
+  def initialize(model_path:)
+    @session = OnnxRuntime::InferenceSession.new(model_path)
+  end
+
+  def embed(texts)
+    inputs = texts.map { |text| tokenize(text) }
+    outputs = @session.run(nil, { input_ids: inputs })
+    outputs.first # Already Array<Array<Float>>
+  end
+
+  private
+
+  def tokenize(text)
+    # Tokenization logic
+  end
+end
+
+# Your service code doesn't know or care which adapter it uses
+class Codebase::IndexService
+  def initialize(embedder:)
+    @embedder = embedder  # Any adapter works
+  end
+
+  def call(project, files)
+    files.each_slice(10) do |batch|
+      contents = batch.map(&:last)
+      vectors = @embedder.embed(contents)  # Same interface, any provider
+      batch.zip(vectors).each do |(path, _), vector|
+        project.code_embeddings.upsert(
+          { file_path: path, embedding: vector },
+          unique_by: [:project_id, :file_path]
+        )
+      end
+    end
+  end
+end
+
+# Wire up in config
+embedder = Embeddings::RubynAdapter.new(base_url: ENV["EMBEDDING_SERVICE_URL"])
+# OR: Embeddings::OpenAiAdapter.new(api_key: ENV["OPENAI_API_KEY"])
+# OR: Embeddings::LocalOnnxAdapter.new(model_path: "models/code-embed.onnx")
+
+Codebase::IndexService.new(embedder: embedder).call(project, files)
+```
+
+Adapting a gem's interface to your domain:
+
+```ruby
+# The Stripe gem returns Stripe::Charge objects with their own structure.
+# Your app works with a consistent PaymentResult.
+
+PaymentResult = Data.define(:success, :transaction_id, :amount_cents, :error)
+
+class Payments::StripeAdapter
+  def charge(amount_cents:, token:, description:)
+    charge = Stripe::Charge.create(
+      amount: amount_cents,
+      currency: "usd",
+      source: token,
+      description: description
+    )
+    PaymentResult.new(
+      success: true,
+      transaction_id: charge.id,
+      amount_cents: charge.amount,
+      error: nil
+    )
+  rescue Stripe::CardError => e
+    PaymentResult.new(success: false, transaction_id: nil, amount_cents: 0, error: e.message)
+  rescue Stripe::StripeError => e
+    PaymentResult.new(success: false, transaction_id: nil, amount_cents: 0, error: "Payment service error")
+  end
+end
+
+class Payments::BraintreeAdapter
+  def charge(amount_cents:, token:, description:)
+    result = Braintree::Transaction.sale(
+      amount: (amount_cents / 100.0).round(2),
+      payment_method_nonce: token,
+      options: { submit_for_settlement: true }
+    )
+    if result.success?
+      PaymentResult.new(
+        success: true,
+        transaction_id: result.transaction.id,
+        amount_cents: (result.transaction.amount * 100).to_i,
+        error: nil
+      )
+    else
+      PaymentResult.new(success: false, transaction_id: nil, amount_cents: 0, error: result.message)
+    end
+  end
+end
+```
+
+## Why This Is Good
+
+- **Unified interface across providers.** `embedder.embed(texts)` works identically whether the backend is your Python sidecar, OpenAI, or a local ONNX model. Business logic never sees provider-specific details.
+- **Provider-specific complexity is contained.** OpenAI's response format (`{ data: [{ embedding, index }] }`) is normalized inside the adapter. Nobody else in the codebase deals with that structure.
+- **Swappable at configuration time.** Switching from OpenAI to your own model means changing one line in an initializer. No business logic changes, no test changes.
+- **Error normalization.** Each adapter catches its own exceptions (Stripe::CardError, Braintree errors) and returns a consistent `PaymentResult`. The caller never rescues provider-specific errors.
+- **Gem upgrades are isolated.** If Stripe changes their API, only `StripeAdapter` changes. Every other class in your app is insulated.
+
+## When To Apply
+
+- **Every external API integration.** Wrap third-party APIs in adapters from day one. Even if you'll never switch providers, the adapter isolates your code from their API changes.
+- **When migrating between providers.** Build the new adapter, test it, swap the configuration. Both adapters coexist during migration.
+- **Normalizing inconsistent interfaces.** Two gems that do similar things with different method names and return types — adapt them to one internal interface.
+
+## When NOT To Apply
+
+- **Internal classes with consistent interfaces.** You don't need an adapter between your own service objects if they already share an interface.
+- **Don't over-abstract stable gems.** If you use Devise and will always use Devise, wrapping every Devise method in an adapter is pointless friction.
+- **Single-use, simple integrations.** A one-off API call in a rake task doesn't need a full adapter class.
+
+## Edge Cases
+
+**Adapter + Decorator composition:**
+Adapters normalize the interface. Decorators add cross-cutting behavior. They compose naturally:
+
+```ruby
+embedder = Embeddings::RubynAdapter.new(base_url: url)   # Normalize interface
+embedder = Embeddings::RetryDecorator.new(embedder)       # Add retry
+embedder = Embeddings::LoggingDecorator.new(embedder)     # Add logging
+# Result: logged, retried, normalized embedding calls
+```
+
+**Testing adapters:**
+Test each adapter against a shared example that defines the contract:
+
+```ruby
+RSpec.shared_examples "an embedding adapter" do
+  it "returns an array of float arrays" do
+    result = subject.embed(["def hello; end"])
+    expect(result).to be_an(Array)
+    expect(result.first).to all(be_a(Float))
+  end
+end
+```

data/skills/design_patterns/bridge_memento_visitor.md

@@ -0,0 +1,254 @@
+# Design Pattern: Bridge
+
+## Pattern
+
+Separate an abstraction from its implementation so the two can vary independently. In Ruby, this means composing objects rather than inheriting — passing the implementation as a dependency.
+
+```ruby
+# The "abstraction" — what the caller interacts with
+class NotificationSender
+  def initialize(transport:, formatter:)
+    @transport = transport    # HOW to send (email, SMS, push)
+    @formatter = formatter    # HOW to format (plain, HTML, markdown)
+  end
+
+  def send(user, event)
+    message = @formatter.format(event)
+    @transport.deliver(user, message)
+  end
+end
+
+# Transports (one dimension of variation)
+class EmailTransport
+  def deliver(user, message)
+    NotificationMailer.send(to: user.email, body: message).deliver_later
+  end
+end
+
+class SmsTransport
+  def deliver(user, message)
+    SmsClient.send(user.phone, message.truncate(160))
+  end
+end
+
+# Formatters (another dimension of variation)
+class PlainFormatter
+  def format(event)
+    "#{event.title}: #{event.description}"
+  end
+end
+
+class HtmlFormatter
+  def format(event)
+    "<h2>#{event.title}</h2><p>#{event.description}</p>"
+  end
+end
+
+# Mix and match independently — 2 transports × 2 formatters = 4 combinations
+# Without Bridge, you'd need: EmailPlainNotifier, EmailHtmlNotifier,
+# SmsPlainNotifier, SmsHtmlNotifier — and N×M more as you add options
+
+sender = NotificationSender.new(transport: EmailTransport.new, formatter: HtmlFormatter.new)
+sender.send(user, order_confirmed_event)
+```
+
+**When to use:** When you have two or more dimensions of variation that would otherwise create an explosion of subclasses.
+
+---
+
+# Design Pattern: Memento
+
+## Pattern
+
+Capture an object's internal state so it can be restored later, without exposing the internals. Useful for undo, versioning, and audit trails.
+
+```ruby
+# Memento — a frozen snapshot of state
+class OrderMemento
+  attr_reader :state, :created_at
+
+  def initialize(order)
+    @state = {
+      status: order.status,
+      total: order.total,
+      shipping_address: order.shipping_address,
+      discount_amount: order.discount_amount,
+      notes: order.notes
+    }.freeze
+    @created_at = Time.current
+    freeze
+  end
+end
+
+# Originator — the object that creates and restores from mementos
+class Order < ApplicationRecord
+  def save_snapshot
+    OrderMemento.new(self)
+  end
+
+  def restore_from(memento)
+    assign_attributes(memento.state)
+    save!
+  end
+end
+
+# Caretaker — manages the history of mementos
+class OrderHistory
+  def initialize
+    @snapshots = []
+  end
+
+  def push(memento)
+    @snapshots.push(memento)
+  end
+
+  def pop
+    @snapshots.pop
+  end
+
+  def peek
+    @snapshots.last
+  end
+
+  def size
+    @snapshots.size
+  end
+end
+
+# Usage — admin makes changes with undo support
+history = OrderHistory.new
+order = Order.find(params[:id])
+
+# Save state before changes
+history.push(order.save_snapshot)
+order.update!(status: :shipped, notes: "Expedited shipping")
+
+# Oops, wrong order — undo
+previous = history.pop
+order.restore_from(previous)
+# Order is back to its previous state
+```
+
+**When to use:** Undo/redo, draft saving, version history, audit trails where you need to restore previous state.
+
+**Rails built-in alternative:** The `paper_trail` gem provides automatic versioning with mementos stored in the database.
+
+---
+
+# Design Pattern: Visitor
+
+## Pattern
+
+Separate an algorithm from the objects it operates on. Define operations in visitor objects, and let each element "accept" the visitor. This lets you add new operations without modifying the element classes.
+
+```ruby
+# Elements — domain objects that accept visitors
+class Order < ApplicationRecord
+  def accept(visitor)
+    visitor.visit_order(self)
+  end
+end
+
+class LineItem < ApplicationRecord
+  def accept(visitor)
+    visitor.visit_line_item(self)
+  end
+end
+
+class Discount < ApplicationRecord
+  def accept(visitor)
+    visitor.visit_discount(self)
+  end
+end
+
+# Visitor 1: Calculate tax differently per element type
+class TaxCalculatorVisitor
+  attr_reader :total_tax
+
+  def initialize(tax_rate:)
+    @tax_rate = tax_rate
+    @total_tax = 0
+  end
+
+  def visit_order(order)
+    order.line_items.each { |item| item.accept(self) }
+    order.discounts.each { |discount| discount.accept(self) }
+  end
+
+  def visit_line_item(item)
+    @total_tax += (item.quantity * item.unit_price * @tax_rate).round
+  end
+
+  def visit_discount(discount)
+    @total_tax -= (discount.amount * @tax_rate).round
+  end
+end
+
+# Visitor 2: Export elements to different formats
+class CsvExportVisitor
+  attr_reader :rows
+
+  def initialize
+    @rows = [%w[type reference amount]]
+  end
+
+  def visit_order(order)
+    @rows << ["order", order.reference, order.total]
+    order.line_items.each { |item| item.accept(self) }
+  end
+
+  def visit_line_item(item)
+    @rows << ["line_item", item.product.name, item.quantity * item.unit_price]
+  end
+
+  def visit_discount(discount)
+    @rows << ["discount", discount.code, -discount.amount]
+  end
+
+  def to_csv
+    @rows.map { |row| row.join(",") }.join("\n")
+  end
+end
+
+# Usage — different operations, same elements
+tax_visitor = TaxCalculatorVisitor.new(tax_rate: 0.08)
+order.accept(tax_visitor)
+tax_visitor.total_tax  # => calculated tax
+
+csv_visitor = CsvExportVisitor.new
+order.accept(csv_visitor)
+csv_visitor.to_csv  # => CSV string
+```
+
+**When to use:** When you need multiple unrelated operations on a set of element types, and you don't want to pollute the element classes with every operation. Common in compilers, report generators, and data exporters.
+
+**When NOT to use:** In most Rails apps. Visitor is powerful but heavyweight. If you have 2-3 operations, methods on the models or service objects are simpler. Visitor shines when you have 5+ operations across 5+ element types.
+
+---
+
+## Ruby Idiomatic Alternative to Visitor
+
+Ruby's duck typing often makes the Visitor pattern unnecessary. Instead of the formal accept/visit protocol, use polymorphic method dispatch:
+
+```ruby
+# Simpler Ruby approach — no accept/visit ceremony
+class ReportGenerator
+  def generate(elements)
+    elements.each do |element|
+      case element
+      when Order then process_order(element)
+      when LineItem then process_line_item(element)
+      when Discount then process_discount(element)
+      end
+    end
+  end
+
+  private
+
+  def process_order(order) = # ...
+  def process_line_item(item) = # ...
+  def process_discount(discount) = # ...
+end
+```
+
+This is less "pure" OOP but more idiomatic Ruby. Use the formal Visitor when the element hierarchy is stable but operations change frequently.