better_model 1.0.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6ba3b1688c75e16f9499780eebd533c307cd8ba18f9c37a03597c8d62310fae7
-  data.tar.gz: '0835904e4ea513187668f8f9c36e3d9855096bc46a2150555fae900b320b764d'
+  metadata.gz: ec236d26e4c1e0a5a62e9932606a1baa28de1bcadf8b447f1da545fb35d029b6
+  data.tar.gz: 24e4aa004924ab09c6104cad770229041b8c8d24556ce5f2f2d190bf15071e90
 SHA512:
-  metadata.gz: d42074244a7e4af9321b68e9657f343ac4c087956856cfd0cbfe68e72adc1fce5200fc051cdfe1badd0e6bc753dfa3abcf0603113e3dede3cd7ce083b3ba932c
-  data.tar.gz: e5305841ab87d40047b6bc458bdac8a163a96d0d9e864ead0a0335ab84b53759a5da837cb6b95f1c2bdc3596fcd74dc7281d77d370a3db0aa9cc98f72c281708
+  metadata.gz: 77d291e54bcbbb179eabd842290530d0f42e03636981e93bfdeb6575d5d0e02960d359072c0b0db0144f35cdbea647d463bf7320037c557552f6fce8365a393e
+  data.tar.gz: bfe3bf61206cb343dce4d84b2ff643e719c09b93a623de77e127a00aadbce646d25bfcc2cd66ca3bd725b6af224a82eb7cff2e059f79f45c8e026d5d878c95d6

data/README.md

@@ -1,8 +1,8 @@
-# BetterModel
+# BetterModel 🚀
 
-BetterModel is a Rails engine gem (Rails 8.1+) that provides powerful extensions for ActiveRecord models, including declarative status management, permissions, archiving, sorting, filtering, and unified search capabilities.
+BetterModel is a Rails engine gem (Rails 8.1+) that provides powerful extensions for ActiveRecord models, including declarative status management, permissions, state machines, validations, archiving, change tracking, sorting, filtering, and unified search capabilities.
 
-## Installation
+## 📦 Installation
 
 Add this line to your application's Gemfile:
 
@@ -20,7 +20,7 @@ Or install it yourself as:
 $ gem install better_model
 ```
 
-## Quick Start
+## ⚡ Quick Start
 
 Simply include `BetterModel` in your model to get all features:
 
@@ -52,7 +52,52 @@ class Article < ApplicationRecord
     skip_archived_by_default true  # Hide archived records by default
   end
 
-  # 6. SEARCHABLE - Configure unified search interface
+  # 6. VALIDATABLE - Declarative validation system (opt-in)
+  validatable do
+    # Basic validations
+    validate :title, :content, presence: true
+
+    # Conditional validations
+    validate_if :is_published? do
+      validate :published_at, presence: true
+    end
+
+    # Cross-field validations
+    validate_order :starts_at, :before, :ends_at
+
+    # Business rules
+    validate_business_rule :valid_category
+
+    # Validation groups (multi-step forms)
+    validation_group :step1, [:title, :content]
+    validation_group :step2, [:published_at]
+  end
+
+  # 7. STATEABLE - Declarative state machine (opt-in)
+  stateable do
+    # Define states
+    state :draft, initial: true
+    state :published
+    state :archived
+
+    # Define transitions with guards and callbacks
+    transition :publish, from: :draft, to: :published do
+      guard { valid? }
+      guard if: :is_ready_for_publishing?  # Statusable integration
+      before { set_published_at }
+      after { notify_subscribers }
+    end
+
+    transition :archive, from: [:draft, :published], to: :archived
+  end
+
+  # 8. TRACEABLE - Audit trail with time-travel (opt-in)
+  traceable do
+    track :title, :content, :status, :published_at
+    versions_table :article_versions  # Optional: custom table
+  end
+
+  # 9. SEARCHABLE - Configure unified search interface
   searchable do
     per_page 25
     max_per_page 100
@@ -62,41 +107,66 @@ class Article < ApplicationRecord
 end
 ```
 
