rubyn-code 0.1.0

data/skills/design_patterns/facade.md

@@ -0,0 +1,133 @@
+# Design Pattern: Facade
+
+## Pattern
+
+Provide a simplified interface to a complex subsystem. The facade hides the complexity of multiple classes, APIs, or steps behind a single method call. In Rails, service objects often act as facades over multi-step operations.
+
+```ruby
+# The subsystem is complex — embedding client, chunker, database, change detection
+# The facade makes it one call
+
+class Codebase::IndexFacade
+  def initialize(
+    embedding_client: Rails.application.config.x.embedding_client,
+    chunker: Codebase::Chunker.new,
+    change_detector: Codebase::ChangeDetector.new
+  )
+    @embedding_client = embedding_client
+    @chunker = chunker
+    @change_detector = change_detector
+  end
+
+  # One method hides 5 subsystem interactions
+  def index_project(project, files)
+    changed_files = @change_detector.filter_changed(project, files)
+    return { indexed: 0, skipped: files.size } if changed_files.empty?
+
+    changed_files.each_slice(10) do |batch|
+      chunks = batch.flat_map { |path, content| @chunker.split(path, content) }
+      vectors = @embedding_client.embed(chunks.map(&:text))
+
+      chunks.zip(vectors).each do |chunk, vector|
+        project.code_embeddings.upsert(
+          {
+            file_path: chunk.path,
+            chunk_content: chunk.text,
+            chunk_type: chunk.type,
+            embedding: vector,
+            file_hash: chunk.file_hash,
+            last_embedded_at: Time.current
+          },
+          unique_by: [:project_id, :file_path, :chunk_type, :chunk_content]
+        )
+      end
+    end
+
+    project.update!(last_indexed_at: Time.current)
+    { indexed: changed_files.size, skipped: files.size - changed_files.size }
+  end
+end
+
+# Caller doesn't know about chunkers, change detectors, or embedding clients
+result = Codebase::IndexFacade.new.index_project(project, files)
+puts "Indexed #{result[:indexed]} files, skipped #{result[:skipped]}"
+```
+
+Another example — wrapping a multi-step onboarding process:
+
+```ruby
+class Onboarding::Facade
+  def self.call(registration_params)
+    new(registration_params).call
+  end
+
+  def initialize(params)
+    @params = params
+  end
+
+  def call
+    user = create_user
+    project = create_default_project(user)
+    api_key = generate_api_key(user)
+    seed_credits(user)
+    send_welcome(user)
+
+    Result.new(success: true, user: user, project: project, api_key: api_key)
+  rescue ActiveRecord::RecordInvalid => e
+    Result.new(success: false, error: e.record.errors.full_messages.join(", "))
+  end
+
+  private
+
+  def create_user
+    User.create!(
+      email: @params[:email],
+      password: @params[:password],
+      name: @params[:name]
+    )
+  end
+
+  def create_default_project(user)
+    project = Project.create!(name: "My First Project")
+    ProjectMembership.create!(user: user, project: project, role: :owner)
+    project
+  end
+
+  def generate_api_key(user)
+    ApiKey.create!(user: user, name: "Default")
+  end
+
+  def seed_credits(user)
+    CreditLedger.create!(user: user, amount: 30, description: "Welcome credits")
+  end
+
+  def send_welcome(user)
+    WelcomeMailer.welcome(user).deliver_later
+  end
+end
+
+# Controller is one line
+result = Onboarding::Facade.call(registration_params)
+```
+
+## Why This Is Good
+
+- **One entry point for a complex operation.** `IndexFacade.new.index_project(project, files)` hides change detection, chunking, embedding, upserting, and timestamp updates behind one call.
+- **Subsystem classes remain independent.** `Chunker`, `ChangeDetector`, and `EmbeddingClient` don't know about each other. The facade coordinates them.
+- **Easy to test at two levels.** Integration test: call the facade and assert the database state. Unit tests: test each subsystem class in isolation.
+- **Callers are decoupled from subsystem changes.** If you replace the chunker algorithm, the facade's interface doesn't change. Callers never know.
+
+## When To Apply
+
+- **Multi-step operations.** Onboarding, order processing, codebase indexing — anything that coordinates 3+ subsystems.
+- **Complex API integrations.** Wrapping a third-party SDK's 5-step authentication flow behind `Auth::Facade.authenticate(credentials)`.
+- **Simplifying legacy code.** Wrap a messy subsystem in a clean facade before refactoring the internals.
+
+## When NOT To Apply
+
+- **Single-step operations.** Wrapping `User.create!(params)` in a facade adds a pointless layer.
+- **Don't hide everything.** If callers sometimes need fine-grained control over individual subsystems, expose them alongside the facade — don't force everything through one entry point.
+
+## Rails Connection
+
+Most Rails service objects ARE facades. `Orders::CreateService` is a facade over validation, persistence, payment charging, and notification. The pattern is so common in Rails that we don't always name it — but recognizing it helps design better services.

