rubyn-code 0.1.0

data/skills/rails/query_objects.md

@@ -0,0 +1,177 @@
+# Rails: Query Objects
+
+## Pattern
+
+Extract complex database queries into query objects when a scope chain becomes long, requires conditional logic, or involves joins and subqueries that obscure intent. Query objects live in `app/queries/` and return ActiveRecord relations so they remain chainable.
+
+```ruby
+# app/queries/orders/search_query.rb
+module Orders
+  class SearchQuery
+    def self.call(params)
+      new(params).call
+    end
+
+    def initialize(params)
+      @params = params
+    end
+
+    def call
+      scope = Order.includes(:user, :line_items)
+      scope = filter_by_status(scope)
+      scope = filter_by_date_range(scope)
+      scope = filter_by_total(scope)
+      scope = search_by_keyword(scope)
+      scope = apply_sorting(scope)
+      scope
+    end
+
+    private
+
+    def filter_by_status(scope)
+      return scope unless @params[:status].present?
+
+      scope.where(status: @params[:status])
+    end
+
+    def filter_by_date_range(scope)
+      scope = scope.where(created_at: @params[:from]..) if @params[:from].present?
+      scope = scope.where(created_at: ..@params[:to]) if @params[:to].present?
+      scope
+    end
+
+    def filter_by_total(scope)
+      scope = scope.where("total >= ?", @params[:min_total]) if @params[:min_total].present?
+      scope = scope.where("total <= ?", @params[:max_total]) if @params[:max_total].present?
+      scope
+    end
+
+    def search_by_keyword(scope)
+      return scope unless @params[:q].present?
+
+      scope.where("orders.reference ILIKE :q OR users.email ILIKE :q", q: "%#{@params[:q]}%")
+           .references(:user)
+    end
+
+    def apply_sorting(scope)
+      case @params[:sort]
+      when "newest" then scope.order(created_at: :desc)
+      when "oldest" then scope.order(created_at: :asc)
+      when "highest" then scope.order(total: :desc)
+      else scope.order(created_at: :desc)
+      end
+    end
+  end
+end
+```
+
+The controller stays minimal:
+
+```ruby
+class OrdersController < ApplicationController
+  def index
+    @orders = Orders::SearchQuery.call(search_params).page(params[:page])
+  end
+
+  private
+
+  def search_params
+    params.permit(:status, :from, :to, :min_total, :max_total, :q, :sort)
+  end
+end
+```
+
+## Why This Is Good
+
+- **Returns a relation.** The query object returns an ActiveRecord::Relation, not an array. You can chain `.page()`, `.limit()`, `.count()` on the result. It composes with the rest of Rails.
+- **Each filter is isolated.** Adding a new filter means adding one private method. Removing a filter means removing one method. No risk of breaking other filters.
+- **Testable without HTTP.** Pass in a params hash, assert the SQL or the returned records. Fast, focused tests.
+- **Reusable.** The same query object works in the controller, in an API endpoint, in a CSV export job, and in an admin panel.
+- **Readable intent.** `Orders::SearchQuery.call(params)` communicates what's happening. A 30-line scope chain in a controller does not.
+
+## Anti-Pattern
+
+Building complex queries inline in the controller with conditional scope chaining:
+
+```ruby
+class OrdersController < ApplicationController
+  def index
+    @orders = Order.includes(:user, :line_items)
+
+    if params[:status].present?
+      @orders = @orders.where(status: params[:status])
+    end
+
+    if params[:from].present?
+      @orders = @orders.where("created_at >= ?", params[:from])
+    end
+
+    if params[:to].present?
+      @orders = @orders.where("created_at <= ?", params[:to])
+    end
+
+    if params[:min_total].present?
+      @orders = @orders.where("total >= ?", params[:min_total])
+    end
+
+    if params[:q].present?
+      @orders = @orders.joins(:user)
+                       .where("orders.reference ILIKE :q OR users.email ILIKE :q", q: "%#{params[:q]}%")
+    end
+
+    @orders = case params[:sort]
+              when "newest" then @orders.order(created_at: :desc)
+              when "oldest" then @orders.order(created_at: :asc)
+              when "highest" then @orders.order(total: :desc)
+              else @orders.order(created_at: :desc)
+              end
+
+    @orders = @orders.page(params[:page])
+  end
+end
+```
+
+## Why This Is Bad
+
+- **30+ lines of query logic in a controller.** The controller's job is HTTP handling, not query construction.
+- **Impossible to reuse.** When the admin panel needs the same search, you copy-paste the entire block. When the API needs it, you copy it again. When the logic changes, you update it in three places.
+- **Difficult to test.** Testing this requires making HTTP requests and asserting HTML or JSON output. You can't test the query logic in isolation.
+- **Grows unbounded.** Every new filter adds another `if` block. Every new sort option adds a `when` clause. The controller action becomes the longest method in the codebase.
+
+## When To Apply
+
+Use a query object when ANY of these are true:
+
+- A query has **3 or more conditional filters** (status, date range, keyword, price range)
+- The query involves **joins, subqueries, or raw SQL fragments** that obscure what's being queried
+- The **same query logic is needed in multiple places** (web controller, API, admin, background job, export)
+- The query is used for **reporting or analytics** (monthly revenue, user activity, conversion funnels)
+- A model's scope chain is getting **longer than 3 chained scopes** for a single use case
+
+## When NOT To Apply
+
+- **Simple, reusable filters belong as scopes on the model.** `Order.recent`, `Order.pending`, `Order.for_user(user)` are fine as scopes. They're short, reusable, and chainable.
+- **Single-condition queries don't need a class.** `Order.where(status: :pending)` in a controller is perfectly fine. Don't extract a query object for one `where` clause.
+- The query is **only used in one place** and is **under 5 lines.** A small inline query in a controller is more readable than navigating to a separate file.
+
+## Edge Cases
+
+**Some filters should always be applied (like tenant scoping):**
+Apply those in the constructor or at the top of `call`, not as conditional filters. Tenant scoping is not optional.
+
+```ruby
+def call
+  scope = Order.where(company: @company) # Always applied
+  scope = filter_by_status(scope)        # Conditionally applied
+  scope
+end
+```
+
+**The query needs to return raw data (not ActiveRecord objects):**
+Use `.pluck`, `.select`, or `.to_sql` at the call site, not inside the query object. The query object returns a relation; the caller decides how to materialize it.
+
+**You need both a count and the results:**
+Return the relation. The caller chains `.count` or `.to_a` as needed. Don't build two methods that run nearly identical queries.
+
+**The query is extremely complex (CTEs, window functions):**
+Consider `Arel` for type-safe query construction, or use `.from(Arel.sql(...))` for raw SQL. Wrap it in the query object so the complexity is contained in one place. Add comments explaining the SQL.