-Now you can use all the features:
+💡 **Now you can use all the features:**
 
 ```ruby
-# Check statuses
+# ✅ Check statuses
 article.is?(:draft)          # => true/false
 article.is_published?        # => true/false
 article.statuses             # => { draft: true, published: false, ... }
 
-# Check permissions
+# 🔐 Check permissions
 article.permit?(:edit)       # => true/false
 article.permit_delete?       # => true/false
 article.permissions          # => { edit: true, delete: true, ... }
 
-# Sort
+# ⬆️ Sort
 Article.sort_title_asc
 Article.sort_view_count_desc
 Article.sort_published_at_desc
 
-# Filter with predicates
+# 🔍 Filter with predicates
 Article.status_eq("published")
 Article.title_cont("Rails")
 Article.view_count_gteq(100)
 Article.published_at_present
 
-# Archive records
+# 🗄️ Archive records
 article.archive!(by: current_user, reason: "Outdated")
 article.archived?  # => true
 article.restore!
 
-# Query archived records
+# 📂 Query archived records
 Article.archived
 Article.not_archived
 Article.archived_recently(7.days)
 
-# Unified search with filters, sorting, and pagination
+# ✅ Validate with groups (multi-step forms)
+article.valid?(:step1)  # Validate only step1 fields
+article.valid?(:step2)  # Validate only step2 fields
+article.errors_for_group(:step1)  # Get errors for step1 only
+
+# 🔄 State machine transitions
+article.state            # => "draft"
+article.draft?           # => true
+article.can_publish?     # => true (checks guards)
+article.publish!         # Executes transition with guards & callbacks
+article.published?       # => true
+article.state_transitions  # History of all transitions
+article.transition_history # Formatted history array
+
+# ⏰ Time travel & rollback (Traceable)
+article.audit_trail              # Full change history
+article.as_of(3.days.ago)        # Reconstruct past state
+article.rollback_to(version)     # Restore to previous version
+article.changes_for(:status)     # Changes for specific field
+
+# 🔍 Query changes
+Article.changed_by(user.id)
+Article.changed_between(1.week.ago, Time.current)
+Article.status_changed_from("draft").to("published")
+
+# 🔎 Unified search with filters, sorting, and pagination
 Article.search(
   { status_eq: "published", view_count_gteq: 50 },
   orders: [:sort_published_at_desc],
@@ -104,7 +174,7 @@ Article.search(
 )
 ```
 
-### Including Individual Concerns (Advanced)
+### 🎯 Including Individual Concerns (Advanced)
 
 If you only need specific features, you can include individual concerns:
 
@@ -113,21 +183,42 @@ class Article < ApplicationRecord
   include BetterModel::Statusable    # Only status management
   include BetterModel::Permissible   # Only permissions
   include BetterModel::Archivable    # Only archiving
+  include BetterModel::Traceable     # Only audit trail & time-travel
   include BetterModel::Sortable      # Only sorting
   include BetterModel::Predicable    # Only filtering