data/skills/design_patterns/factory_method.md

@@ -0,0 +1,169 @@
+# Design Pattern: Factory Method
+
+## Pattern
+
+Define a method that creates objects without specifying the exact class. Let subclasses or configuration determine which class to instantiate. In Ruby, factories are often class methods, configuration hashes, or registry patterns rather than subclass hierarchies.
+
+```ruby
+# Factory method as a class method with registration
+class Notifications::Factory
+  REGISTRY = {}
+
+  def self.register(channel, klass)
+    REGISTRY[channel.to_sym] = klass
+  end
+
+  def self.build(channel, **options)
+    klass = REGISTRY.fetch(channel.to_sym) do
+      raise ArgumentError, "Unknown notification channel: #{channel}. Available: #{REGISTRY.keys.join(', ')}"
+    end
+    klass.new(**options)
+  end
+end
+
+class Notifications::EmailNotifier
+  def initialize(from: "noreply@rubyn.ai")
+    @from = from
+  end
+
+  def deliver(user, message)
+    NotificationMailer.notify(to: user.email, from: @from, body: message).deliver_later
+  end
+end
+Notifications::Factory.register(:email, Notifications::EmailNotifier)
+
+class Notifications::SmsNotifier
+  def initialize(provider: :twilio)
+    @provider = provider
+  end
+
+  def deliver(user, message)
+    SmsClient.new(provider: @provider).send(user.phone, message.truncate(160))
+  end
+end
+Notifications::Factory.register(:sms, Notifications::SmsNotifier)
+
+# Usage — caller doesn't know or import the concrete class
+notifier = Notifications::Factory.build(:email)
+notifier.deliver(user, "Your order shipped!")
+
+notifier = Notifications::Factory.build(:sms, provider: :vonage)
+notifier.deliver(user, "Your order shipped!")
+```
+
+Factory method on a model — named constructors:
+
+```ruby
+class Order < ApplicationRecord
+  def self.from_cart(cart, user:)
+    new(
+      user: user,
+      shipping_address: user.default_address,
+      line_items: cart.items.map { |item|
+        LineItem.new(product: item.product, quantity: item.quantity, unit_price: item.product.price)
+      }
+    )
+  end
+
+  def self.from_api(params)
+    new(
+      user: User.find(params[:user_id]),
+      shipping_address: params[:shipping_address],
+      line_items: params[:items].map { |item|
+        LineItem.new(product_id: item[:product_id], quantity: item[:quantity])
+      }
+    )
+  end
+
+  def self.reorder(previous_order)
+    from_cart(
+      OpenStruct.new(items: previous_order.line_items),
+      user: previous_order.user
+    )
+  end
+end
+
+# Each factory method communicates intent and handles context-specific setup
+order = Order.from_cart(shopping_cart, user: current_user)
+order = Order.from_api(api_params)
+order = Order.reorder(previous_order)
+```
+
+Configuration-driven factory:
+
+```ruby
+# Embedding client factory — environment determines the implementation
+class Embeddings::ClientFactory
+  def self.build
+    case Rails.env
+    when "production"
+      Embeddings::HttpClient.new(base_url: ENV.fetch("EMBEDDING_SERVICE_URL"))
+    when "test"
+      Embeddings::FakeClient.new
+    when "development"
+      if ENV["EMBEDDING_SERVICE_URL"].present?
+        Embeddings::HttpClient.new(base_url: ENV["EMBEDDING_SERVICE_URL"])
+      else
+        Embeddings::FakeClient.new
+      end
+    end
+  end
+end
+
+# config/initializers/embeddings.rb
+Rails.application.config.x.embedding_client = Embeddings::ClientFactory.build
+```
+
+## Why This Is Good
+
+- **Decouples creation from use.** The code that uses a notifier doesn't need to know which concrete class to instantiate. It asks the factory for `:email` and gets back a ready-to-use object.
+- **Named constructors are self-documenting.** `Order.from_cart(cart, user:)` tells you exactly what context the order is being created in. `Order.new(user: user, ...)` doesn't.
+- **New types don't require modifying callers.** Adding a `PushNotifier` means registering it with the factory. Every caller that uses `Factory.build(:push)` works immediately.
+- **Environment-aware factories centralize configuration.** One place decides that production uses the real embedding service and tests use a fake.
+
+## When To Apply
+
+- **Multiple types with the same interface.** Notification channels, payment processors, export formatters, AI model clients — any family of interchangeable implementations.
+- **Complex construction.** When building an object requires 5+ lines of setup, configuration lookups, or conditional logic, wrap it in a factory method.
+- **Named constructors for models.** When the same model is created from different sources (web form, API, CSV import) with different setup requirements.
+
+## When NOT To Apply
+
+- **Simple `new` calls.** `User.new(email: email, name: name)` doesn't need a factory. Factories solve complex or polymorphic construction, not all construction.
+- **One implementation.** If there's only one notifier and will only ever be one, skip the factory. Direct instantiation is clearer.
+- **Rails model `.create` with simple params.** Don't wrap `Order.create!(params)` in a factory just for abstraction. Use factories when there's actual construction complexity.
+
+## Rails Example
+
+```ruby
+# Service object factory for AI interactions — selects strategy based on request type
+class Ai::ServiceFactory
+  SERVICES = {
+    "refactor" => Ai::RefactorService,
+    "review" => Ai::ReviewService,
+    "explain" => Ai::ExplainService,
+    "generate" => Ai::GenerateService,
+    "debug" => Ai::DebugService
+  }.freeze
+
+  def self.build(request_type, **dependencies)
+    service_class = SERVICES.fetch(request_type) do
+      raise ArgumentError, "Unknown AI request type: #{request_type}"
+    end
+    service_class.new(**dependencies)
+  end
+end
+
+# API controller uses the factory
+class Api::V1::AiController < Api::V1::BaseController
+  def create
+    service = Ai::ServiceFactory.build(
+      params[:type],
+      client: Rails.application.config.x.ai_client,
+      pricing: current_pricing_strategy
+    )
+    result = service.call(params[:prompt], context: build_context)
+    render json: result
+  end
+end
+```