data/skills/rails/routing.md

@@ -0,0 +1,194 @@
+# Rails: Routing
+
+## Pattern
+
+Routes define your application's public API surface. Keep them RESTful, use resources for CRUD, create new controllers instead of custom actions, and use namespaces to organize related endpoints.
+
+### RESTful Resources
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  # GOOD: Standard RESTful resources
+  resources :orders, only: [:index, :show, :create, :update, :destroy]
+  resources :products, only: [:index, :show]
+
+  # GOOD: Nested resources for parent-child relationships
+  resources :orders do
+    resources :line_items, only: [:create, :destroy]
+    resource :shipment, only: [:show, :create]  # singular — one shipment per order
+  end
+  # Generates: /orders/:order_id/line_items
+  #            /orders/:order_id/shipment
+
+  # GOOD: Shallow nesting — child resources get their own top-level routes for show/edit/destroy
+  resources :projects, shallow: true do
+    resources :memberships, only: [:index, :create, :show, :destroy]
+  end
+  # Generates: /projects/:project_id/memberships     (index, create)
+  #            /memberships/:id                        (show, destroy)
+end
+```
+
+### New Controllers Over Custom Actions
+
+```ruby
+# BAD: Custom actions on a resource controller
+resources :orders do
+  member do
+    post :cancel        # POST /orders/:id/cancel
+    post :ship          # POST /orders/:id/ship
+    post :refund        # POST /orders/:id/refund
+    get :invoice        # GET /orders/:id/invoice
+    get :tracking       # GET /orders/:id/tracking
+  end
+end
+
+# GOOD: Each verb gets its own resource controller
+resources :orders, only: [:index, :show, :create, :update] do
+  resource :cancellation, only: [:create], controller: "order_cancellations"
+  resource :shipment, only: [:show, :create], controller: "order_shipments"
+  resource :refund, only: [:create], controller: "order_refunds"
+  resource :invoice, only: [:show], controller: "order_invoices"
+  resource :tracking, only: [:show], controller: "order_trackings"
+end
+```
+
+Each new controller has a single RESTful action. `OrderCancellationsController#create` is clearer than `OrdersController#cancel`, and each controller stays skinny.
+
+### Namespaces, Scopes, and Modules
+
+```ruby
+Rails.application.routes.draw do
+  # namespace: adds URL prefix AND module prefix
+  namespace :admin do
+    resources :users          # Admin::UsersController, /admin/users
+    resources :orders         # Admin::OrdersController, /admin/orders
+    root to: "dashboard#show"
+  end
+
+  # namespace for API versioning
+  namespace :api do
+    namespace :v1 do
+      resources :orders       # Api::V1::OrdersController, /api/v1/orders
+      resources :projects do
+        resources :embeddings, only: [:index, :create]
+      end
+      namespace :ai do
+        post :refactor        # Api::V1::Ai::RefactorController (if using Grape, mount instead)
+        post :review
+        post :spec
+      end
+    end
+  end
+
+  # scope: adds URL prefix but NOT module prefix
+  scope "/dashboard" do
+    resources :analytics, only: [:index]  # AnalyticsController, /dashboard/analytics
+  end
+
+  # module: adds module prefix but NOT URL prefix
+  scope module: :public do
+    resources :products, only: [:index, :show]  # Public::ProductsController, /products
+  end
+end
+```
+
+### Constraints and Advanced Routing
+
+```ruby
+Rails.application.routes.draw do
+  # Subdomain constraints
+  constraints subdomain: "api" do
+    namespace :api, path: "" do  # api.rubyn.ai/v1/orders instead of api.rubyn.ai/api/v1/orders
+      namespace :v1 do
+        resources :orders
+      end
+    end
+  end
+
+  # Format constraints
+  resources :reports, only: [:show], defaults: { format: :json }
+
+  # Custom constraints
+  constraints ->(req) { req.env["HTTP_AUTHORIZATION"].present? } do
+    resources :admin_tools
+  end
+
+  # Catch-all for SPA (must be LAST)
+  get "*path", to: "application#frontend", constraints: ->(req) { !req.xhr? && req.format.html? }
+end
+```
+
+### Route Helpers and Path Generation
+
+```ruby
+# Use named routes — never hardcode paths
+redirect_to order_path(@order)              # /orders/123
+redirect_to order_line_items_path(@order)    # /orders/123/line_items
+redirect_to [:admin, @user]                  # /admin/users/456
+redirect_to new_order_path                   # /orders/new
+
+# Polymorphic routing
+redirect_to [@order, @line_item]             # /orders/123/line_items/789
+
+# URL helpers in non-controller contexts
+Rails.application.routes.url_helpers.order_url(order, host: "rubyn.ai")
+```
+
+## Why This Is Good
+
+- **RESTful resources are predictable.** Any Rails developer opening your routes file knows that `resources :orders` means 7 standard actions. Custom actions require reading each one.
+- **New controllers keep actions skinny.** `OrderCancellationsController#create` has one job. `OrdersController#cancel` is a non-RESTful action hiding in a RESTful controller.
+- **Namespaces organize by concern.** Admin routes, API routes, and public routes are clearly separated. Different authentication, different base controllers, different middleware.
+- **Shallow nesting avoids deep URLs.** `/projects/1/memberships/2/permissions/3` is painful. Shallow nesting gives children their own top-level routes after creation.
+- **`only:` keeps it explicit.** `resources :products, only: [:index, :show]` tells you exactly which endpoints exist. No guessing, no unused routes.
+
+## Anti-Pattern
+
+```ruby
+# BAD: Everything on one controller, no nesting discipline
+resources :orders do
+  collection do
+    get :search
+    get :export
+    get :report
+  end
+  member do
+    post :cancel
+    post :ship
+    post :approve
+    post :reject
+    post :archive
+    post :duplicate
+    get :pdf
+    get :receipt
+  end
+end
+# OrdersController now has 15+ actions
+```
+
+## When To Apply
+
+- **Every Rails app.** RESTful routing is the Rails way. It's not optional.
+- **When an action doesn't map to CRUD** — it's a new controller, not a custom action. "Cancel" is creating a cancellation. "Ship" is creating a shipment.
+- **API versioning from day one.** `/api/v1/` costs nothing now and saves everything later.
+- **`only:` on every `resources` call.** Don't generate routes you don't use.
+
+## When NOT To Apply
+
+- **Sinatra apps.** Sinatra routes are explicit — no `resources` macro. Just define the routes you need.
+- **Single-action controllers don't need resources.** A health check is `get "/health", to: "health#show"`, not `resources :health`.
+- **Don't over-nest.** Never go deeper than 2 levels. `/orders/:id/line_items` is fine. `/companies/:id/orders/:id/line_items/:id/adjustments` is too deep — use shallow nesting or flatten.
+
+## Edge Cases
+
+**Mounting engines and Rack apps:**
+
+```ruby
+mount Rubyn::Engine => "/rubyn" if Rails.env.development?
+mount Sidekiq::Web => "/sidekiq" if Rails.env.development?
+mount ActionCable.server => "/cable"
+```
+
+**Route precedence:** Routes are matched top to bottom. Put specific routes before generic ones, and catch-all routes last.