+  include BetterModel::Validatable   # Only validations
+  include BetterModel::Stateable     # Only state machine
   include BetterModel::Searchable    # Only search (requires Predicable & Sortable)
 
   # Define your features...
 end
 ```
 
-## Requirements
+## 📋 Features Overview
+
+BetterModel provides nine powerful concerns that work seamlessly together:
+
+### Core Features
+
+- **✨ Statusable** - Declarative status management with lambda-based conditions
+- **🔐 Permissible** - State-based permission system
+- **🗄️ Archivable** - Soft delete with tracking (by user, reason)
+- **⏰ Traceable** 🆕 - Complete audit trail with time-travel and rollback
+- **⬆️ Sortable** - Type-aware sorting scopes
+- **🔍 Predicable** - Advanced filtering with rich predicate system
+- **🔎 Searchable** - Unified search interface (Predicable + Sortable)
+- **✅ Validatable** - Declarative validation DSL with conditional rules
+- **🔄 Stateable** 🆕 - Declarative state machines with guards & callbacks
+
+[See all features in detail →](#-features)
+
+## ⚙️ Requirements
 
 - **Ruby:** 3.0 or higher
 - **Rails:** 8.1 or higher
 - **ActiveRecord:** Included with Rails
 
-## Database Compatibility
+## 💾 Database Compatibility
 
 BetterModel works with all databases supported by ActiveRecord:
 
@@ -143,20 +234,20 @@ BetterModel works with all databases supported by ActiveRecord:
 - Array predicates: `overlaps`, `contains`, `contained_by`
 - JSONB predicates: `has_key`, `has_any_key`, `has_all_keys`, `jsonb_contains`
 
-## Features
+## 📚 Features
 
-BetterModel provides six powerful concerns that work together seamlessly:
+BetterModel provides eight powerful concerns that work together seamlessly:
 
 ### 📋 Statusable - Declarative Status Management
 
 Define derived statuses dynamically based on model attributes - no database columns needed!
 
-**Key Benefits:**
-- Declarative DSL with clear, readable conditions
-- Statuses calculated in real-time from model attributes
-- Reference other statuses in conditions
-- Automatic method generation (`is_draft?`, `is_published?`)
-- Thread-safe with immutable registry
+**🎯 Key Benefits:**
+- ✨ Declarative DSL with clear, readable conditions
+- ⚡ Statuses calculated in real-time from model attributes
+- 🔗 Reference other statuses in conditions
+- 🤖 Automatic method generation (`is_draft?`, `is_published?`)
+- 🔒 Thread-safe with immutable registry
 
 **[📖 Full Documentation →](docs/statusable.md)**
 
@@ -166,12 +257,12 @@ Define derived statuses dynamically based on model attributes - no database colu
 
 Define permissions dynamically based on model state and statuses - perfect for authorization logic!
 
-**Key Benefits:**
-- Declarative DSL following Statusable pattern
-- Permissions calculated from model state
-- Reference statuses in permission logic
-- Automatic method generation (`permit_edit?`, `permit_delete?`)
-- Thread-safe with immutable registry
+**🎯 Key Benefits:**
+- ✨ Declarative DSL following Statusable pattern
+- ⚡ Permissions calculated from model state
+- 🔗 Reference statuses in permission logic
+- 🤖 Automatic method generation (`permit_edit?`, `permit_delete?`)
+- 🔒 Thread-safe with immutable registry
 
 **[📖 Full Documentation →](docs/permissible.md)**
 
@@ -181,30 +272,87 @@ Define permissions dynamically based on model state and statuses - perfect for a
 
 Soft-delete records with archive tracking, audit trails, and restoration capabilities.
 
-**Key Benefits:**
-- Opt-in activation: only enabled when explicitly configured
-- Archive and restore methods with optional tracking
-- Status methods: `archived?` and `active?`
-- Semantic scopes: `archived`, `not_archived`, `archived_only`
-- Helper predicates: `archived_today`, `archived_this_week`, `archived_recently`
-- Optional default scope to hide archived records
-- Migration generator with flexible options
-- Thread-safe with immutable configuration
+**🎯 Key Benefits:**
+- 🎛️ Opt-in activation: only enabled when explicitly configured
+- 🔄 Archive and restore methods with optional tracking
+- ✅ Status methods: `archived?` and `active?`
+- 🔍 Semantic scopes: `archived`, `not_archived`, `archived_only`
+- 🛠️ Helper predicates: `archived_today`, `archived_this_week`, `archived_recently`
+- 👻 Optional default scope to hide archived records
+- 🚀 Migration generator with flexible options
+- 🔒 Thread-safe with immutable configuration
 
 **[📖 Full Documentation →](docs/archivable.md)**
 
 ---
 
+### ✅ Validatable - Declarative Validation System
+
+Define validations declaratively with support for conditional rules, cross-field validation, business rules, and validation groups.
+
+**🎯 Key Benefits:**
+- 🎛️ Opt-in activation: only enabled when explicitly configured
+- ✨ Declarative DSL for all validation types
+- 🔀 Conditional validations: `validate_if` / `validate_unless`
+- 🔗 Cross-field validations: `validate_order` for date/number comparisons
+- 💼 Business rules: delegate complex logic to custom methods
+- 📋 Validation groups: partial validation for multi-step forms
+- 🔒 Thread-safe with immutable configuration
+
+**[📖 Full Documentation →](docs/validatable.md)**
+
+---
+
+### 🔄 Stateable - Declarative State Machine
+
+Define state machines declaratively with transitions, guards, validations, and callbacks for robust workflow management.
+
+**🎯 Key Benefits:**
+- 🎛️ Opt-in activation: only enabled when explicitly configured
+- ✨ Declarative DSL for states and transitions
+- 🛡️ Guards: preconditions with lambda, methods, or Statusable predicates
+- ✅ Validations: custom validation logic per transition
+- 🔗 Callbacks: before/after/around hooks for each transition
+- 📜 State history tracking with customizable table names
+- 🤖 Dynamic methods: `pending?`, `confirm!`, `can_confirm?`
+- 🔗 Integration with Statusable for complex guard logic
+- 🔒 Thread-safe with immutable configuration
+
+**[📖 Full Documentation →](docs/stateable.md)**
+
+---
+
+### ⏰ Traceable - Audit Trail with Time-Travel
+
+Track all changes to your records with complete audit trail, time-travel capabilities, and rollback support.
+
+**🎯 Key Benefits:**
+- 🎛️ Opt-in activation: only enabled when explicitly configured
+- 📝 Automatic change tracking on create, update, and destroy
+- 👤 User attribution: track who made each change
+- 💬 Change reasons: optional context for changes
+- ⏰ Time-travel: reconstruct object state at any point in history
+- ↩️ Rollback support: restore records to previous versions
+- 🔍 Rich query API: find changes by user, time, or field transitions
+- 📊 Flexible table naming: per-model, shared, or custom tables
+- 🔗 Polymorphic association for efficient storage
+- 💾 Database adapter safety: PostgreSQL, MySQL, SQLite support
+- 🔒 Thread-safe dynamic class creation
+
+**[📖 Full Documentation →](docs/traceable.md)**
+
+---
+
 ### ⬆️ Sortable - Type-Aware Sorting Scopes
 
 Generate intelligent sorting scopes automatically with database-specific optimizations and NULL handling.
 
-**Key Benefits:**
-- Type-aware scope generation (string, numeric, datetime, boolean)
-- Case-insensitive sorting for strings
-- Database-specific NULLS FIRST/LAST support
-- Sort by multiple fields with chaining
-- Optimized queries with proper indexing support
+**🎯 Key Benefits:**
+- 🎯 Type-aware scope generation (string, numeric, datetime, boolean)
+- 🔤 Case-insensitive sorting for strings
+- 💾 Database-specific NULLS FIRST/LAST support
+- 🔗 Sort by multiple fields with chaining
+- ⚡ Optimized queries with proper indexing support
 
 **[📖 Full Documentation →](docs/sortable.md)**
 
@@ -214,13 +362,13 @@ Generate intelligent sorting scopes automatically with database-specific optimiz
 
 Generate comprehensive predicate scopes for filtering and searching with support for all data types.
 
-**Key Benefits:**
-- Complete coverage: string, numeric, datetime, boolean, null predicates
-- Type-safe predicates based on column type
-- Case-insensitive string matching
-- Range queries (between) for numerics and dates
-- PostgreSQL array and JSONB support
-- Chainable with standard ActiveRecord queries
+**🎯 Key Benefits:**
+- ✅ Complete coverage: string, numeric, datetime, boolean, null predicates
+- 🔒 Type-safe predicates based on column type
+- 🔤 Case-insensitive string matching
+- 📊 Range queries (between) for numerics and dates
+- 🐘 PostgreSQL array and JSONB support
+- 🔗 Chainable with standard ActiveRecord queries
 
 **[📖 Full Documentation →](docs/predicable.md)**
 
@@ -230,57 +378,230 @@ Generate comprehensive predicate scopes for filtering and searching with support
 
 Orchestrate Predicable and Sortable into a powerful, secure search interface with pagination and security.
 
-**Key Benefits:**
-- Unified API: single `search()` method for all operations
-- OR conditions for complex logic
-- Built-in pagination with DoS protection (max_per_page)
-- Security enforcement with required predicates
-- Default ordering configuration
-- Strong parameters integration
-- Type-safe validation of all parameters
+**🎯 Key Benefits:**
+- 🎯 Unified API: single `search()` method for all operations
+- 🔀 OR conditions for complex logic
+- 📄 Built-in pagination with DoS protection (max_per_page)
+- 🔒 Security enforcement with required predicates
+- ⚙️ Default ordering configuration
+- 💪 Strong parameters integration
+- ✅ Type-safe validation of all parameters
 
 **[📖 Full Documentation →](docs/searchable.md)**
 
 ---
 
-## Version & Changelog
+### 📜 Traceable - Audit Trail & Change Tracking
+
+Track all changes to your records with comprehensive audit trail functionality, time-travel queries, and rollback capabilities.
+
+**🎯 Key Benefits:**
+- 🎛️ Opt-in activation: only enabled when explicitly configured
+- 🤖 Automatic change tracking on create/update/destroy
+- ⏰ Time-travel: reconstruct record state at any point in time
+- ↩️ Rollback: restore to previous versions
+- 📝 Audit trail with who/why tracking
+- 🔍 Query changes by user, date range, or field transitions
+- 🗂️ Flexible table naming: per-model tables (default), shared table, or custom names
+
+**[📖 Full Documentation →](docs/traceable.md)**
+
+#### 🚀 Quick Setup
+
+**1️⃣ Step 1: Create the versions table**
+
+By default, each model gets its own versions table (`{model}_versions`):
+
+```bash
+# Creates migration for article_versions table
+rails g better_model:traceable Article --create-table
+rails db:migrate
+```
+
+Or use a custom table name:
+
+```bash
+# Creates migration for custom table name
+rails g better_model:traceable Article --create-table --table-name=audit_log
+rails db:migrate
+```
+
+**2️⃣ Step 2: Enable in your model**
+
+```ruby
+class Article < ApplicationRecord
+  include BetterModel
+
+  # Activate traceable (opt-in)
+  traceable do
+    track :status, :title, :published_at  # Fields to track
+    # versions_table 'audit_log'  # Optional: custom table (default: article_versions)
+  end
+end
+```
+
+**💡 Usage:**
+
+```ruby
+# 🤖 Automatic tracking on changes
+article.update!(status: "published", updated_by_id: user.id, updated_reason: "Approved")
+
+# 🔍 Query version history
+article.versions                              # All versions (ordered desc)
+article.changes_for(:status)                  # Changes for specific field
+article.audit_trail                           # Full formatted history
+
+# ⏰ Time-travel: reconstruct state at specific time
+past_article = article.as_of(3.days.ago)
+past_article.status                           # => "draft" (what it was 3 days ago)
+
+# ↩️ Rollback to previous version
+version = article.versions.where(event: "updated").first
+article.rollback_to(version, updated_by_id: user.id, updated_reason: "Mistake")
+
+# 📊 Class-level queries
+Article.changed_by(user.id)                   # Records changed by user
+Article.changed_between(1.week.ago, Time.current)  # Changes in period
+Article.status_changed_from("draft").to("published")  # Specific transitions (PostgreSQL)
+
+# 📦 Integration with as_json
+article.as_json(include_audit_trail: true)    # Include full history in JSON
+```
+
+**💾 Database Schema:**
+
+By default, each model gets its own versions table (e.g., `article_versions` for Article model).
+You can also use a shared table across multiple models or a custom table name.
+
+| Column | Type | Description |
+|--------|------|-------------|
+| `item_type` | string | Polymorphic model name |
+| `item_id` | integer | Polymorphic record ID |
+| `event` | string | Event type: created/updated/destroyed |
+| `object_changes` | json | Before/after values for tracked fields |
+| `updated_by_id` | integer | Optional: user who made the change |
+| `updated_reason` | string | Optional: reason for the change |
+| `created_at` | datetime | When the change occurred |
+
+**🗂️ Table Naming Options:**
+
+```ruby
+# 1️⃣ Option 1: Per-model table (default)
+class Article < ApplicationRecord
+  traceable do
+    track :status
+    # Uses article_versions table automatically
+  end
+end
+
+# 2️⃣ Option 2: Custom table name
+class Article < ApplicationRecord
+  traceable do
+    track :status
+    versions_table 'audit_log'  # Uses audit_log table
+  end
+end
+
+# 3️⃣ Option 3: Shared table across models
+class Article < ApplicationRecord
+  traceable do
+    track :status
+    versions_table 'versions'  # Shared table
+  end
+end
+
+class User < ApplicationRecord
+  traceable do
+    track :email
+    versions_table 'versions'  # Same shared table
+  end
+end
+```
+
+**📝 Optional Tracking:**
+
+To track who made changes and why, simply set attributes before saving:
+
+```ruby
+article.updated_by_id = current_user.id
+article.updated_reason = "Fixed typo"
+article.update!(title: "Corrected Title")
+
+# The version will automatically include updated_by_id and updated_reason
+```
+
+---
+
+## 📌 Version & Changelog
 
 **Current Version:** 1.0.0
 
 See [CHANGELOG.md](CHANGELOG.md) for version history and release notes.
 
-## Support & Community
+## 💬 Support & Community
+
+- 🐛 **Issues & Bugs:** [GitHub Issues](https://github.com/alessiobussolari/better_model/issues)
+- 💻 **Source Code:** [GitHub Repository](https://github.com/alessiobussolari/better_model)
+- 📖 **Documentation:** This README and detailed docs in `docs/` directory
+
+## 📚 Complete Documentation
+
+### 📖 Feature Guides
+
+Detailed documentation for each BetterModel concern:
+
+- [**Statusable**](docs/statusable.md) - Status management with derived conditions
+- [**Permissible**](docs/permissible.md) - Permission system based on state
+- [**Archivable**](docs/archivable.md) - Soft delete with comprehensive tracking
+- [**Traceable**](docs/traceable.md) 🆕 - Audit trail, time-travel, and rollback
+- [**Sortable**](docs/sortable.md) - Type-aware sorting system
+- [**Predicable**](docs/predicable.md) - Advanced filtering and predicates
+- [**Searchable**](docs/searchable.md) - Unified search interface
+- [**Validatable**](docs/validatable.md) - Declarative validation system
+- [**Stateable**](docs/stateable.md) 🆕 - State machine with transitions
 
-- **Issues & Bugs:** [GitHub Issues](https://github.com/alessiobussolari/better_model/issues)
-- **Source Code:** [GitHub Repository](https://github.com/alessiobussolari/better_model)
-- **Documentation:** This README and detailed docs in `docs/` directory
+### 🎓 Advanced Guides
 
-## Contributing
+Learn how to master BetterModel in production:
+
+- [**Integration Guide**](docs/integration_guide.md) 🆕 - Combining multiple concerns effectively
+- [**Performance Guide**](docs/performance_guide.md) 🆕 - Optimization strategies and indexing
+- [**Migration Guide**](docs/migration_guide.md) 🆕 - Adding BetterModel to existing apps
+
+### 💡 Quick Links
+
+- [Installation](#-installation)
+- [Quick Start](#-quick-start)
+- [Features Overview](#-features-overview)
+- [Requirements](#%EF%B8%8F-requirements)
+- [Contributing](#-contributing)
+
+## 🤝 Contributing
 
 We welcome contributions! Here's how you can help:
 
-### Reporting Bugs
+### 🐛 Reporting Bugs
 
-1. Check if the issue already exists in [GitHub Issues](https://github.com/alessiobussolari/better_model/issues)
-2. Create a new issue with:
+1. ✅ Check if the issue already exists in [GitHub Issues](https://github.com/alessiobussolari/better_model/issues)
+2. 📝 Create a new issue with:
    - Clear description of the problem
    - Steps to reproduce
    - Expected vs actual behavior
    - Ruby/Rails versions
    - Database adapter
 
-### Submitting Pull Requests
+### 🚀 Submitting Pull Requests
 
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Make your changes with tests
-4. Run the test suite (`bundle exec rake test`)
-5. Ensure RuboCop passes (`bundle exec rubocop`)
-6. Commit your changes (`git commit -m 'Add amazing feature'`)
-7. Push to the branch (`git push origin feature/amazing-feature`)
-8. Open a Pull Request
+1. 🍴 Fork the repository
+2. 🌿 Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. ✍️ Make your changes with tests
+4. 🧪 Run the test suite (`bundle exec rake test`)
+5. 💅 Ensure RuboCop passes (`bundle exec rubocop`)
+6. 💾 Commit your changes (`git commit -m 'Add amazing feature'`)
+7. 📤 Push to the branch (`git push origin feature/amazing-feature`)
+8. 🎉 Open a Pull Request
 
-### Development Setup
+### 🔧 Development Setup
 
 ```bash
 # Clone your fork
