anima-core 0.2.1 → 1.0.0

data/skills/activerecord/SKILL.md

@@ -0,0 +1,255 @@
+---
+name: activerecord
+description: "ActiveRecord patterns — associations, validations, queries, migrations, eager loading. Activate when working with models, migrations, database schema, N+1 queries, scopes, includes/preload/eager_load, callbacks, or editing files in app/models/ or db/migrate/."
+---
+
+# ActiveRecord
+
+This skill provides comprehensive guidance for working with ActiveRecord in Rails applications. Use for writing migrations, defining associations, optimizing queries, preventing N+1 issues, implementing validations, and following database best practices.
+
+## Quick Reference
+
+### CRUD Operations
+
+```ruby
+# Create
+user = User.create(name: "Alice", email: "alice@example.com")
+user = User.create!(...)  # Raises on failure
+
+# Read
+User.find(1)              # Raises RecordNotFound
+User.find_by(email: "x")  # Returns nil if not found
+User.where(active: true)  # Returns Relation
+
+# Update
+user.update(name: "Bob")
+user.update!(...)         # Raises on failure
+
+# Delete (callbacks run)
+user.destroy
+
+# Delete (no callbacks)
+user.delete
+```
+
+### Key Concepts
+
+| Concept | Purpose |
+|---------|---------|
+| `belongs_to` | Child side of association (has foreign key) |
+| `has_many` / `has_one` | Parent side of association |
+| `has_many :through` | Many-to-many via join model |
+| `includes` / `preload` | Eager loading (prevent N+1) |
+| `scope` | Named query builder |
+| `validates` | Model-level data validation |
+| `before_save` / `after_commit` | Lifecycle callbacks |
+
+## Eager Loading Decision Tree
+
+```
+Need to access associated data?
+├── NO → Use `joins` (filtering only)
+└── YES → Need to filter/sort by association?
+          ├── NO → Use `preload` (separate queries)
+          └── YES → Large dataset with many associations?
+                    ├── YES → Use `includes` with `references`
+                    └── NO → Use `eager_load` (single JOIN)
+```
+
+### Quick Comparison
+
+| Method | Strategy | Best For |
+|--------|----------|----------|
+| `includes` | Auto-choose | Default choice |
+| `preload` | Separate queries | Large datasets, no filtering |
+| `eager_load` | LEFT OUTER JOIN | Filtering by association |
+| `joins` | INNER JOIN | Filtering only, not accessing data |
+
+```ruby
+# N+1 problem
+Post.all.each { |p| p.author.name }  # 1 + N queries
+
+# Solution
+Post.includes(:author).each { |p| p.author.name }  # 2 queries
+```
+
+## Validation vs Constraint Decision
+
+```
+Does the rule ALWAYS apply, regardless of business logic?
+├── Yes → Database constraint
+│   └── Examples: NOT NULL, foreign keys, unique emails
+└── No → Model validation
+    └── Examples: Format rules that change, conditional requirements
+
+Need helpful user-facing error messages?
+├── Yes → Model validation (possibly WITH constraint)
+└── No → Constraint alone is fine
+```
+
+**Best Practice**: Use both for critical fields:
+
+```ruby
+# Migration (data integrity)
+add_index :users, :email, unique: true
+
+# Model (user feedback)
+validates :email, presence: true, uniqueness: true
+```
+
+## Associations Quick Reference
+
+### Basic Types
+
+```ruby
+class Author < ApplicationRecord
+  has_many :books, dependent: :destroy
+  has_one :profile
+end
+
+class Book < ApplicationRecord
+  belongs_to :author                    # Required by default
+  belongs_to :publisher, optional: true # Allow NULL
+end
+```
+
+### Through Associations
+
+```ruby
+class Physician < ApplicationRecord
+  has_many :appointments
+  has_many :patients, through: :appointments
+end
+
+class Appointment < ApplicationRecord
+  belongs_to :physician
+  belongs_to :patient
+  # Join model can have attributes
+  validates :scheduled_at, presence: true
+end
+```
+
+### Critical Options
+
+| Option | Purpose |
+|--------|---------|
+| `inverse_of` | Required with custom foreign_key |
+| `dependent: :destroy` | Cascade delete with callbacks |
+| `counter_cache: true` | Cache association count |
+| `touch: true` | Update parent's updated_at |
+
+## Migrations Quick Reference
+
+### Safe Patterns
+
+```ruby
+# Always reversible
+add_column :users, :name, :string
+add_index :users, :email, unique: true
+add_reference :orders, :user, foreign_key: true
+
+# Concurrent index (no table lock)
+disable_ddl_transaction!
+add_index :users, :email, algorithm: :concurrently
+```
+
+### Must Include Type for Reversibility
+
+```ruby
+remove_column :users, :legacy_field, :string  # Include type!
+change_column_default :users, :status, from: nil, to: "active"
+```
+
+## Callbacks Quick Reference
+
+### Order of Execution
+
+```
+before_validation → after_validation →
+before_save → around_save → before_create →
+around_create → [INSERT] → after_create →
+after_save → [COMMIT] → after_commit
+```
+
+### Critical Rule: Use after_commit for External Systems
+
+```ruby
+# WRONG - Race condition!
+after_save :enqueue_processing
+
+# CORRECT - Runs after COMMIT
+after_commit :enqueue_processing, on: :create
+```
+
+## Batch Processing
+
+```ruby
+# BAD - loads all records
+User.all.each { |u| process(u) }
+
+# GOOD - processes in batches
+User.find_each { |u| process(u) }
+
+# Bulk operations
+User.where(old: true).in_batches.update_all(archived: true)
+```
+
+## Best Practices
+
+### Do
+
+- Add database index for columns used in WHERE, ORDER BY, JOIN
+- Use `includes` to prevent N+1 queries
+- Pair uniqueness validations with unique database indexes
+- Use `find_each` for processing large datasets
+- Use `pluck(:column)` instead of `all.map(&:column)`
+- Define `inverse_of` when using custom `foreign_key`
+- Use `after_commit` for background jobs and external APIs
+- Prefer `has_many :through` over `has_and_belongs_to_many`
+
+### Don't
+
+- Don't use `default_scope` (causes subtle issues)
+- Don't use `delete` when you need callbacks
+- Don't skip database constraints for critical uniqueness
+- Don't use `update_column` to bypass validations casually
+- Don't reference models in migrations (use raw SQL)
+- Don't edit already-deployed migrations
+- Don't use `after_save` for external system interactions
+
+## Anti-Patterns Quick List
+
+| Anti-Pattern | Solution |
+|--------------|----------|
+| N+1 queries | Use `includes`, `preload`, or `eager_load` |
+| `User.all.map(&:email)` | Use `User.pluck(:email)` |
+| Uniqueness without index | Add unique database index |
+| `validates :active, presence: true` | Use `inclusion: { in: [true, false] }` for booleans |
+| `after_save` for jobs | Use `after_commit` |
+| Callback hell | Extract to service objects |
+| `default_scope` | Use explicit scopes |
+| `has_and_belongs_to_many` | Use `has_many :through` |
+
+## Additional Resources
+
+### Reference Files
+
+For detailed patterns and complete API references, consult:
+
+- **`references/basics.md`** - Conventions, CRUD, dirty tracking, STI, type casting
+- **`references/migrations.md`** - Schema changes, indexes, constraints, safe patterns
+- **`references/validations.md`** - Built-in validators, custom validators, contexts
+- **`references/callbacks.md`** - Lifecycle hooks, transaction callbacks, alternatives
+- **`references/associations.md`** - All association types, inverse_of, dependent options
+- **`references/querying.md`** - Finders, eager loading, scopes, batch processing
+
+### Example Files
+
+Ready-to-use code patterns in `examples/`:
+
+- **`examples/basics/`** - CRUD, dirty tracking, type casting, inheritance
+- **`examples/migrations/`** - Schema changes, indexes, safe patterns, reversibility
+- **`examples/validations/`** - Built-in, conditional, custom, contexts, constraints
+- **`examples/callbacks/`** - Lifecycle, transaction callbacks, conditional, alternatives
+- **`examples/associations/`** - Basic, through, polymorphic, self-referential, extensions
+- **`examples/querying/`** - Finders, eager loading, scopes, batch processing, optimization

