rubyn-code 0.1.0

data/skills/rails/api_design.md

@@ -0,0 +1,212 @@
+# Rails: API Design
+
+## Pattern
+
+Design APIs to be consistent, versioned, and self-documenting. Use Grape or Rails API mode with `jbuilder`/`jsonapi-serializer`. Follow RESTful conventions. Handle errors uniformly.
+
+### API Controller Structure
+
+```ruby
+# app/controllers/api/v1/base_controller.rb
+module Api
+  module V1
+    class BaseController < ActionController::API
+      include Authenticatable
+      include Paginatable
+      include ErrorHandling
+
+      before_action :authenticate!
+
+      private
+
+      def render_success(data, status: :ok, meta: {})
+        response = { data: data }
+        response[:meta] = meta if meta.present?
+        render json: response, status: status
+      end
+
+      def render_created(data)
+        render_success(data, status: :created)
+      end
+
+      def render_error(message, status:, details: nil)
+        body = { error: { message: message } }
+        body[:error][:details] = details if details
+        render json: body, status: status
+      end
+    end
+  end
+end
+```
+
+```ruby
+# app/controllers/api/v1/orders_controller.rb
+module Api
+  module V1
+    class OrdersController < BaseController
+      def index
+        orders = paginate(current_user.orders.includes(:line_items).recent)
+
+        render_success(
+          orders.map { |o| OrderSerializer.new(o).as_json },
+          meta: pagination_meta(orders)
+        )
+      end
+
+      def show
+        order = current_user.orders.find(params[:id])
+        render_success(OrderSerializer.new(order).as_json)
+      end
+
+      def create
+        result = Orders::CreateService.call(order_params.to_h, current_user)
+
+        if result.success?
+          render_created(OrderSerializer.new(result.order).as_json)
+        else
+          render_error("Validation failed", status: :unprocessable_entity,
+            details: result.order.errors.full_messages)
+        end
+      end
+
+      private
+
+      def order_params
+        params.require(:order).permit(:shipping_address, line_items: [:product_id, :quantity])
+      end
+    end
+  end
+end
+```
+
+### Consistent Error Responses
+
+```ruby
+# app/controllers/concerns/error_handling.rb
+module ErrorHandling
+  extend ActiveSupport::Concern
+
+  included do
+    rescue_from ActiveRecord::RecordNotFound do |e|
+      render_error("Resource not found", status: :not_found)
+    end
+
+    rescue_from ActiveRecord::RecordInvalid do |e|
+      render_error("Validation failed", status: :unprocessable_entity,
+        details: e.record.errors.full_messages)
+    end
+
+    rescue_from ActionController::ParameterMissing do |e|
+      render_error("Missing parameter: #{e.param}", status: :bad_request)
+    end
+
+    rescue_from Pundit::NotAuthorizedError do
+      render_error("Forbidden", status: :forbidden)
+    end
+  end
+end
+```
+
+### Serializers
+
+```ruby
+# app/serializers/order_serializer.rb
+class OrderSerializer
+  def initialize(order)
+    @order = order
+  end
+
+  def as_json(*)
+    {
+      id: @order.id,
+      reference: @order.reference,
+      status: @order.status,
+      total: @order.total,
+      shipping_address: @order.shipping_address,
+      line_items: @order.line_items.map { |li| LineItemSerializer.new(li).as_json },
+      created_at: @order.created_at.iso8601,
+      updated_at: @order.updated_at.iso8601
+    }
+  end
+end
+```
+
+### Versioning
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  namespace :api do
+    namespace :v1 do
+      resources :orders, only: [:index, :show, :create, :update, :destroy]
+      resources :projects, only: [:index, :show, :create] do
+        resources :embeddings, only: [:index, :create], controller: "project_embeddings"
+      end
+      namespace :ai do
+        post :refactor
+        post :review
+        post :explain
+      end
+    end
+  end
+end
+```
+
+### Authentication
+
+```ruby
+# app/controllers/concerns/authenticatable.rb
+module Authenticatable
+  extend ActiveSupport::Concern
+
+  private
+
+  def authenticate!
+    token = request.headers["Authorization"]&.delete_prefix("Bearer ")
+    render_error("Unauthorized", status: :unauthorized) and return unless token
+
+    api_key = ApiKey.active.find_by_token(token)
+    render_error("Invalid API key", status: :unauthorized) and return unless api_key
+
+    api_key.touch(:last_used_at)
+    @current_user = api_key.user
+  end
+
+  def current_user
+    @current_user
+  end
+end
+```
+
+## Why This Is Good
+
+- **Consistent response shape.** Every success returns `{ data: ... }`. Every error returns `{ error: { message: ..., details: ... } }`. Clients parse responses predictably.
+- **Versioned from day one.** `/api/v1/` allows breaking changes in v2 without breaking existing clients.
+- **Centralized error handling.** `rescue_from` in a concern handles all common exceptions. No begin/rescue in every action.
+- **Serializers control the API surface.** Only expose the fields you intend. Internal fields (password_digest, internal notes) never leak.
+- **Pagination metadata in every list endpoint.** Clients always know total count, current page, and total pages.
+
+## Anti-Pattern
+
+Inconsistent responses, no versioning, and exposing model internals:
+
+```ruby
+# BAD: render model directly
+def show
+  render json: Order.find(params[:id])
+  # Exposes EVERY column including internal fields
+end
+
+# BAD: inconsistent error formats
+def create
+  order = Order.create!(params)
+  render json: order
+rescue => e
+  render json: { msg: e.message }, status: 500  # Different shape than other errors
+end
+```
+
+## When To Apply
+
+- **Every API.** Consistent structure, versioning, and error handling should be established in the first endpoint.
+- **Even internal APIs.** Microservice-to-microservice APIs benefit from the same discipline. Future developers will thank you.

data/skills/rails/associations.md

@@ -0,0 +1,182 @@
+# Rails: ActiveRecord Associations
+
+## Pattern
+
+Define associations explicitly with appropriate options. Always set `dependent` on `has_many`. Use `inverse_of` when Rails can't infer it. Prefer `has_many :through` over `has_and_belongs_to_many`. Use `counter_cache` to avoid N+1 counts.
+
+```ruby
+class User < ApplicationRecord
+  has_many :orders, dependent: :destroy, inverse_of: :user
+  has_many :line_items, through: :orders
+  has_many :reviews, dependent: :destroy
+  has_many :project_memberships, dependent: :destroy
+  has_many :projects, through: :project_memberships
+  has_one :profile, dependent: :destroy
+
+  # Optional belongs_to (Rails 5+ requires belongs_to by default)
+  belongs_to :company, optional: true
+end
+
+class Order < ApplicationRecord
+  belongs_to :user, counter_cache: true
+  has_many :line_items, dependent: :destroy, inverse_of: :order
+  has_one :shipment, dependent: :destroy
+
+  # Scoped association
+  has_many :active_line_items, -> { where(cancelled: false) },
+           class_name: "LineItem",
+           inverse_of: :order
+end
+
+class LineItem < ApplicationRecord
+  belongs_to :order, counter_cache: true
+  belongs_to :product
+
+  # Validate presence of the association, not just the foreign key
+  validates :order, presence: true
+  validates :product, presence: true
+end
+```
+
+`has_many :through` for many-to-many with join model:
+
+```ruby
+class Project < ApplicationRecord
+  has_many :project_memberships, dependent: :destroy
+  has_many :users, through: :project_memberships
+end
+
+class ProjectMembership < ApplicationRecord
+  belongs_to :project
+  belongs_to :user
+
+  enum :role, { owner: 0, admin: 1, member: 2, viewer: 3 }
+
+  validates :project_id, uniqueness: { scope: :user_id }
+end
+
+class User < ApplicationRecord
+  has_many :project_memberships, dependent: :destroy
+  has_many :projects, through: :project_memberships
+
+  def role_in(project)
+    project_memberships.find_by(project: project)&.role
+  end
+
+  def member_of?(project)
+    project_memberships.exists?(project: project)
+  end
+end
+```
+
+## Why This Is Good
+
+- **`dependent: :destroy` prevents orphans.** When a user is deleted, their orders are destroyed too. Without this, you get orphaned records with foreign keys pointing to nothing.
+- **`inverse_of` optimizes memory.** Rails reuses the same object in memory instead of loading a new one. `order.user` and `user.orders.first.user` return the same object instance, saving queries and preventing stale data.
+- **`counter_cache` eliminates count queries.** `user.orders_count` reads a column instead of running `SELECT COUNT(*)`. For pages that display counts for many records, this prevents N+1 count queries.
+- **`has_many :through` gives you a join model.** The join model can have its own attributes (role, permissions, created_at), validations, and callbacks. `has_and_belongs_to_many` can't.
+- **Scoped associations provide named, preloadable subsets.** `order.active_line_items` is preloadable with `includes(:active_line_items)` and reads clearly.
+
+## Anti-Pattern
+
+Missing dependent options, using HABTM, and ignoring inverse_of:
+
+```ruby
+class User < ApplicationRecord
+  # BAD: No dependent — deleting a user orphans all their orders
+  has_many :orders
+
+  # BAD: HABTM — no join model, can't add attributes or validations
+  has_and_belongs_to_many :projects
+end
+
+class Order < ApplicationRecord
+  # BAD: belongs_to without counter_cache when counts are displayed frequently
+  belongs_to :user
+
+  # BAD: No dependent — deleting an order orphans line items
+  has_many :line_items
+
+  # BAD: Accessing association in a way that breaks inverse_of
+  has_many :items, class_name: "LineItem", foreign_key: "order_id"
+  # Rails can't infer inverse_of for :items because the name doesn't match
+end
+```
+
+## Why This Is Bad
+
+- **Missing `dependent` creates orphaned records.** `User.destroy` leaves behind orders, line items, and shipments with `user_id` pointing to a deleted record. Foreign key constraints fail or, worse, the data silently rots.
+- **HABTM can't have join attributes.** You can't store when a user joined a project, what role they have, or who invited them. You're stuck with just the two foreign keys. Every non-trivial many-to-many needs a join model eventually — start with `has_many :through`.
+- **Missing `inverse_of` causes extra queries.** Without it, `order.line_items.first.order` loads the order again from the database instead of reusing the object already in memory. In loops, this multiplies into hundreds of unnecessary queries.
+- **Missing `counter_cache` on frequently counted associations.** If your UI shows "12 orders" next to every user, that's a COUNT query per user. With 50 users on the page, that's 50 COUNT queries.
+
+## When To Apply
+
+- **Always set `dependent` on `has_many` and `has_one`.** Choose:
+  - `:destroy` — run callbacks on each child (use when children have their own dependents or callbacks)
+  - `:delete_all` — single DELETE SQL, skip callbacks (faster, use when children have no dependents)
+  - `:nullify` — set foreign key to NULL (use when the child can exist without the parent)
+  - `:restrict_with_error` — prevent deletion if children exist (use for referential integrity)
+
+- **Always use `has_many :through`** for many-to-many. Even if you don't need join attributes today, you will tomorrow.
+
+- **Set `inverse_of`** when the association name doesn't match the class name, or when using `:foreign_key`, `:class_name`, or scoped associations.
+
+- **Use `counter_cache`** when you display counts in lists (index pages, admin panels, dashboards).
+
+## When NOT To Apply
+
+- **Don't add `dependent: :destroy` on `belongs_to`.** Destroying a line item should not destroy the order it belongs to. Dependent options go on the "parent" side (`has_many`/`has_one`).
+- **Don't over-use `counter_cache`.** It adds a write on every insert/delete of the child. If counts are only viewed in admin reports (not on every page load), a query is fine.
+- **Don't create associations you don't need.** If `User` never needs to directly access `LineItem` without going through `Order`, don't add `has_many :line_items, through: :orders` unless you have a concrete use case.
+
+## Edge Cases
+
+**Polymorphic associations:**
+Use when multiple models can be the parent:
+
+```ruby
+class Comment < ApplicationRecord
+  belongs_to :commentable, polymorphic: true
+end
+
+class Order < ApplicationRecord
+  has_many :comments, as: :commentable, dependent: :destroy
+end
+
+class Product < ApplicationRecord
+  has_many :comments, as: :commentable, dependent: :destroy
+end
+```
+
+Downside: polymorphic foreign keys can't have database-level foreign key constraints. Use application-level validations.
+
+**Self-referential associations:**
+
+```ruby
+class Employee < ApplicationRecord
+  belongs_to :manager, class_name: "Employee", optional: true, inverse_of: :direct_reports
+  has_many :direct_reports, class_name: "Employee", foreign_key: :manager_id,
+           dependent: :nullify, inverse_of: :manager
+end
+```
+
+**`touch: true` for cache invalidation:**
+
+```ruby
+class LineItem < ApplicationRecord
+  belongs_to :order, touch: true  # Updates order.updated_at when line item changes
+end
+```
+
+This is essential for Russian doll caching — changing a line item invalidates the order's cache fragment automatically.
+
+**Preloading polymorphic associations:**
+
+```ruby
+# Must specify each possible type
+Comment.includes(:commentable)  # Works but may generate N queries for N types
+
+# Better: preload specific types
+comments = Comment.where(commentable_type: "Order").includes(:commentable)
+```

data/skills/rails/background_jobs.md

@@ -0,0 +1,212 @@
+# Rails: Background Jobs (Sidekiq)
+
+## Pattern
+
+Design jobs to be small, idempotent, and retriable. Pass IDs not objects. Set appropriate queues and retry strategies. Use Sidekiq's features (bulk, batches, rate limiting) for complex workflows.
+
+```ruby
+# GOOD: Small, idempotent, passes ID
+class OrderConfirmationJob < ApplicationJob
+  queue_as :default
+  retry_on ActiveRecord::RecordNotFound, wait: 5.seconds, attempts: 3
+
+  def perform(order_id)
+    order = Order.find(order_id)
+    return if order.confirmation_sent?  # Idempotent check
+
+    OrderMailer.confirmation(order).deliver_now
+    order.update!(confirmation_sent_at: Time.current)
+  end
+end
+
+# Enqueue
+OrderConfirmationJob.perform_later(order.id)
+```
+
+```ruby
+# GOOD: Batch processing with find_each
+class RecalculateTotalsJob < ApplicationJob
+  queue_as :low
+
+  def perform
+    Order.where(total: nil).find_each(batch_size: 500) do |order|
+      order.update!(total: order.line_items.sum("quantity * unit_price"))
+    end
+  end
+end
+```
+
+```ruby
+# GOOD: Job with error handling and dead letter
+class WebhookDeliveryJob < ApplicationJob
+  queue_as :webhooks
+  retry_on Faraday::TimeoutError, wait: :polynomially_longer, attempts: 5
+  discard_on Faraday::ClientError  # 4xx errors won't succeed on retry
+
+  def perform(webhook_id)
+    webhook = Webhook.find(webhook_id)
+    response = Faraday.post(webhook.url, webhook.payload.to_json, "Content-Type" => "application/json")
+
+    if response.success?
+      webhook.update!(delivered_at: Time.current, status: :delivered)
+    else
+      webhook.update!(status: :failed, last_error: "HTTP #{response.status}")
+      raise Faraday::ServerError, "Webhook failed: #{response.status}"
+    end
+  end
+end
+```
+
+Queue configuration:
+
+```yaml
+# config/sidekiq.yml
+:concurrency: 10
+:queues:
+  - [critical, 3]    # Payments, auth — 3x priority
+  - [default, 2]     # Email, notifications — 2x priority
+  - [embeddings, 1]  # Codebase indexing — normal priority
+  - [low, 1]         # Reports, cleanup — normal priority
+```
+
+## Why This Is Good
+
+- **Pass IDs, not objects.** Serializing an ActiveRecord object into Redis is fragile — the object might change between enqueue and execution. `Order.find(order_id)` always loads the current state.
+- **Idempotent jobs are safe to retry.** If the job runs twice (Redis failover, process crash, manual retry), `return if order.confirmation_sent?` prevents sending a duplicate email. The second run is a no-op.
+- **`retry_on` with specific exceptions.** Transient errors (timeout, record not found due to replication lag) get retried with backoff. Permanent errors (`discard_on` for client errors) don't waste retries.
+- **Queue separation by priority.** Payment processing gets 3x the scheduling weight of report generation. A backlog of reports doesn't delay payment confirmations.
+- **`find_each` in batch jobs.** Processing 100,000 orders loads 500 at a time, not all at once. Memory stays flat.
+
+## Anti-Pattern
+
+Passing objects, doing too much in one job, no idempotency, no retry strategy:
+
+```ruby
+# BAD: Passes entire object
+class ProcessOrderJob < ApplicationJob
+  def perform(order)
+    # order is a serialized/deserialized AR object — stale data
+    order.line_items.each do |item|
+      item.product.decrement!(:stock, item.quantity)
+    end
+    OrderMailer.confirmation(order).deliver_now
+    WarehouseApi.notify(order)
+    Analytics.track("order_created", order.attributes)
+    order.update!(processed: true)
+  end
+end
+```
+
+```ruby
+# BAD: God job that does everything
+class NightlyProcessingJob < ApplicationJob
+  def perform
+    # Recalculate all totals
+    Order.find_each { |o| o.recalculate! }
+    # Send reminder emails
+    User.inactive.each { |u| ReminderMailer.nudge(u).deliver_now }
+    # Clean up old records
+    Order.where("created_at < ?", 1.year.ago).destroy_all
+    # Generate reports
+    ReportGenerator.monthly.generate!
+    # Sync to external system
+    ExternalSync.full_sync!
+  end
+end
+```
+
+## Why This Is Bad
+
+- **Serialized objects are stale.** The order's data at enqueue time may differ from the database when the job runs (seconds, minutes, or hours later). The price could change, the status could update, line items could be modified.
+- **No idempotency.** If `ProcessOrderJob` runs twice, stock is decremented twice, two confirmation emails are sent, and the warehouse is notified twice. Retries after a crash corrupt data.
+- **God jobs can't be retried partially.** If `NightlyProcessingJob` fails during report generation, retrying it re-runs total recalculation, re-sends reminder emails, and re-deletes old records — all of which already completed.
+- **No error isolation.** One failure in the god job kills the entire run. A network error in `ExternalSync.full_sync!` means reports don't generate and reminders don't send.
+- **No queue differentiation.** Everything runs in the default queue. A burst of slow external API calls blocks email delivery.
+- **`deliver_now` in a job.** Mailer delivery should use `deliver_now` inside a job (it's already async). But if the job itself fails and retries, the email sends again — unless you add an idempotency check.
+
+## When To Apply
+
+Move work to a background job when ANY of these are true:
+
+- **External API calls** — HTTP requests to payment providers, notification services, webhooks. These are slow, unreliable, and shouldn't block a web response.
+- **Email delivery** — Always `deliver_later`, never `deliver_now` in a controller. Let the job handle retries.
+- **Data processing** — Recalculations, imports, exports, reports. These can take seconds or minutes and shouldn't tie up a web worker.
+- **User-facing response doesn't need the result.** If the user doesn't need to see the outcome immediately (like "your report is being generated"), do it in a background job.
+
+## When NOT To Apply
+
+- **Don't background everything.** A 50ms database write that the user needs to see the result of (creating a comment, updating a profile) should happen synchronously in the request. Adding a job adds latency (Redis round trip + queue wait) for no benefit.
+- **Don't use jobs for request-response patterns.** If the user is waiting for a result (like a refactored code response), use streaming — not "enqueue a job and poll for completion."
+- **Don't create jobs for operations that must be transactional with the web request.** If creating an order and deducting credits must succeed or fail together, do both in the request within a transaction.
+
+## Edge Cases
+
+**Job needs to run after a transaction commits:**
+Use `after_commit` or `ActiveRecord::Base.after_transaction` to ensure the record is visible to the job:
+
+```ruby
+# In a service object
+def call
+  ActiveRecord::Base.transaction do
+    order = Order.create!(params)
+    # Job runs AFTER the transaction commits
+    order.run_callbacks(:commit) { OrderConfirmationJob.perform_later(order.id) }
+  end
+end
+
+# Or in the model
+after_commit :send_confirmation, on: :create
+
+def send_confirmation
+  OrderConfirmationJob.perform_later(id)
+end
+```
+
+**Unique jobs (prevent duplicates):**
+Use `sidekiq-unique-jobs` or check within the job:
+
+```ruby
+class IndexCodebaseJob < ApplicationJob
+  def perform(project_id)
+    project = Project.find(project_id)
+    return if project.indexing?  # Already running
+
+    project.update!(indexing: true)
+    # ... do work ...
+    project.update!(indexing: false)
+  end
+end
+```
+
+**Long-running jobs:**
+Break into smaller jobs that each process a chunk:
+
+```ruby
+class BulkImportJob < ApplicationJob
+  def perform(file_path, offset: 0, batch_size: 1000)
+    rows = CSV.read(file_path)[offset, batch_size]
+    return if rows.blank?
+
+    rows.each { |row| import_row(row) }
+
+    # Enqueue next batch
+    BulkImportJob.perform_later(file_path, offset: offset + batch_size, batch_size: batch_size)
+  end
+end
+```
+
+**Testing jobs:**
+Test the job logic directly with `perform_now`. Test the enqueuing separately.
+
+```ruby
+it "sends confirmation" do
+  order = create(:order)
+  expect { OrderConfirmationJob.perform_now(order.id) }
+    .to change { ActionMailer::Base.deliveries.count }.by(1)
+end
+
+it "enqueues on order creation" do
+  expect { create(:order) }
+    .to have_enqueued_job(OrderConfirmationJob)
+end
+```