data/skills/design_patterns/iterator.md

@@ -0,0 +1,116 @@
+# Design Pattern: Iterator
+
+## Pattern
+
+Provide a way to traverse elements of a collection without exposing its underlying structure. Ruby's `Enumerable` module IS the Iterator pattern — include it in any class that defines `each`, and you get 50+ traversal methods for free.
+
+```ruby
+# Custom collection with Enumerable — the Ruby way to implement Iterator
+class CodeChunkCollection
+  include Enumerable
+
+  def initialize
+    @chunks = []
+  end
+
+  def add(chunk)
+    @chunks << chunk
+    self
+  end
+
+  # Define `each` — Enumerable gives you everything else
+  def each(&block)
+    @chunks.each(&block)
+  end
+
+  # Optional: define <=> on elements for sort methods
+  def by_relevance(query_embedding)
+    sort_by { |chunk| -chunk.similarity_to(query_embedding) }
+  end
+end
+
+class CodeChunk
+  attr_reader :file_path, :content, :embedding, :chunk_type
+
+  def initialize(file_path:, content:, embedding:, chunk_type:)
+    @file_path = file_path
+    @content = content
+    @embedding = embedding
+    @chunk_type = chunk_type
+  end
+
+  def similarity_to(other_embedding)
+    dot_product(embedding, other_embedding)
+  end
+
+  private
+
+  def dot_product(a, b)
+    a.zip(b).sum { |x, y| x * y }
+  end
+end
+
+# Usage — all Enumerable methods work automatically
+chunks = CodeChunkCollection.new
+chunks.add(CodeChunk.new(file_path: "app/models/order.rb", content: "class Order...", embedding: [...], chunk_type: "class"))
+chunks.add(CodeChunk.new(file_path: "app/services/create.rb", content: "class Create...", embedding: [...], chunk_type: "class"))
+
+# All these work because we included Enumerable and defined each:
+chunks.map(&:file_path)                    # ["app/models/order.rb", "app/services/create.rb"]
+chunks.select { |c| c.chunk_type == "class" }
+chunks.count                                # 2
+chunks.any? { |c| c.file_path.include?("models") }
+chunks.flat_map { |c| c.content.lines }
+chunks.group_by(&:chunk_type)
+chunks.min_by { |c| c.file_path.length }
+```
+
+### External Iterator with Enumerator
+
+```ruby
+# When you need lazy or external iteration control
+class PaginatedApiIterator
+  include Enumerable
+
+  def initialize(client, endpoint, per_page: 100)
+    @client = client
+    @endpoint = endpoint
+    @per_page = per_page
+  end
+
+  def each
+    page = 1
+    loop do
+      results = @client.get(@endpoint, page: page, per_page: @per_page)
+      break if results.empty?
+
+      results.each { |item| yield item }
+      page += 1
+    end
+  end
+end
+
+# Iterate over ALL pages transparently
+iterator = PaginatedApiIterator.new(api_client, "/orders")
+iterator.each { |order| process(order) }
+
+# Or use lazily — only fetches pages as needed
+iterator.lazy.select { |o| o["status"] == "pending" }.first(10)
+```
+
+## Why This Is Good
+
+- **Include `Enumerable`, get 50+ methods.** `map`, `select`, `reduce`, `any?`, `none?`, `group_by`, `sort_by`, `flat_map`, `tally`, `min_by`, `max_by`, `chunk`, `each_slice` — all from defining one `each` method.
+- **Lazy evaluation for large/infinite collections.** `.lazy` chains don't materialize intermediate arrays. Process a 10GB file line by line without loading it into memory.
+- **Uniform interface.** Any Enumerable collection works with any method that accepts an Enumerable. Your custom collection is instantly compatible with the entire Ruby ecosystem.
+
+## When To Apply
+
+- **Any class that holds a collection.** If your class wraps an array, hash, or tree of objects, include `Enumerable` and define `each`.
+- **Paginated API responses.** Wrap pagination logic in an iterator so callers see a seamless stream of items.
+- **Tree traversal.** Define `each` to walk the tree (depth-first, breadth-first), and all Enumerable methods work on tree nodes.
+
+## When NOT To Apply
+
+- **You're just wrapping an Array.** If your class is a thin wrapper around `@items`, consider exposing the array directly or using `delegate :each, :map, :select, to: :items` instead of a full Enumerable include.
+- **ActiveRecord already provides this.** `Order.where(status: :pending).each` — ActiveRecord relations are already iterable. Don't wrap them in another iterator.