data/skills/activerecord/examples/associations/association_extensions.rb

@@ -0,0 +1,298 @@
+# Association Extension Examples
+# Adding custom methods to association proxies
+
+# ============================================
+# Inline Extension
+# ============================================
+
+class Project < ApplicationRecord
+  has_many :tasks do
+    # Filter methods
+    def active
+      where(status: "active")
+    end
+
+    def completed
+      where(status: "completed")
+    end
+
+    def overdue
+      active.where("due_date < ?", Date.current)
+    end
+
+    # Calculation methods
+    def total_hours
+      sum(:estimated_hours)
+    end
+
+    def completion_percentage
+      return 0 if empty?
+
+      (completed.count.to_f / count * 100).round(2)
+    end
+
+    # Creation helpers
+    def create_milestone!(name, due_date)
+      create!(name:, due_date:, priority: :high, milestone: true)
+    end
+
+    # Access owner via proxy_association
+    def recent_for_owner
+      where("created_at > ?", proxy_association.owner.created_at)
+    end
+  end
+end
+
+# Usage
+project = Project.find(1)
+project.tasks.active
+project.tasks.overdue.count
+project.tasks.total_hours
+project.tasks.completion_percentage
+project.tasks.create_milestone!("Launch", 1.month.from_now)
+
+# ============================================
+# Shared Extension Module
+# ============================================
+
+module StatusFilter
+  def active
+    where(status: "active")
+  end
+
+  def completed
+    where(status: "completed")
+  end
+
+  def pending
+    where(status: "pending")
+  end
+
+  def by_status(status)
+    where(status:)
+  end
+end
+
+module Orderable
+  def by_priority
+    order(priority: :desc)
+  end
+
+  def by_recent
+    order(created_at: :desc)
+  end
+
+  def by_due_date
+    order(due_date: :asc)
+  end
+end
+
+class Project < ApplicationRecord
+  has_many :tasks, -> { extending StatusFilter, Orderable }
+  has_many :issues, -> { extending StatusFilter, Orderable }
+end
+
+class Team < ApplicationRecord
+  has_many :members, -> { extending StatusFilter }
+end
+
+# Usage
+project.tasks.active.by_priority
+project.issues.pending.by_due_date
+team.members.active
+
+# ============================================
+# Extension with Scopes
+# ============================================
+
+class Author < ApplicationRecord
+  has_many :books, -> { order(published_at: :desc) } do
+    def fiction
+      where(genre: "fiction")
+    end
+
+    def nonfiction
+      where(genre: "nonfiction")
+    end
+
+    def bestsellers
+      where(bestseller: true)
+    end
+
+    def published_in(year)
+      where("EXTRACT(YEAR FROM published_at) = ?", year)
+    end
+
+    def search(query)
+      where("title ILIKE ?", "%#{query}%")
+    end
+  end
+end
+
+# Chain extensions with other query methods
+author.books.fiction.bestsellers
+author.books.nonfiction.published_in(2024)
+author.books.search("ruby").limit(10)
+
+# ============================================
+# Extension Accessing Owner
+# ============================================
+
+class User < ApplicationRecord
+  has_many :notifications do
+    def unread
+      where(read_at: nil)
+    end
+
+    def mark_all_read!
+      update_all(read_at: Time.current)
+    end
+
+    def for_past_week
+      where("created_at > ?", 1.week.ago)
+    end
+
+    # Access the user via proxy_association.owner
+    def summary
+      owner = proxy_association.owner
+      {
+        total: count,
+        unread: unread.count,
+        user_name: owner.name
+      }
+    end
+  end
+end
+
+# Usage
+user.notifications.unread.count
+user.notifications.mark_all_read!
+user.notifications.summary
+# => { total: 42, unread: 5, user_name: "Alice" }
+
+# ============================================
+# Extension for Through Associations
+# ============================================
+
+class Doctor < ApplicationRecord
+  has_many :appointments
+  has_many :patients, through: :appointments do
+    def with_recent_visit
+      where("appointments.scheduled_at > ?", 6.months.ago)
+    end
+
+    def needing_followup
+      joins(:appointments)
+        .where(appointments: { followup_needed: true })
+        .distinct
+    end
+  end
+end
+
+# Usage
+doctor.patients.with_recent_visit
+doctor.patients.needing_followup.count
+
+# ============================================
+# Real-World Example: Versioned Documents
+# ============================================
+
+class Document < ApplicationRecord
+  has_many :versions, -> { order(version_number: :desc) } do
+    def latest
+      first
+    end
+
+    def published
+      where(published: true)
+    end
+
+    def latest_published
+      published.first
+    end
+
+    def diff(v1, v2)
+      # Return diff between two versions
+      version1 = find_by(version_number: v1)
+      version2 = find_by(version_number: v2)
+      # Implementation...
+    end
+
+    def create_new_version!(content, author:)
+      last_number = maximum(:version_number) || 0
+      create!(
+        content:,
+        author:,
+        version_number: last_number + 1,
+        created_at: Time.current
+      )
+    end
+  end
+end
+
+# Usage
+doc.versions.latest
+doc.versions.published.count
+doc.versions.create_new_version!("Updated content", author: current_user)
+
+# ============================================
+# Extension vs Scope Decision
+# ============================================
+
+# Use SCOPE when:
+# - Query is useful globally (not just via association)
+# - Simple filtering/ordering
+# - Used in multiple associations
+
+class Task < ApplicationRecord
+  scope :active, -> { where(status: "active") }
+  scope :by_priority, -> { order(priority: :desc) }
+end
+
+# Use EXTENSION when:
+# - Query only makes sense in association context
+# - Need access to owner (proxy_association.owner)
+# - Doing mutations (mark_all_read!, etc.)
+# - Complex business logic specific to relationship
+
+class Project < ApplicationRecord
+  has_many :tasks do
+    # Makes sense only in project context
+    def critical_path
+      # Complex calculation involving project data
+      owner = proxy_association.owner
+      active.where("due_date <= ?", owner.deadline)
+            .order(priority: :desc)
+    end
+  end
+end
+
+# ============================================
+# Testing Extensions
+# ============================================
+
+# spec/models/project_spec.rb
+RSpec.describe Project do
+  describe "tasks extension" do
+    let(:project) { create(:project) }
+    let!(:active_task) { create(:task, project:, status: "active") }
+    let!(:completed_task) { create(:task, project:, status: "completed") }
+
+    describe "#active" do
+      it "returns only active tasks" do
+        expect(project.tasks.active).to contain_exactly(active_task)
+      end
+    end
+
+    describe "#completion_percentage" do
+      it "calculates correct percentage" do
+        expect(project.tasks.completion_percentage).to eq(50.0)
+      end
+
+      it "returns 0 for empty association" do
+        empty_project = create(:project)
+        expect(empty_project.tasks.completion_percentage).to eq(0)
+      end
+    end
+  end
+end