data/skills/rails/scopes.md

@@ -0,0 +1,187 @@
+# Rails: ActiveRecord Scopes
+
+## Pattern
+
+Scopes are named, reusable query fragments that return `ActiveRecord::Relation`. They chain, compose, and serve as the vocabulary for querying your domain. Design scopes like building blocks — small, focused, and combinable.
+
+```ruby
+class Order < ApplicationRecord
+  # Status scopes — named after the state
+  scope :pending, -> { where(status: :pending) }
+  scope :confirmed, -> { where(status: :confirmed) }
+  scope :shipped, -> { where(status: :shipped) }
+  scope :completed, -> { where(status: %i[shipped delivered]) }
+  scope :active, -> { where.not(status: :cancelled) }
+
+  # Time scopes — named after the time frame
+  scope :recent, -> { where(created_at: 30.days.ago..) }
+  scope :today, -> { where(created_at: Date.current.all_day) }
+  scope :this_month, -> { where(created_at: Date.current.all_month) }
+  scope :before, ->(date) { where(created_at: ...date) }
+  scope :after, ->(date) { where(created_at: date..) }
+  scope :between, ->(start_date, end_date) { where(created_at: start_date..end_date) }
+
+  # Relationship scopes — named after the association
+  scope :for_user, ->(user) { where(user: user) }
+  scope :for_product, ->(product) { joins(:line_items).where(line_items: { product: product }) }
+
+  # Value scopes — named after what they filter
+  scope :high_value, -> { where("total >= ?", 200_00) }
+  scope :above, ->(amount) { where("total >= ?", amount) }
+  scope :free_shipping, -> { where("total >= ?", 50_00) }
+
+  # Ordering scopes
+  scope :by_newest, -> { order(created_at: :desc) }
+  scope :by_total, -> { order(total: :desc) }
+  scope :by_status, -> { order(:status) }
+
+  # Inclusion scopes — preload associations for performance
+  scope :with_details, -> { includes(:user, :line_items, line_items: :product) }
+  scope :with_user, -> { includes(:user) }
+end
+
+# Compose scopes naturally — reads like a sentence
+Order.for_user(current_user).pending.recent.by_newest
+Order.confirmed.high_value.with_details.by_total
+Order.active.this_month.for_product(widget)
+```
+
+### Scopes with Conditional Logic
+
+```ruby
+class Product < ApplicationRecord
+  # Parameterized scope — nil-safe
+  scope :in_category, ->(category) { where(category: category) if category.present? }
+  scope :cheaper_than, ->(price) { where("price <= ?", price) if price.present? }
+  scope :search, ->(query) {
+    where("name ILIKE :q OR sku ILIKE :q", q: "%#{sanitize_sql_like(query)}%") if query.present?
+  }
+
+  # Scope that wraps a subquery
+  scope :with_recent_orders, -> {
+    where(id: LineItem.joins(:order).where(orders: { created_at: 30.days.ago.. }).select(:product_id))
+  }
+
+  # Scope using merge to combine conditions from another model's scope
+  scope :ordered_recently, -> {
+    joins(:line_items).merge(LineItem.joins(:order).merge(Order.recent)).distinct
+  }
+end
+
+# Nil-safe scopes chain gracefully — nil params are ignored
+Product.in_category(params[:category]).cheaper_than(params[:max_price]).search(params[:q])
+# If params[:category] is nil, that scope returns `all` — the chain continues
+```
+
+### Scopes vs Class Methods
+
+```ruby
+class Order < ApplicationRecord
+  # SCOPE: Always returns a relation, even when the condition is nil
+  scope :by_status, ->(status) { where(status: status) if status.present? }
+  # When status is nil: returns `all` (chainable)
+
+  # CLASS METHOD: Can return nil, breaking the chain
+  def self.by_status(status)
+    return if status.blank?  # Returns nil — .by_newest chained after this explodes
+    where(status: status)
+  end
+
+  # FIX: Class method that always returns a relation
+  def self.by_status(status)
+    return all if status.blank?  # Returns scope, not nil
+    where(status: status)
+  end
+end
+```
+
+**Rule:** Use scopes for simple query fragments. Use class methods when you need complex logic (multiple lines, early returns, error handling) — but always return a relation or `all`/`none`, never `nil`.
+
+## Why This Is Good
+
+- **Composable.** Each scope is a LEGO brick. Snap them together in any combination. `Order.pending.recent.high_value` generates one SQL query with three WHERE clauses.
+- **Readable.** `Order.for_user(user).completed.this_month` reads like English. The equivalent raw SQL is harder to scan and impossible to reuse.
+- **Chainable.** Scopes return `ActiveRecord::Relation`, so you can always chain more scopes, `.count`, `.page()`, `.pluck()`, `.exists?` after them.
+- **Nil-safe.** A scope with `if condition.present?` returns `all` when the condition is false — the chain continues without breaking. This makes conditional filtering trivial.
+- **Single source of truth.** "What does 'recent' mean?" is answered in one place — the scope definition. Not scattered across 8 controllers with slightly different `where` clauses.
+- **Preloadable.** Scopes work with `includes`, `preload`, and `eager_load`. Query objects that return arrays don't.
+
+## Anti-Pattern
+
+```ruby
+class Order < ApplicationRecord
+  # BAD: default_scope — poisons every query
+  default_scope { where(deleted: false) }
+  # Every Order.find, Order.count, Order.joins silently adds WHERE deleted = false
+  # Forgetting to unscope causes subtle bugs
+
+  # BAD: Scope that returns an array, not a relation
+  scope :totals, -> { pluck(:total) }
+  # Can't chain: Order.totals.pending → NoMethodError
+
+  # BAD: Scope with side effects
+  scope :expire_old, -> {
+    where(created_at: ...30.days.ago).update_all(status: :expired)
+  }
+  # Scopes should query, not mutate. This belongs in a service object.
+
+  # BAD: Overly complex scope that should be a query object
+  scope :dashboard_summary, -> {
+    select("status, COUNT(*) as count, SUM(total) as revenue")
+      .where(created_at: 30.days.ago..)
+      .where.not(status: :cancelled)
+      .group(:status)
+      .having("COUNT(*) > ?", 0)
+      .order("revenue DESC")
+  }
+end
+```
+
+## When To Apply
+
+- **Every reusable query condition** that's used in 2+ places. If two controllers filter by `pending`, that's a scope.
+- **Parameterized filters.** `scope :for_user, ->(user)` is cleaner than `where(user: user)` repeated everywhere.
+- **Ordering.** `scope :by_newest` is more expressive than `.order(created_at: :desc)` in every controller.
+- **Eager loading bundles.** `scope :with_details` bundles the `includes` for a specific use case.
+
+## When NOT To Apply
+
+- **Complex queries with 4+ joins, subqueries, or CTEs.** These belong in a Query Object, not a scope.
+- **Queries with side effects.** Scopes should never `update_all`, send emails, or modify state. They read data.
+- **One-off queries.** If a query is only used in one place and is simple (one `where` clause), inline it. Don't create a scope for everything.
+- **Never use `default_scope`.** It silently affects every query on the model. Use explicit scopes and apply them where needed.
+
+## Edge Cases
+
+**Merging scopes across models:**
+
+```ruby
+# merge applies another model's scope in a join
+Order.joins(:user).merge(User.active)
+# WHERE users.active = true
+
+# Useful for combining scopes from both sides of a join
+Order.confirmed.joins(:user).merge(User.active).merge(User.pro_plan)
+```
+
+**Scopes on associations:**
+
+```ruby
+class User < ApplicationRecord
+  has_many :orders
+  has_many :pending_orders, -> { pending }, class_name: "Order"
+  has_many :recent_orders, -> { recent.by_newest }, class_name: "Order"
+end
+
+user.pending_orders  # Preloadable scoped association
+User.includes(:pending_orders)  # Works with includes
+```
+
+**`none` scope for empty results:**
+
+```ruby
+def orders_for(user)
+  return Order.none unless user&.active?  # Returns empty relation, still chainable
+  user.orders.active
+end
+```