data/skills/design_patterns/mediator.md

@@ -0,0 +1,133 @@
+# Design Pattern: Mediator
+
+## Pattern
+
+Reduce chaotic dependencies between objects by centralizing communication through a mediator. Instead of objects referencing each other directly, they communicate through the mediator, which coordinates the interaction.
+
+In Rails, this maps to orchestrator services that coordinate multiple subsystems without those subsystems knowing about each other.
+
+```ruby
+# Without Mediator: Objects reference each other directly
+# Order knows about Inventory, Payment, Notification, Analytics
+# Inventory knows about Order, Notification
+# Payment knows about Order, Notification, Analytics
+# Everything is coupled to everything
+
+# With Mediator: One orchestrator coordinates everything
+class Orders::CheckoutMediator
+  def initialize(
+    inventory: Inventory::ReservationService.new,
+    payment: Payments::ChargeService.new,
+    notification: Notifications::Dispatcher.new,
+    analytics: Analytics::Tracker.new
+  )
+    @inventory = inventory
+    @payment = payment
+    @notification = notification
+    @analytics = analytics
+  end
+
+  def checkout(order, payment_method)
+    # Step 1: Reserve inventory
+    reservation = @inventory.reserve(order.line_items)
+    unless reservation.success?
+      return Result.new(success: false, error: "Items unavailable: #{reservation.error}")
+    end
+
+    # Step 2: Charge payment
+    charge = @payment.charge(order.total_cents, payment_method.token)
+    unless charge.success?
+      @inventory.release(reservation.id)  # Compensate
+      return Result.new(success: false, error: "Payment failed: #{charge.error}")
+    end
+
+    # Step 3: Confirm order
+    order.update!(
+      status: :confirmed,
+      confirmed_at: Time.current,
+      payment_transaction_id: charge.transaction_id
+    )
+
+    # Step 4: Side effects (non-critical)
+    @notification.dispatch(order.user, "Order #{order.reference} confirmed!")
+    @analytics.track("checkout_completed", order_id: order.id, total: order.total)
+
+    Result.new(success: true, order: order)
+  rescue StandardError => e
+    # Compensate on unexpected failure
+    @inventory.release(reservation&.id) if reservation&.success?
+    @payment.refund(charge.transaction_id) if charge&.success?
+    raise
+  end
+end
+
+# Each service is independent — none knows about the others
+class Inventory::ReservationService
+  def reserve(line_items)
+    # Only knows about inventory
+  end
+
+  def release(reservation_id)
+    # Only knows about inventory
+  end
+end
+
+class Payments::ChargeService
+  def charge(amount_cents, token)
+    # Only knows about payments
+  end
+
+  def refund(transaction_id)
+    # Only knows about payments
+  end
+end
+```
+
+## Why This Is Good
+
+- **Subsystems are decoupled.** `Inventory::ReservationService` doesn't know about payments. `Payments::ChargeService` doesn't know about notifications. Each can be developed, tested, and deployed independently.
+- **The workflow is visible in one place.** Open `CheckoutMediator` and read the entire checkout flow: reserve → charge → confirm → notify → track. The orchestration logic is centralized.
+- **Compensation logic is explicit.** If payment fails, inventory is released. If anything unexpected happens, both are rolled back. This saga-style coordination is easy to reason about when it's in one mediator.
+- **Easy to modify the flow.** Adding fraud detection between reserve and charge means adding one step in the mediator. No other services change.
+- **Testable with injected doubles.** Each service is injected, so tests can verify the orchestration without real inventory, payments, or notifications.
+
+## Anti-Pattern
+
+Objects communicating directly, creating a web of dependencies:
+
+```ruby
+# BAD: Order model orchestrates everything
+class Order < ApplicationRecord
+  after_create :reserve_inventory
+  after_create :charge_payment
+  after_create :send_notification
+  after_create :track_analytics
+
+  private
+
+  def reserve_inventory
+    Inventory::ReservationService.new.reserve(line_items)
+  end
+
+  def charge_payment
+    result = Payments::ChargeService.new.charge(total_cents, user.default_payment_method.token)
+    unless result.success?
+      Inventory::ReservationService.new.release(inventory_reservation_id)
+      raise "Payment failed"
+    end
+  end
+  # ... Order knows about EVERY subsystem
+end
+```
+
+## When To Apply
+
+- **Multi-step workflows** — checkout, registration, order fulfillment, onboarding. Any flow that touches 3+ subsystems.
+- **When objects are becoming too interconnected.** If Service A calls Service B which calls Service C which calls Service A, you need a mediator to break the cycle.
+- **Saga/compensation patterns.** When steps must be rolled back if later steps fail, a mediator manages the compensation logic.
+
+## When NOT To Apply
+
+- **Two objects communicating.** A service calling one other service doesn't need a mediator. That's just a method call.
+- **Event-driven communication works better.** If subsystems don't need coordination (just fire-and-forget), use the Observer pattern instead.
+- **The mediator becomes a god object.** If the mediator is 500 lines with 20 dependencies, split it into smaller mediators for sub-workflows.