data/skills/activerecord/examples/associations/basic_associations.rb

@@ -0,0 +1,118 @@
+# Basic Association Examples
+# Demonstrates belongs_to, has_one, has_many relationships
+
+# ============================================
+# belongs_to - Child side (has foreign key)
+# ============================================
+
+class Book < ApplicationRecord
+  # Required by default (Rails 5+)
+  belongs_to :author
+
+  # Optional - allows NULL foreign key
+  belongs_to :publisher, optional: true
+
+  # Custom naming
+  belongs_to :category,
+             class_name: "Genre",
+             foreign_key: "genre_id",
+             inverse_of: :books  # Required with custom FK
+
+  # With counter cache on parent
+  belongs_to :series, counter_cache: true
+
+  # Touch parent on save
+  belongs_to :library, touch: true
+end
+
+# Migration for books
+# create_table :books do |t|
+#   t.belongs_to :author, null: false, foreign_key: true
+#   t.belongs_to :publisher, foreign_key: true
+#   t.belongs_to :genre, foreign_key: { to_table: :genres }
+#   t.belongs_to :series, foreign_key: true
+#   t.belongs_to :library, foreign_key: true
+#   t.string :title
+#   t.timestamps
+# end
+
+# ============================================
+# has_one - Parent side one-to-one
+# ============================================
+
+class Supplier < ApplicationRecord
+  has_one :account, dependent: :destroy
+
+  # Optional association
+  has_one :profile
+
+  # Custom naming
+  has_one :representative,
+          class_name: "Person",
+          foreign_key: "company_id",
+          inverse_of: :employer
+end
+
+# Migration - enforce true 1:1 at database level
+# create_table :accounts do |t|
+#   t.belongs_to :supplier, null: false, index: { unique: true }, foreign_key: true
+#   t.decimal :balance
+#   t.timestamps
+# end
+
+# ============================================
+# has_many - One-to-many
+# ============================================
+
+class Author < ApplicationRecord
+  has_many :books, dependent: :destroy
+
+  # Scoped association
+  has_many :published_books,
+           -> { where(published: true) },
+           class_name: "Book"
+
+  has_many :recent_books,
+           -> { order(created_at: :desc).limit(5) },
+           class_name: "Book"
+
+  # Through association
+  has_many :publishers, -> { distinct }, through: :books
+end
+
+# ============================================
+# Usage Examples
+# ============================================
+
+# Creating with associations
+author = Author.create!(name: "Jane Austen")
+book = author.books.create!(title: "Pride and Prejudice")
+
+# Building without saving
+draft = author.books.build(title: "Work in Progress")
+draft.save
+
+# Adding existing record
+existing_book = Book.find(123)
+author.books << existing_book  # Saves immediately!
+
+# Association queries
+author.books.count           # COUNT query
+author.books.size            # Uses counter_cache if present
+author.books.empty?          # Boolean check
+author.book_ids              # Array of IDs
+
+# Scoped queries on association
+author.books.where(published: true)
+author.books.order(created_at: :desc)
+author.published_books.first
+
+# has_one building
+supplier = Supplier.create!(name: "ACME Corp")
+supplier.create_account!(balance: 1000)
+# or
+supplier.build_account(balance: 500)
+supplier.save
+
+# has_one replacement
+supplier.account = Account.new(balance: 2000)  # Old account nullified/destroyed