@@ -300,13 +621,34 @@ bundle exec rake test  # Coverage report in coverage/index.html
 bundle exec rubocop
 ```
 
-### Code Guidelines
+### 📊 Test Coverage Notes
+
+The test suite runs on **SQLite** for performance and portability. Current coverage: **91.45%** (1272 / 1391 lines).
+
+**Database-Specific Features Not Covered:**
+- **Predicable**: PostgreSQL array predicates (`_overlaps`, `_contains`, `_contained_by`) and JSONB predicates (`_has_key`, `_has_any_key`, `_has_all_keys`, `_jsonb_contains`) - lines 278-376 in `lib/better_model/predicable.rb`
+- **Traceable**: PostgreSQL JSONB queries and MySQL JSON_EXTRACT queries for field-specific change tracking - lines 454-489 in `lib/better_model/traceable.rb`
+- **Sortable**: MySQL NULLS emulation with CASE statements - lines 198-203 in `lib/better_model/sortable.rb`
+
+These features are fully implemented with proper SQL sanitization but require manual testing on PostgreSQL/MySQL:
+
+```bash
+# Test on PostgreSQL
+RAILS_ENV=test DATABASE_URL=postgresql://user:pass@localhost/better_model_test rails console
+
+# Test on MySQL
+RAILS_ENV=test DATABASE_URL=mysql2://user:pass@localhost/better_model_test rails console
+```
+
+All code has inline comments marking database-specific sections for maintainability.
+
+### 📐 Code Guidelines
 
-- Follow the existing code style (enforced by RuboCop Omakase)
-- Write tests for new features
-- Update documentation (README) for user-facing changes
-- Keep pull requests focused (one feature/fix per PR)
+- ✨ Follow the existing code style (enforced by RuboCop Omakase)
+- 🧪 Write tests for new features
+- 📝 Update documentation (README) for user-facing changes
+- 🎯 Keep pull requests focused (one feature/fix per PR)
 
-## License
+## 📝 License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).