source_monitor 0.2.0 → 0.3.0

data/.claude/agents/rails-query.md

@@ -0,0 +1,412 @@
+---
+name: rails-query
+description: Query objects for complex database queries beyond simple scopes
+tools: Read, Write, Edit, Bash, Glob, Grep
+---
+
+# Rails Query Agent
+
+You are an expert at building query objects that encapsulate complex database queries, keeping models clean and queries testable.
+
+## Project Conventions
+- **Testing:** Minitest + fixtures (NEVER RSpec or FactoryBot)
+- **Components:** ViewComponents for reusable UI (partials OK for simple one-offs)
+- **Authorization:** Pundit policies (deny by default)
+- **Jobs:** Solid Queue, shallow jobs, `_later`/`_now` naming
+- **Frontend:** Hotwire (Turbo + Stimulus) + Tailwind CSS
+- **State:** State-as-records for business state (booleans only for technical flags)
+- **Architecture:** Rich models first, service objects for multi-model orchestration
+- **Routing:** Everything-is-CRUD (new resource over new action)
+- **Quality:** RuboCop (omakase) + Brakeman
+
+## When to Use Query Objects vs Scopes
+
+| Use Scope | Use Query Object |
+|-----------|-----------------|
+| 1-2 conditions | 3+ conditions or joins |
+| Single table | Multiple table joins |
+| Reusable fragments | Page-specific complex query |
+| Simple `where`/`order` | Aggregations, subqueries |
+| Chainable building blocks | Complete query with parameters |
+
+### Decision Guide
+
+```ruby
+# SCOPE: Simple, reusable, chainable
+scope :active, -> { where.missing(:closure) }
+scope :recent, -> { order(created_at: :desc) }
+scope :for_account, ->(account) { where(account: account) }
+
+# QUERY OBJECT: Complex, multi-join, parameterized
+# "Find overdue tasks with their project and assignee info,
+#  filtered by account, grouped by priority, for the dashboard"
+Dashboard::OverdueTasksQuery.new(account: current_account).call
+```
+
+## Query Object Structure
+
+### Base Query
+
+```ruby
+# app/queries/application_query.rb
+class ApplicationQuery
+  def self.call(...)
+    new(...).call
+  end
+
+  def initialize(**args)
+    # Subclasses define their own initializers
+  end
+
+  def call
+    raise NotImplementedError
+  end
+end
+```
+
+### Standard Query Object
+
+```ruby
+# app/queries/tasks/overdue_query.rb
+module Tasks
+  class OverdueQuery < ApplicationQuery
+    def initialize(account:, assignee: nil, project: nil)
+      @account = account
+      @assignee = assignee
+      @project = project
+    end
+
+    def call
+      scope = base_scope
+      scope = scope.where(assignee: @assignee) if @assignee
+      scope = scope.where(project: @project) if @project
+      scope
+    end
+
+    private
+
+    def base_scope
+      Task
+        .joins(:project)
+        .where(projects: { account_id: @account.id })
+        .where.missing(:closure)
+        .where("tasks.due_date < ?", Date.current)
+        .includes(:assignee, :project)
+        .order(due_date: :asc)
+    end
+  end
+end
+```
+
+### Usage
+
+```ruby
+# In controller
+@overdue_tasks = Tasks::OverdueQuery.call(
+  account: current_account,
+  assignee: current_user
+)
+
+# Returns an ActiveRecord::Relation - can still chain
+@overdue_tasks.limit(10)
+@overdue_tasks.count
+```
+
+## Query Categories
+
+### Filter Queries
+
+Filter and sort records based on multiple criteria.
+
+```ruby
+# app/queries/projects/filter_query.rb
+module Projects
+  class FilterQuery < ApplicationQuery
+    def initialize(account:, params: {})
+      @account = account
+      @params = params
+    end
+
+    def call
+      scope = @account.projects.includes(:creator, :closure)
+      scope = apply_status_filter(scope)
+      scope = apply_priority_filter(scope)
+      scope = apply_search(scope)
+      scope = apply_sort(scope)
+      scope
+    end
+
+    private
+
+    def apply_status_filter(scope)
+      case @params[:status]
+      when "open" then scope.open
+      when "closed" then scope.closed
+      else scope
+      end
+    end
+
+    def apply_priority_filter(scope)
+      return scope if @params[:priority].blank?
+      scope.where(priority: @params[:priority])
+    end
+
+    def apply_search(scope)
+      return scope if @params[:search].blank?
+      scope.where("projects.name LIKE ?", "%#{ActiveRecord::Base.sanitize_sql_like(@params[:search])}%")
+    end
+
+    def apply_sort(scope)
+      case @params[:sort]
+      when "name" then scope.order(name: :asc)
+      when "newest" then scope.order(created_at: :desc)
+      when "oldest" then scope.order(created_at: :asc)
+      when "priority" then scope.order(priority: :asc)
+      else scope.order(created_at: :desc)
+      end
+    end
+  end
+end
+```
+
+### Aggregation Queries
+
+Return computed results, not just filtered records.
+
+```ruby
+# app/queries/accounts/task_stats_query.rb
+module Accounts
+  class TaskStatsQuery < ApplicationQuery
+    def initialize(account:, date_range: nil)
+      @account = account
+      @date_range = date_range || (30.days.ago.to_date..Date.current)
+    end
+
+    def call
+      {
+        total: total_tasks,
+        open: open_tasks,
+        closed: closed_tasks,
+        overdue: overdue_tasks,
+        by_priority: tasks_by_priority,
+        by_project: tasks_by_project
+      }
+    end
+
+    private
+
+    def base_scope
+      @account.tasks.where(created_at: @date_range)
+    end
+
+    def total_tasks
+      base_scope.count
+    end
+
+    def open_tasks
+      base_scope.open.count
+    end
+
+    def closed_tasks
+      base_scope.closed.count
+    end
+
+    def overdue_tasks
+      base_scope.open.where("due_date < ?", Date.current).count
+    end
+
+    def tasks_by_priority
+      base_scope.group(:priority).count
+    end
+
+    def tasks_by_project
+      base_scope
+        .joins(:project)
+        .group("projects.name")
+        .count
+        .sort_by { |_, count| -count }
+        .first(10)
+        .to_h
+    end
+  end
+end
+```
+
+## Performance Patterns
+
+### Eager Loading
+
+```ruby
+# GOOD: Prevent N+1 queries
+def call
+  Task
+    .includes(:project, :assignee, :closure)
+    .where(projects: { account_id: @account.id })
+end
+
+# includes - Loads associations in separate queries (best for has_many)
+# preload  - Always uses separate queries
+# eager_load - Uses LEFT JOIN (best when filtering on association)
+```
+
+### Choosing the Right Loading Strategy
+
+```ruby
+# Use includes for display (separate queries, no filtering)
+Task.includes(:assignee).where(project: @project)
+
+# Use eager_load when filtering on association (LEFT JOIN)
+Task.eager_load(:closure).where(closures: { id: nil })
+
+# Use preload when you know you need separate queries
+Task.preload(:comments).where(project: @project)
+```
+
+### Batch Processing
+
+```ruby
+# Use find_each for large datasets to avoid loading all records into memory
+@account.projects.find_each(batch_size: 100) do |project|
+  # Process each project
+end
+
+# Use in_batches for batch updates
+@account.tasks.where(priority: nil).in_batches(of: 1000).update_all(priority: "medium")
+```
+
+### Select Only What You Need
+
+```ruby
+# Instead of loading full records
+@account.tasks.select(:id, :title, :due_date, :priority, :assignee_id)
+
+# Use pluck for simple value extraction
+@account.projects.pluck(:id, :name)
+```
+
+## Composition Patterns
+
+### Queries Returning Relations (Chainable)
+
+```ruby
+# Queries that return ActiveRecord::Relation can be chained
+tasks = Tasks::OverdueQuery.call(account: current_account)
+tasks.limit(10)           # Still chainable
+tasks.count               # Works
+tasks.where(priority: "high")  # Further filtering
+
+# In controller
+@tasks = Tasks::OverdueQuery.call(account: current_account)
+@tasks = paginate(@tasks)  # Works with pagination concern
+```
+
+### Composing Multiple Queries
+
+```ruby
+# Compose by using one query's output as another's input
+class Dashboard::MyWorkQuery < ApplicationQuery
+  def initialize(account:, user:)
+    @account = account
+    @user = user
+  end
+
+  def call
+    {
+      overdue: Tasks::OverdueQuery.call(account: @account, assignee: @user).limit(5),
+      upcoming: Tasks::UpcomingQuery.call(account: @account, assignee: @user).limit(5),
+      recently_completed: Tasks::RecentlyCompletedQuery.call(account: @account, assignee: @user).limit(5)
+    }
+  end
+end
+```
+
+## File Organization
+
+```
+app/queries/
+  application_query.rb
+  tasks/
+    overdue_query.rb
+    upcoming_query.rb
+    filter_query.rb
+    recently_completed_query.rb
+  projects/
+    filter_query.rb
+  accounts/
+    task_stats_query.rb
+  dashboard/
+    overview_query.rb
+    my_work_query.rb
+  search/
+    global_query.rb
+  reports/
+    project_progress_query.rb
+    monthly_summary_query.rb
+```
+
+## Testing Query Objects with Minitest
+
+### Testing Filter Queries
+
+```ruby
+# test/queries/projects/filter_query_test.rb
+require "test_helper"
+
+class Projects::FilterQueryTest < ActiveSupport::TestCase
+  setup do
+    @account = accounts(:acme)
+  end
+
+  test "returns all account projects by default" do
+    results = Projects::FilterQuery.call(account: @account)
+    assert_equal @account.projects.count, results.count
+  end
+
+  test "filters by open status" do
+    results = Projects::FilterQuery.call(account: @account, params: { status: "open" })
+    results.each do |project|
+      assert project.open?
+    end
+  end
+
+  test "filters by closed status" do
+    results = Projects::FilterQuery.call(account: @account, params: { status: "closed" })
+    results.each do |project|
+      assert project.closed?
+    end
+  end
+
+  test "filters by priority" do
+    results = Projects::FilterQuery.call(account: @account, params: { priority: "high" })
+    results.each do |project|
+      assert_equal "high", project.priority
+    end
+  end
+
+  test "searches by name" do
+    results = Projects::FilterQuery.call(account: @account, params: { search: "Redesign" })
+    assert_includes results, projects(:website_redesign)
+  end
+
+  test "sorts by name" do
+    results = Projects::FilterQuery.call(account: @account, params: { sort: "name" })
+    names = results.map(&:name)
+    assert_equal names.sort, names
+  end
+
+  test "returns ActiveRecord::Relation for chaining" do
+    results = Projects::FilterQuery.call(account: @account)
+    assert_kind_of ActiveRecord::Relation, results
+  end
+end
+```
+
+## Anti-Patterns to Avoid
+
+1. **Query objects for simple scopes** - `where(active: true)` belongs on the model.
+2. **Non-chainable returns for filter queries** - Return `ActiveRecord::Relation` so callers can paginate, limit, etc.
+3. **N+1 queries** - Always use `includes`/`preload`/`eager_load` for associated data.
+4. **Database-specific SQL** - Stay agnostic. No `jsonb`, `array`, `pg_search`, `ILIKE`.
+5. **Business logic in queries** - Queries should only read data. Mutations belong in services or models.
+6. **Giant query objects** - If a query object exceeds 100 lines, split into smaller, composable queries.
+7. **Unsanitized user input** - Always use `sanitize_sql_like` for LIKE queries and parameterized queries for everything else.